Documentation
¶
Overview ¶
jobapi provides an API with which to interact with and mutate the currently executing job Pronunciation: /ˈdʒɑbapi/ /joh-bah-pee/
Index ¶
- Constants
- Variables
- func DefaultSocketPath() (path, token string, err error)
- func NewSocketPath(base string) (string, error)
- type Client
- func (c *Client) DeclarePromiseFailure(ctx context.Context, exitStatus int, reason string) (*PromiseFailureResponse, 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)
- func (c *Client) SetWorkdir(ctx context.Context, dir string) (string, error)
- type EnvDeleteRequest
- type EnvDeleteResponse
- type EnvGetResponse
- type EnvUpdateRequest
- type EnvUpdateRequestPayload
- type EnvUpdateResponse
- type ErrorResponse
- type PromiseFailureDeclarer
- type PromiseFailureRequest
- type PromiseFailureResponse
- type RedactionCreateRequest
- type RedactionCreateResponse
- type Server
- type ServerOpts
- type WorkdirSetRequest
- type WorkdirSetResponse
Constants ¶
const ( // PromiseFailureDeclared means this call declared the exit status to the // Buildkite API. PromiseFailureDeclared = "declared" // PromiseFailureDebounced means an earlier call already declared this exit // status, so this call shared that result without calling the Buildkite API. PromiseFailureDebounced = "debounced" )
Promise failure outcomes, reported in PromiseFailureResponse.Outcome.
Variables ¶
var ( ErrJobAPIUnavailable = errors.New("job API is unavailable on this machine") )
Functions ¶
func DefaultSocketPath ¶
DefaultSocketPath returns the socket path and access token, if available.
func NewSocketPath ¶
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 NewDefaultClient ¶
NewDefaultClient returns a new Job API Client with the default socket path and token.
func (*Client) DeclarePromiseFailure ¶
func (c *Client) DeclarePromiseFailure(ctx context.Context, exitStatus int, reason string) (*PromiseFailureResponse, error)
DeclarePromiseFailure asks the Job API to declare a promised failure with the given exit status and reason to the Buildkite API, blocking until it completes. The server debounces repeated and concurrent calls for the same exit status: concurrent callers share one in-flight call, and once it succeeds later calls return from the cache. If the Job API handles the request, the returned response describes whether the Buildkite API accepted or rejected the declaration. Errors are reserved for Job API transport/request failures.
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 ¶
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 ¶
EnvUpdateRequest is the request body for the PATCH /env endpoint
type EnvUpdateRequestPayload ¶
EnvUpdateRequestPayload is the request body that the PATCH /env endpoint unmarshalls requests into
type EnvUpdateResponse ¶
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 PromiseFailureDeclarer ¶
type PromiseFailureDeclarer func(ctx context.Context, exitStatus int, reason string) (statusCode int, err error)
PromiseFailureDeclarer declares a promised failure for the current job to the Buildkite API. It returns the status code of the most recent API response (0 if none was received, e.g. a network error after exhausting retries) and an error describing any failure. A nil error means the declaration was accepted.
type PromiseFailureRequest ¶
type PromiseFailureRequest struct {
ExitStatus int `json:"exit_status"`
Reason string `json:"reason,omitempty"`
}
PromiseFailureRequest is the request body for the POST /promise-failure endpoint
type PromiseFailureResponse ¶
type PromiseFailureResponse struct {
// Outcome is PromiseFailureDeclared or PromiseFailureDebounced.
Outcome string `json:"outcome"`
// Accepted reports whether the Buildkite API accepted the promised failure.
Accepted bool `json:"accepted"`
// UpstreamStatus is the Buildkite API status, when one was received.
// Network errors that never received a response leave this as 0.
UpstreamStatus int `json:"upstream_status,omitempty"`
// Error is the Buildkite API declaration error, if Accepted is false.
Error string `json:"error,omitempty"`
}
PromiseFailureResponse is the response body for the POST /promise-failure endpoint
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 ¶
Start starts the server in a goroutine, returning an error if the server can't be started
func (*Server) Stop ¶
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
func (*Server) TakePendingWorkdir ¶
TakePendingWorkdir returns the working directory requested by a hook via the /workdir endpoint (if any) and clears the pending signal. The second return value reports whether a directory was pending. The applied directory persists in the executor's shell working directory; this only consumes the signal.
type ServerOpts ¶
type ServerOpts func(*Server)
ServerOpts provides a way to configure a Server
func WithDebug ¶
func WithDebug() ServerOpts
func WithPromiseFailureDeclarer ¶
func WithPromiseFailureDeclarer(d PromiseFailureDeclarer) ServerOpts
WithPromiseFailureDeclarer sets the function the /promise-failure endpoint uses to declare promised failures to the Buildkite API. Debouncing means it's called at most once per successfully-declared exit status. If unset (e.g. in tests), the endpoint returns an error.
type WorkdirSetRequest ¶
type WorkdirSetRequest struct {
Workdir string `json:"workdir"`
}
WorkdirSetRequest is the request body for the PUT /workdir endpoint
type WorkdirSetResponse ¶
type WorkdirSetResponse struct {
Workdir string `json:"workdir"`
}
WorkdirSetResponse echoes the absolute working directory.
Source Files