s3-orchestrator

di

import "github.com/afreidah/s3-orchestrator/internal/di"

Package di is the single wiring point for the orchestrator. It uses samber/do/v2 to register every store role, backend, worker, and transport handler as a lazy provider; consumers resolve their dependencies through the injector at the moment they need them.

Index

func IsRegistered

func IsRegistered[T any](inj do.Injector) bool

IsRegistered reports whether T has a provider registered in the injector or any ancestor scope. Cheap; does not invoke the constructor.

func NewInjector

func NewInjector(deps InjectorDeps) do.Injector

NewInjector creates the DI container and registers every provider the service needs. The body is intentionally a flat sequence of per-domain registration calls so a contributor can see the full dependency graph in one screen; each helper below owns the providers for its domain.

func NewLifecycleService

func NewLifecycleService(manager lifecycleOps, locker tickrunner.AdvisoryLocker) lifecycle.Runner

NewLifecycleService constructs the lifecycle-expiration background service. Lives in DI (rather than next to a worker) because the work surface is on *proxy.BackendManager itself (via the lifecycleOps consumer interface) - there is no dedicated worker type.

func NewUsageFlushService

func NewUsageFlushService(manager usageFlushOps, locker tickrunner.AdvisoryLocker) lifecycle.Runner

NewUsageFlushService constructs the usage flush background service.

func ProvideAdminHandler

func ProvideAdminHandler(i do.Injector) (*admin.Handler, error)

ProvideAdminHandler creates the admin API handler.

func ProvideBackendManager

func ProvideBackendManager(i do.Injector) (*proxy.BackendManager, error)

func ProvideBackendRuntime

func ProvideBackendRuntime(i do.Injector) (*infra.BackendRuntime, error)

ProvideBackendManager creates the central orchestration manager with the narrow per-role store interfaces supplied. Also installs a recovery listener on the DB breaker so the degraded-mode location cache is cleared the moment the DB transitions back to closed. ProvideBackendRuntime builds the backend runtime: the fleet registry, usage tracker, admission semaphore, timeout policy, error classification, and metrics collector. Constructing it here (rather than inside NewBackendManager) makes the runtime a first-class, independently-resolvable dependency that workers, drain, and the manager all share, instead of a promoted embed only reachable through the manager.

func ProvideBreakerRegistry

func ProvideBreakerRegistry(i do.Injector) (*breaker.Registry, error)

ProvideBreakerRegistry assembles the watchdog’s breaker registry from the database circuit breaker and the per-backend breakers produced during backend initialization. Centralizing membership here keeps the watchdog itself free of type-assertions and keeps DI as the single wiring point.

func ProvideBucketAuth

func ProvideBucketAuth(i do.Injector) (*auth.BucketRegistry, error)

ProvideBucketAuth creates the credential-to-bucket registry.

func ProvideCleanupWorker

func ProvideCleanupWorker(i do.Injector) (*worker.CleanupWorker, error)

ProvideCleanupWorker constructs the cleanup-queue worker. It resolves the backend runtime and store directly rather than through the manager so the drain manager (which takes this worker’s ProcessCleanupQueue hook) can be built before the manager.

func ProvideDatabaseBreaker

func ProvideDatabaseBreaker(i do.Injector) (*breaker.CircuitBreaker, error)

ProvideDatabaseBreaker constructs the shared *breaker.CircuitBreaker every driver-level SQL statement forwards calls through.

func ProvideDrainManager

func ProvideDrainManager(i do.Injector) (*drain.Manager, error)

ProvideDrainManager constructs the drain manager from the backend runtime (fleet/copy/delete primitives), the write coordinator (its mover), the wide MetadataStore for the object/quota/lifecycle role surfaces, the multipart manager’s abort hook, and the cleanup worker’s queue flush. None of these is the BackendManager, so drain builds before the manager and is injected into it.

func ProvideEncryptionAdmin

func ProvideEncryptionAdmin(i do.Injector) (core.EncryptionAdmin, error)

ProvideEncryptionAdmin aliases the wide MetadataStore as its EncryptionAdmin role for the admin HTTP handler’s key rotation and encrypt/decrypt batch ops.

func ProvideEncryptionProvider

func ProvideEncryptionProvider(i do.Injector) (encryption.KeyProvider, error)

ProvideEncryptionProvider creates the key provider for admin key rotation operations. Only registered when encryption is enabled.

func ProvideEncryptor

