apihttp

type AuditEntry struct {
	// Sequence is the stored chain position.
	Sequence uint64 `json:"sequence"`
	// HashVersion selects the package digest encoding; it is not a signature
	// algorithm identifier.
	HashVersion uint16 `json:"hash_version"`
	// OccurredAt is the stored audit occurrence time.
	OccurredAt time.Time `json:"occurred_at"`
	// IdempotencyKey links command events; privileged read audits may leave it
	// empty.
	IdempotencyKey string `json:"idempotency_key"`
	// CommandID links the attributed operation or privileged-access record.
	CommandID string `json:"command_id"`
	// Actor is stored actor attribution, not a new authentication decision.
	Actor string `json:"actor"`
	// Action is the stored operation or sensitive-access permission.
	Action string `json:"action"`
	// Target is the stored resource description; tenant scope is provided by
	// the route.
	Target string `json:"target"`
	// Result is the stored public outcome.
	Result string `json:"result"`
	// PreviousHash is lowercase hexadecimal chain-link data, not a trusted
	// anchor by itself.
	PreviousHash string `json:"previous_hash"`
	// Hash is lowercase hexadecimal unkeyed SHA-256 digest data.
	Hash string `json:"hash"`
}

type AuditPage struct {
	// Entries is the sequence-ordered public page; HTTP projection does not
	// independently authenticate its anchor.
	Entries []AuditEntry `json:"entries"`
	// NextSequence is the exclusive next-page cursor; zero means no additional
	// page was detected.
	NextSequence uint64 `json:"next_sequence,omitempty"`
}

type AuditSource interface {
	// ListTenant returns a bounded ordered tenant audit page after the
	// exclusive sequence cursor; source integrity checking remains provider-owned.
	ListTenant(context.Context, string, uint64, uint32) (controlpostgres.AuditPage, error)
}

type BuildInfo struct {
	// Version is configured public version text, not a verified release
	// attestation.
	Version string `json:"version"`
	// Commit is configured public source identity text.
	Commit string `json:"commit"`
	// BuiltAt is normalized to UTC when the handler is constructed.
	BuiltAt time.Time `json:"built_at"`
}

type CommandExecutor interface {
	// Execute must validate, authorize and durably admit the scoped command;
	// errors can coexist with committed or partial external work.
	Execute(context.Context, controlplane.Command) (controlplane.CommandResult, error)
}

type CommandHistoryEntry struct {
	// CommandID is the stored operation identity, separate from its idempotency
	// key.
	CommandID string `json:"command_id"`
	// IdempotencyKey is the tenant-scoped journal duplicate/conflict key.
	IdempotencyKey string `json:"idempotency_key"`
	// Actor is the authenticated attribution originally recorded, not body-selected identity.
	Actor string `json:"actor"`
	// AuthenticationMethod is recorded ingress method attribution.
	AuthenticationMethod string `json:"authentication_method"`
	// Reason is stored administrative audit text; callers must exclude
	// sensitive values.
	Reason string `json:"reason"`
	// Action is the originally admitted operation.
	Action controlplane.Action `json:"action"`
	// Capability is recorded operation capability attribution, not a grant.
	Capability string `json:"capability"`
	// Target is the originally admitted resource.
	Target TargetRequest `json:"target"`
	// RequestedAt is the stored request time used in newest-first ordering.
	RequestedAt time.Time `json:"requested_at"`
	// Deadline is the stored bounded enforcement deadline.
	Deadline time.Time `json:"deadline"`
	// Confirmed records the submitted destructive-operation confirmation.
	Confirmed bool `json:"confirmed"`
	// Selection is an independently projected optional bulk bound.
	Selection *SelectionRequest `json:"selection,omitempty"`
	// Replay is an independently projected optional replay destination/policy.
	Replay *ReplayRequest `json:"replay,omitempty"`
	// Scale is an independently projected optional replica request.
	Scale *ScaleRequest `json:"scale,omitempty"`
	// Result is the stored outcome; HTTP projection borrows its optional fields
	// until synchronous encoding.
	Result controlplane.CommandResult `json:"result"`
}

