api

package
v2.0.0-...-97c83bf Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2025 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsPermanentError

func IsPermanentError(err error) bool

IsPermanentError reports whether err is a non-nil Permanent AgentError.

func NewAuthedTransportWithBearer

func NewAuthedTransportWithBearer(inner http.RoundTripper, bearer string) http.RoundTripper

func NewAuthedTransportWithToken

func NewAuthedTransportWithToken(inner http.RoundTripper, token string) http.RoundTripper

func NewLogger

func NewLogger(inner http.RoundTripper) http.RoundTripper

Types

type AgentClient

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

AgentClient is a client for Agent API methods for retrieving jobs.

func NewAgentClient

func NewAgentClient(token, endpoint, clusterID, queue string, agentQueryRules []string, opts ...AgentClientOption) (*AgentClient, error)

func (*AgentClient) GetJobState

func (c *AgentClient) GetJobState(ctx context.Context, id string) (result *AgentJobState, retryAfter time.Duration, err error)

GetJobState gets the state of a specific job.

func (*AgentClient) GetJobToRun

func (c *AgentClient) GetJobToRun(ctx context.Context, id string) (result *AgentJob, retryAfter time.Duration, err error)

GetJobToRun gets info about a specific job needed to run it.

func (*AgentClient) GetScheduledJobs

func (c *AgentClient) GetScheduledJobs(ctx context.Context, afterCursor string, limit int) (result *AgentScheduledJobs, retryAfter time.Duration, err error)

GetScheduledJobs gets a page of jobs that could be run.

func (*AgentClient) ReserveJobs

func (c *AgentClient) ReserveJobs(ctx context.Context, ids []string) (result *BatchReserveJobsResult, retryAfter time.Duration, err error)

ReserveJobs reserves a batch of jobs.

type AgentClientOption

type AgentClientOption func(*AgentClient)

func WithReservation

func WithReservation(enable bool) AgentClientOption

type AgentError

type AgentError struct {
	Message string `json:"message"`

	Status     string `json:"-"`
	StatusCode int    `json:"-"`
}

AgentError is the JSON object of the response body returned when the HTTP status code is not success. It doubles as a Go error.

func (AgentError) Error

func (e AgentError) Error() string

func (AgentError) Permanent

func (e AgentError) Permanent() bool

Permanent reports if the error is not transient (i.e. a 4xx status code that isn't 429).

type AgentJob

type AgentJob struct {
	ID      string            `json:"id"`
	Command string            `json:"command"`
	Env     map[string]string `json:"env"`
}

AgentJob is enough info to run a job (includes command and env).

type AgentJobState

type AgentJobState struct {
	ID    string   `json:"id"`
	State JobState `json:"state"`
}

AgentJobState describes the current state of a job.

type AgentScheduledJob

type AgentScheduledJob struct {
	ID              string   `json:"id"`
	Priority        int      `json:"priority"`
	AgentQueryRules []string `json:"agent_query_rules"`

	// added by GetScheduledJobs to track end-to-end latency
	QueriedAt time.Time `json:"-"`
}

AgentScheduledJob is enough job information to prioritise and decide on sending a job through the controller's pipeline to run. It doesn't have enough info to actually run the job.

type AgentScheduledJobs

type AgentScheduledJobs struct {
	Jobs         []*AgentScheduledJob `json:"jobs"`
	ClusterQueue struct {
		ID             string `json:"id"`
		DispatchPaused bool   `json:"dispatch_paused"`
	} `json:"cluster_queue"`
	PageInfo struct {
		EndCursor   string `json:"end_cursor"`
		HasNextPage bool   `json:"has_next_page"`
	} `json:"page_info"`
}

AgentScheduledJobs is the response object from the scheduled_jobs path.

type AgentTokenClient

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

func NewAgentTokenClient

func NewAgentTokenClient(token, endpoint string) (*AgentTokenClient, error)

This is a special agent client: it can only be used to query the GET /token API. Meaning for this client to function, there isn't a need for a cluster id nor queue id.

func (*AgentTokenClient) GetTokenIdentity

func (c *AgentTokenClient) GetTokenIdentity(ctx context.Context) (result *AgentTokenIdentity, retryAfter time.Duration, err error)

GetJobState gets the state of a specific job.

type AgentTokenIdentity

type AgentTokenIdentity struct {
	UUID                  string `json:"uuid"`
	Description           string `json:"description"`
	TokenType             string `json:"token_type"`
	OrganizationSlug      string `json:"organization_slug"`
	OrganizationUUID      string `json:"organization_uuid"`
	ClusterUUID           string `json:"cluster_uuid"`
	ClusterName           string `json:"cluster_name"`
	OrganizationQueueUUID string `json:"organization_queue_uuid"`
	OrganizationQueueKey  string `json:"organization_queue_key"`
}

AgentTokenIdentity describes the token identity information.

type BatchReserveJobsResult

type BatchReserveJobsResult struct {
	ReservedJobUUIDs    []string `json:"reserved"`
	NotReservedJobUUIDs []string `json:"not_reserved"`
}

ReserveJobBatchResult describes the result of a batch job reservation.

type JobState

type JobState string

All the possible states a job can be in

const (
	// The job was accepted by the agent, and now it's waiting to start running
	JobStateAccepted JobState = "accepted"
	// The job has been assigned to an agent, and it's waiting for it to accept
	JobStateAssigned JobState = "assigned"
	// The job is waiting on a `block` step to finish
	JobStateBlocked JobState = "blocked"
	// The job was in a `blocked` state when the build failed
	JobStateBlockedFailed JobState = "blocked_failed"
	// The jobs configuration means that it can't be run
	JobStateBroken JobState = "broken"
	// The job was canceled
	JobStateCanceled JobState = "canceled"
	// The job is currently canceling
	JobStateCanceling JobState = "canceling"
	// The job expired before it was started on an agent
	JobStateExpired JobState = "expired"
	// The job has finished
	JobStateFinished JobState = "finished"
	// The job is waiting for jobs with the same concurrency group to finish
	JobStateLimited JobState = "limited"
	// The job is waiting on a concurrency group check before becoming either `limited` or `scheduled`
	JobStateLimiting JobState = "limiting"
	// The job has just been created and doesn't have a state yet
	JobStatePending JobState = "pending"
	// The job is running
	JobStateRunning JobState = "running"
	// The job is scheduled and waiting for an agent
	JobStateScheduled JobState = "scheduled"
	// The job was skipped
	JobStateSkipped JobState = "skipped"
	// The job timed out
	JobStateTimedOut JobState = "timed_out"
	// The job is timing out for taking too long
	JobStateTimingOut JobState = "timing_out"
	// This `block` job has been manually unblocked
	JobStateUnblocked JobState = "unblocked"
	// This `block` job was in an `unblocked` state when the build failed
	JobStateUnblockedFailed JobState = "unblocked_failed"
	// The job is waiting on a `wait` step to finish
	JobStateWaiting JobState = "waiting"
	// The job was in a `waiting` state when the build failed
	JobStateWaitingFailed JobState = "waiting_failed"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL