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 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
    UpdateQuotaMetrics(ctx context.Context) error
    RecordUsage(backendName string, requests, ingressBytes, egressBytes int64)
    GetBackend(name string) (backend.ObjectBackend, error)
    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
}

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
    Replicator   ReplicatorOps
    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
    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 int) BackfillChecksumsResult

BackfillChecksums computes and stores content hashes for objects that don’t have one, paginating internally until all objects are processed or the context is cancelled. batchSize <= 0 means use 100. 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) Register

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

func (*Handler) Replicate

func (h *Handler) Replicate(ctx context.Context) (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. 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) ScrubResult

Scrub runs one integrity-verification scrub pass synchronously and returns the per-pass counts. batchSize <= 0 means use the configured ScrubberBatchSize. 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) (int, 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)
}

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) (int, 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) (checked, failed int)
    Backfill(ctx context.Context, batchSize, offset int) (processed, nextOffset 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,omitempty"`
    LastFailure         time.Time `json:"last_failure,omitempty"`
    LastError           string    `json:"last_error,omitempty"`
    ConsecutiveFailures int       `json:"consecutive_failures"`
}

Generated by gomarkdoc