Unpublished SDK candidate: reviewed source snapshot of 13 September 2026; SDK modules, v2 writes and the external-worker dispatcher are unavailable in
main. See availability and source.
SDK Go declarations¶
Generated by python3 scripts/sdk/reference.py. Do not edit generated tables.
These are the SDK candidate contracts. The current CPRa application serves v1 read-only endpoints; its v2 management and worker servers are not implemented. A listed SDK method is not evidence of a deployed server route. See the guide for runnable local examples.
Schema input SHA-256: 71723960b55145b57009faa9daa7fede20b08d85117171474b7c0631b4eb4977.
This index includes exported types, constants, errors, functions, and methods from the public SDK packages. Signatures and comments are extracted from Go syntax. Function bodies and private fields are omitted. Platform-specific implementation files may produce repeated signatures.
The combined api listing includes base types plus the tagged extension. Consult wire types for the per-type build boundary; api declarations that also exist in the base projection are available without externaljobs.
Package cpra¶
*ActionsService.Get¶
Get calls GET /api/v2/actions/{id}.
*ActionsService.Iterate¶
Iterate walks pages lazily.
*ActionsService.List¶
List calls GET /api/v2/actions.
func (s *ActionsService) List(ctx context.Context, opts ListOptions) (*Response[api.ActionList], error)
*ActionsService.Review¶
Review calls POST /api/v2/actions/{id}/review.
func (s *ActionsService) Review(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Action], error)
*AmbiguousError.Error¶
*AmbiguousError.Is¶
*AmbiguousError.Unwrap¶
*Client.Capabilities¶
Capabilities calls GET /api/v2/discovery.
*Client.CloseIdleConnections¶
CloseIdleConnections releases idle HTTP connections; it does not cancel calls. CloseIdleConnections closes idle transport connections without interrupting requests already in flight. It does not cancel operations on the server.
*Client.Explain¶
Explain calls GET /api/v2/schemas/{id}.
*Client.History¶
History calls GET /api/v2/history.
*Client.JobTypes¶
Build requirement: externaljobs.
JobTypes manages immutable versioned descriptors; it never loads executable code.
*Client.Live¶
Live calls GET /api/v2/healthz.
*Client.Metrics¶
Metrics returns the structured diagnostic snapshot.
*Client.Prometheus¶
Prometheus streams the metrics representation without accumulating it in memory. The bound detects excess data rather than silently returning a truncated success.
*Client.Ready¶
Ready calls GET /api/v2/readyz.
*Client.RuntimeConfig¶
RuntimeConfig calls GET /api/v2/config.
*Client.State¶
State calls GET /api/v2/state.
*Client.Version¶
Version calls GET /api/v2/version.
*Client.Workers¶
Build requirement: externaljobs.
Workers calls GET /api/v2/external-workers.
func (c *Client) Workers(ctx context.Context, opts ListOptions) (*Response[api.WorkerObservationList], error)
*CredentialsService.Create¶
Create calls POST /api/v2/credentials.
func (s *CredentialsService) Create(ctx context.Context, req api.Credential) (*Response[api.Credential], error)
*CredentialsService.Delete¶
Delete calls DELETE /api/v2/credentials/{id}.
func (s *CredentialsService) Delete(ctx context.Context, id string, version string) (*Response[api.Operation], error)
*CredentialsService.Get¶
Get calls GET /api/v2/credentials/{id}.
*CredentialsService.Iterate¶
Iterate walks pages lazily.
*CredentialsService.List¶
List calls GET /api/v2/credentials.
func (s *CredentialsService) List(ctx context.Context, opts ListOptions) (*Response[api.CredentialList], error)
*CredentialsService.Patch¶
Patch calls PATCH /api/v2/credentials/{id}.
func (s *CredentialsService) Patch(ctx context.Context, id string, version string, req api.MergePatch) (*Response[api.Credential], error)
*CredentialsService.Replace¶
Replace calls PUT /api/v2/credentials/{id}.
func (s *CredentialsService) Replace(ctx context.Context, id string, version string, req api.Credential) (*Response[api.Credential], error)
*Error.Error¶
*Error.Is¶
*IncidentsService.Acknowledge¶
Acknowledge calls POST /api/v2/incidents/{id}/acknowledge.
func (s *IncidentsService) Acknowledge(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Incident], error)
*IncidentsService.Dismiss¶
Dismiss calls POST /api/v2/incidents/{id}/dismiss.
func (s *IncidentsService) Dismiss(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Incident], error)
*IncidentsService.Get¶
Get calls GET /api/v2/incidents/{id}.
*IncidentsService.Iterate¶
Iterate walks pages lazily.
*IncidentsService.List¶
List calls GET /api/v2/incidents.
func (s *IncidentsService) List(ctx context.Context, opts ListOptions) (*Response[api.IncidentList], error)
*IncidentsService.Reopen¶
Reopen calls POST /api/v2/incidents/{id}/reopen.
func (s *IncidentsService) Reopen(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Incident], error)
*Iterator[T].Err¶
Err returns the first paging or context error, or nil after normal completion.
*Iterator[T].Next¶
Next advances to the next item, fetching at most one page as needed. It returns false at the end or after an error; inspect Err to distinguish those cases.
*Iterator[T].Value¶
Value returns the item selected by the most recent successful Next call.
*JobTypesService.Create¶
Build requirement: externaljobs.
Create calls POST /api/v2/job-types.
func (s *JobTypesService) Create(ctx context.Context, req api.JobType) (*Response[api.JobType], error)
*JobTypesService.Delete¶
Build requirement: externaljobs.
Delete calls DELETE /api/v2/job-types/{id}.
func (s *JobTypesService) Delete(ctx context.Context, id string, version string) (*Response[api.Operation], error)
*JobTypesService.Get¶
Build requirement: externaljobs.
Get calls GET /api/v2/job-types/{id}.
*JobTypesService.Iterate¶
Build requirement: externaljobs.
Iterate walks pages lazily.
*JobTypesService.List¶
Build requirement: externaljobs.
List calls GET /api/v2/job-types.
func (s *JobTypesService) List(ctx context.Context, opts ListOptions) (*Response[api.JobTypeList], error)
*JobTypesService.Replace¶
Build requirement: externaljobs.
Replace calls PUT /api/v2/job-types/{id}.
func (s *JobTypesService) Replace(ctx context.Context, id string, version string, req api.JobType) (*Response[api.JobType], error)
*MonitorsService.Create¶
Create calls POST /api/v2/monitors.
func (s *MonitorsService) Create(ctx context.Context, req api.Monitor) (*Response[api.Monitor], error)
*MonitorsService.Delete¶
Delete calls DELETE /api/v2/monitors/{id}.
func (s *MonitorsService) Delete(ctx context.Context, id string, version string) (*Response[api.Operation], error)
*MonitorsService.Disable¶
Disable conditionally disables admission without altering other operator controls.
func (s *MonitorsService) Disable(ctx context.Context, id, version string) (*Response[api.Monitor], error)
*MonitorsService.Enable¶
Enable preserves snoozes, dismissals, and maintenance policy.
func (s *MonitorsService) Enable(ctx context.Context, id, version string) (*Response[api.Monitor], error)
*MonitorsService.Get¶
Get calls GET /api/v2/monitors/{id}.
*MonitorsService.Iterate¶
Iterate walks pages lazily.
*MonitorsService.List¶
List calls GET /api/v2/monitors.
func (s *MonitorsService) List(ctx context.Context, opts ListOptions) (*Response[api.MonitorList], error)
*MonitorsService.Patch¶
Patch calls PATCH /api/v2/monitors/{id}.
func (s *MonitorsService) Patch(ctx context.Context, id string, version string, req api.MergePatch) (*Response[api.Monitor], error)
*MonitorsService.Recover¶
Recover calls POST /api/v2/monitors/{id}/recover.
func (s *MonitorsService) Recover(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Operation], error)
*MonitorsService.Replace¶
Replace calls PUT /api/v2/monitors/{id}.
func (s *MonitorsService) Replace(ctx context.Context, id string, version string, req api.Monitor) (*Response[api.Monitor], error)
*MonitorsService.Snooze¶
Snooze calls POST /api/v2/monitors/{id}/snooze.
func (s *MonitorsService) Snooze(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Operation], error)
*MonitorsService.Unsnooze¶
Unsnooze calls POST /api/v2/monitors/{id}/unsnooze.
func (s *MonitorsService) Unsnooze(ctx context.Context, id string, req api.ControlRequest) (*Response[api.Operation], error)
*NotificationEndpointsService.Create¶
Create calls POST /api/v2/notification-endpoints.
func (s *NotificationEndpointsService) Create(ctx context.Context, req api.NotificationEndpoint) (*Response[api.NotificationEndpoint], error)
*NotificationEndpointsService.Delete¶
Delete calls DELETE /api/v2/notification-endpoints/{id}.
func (s *NotificationEndpointsService) Delete(ctx context.Context, id string, version string) (*Response[api.Operation], error)
*NotificationEndpointsService.Get¶
Get calls GET /api/v2/notification-endpoints/{id}.
func (s *NotificationEndpointsService) Get(ctx context.Context, id string) (*Response[api.NotificationEndpoint], error)
*NotificationEndpointsService.Iterate¶
Iterate walks pages lazily.
func (s *NotificationEndpointsService) Iterate(opts ListOptions) *Iterator[api.NotificationEndpoint]
*NotificationEndpointsService.List¶
List calls GET /api/v2/notification-endpoints.
func (s *NotificationEndpointsService) List(ctx context.Context, opts ListOptions) (*Response[api.NotificationEndpointList], error)
*NotificationEndpointsService.Patch¶
Patch calls PATCH /api/v2/notification-endpoints/{id}.
func (s *NotificationEndpointsService) Patch(ctx context.Context, id string, version string, req api.MergePatch) (*Response[api.NotificationEndpoint], error)
*NotificationEndpointsService.Replace¶
Replace calls PUT /api/v2/notification-endpoints/{id}.
func (s *NotificationEndpointsService) Replace(ctx context.Context, id string, version string, req api.NotificationEndpoint) (*Response[api.NotificationEndpoint], error)
*NotificationGroupsService.Create¶
Create calls POST /api/v2/notification-groups.
func (s *NotificationGroupsService) Create(ctx context.Context, req api.NotificationGroup) (*Response[api.NotificationGroup], error)
*NotificationGroupsService.Delete¶
Delete calls DELETE /api/v2/notification-groups/{id}.
func (s *NotificationGroupsService) Delete(ctx context.Context, id string, version string) (*Response[api.Operation], error)
*NotificationGroupsService.Get¶
Get calls GET /api/v2/notification-groups/{id}.
func (s *NotificationGroupsService) Get(ctx context.Context, id string) (*Response[api.NotificationGroup], error)
*NotificationGroupsService.Iterate¶
Iterate walks pages lazily.
*NotificationGroupsService.List¶
List calls GET /api/v2/notification-groups.
func (s *NotificationGroupsService) List(ctx context.Context, opts ListOptions) (*Response[api.NotificationGroupList], error)
*NotificationGroupsService.Patch¶
Patch calls PATCH /api/v2/notification-groups/{id}.
func (s *NotificationGroupsService) Patch(ctx context.Context, id string, version string, req api.MergePatch) (*Response[api.NotificationGroup], error)
*NotificationGroupsService.Replace¶
Replace calls PUT /api/v2/notification-groups/{id}.
func (s *NotificationGroupsService) Replace(ctx context.Context, id string, version string, req api.NotificationGroup) (*Response[api.NotificationGroup], error)
*OperationsService.Activate¶
Activate calls POST /api/v2/operations/{id}/activate.
func (s *OperationsService) Activate(ctx context.Context, id string) (*Response[api.Operation], error)
*OperationsService.Cancel¶
Cancel calls POST /api/v2/operations/{id}/cancel.
func (s *OperationsService) Cancel(ctx context.Context, id string) (*Response[api.Operation], error)
*OperationsService.Create¶
Create calls POST /api/v2/operations.
func (s *OperationsService) Create(ctx context.Context, req api.OperationCreateRequest) (*Response[api.Operation], error)
*OperationsService.Get¶
Get calls GET /api/v2/operations/{id}.
*OperationsService.Preflight¶
Preflight calls POST /api/v2/collections/preflight.
func (s *OperationsService) Preflight(ctx context.Context, req api.PreflightRequest) (*Response[api.Preflight], error)
*OperationsService.Upload¶
Upload calls PUT /api/v2/operations/{id}/items.
func (s *OperationsService) Upload(ctx context.Context, id string, req api.UploadRequest) (*Response[api.Operation], error)
*OperationsService.Validate¶
Validate calls POST /api/v2/operations/{id}/validate.
func (s *OperationsService) Validate(ctx context.Context, id string) (*Response[api.Preflight], error)
*OperationsService.Wait¶
Wait observes operation progress. Cancelling the context never cancels the server operation.
*PoolsService.Iterate¶
Iterate walks pages lazily.
*PoolsService.List¶
List calls GET /api/v2/pools.
*QueuesService.Iterate¶
Iterate walks pages lazily.
*QueuesService.List¶
List calls GET /api/v2/queues.
func (s *QueuesService) List(ctx context.Context, opts ListOptions) (*Response[api.QueueList], error)
*SLOService.Get¶
Get calls GET /api/v2/slo.
*SystemsService.Iterate¶
Iterate walks pages lazily.
*SystemsService.List¶
List calls GET /api/v2/systems.
func (s *SystemsService) List(ctx context.Context, opts ListOptions) (*Response[api.SystemList], error)
*TransportError.Error¶
*TransportError.Unwrap¶
*WorkerClient.CloseIdleConnections¶
Build requirement: externaljobs.
CloseIdleConnections closes idle transport connections without cancelling an active handler, request, or server execution.
*WorkerClient.Heartbeat¶
Build requirement: externaljobs.
Heartbeat reports continued ownership of an execution. Callers must stop cooperative work when the server response revokes permission.
func (c *WorkerClient) Heartbeat(ctx context.Context, req api.HeartbeatRequest) (*api.HeartbeatResponse, error)
*WorkerClient.LateEvidence¶
Build requirement: externaljobs.
LateEvidence appends evidence without replacing an outcome or operator review.
func (c *WorkerClient) LateEvidence(ctx context.Context, req api.LateEvidenceRequest) (*api.Receipt, error)
*WorkerClient.Poll¶
Build requirement: externaljobs.
Poll requests bounded assignments for available capacity. An assignment is not permission to invoke a handler; obtain a granted Start disposition first.
*WorkerClient.Result¶
Build requirement: externaljobs.
Result reports the same server-owned outcome envelope until a durable receipt.
*WorkerClient.Start¶
Build requirement: externaljobs.
Start authorizes one execution only when Disposition is granted. Repeated terminal requests never confer permission to execute again.
ActionsService¶
AmbiguousError¶
AmbiguousError means the SDK cannot establish whether a mutation committed. Inspect the operation handle; never retry a new mutation blindly.
Client¶
Client is safe for concurrent use after creation. Treat its services as immutable.
type Client struct {
Monitors *MonitorsService
NotificationEndpoints *NotificationEndpointsService
NotificationGroups *NotificationGroupsService
Credentials *CredentialsService
Incidents *IncidentsService
Actions *ActionsService
Operations *OperationsService
Queues *QueuesService
Pools *PoolsService
Systems *SystemsService
SLO *SLOService
// contains filtered or unexported fields
}
Config¶
Config is copied by New. Callers retain ownership of supplied transports. HTTPClient redirect policy is always replaced; no authorization follows redirects.
type Config struct {
BaseURL string
AuthToken string
TokenSource TokenSource
Timeout time.Duration
HTTPClient *http.Client
RootCAs *x509.CertPool
AllowInsecureHTTP bool
MaxResponseBytes int64
// ReadAttempts is opt-in, at most three. Mutations are never automatically retried.
ReadAttempts int
}
CredentialsService¶
DefaultMaxResponseBytes¶
DefaultMaxResponseBytes bounds an ordinary decoded response to 64 MiB.
ErrConflict ErrNotFound ErrUnavailable ErrFeatureUnavailable ErrExpired ErrUnauthorized ErrInvalid ErrResponseTooLarge ErrAmbiguous¶
var (
ErrConflict = errors.New("resource version conflict")
ErrNotFound = errors.New("resource not found")
ErrUnavailable = errors.New("API unavailable")
ErrFeatureUnavailable = errors.New("feature unavailable")
ErrExpired = errors.New("operation or cursor expired")
ErrUnauthorized = errors.New("request unauthorized")
ErrInvalid = errors.New("invalid request")
ErrResponseTooLarge = errors.New("response exceeds configured byte limit")
ErrAmbiguous = errors.New("mutation outcome is uncertain")
)
Error¶
Error is an RFC 9457 response. Error() intentionally omits server-controlled detail and field values; inspect Problem explicitly when appropriate.
IncidentsService¶
Iterator¶
Iterator retains one page and fetches the next page only when exhausted.
JobTypesService¶
Build requirement: externaljobs.
ListOptions¶
ListOptions never requests an implicit full-fleet response.
MonitorsService¶
New¶
New validates connection settings and constructs a client without making a request. Caller-supplied HTTP clients are copied; their transport remains caller-owned. Redirects and automatic mutation retries are disabled.
NewWorkerClient¶
Build requirement: externaljobs.
NewWorkerClient constructs a protocol client with required authentication. Construction makes no request and grants no permission to execute work.
NotificationEndpointsService¶
NotificationGroupsService¶
OperationsService¶
PoolsService¶
QueuesService¶
Response¶
Response retains identity/progress headers separately from the typed payload.
type Response[T any] struct {
Data T
RequestID string
ResourceVersion string
OperationID string
StatusCode int
RetryAfter time.Duration
}
SLOService¶
SystemsService¶
TokenSource¶
TokenSource supplies credentials at request time, supporting explicit rotation.
TransportError¶
TransportError preserves errors.Is cancellation while excluding URL/token details from its printable message.
Version¶
Version identifies the SDK candidate, independently of the server API version.
WorkerClient¶
Build requirement: externaljobs.
WorkerClient uses a worker-scoped credential, separate from operator services. Servers must additionally enforce scoped worker permissions and runtime enablement.
Package api¶
APIVersion¶
APIVersion is the desired-resource wire version, independent of SDK versions.
Action¶
Action defines model for Action.
type Action struct {
CreatedAt time.Time `json:"createdAt,omitempty"`
ExecutionID string `json:"executionID,omitempty"`
ExecutionRevision string `json:"executionRevision,omitempty"`
ID string `json:"id"`
IncarnationUID string `json:"incarnationUID,omitempty"`
IncidentID string `json:"incidentID,omitempty"`
Kind string `json:"kind,omitempty"`
MonitorID string `json:"monitorID,omitempty"`
Reason string `json:"reason,omitempty"`
ReceiptID string `json:"receiptID,omitempty"`
State string `json:"state"`
UpdatedAt time.Time `json:"updatedAt,omitempty"`
}
ActionList¶
ActionList defines model for ActionList.
type ActionList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Action `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
AlertRule¶
AlertRule defines model for AlertRule.
type AlertRule struct {
Dispatch *bool `json:"dispatch,omitempty"`
Driver *DriverConfig `json:"driver,omitempty"`
EndpointRefs *[]string `json:"endpointRefs,omitempty"`
GroupRef *string `json:"groupRef,omitempty"`
}
ApplyItem¶
ApplyItem defines model for ApplyItem.
type ApplyItem struct {
ContentDigest string `json:"contentDigest"`
ID string `json:"id"`
Resource Resource `json:"resource"`
Source string `json:"source"`
}
ApplyResult¶
ApplyResult defines model for ApplyResult.
type ApplyResult struct {
Applied bool `json:"applied,omitempty"`
Committed bool `json:"committed,omitempty"`
ID string `json:"id"`
Message string `json:"message,omitempty"`
NewVersion string `json:"newVersion,omitempty"`
OldVersion string `json:"oldVersion,omitempty"`
Outcome string `json:"outcome"`
}
Assignment¶
Build requirement: externaljobs.
Assignment defines model for Assignment.
type Assignment struct {
CredentialProfile string `json:"credentialProfile"`
Deadline time.Time `json:"deadline"`
ExecutionID string `json:"executionID"`
ExecutionRevision string `json:"executionRevision"`
IncarnationUID string `json:"incarnationUID"`
JobTypeID string `json:"jobTypeID"`
JobTypeVersion string `json:"jobTypeVersion"`
Kind string `json:"kind"`
LeaseID string `json:"leaseID"`
MonitorID string `json:"monitorID"`
Parameters json.RawMessage `json:"parameters"`
ServerID string `json:"serverID"`
}
Assignments¶
Build requirement: externaljobs.
Assignments defines model for Assignments.
Capabilities¶
Capabilities defines model for Capabilities.
type Capabilities struct {
APIVersions []string `json:"apiVersions"`
Drivers map[string][]string `json:"drivers"`
PatchTypes []string `json:"patchTypes"`
Resources []string `json:"resources"`
}
CheckSpec¶
CheckSpec defines model for CheckSpec.
type CheckSpec struct {
Driver DriverConfig `json:"driver"`
Groups *[]string `json:"groups,omitempty"`
HealthyThreshold *int64 `json:"healthyThreshold,omitempty"`
// Interval Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Interval Duration `json:"interval"`
MaxFailures *int64 `json:"maxFailures,omitempty"`
Retries *int64 `json:"retries,omitempty"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout Duration `json:"timeout"`
UnhealthyThreshold *int64 `json:"unhealthyThreshold,omitempty"`
}
CodeNotificationDatadog¶
CodeNotificationDatadog defines model for CodeNotificationDatadog.
type CodeNotificationDatadog struct {
APIKey *string `json:"apiKey,omitempty"`
AppKey *string `json:"appKey,omitempty"`
Site *string `json:"site,omitempty"`
Tags *[]string `json:"tags,omitempty"`
URL *string `json:"url,omitempty"`
}
CodeNotificationDiscord¶
CodeNotificationDiscord defines model for CodeNotificationDiscord.
CodeNotificationEmail¶
CodeNotificationEmail defines model for CodeNotificationEmail.
type CodeNotificationEmail struct {
AllowInsecure *bool `json:"allowInsecure,omitempty"`
From *string `json:"from,omitempty"`
Server *string `json:"server,omitempty"`
Subject *string `json:"subject,omitempty"`
To *string `json:"to,omitempty"`
}
CodeNotificationLog¶
CodeNotificationLog defines model for CodeNotificationLog.
CodeNotificationMattermost¶
CodeNotificationMattermost defines model for CodeNotificationMattermost.
type CodeNotificationMattermost struct {
Channel *string `json:"channel,omitempty"`
Username *string `json:"username,omitempty"`
WebhookURL *string `json:"webhookUrl,omitempty"`
}
CodeNotificationOpsgenie¶
CodeNotificationOpsgenie defines model for CodeNotificationOpsgenie.
type CodeNotificationOpsgenie struct {
APIKey *string `json:"apiKey,omitempty"`
URL *string `json:"url,omitempty"`
}
CodeNotificationPagerDuty¶
CodeNotificationPagerDuty defines model for CodeNotificationPagerDuty.
type CodeNotificationPagerDuty struct {
RoutingKey *string `json:"routingKey,omitempty"`
URL *string `json:"url,omitempty"`
}
CodeNotificationPushover¶
CodeNotificationPushover defines model for CodeNotificationPushover.
type CodeNotificationPushover struct {
AppToken *string `json:"appToken,omitempty"`
Expire *int64 `json:"expire,omitempty"`
Priority *int64 `json:"priority,omitempty"`
Retry *int64 `json:"retry,omitempty"`
Sound *string `json:"sound,omitempty"`
Title *string `json:"title,omitempty"`
URL *string `json:"url,omitempty"`
UserKey *string `json:"userKey,omitempty"`
}
CodeNotificationSlack¶
CodeNotificationSlack defines model for CodeNotificationSlack.
CodeNotificationTeams¶
CodeNotificationTeams defines model for CodeNotificationTeams.
CodeNotificationTelegram¶
CodeNotificationTelegram defines model for CodeNotificationTelegram.
type CodeNotificationTelegram struct {
BotToken *string `json:"botToken,omitempty"`
ChatID *string `json:"chatId,omitempty"`
TestMode *bool `json:"testMode,omitempty"`
URL *string `json:"url,omitempty"`
}
CodeNotificationTwilio¶
CodeNotificationTwilio defines model for CodeNotificationTwilio.
type CodeNotificationTwilio struct {
AccountSID *string `json:"accountSid,omitempty"`
AuthToken *string `json:"authToken,omitempty"`
From *string `json:"from,omitempty"`
To *string `json:"to,omitempty"`
URL *string `json:"url,omitempty"`
}
CodeNotificationVictorOps¶
CodeNotificationVictorOps defines model for CodeNotificationVictorOps.
type CodeNotificationVictorOps struct {
EntityID *string `json:"entityId,omitempty"`
MessageType *string `json:"messageType,omitempty"`
RESTEndpointKey *string `json:"restEndpointKey,omitempty"`
RoutingKey *string `json:"routingKey,omitempty"`
URL *string `json:"url,omitempty"`
}
CodeNotificationWebhook¶
CodeNotificationWebhook defines model for CodeNotificationWebhook.
type CodeNotificationWebhook struct {
Headers *map[string]string `json:"headers,omitempty"`
Method *string `json:"method,omitempty"`
URL *string `json:"url,omitempty"`
}
ControlRequest¶
ControlRequest defines model for ControlRequest.
type ControlRequest struct {
// Duration Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Duration Duration `json:"duration,omitempty"`
EvidenceRefs []string `json:"evidenceRefs,omitempty"`
IncidentID string `json:"incidentID,omitempty"`
Note string `json:"note,omitempty"`
Reason string `json:"reason,omitempty"`
Resolution string `json:"resolution,omitempty"`
Revision string `json:"revision"`
}
Credential¶
Credential defines model for Credential.
type Credential struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec CredentialSpec `json:"spec"`
Status json.RawMessage `json:"status,omitempty"`
}
CredentialList¶
CredentialList defines model for CredentialList.
type CredentialList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Credential `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
CredentialSpec¶
CredentialSpec defines model for CredentialSpec.
type CredentialSpec struct {
Description *string `json:"description,omitempty"`
Value *string `json:"value,omitempty"`
}
DecodeResource¶
DecodeResource validates a source-neutral resource envelope.
DecodeResponse¶
DecodeResponse permits additive fields from newer servers while checking the presence of required contract fields. Unavailable zero values must be explicit. Unlike mutation decoding, forward-compatible response fields are not rejected.
Driver¶
Driver constructs a concrete driver envelope while preserving optional fields.
DriverConfig¶
DriverConfig defines model for DriverConfig.
type DriverConfig struct {
Config json.RawMessage `json:"config"`
CredentialRefs *map[string]string `json:"credentialRefs,omitempty"`
Type string `json:"type"`
}
Duration¶
Duration Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
ErrUnsupportedDriver¶
ErrUnsupportedDriver reports a driver absent from this SDK's selected schema.
Event¶
Event defines model for Event.
type Event struct {
ActionID string `json:"actionID,omitempty"`
Actor string `json:"actor,omitempty"`
ID string `json:"id"`
IncidentID string `json:"incidentID,omitempty"`
Kind string `json:"kind"`
MonitorID string `json:"monitorID"`
Reason string `json:"reason,omitempty"`
Time time.Time `json:"time"`
}
EventList¶
EventList defines model for EventList.
type EventList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Event `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
Explanation¶
Explanation defines model for Explanation.
type Explanation struct {
Description string `json:"description"`
Resource string `json:"resource"`
Schema json.RawMessage `json:"schema"`
}
ExternalConfig¶
Build requirement: externaljobs.
ExternalConfig defines model for ExternalConfig.
type ExternalConfig struct {
CredentialProfile string `json:"credentialProfile,omitempty"`
JobTypeID string `json:"jobTypeID"`
Parameters json.RawMessage `json:"parameters"`
Version string `json:"version"`
}
FieldError¶
FieldError defines model for FieldError.
type FieldError struct {
Field string `json:"field"`
Message string `json:"message"`
Reason string `json:"reason,omitempty"`
}
Health¶
Health defines model for Health.
type Health struct {
Available bool `json:"available"`
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Reason string `json:"reason,omitempty"`
}
HeartbeatRequest¶
Build requirement: externaljobs.
HeartbeatRequest defines model for HeartbeatRequest.
type HeartbeatRequest struct {
ExecutionID string `json:"executionID"`
ExecutionIDs []string `json:"executionIDs,omitempty"`
GrantID string `json:"grantID"`
WorkerID string `json:"workerID"`
}
HeartbeatResponse¶
Build requirement: externaljobs.
HeartbeatResponse defines model for HeartbeatResponse.
Incident¶
Incident defines model for Incident.
type Incident struct {
AcknowledgedAt time.Time `json:"acknowledgedAt,omitempty"`
AcknowledgedBy string `json:"acknowledgedBy,omitempty"`
ClosedAt time.Time `json:"closedAt,omitempty"`
Dismissed bool `json:"dismissed,omitempty"`
ID string `json:"id"`
MonitorID string `json:"monitorID"`
OpenedAt time.Time `json:"openedAt,omitempty"`
Revision string `json:"revision"`
State string `json:"state"`
}
IncidentList¶
IncidentList defines model for IncidentList.
type IncidentList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Incident `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
InterventionTargetAWS¶
InterventionTargetAWS defines model for InterventionTargetAWS.
type InterventionTargetAWS struct {
InstanceID *string `json:"instanceId,omitempty"`
Operation *string `json:"operation,omitempty"`
Region *string `json:"region,omitempty"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout *Duration `json:"timeout,omitempty"`
Type *string `json:"type,omitempty"`
}
InterventionTargetDocker¶
InterventionTargetDocker defines model for InterventionTargetDocker.
type InterventionTargetDocker struct {
Container *string `json:"container,omitempty"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout *Duration `json:"timeout,omitempty"`
Type *string `json:"type,omitempty"`
}
InterventionTargetKubernetes¶
InterventionTargetKubernetes defines model for InterventionTargetKubernetes.
type InterventionTargetKubernetes struct {
Kind *string `json:"kind,omitempty"`
KubeconfigPath *string `json:"kubeconfigPath,omitempty"`
Name *string `json:"name,omitempty"`
Namespace *string `json:"namespace,omitempty"`
Replicas *int64 `json:"replicas,omitempty"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout *Duration `json:"timeout,omitempty"`
Type *string `json:"type,omitempty"`
}
InterventionTargetSystemd¶
InterventionTargetSystemd defines model for InterventionTargetSystemd.
type InterventionTargetSystemd struct {
Mode *string `json:"mode,omitempty"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout *Duration `json:"timeout,omitempty"`
Type *string `json:"type,omitempty"`
Unit *string `json:"unit,omitempty"`
}
InterventionTargetWebhook¶
InterventionTargetWebhook defines model for InterventionTargetWebhook.
type InterventionTargetWebhook struct {
Body *string `json:"body,omitempty"`
Headers *map[string]string `json:"headers,omitempty"`
Method *string `json:"method,omitempty"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout *Duration `json:"timeout,omitempty"`
Type *string `json:"type,omitempty"`
URL *string `json:"url,omitempty"`
}
JobType¶
Build requirement: externaljobs.
JobType defines model for JobType.
type JobType struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec JobTypeSpec `json:"spec"`
}
JobTypeList¶
Build requirement: externaljobs.
JobTypeList defines model for JobTypeList.
type JobTypeList struct {
Items []JobType `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
}
JobTypeSpec¶
Build requirement: externaljobs.
JobTypeSpec defines model for JobTypeSpec.
type JobTypeSpec struct {
Handler string `json:"handler"`
Kind string `json:"kind"`
ParameterSchema json.RawMessage `json:"parameterSchema"`
ProtocolVersion string `json:"protocolVersion"`
RejectionCodes []string `json:"rejectionCodes,omitempty"`
ResultSchema json.RawMessage `json:"resultSchema"`
// Timeout Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Timeout Duration `json:"timeout,omitempty"`
Version string `json:"version"`
}
LateEvidenceRequest¶
Build requirement: externaljobs.
LateEvidenceRequest defines model for LateEvidenceRequest.
type LateEvidenceRequest struct {
Data json.RawMessage `json:"data"`
Diagnostic string `json:"diagnostic"`
Evidence []string `json:"evidence"`
EvidenceID string `json:"evidenceID"`
ExecutionID string `json:"executionID"`
OriginalReceiptID string `json:"originalReceiptID"`
}
MaintenanceWindow¶
MaintenanceWindow defines model for MaintenanceWindow.
type MaintenanceWindow struct {
Cron *string `json:"cron,omitempty"`
// Duration Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Duration *Duration `json:"duration,omitempty"`
End *time.Time `json:"end,omitempty"`
Start *time.Time `json:"start,omitempty"`
Timezone *string `json:"timezone,omitempty"`
}
MaxResourceBytes¶
MaxResourceBytes bounds each encoded desired resource to 1 MiB.
Measurement¶
Measurement defines model for Measurement.
type Measurement struct {
Available bool `json:"available"`
Reason string `json:"reason,omitempty"`
Value float64 `json:"value,omitempty"`
}
MergePatch¶
MergePatch defines model for MergePatch.
Metadata¶
Metadata defines model for Metadata.
type Metadata struct {
Generation int64 `json:"generation,omitempty"`
ID string `json:"id"`
Labels *map[string]string `json:"labels,omitempty"`
Name *string `json:"name,omitempty"`
ResourceVersion string `json:"resourceVersion,omitempty"`
UID string `json:"uid,omitempty"`
}
Metrics¶
Metrics defines model for Metrics.
type Metrics struct {
GeneratedAt time.Time `json:"generatedAt"`
Pools []Pool `json:"pools,omitempty"`
Queues []Queue `json:"queues,omitempty"`
SLO SLOView `json:"slo,omitempty"`
Systems []System `json:"systems,omitempty"`
}
Monitor¶
Monitor defines model for Monitor.
type Monitor struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec MonitorSpec `json:"spec"`
Status MonitorStatus `json:"status,omitempty"`
}
MonitorList¶
MonitorList defines model for MonitorList.
type MonitorList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Monitor `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
MonitorSpec¶
MonitorSpec defines model for MonitorSpec.
type MonitorSpec struct {
Check CheckSpec `json:"check"`
Enabled *bool `json:"enabled,omitempty"`
Maintenance *[]MaintenanceWindow `json:"maintenance,omitempty"`
NotificationGroupRefs *[]string `json:"notificationGroupRefs,omitempty"`
Notifications *map[string]AlertRule `json:"notifications,omitempty"`
Recovery *RecoverySpec `json:"recovery,omitempty"`
Tags *[]string `json:"tags,omitempty"`
}
MonitorStatus¶
MonitorStatus defines model for MonitorStatus.
type MonitorStatus struct {
ControlRevision string `json:"controlRevision,omitempty"`
ExecutionRevision string `json:"executionRevision,omitempty"`
Health string `json:"health,omitempty"`
IncidentID string `json:"incidentID,omitempty"`
LastCheckLatencyMS Measurement `json:"lastCheckLatencyMs,omitempty"`
LastCheckedAt time.Time `json:"lastCheckedAt,omitempty"`
ObservedGeneration int64 `json:"observedGeneration,omitempty"`
SnoozedUntil time.Time `json:"snoozedUntil,omitempty"`
StatusRevision string `json:"statusRevision,omitempty"`
UnknownActions int64 `json:"unknownActions,omitempty"`
}
NormalizeLegacyDriver¶
NormalizeLegacyDriver converts known top-level keys, never map values such as headers.
NotificationEndpoint¶
NotificationEndpoint defines model for NotificationEndpoint.
type NotificationEndpoint struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec DriverConfig `json:"spec"`
Status json.RawMessage `json:"status,omitempty"`
}
NotificationEndpointList¶
NotificationEndpointList defines model for NotificationEndpointList.
type NotificationEndpointList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []NotificationEndpoint `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
NotificationGroup¶
NotificationGroup defines model for NotificationGroup.
type NotificationGroup struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec NotificationGroupSpec `json:"spec"`
Status json.RawMessage `json:"status,omitempty"`
}
NotificationGroupList¶
NotificationGroupList defines model for NotificationGroupList.
type NotificationGroupList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []NotificationGroup `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
NotificationGroupSpec¶
NotificationGroupSpec defines model for NotificationGroupSpec.
Operation¶
Operation defines model for Operation.
type Operation struct {
Applied int64 `json:"applied,omitempty"`
Committed int64 `json:"committed,omitempty"`
ContentDigest string `json:"contentDigest"`
ID string `json:"id"`
Items []ApplyResult `json:"items,omitempty"`
NextCursor string `json:"nextCursor,omitempty"`
RetryAfterSeconds int64 `json:"retryAfterSeconds,omitempty"`
State string `json:"state"`
Uploaded int64 `json:"uploaded,omitempty"`
Validated bool `json:"validated,omitempty"`
}
OperationCreateRequest¶
OperationCreateRequest defines model for OperationCreateRequest.
type OperationCreateRequest struct {
ContentDigest string `json:"contentDigest"`
ItemCount int64 `json:"itemCount"`
}
Outcome¶
Build requirement: externaljobs.
Outcome defines model for Outcome.
type Outcome struct {
Data json.RawMessage `json:"data"`
Diagnostic string `json:"diagnostic"`
DiagnosticTruncated bool `json:"diagnosticTruncated"`
Evidence []string `json:"evidence"`
ExecutionID string `json:"executionID"`
GrantID string `json:"grantID"`
Kind string `json:"kind"`
RejectionCode string `json:"rejectionCode"`
Status string `json:"status"`
}
Percentiles¶
Percentiles defines model for Percentiles.
type Percentiles struct {
Available bool `json:"available"`
P50MS float64 `json:"p50Ms,omitempty"`
P95MS float64 `json:"p95Ms,omitempty"`
P99MS float64 `json:"p99Ms,omitempty"`
}
Pointer¶
Pointer returns a pointer to a copy of value, preserving optional false and zero values without losing presence.
PollRequest¶
Build requirement: externaljobs.
PollRequest defines model for PollRequest.
type PollRequest struct {
Capabilities []WorkerCapability `json:"capabilities"`
Capacity int64 `json:"capacity"`
Limit int64 `json:"limit"`
WaitSeconds int64 `json:"waitSeconds"`
WorkerID string `json:"workerID"`
}
Pool¶
Pool defines model for Pool.
type Pool struct {
AdjustmentReason string `json:"adjustmentReason,omitempty"`
Busy int64 `json:"busy,omitempty"`
Maximum int64 `json:"maximum,omitempty"`
Minimum int64 `json:"minimum,omitempty"`
ModelRecommendation int64 `json:"modelRecommendation,omitempty"`
Name string `json:"name"`
Workers int64 `json:"workers"`
}
PoolList¶
PoolList defines model for PoolList.
type PoolList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Pool `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
Preflight¶
Preflight defines model for Preflight.
type Preflight struct {
ContentDigest string `json:"contentDigest,omitempty"`
Errors []FieldError `json:"errors,omitempty"`
Items []ApplyResult `json:"items,omitempty"`
Valid bool `json:"valid"`
}
PreflightRequest¶
PreflightRequest defines model for PreflightRequest.
Problem¶
Problem defines model for Problem.
type Problem struct {
Code string `json:"code,omitempty"`
Detail string `json:"detail,omitempty"`
Errors []FieldError `json:"errors,omitempty"`
Instance string `json:"instance,omitempty"`
OperationID string `json:"operationID,omitempty"`
RequestID string `json:"requestID,omitempty"`
Status int64 `json:"status,omitempty"`
Title string `json:"title,omitempty"`
Type string `json:"type,omitempty"`
}
PulseDNSConfig¶
PulseDNSConfig defines model for PulseDNSConfig.
type PulseDNSConfig struct {
Host *string `json:"host,omitempty"`
Retries *int64 `json:"retries,omitempty"`
Server *string `json:"server,omitempty"`
}
PulseDockerConfig¶
PulseDockerConfig defines model for PulseDockerConfig.
type PulseDockerConfig struct {
Container *string `json:"container,omitempty"`
Retries *int64 `json:"retries,omitempty"`
}
PulseGRPCConfig¶
PulseGRPCConfig defines model for PulseGRPCConfig.
type PulseGRPCConfig struct {
Host *string `json:"host,omitempty"`
Port *int64 `json:"port,omitempty"`
Retries *int64 `json:"retries,omitempty"`
Service *string `json:"service,omitempty"`
}
PulseHTTPConfig¶
PulseHTTPConfig defines model for PulseHTTPConfig.
type PulseHTTPConfig struct {
Body *string `json:"body,omitempty"`
ExpectedStatus *[]int64 `json:"expectedStatus,omitempty"`
Headers *map[string]string `json:"headers,omitempty"`
InsecureSkipVerify *bool `json:"insecureSkipVerify,omitempty"`
Method *string `json:"method,omitempty"`
Retries *int64 `json:"retries,omitempty"`
URL *string `json:"url,omitempty"`
}
PulseICMPConfig¶
PulseICMPConfig defines model for PulseICMPConfig.
type PulseICMPConfig struct {
Count *int64 `json:"count,omitempty"`
Host *string `json:"host,omitempty"`
Privilege *bool `json:"ignorePrivilege,omitempty"`
Retries *int64 `json:"retries,omitempty"`
}
PulseKafkaConfig¶
PulseKafkaConfig defines model for PulseKafkaConfig.
type PulseKafkaConfig struct {
Brokers *[]string `json:"brokers,omitempty"`
Retries *int64 `json:"retries,omitempty"`
}
PulseMongoConfig¶
PulseMongoConfig defines model for PulseMongoConfig.
type PulseMongoConfig struct {
Retries *int64 `json:"retries,omitempty"`
URI *string `json:"uri,omitempty"`
}
PulseMySQLConfig¶
PulseMySQLConfig defines model for PulseMySQLConfig.
type PulseMySQLConfig struct {
Database *string `json:"database,omitempty"`
DSN *string `json:"dsn,omitempty"`
Host *string `json:"host,omitempty"`
Password *string `json:"password,omitempty"`
Port *int64 `json:"port,omitempty"`
Retries *int64 `json:"retries,omitempty"`
User *string `json:"user,omitempty"`
}
PulsePostgresConfig¶
PulsePostgresConfig defines model for PulsePostgresConfig.
type PulsePostgresConfig struct {
Database *string `json:"database,omitempty"`
DSN *string `json:"dsn,omitempty"`
Host *string `json:"host,omitempty"`
Password *string `json:"password,omitempty"`
Port *int64 `json:"port,omitempty"`
Retries *int64 `json:"retries,omitempty"`
SSLMode *string `json:"sslmode,omitempty"`
User *string `json:"user,omitempty"`
}
PulseRabbitMQConfig¶
PulseRabbitMQConfig defines model for PulseRabbitMQConfig.
type PulseRabbitMQConfig struct {
Retries *int64 `json:"retries,omitempty"`
URL *string `json:"url,omitempty"`
}
PulseRedisConfig¶
PulseRedisConfig defines model for PulseRedisConfig.
type PulseRedisConfig struct {
Addr *string `json:"addr,omitempty"`
DB *int64 `json:"db,omitempty"`
Password *string `json:"password,omitempty"`
Retries *int64 `json:"retries,omitempty"`
Username *string `json:"username,omitempty"`
}
PulseTCPConfig¶
PulseTCPConfig defines model for PulseTCPConfig.
type PulseTCPConfig struct {
Host *string `json:"host,omitempty"`
Port *int64 `json:"port,omitempty"`
Retries *int64 `json:"retries,omitempty"`
}
PulseTLSConfig¶
PulseTLSConfig defines model for PulseTLSConfig.
type PulseTLSConfig struct {
CriticalDays *int64 `json:"criticalDays,omitempty"`
Host *string `json:"host,omitempty"`
InsecureSkipVerify *bool `json:"insecureSkipVerify,omitempty"`
Port *int64 `json:"port,omitempty"`
Retries *int64 `json:"retries,omitempty"`
ServerName *string `json:"serverName,omitempty"`
WarnDays *int64 `json:"warnDays,omitempty"`
}
PulseUDPConfig¶
PulseUDPConfig defines model for PulseUDPConfig.
type PulseUDPConfig struct {
Host *string `json:"host,omitempty"`
Payload *string `json:"payload,omitempty"`
Port *int64 `json:"port,omitempty"`
Retries *int64 `json:"retries,omitempty"`
}
Queue¶
Queue defines model for Queue.
type Queue struct {
Capacity int64 `json:"capacity"`
CompletedPerSecond float64 `json:"completedPerSecond,omitempty"`
Depth int64 `json:"depth"`
Drops int64 `json:"drops,omitempty"`
EnqueuedPerSecond float64 `json:"enqueuedPerSecond,omitempty"`
LimitReason string `json:"limitReason,omitempty"`
Name string `json:"name"`
OldestPendingMS Measurement `json:"oldestPendingMs,omitempty"`
Saturated bool `json:"saturated"`
}
QueueList¶
QueueList defines model for QueueList.
type QueueList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []Queue `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
Receipt¶
Build requirement: externaljobs.
Receipt defines model for Receipt.
type Receipt struct {
Disposition string `json:"disposition"`
ExecutionID string `json:"executionID"`
ReceiptID string `json:"receiptID"`
ServerID string `json:"serverID"`
}
RecoverySpec¶
RecoverySpec defines model for RecoverySpec.
type RecoverySpec struct {
// Cooldown Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Cooldown *Duration `json:"cooldown,omitempty"`
Driver DriverConfig `json:"driver"`
MaxAttempts *int64 `json:"maxAttempts,omitempty"`
MaxFailures *int64 `json:"maxFailures,omitempty"`
Retries *int64 `json:"retries,omitempty"`
}
Resource¶
Resource defines model for Resource.
type Resource struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec json.RawMessage `json:"spec"`
Status json.RawMessage `json:"status,omitempty"`
}
RuntimeConfig¶
RuntimeConfig defines model for RuntimeConfig.
type RuntimeConfig struct {
// HistoryRetention Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
HistoryRetention Duration `json:"historyRetention,omitempty"`
QueueCapacity int64 `json:"queueCapacity,omitempty"`
ReadOnly bool `json:"readOnly,omitempty"`
// SloWindow Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
SloWindow Duration `json:"sloWindow,omitempty"`
StorageMode string `json:"storageMode,omitempty"`
}
SLOReport¶
SLOReport defines model for SLOReport.
type SLOReport struct {
Attainment Measurement `json:"attainment,omitempty"`
Condition string `json:"condition,omitempty"`
Driver string `json:"driver"`
Execution Percentiles `json:"execution,omitempty"`
Missed int64 `json:"missed,omitempty"`
Pipeline string `json:"pipeline"`
QueueDelay Percentiles `json:"queueDelay,omitempty"`
QueueThresholdPassed int64 `json:"queueThresholdPassed,omitempty"`
Samples int64 `json:"samples"`
Timeouts int64 `json:"timeouts,omitempty"`
TotalLatency Percentiles `json:"totalLatency,omitempty"`
TotalThresholdPassed int64 `json:"totalThresholdPassed,omitempty"`
}
SLOView¶
SLOView defines model for SLOView.
type SLOView struct {
CoverageGap bool `json:"coverageGap"`
GeneratedAt time.Time `json:"generatedAt"`
Reports []SLOReport `json:"reports"`
// Window Go duration string, e.g. 60s. Never numeric nanoseconds or ISO-8601.
Window Duration `json:"window"`
}
Schema¶
Schema returns an independent copy of this build's OpenAPI contract.
StartRequest¶
Build requirement: externaljobs.
StartRequest defines model for StartRequest.
type StartRequest struct {
ExecutionID string `json:"executionID"`
ExecutionRevision string `json:"executionRevision"`
LeaseID string `json:"leaseID"`
}
StartResponse¶
Build requirement: externaljobs.
StartResponse defines model for StartResponse.
type StartResponse struct {
Deadline time.Time `json:"deadline"`
Disposition string `json:"disposition"`
GrantID string `json:"grantID"`
ReceiptID string `json:"receiptID"`
ServerID string `json:"serverID"`
}
State¶
State defines model for State.
type State struct {
Actions []Action `json:"actions,omitempty"`
GeneratedAt time.Time `json:"generatedAt"`
Live bool `json:"live"`
ProjectionAgeMS float64 `json:"projectionAgeMs,omitempty"`
Ready bool `json:"ready"`
Storage StorageState `json:"storage"`
UnknownActions int64 `json:"unknownActions,omitempty"`
}
StorageState¶
StorageState defines model for StorageState.
type StorageState struct {
AppliedIndex int64 `json:"appliedIndex,omitempty"`
Available bool `json:"available"`
Bytes int64 `json:"bytes,omitempty"`
CommitIndex int64 `json:"commitIndex,omitempty"`
Error string `json:"error,omitempty"`
FormatVersion int64 `json:"formatVersion,omitempty"`
Mode string `json:"mode"`
}
StrictDecode¶
StrictDecode rejects duplicate keys, unknown typed fields and trailing values.
System¶
System defines model for System.
type System struct {
EntitiesProcessed int64 `json:"entitiesProcessed,omitempty"`
LastUpdateDurationMS Measurement `json:"lastUpdateDurationMs,omitempty"`
Name string `json:"name"`
ProgressAt time.Time `json:"progressAt,omitempty"`
Updates int64 `json:"updates,omitempty"`
}
SystemList¶
SystemList defines model for SystemList.
type SystemList struct {
GeneratedAt time.Time `json:"generatedAt,omitempty"`
Items []System `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
Snapshot string `json:"snapshot,omitempty"`
}
UploadRequest¶
UploadRequest defines model for UploadRequest.
ValidateDriver¶
ValidateDriver rejects unknown variants on mutation; ordinary read decoding retains their type and raw configuration for inspection.
ValidateResource¶
ValidateResource checks a resource envelope, spec, and selected driver shapes. It performs no server authorization, live dependency check, or provider I/O.
ValidateResourceValue¶
ValidateResourceValue validates a typed resource before mutation.
Version¶
Version defines model for Version.
type Version struct {
Commit string `json:"commit,omitempty"`
GoVersion string `json:"goVersion,omitempty"`
SourceTime time.Time `json:"sourceTime,omitempty"`
StorageFormat int64 `json:"storageFormat,omitempty"`
Version string `json:"version"`
}
WorkerCapability¶
Build requirement: externaljobs.
WorkerCapability defines model for WorkerCapability.
type WorkerCapability struct {
JobTypeID string `json:"jobTypeID"`
Kind string `json:"kind"`
Version string `json:"version"`
}
WorkerObservation¶
Build requirement: externaljobs.
WorkerObservation defines model for WorkerObservation.
type WorkerObservation struct {
Active int64 `json:"active"`
Capacity int64 `json:"capacity"`
LastSeenAt time.Time `json:"lastSeenAt"`
WorkerID string `json:"workerID"`
}
WorkerObservationList¶
Build requirement: externaljobs.
WorkerObservationList defines model for WorkerObservationList.
type WorkerObservationList struct {
Items []WorkerObservation `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
}
Package collection¶
*Frozen.Close¶
Close closes and removes private plaintext staging. Calling it again is safe.
*Frozen.Digest¶
Digest returns the frozen collection's content identity for operation resume.
*Frozen.Item¶
Item reads one bounded resource. Concurrent reads are supported until Close.
*Frozen.Len¶
Len returns the number of frozen resource records.
*Frozen.Range¶
Range reads at most one resource at a time in frozen source order.
*Frozen.StagedBytes¶
StagedBytes reports encoded resource bytes retained in local staging.
Apply¶
Apply creates inactive staging only after Freeze has fully parsed and locally validated every source. It uploads bounded chunks, asks the server to validate the entire staged union, and activates only after that succeeds. The server is responsible for dependency ordering, authorization, and per-resource CAS.
Diff¶
Diff uses the same ephemeral preflight contract and returns proposed item outcomes. It makes no active writes or implicit deletions.
ErrPreflightRejected¶
ErrPreflightRejected reports a server validation response whose Valid is false.
File¶
File selects a file or directory for Freeze. Recursive traversal requires Options.Recursive; this constructor does not read the filesystem.
Freeze¶
Freeze reads all inputs before returning. Any parse, duplicate, quota, or cancellation error removes the complete staging directory. Remote permission, capability, schema, and live-reference validation still require Preflight.
FreezeResources¶
FreezeResources reads, validates, and privately stages a typed resource stream. It returns only after all resources have been frozen; failure removes staging.
func FreezeResources(ctx context.Context, source ResourceSource, options Options) (_ *Frozen, err error)
Frozen¶
Frozen holds private, plaintext, bounded client staging. Close removes all staging. It is not a persistent resume token and must not be included in logs or backups. A new Freeze observes changed files; this instance never does.
Item¶
Item is a frozen desired resource. ContentDigest is its SHA-256 JSON digest. ID is the immutable identity within an apply operation, distinct from resource ID.
type Item struct {
ID string `json:"id"`
ContentDigest string `json:"contentDigest"`
Location Location `json:"location"`
Resource api.Resource `json:"resource"`
}
Location.String¶
String formats a source location without including its resource payload.
Location¶
Location is retained without URL query strings, user credentials, or payloads.
type Location struct {
Source string `json:"source"`
Document int `json:"document"`
Item int `json:"item"`
}
MaxChunkItems MaxChunkBytes¶
const (
// MaxChunkItems bounds the resource records in one upload request.
MaxChunkItems = 256
// MaxChunkBytes bounds an encoded upload or ephemeral preflight request.
MaxChunkBytes = 4 << 20
)
Operations¶
Operations is implemented by cpra.OperationsService. Keeping the interface narrow also permits protocol contract tests without importing a server.
type Operations interface {
Preflight(context.Context, api.PreflightRequest) (*cpra.Response[api.Preflight], error)
Create(context.Context, api.OperationCreateRequest) (*cpra.Response[api.Operation], error)
Upload(context.Context, string, api.UploadRequest) (*cpra.Response[api.Operation], error)
Validate(context.Context, string) (*cpra.Response[api.Preflight], error)
Activate(context.Context, string) (*cpra.Response[api.Operation], error)
Get(context.Context, string) (*cpra.Response[api.Operation], error)
Cancel(context.Context, string) (*cpra.Response[api.Operation], error)
}
Options¶
Options bounds plaintext client staging. A zero field selects its default. SourceTransport, when supplied, must be an unauthenticated source transport; it must not inject API or provider credentials.
type Options struct {
Recursive bool
AllowHTTP bool
TempDir string
MaxStagingBytes int64
MaxResourceBytes int
MaxDocumentBytes int
MaxResources int
SourceTimeout time.Duration
SourceTransport http.RoundTripper
}
Preflight¶
Preflight performs ephemeral, bounded server validation/diff. It does not create a durable apply operation. A collection larger than one 4 MiB request fails explicitly: streaming ephemeral validation requires server support. Apply can stage a larger collection in encrypted, inactive server storage.
Reader¶
Reader consumes r once; ownership and closing remain with its caller.
Reference¶
Reference identifies a dependency independently of its display name.
ResolveReference¶
ResolveReference resolves an omitted, authorized live dependency to its opaque resource version. It must return an error for a missing or unauthorized object. Versions are observations, not locks: server preflight and activation CAS are still mandatory. Nil resolves against the submitted collection only.
ResourceSource¶
ResourceSource supplies typed API resources without constructing a fleet-sized slice. io.EOF ends the source. Resource values are serialized before advancing.
Result¶
Result retains the server-issued handle on partial progress or an error. It never treats a stopped client as a request to undo or cancel server commits.
type Result struct {
OperationID string
Operation api.Operation
Preflight *api.Preflight
Noop bool
}
Resume¶
Resume explicitly resumes the original operation only when frozen content matches it. Identical item uploads are replay-safe by the server contract; unknown transport outcomes are returned, never automatically retried here.
Slice¶
Slice adapts a small caller-owned typed collection. FreezeResources copies its serialized values; callers must not mutate the slice during freezing.
Source¶
Source identifies a file, directory, URL, or caller-owned reader. Constructors keep source fetching separate from the authenticated CPRa client.
URL¶
URL selects an explicit remote input for Freeze's separate source client. CPRa authentication is never inherited by that client.
ValidateReferences¶
ValidateReferences checks all shared definitions, not only referenced groups. It returns observed versions for dependencies omitted from the collection. Provider capabilities and permission checks remain server responsibilities.
func ValidateReferences(ctx context.Context, frozen *Frozen, resolve ResolveReference) (map[Reference]string, error)
Package legacy¶
*Client.Config¶
Config returns the runtime configuration.
*Client.GetMonitor¶
GetMonitor returns a single monitor by entity ID.
*Client.Health¶
Health checks the /api/v1/healthz endpoint and returns nil when healthy.
*Client.History¶
func (c *Client) History(ctx context.Context, monitorID, cursor string, limit int) (*HistoryPage, error)
*Client.ListIncidents¶
ListIncidents returns the current incidents.
*Client.ListMonitors¶
ListMonitors returns a filtered, paginated list of monitors.
*Client.Metrics¶
Metrics returns the raw Prometheus text from /metrics.
*Client.Overview¶
Overview returns the fleet overview.
*Client.Pools¶
Pools returns the current worker-pool statistics, keyed by pool name (pulse, intervention, code).
*Client.PoolsHistory¶
PoolsHistory returns the rolling window of worker-pool statistics, keyed by pool name.
*Client.Queues¶
Queues returns the current queue statistics, keyed by queue name (pulse, intervention, code).
*Client.QueuesHistory¶
QueuesHistory returns the rolling window of queue statistics, keyed by queue name.
*Client.Ready¶
Ready checks admission readiness, independently of process liveness.
*Client.SLO¶
*Client.State¶
*Client.Systems¶
Systems returns the per-system and aggregate performance metrics.
*Error.Error¶
*TransportError.Error¶
*TransportError.Unwrap¶
Action¶
type Action struct {
ID string `json:"id"`
Revision string `json:"revision"`
Kind string `json:"kind"`
Color string `json:"color,omitempty"`
Endpoint int `json:"endpoint"`
Attempt int `json:"attempt"`
State ActionState `json:"state"`
NotBefore time.Time `json:"not_before"`
StartedAt time.Time `json:"started_at,omitempty"`
FinishedAt time.Time `json:"finished_at,omitempty"`
Outcome string `json:"outcome,omitempty"`
}
ActionState¶
AggregateMetrics¶
AggregateMetrics mirrors the aggregate performance metrics exposed by the API.
type AggregateMetrics struct {
StartTime time.Time `json:"start_time"`
MinUpdateDuration time.Duration `json:"min_update_duration"`
TotalEntitiesProcessed int64 `json:"total_entities_processed"`
TotalBatchesCreated int64 `json:"total_batches_created"`
TotalDuration time.Duration `json:"total_duration"`
MaxUpdateDuration time.Duration `json:"max_update_duration"`
SystemCount int `json:"system_count"`
AvgUpdateDuration time.Duration `json:"avg_update_duration"`
AvgEntitiesPerUpdate float64 `json:"avg_entities_per_update"`
AvgBatchesPerUpdate float64 `json:"avg_batches_per_update"`
EntitiesPerSecond float64 `json:"entities_per_second"`
UpdatesPerSecond float64 `json:"updates_per_second"`
TotalUpdates int64 `json:"total_updates"`
}
Client¶
Client is a typed HTTP client for the CPRA read-only API.
Config¶
Config configures a Client.
type Config struct {
AuthToken string
// BaseURL is the CPRA web server address, e.g. "http://localhost:8060".
BaseURL string
// Timeout is the per-request timeout. Defaults to 10s when <= 0.
Timeout time.Duration
}
DiskUsage¶
type DiskUsage struct {
Bytes int64 `json:"bytes"`
HistoryBytes int64 `json:"history_bytes"`
SnapshotBytes int64 `json:"snapshot_bytes"`
SnapshotFiles int `json:"snapshot_files"`
Available bool `json:"available"`
}
Error¶
Error is a non-2xx API response.
Event¶
type Event struct {
ID string `json:"id"`
MonitorID string `json:"monitor_id"`
Revision string `json:"revision"`
At time.Time `json:"at"`
Type string `json:"type"`
ActionID string `json:"action_id,omitempty"`
Kind string `json:"kind,omitempty"`
Color string `json:"color,omitempty"`
Endpoint int `json:"endpoint,omitempty"`
Outcome string `json:"outcome,omitempty"`
}
HistoryPage¶
type HistoryPage struct {
Events []Event `json:"events"`
NextCursor string `json:"next_cursor,omitempty"`
RetentionDays int `json:"retention_days"`
}
Incidents¶
Incidents is the /api/v1/incidents payload.
type Incidents struct {
Generated time.Time `json:"generated"`
Count int `json:"count"`
Incidents []MonitorSummary `json:"incidents"`
}
MonitorListOptions¶
MonitorListOptions filters and paginates the /api/v1/monitors request.
type MonitorListOptions struct {
Status string // up | down | verifying | incident | disabled
PulseType string // http | tcp | icmp | dns | udp | grpc | docker
Code string // red | yellow | green | cyan | gray
Query string // substring match on monitor name
Page int // 1-based; default 1
Size int // page size; default 50, max 500
}
MonitorSummary¶
type MonitorSummary struct {
MonitorID string `json:"monitor_id" yaml:"monitor_id"`
LatencyAvailable bool `json:"latency_available"`
UnknownActions int `json:"unknown_actions"`
Warning string `json:"warning,omitempty"`
ID uint32 `json:"id" yaml:"id"`
Name string `json:"name" yaml:"name"`
PulseType string `json:"pulse_type" yaml:"pulse_type"`
Status string `json:"status" yaml:"status"` // up | down | verifying | incident | disabled
Incident bool `json:"incident" yaml:"incident"`
PendingCode string `json:"pending_code" yaml:"pending_code"`
ConsecutiveFailures int `json:"consecutive_failures" yaml:"consecutive_failures"`
LastCheck time.Time `json:"last_check" yaml:"last_check"`
LastSuccess time.Time `json:"last_success" yaml:"last_success"`
NextCheck time.Time `json:"next_check" yaml:"next_check"`
ActiveCodes []string `json:"active_codes" yaml:"active_codes"`
// Target is a human-readable endpoint for display (URL for http, host:port for
// tcp/udp/grpc, host for icmp/dns/docker). Empty when not derivable.
Target string `json:"target"` // endpoint host/url for display
IntervalMs int64 `json:"interval_ms"` // pulse interval in ms
Uptime float64 `json:"uptime"` // rolling success ratio 0..1 over observed checks
LatencyMs float64 `json:"latency_ms"` // last observed latency ms (0 if unknown)
}
MonitorsList¶
MonitorsList is the /api/v1/monitors payload.
type MonitorsList struct {
Generated time.Time `json:"generated"`
Page int `json:"page"`
Size int `json:"size"`
Total int `json:"total"`
Filters map[string]string `json:"filters,omitempty"`
Monitors []MonitorSummary `json:"monitors"`
}
New¶
New returns a Client for the given base URL.
Overview¶
Overview is the /api/v1/overview payload.
type Overview struct {
Generated time.Time `json:"generated"`
Total int `json:"total"`
Disabled int `json:"disabled"`
ByStatus map[string]int `json:"by_status"`
ByPulseType map[string]int `json:"by_pulse_type"`
ByCode map[string]int `json:"by_code"`
UpPercent float64 `json:"up_percent"`
IndexCapped bool `json:"index_capped"`
}
Percentiles¶
type Percentiles struct {
P50 *float64 `json:"p50_ms"`
P95 *float64 `json:"p95_ms"`
P99 *float64 `json:"p99_ms"`
}
PoolStats¶
PoolStats is a named worker-pool statistics snapshot (the /api/v1/pools entry).
PoolsHistory¶
PoolsHistory is the /api/v1/pools/history payload, keyed by pool name.
QueueStats¶
QueueStats is a named queue statistics snapshot (the /api/v1/queues entry).
Queued Started Succeeded Failed Unknown Cancelled¶
const (
Queued ActionState = "queued"
Started ActionState = "started"
Succeeded ActionState = "succeeded"
Failed ActionState = "failed"
Unknown ActionState = "unknown"
Cancelled ActionState = "cancelled"
)
QueuesHistory¶
QueuesHistory is the /api/v1/queues/history payload, keyed by queue name.
Report¶
type Report struct {
Driver string `json:"driver"`
Samples uint64 `json:"samples"`
Expected uint64 `json:"expected"`
Overdue uint64 `json:"overdue"`
Pending uint64 `json:"pending"`
Timeouts uint64 `json:"timeouts"`
Missed uint64 `json:"missed"`
Queue Percentiles `json:"scheduling_queue"`
Execution Percentiles `json:"execution"`
Result Percentiles `json:"scheduled_result"`
QueueMet uint64 `json:"queue_met"`
ResultMet uint64 `json:"result_met"`
QueueAttainment *float64 `json:"queue_attainment"`
ResultAttainment *float64 `json:"result_attainment"`
Condition string `json:"condition"`
}
RuntimeConfig¶
RuntimeConfig is the /api/v1/config payload (a redacted projection of the controller configuration).
type RuntimeConfig struct {
QueueCapacity uint64 `json:"queue_capacity"`
BatchSize int `json:"batch_size"`
AlertCooldown time.Duration `json:"alert_cooldown"`
RecoveryBypass bool `json:"recovery_bypass"`
UseAdaptive bool `json:"use_adaptive_queue"`
QueueType string `json:"queue_type"`
}
SLOView¶
type SLOView struct {
Generated time.Time `json:"generated"`
WindowSeconds int `json:"window_seconds"`
QueueTargetMS float64 `json:"queue_target_ms"`
ResultTargetMS float64 `json:"result_target_ms"`
CoverageComplete bool `json:"coverage_complete"`
GapStart time.Time `json:"gap_start,omitempty"`
GapEnd time.Time `json:"gap_end,omitempty"`
Reports []Report `json:"reports"`
}
Sample¶
State¶
type State struct {
StorageUsage DiskUsage `json:"storage_usage"`
Process map[string]uint64 `json:"process"`
Storage StorageStatus `json:"storage"`
MonitorID string `json:"monitor_id,omitempty"`
Revision string `json:"revision,omitempty"`
Actions []Action `json:"actions"`
}
Stats¶
type Stats struct {
ArrivalCV float64 `json:"arrival_cv"`
ArrivalSamples int `json:"arrival_samples"`
LastEnqueue time.Time `json:"last_enqueue"`
LastDequeue time.Time `json:"last_dequeue"`
AvgQueueTime time.Duration `json:"avg_queue_time"`
Dequeued int64 `json:"dequeued"`
Dropped int64 `json:"dropped"`
MaxQueueTime time.Duration `json:"max_queue_time"`
QueueDepth int `json:"queue_depth"`
MaxJobLatency time.Duration `json:"max_job_latency"`
AvgJobLatency time.Duration `json:"avg_job_latency"`
EnqueueRate float64 `json:"enqueue_rate"`
DequeueRate float64 `json:"dequeue_rate"`
Enqueued int64 `json:"enqueued"`
Capacity int `json:"capacity"`
SampleWindow time.Duration `json:"sample_window"`
}
StorageStatus¶
type StorageStatus struct {
Mode string `json:"mode"`
Ready bool `json:"ready"`
NodeID string `json:"node_id,omitempty"`
SingleNode bool `json:"single_node"`
CommittedIndex uint64 `json:"committed_index"`
Error string `json:"error,omitempty"`
CommitLatencyMS float64 `json:"commit_latency_ms"`
SnapshotDurationMS float64 `json:"snapshot_duration_ms"`
}
SystemMetrics¶
SystemMetrics mirrors the per-system performance metrics exposed by the API.
type SystemMetrics struct {
LastUpdateTime time.Time `json:"last_update_time"`
StartTime time.Time `json:"start_time"`
SystemName string `json:"system_name"`
TotalUpdates int64 `json:"total_updates"`
TotalEntitiesProcessed int64 `json:"total_entities_processed"`
TotalBatchesCreated int64 `json:"total_batches_created"`
TotalDuration time.Duration `json:"total_duration"`
MaxUpdateDuration time.Duration `json:"max_update_duration"`
MinUpdateDuration time.Duration `json:"min_update_duration"`
}
Systems¶
Systems is the /api/v1/systems payload.
type Systems struct {
Systems map[string]SystemMetrics `json:"systems"`
Aggregate AggregateMetrics `json:"aggregate"`
}
TransportError¶
TransportError omits server URL details from printable errors while preserving cancellation.
WorkerPoolStats¶
type WorkerPoolStats struct {
SLOCondition string `json:"slo_condition"`
ServiceTime time.Duration `json:"service_time"`
ServiceCV float64 `json:"service_cv"`
ServiceSamples int `json:"service_samples"`
SizingModel string `json:"sizing_model"`
LastScaleTime time.Time `json:"last_scale_time"`
MinWorkers int `json:"min_workers"`
MaxWorkers int `json:"max_workers"`
CurrentCapacity int `json:"current_capacity"`
RunningWorkers int `json:"running_workers"`
WaitingTasks int `json:"waiting_tasks"`
TargetWorkers int `json:"target_workers"`
TasksSubmitted int64 `json:"tasks_submitted"`
TasksCompleted int64 `json:"tasks_completed"`
ScalingEvents int64 `json:"scaling_events"`
PendingResults int `json:"pending_results"`
}
Package worker¶
*Registry.Register¶
Build requirement: externaljobs.
Register associates an exact ID, version, and category with a handler. It rejects duplicates, invalid categories, and changes after Run has started.
*Runner.Close¶
Build requirement: externaljobs.
Close releases an unused or finished runner's journal. It returns ErrRunning while Run still owns handlers or protocol calls; cancel Run's context first.
*Runner.QueueLateEvidence¶
Build requirement: externaljobs.
QueueLateEvidence durably queues one append-only evidence submission for an unknown execution with a confirmed original receipt. The caller supplies a stable fresh EvidenceID and may safely retry identical evidence. It neither replaces the original result nor re-enables execution.
*Runner.Run¶
Build requirement: externaljobs.
Run stops admission on cancellation, then requests cooperative cancellation. Drain expiry is immediately visible through Status. It does not release the lock or return while a handler remains alive; process supervision is required for a hard execution deadline.
*Runner.Status¶
Build requirement: externaljobs.
Status returns current admission, handler, and journal accounting. After Run returns it reports the final retained status without reopening the journal.
Config¶
Build requirement: externaljobs.
Config requires absolute state/key paths, a private 32-byte key file outside StateDir, and the expected CPRa store/restore identity. No key is generated or replaced automatically. Use a separate state directory for each worker.
type Config struct {
Client Protocol
Registry *Registry
WorkerID string
ServerID string
StateDir string
WrappingKeyPath string
Credentials CredentialResolver
Limits Limits
DrainTimeout time.Duration
RetryInterval time.Duration
PollWait time.Duration
HeartbeatInterval time.Duration
}
CredentialResolver¶
Build requirement: externaljobs.
CredentialResolver resolves an opaque profile within the worker. Resolved values are never persisted by this library or requested from CPRa.
ErrCapacity ErrCorrupt ErrIdentity ErrRunning ErrDrainDeadline ErrClosed ErrDuplicate ErrStorage¶
Build requirement: externaljobs.
var (
ErrCapacity = errors.New("worker journal admission capacity exhausted")
ErrCorrupt = errors.New("worker journal is corrupt or cannot be decrypted")
ErrIdentity = errors.New("worker server or journal identity mismatch")
ErrRunning = errors.New("worker is already running or has run")
ErrDrainDeadline = errors.New("worker drain deadline expired; handler still active")
ErrClosed = errors.New("worker journal is closed")
ErrDuplicate = errors.New("execution already recorded")
ErrStorage = errors.New("worker journal durable write failed")
)
Handler¶
Build requirement: externaljobs.
Handler returns the server-owned outcome envelope. Execution identity, grant, and kind are filled by the runner, never taken from handler output. Errors are intentionally not serialized: they may contain provider credentials.
Job¶
Build requirement: externaljobs.
Job contains a copied assignment and worker-local credential resolution. Do not include credentials in returned diagnostics, data, or evidence.
Limits¶
Build requirement: externaljobs.
Limits bound admission before execution permission is requested. Byte counts distinguish reserved payload capacity, live encrypted-record plaintext, and the allocated bbolt file. Allocation limits do not interrupt completion writes.
type Limits struct {
Concurrency int
Records int
LiveBytes int64
OutcomeBytes int
DiagnosticBytes int
AllocatedBytes int64
}
New¶
Build requirement: externaljobs.
New validates configuration and opens the exclusively locked encrypted journal. It starts no poller and invokes no handler until Run is called.
NewRegistry¶
Build requirement: externaljobs.
NewRegistry constructs an empty registry for locally compiled handlers.
Protocol¶
Build requirement: externaljobs.
Protocol is implemented by the SDK WorkerClient. Implementations must honor context cancellation and the server's durable start/receipt contracts.
type Protocol interface {
Poll(context.Context, api.PollRequest) (*api.Assignments, error)
Start(context.Context, api.StartRequest) (*api.StartResponse, error)
Heartbeat(context.Context, api.HeartbeatRequest) (*api.HeartbeatResponse, error)
Result(context.Context, api.Outcome) (*api.Receipt, error)
LateEvidence(context.Context, api.LateEvidenceRequest) (*api.Receipt, error)
}
Registry¶
Build requirement: externaljobs.
Registry maps exact immutable JobType versions to locally compiled handlers. It becomes immutable when a Runner using it starts.
Runner¶
Build requirement: externaljobs.
Runner owns a journal and one execution slot per accepted assignment. Run is single-use. Close releases an unused runner; a running runner closes only once all handler goroutines and protocol calls have returned.
Status¶
Build requirement: externaljobs.
Status reports bounded worker activity and journal usage. Allocated bytes can exceed live bytes because removing records does not shrink the database file.