api

package
v0.2.15 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: MIT Imports: 10 Imported by: 10

Documentation

Index

Constants

View Source 
const (
	// EventWorker is the event type for worker-level events.
	EventWorker = "WorkerEvent"

	// EventBridgeWorker is the event type for bridge worker-level events.
	EventBridgeWorker = "BridgeWorkerEvent"

	// EventFunctionWorker is the event type for function worker-level events.
	EventFunctionWorker = "FunctionWorkerEvent"

	// EventLog is the message type carrying one EventLogEntry: a fact delivered
	// from ConfigHub's event log to a subscribed worker. Its Data is an
	// EventLogEntry.
	EventLog = "EventLog"
)

SSE event types

View Source 
const BridgeHandlePrefixRegexpString = "^[A-Za-z0-9]([\\-_\\./\\:A-Za-z0-9]*[A-Za-z0-9])?"
View Source 
const BridgeOptionNamePrefixRegexpString = "^[A-Za-z0-9]([\\-_A-Za-z0-9]{0,127})?"
View Source 
const MaxActionResultMessageLength = 4096
View Source 
const MaxBridgeDescriptionLength = 1024
View Source 
const MaxBridgeHandleLength = 512

TODO: Validate these

View Source 
const MaxBridgeOptionNameLength = 128
View Source 
const MaxConfigDataLength = 64 * 1024 * 1024 // 64MB
View Source 
const MaxParametersLength = 16384

Max size of marshaled parameters

View Source 
const MaxProviderTypeLength = 128

Max length for 3P providers

Variables

View Source 
var SupportedProviders = map[ProviderType]bool{
	ProviderConfigHub:         true,
	ProviderKubernetes:        true,
	ProviderFluxOCI:           true,
	ProviderFluxRenderer:      true,
	ProviderArgoCDRenderer:    true,
	ProviderArgoCDOCI:         true,
	ProviderConfigMapRenderer: true,
	ProviderNoop:              true,
	ProviderOCI:               true,
	ProviderNone:              true,
}
View Source 
var ValidAction = map[ActionType]bool{
	ActionNA:              true,
	ActionCancel:          true,
	ActionInvokeFunctions: true,
	ActionListFunctions:   true,
}
View Source 
var ValidActionResult = map[ActionResultType]bool{
	ActionResultNone:                        true,
	ActionResultFunctionInvocationCompleted: true,
	ActionResultFunctionInvocationFailed:    true,
}
View Source 
var ValidActionStatus = map[ActionStatusType]bool{
	ActionStatusNone:        true,
	ActionStatusPending:     true,
	ActionStatusSubmitted:   true,
	ActionStatusProgressing: true,
	ActionStatusCompleted:   true,
	ActionStatusFailed:      true,
	ActionStatusCanceled:    true,
	ActionStatusAborted:     true,
}

Functions

func GenerateTargetName 

func GenerateTargetName(workerSlug string, provider ProviderType, toolchain workerapi.ToolchainType, suffix string) string

func IsSupportedProvider 

func IsSupportedProvider(provider ProviderType) bool

func IsValidDriftReconciliationMode 

func IsValidDriftReconciliationMode(mode DriftReconciliationMode) bool

func IsValidProviderType 

func IsValidProviderType(provider ProviderType) bool

func ValidateActionResultBaseMeta 

func ValidateActionResultBaseMeta(arbm *ActionResultBaseMeta) error

func ValidateActionResultData 

func ValidateActionResultData(ar *ActionResult) error

func ValidateActionResultMeta 

func ValidateActionResultMeta(ar *ActionResult) error

Types

type ActionResult 

