core

Documentation

Overview

Package core implements core functions wrapped up in a tasty library package. This package is intended to be imported and used elsewhere, but the API should NOT yet be considered stable. Use at own risk!

Index

• Variables
• func BKTimestamp(t time.Time) string
• type APIClient
• type Client
  • func (c *Client) AcquireJob(ctx context.Context, jobID string) (*api.Job, error)
  • func (c *Client) Connect(ctx context.Context) error
  • func (c *Client) Disconnect(ctx context.Context) error
  • func (c *Client) FinishJob(ctx context.Context, job *api.Job, finishedAt time.Time, exit ProcessExit, ...) error
  • func (c *Client) Register(ctx context.Context, req api.AgentRegisterRequest) (*api.AgentRegisterResponse, error)
  • func (c *Client) StartJob(ctx context.Context, job *api.Job, startedAt time.Time) error
  • func (c *Client) UploadChunk(ctx context.Context, jobID string, chunk *api.Chunk) error
• type Controller
  • func NewController(ctx context.Context, regToken, agentName string, tags []string, ...) (*Controller, error)
  • func (a *Controller) AcquireJob(ctx context.Context, jobID string) (*api.Job, error)
  • func (a *Controller) Close(ctx context.Context) error
  • func (a *Controller) NewJobController(job *api.Job) *JobController
• type ControllerOption
  • func WithAllowHTTP2(allow bool) ControllerOption
  • func WithDebugHTTP(debug bool) ControllerOption
  • func WithEndpoint(endpoint string) ControllerOption
  • func WithLogger(l logger.Logger) ControllerOption
  • func WithPriority(priority string) ControllerOption
  • func WithRetrySleepFunc(f func(time.Duration)) ControllerOption
  • func WithScriptEvalEnabled(enabled bool) ControllerOption
  • func WithUserAgent(userAgent string) ControllerOption
• type JobController
  • func NewJobController(client *Client, job *api.Job) *JobController
  • func (c *JobController) Finish(ctx context.Context, exit ProcessExit) error
  • func (c *JobController) Start(ctx context.Context) error
  • func (c *JobController) WriteLog(ctx context.Context, log string) error
• type ProcessExit

Variables

var ErrJobAcquisitionRejected = errors.New("job acquisition rejected")

ErrJobAcquisitionRejected is a sentinel error used when acquisition fails because the job is already acquired/started/finished/cancelled.

Functions

func BKTimestamp

func BKTimestamp(t time.Time) string

BKTimestamp formats a time as a Buildkite timestamp code.

Types

type APIClient

type APIClient interface {
	AcquireJob(context.Context, string, ...api.Header) (*api.Job, *api.Response, error)
	Connect(context.Context) (*api.Response, error)
	Disconnect(context.Context) (*api.Response, error)
	FinishJob(context.Context, *api.Job) (*api.Response, error)
	Register(context.Context, *api.AgentRegisterRequest) (*api.AgentRegisterResponse, *api.Response, error)
	StartJob(context.Context, *api.Job) (*api.Response, error)
	UploadChunk(context.Context, string, *api.Chunk) (*api.Response, error)
}

APIClient defines the subset of client methods needed by core.

type Client

type Client struct {
	// APIClient is the API client that Client drives.
	APIClient APIClient

	// Logger is used for logging throughout the client.
	Logger logger.Logger

	// RetrySleepFunc overrides the sleep function within roko retries.
	// This is primarily useful for unit tests. It's recommended to leave as nil.
	RetrySleepFunc func(time.Duration)
}

Client is a driver for APIClient that adds retry loops and some error handling logic.

func (*Client) AcquireJob

func (c *Client) AcquireJob(ctx context.Context, jobID string) (*api.Job, error)

AcquireJob acquires a specific job from Buildkite. It doesn't interpret or run the job - the caller is responsible for that. It contains a builtin timeout of 270 seconds and makes up to 10 attempts.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

Connects the agent to the Buildkite Agent API, retrying up to 10 times with 5 seconds delay if it fails.

func (*Client) Disconnect

func (c *Client) Disconnect(ctx context.Context) error

Disconnect notifies the Buildkite API that this agent worker/session is permanently disconnecting. Don't spend long retrying, because we want to disconnect as fast as possible.

func (*Client) FinishJob

func (c *Client) FinishJob(ctx context.Context, job *api.Job, finishedAt time.Time, exit ProcessExit, failedChunkCount int) error

FinishJob finishes the job in the Buildkite Agent API. If the FinishJob call cannot return successfully, this will retry for a long time.

