management

type Capability string

type Classification string

type Command struct {
	// ID correlates one command and its returned result.
	ID string
	// IdempotencyKey selects provider-owned duplicate handling; shape validation supplies no durable deduplication.
	IdempotencyKey string
	// Actor is a caller assertion; authenticate it outside this envelope.
	Actor string
	// Reason is required bounded operator text, not automatically redacted.
	Reason string
	// Protocol is the management protocol version; zero is unknown or invalid.
	Protocol ProtocolVersion
	// Action selects the requested management operation.
	Action CommandAction
	// Target scopes the operation to one logical resource.
	Target Target
	// RequestedAt is the nonzero caller request time.
	RequestedAt time.Time
	// Deadline must follow RequestedAt; Validate does not compare it with the current clock.
	Deadline time.Time
	// Confirmed is required for purge, bulk retry and replay; it is not an access credential.
	Confirmed bool
	// Selection is retained mutable bulk selection; do not change it while a command is in use.
	Selection *Selection
	// Replay is retained mutable replay configuration; providers may retain it for deduplication.
	Replay *ReplayOptions
}

type CommandAction string

type CommandResult struct {
	// CommandID echoes the command identity.
	CommandID string
	// IdempotencyKey echoes the duplicate-operation key.
	IdempotencyKey string
	// WorkerID identifies the reporting worker or aggregate.
	WorkerID string
	// Protocol is the management protocol version; zero is unknown or invalid.
	Protocol ProtocolVersion
	// Status distinguishes acknowledged, rejected, partial and unknown outcomes.
	Status CommandResultStatus
	// FailureCode is an operational failure label, not arbitrary error text.
	FailureCode string
	// CompletedAt is the nonzero reporting time, not proof of durable handler completion.
	CompletedAt time.Time
}

type CommandResultStatus string

type Compatibility struct {
	// State classifies version compatibility, independently of authentication.
	State CompatibilityState
	// Enabled is a sorted, deduplicated intersection only for compatible peers.
	Enabled []Capability
	// WorkerOnly contains sorted worker-only capability claims.
	WorkerOnly []Capability
	// ControlPlaneOnly contains sorted control-plane-only capability claims.
	ControlPlaneOnly []Capability
}

type CompatibilityState string

type Controller interface {
	// Execute applies a command under provider-owned deduplication/outcome rules.
	// Authorization remains caller-owned.
	Execute(context.Context, Command) (CommandResult, error)
}

type DesiredRecord struct {
	// Target scopes the operation to one logical resource.
	Target Target
	// State is the reported or requested lifecycle state, not transport connectivity proof.
	State DesiredState
	// Revision is a positive target-local revision; regressions are rejected by the reconciler.
	Revision uint64
	// ChangedAt is the nonzero authored time, not an ordering substitute for Revision.
	ChangedAt time.Time
	// CommandID attributes the desired revision to a bounded command identity.
	CommandID string
}

type DesiredState string

type DesiredStateApplier interface {
	// ApplyDesiredState applies a revision; a returned error need not undo effects already applied.
	ApplyDesiredState(context.Context, DesiredRecord) error
}

type DesiredStateReader interface {
	// GetDesiredState returns target-scoped authoritative state or ErrDesiredStateNotFound.
	GetDesiredState(context.Context, Target) (DesiredRecord, error)
}

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

type DesiredStateReconcilerConfig struct {
	// Reader is a borrowed authoritative provider called under the reconciler mutex.
	Reader DesiredStateReader
	// Applier is a borrowed synchronous callback called under the reconciler mutex.
	Applier DesiredStateApplier
	// Targets is copied at construction and applied in configured order; duplicates are rejected.
	Targets []Target
}

type DrainState string

type Failure struct {
	// Classification selects backend failure disposition; it does not redact the cause.
	Classification Classification
	// Code is caller-supplied failure text; keep it stable and non-sensitive.
	Code string
	// contains filtered or unexported fields
}

type FailureResolution struct {
	// Classification selects backend failure disposition; it does not redact the cause.
	Classification Classification
	// Code is the selected winning-classification code, or empty when absent.
	Code string
}