type ActionResult struct {
	UnitID  uuid.UUID `description:"UUID of the Unit on which the action is performed"`
	SpaceID uuid.UUID `description:"UUID of the Space of the Unit on which the action is performed"`
	// OrganizationID comes from the worker
	// QueuedOperationID links this result back to the original operation request.
	QueuedOperationID uuid.UUID `description:"UUID of the operation corresponding to the action request"`
	ActionResultBaseMeta
	Data        []byte `` /* 130-byte string literal not displayed */
	LiveData    []byte `` /* 138-byte string literal not displayed */
	LiveState   []byte `` /* 130-byte string literal not displayed */
	BridgeState []byte `json:",omitempty" swaggertype:"string" format:"byte" description:"Additional state used by the Bridge"`
	// ResourceStatuses contains per-resource sync and readiness status.
	// Key format: "apiVersion/kind#namespace/name" (e.g., "apps/v1/Deployment#default/my-app")
	ResourceStatuses ResourceStatusMap `json:",omitempty" description:"Per-resource sync and readiness status"`
	// ErrorMessages contains warning or error messages to surface to the user.
	ErrorMessages []string `json:",omitempty" description:"Warning or error messages to surface to the user"`
}

ActionResult is a result of action from the Bridgeworker

type ActionResultBaseMeta 

type ActionResultBaseMeta struct {
	RevisionNum  int64
	Action       ActionType       `bun:",notnull" swaggertype:"string"`
	Result       ActionResultType `bun:",notnull,default:'None'" swaggertype:"string"`
	Status       ActionStatusType `bun:",notnull,default:'None'" swaggertype:"string"`
	Message      string           `bun:"type:text"`
	StartedAt    time.Time        `json:",omitempty" bun:"type:timestamptz"`
	TerminatedAt *time.Time       `json:",omitempty" bun:"type:timestamptz"`
}

type ActionResultType 

type ActionResultType string
const (
	ActionResultNone ActionResultType = "None"

	ActionResultFunctionInvocationCompleted ActionResultType = "FunctionInvocationCompleted"
	ActionResultFunctionInvocationFailed    ActionResultType = "FunctionInvocationFailed"
)

Drift values

type ActionStatusType 

type ActionStatusType string
const (
	ActionStatusNone        ActionStatusType = "None"
	ActionStatusPending     ActionStatusType = "Pending"
	ActionStatusSubmitted   ActionStatusType = "Submitted"
	ActionStatusProgressing ActionStatusType = "Progressing"
	ActionStatusCompleted   ActionStatusType = "Completed"
	ActionStatusFailed      ActionStatusType = "Failed"
	ActionStatusCanceled    ActionStatusType = "Canceled"
	ActionStatusAborted     ActionStatusType = "Aborted" // Operation superseded by a newer one
)

Status values

type ActionType 

type ActionType string
const (
	ActionNA     ActionType = "N/A"
	ActionCancel ActionType = "Cancel"

	// ActionApply is no longer performed — nothing applies configuration since
	// the bridge sunset. The constant remains because historical UnitActions and
	// UnitEvents carry it, and a Link that sources its data from LiveState
	// resolves against the last completed Apply. It is deliberately absent from
	// ValidAction: it can be read, not submitted.
	ActionApply ActionType = "Apply"

	ActionInvokeFunctions ActionType = "InvokeFunctions"
	ActionListFunctions   ActionType = "ListFunctions"
)

Action values

type BridgeOption 

type BridgeOption struct {
	Name        string           `description:"Name of the option in PascalCase"`
	Description string           `description:"Description of the option"`
	Required    bool             `description:"Whether the option is required"`
	DataType    funcapi.DataType `swaggertype:"string" description:"Data type of the option"`
	Example     string           `json:",omitempty" description:"Example value"`
}

BridgeOption specifies the option name, description, required vs optional, data type, and example. It is very similar to FunctionParameter and the two may be unified at some point.

type BridgeWorkerInfo 

type BridgeWorkerInfo struct {
	SupportedConfigTypes []*SupportedConfigType `json:",omitempty" description:"Configuration types of the bridges supported by the worker"`
}

type ConfigType 

type ConfigType struct {
	ProviderType  ProviderType            `swaggertype:"string" description:"Type identifying a bridge implementation supported by the worker"`
	ToolchainType workerapi.ToolchainType `swaggertype:"string" description:"Configuration toolchain and format implemented by this bridge of the worker"`
	LiveStateType workerapi.ToolchainType `` /* 172-byte string literal not displayed */
}

