jobapi

Documentation

Overview

jobapi provides an API with which to interact with and mutate the currently executing job Pronunciation: /ˈdʒɑbapi/ /joh-bah-pee/

Index

• func DefaultSocketPath() (path, token string, err error)
• func NewSocketPath(base string) (string, error)
• type Client
  • func NewClient(ctx context.Context, sock, token string) (*Client, error)
  • func NewDefaultClient(ctx context.Context) (*Client, error)
  • func (c *Client) EnvDelete(ctx context.Context, del []string) (deleted []string, err error)
  • func (c *Client) EnvGet(ctx context.Context) (map[string]string, error)
  • func (c *Client) EnvUpdate(ctx context.Context, req *EnvUpdateRequest) (*EnvUpdateResponse, error)
  • func (c *Client) RedactionCreate(ctx context.Context, text string) (string, error)
• type EnvDeleteRequest
• type EnvDeleteResponse
  • func (e EnvDeleteResponse) Normalize()
• type EnvGetResponse
• type EnvUpdateRequest
• type EnvUpdateRequestPayload
• type EnvUpdateResponse
  • func (e EnvUpdateResponse) Normalize()
• type ErrorResponse
• type RedactionCreateRequest
• type RedactionCreateResponse
• type Server
  • func NewServer(logger shell.Logger, socketPath string, environ *env.Environment, ...) (server *Server, token string, err error)
  • func (s *Server) Start() error
  • func (s *Server) Stop() error
• type ServerOpts
  • func WithDebug() ServerOpts

Functions

func DefaultSocketPath

func DefaultSocketPath() (path, token string, err error)

DefaultSocketPath returns the socket path and access token, if available.

func NewSocketPath

func NewSocketPath(base string) (string, error)

NewSocketPath generates a path to a socket file (without actually creating the file itself) that can be used with the job api.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client connects to the Job API.

func NewClient

func NewClient(ctx context.Context, sock, token string) (*Client, error)

NewClient creates a new Job API Client.

func NewDefaultClient

func NewDefaultClient(ctx context.Context) (*Client, error)

NewDefaultClient returns a new Job API Client with the default socket path and token.

func (*Client) EnvDelete

func (c *Client) EnvDelete(ctx context.Context, del []string) (deleted []string, err error)

EnvDelete deletes environment variables within the job executor.

func (*Client) EnvGet

func (c *Client) EnvGet(ctx context.Context) (map[string]string, error)

EnvGet gets the current environment variables from within the job executor.

func (*Client) EnvUpdate

func (c *Client) EnvUpdate(ctx context.Context, req *EnvUpdateRequest) (*EnvUpdateResponse, error)

EnvUpdate updates environment variables within the job executor.

func (*Client) RedactionCreate

func (c *Client) RedactionCreate(ctx context.Context, text string) (string, error)

RedactionCreate creates a redaction in the job executor.

type EnvDeleteRequest

type EnvDeleteRequest struct {
	Keys []string `json:"keys"`
}

EnvDeleteRequest is the request body for the DELETE /env endpoint

type EnvDeleteResponse

type EnvDeleteResponse struct {
	Deleted []string `json:"deleted"`
}

EnvDeleteResponse is the response body for the DELETE /env endpoint

func (EnvDeleteResponse) Normalize

func (e EnvDeleteResponse) Normalize()

type EnvGetResponse

type EnvGetResponse struct {
	Env map[string]string `json:"env"` // Different to EnvUpdateRequest because we don't want to send nulls
}

EnvGetResponse is the response body for the GET /env endpoint

type EnvUpdateRequest

type EnvUpdateRequest struct {
	Env map[string]string `json:"env"`
}

EnvUpdateRequest is the request body for the PATCH /env endpoint

type EnvUpdateRequestPayload

type EnvUpdateRequestPayload struct {
	Env map[string]*string `json:"env"`
}

EnvUpdateRequestPayload is the request body that the PATCH /env endpoint unmarshalls requests into

type EnvUpdateResponse

type EnvUpdateResponse struct {
	Added   []string `json:"added"`
	Updated []string `json:"updated"`
}

EnvUpdateResponse is the response body for the PATCH /env endpoint

func (EnvUpdateResponse) Normalize

func (e EnvUpdateResponse) Normalize()

type ErrorResponse

type ErrorResponse = socket.ErrorResponse

ErrorResponse is the response body for any errors that occur.

type RedactionCreateRequest

type RedactionCreateRequest struct {
	Redact string `json:"redact"`
}

RedactionCreateRequest is the request body for the POST /redactions endpoint

type RedactionCreateResponse

type RedactionCreateResponse struct {
	Redacted string `json:"redacted"`
}

RedactionCreateResponse is the response body for the POST /redactions endpoint

type Server

type Server struct {
	// SocketPath is the path to the socket that the server is (or will be) listening on
	SocketPath string
	Logger     shell.Logger
	// contains filtered or unexported fields
}

Server is a Job API server. It provides an HTTP API with which to interact with the job currently running in the buildkite agent and allows jobs to introspect and mutate their own state

func NewServer

func NewServer(
	logger shell.Logger,
	socketPath string,
	environ *env.Environment,
	redactors *replacer.Mux,
	opts ...ServerOpts,
) (server *Server, token string, err error)

NewServer creates a new Job API server socketPath is the path to the socket on which the server will listen environ is the environment which the server will mutate and inspect as part of its operation

func (*Server) Start

func (s *Server) Start() error

Start starts the server in a goroutine, returning an error if the server can't be started

func (*Server) Stop

func (s *Server) Stop() error

Stop gracefully shuts the server down, blocking until all requests have been served or the grace period has expired It returns an error if the server has not been started

type ServerOpts

type ServerOpts func(*Server)

ServerOpts provides a way to configure a Server

func WithDebug

func WithDebug() ServerOpts