func ProvideEncryptor(i do.Injector) (*encryption.Encryptor, error)

ProvideEncryptor creates the envelope encryption engine.

func ProvideFlightRecorderService

func ProvideFlightRecorderService(i do.Injector) (*debug.FlightRecorderService, error)

ProvideFlightRecorderService constructs the always-on runtime/trace FlightRecorder wrapper that the admin trace-snapshot endpoint streams from. Only registered when cfg.Debug.FlightRecorder.Enabled is true, so resolution failure means the operator did not opt in.

func ProvideInstanceID

func ProvideInstanceID(_ do.Injector) (instanceid.ID, error)

ProvideInstanceID resolves a stable per-process identifier used as the claimed_by stamp on cleanup_queue rows. The identifier is generated once at first invoke and reused everywhere the value is needed.

func ProvideIntegrityConfig

func ProvideIntegrityConfig(_ do.Injector) (*syncutil.AtomicConfig[config.IntegrityConfig], error)

ProvideIntegrityConfig provides the atomic integrity config shared by the multipart manager and the object manager so a SIGHUP flips both write paths’ hashing behavior in one swap.

func ProvideLifecycleAdmin

func ProvideLifecycleAdmin(i do.Injector) (core.LifecycleAdmin, error)

ProvideLifecycleAdmin aliases the wide MetadataStore as its LifecycleAdmin role for boot/shutdown migrations, schema checks, and Close.

func ProvideLifecycleManager

func ProvideLifecycleManager(i do.Injector) (*lifecycle.Manager, error)

ProvideLifecycleManager creates and registers all background services.

func ProvideLoginThrottle

func ProvideLoginThrottle(_ do.Injector) (*httputil.LoginThrottle, error)

ProvideLoginThrottle creates the per-IP login attempt throttle.

func ProvideMetadataStore

func ProvideMetadataStore(i do.Injector) (core.MetadataStore, error)

ProvideMetadataStore opens the configured driver, runs migrations, syncs quota limits, and returns the wide core.MetadataStore every consumer depends on. CB protection lives inside each driver’s DBTX/DB chokepoint, so this provider does no wrapping of its own.

func ProvideMetricsDeps

func ProvideMetricsDeps(i do.Injector) (metrics.Deps, error)

ProvideMetricsDeps aliases the wide MetadataStore as the metrics.Deps subset metrics.Collector uses to refresh Prometheus gauges.

func ProvideMultipartManager

func ProvideMultipartManager(i do.Injector) (*multipart.Manager, error)

ProvideMultipartManager builds the multipart upload lifecycle manager. Built outside the BackendManager so the drain manager can take its AbortMultipartUploadsOnBackend hook directly.

func ProvideNotificationOutbox

func ProvideNotificationOutbox(i do.Injector) (core.NotificationOutbox, error)

ProvideNotificationOutbox aliases the wide MetadataStore as its NotificationOutbox role for the notifier worker.

func ProvideNotifier

func ProvideNotifier(i do.Injector) (*notify.Notifier, error)

ProvideNotifier creates the webhook notification system.

func ProvideObjectCache

func ProvideObjectCache(i do.Injector) (objcache.ObjectCache, error)

ProvideObjectCache creates the in-memory LRU object data cache.

func ProvideOverReplicationCleaner

func ProvideOverReplicationCleaner(i do.Injector) (*worker.OverReplicationCleaner, error)

ProvideOverReplicationCleaner constructs the over-replication cleanup worker.

func ProvidePendingReaper

func ProvidePendingReaper(i do.Injector) (*worker.PendingReaper, error)

ProvidePendingReaper constructs the pending-reaper worker. The provider is registered in NewInjector only when the pending pattern is enabled, so reaching this function implies the feature is on. Any nil dependency at this point is a wiring bug, not a “feature off” signal — it surfaces as an error so Optional[*worker.PendingReaper] reports Failed instead of conflating it with Disabled.

func ProvideRateLimiter

func ProvideRateLimiter(i do.Injector) (*s3api.RateLimiter, error)

ProvideRateLimiter creates the per-IP rate limiter.

func ProvideRebalancer

func ProvideRebalancer(i do.Injector) (*worker.Rebalancer, error)

ProvideRebalancer constructs the rebalancer worker.

func ProvideReconciler

func ProvideReconciler(i do.Injector) (*worker.Reconciler, error)