type ConfigTypeSignature 

type ConfigTypeSignature struct {
	ConfigType
	Options []BridgeOption `json:",omitempty" description:"Supported bridge options"`
}

type DriftReconciliationMode 

type DriftReconciliationMode string
const (
	DriftReconciliationModeOnDemand          DriftReconciliationMode = "OnDemand"
	DriftReconciliationModeContinuousApply   DriftReconciliationMode = "ContinuousApply"
	DriftReconciliationModeContinuousRefresh DriftReconciliationMode = "ContinuousRefresh"
)

type EventLogEntry added in v0.1.95 

type EventLogEntry struct {
	// CursorID is this event's monotonic position in the log. A consumer that
	// has handled through here resumes after it.
	CursorID int64 `description:"Monotonic cursor of this event in the log."`

	// EventType is the fact's type, for example "release.published".
	EventType string `description:"The event type."`

	// SubjectEntityType is the entity type the event is about, for example
	// "Unit" or "Release".
	SubjectEntityType string `description:"Entity type the event is about."`

	// SubjectEntityID is the id of the entity the event is about.
	SubjectEntityID uuid.UUID `description:"Id of the entity the event is about."`

	// SpaceID is the event's Space scope, if any (UUID string).
	SpaceID string `json:",omitempty" description:"Space scope, if any."`

	// TargetID is the event's Target scope, if any (UUID string).
	TargetID string `json:",omitempty" description:"Target scope, if any."`

	// Payload is the event-type-specific data, opaque to the transport.
	Payload json.RawMessage `json:",omitempty" description:"Event-type-specific payload."`

	// CreatedAt is when the event was emitted.
	CreatedAt time.Time `description:"When the event was emitted."`

	// SubscriptionName is the subscription this event was delivered for.
	SubscriptionName string `description:"The subscription this event was delivered for."`
}

EventLogEntry is one delivered event: a fact from ConfigHub's event log, addressed to no one. It is the Data of an EventMessage whose Event is api.EventLog. A bot reacts to it however it likes; the reaction is the bot's own business and never came from ConfigHub.

type EventMessage 

type EventMessage struct {
	Event string
	Data  interface{}
}

type EventSubscription added in v0.1.95 

type EventSubscription struct {
	// Name is the stable per-worker subscription name. The server keys the
	// delivery cursor on it, so it must be identical across reconnects for
	// resume to work. A worker with a single subscription uses a constant.
	Name string `` /* 136-byte string literal not displayed */

	// EventTypes are the event types to receive, for example
	// "release.published". Empty means every type.
	EventTypes []string `json:",omitempty" description:"Event types to receive, e.g. \"release.published\". Empty means every type."`

	// SpaceID optionally scopes delivery to one Space (UUID string). Empty means
	// any Space.
	SpaceID string `json:",omitempty" description:"Optional Space scoping filter (UUID). Empty means any Space."`

	// TargetID optionally scopes delivery to one Target (UUID string). Empty
	// means any Target.
	TargetID string `json:",omitempty" description:"Optional Target scoping filter (UUID). Empty means any Target."`

	// FromCursor optionally overrides where delivery begins. When set, delivery
	// starts after this cursor; when unset, delivery resumes from the
	// server-stored bookmark, or from the log tail on a first-ever connect.
	FromCursor *int64 `` /* 173-byte string literal not displayed */
}

EventSubscription is a worker's standing request to receive facts from ConfigHub's event log over the long-poll connection. The worker declares its subscriptions in WorkerInfo at connect time; the server matches the log's scoping columns against the filter and pushes matching events down the same connection it already holds open.

A subscription is a filter, not a queue: ConfigHub keeps no per-message delivery state. It keeps one cursor per (worker, Name) — the bookmark — so a restarted worker resumes where it left off instead of replaying the log or skipping to the present.

type FunctionWorkerEventRequest 