type InspectRequest struct {
	// Kind selects the supported resource or record category.
	Kind RecordKind
	// ID is the provider-owned identity, not an authenticated credential.
	ID string
	// Visibility selects disclosure; hidden is the zero value, not an authorization check.
	Visibility PayloadVisibility
}

type JobRecord struct {
	// Kind selects the supported resource or record category.
	Kind RecordKind
	// ID identifies this backend failure/dead-letter record, separately from OriginalID.
	ID string
	// Backend identifies the reporting transport, not its address or credentials.
	Backend string
	// Queue identifies the logical queue, not a connection URI.
	Queue string
	// OccurredAt is the backend/event time of this observation, not a universal ordering clock.
	OccurredAt time.Time
	// Attempts counts backend delivery attempts, independently of local handler retries.
	Attempts uint32
	// FailureCode is an operational failure label, not arbitrary error text.
	FailureCode string
	// Payload holds disclosure-controlled mutable application bytes.
	Payload Payload

	// EnvelopeVersion is zero for basic legacy records or CurrentEnvelopeVersion for extended metadata.
	EnvelopeVersion uint16
	// PayloadSchemaVersion is optional application schema identity; this package does not validate that schema.
	PayloadSchemaVersion string
	// OriginalID is optional application identity, distinct from backend source identity.
	OriginalID string
	// Topic is optional source topic identity.
	Topic string
	// Stream is the logical stream key, not a transport endpoint.
	Stream string
	// RoutingKey is optional source routing identity.
	RoutingKey string
	// ConsumerGroup is optional source consumer-group identity.
	ConsumerGroup string
	// SourceRecordID identifies the original backend source entry when known.
	SourceRecordID string
	// EnqueuedAt is an optional nonzero enqueue time; nil means unknown.
	EnqueuedAt *time.Time
	// FirstDeliveryAt is optional first-delivery time; nil means unknown.
	FirstDeliveryAt *time.Time
	// LastDeliveryAt is optional last-delivery time, ordered after FirstDeliveryAt when both known.
	LastDeliveryAt *time.Time
	// DeadLetteredAt is required for a versioned terminal record.
	DeadLetteredAt *time.Time
	// RetryPolicy is optional application policy identity, not executable retry configuration.
	RetryPolicy string
	// Classification selects the recorded backend-neutral failure disposition.
	Classification Classification
	// FailureSummary is deliberately safe operator text; Validate bounds but does not redact it.
	FailureSummary string
	// Diagnostics uses independent disclosure bounds; it must not expose bytes implicitly.
	Diagnostics Payload
	// HandlerType is an optional handler label, not serialized code.
	HandlerType string
	// JobType is optional application job identity.
	JobType string
	// Tags contains mutable application dimensions with bounded keys, values and count.
	Tags map[string]string
	// TraceID is optional caller-supplied trace identity, not authenticated evidence.
	TraceID string
	// TenantID is optional caller-supplied tenancy metadata, not access enforcement.
	TenantID string
	// ProducerVersion identifies the producer application when known.
	ProducerVersion string
	// WorkerVersion identifies the handling application when known.
	WorkerVersion string
	// OriginalDeadLetterID identifies the first terminal record in replay lineage.
	OriginalDeadLetterID string
	// PriorDeadLetterID identifies the terminal record immediately preceding this replay.
	PriorDeadLetterID string
	// ReplayGeneration is positive only with complete original/prior lineage; zero means no replay metadata.
	ReplayGeneration uint32
	// RetentionDeadline is optional nonzero expiry, later than DeadLetteredAt when both known.
	RetentionDeadline *time.Time
}

type Measurement[T any] struct {
	// Value is meaningful only when Supported is true.
	Value T
	// Supported distinguishes an actual measured zero from an unavailable value.
	Supported bool
}

type PageRequest struct {
	// Cursor is provider-specific pagination state; empty begins traversal.
	Cursor string
	// Limit is the positive requested item ceiling, checked against the applicable limit.
	Limit uint32
	// Search is bounded provider-defined metadata search, not payload search.
	Search string
	// Sort selects requested ordering; a provider may reject unsupported fields.
	Sort SortField
	// Direction selects ascending or descending traversal.
	Direction SortDirection
}

