apihttp

Documentation

Overview

Package apihttp provides the versioned administrative HTTP API.

Index

• Constants
• Variables
• func NewHandler(config Config) (http.Handler, error)
• func NewRateLimitMiddleware(limiter RateLimiter) (func(http.Handler) http.Handler, error)
• func NewSecurityMiddleware(config SecurityConfig) (func(http.Handler) http.Handler, error)
• type AuditEntry
• type AuditPage
• type AuditSource
• type BuildInfo
• type CommandExecutor
• type CommandHistoryEntry
• type CommandHistoryPage
• type CommandRequest
• type CommandResultSource
• type Config
• type DesiredStateSource
• type FixedWindowRateLimiter
  • func NewFixedWindowRateLimiter(limit uint32, window time.Duration, maxKeys int, now func() time.Time) (*FixedWindowRateLimiter, error)
  • func (limiter *FixedWindowRateLimiter) Allow(ctx context.Context, key string) bool
• type Measurement
• type Problem
• type Queue
• type QueueMetrics
• type QueuePage
• type QueueSource
• type RateLimiter
• type Readiness
• type Record
• type RecordPage
• type RecordPayload
• type RecordSource
• type RemoteWorkerSource
• type ReplayRequest
• type ScaleRequest
• type SecurityConfig
• type SelectionRequest
• type SensitiveAccessAuditor
• type TargetRequest
• type TelemetryConfig
• type Viewer
• type Worker
• type WorkerPage
• type WorkerSource
• type WorkloadSource

Constants

const (

	// MaxCommandPageSize bounds one public command-history response.
	MaxCommandPageSize = controlpostgres.MaxCommandPageSize
	// MaxCommandCursorBytes bounds public opaque command-history cursors.
	MaxCommandCursorBytes = controlpostgres.MaxCommandCursorBytes
)

const (

	// MaxAuditPageSize bounds one public audit-history response.
	MaxAuditPageSize uint32 = 1_000
)

const (
	MaxWorkerPageSize uint32 = 1_000
)

Variables

var ErrInvalidConfiguration = errors.New("apihttp: invalid configuration")

var ErrInvalidRateLimitConfiguration = errors.New("apihttp: invalid rate limit configuration")

ErrInvalidRateLimitConfiguration reports unusable admission bounds.

var ErrInvalidSecurityConfiguration = errors.New("apihttp: invalid security configuration")

Functions

func NewHandler

func NewHandler(config Config) (http.Handler, error)

NewHandler creates the versioned administrative HTTP handler.

func NewRateLimitMiddleware

func NewRateLimitMiddleware(
	limiter RateLimiter,
) (func(http.Handler) http.Handler, error)

NewRateLimitMiddleware creates an authentication-aware admission layer. It must be composed after authentication so stable subjects take precedence over source addresses.

func NewSecurityMiddleware

func NewSecurityMiddleware(config SecurityConfig) (func(http.Handler) http.Handler, error)

NewSecurityMiddleware creates the administrative transport security layer.

Types

type AuditEntry

type AuditEntry struct {
	Sequence       uint64    `json:"sequence"`
	HashVersion    uint16    `json:"hash_version"`
	OccurredAt     time.Time `json:"occurred_at"`
	IdempotencyKey string    `json:"idempotency_key"`
	CommandID      string    `json:"command_id"`
	Actor          string    `json:"actor"`
	Action         string    `json:"action"`
	Target         string    `json:"target"`
	Result         string    `json:"result"`
	PreviousHash   string    `json:"previous_hash"`
	Hash           string    `json:"hash"`
}

AuditEntry is the stable JSON representation of one chained audit event.

type AuditPage

type AuditPage struct {
	Entries      []AuditEntry `json:"entries"`
	NextSequence uint64       `json:"next_sequence,omitempty"`
}

AuditPage is one bounded tenant audit-history response.

type AuditSource

type AuditSource interface {
	ListTenant(context.Context, string, uint64, uint32) (controlpostgres.AuditPage, error)
}

AuditSource reads bounded tenant audit-history pages.

type BuildInfo

type BuildInfo struct {
	Version string    `json:"version"`
	Commit  string    `json:"commit"`
	BuiltAt time.Time `json:"built_at"`
}

BuildInfo is immutable release metadata exposed to automation.

type CommandExecutor

type CommandExecutor interface {
	Execute(context.Context, controlplane.Command) (controlplane.CommandResult, error)
}