type FunctionWorkerEventRequest struct {
	// Action defines the operation the function worker should perform.
	Action ActionType `description:"Action defines the operation the function worker should perform."`

	// Payload contains the data required for the action, primarily the function invocation details.
	Payload FunctionWorkerPayload `description:"Payload contains the data required for the action, primarily the function invocation details."`
}

FunctionWorkerEventRequest encapsulates a request destined for the function worker plugin. It specifies the action to be performed and includes the necessary payload.

type FunctionWorkerInfo 

type FunctionWorkerInfo struct {
	ToolchainTypes     []workerapi.ToolchainType                                        `description:"Supported ToolchainTypes"`
	SupportedFunctions map[workerapi.ToolchainType]map[string]funcApi.FunctionSignature `description:"Signatures of supported functions by ToolchainType"`
}

FunctionWorkerInfo is a data-only struct for wire serialization of function worker capabilities. It is generated by FunctionExecutor.Info() or built directly from a signature registry.

type FunctionWorkerPayload 

type FunctionWorkerPayload struct {
	// QueuedOperationID is the identifier of the original queued operation request.
	QueuedOperationID uuid.UUID `description:"QueuedOperationID is the identifier of the original queued operation request."`

	// InvocationRequest encapsulates the full request for invoking one or more functions,
	// including context, configuration data, function calls, and execution options.
	// This structure is defined in the functions plugin's API package.
	InvocationRequest funcApi.FunctionInvocationRequest `` /* 175-byte string literal not displayed */
}

FunctionWorkerPayload holds the specific data for a function worker request.

type ProviderType 

type ProviderType string
const (
	ProviderConfigHub         ProviderType = "ConfigHub"
	ProviderKubernetes        ProviderType = "Kubernetes"
	ProviderFluxOCI           ProviderType = "FluxOCI"
	ProviderFluxRenderer      ProviderType = "FluxRenderer"
	ProviderArgoCDRenderer    ProviderType = "ArgoCDRenderer"
	ProviderArgoCDOCI         ProviderType = "ArgoCDOCI"
	ProviderConfigMapRenderer ProviderType = "ConfigMapRenderer"
	ProviderNoop              ProviderType = "Noop"
	// ProviderOCI publishes Unit data verbatim to an OCI repository for a puller
	// (e.g. Argo/Flux) to consume. Like Noop it performs no remote apply; the
	// Target is the OCI repo and the worker is only a required placeholder. It
	// does not route by toolchain, so its bridge advertises ToolchainAny.
	ProviderOCI ProviderType = "OCI"
	// ProviderNone is used to express the Unit is not in use in a Release
	// or to be applied
	ProviderNone ProviderType = "None"
)

ProviderType identifies a bridge implementation, including the API, authentication method, behavior, etc. It is used by the worker's dispatcher to route to the selected bridge.

type ResourceInfo 

type ResourceInfo struct {
	ResourceName string `` /* 206-byte string literal not displayed */
	ResourceType string `` /* 214-byte string literal not displayed */
}

TODO unify this API with the function API package. This struct is redundant with that of function API.

type ResourceReadinessType 

type ResourceReadinessType string

ResourceReadinessType represents the readiness status of an individual resource. Readiness status is derived from kstatus polling and indicates whether the resource has reached a ready/healthy state in the target system. 

const (
	// ResourceReadinessReady indicates the resource is ready/healthy
	ResourceReadinessReady ResourceReadinessType = "Ready"
	// ResourceReadinessInProgress indicates the resource is progressing towards ready state
	ResourceReadinessInProgress ResourceReadinessType = "InProgress"
	// ResourceReadinessStuck indicates the resource has been InProgress without
	// observed progress for longer than the staleness threshold. Its controller
	// may be suspended, missing, broken, or backpressured. The resource is not
	// failed; if progress resumes it transitions back to InProgress.
	ResourceReadinessStuck ResourceReadinessType = "Stuck"
	// ResourceReadinessFailed indicates the resource failed to reach ready state
	ResourceReadinessFailed ResourceReadinessType = "Failed"
	// ResourceReadinessTerminating indicates the resource is being deleted
	ResourceReadinessTerminating ResourceReadinessType = "Terminating"
	// ResourceReadinessUnknown indicates the resource readiness cannot be determined
	ResourceReadinessUnknown ResourceReadinessType = "Unknown"
)