type Payload struct {
	// Visibility selects disclosure; hidden is the zero value, not an authorization check.
	Visibility PayloadVisibility
	// ContentType is an optional application media-type label, not verified payload content.
	ContentType string
	// Size reports original byte size and may exceed revealed Data length.
	Size int64
	// Data is mutable; value copies share its backing array. Validation permits
	// bytes only when revealed.
	Data []byte
}

type PayloadVisibility string

type ProtocolRange struct {
	// Minimum is the inclusive lower supported version.
	Minimum ProtocolVersion
	// Maximum is the inclusive upper supported version; reversed ranges negotiate unknown.
	Maximum ProtocolVersion
}

type ProtocolVersion struct {
	// Major orders versions before Minor.
	Major uint16
	// Minor orders versions within one Major.
	Minor uint16
}

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

type QueueMetrics struct {
	// Depth reports outstanding work under the provider's scope; stream backends
	// combine pending and known lag.
	Depth Measurement[int64]
	// Lag counts undelivered group entries when supported; unknown lag uses
	// Supported=false rather than a supported negative value.
	Lag Measurement[int64]
	// Pending counts entries delivered to the consumer group but not acknowledged.
	Pending Measurement[int64]
	// OldestAge reports age of the backend's oldest supported outstanding entry.
	OldestAge Measurement[time.Duration]
	// Throughput is a finite nonnegative backend-reported rate when supported.
	Throughput Measurement[float64]
	// Runtime reports backend-measured elapsed runtime when supported.
	Runtime Measurement[time.Duration]
	// Succeeded counts backend-observed success under that provider's scope.
	Succeeded Measurement[uint64]
	// Failed counts backend-observed failures under that provider's scope.
	Failed Measurement[uint64]
	// Retried counts backend-observed retry deliveries, not necessarily local handler attempts.
	Retried Measurement[uint64]
	// Reclaimed counts recovered pending entries under the provider's scope.
	Reclaimed Measurement[uint64]
	// DeadLettered counts terminal transfers under the provider's scope.
	DeadLettered Measurement[uint64]
	// SettlementErrors counts failed backend settlement operations under the provider's scope.
	SettlementErrors Measurement[uint64]
}

type QueueStatus struct {
	// Backend identifies the reporting transport, not its address or credentials.
	Backend string
	// Queue identifies the logical queue, not a connection URI.
	Queue string
	// ObservedAt is the nonzero report time.
	ObservedAt time.Time
	// Metrics retains support flags instead of inventing unsupported measurements.
	Metrics QueueMetrics
}

type QueueStatusPage struct {
	// Items contains this page's records; slice storage is mutable and not copied by validation.
	Items []QueueStatus
	// NextCursor is provider-specific continuation state; empty finishes traversal.
	NextCursor string
}

type QueueStatusProvider interface {
	// ObserveQueue reports native queue support flags and values, not invented metrics.
	ObserveQueue(context.Context) (QueueStatus, error)
}

type RecordKind string

type RecordPage struct {
	// Items contains this page's records; slice storage is mutable and not copied by validation.
	Items []JobRecord
	// NextCursor is provider-specific continuation state; empty finishes traversal.
	NextCursor string
}

type RecordReader interface {
	// ListFailures lists bounded metadata with payload and diagnostics hidden.
	ListFailures(context.Context, PageRequest) (RecordPage, error)
	// ListDeadLetters lists bounded terminal metadata with payload and diagnostics hidden.
	ListDeadLetters(context.Context, PageRequest) (RecordPage, error)
	// Inspect returns one record with no more disclosure than requested; authorization is caller-owned.
	Inspect(context.Context, InspectRequest) (JobRecord, error)
}

type ReplayOptions struct {
	// Destination must identify an explicitly allowed logical queue/stream.
	Destination string
	// IdempotencyPolicy selects replacement or rejection within the backend's retention/window semantics.
	IdempotencyPolicy ReplayPolicy
}

type ReplayPolicy string

type Selection struct {
	// Limit is the positive requested item ceiling, checked against the applicable limit.
	Limit uint32
}

type SortDirection string

type SortField string

