admin

import "github.com/afreidah/s3-orchestrator/internal/transport/admin"

Package admin provides the admin API handler for operational control endpoints.

Index

type BackendOps

BackendOps is the narrow surface of *proxy.BackendManager that the admin handler depends on for store-coupled operations not encapsulated by a named sub-manager (replicator, drain, scrubber, etc.). *proxy.BackendManager satisfies it.

type BackendOps interface {
    GetDashboardData(ctx context.Context) (*dashboard.Data, error)
    FlushUsage(ctx context.Context) error
    ReconcileUsage(ctx context.Context) (map[string]int64, error)
    RecordUsage(backendName string, requests, ingressBytes, egressBytes int64)
    IntegrityConfig() *config.IntegrityConfig
}

type BackfillChecksumsResult

BackfillChecksumsResult is the outcome of a checksum backfill pass.

type BackfillChecksumsResult struct {
    Status    string // "ok" or "skipped"
    Reason    string // populated when Status is "skipped"
    Processed int
    Done      bool // true when no unhashed objects remained after this pass
}

type BulkRewriteResult

BulkRewriteResult is the outcome of a bulk encrypt/decrypt-existing pass. Status is “complete” when the run finished, “skipped” when the operation is unavailable (encryption not enabled).

type BulkRewriteResult struct {
    Status  string
    Reason  string
    Success int
    Failed  int
    Total   int
}

type Deps

Deps groups the narrow role interfaces and infrastructure the admin handler touches. Each field carries the smallest contract the handler actually uses, so the constructor (and the backing DI provider) never hand the handler a god-shaped *proxy.BackendManager.

type Deps struct {
    BackendOps   BackendOps
    RuntimeOps   RuntimeOps
    Replicator   ReplicatorOps
    Rebalancer   RebalancerOps // nil when the worker pool is not wired
    OverRep      OverReplicationOps
    Drain        *drain.Manager
    Scrubber     ScrubberOps
    Lifecycle    core.BackendLifecycleStore
    DBHealthy    func() bool           // typically *breaker.CircuitBreaker.IsHealthy
    WorkerHealth func() []WorkerHealth // typically lifecycle.Manager.Health adapted
    Encryption   core.EncryptionAdmin
    Objects      core.ObjectStore
    Cleanup      core.CleanupStore
    Encryptor    *encryption.Encryptor
    ObjectCache  cache.ObjectCache // nil when object data caching is disabled
    FlightRec    io.WriterTo       // nil when debug.flight_recorder.enabled is false
    Reconciler   Reconciler
    Token        string
    LogLevel     *slog.LevelVar
}

type Handler

Handler serves the admin API endpoints.

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

func New

func New(d *Deps) *Handler

New creates a new admin API handler from its narrow dependency bag.

func (*Handler) BackfillChecksums

func (h *Handler) BackfillChecksums(ctx context.Context, batchSize, maxObjects int, pause time.Duration, observer progress.Observer) BackfillChecksumsResult

BackfillChecksums computes and stores content hashes for objects that don’t have one. It processes batchSize objects per pass, pausing for pause between passes to rate-limit backend reads, and stops after maxObjects objects (maxObjects <= 0 drains the whole backlog). batchSize <= 0 means use 100. Done reports whether the backlog is fully drained. observer, when non-nil, receives a start and end event for each object so a streaming caller can report per-object progress. Skips when integrity verification is not enabled.

func (*Handler) EncryptExisting

func (h *Handler) EncryptExisting(ctx context.Context) BulkRewriteResult

EncryptExisting downloads every unencrypted object, encrypts it, re-uploads the ciphertext, and updates the DB record. Returns counts. Skips when encryption is not configured.

func (*Handler) Rebalance

func (h *Handler) Rebalance(ctx context.Context) (RebalanceResult, error)

Rebalance runs one rebalance cycle synchronously and returns the number of objects moved. Skips when the rebalancer worker is not wired. Applies the same defaults the dashboard does so a manual run works even when rebalance was never configured. Exposed for callers (UI, tests) that need the count back as a Go value rather than JSON.

func (*Handler) Register

func (h *Handler) Register(mux *http.ServeMux)

func (*Handler) Replicate

func (h *Handler) Replicate(ctx context.Context, observer progress.Observer) (ReplicateResult, error)

Replicate runs one replication cycle synchronously and returns the resulting counts. Skips when replication is unconfigured or factor <= 1. Refreshes quota metrics on success. observer, when non-nil, receives a start and end step per object replicated. Exposed for callers (UI, tests) that need the counts back as Go values rather than JSON.