type CommandHistoryPage struct {
	// Commands is a newly projected newest-first page; source providers own
	// size and content validity.
	Commands []CommandHistoryEntry `json:"commands"`
	// NextCursor is opaque pagination state; empty means no additional page was
	// detected.
	NextCursor string `json:"next_cursor,omitempty"`
}

type CommandRequest struct {
	// IdempotencyKey is required scoped duplicate/conflict identity; actor and
	// tenant come from trusted ingress, not this body.
	IdempotencyKey string `json:"idempotency_key"`
	// Reason is required bounded audit text; callers must omit credentials and
	// sensitive payloads.
	Reason string `json:"reason"`
	// Action selects the requested supported administrative mutation.
	Action controlplane.Action `json:"action"`
	// Target identifies the action-compatible resource without backend
	// addressing.
	Target TargetRequest `json:"target"`
	// RequestedAt is required caller time anchoring the enforcement window, not
	// the server receipt time.
	RequestedAt time.Time `json:"requested_at"`
	// Confirmed is required for destructive bulk/purge/replay and scale-to-zero
	// operations.
	Confirmed bool `json:"confirmed"`
	// Selection is required for bulk retry and is copied into the domain
	// command.
	Selection *SelectionRequest `json:"selection,omitempty"`
	// Replay is required for replay with explicit destination and duplicate
	// policy.
	Replay *ReplayRequest `json:"replay,omitempty"`
	// Scale is required for scaling, including an explicit zero replica count.
	Scale *ScaleRequest `json:"scale,omitempty"`
}

type CommandResultSource interface {
	// Get returns the durable outcome for the tenant/idempotency key;
	// implementations own validation and diagnostic safety.
	Get(context.Context, string, string) (controlplane.CommandResult, error)
}

type Config struct {
	// Commands is the required borrowed mutation executor; the handler does not
	// own its shutdown.
	Commands CommandExecutor
	// MaxRequestBytes bounds JSON mutation input through MaxBytesReader; zero
	// selects 1 MiB and negative values fail.
	MaxRequestBytes int64
	// Readiness is optional borrowed dependency health checking; nil reports
	// ready without checking external services.
	Readiness Readiness
	// Build is copied public startup metadata; it is not cryptographically
	// authenticated.
	Build BuildInfo
	// Capabilities is copied public capability text; advertisement does not
	// grant permission.
	Capabilities []string
	// Workers is optional synchronous fleet state, mutually exclusive with
	// RemoteWorkers; read sources require Viewer.
	Workers WorkerSource
	// RemoteWorkers is optional cancellable remote fleet state, mutually
	// exclusive with Workers.
	RemoteWorkers RemoteWorkerSource
	// Workloads is optional borrowed workload visibility; the source owns
	// provider scope and page bounds.
	Workloads WorkloadSource
	// Viewer is required exactly when ordinary read sources are configured; it
	// must authorize before source access.
	Viewer Viewer
	// Now supplies fleet/sensitive-audit observation time; nil selects time.Now
	// and the callback remains borrowed.
	Now func() time.Time
	// NewCommandID supplies privileged-access audit identities; nil selects
	// controlplane.NewCommandID. Commands are identified by their executor.
	NewCommandID func() (string, error)
	// WorkflowLimiter optionally admits subject/action and sensitive-read
	// workflows synchronously; nil disables this layer.
	WorkflowLimiter RateLimiter
	// StaleAfter is the fleet staleness duration; zero selects thirty seconds
	// and negative values fail.
	StaleAfter time.Duration
	// Protocol selects the advertised inclusive control-plane version range
	// used for negotiation.
	Protocol fleet.ProtocolRange
	// WorkerCapabilities is copied negotiation input, not worker authentication
	// or authorization.
	WorkerCapabilities []fleet.Capability
	// Telemetry optionally supplies borrowed HTTP instrumentation providers;
	// the handler does not shut them down.
	Telemetry *TelemetryConfig
	// Audit is an optional borrowed tenant audit-history source.
	Audit AuditSource
	// SensitiveAudit is required before revealed payload/diagnostic access; nil
	// causes audit_unavailable, not unaudited disclosure.
	SensitiveAudit SensitiveAccessAuditor
	// CommandResults is optional durable lookup; implementations also exposing
	// ListTenant enable command-history pagination.
	CommandResults CommandResultSource
	// Records is optional scoped failure/dead-letter reading; implementations
	// must preserve bounds and disclosure contracts.
	Records RecordSource
	// Queues is optional scoped queue observation; unsupported measurements
	// must remain distinguishable from zero.
	Queues QueueSource
	// DesiredState is optional durable convergence-state reading, separate from
	// worker enforcement.
	DesiredState DesiredStateSource
}