type StatusMetadata struct {
	// ID is the provider-owned identity, not an authenticated credential.
	ID string
	// Version is the reporter/application version label, not protocol negotiation.
	Version string
	// Concurrency is configured reporting concurrency, from one to MaxWorkerConcurrency.
	Concurrency uint32
	// Protocol is the management protocol version; zero is unknown or invalid.
	Protocol ProtocolVersion
}

type StatusPageRequest struct {
	// Cursor is provider-specific pagination state; empty begins traversal.
	Cursor string
	// Limit is the positive requested item ceiling, checked against the applicable limit.
	Limit uint32
}

type StatusProvider interface {
	WorkerStatusProvider
	QueueStatusProvider
}

type StatusReader interface {
	// ListWorkers returns a bounded page under provider-owned cursor/snapshot semantics.
	ListWorkers(context.Context, StatusPageRequest) (WorkerStatusPage, error)
	// ListQueues returns a bounded page under provider-owned cursor/snapshot semantics.
	ListQueues(context.Context, StatusPageRequest) (QueueStatusPage, error)
}

type StatusReaderConfig struct {
	// Workers contains borrowed providers; construction copies the slice, not providers.
	Workers []WorkerStatusProvider
	// Queues contains borrowed providers; construction copies the slice, not providers.
	Queues []QueueStatusProvider
}

type Target struct {
	// Kind selects the supported resource or record category.
	Kind TargetKind
	// Name is the logical target identity, bounded by MaxIdentityBytes.
	Name string
}

type TargetKind string

type ValidationError struct {
	// Field identifies a validation field; caller construction must keep the label safe.
	Field string
	// Problem describes the rejected shape; caller construction controls its disclosure.
	Problem string
}

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

type WorkerLifecycleConfig struct {
	// Metadata identifies the worker/protocol/concurrency scope.
	Metadata StatusMetadata
	// WorkerGroup identifies the permitted group target.
	WorkerGroup string
	// Queue identifies the permitted queue target.
	Queue string
	// MaxCommandResults bounds retained command entries in [1, MaxLifecycleCommandResults]; no entries are evicted.
	MaxCommandResults int
	// Now is a required borrowed clock callback; it must return meaningful times and not reenter locked operations.
	Now func() time.Time
}

type WorkerLifecycleSnapshot struct {
	// State presents the local admission state.
	State WorkerState
	// DrainStatus presents admissions/jobs completion or timeout, not backend connectivity.
	DrainStatus DrainState
	// CurrentJobs counts promoted work wrappers still awaiting EndJob.
	CurrentJobs uint32
	// Terminating marks the irreversible terminating state.
	Terminating bool
}

type WorkerState string

type WorkerStatus struct {
	// ID identifies this worker report, bounded by MaxIdentityBytes.
	ID string
	// Version is the reporter/application version label, not protocol negotiation.
	Version string
	// StartedAt is the required nonzero process start time.
	StartedAt time.Time
	// HeartbeatAt is the report time and must not precede StartedAt.
	HeartbeatAt time.Time
	// Queues contains mutable logical queue labels, at most MaxQueuesPerWorker.
	Queues []string
	// Concurrency reports configured concurrency, from one to MaxWorkerConcurrency.
	Concurrency uint32
	// State is the reported or requested lifecycle state, not transport connectivity proof.
	State WorkerState
	// CurrentJobs must not exceed Concurrency in a valid report.
	CurrentJobs uint32
	// DrainStatus describes requested drain progress.
	DrainStatus DrainState
	// Backend identifies the reporting transport, not its address or credentials.
	Backend string
	// Protocol is the management protocol version; zero is unknown or invalid.
	Protocol ProtocolVersion
	// Capabilities contains mutable bounded capability claims, not authorization grants.
	Capabilities []Capability
}

type WorkerStatusPage struct {
	// Items contains this page's records; slice storage is mutable and not copied by validation.
	Items []WorkerStatus
	// NextCursor is provider-specific continuation state; empty finishes traversal.
	NextCursor string
}

type WorkerStatusProvider interface {
	// ObserveWorker reports native worker state; the provider owns context handling and concurrency.
	ObserveWorker(context.Context) (WorkerStatus, error)
}