func (*Handler) Scrub

func (h *Handler) Scrub(ctx context.Context, batchSize int, observer progress.Observer) ScrubResult

Scrub runs one integrity-verification scrub pass synchronously and returns the per-pass counts. batchSize <= 0 means use the configured ScrubberBatchSize. observer, when non-nil, receives a start and end step per object verified. Skips when integrity verification is not enabled.

func (*Handler) SetReloadStatusProvider

func (h *Handler) SetReloadStatusProvider(fn func() any)

SetReloadStatusProvider wires the callback that returns the most recent reload result. Called by the runtime after the reload coordinator is built. Routing through a setter rather than constructor injection avoids the import cycle that would result from admin importing the reload package directly.

type OverReplicationOps

OverReplicationOps is the slice of *worker.OverReplicationCleaner the admin handler uses for the over-replication status and cleanup endpoints.

type OverReplicationOps interface {
    Config() *config.ReplicationConfig
    CountPending(ctx context.Context, factor int) (int64, error)
    Clean(ctx context.Context, cfg config.ReplicationConfig, observer progress.Observer) (int, error)
}

type RebalanceResult

RebalanceResult is the outcome of a one-shot rebalance cycle.

type RebalanceResult struct {
    Status string // "ok" or "skipped"
    Reason string // populated when Status is "skipped"
    Moved  int
}

type RebalancerOps

RebalancerOps is the slice of *worker.Rebalancer the admin handler uses for the on-demand rebalance endpoint. Config returns nil when the worker is unconfigured; Rebalance runs one cycle and returns its work summary.

type RebalancerOps interface {
    Config() *config.RebalanceConfig
    Rebalance(ctx context.Context, cfg config.RebalanceConfig) (worker.WorkSummary, error)
}

type Reconciler

Reconciler is the slice of *worker.Reconciler the admin handler uses for the on-demand reconciliation endpoint.

type Reconciler interface {
    Reconcile(ctx context.Context, backendName string) (*worker.ReconcileResult, error)
    ReconcileStreaming(ctx context.Context, backendName string, observer progress.Observer) (*worker.ReconcileResult, error)
}

type ReplicateResult

ReplicateResult is the outcome of a one-shot replication cycle.

type ReplicateResult struct {
    Status        string // "ok" or "skipped"
    Reason        string // populated when Status is "skipped"
    CopiesCreated int
}

type ReplicatorOps

ReplicatorOps is the slice of *worker.Replicator the admin handler uses for the synchronous replicate-now endpoint. Config returns nil when the worker is unconfigured; Replicate runs one cycle and returns the count.

type ReplicatorOps interface {
    Config() *config.ReplicationConfig
    Replicate(ctx context.Context, cfg config.ReplicationConfig, observer progress.Observer) (int, error)
}

type RuntimeOps

RuntimeOps is the backend-runtime surface the admin handler reaches directly: backend lookup and the post-mutation quota-metric refresh. *infra.BackendRuntime satisfies it.

type RuntimeOps interface {
    GetBackend(name string) (backend.ObjectBackend, error)
    UpdateQuotaMetrics(ctx context.Context) error
}

type ScrubResult

ScrubResult is the outcome of one on-demand scrub cycle.

type ScrubResult struct {
    Status  string // "ok" or "skipped"
    Reason  string // populated when Status is "skipped"
    Checked int
    Failed  int
}

type ScrubberOps

ScrubberOps is the slice of *worker.Scrubber the admin handler uses for the integrity-scrub and hash-backfill endpoints.

type ScrubberOps interface {
    Scrub(ctx context.Context, batchSize int, observer progress.Observer) worker.WorkSummary
    Backfill(ctx context.Context, batchSize, offset int, observer progress.Observer) (worker.WorkSummary, int)
}

type WorkerHealth

WorkerHealth is the JSON shape returned by /admin/api/workers. Mirrors lifecycle.WorkerHealth but lives here so the admin transport package owns its own response contract and does not import the lifecycle package directly. Field tags must stay in lockstep with the source type or the wire format silently diverges.

type WorkerHealth struct {
    Name                string    `json:"name"`
    LastSuccess         time.Time `json:"last_success"`
    LastFailure         time.Time `json:"last_failure"`
    LastError           string    `json:"last_error,omitempty"`
    ConsecutiveFailures int       `json:"consecutive_failures"`
}

Generated by gomarkdoc