CommandExecutor runs an authenticated administrative command.

type CommandHistoryEntry

type CommandHistoryEntry struct {
	CommandID            string                     `json:"command_id"`
	IdempotencyKey       string                     `json:"idempotency_key"`
	Actor                string                     `json:"actor"`
	AuthenticationMethod string                     `json:"authentication_method"`
	Reason               string                     `json:"reason"`
	Action               controlplane.Action        `json:"action"`
	Capability           string                     `json:"capability"`
	Target               TargetRequest              `json:"target"`
	RequestedAt          time.Time                  `json:"requested_at"`
	Deadline             time.Time                  `json:"deadline"`
	Confirmed            bool                       `json:"confirmed"`
	Selection            *SelectionRequest          `json:"selection,omitempty"`
	Replay               *ReplayRequest             `json:"replay,omitempty"`
	Scale                *ScaleRequest              `json:"scale,omitempty"`
	Result               controlplane.CommandResult `json:"result"`
}

CommandHistoryEntry is one immutable command envelope and durable outcome.

type CommandHistoryPage

type CommandHistoryPage struct {
	Commands   []CommandHistoryEntry `json:"commands"`
	NextCursor string                `json:"next_cursor,omitempty"`
}

CommandHistoryPage is one bounded tenant command-history response.

type CommandRequest

type CommandRequest struct {
	IdempotencyKey string              `json:"idempotency_key"`
	Reason         string              `json:"reason"`
	Action         controlplane.Action `json:"action"`
	Target         TargetRequest       `json:"target"`
	RequestedAt    time.Time           `json:"requested_at"`
	Confirmed      bool                `json:"confirmed"`
	Selection      *SelectionRequest   `json:"selection,omitempty"`
	Replay         *ReplayRequest      `json:"replay,omitempty"`
	Scale          *ScaleRequest       `json:"scale,omitempty"`
}

CommandRequest is the actor-free JSON mutation accepted by the API.

type CommandResultSource

type CommandResultSource interface {
	Get(context.Context, string, string) (controlplane.CommandResult, error)
}

CommandResultSource reads tenant-scoped durable command outcomes.

type Config

type Config struct {
	Commands           CommandExecutor
	MaxRequestBytes    int64
	Readiness          Readiness
	Build              BuildInfo
	Capabilities       []string
	Workers            WorkerSource
	RemoteWorkers      RemoteWorkerSource
	Workloads          WorkloadSource
	Viewer             Viewer
	Now                func() time.Time
	NewCommandID       func() (string, error)
	WorkflowLimiter    RateLimiter
	StaleAfter         time.Duration
	Protocol           fleet.ProtocolRange
	WorkerCapabilities []fleet.Capability
	Telemetry          *TelemetryConfig
	Audit              AuditSource
	SensitiveAudit     SensitiveAccessAuditor
	CommandResults     CommandResultSource
	Records            RecordSource
	Queues             QueueSource
	DesiredState       DesiredStateSource
}

Config defines bounded dependencies for the administrative API.

type DesiredStateSource

type DesiredStateSource interface {
	Get(context.Context, string, controlplane.Target) (control.DesiredRecord, error)
}

DesiredStateSource reads one tenant-scoped durable convergence record.

type FixedWindowRateLimiter

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

FixedWindowRateLimiter keeps a bounded number of in-memory admission counters. Capacity exhaustion fails closed for previously unseen keys.

func NewFixedWindowRateLimiter

func NewFixedWindowRateLimiter(
	limit uint32,
	window time.Duration,
	maxKeys int,
	now func() time.Time,
) (*FixedWindowRateLimiter, error)

NewFixedWindowRateLimiter creates a process-local bounded rate limiter.

func (*FixedWindowRateLimiter) Allow

func (limiter *FixedWindowRateLimiter) Allow(ctx context.Context, key string) bool

Allow admits at most the configured number of calls for one bounded key in each fixed window.

type Measurement

type Measurement[T any] struct {
	Value     T    `json:"value"`
	Supported bool `json:"supported"`
}

Measurement distinguishes an honestly measured zero from unsupported data.

type Problem

type Problem struct {
	Code string `json:"code"`
}

Problem is the stable secret-safe API error envelope.

type Queue