type DesiredStateSource interface {
	// Get returns current durable state for the exact scoped target, not proof
	// of worker convergence.
	Get(context.Context, string, controlplane.Target) (control.DesiredRecord, error)
}

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

type Measurement[T any] struct {
	// Value is meaningful only when Supported is true; unsupported values
	// project to zero.
	Value T `json:"value"`
	// Supported distinguishes observed zero from an unavailable backend
	// measurement.
	Supported bool `json:"supported"`
}

type Problem struct {
	// Code is a stable public error category selected by the handler, never a
	// raw backend diagnostic.
	Code string `json:"code"`
}

type Queue struct {
	// Backend is observed backend attribution, not its address.
	Backend string `json:"backend"`
	// Name is the logical observed queue identity.
	Name string `json:"name"`
	// ObservedAt is source observation time normalized to UTC.
	ObservedAt time.Time `json:"observed_at"`
	// Metrics contains independent support flags for backend gauges/counters.
	Metrics QueueMetrics `json:"metrics"`
}

type QueueMetrics struct {
	// Depth is supported observed queue depth, not a guaranteed future count.
	Depth Measurement[int64] `json:"depth"`
	// Lag is supported backend-defined queue lag.
	Lag Measurement[int64] `json:"lag"`
	// Pending is supported in-flight/pending work.
	Pending Measurement[int64] `json:"pending"`
	// OldestAgeSeconds is supported oldest-record age converted from duration
	// to seconds.
	OldestAgeSeconds Measurement[float64] `json:"oldest_age_seconds"`
	// Throughput is supported backend-defined throughput, not a control-plane
	// benchmark.
	Throughput Measurement[float64] `json:"throughput"`
	// RuntimeSeconds is supported runtime duration converted to seconds;
	// averaging remains consumer-owned.
	RuntimeSeconds Measurement[float64] `json:"runtime_seconds"`
	// Succeeded counts supported successful lifecycle observations.
	Succeeded Measurement[uint64] `json:"succeeded"`
	// Failed counts supported failed lifecycle observations.
	Failed Measurement[uint64] `json:"failed"`
	// Retried counts supported retry observations.
	Retried Measurement[uint64] `json:"retried"`
	// Reclaimed counts supported reclaimed work.
	Reclaimed Measurement[uint64] `json:"reclaimed"`
	// DeadLettered counts supported dead-letter events.
	DeadLettered Measurement[uint64] `json:"dead_lettered"`
	// SettlementErrors counts supported settlement failures; handler success
	// alone does not imply settlement.
	SettlementErrors Measurement[uint64] `json:"settlement_errors"`
}

type QueuePage struct {
	// Queues is the newly projected observation page; providers own page
	// limits.
	Queues []Queue `json:"queues"`
	// NextCursor is opaque backend pagination state; empty means no further
	// page is advertised.
	NextCursor string `json:"next_cursor,omitempty"`
}

type QueueSource interface {
	// ListQueues returns a validated bounded tenant queue page with honest
	// supported/unsupported measurements.
	ListQueues(context.Context, string, queue.StatusPageRequest) (queue.QueueStatusPage, error)
}