type ResourceStatus 

type ResourceStatus struct {
	// SyncStatus indicates whether config was pushed to the target
	SyncStatus ResourceSyncStatusType `json:",omitempty" description:"Whether config was pushed to the target (Synced or NotSynced)"`
	// Readiness indicates the health/ready state from kstatus
	Readiness ResourceReadinessType `json:",omitempty" description:"Health state from kstatus (Ready, InProgress, Failed, Unknown)"`
	// Message provides human-readable status details
	Message string `json:",omitempty" description:"Human-readable status details or error message"`
	// UpdatedAt is the timestamp when this resource status was last updated
	UpdatedAt time.Time `json:",omitempty" description:"Timestamp when this resource status was last updated"`
}

ResourceStatus represents the sync and readiness status of a single resource. It tracks both whether configuration was pushed (SyncStatus) and whether the resource has become healthy/ready (Readiness), along with a timestamp for tracking progress duration.

type ResourceStatusMap 

type ResourceStatusMap map[funcApi.ResourceTypeAndName]ResourceStatus

ResourceStatusMap maps ResourceTypeAndName to ResourceStatus. Key format: "apiVersion/kind#namespace/name" following K8sResourceProviderType conventions Examples: "apps/v1/Deployment#default/my-app", "v1/ConfigMap#/my-config" This format includes namespace to distinguish resources with the same name in different namespaces.

type ResourceSyncStatusType 

type ResourceSyncStatusType string

ResourceSyncStatusType represents the sync status of an individual resource. Sync status indicates whether the configuration has been pushed to the target. 

const (
	// ResourceSyncStatusSynced indicates the config was successfully pushed to the target
	ResourceSyncStatusSynced ResourceSyncStatusType = "Synced"
	// ResourceSyncStatusPending indicates the resource is waiting to be synced
	ResourceSyncStatusPending ResourceSyncStatusType = "Pending"
	// ResourceSyncStatusFailed indicates the sync operation failed
	ResourceSyncStatusFailed ResourceSyncStatusType = "Failed"
)

type SupportedConfigType 

type SupportedConfigType struct {
	ConfigTypeSignature
	CompatibleBridge ProviderType `json:",omitempty" description:"Bridge with compatible BridgeHandles"`
	AvailableTargets []Target     `json:",omitempty" description:"Targets known by the BridgeWorker. Optional."`
}

func (*SupportedConfigType) ScrubAvailableTargets 

func (sct *SupportedConfigType) ScrubAvailableTargets()

ScrubAvailableTargets prepares AvailableTargets for storage by keeping only targets that have a BridgeHandle and clearing their Name and Params fields. Targets without a BridgeHandle are removed entirely.

func (*SupportedConfigType) Validate 

func (sct *SupportedConfigType) Validate() error

type Target 

type Target struct {
	BridgeHandle string                 `` /* 127-byte string literal not displayed */
	Name         string                 `json:",omitempty" description:"Used to set the Slug and DisplayName of the Target created in ConfigHub. Optional."`
	Params       map[string]interface{} `json:",omitempty" description:"Deprecated. Used to set the Parameters of the Target created in ConfigHub"`
}

type WorkerEventRequest 

type WorkerEventRequest struct {
	Action  ActionType `description:"The action requested"`
	Payload WorkerPayload
}

type WorkerInfo 

type WorkerInfo struct {
	IsServerWorker     bool               `json:",omitempty" description:"If true, this is a server-hosted worker."`
	UseUserIdentity    bool               `` /* 179-byte string literal not displayed */
	BridgeWorkerInfo   BridgeWorkerInfo   `description:"BridgeWorker capabilities"`
	FunctionWorkerInfo FunctionWorkerInfo `description:"FunctionWorker capabilities"`
}

type WorkerPayload 

type WorkerPayload struct {
	Timestamp int64 `description:"Time the action was requested"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.