type Queue struct {
	Backend    string       `json:"backend"`
	Name       string       `json:"name"`
	ObservedAt time.Time    `json:"observed_at"`
	Metrics    QueueMetrics `json:"metrics"`
}

Queue is a backend-neutral logical queue observation.

type QueueMetrics

type QueueMetrics struct {
	Depth            Measurement[int64]   `json:"depth"`
	Lag              Measurement[int64]   `json:"lag"`
	Pending          Measurement[int64]   `json:"pending"`
	OldestAgeSeconds Measurement[float64] `json:"oldest_age_seconds"`
	Throughput       Measurement[float64] `json:"throughput"`
	RuntimeSeconds   Measurement[float64] `json:"runtime_seconds"`
	Succeeded        Measurement[uint64]  `json:"succeeded"`
	Failed           Measurement[uint64]  `json:"failed"`
	Retried          Measurement[uint64]  `json:"retried"`
	Reclaimed        Measurement[uint64]  `json:"reclaimed"`
	DeadLettered     Measurement[uint64]  `json:"dead_lettered"`
	SettlementErrors Measurement[uint64]  `json:"settlement_errors"`
}

QueueMetrics contains supported gauges and monotonic lifecycle counters.

type QueuePage

type QueuePage struct {
	Queues     []Queue `json:"queues"`
	NextCursor string  `json:"next_cursor,omitempty"`
}

QueuePage is one bounded page of queue observations.

type QueueSource

type QueueSource interface {
	ListQueues(context.Context, string, queue.StatusPageRequest) (queue.QueueStatusPage, error)
}

QueueSource reads tenant-scoped queue status pages.

type RateLimiter

type RateLimiter interface {
	Allow(context.Context, string) bool
}

RateLimiter makes one bounded admission decision for a stable safe key.

type Readiness

type Readiness interface {
	Ready(context.Context) error
}

Readiness checks dependencies without changing process liveness.

type Record

type Record struct {
	Kind                 queue.RecordKind     `json:"kind"`
	ID                   string               `json:"id"`
	Backend              string               `json:"backend"`
	Queue                string               `json:"queue"`
	OccurredAt           time.Time            `json:"occurred_at"`
	Attempts             uint32               `json:"attempts"`
	FailureCode          string               `json:"failure_code"`
	Payload              RecordPayload        `json:"payload"`
	EnvelopeVersion      uint16               `json:"envelope_version,omitempty"`
	PayloadSchemaVersion string               `json:"payload_schema_version,omitempty"`
	OriginalID           string               `json:"original_id,omitempty"`
	Topic                string               `json:"topic,omitempty"`
	Stream               string               `json:"stream,omitempty"`
	RoutingKey           string               `json:"routing_key,omitempty"`
	ConsumerGroup        string               `json:"consumer_group,omitempty"`
	SourceRecordID       string               `json:"source_record_id,omitempty"`
	EnqueuedAt           *time.Time           `json:"enqueued_at,omitempty"`
	FirstDeliveryAt      *time.Time           `json:"first_delivery_at,omitempty"`
	LastDeliveryAt       *time.Time           `json:"last_delivery_at,omitempty"`
	DeadLetteredAt       *time.Time           `json:"dead_lettered_at,omitempty"`
	RetryPolicy          string               `json:"retry_policy,omitempty"`
	Classification       queue.Classification `json:"classification,omitempty"`
	FailureSummary       string               `json:"failure_summary,omitempty"`
	Diagnostics          RecordPayload        `json:"diagnostics"`
	HandlerType          string               `json:"handler_type,omitempty"`
	JobType              string               `json:"job_type,omitempty"`
	Tags                 map[string]string    `json:"tags,omitempty"`
	TraceID              string               `json:"trace_id,omitempty"`
	TenantID             string               `json:"tenant_id,omitempty"`
	ProducerVersion      string               `json:"producer_version,omitempty"`
	WorkerVersion        string               `json:"worker_version,omitempty"`
	OriginalDeadLetterID string               `json:"original_dead_letter_id,omitempty"`
	PriorDeadLetterID    string               `json:"prior_dead_letter_id,omitempty"`
	ReplayGeneration     uint32               `json:"replay_generation,omitempty"`
	RetentionDeadline    *time.Time           `json:"retention_deadline,omitempty"`
}

Record is the stable HTTP representation of a failed or dead-lettered job.

type RecordPage