type RateLimiter interface {
	// Allow synchronously returns admission for ctx/key; implementations must
	// bound blocking, preserve shared-use safety and fail closed.
	Allow(context.Context, string) bool
}

type Readiness interface {
	// Ready checks borrowed dependencies using ctx without performing
	// mutations.
	Ready(context.Context) error
}

type Record struct {
	// Kind identifies failure or dead-letter storage.
	Kind queue.RecordKind `json:"kind"`
	// ID is the scoped record identity checked for inspection.
	ID string `json:"id"`
	// Backend is source backend attribution, not addressing.
	Backend string `json:"backend"`
	// Queue is the logical source queue identity.
	Queue string `json:"queue"`
	// OccurredAt is source occurrence time normalized to UTC.
	OccurredAt time.Time `json:"occurred_at"`
	// Attempts is reported delivery-attempt count.
	Attempts uint32 `json:"attempts"`
	// FailureCode is the source's public failure category; the provider must
	// keep it secret-safe.
	FailureCode string `json:"failure_code"`
	// Payload is hidden by default; explicit permitted inspection may return
	// copied redacted or revealed bytes.
	Payload RecordPayload `json:"payload"`
	// EnvelopeVersion optionally reports source envelope format, not control-plane API version.
	EnvelopeVersion uint16 `json:"envelope_version,omitempty"`
	// PayloadSchemaVersion optionally identifies the application payload
	// schema.
	PayloadSchemaVersion string `json:"payload_schema_version,omitempty"`
	// OriginalID optionally preserves the original job identity through
	// retries/replay.
	OriginalID string `json:"original_id,omitempty"`
	// Topic optionally identifies source topic routing.
	Topic string `json:"topic,omitempty"`
	// Stream optionally identifies source stream routing.
	Stream string `json:"stream,omitempty"`
	// RoutingKey optionally identifies source routing metadata; providers must
	// classify safe public fields.
	RoutingKey string `json:"routing_key,omitempty"`
	// ConsumerGroup optionally identifies source consumer-group metadata.
	ConsumerGroup string `json:"consumer_group,omitempty"`
	// SourceRecordID optionally identifies the original transport record.
	SourceRecordID string `json:"source_record_id,omitempty"`
	// EnqueuedAt is an optional independently copied UTC enqueue time.
	EnqueuedAt *time.Time `json:"enqueued_at,omitempty"`
	// FirstDeliveryAt is an optional independently copied UTC first delivery
	// time.
	FirstDeliveryAt *time.Time `json:"first_delivery_at,omitempty"`
	// LastDeliveryAt is an optional independently copied UTC last delivery
	// time.
	LastDeliveryAt *time.Time `json:"last_delivery_at,omitempty"`
	// DeadLetteredAt is an optional independently copied UTC dead-letter time.
	DeadLetteredAt *time.Time `json:"dead_lettered_at,omitempty"`
	// RetryPolicy optionally names reported retry policy, not a new enforcement
	// instruction.
	RetryPolicy string `json:"retry_policy,omitempty"`
	// Classification is source failure classification.
	Classification queue.Classification `json:"classification,omitempty"`
	// FailureSummary is public source summary text; HTTP projection does not
	// sanitize its contents.
	FailureSummary string `json:"failure_summary,omitempty"`
	// Diagnostics is hidden unless independently authorized and audited;
	// returned bytes are copied.
	Diagnostics RecordPayload `json:"diagnostics"`
	// HandlerType optionally names the application handler.
	HandlerType string `json:"handler_type,omitempty"`
	// JobType optionally names the application job type.
	JobType string `json:"job_type,omitempty"`
	// Tags is a copied public metadata map; providers must exclude sensitive
	// values.
	Tags map[string]string `json:"tags,omitempty"`
	// TraceID optionally preserves trace correlation, not authorization.
	TraceID string `json:"trace_id,omitempty"`
	// TenantID is optional source metadata; request authorization uses route
	// scope instead.
	TenantID string `json:"tenant_id,omitempty"`
	// ProducerVersion optionally identifies producer implementation version.
	ProducerVersion string `json:"producer_version,omitempty"`
	// WorkerVersion optionally identifies processing worker version.
	WorkerVersion string `json:"worker_version,omitempty"`
	// OriginalDeadLetterID optionally identifies the original dead-letter
	// lineage.
	OriginalDeadLetterID string `json:"original_dead_letter_id,omitempty"`
	// PriorDeadLetterID optionally identifies the immediately preceding dead-letter lineage.
	PriorDeadLetterID string `json:"prior_dead_letter_id,omitempty"`
	// ReplayGeneration is the reported replay generation, not a control-plane
	// dispatch fence.
	ReplayGeneration uint32 `json:"replay_generation,omitempty"`
	// RetentionDeadline is an optional independently copied UTC retention
	// deadline.
	RetentionDeadline *time.Time `json:"retention_deadline,omitempty"`
}