ProvideReconciler constructs the bucket reconciler worker. Registered only in worker/all modes because reconciliation is a worker-side background task. Returns the reconciler so the lifecycle manager can register a service for it; the reconciler is also resolvable directly for the admin handler’s inspection endpoints.

func ProvideRedisCounterBackend

func ProvideRedisCounterBackend(i do.Injector) (*counter.RedisCounterBackend, error)

ProvideRedisCounterBackend creates the shared Redis counter backend.

func ProvideReplicator

func ProvideReplicator(i do.Injector) (*worker.Replicator, error)

ProvideReplicator constructs the replication worker.

func ProvideS3Server

func ProvideS3Server(i do.Injector) (*s3api.Server, error)

ProvideS3Server creates the S3-compatible HTTP handler.

func ProvideScrubber

func ProvideScrubber(i do.Injector) (*worker.Scrubber, error)

ProvideScrubber constructs the integrity-verification worker.

func ProvideUIHandler

func ProvideUIHandler(i do.Injector) (*ui.Handler, error)

ProvideUIHandler creates the web dashboard handler.

func ProvideWriteCoordinator

func ProvideWriteCoordinator(i do.Injector) (*writepath.Coordinator, error)

ProvideWriteCoordinator builds the write coordinator: the shared delete/move/orphan-cleanup primitive the manager, multipart manager, object manager, and drain manager all route writes through.

func WireAuditMetrics

func WireAuditMetrics()

WireAuditMetrics connects the audit event counter to Prometheus. Called from the main binary during startup, outside the injector.

func WireManager

func WireManager(inj do.Injector) error

WireManager resolves the BackendManager plus every required worker (as a smoke check that construction succeeded) and points the runtime’s eligibility filter at the drain manager. Returns the first error from resolving a required dependency; the optional PendingReaper Failed resolution is logged so a broken provider stays distinguishable from an intentionally absent one.

type BackendsResult

BackendsResult groups the outputs of backend initialization so multiple providers can resolve it without re-running construction.

type BackendsResult struct {
    Backends       map[string]backend.ObjectBackend
    Order          []string
    UsageLimits    map[string]core.UsageLimits
    MaxObjectSizes map[string]int64
    // Breakers is the per-backend circuit breakers produced when
    // BackendCircuitBreaker is enabled. Empty when CBs are disabled.
    // The watchdog registry consumes this so it never has to rediscover
    // breakers via type assertion at runtime.
    Breakers []breaker.StaleProbeResetter
}

func ProvideBackends

func ProvideBackends(i do.Injector) (*BackendsResult, error)

ProvideBackends initializes all configured storage backends, wrapping each with a per-backend circuit breaker when enabled.

type InjectorDeps

InjectorDeps groups the values NewInjector seeds the container with.

type InjectorDeps struct {
    Config    *config.Config
    Mode      config.Mode
    LogLevel  *slog.LevelVar
    LogBuffer *telemetry.LogBuffer
}

type OptionalResult

OptionalResult carries the outcome of an Optional[T] lookup. Callers pick the field they care about: Value for the resolved instance, Resolution for the operational classification, Err for the failure detail when Resolution is Failed.

type OptionalResult[T any] struct {
    Value      T
    Resolution Resolution
    Err        error
}

func Optional

func Optional[T any](inj do.Injector) OptionalResult[T]

Optional resolves T as an optional dependency. Inspects the injector’s registered service list first so a missing provider is distinguished from a constructor failure: a Disabled result means the feature was never wired in this run mode, while a Failed result means a provider was wired but its constructor (or a transitive dependency it tried to resolve) returned an error.

func (OptionalResult[T]) Applied

func (r OptionalResult[T]) Applied() bool

Applied reports whether the provider resolved cleanly.

func (OptionalResult[T]) Disabled

func (r OptionalResult[T]) Disabled() bool

Disabled reports whether the underlying provider was not registered.

func (OptionalResult[T]) Failed

func (r OptionalResult[T]) Failed() bool

Failed reports whether the provider was registered but failed to construct (or one of its transitive dependencies failed).

type Resolution

Resolution classifies the outcome of an optional dependency lookup.

type Resolution string

const (
    // ResolutionDisabled means no provider was registered for T.
    ResolutionDisabled Resolution = "disabled"
    // ResolutionApplied means the provider resolved cleanly.
    ResolutionApplied Resolution = "applied"
    // ResolutionFailed means the provider was registered but construction failed.
    ResolutionFailed Resolution = "failed"
)

Generated by gomarkdoc