type RecordPage struct {
	Records    []Record `json:"records"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

RecordPage is one stable bounded administrative record page.

type RecordPayload

type RecordPayload struct {
	Visibility  queue.PayloadVisibility `json:"visibility"`
	ContentType string                  `json:"content_type,omitempty"`
	Size        int64                   `json:"size"`
	Data        []byte                  `json:"data,omitempty"`
}

RecordPayload is hidden by default and contains bytes only after explicit privileged inspection.

type RecordSource

type RecordSource interface {
	ListFailures(context.Context, string, queue.PageRequest) (queue.RecordPage, error)
	ListDeadLetters(context.Context, string, queue.PageRequest) (queue.RecordPage, error)
	Inspect(context.Context, string, queue.InspectRequest) (queue.JobRecord, error)
}

RecordSource reads tenant-scoped queue failures and dead letters.

type RemoteWorkerSource

type RemoteWorkerSource interface {
	SnapshotTenant(
		context.Context,
		string,
		time.Time,
		time.Duration,
	) (fleet.RegistrySnapshot, error)
}

RemoteWorkerSource provides cancellable tenant-scoped worker snapshots.

type ReplayRequest

type ReplayRequest struct {
	Destination       string                    `json:"destination"`
	IdempotencyPolicy controlplane.ReplayPolicy `json:"idempotency_policy"`
}

ReplayRequest declares explicit replay destination and idempotency policy.

type ScaleRequest

type ScaleRequest struct {
	Replicas uint32 `json:"replicas"`
}

ScaleRequest declares the desired workload replica count.

type SecurityConfig

type SecurityConfig struct {
	AllowedOrigins   []string
	AllowCredentials bool
	RateLimiter      RateLimiter
}

SecurityConfig controls browser and request-admission protections.

type SelectionRequest

type SelectionRequest struct {
	Limit uint32 `json:"limit"`
}

SelectionRequest bounds a bulk administrative mutation.

type SensitiveAccessAuditor

type SensitiveAccessAuditor interface {
	AuditSensitiveAccess(context.Context, controlplane.SensitiveAccess) error
}

SensitiveAccessAuditor durably records privileged record reads.

type TargetRequest

type TargetRequest struct {
	Kind controlplane.TargetKind `json:"kind"`
	Name string                  `json:"name"`
}

TargetRequest identifies a command target without backend addressing.

type TelemetryConfig

type TelemetryConfig struct {
	TracerProvider trace.TracerProvider
	MeterProvider  metric.MeterProvider
	Propagator     propagation.TextMapPropagator
	TrustedInbound bool
}

TelemetryConfig supplies standard OpenTelemetry APIs owned by telemetry.

type Viewer

type Viewer interface {
	Authorize(
		context.Context,
		string,
		string,
		controlplane.Permission,
		controlplane.Target,
	) error
}

Viewer authorizes diagnostic reads against tenant resources.

type Worker

type Worker struct {
	TenantID      string                `json:"tenant_id"`
	WorkerID      string                `json:"worker_id"`
	Version       string                `json:"version"`
	StartedAt     time.Time             `json:"started_at"`
	ObservedAt    time.Time             `json:"observed_at"`
	Queues        []string              `json:"queues"`
	Concurrency   uint32                `json:"concurrency"`
	State         fleet.State           `json:"state"`
	CurrentJobs   uint32                `json:"current_jobs"`
	DrainStatus   fleet.DrainState      `json:"drain_status"`
	Backend       string                `json:"backend"`
	Protocol      fleet.ProtocolVersion `json:"protocol"`
	Capabilities  []fleet.Capability    `json:"capabilities"`
	Compatibility fleet.Compatibility   `json:"compatibility"`
}

Worker is the public tenant-scoped worker status representation.

type WorkerPage

type WorkerPage struct {
	Workers    []Worker `json:"workers"`
	Rejected   uint64   `json:"rejected"`
	NextCursor string   `json:"next_cursor,omitempty"`
}

WorkerPage is one deterministic bounded worker result page.

type WorkerSource

type WorkerSource interface {
	SnapshotTenant(string, time.Time, time.Duration) fleet.RegistrySnapshot
}

WorkerSource provides bounded tenant-scoped worker snapshots.

type WorkloadSource

type WorkloadSource interface {
	ListTenantWorkloads(context.Context, string, int64, string) (controlkubernetes.Page, error)
}

WorkloadSource provides bounded tenant-scoped Kubernetes visibility.