Documentation
¶
Overview ¶
Package control orchestrates administrative desired-state mutations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotDesiredStateAction identifies mutations that do not alter durable // worker or queue operational state. ErrNotDesiredStateAction = errors.New("control: action has no desired state") // ErrInvalidDesiredTarget identifies an action/resource combination that // workers cannot enforce through desired state. ErrInvalidDesiredTarget = errors.New("control: invalid desired-state target") // ErrDesiredTargetMismatch prevents a record from being reused for another // resource. ErrDesiredTargetMismatch = errors.New("control: desired-state target mismatch") // ErrDesiredTenantMismatch prevents cross-tenant state reuse. ErrDesiredTenantMismatch = errors.New("control: desired-state tenant mismatch") // ErrInvalidDesiredTransition identifies corrupt or irreversible state. ErrInvalidDesiredTransition = errors.New("control: invalid desired-state transition") // ErrDesiredRevisionExhausted prevents revision wraparound. ErrDesiredRevisionExhausted = errors.New("control: desired-state revision exhausted") )
var ( // ErrInvalidDispatcherConfiguration reports a missing dispatch boundary. ErrInvalidDispatcherConfiguration = errors.New("control: invalid dispatcher configuration") ErrDataPlaneUnavailable = errors.New("control: data plane unavailable") )
ErrCommandIDUnavailable reports failure to allocate a durable operation ID.
ErrLifecycleJournalUnavailable reports a journal that cannot durably record dispatch and acknowledgement recovery boundaries.
var ErrOutcomeUnknown = errors.New("control: command outcome unknown")
ErrOutcomeUnknown means dispatch may have occurred but its result could not be durably recorded. Clients must inspect the command before retrying.
Functions ¶
This section is empty.
Types ¶
type Authorizer ¶
type Authorizer interface {
Authorize(
context.Context,
string,
string,
controlplane.Permission,
controlplane.Target,
) error
}
Authorizer enforces actor permissions at the target-resource boundary.
type DesiredRecord ¶
type DesiredRecord struct {
TenantID string
Target controlplane.Target
State DesiredState
Revision uint64
CommandKey string
ChangedAt time.Time
}
DesiredRecord is one revisioned durable state for a queue or worker scope.
func NextDesiredState ¶
func NextDesiredState( current *DesiredRecord, command controlplane.Command, ) (DesiredRecord, error)
NextDesiredState validates and plans the next monotonic desired-state revision. It performs no persistence and sends no worker command.
type DesiredState ¶
type DesiredState string
DesiredState is the durable operational state workers converge toward.
const ( DesiredActive DesiredState = "active" DesiredPaused DesiredState = "paused" DesiredDraining DesiredState = "draining" DesiredTerminating DesiredState = "terminating" )
type DispatchOutcome ¶
type DispatchOutcome struct {
Status controlplane.CommandStatus
Failure string
WorkerID string
Protocol *controlplane.ProtocolVersion
CapabilityAvailable *bool
CompletedAt time.Time
}
DispatchOutcome is a terminal, redacted data-plane acknowledgement. It deliberately omits tenant and idempotency identity, which Service owns.
type Dispatcher ¶
type Dispatcher interface {
Dispatch(context.Context, controlplane.Command) error
}
Dispatcher sends a validated, authorized, and durably accepted command to its explicitly selected data-plane or workload adapter.
type Journal ¶
type Journal interface {
Accept(
context.Context,
controlplane.Command,
) (result controlplane.CommandResult, created bool, err error)
Complete(context.Context, controlplane.CommandResult) error
}
Journal provides durable idempotency and audit persistence. Accept must atomically persist a newly accepted command and its initial audit event. It returns the existing result with created=false for duplicate keys. Complete must atomically update the result and append its completion audit event.
type LifecycleJournal ¶
type LifecycleJournal interface {
Journal
MarkDispatched(context.Context, controlplane.CommandResult) error
MarkAcknowledged(context.Context, controlplane.CommandResult) error
}
LifecycleJournal adds durable dispatch and acknowledgement boundaries while leaving the original Journal interface source-compatible.
type ResultDispatcher ¶
type ResultDispatcher interface {
DispatchResult(context.Context, controlplane.Command) (DispatchOutcome, error)
}
ResultDispatcher reports an honest terminal data-plane acknowledgement. Legacy Dispatcher implementations remain supported for workload adapters.
type RoutingDispatcher ¶
type RoutingDispatcher struct {
// contains filtered or unexported fields
}
RoutingDispatcher keeps Kubernetes scaling separate from queue control commands.
func NewRoutingDispatcher ¶
func NewRoutingDispatcher(dataPlane Dispatcher, workloads Dispatcher) (*RoutingDispatcher, error)
NewRoutingDispatcher creates an action router with explicit boundaries.
func (*RoutingDispatcher) Dispatch ¶
func (dispatcher *RoutingDispatcher) Dispatch(ctx context.Context, command controlplane.Command) error
Dispatch routes scaling to Kubernetes and every data-plane command to its queue adapter.
func (*RoutingDispatcher) DispatchResult ¶
func (dispatcher *RoutingDispatcher) DispatchResult( ctx context.Context, command controlplane.Command, ) (DispatchOutcome, error)
DispatchResult preserves structured queue acknowledgements while assigning an orchestration completion time to legacy workload adapters.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service sequences authorization, idempotency, audit, dispatch, and outcome persistence without implementing worker or backend semantics.
func NewInstrumentedService ¶
func NewInstrumentedService( authorizer Authorizer, journal Journal, dispatcher Dispatcher, now func() time.Time, meter metric.Meter, ) (*Service, error)
NewInstrumentedService creates a service with bounded command telemetry.
func NewService ¶
func NewService( authorizer Authorizer, journal Journal, dispatcher Dispatcher, now func() time.Time, ) *Service
NewService creates a command orchestration service.
func (*Service) Execute ¶
func (s *Service) Execute( ctx context.Context, command controlplane.Command, ) (controlplane.CommandResult, error)
Execute runs an administrative mutation at most once per durable idempotency record.
type UnavailableDispatcher ¶
type UnavailableDispatcher struct{}
UnavailableDispatcher explicitly represents a disconnected data plane.
func (UnavailableDispatcher) Dispatch ¶
func (UnavailableDispatcher) Dispatch(context.Context, controlplane.Command) error
Dispatch fails closed without issuing any backend operation.
Source Files