httpadapter

Documentation

Overview

Package httpadapter provides the HTTP transport layer for the Filegate API. It maps incoming HTTP requests to domain service calls and encodes responses as JSON or streaming content.

The package focuses on:

• RESTful routing for paths, nodes, uploads, transfers, search, and index endpoints.
• Bearer-token authentication middleware.
• Upload-session lifecycle management with concurrent write control.
• On-demand thumbnail generation with LRU caching.

Key Components:

• NewRouter: constructs the HTTP handler tree with all middleware and routes.
• RouterOptions: configuration struct for router initialization.
• uploadSessionManager: manages resumable upload sessions.
• thumbnailer: generates and caches image thumbnails via a job scheduler.

Related Packages:

• domain: business logic and service interface consumed by handlers.
• api/v1: shared request/response type definitions.
• infra/jobs: bounded worker pool used for thumbnail jobs.

Index

• func NewRouter(svc *domain.Service, opts RouterOptions) http.Handler
• func ParseTrustedProxies(entries []string) ([]netip.Prefix, error)
• func PathsOverlap(a, b string) bool
• func ValidateMetricsPath(path string) error
• type ConfigService
• type RouterOptions
• type S3KeyService

Functions

func NewRouter

func NewRouter(svc *domain.Service, opts RouterOptions) http.Handler

NewRouter constructs the HTTP handler tree with all routes, middleware, and background workers.

func ParseTrustedProxies

func ParseTrustedProxies(entries []string) ([]netip.Prefix, error)

ParseTrustedProxies converts the configured server.trusted_proxies entries (bare IPs or CIDRs) into prefixes. Returns an error on the first malformed entry so startup fails loudly instead of silently trusting nobody.

func PathsOverlap

func PathsOverlap(a, b string) bool

PathsOverlap reports whether either path is equal to or mounted under the other. It is used for startup-time route collision checks.

func ValidateMetricsPath

func ValidateMetricsPath(path string) error

ValidateMetricsPath rejects a metrics path that would collide with the REST route surface. Called at startup so a misconfiguration fails loudly instead of producing a confusing ServeMux conflict or shadowing a real route. The path must be absolute and must not be "/health" or live under "/v1".

Types

type ConfigService

type ConfigService interface {
	Schema() []apiv1.ConfigKeySchema
	Values() apiv1.ConfigValuesResponse
	PlanManifest(values map[string]any) (apiv1.ConfigManifestPlanResponse, error)
	ApplyManifest(values map[string]any, expectedRevision, actor string) (apiv1.ConfigManifestApplyResponse, error)
}

ConfigService is the declarative configuration surface the router exposes.

type RouterOptions

type RouterOptions struct {
	BearerToken      string
	AccessLogEnabled bool
	PublicURL        string
	// TrustedProxies are the peers whose X-Forwarded-For / X-Real-Ip
	// headers are honored (see ParseTrustedProxies). Empty = headers
	// ignored.
	TrustedProxies             []netip.Prefix
	CORS                       domain.CORSConfig
	IndexPath                  string
	JobWorkers                 int
	JobQueueSize               int
	ThumbnailJobWorkers        int
	ThumbnailJobQueueSize      int
	UploadExpiry               time.Duration
	UploadCleanupInterval      time.Duration
	MaxChunkBytes              int64
	MaxUploadBytes             int64
	MaxSessionUploadBytes      int64
	MaxConcurrentSegmentWrites int
	UploadMinFreeBytes         int64
	ThumbnailLRUCacheSize      int
	ThumbnailMaxSourceBytes    int64
	ThumbnailMaxPixels         int64
	Rescan                     func() error

	// MetricsHandler, when non-nil, is mounted at MetricsPath on the
	// REST listener (no separate port). Auth is layered: MetricsToken
	// if set, else the REST BearerToken, else open. The caller
	// (cli/serve.go) validates MetricsPath does not collide with /v1
	// or /health before constructing the router.
	MetricsHandler http.Handler
	MetricsPath    string
	MetricsToken   string
	ActivityLog    *activity.Ring

	// Config is the live snapshot. Runtime-scoped handlers read from it per
	// request so a change applies without a restart; nil falls back to the
	// values captured in this struct, which keeps existing callers working.
	Config *domain.ConfigHolder
	// Lifecycle reports the last background maintenance run. Nil reports zeroes.
	Lifecycle func() apiv1.LifecycleRuntime
	// PruneNow runs a retention round on demand. Nil leaves the route
	// answering 501, which is the honest response when versioning is off.
	PruneNow func() (domain.PruneStats, error)
	// ConfigService backs the /v1/config endpoints. Nil leaves them unmounted,
	// which is how every existing router caller and test keeps working.
	ConfigService ConfigService
	// S3Keys backs the /v1/s3/keys endpoints. Nil leaves them unmounted.
	S3Keys S3KeyService

	// Operational context for GET /v1/system/info, /v1/system/runtime and
	// /v1/health. All optional: zero values degrade the reported detail
	// rather than breaking the endpoints, which keeps existing router
	// callers (including tests) working unchanged.
	BuildVersion string
	BuildCommit  string
	BasePaths    []string
	// PathCacheSize is the configured capacity, reported alongside the live
	// occupancy the service tracks.
	PathCacheSize int
	// DetectorStats returns live detector state. Nil means the router reports
	// an unknown backend instead of guessing.
	DetectorStats      func() detect.Stats
	DetectorConfigured string
	DetectorReason     string
	ReconcileInterval  time.Duration

	VersioningEnabled          bool
	VersioningMode             string
	VersioningCopyMode         string
	VersioningReason           string
	VersioningCooldown         time.Duration
	VersioningPrunerInterval   time.Duration
	VersioningMaxPinnedPerFile int
}

RouterOptions configures the HTTP router including authentication, upload limits, thumbnail generation, and background job worker pools.

type S3KeyService

type S3KeyService interface {
	List() ([]apiv1.S3Key, error)
	Create(req apiv1.S3KeyCreateRequest) (apiv1.S3KeyCreated, error)
	Rotate(accessKey string) (apiv1.S3KeyCreated, error)
	Update(accessKey string, req apiv1.S3KeyUpdateRequest) (apiv1.S3Key, error)
	Delete(accessKey string) error
}

S3KeyService is the access-key surface the router exposes. Implemented in the CLI package, which owns the runtime store.