func (*Client) Register

func (c *Client) Register(ctx context.Context, req api.AgentRegisterRequest) (*api.AgentRegisterResponse, error)

Register takes an APIClient and registers it with the Buildkite API and populates the result of the register call. It retries up to 30 times. Options from opts are *not* set on AgentRegisterRequest, but some fields are overridden with specific values.

func (*Client) StartJob

func (c *Client) StartJob(ctx context.Context, job *api.Job, startedAt time.Time) error

StartJob starts the job in the Buildkite Agent API. We'll retry on connection-related issues, but if a connection succeeds and we get an client error response back from Buildkite, we won't bother retrying. For example, a "no such host" will retry, but an HTTP response from Buildkite that isn't retryable won't.

func (*Client) UploadChunk

func (c *Client) UploadChunk(ctx context.Context, jobID string, chunk *api.Chunk) error

UploadChunk uploads a log chunk. If a valid chunk cannot be uploaded, it will retry for a long time.

type Controller

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

Controller is a client for the Buildkite Agent API. It is useful for implementing completely custom job behaviour within process (instead of having to execute hooks).

func NewController

func NewController(ctx context.Context, regToken, agentName string, tags []string, opts ...ControllerOption) (*Controller, error)

NewController creates and registers a new agent with Buildkite. Currently, only Acquire Job is supported. ctx is only used for agent registration and connection.

func (*Controller) AcquireJob

func (a *Controller) AcquireJob(ctx context.Context, jobID string) (*api.Job, error)

AcquireJob acquires a specific job from Buildkite. It doesn't run the job - the caller is responsible for that.

func (*Controller) Close

func (a *Controller) Close(ctx context.Context) error

Close disconnects the agent.

func (*Controller) NewJobController

func (a *Controller) NewJobController(job *api.Job) *JobController

NewJobController creates a new job controller for a job.

type ControllerOption

type ControllerOption func(*controllerConfig)

ControllerOption is a functional option for setting optional behaviour.

func WithAllowHTTP2

func WithAllowHTTP2(allow bool) ControllerOption

WithAllowHTTP can be used to change whether HTTP/2 is allowed. Only applies to agent creation. Defaults to true.

func WithDebugHTTP

func WithDebugHTTP(debug bool) ControllerOption

WithDebugHTTP can be used to enable HTTP debug logs. Only applies to agent creation. Defaults to false.

func WithEndpoint

func WithEndpoint(endpoint string) ControllerOption

WithEndpoint allows overriding the API endpoint (base URL). Defaults to "https://agent.buildkite.com/v3".

func WithLogger

func WithLogger(l logger.Logger) ControllerOption

WithLogger enables logging through a particular logger. Defaults to logger.Discard.

func WithPriority

func WithPriority(priority string) ControllerOption

WithPriority sets the agent priority value. Defaults to the empty string.

func WithRetrySleepFunc

func WithRetrySleepFunc(f func(time.Duration)) ControllerOption

WithRetrySleepFunc is used to override the inter-retry sleep in roko. This is mainly useful for unit tests. Defaults to nil (default sleep).

func WithScriptEvalEnabled

func WithScriptEvalEnabled(enabled bool) ControllerOption

WithScriptEvalEnabled sets the ScriptEvalEnabled registration parameter. Defaults to true.

func WithUserAgent

func WithUserAgent(userAgent string) ControllerOption

WithUserAgent allows overriding the user agent. Defaults to the value retuned from version.UserAgent.

type JobController

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

JobController provides simple functionality to a job runner - the ability to write job logs and exit with a status code.

func NewJobController

func NewJobController(client *Client, job *api.Job) *JobController

NewJobController creates a new job controller for a job.

func (*JobController) Finish

func (c *JobController) Finish(ctx context.Context, exit ProcessExit) error

Finish marks the job as finished in Buildkite.

func (*JobController) Start

func (c *JobController) Start(ctx context.Context) error

Start marks a job as started in Buildkite. If an error is returned, the job should not proceed.

func (*JobController) WriteLog

func (c *JobController) WriteLog(ctx context.Context, log string) error

WriteLog writes some log content for this job back to Buildkite. Unlike the main agent, this immediately uploads the content without any buffering, does not tee the log to a local file, nor does it insert timestamp codes. However, it uses the same retry loop as the agent, which can attempt to upload logs for a very long time.

type ProcessExit

type ProcessExit struct {
	Status       int
	Signal       string
	SignalReason string
}

ProcessExit describes how a process exited: if it was signaled, what its exit code was