type RecordPage struct {
	// Records is the newly projected metadata page with hidden
	// payload/diagnostics.
	Records []Record `json:"records"`
	// NextCursor is opaque backend pagination state.
	NextCursor string `json:"next_cursor,omitempty"`
}

type RecordPayload struct {
	// Visibility reports hidden/redacted/revealed representation; hidden
	// projections retain no Data or ContentType.
	Visibility queue.PayloadVisibility `json:"visibility"`
	// ContentType is the representation media type when permitted, not source
	// authenticity.
	ContentType string `json:"content_type,omitempty"`
	// Size reports source payload size even when its bytes are hidden.
	Size int64 `json:"size"`
	// Data is a copied permitted representation encoded as base64 in JSON;
	// empty is not proof that the original payload was empty.
	Data []byte `json:"data,omitempty"`
}

type RecordSource interface {
	// ListFailures returns bounded tenant failure metadata; the HTTP projection
	// hides payload and diagnostics.
	ListFailures(context.Context, string, queue.PageRequest) (queue.RecordPage, error)
	// ListDeadLetters returns bounded tenant dead-letter metadata without
	// exceeding the requested page.
	ListDeadLetters(context.Context, string, queue.PageRequest) (queue.RecordPage, error)
	// Inspect must return the exact scoped record at no greater payload
	// visibility than requested; diagnostic authorization remains a separate
	// HTTP boundary.
	Inspect(context.Context, string, queue.InspectRequest) (queue.JobRecord, error)
}

type RemoteWorkerSource interface {
	// SnapshotTenant honors ctx and returns an independently owned bounded
	// tenant snapshot; errors must not masquerade as an empty healthy fleet.
	SnapshotTenant(
		context.Context,
		string,
		time.Time,
		time.Duration,
	) (fleet.RegistrySnapshot, error)
}

type ReplayRequest struct {
	// Destination is the explicit destination separately authorized by the
	// command service.
	Destination string `json:"destination"`
	// IdempotencyPolicy selects rejection or replacement of destination
	// duplicates.
	IdempotencyPolicy controlplane.ReplayPolicy `json:"idempotency_policy"`
}

type ScaleRequest struct {
	// Replicas is at most controlplane.MaxScaleReplicas; zero additionally
	// requires confirmation.
	Replicas uint32 `json:"replicas"`
}

type SecurityConfig struct {
	// AllowedOrigins is copied into an exact HTTP(S) origin set; empty refuses
	// every request carrying Origin.
	AllowedOrigins []string
	// AllowCredentials controls the CORS credential response header for an
	// allowed origin; it does not authenticate users.
	AllowCredentials bool
	// RateLimiter optionally performs admission inside this wrapper; compose
	// after authentication or use NewAdministrativeHandler for subject-aware
	// ordering.
	RateLimiter RateLimiter
}

type SelectionRequest struct {
	// Limit must be positive and at most controlplane.MaxBulkSelection.
	Limit uint32 `json:"limit"`
}

type SensitiveAccessAuditor interface {
	// AuditSensitiveAccess must persist the privileged-access intent before
	// record reading; failure prevents disclosure but success is not proof that
	// bytes reached a client.
	AuditSensitiveAccess(context.Context, controlplane.SensitiveAccess) error
}

type TargetRequest struct {
	// Kind selects a supported resource class compatible with the action.
	Kind controlplane.TargetKind `json:"kind"`
	// Name is required bounded identity text; it is not a backend endpoint.
	Name string `json:"name"`
}

type TelemetryConfig struct {
	// TracerProvider is a borrowed tracing provider; application composition
	// owns processor/exporter shutdown.
	TracerProvider trace.TracerProvider
	// MeterProvider is a borrowed metrics provider used by HTTP
	// instrumentation.
	MeterProvider metric.MeterProvider
	// Propagator is borrowed propagation behavior; trace context is not
	// authentication.
	Propagator propagation.TextMapPropagator
	// TrustedInbound opts into inbound context trust only for requests carrying
	// a non-anonymous authenticated principal.
	TrustedInbound bool
}

type Viewer interface {
	// Authorize must fail closed for the authenticated actor, tenant,
	// permission and resource before source access.
	Authorize(
		context.Context,
		string,
		string,
		controlplane.Permission,
		controlplane.Target,
	) error
}

type Worker struct {
	// TenantID is the source's scoped tenant attribution.
	TenantID string `json:"tenant_id"`
	// WorkerID is the worker identity used in deterministic pagination.
	WorkerID string `json:"worker_id"`
	// Version is reported implementation version text.
	Version string `json:"version"`
	// StartedAt is reported worker start time.
	StartedAt time.Time `json:"started_at"`
	// ObservedAt is the heartbeat observation used for staleness, not
	// necessarily request receipt time.
	ObservedAt time.Time `json:"observed_at"`
	// Queues borrows the independently owned source snapshot's queue slice
	// during HTTP encoding.
	Queues []string `json:"queues"`
	// Concurrency is reported configured worker concurrency.
	Concurrency uint32 `json:"concurrency"`
	// State is derived liveness/conflict state, not a verified process
	// supervision result.
	State fleet.State `json:"state"`
	// CurrentJobs is reported in-flight job count.
	CurrentJobs uint32 `json:"current_jobs"`
	// DrainStatus is reported drain progress.
	DrainStatus fleet.DrainState `json:"drain_status"`
	// Backend is reported backend attribution.
	Backend string `json:"backend"`
	// Protocol is the reported management version pair.
	Protocol fleet.ProtocolVersion `json:"protocol"`
	// Capabilities borrows the independently owned snapshot's reported
	// capabilities during encoding.
	Capabilities []fleet.Capability `json:"capabilities"`
	// Compatibility is newly computed version/capability negotiation, not
	// authorization.
	Compatibility fleet.Compatibility `json:"compatibility"`
}

type WorkerPage struct {
	// Workers contains sorted/filtered worker projections; the source snapshot
	// is materialized before pagination.
	Workers []Worker `json:"workers"`
	// Rejected is the tenant count only when RejectedKnown is true.
	Rejected uint64 `json:"rejected"`
	// RejectedKnown distinguishes exact registered-tenant counts from unknown
	// detail, including providers that do not expose rejection accounting.
	RejectedKnown bool `json:"rejected_known"`
	// NextCursor is the exclusive last worker identity for another page; empty
	// means no further page was detected.
	NextCursor string `json:"next_cursor,omitempty"`
}

type WorkerSource interface {
	// SnapshotTenant returns a bounded, tenant-scoped independently owned
	// snapshot; this synchronous interface has no context parameter.
	SnapshotTenant(string, time.Time, time.Duration) fleet.RegistrySnapshot
}

type WorkloadSource interface {
	// ListTenantWorkloads returns the requested bounded namespace-scoped page;
	// providers must honor pagination and scope.
	ListTenantWorkloads(context.Context, string, int64, string) (controlkubernetes.Page, error)
}