Documentation
¶
Overview ¶
Package admin provides the admin API server for the S3 encryption gateway.
The admin server runs on a separate listener from the S3 data-plane, providing endpoints for key rotation management and (future) diagnostic endpoints. It is gated by bearer-token authentication with constant-time comparison.
Index ¶
- func ApplyRuntimeProfilingRates(cfg config.AdminProfilingConfig, logger *logrus.Logger)
- func BearerAuthMiddleware(tokenSource func() []byte, logger *logrus.Logger, auditLog audit.Logger) func(http.Handler) http.Handler
- func IsAdminRequest(r *http.Request) bool
- func RegisterMPUAdminRoutes(muxSrv *http.ServeMux, store MPUStateStore, abortFn MPUAbortFunc, ...)
- func RegisterPprofRoutes(mux *http.ServeMux, cfg config.AdminProfilingConfig, m ProfilingMetrics, ...)
- func WriteAdminErrorWithRotation(w http.ResponseWriter, status int, code, message, rotationID string)
- type MPUAbortFunc
- type MPUStateStore
- type ProfilingAudit
- type ProfilingMetrics
- type RateLimiter
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyRuntimeProfilingRates ¶
func ApplyRuntimeProfilingRates(cfg config.AdminProfilingConfig, logger *logrus.Logger)
ApplyRuntimeProfilingRates calls runtime.SetBlockProfileRate and runtime.SetMutexProfileFraction once at startup per cfg. This function is separate from RegisterPprofRoutes because the runtime state lives at the process level, not per-mux, and must be called exactly once.
func BearerAuthMiddleware ¶
func BearerAuthMiddleware(tokenSource func() []byte, logger *logrus.Logger, auditLog audit.Logger) func(http.Handler) http.Handler
BearerAuthMiddleware returns HTTP middleware that validates an Authorization: Bearer <token> header using constant-time comparison. tokenSource is called on every request to support runtime token rotation (e.g. via file-watch).
auditLog may be nil; when nil, audit events are silently skipped so callers that do not configure an audit sink still function correctly.
func IsAdminRequest ¶
IsAdminRequest returns true if the request arrived on the admin listener. This is the reusable predicate consumed by V0.6-S3-2.
func RegisterMPUAdminRoutes ¶
func RegisterMPUAdminRoutes(muxSrv *http.ServeMux, store MPUStateStore, abortFn MPUAbortFunc, logger *logrus.Logger)
RegisterMPUAdminRoutes mounts the MPU admin endpoints on the provided mux.
POST /admin/mpu/abort/{uploadId} — force-abort an in-flight upload
GET /admin/mpu/list — list active uploads from Valkey
func RegisterPprofRoutes ¶
func RegisterPprofRoutes( mux *http.ServeMux, cfg config.AdminProfilingConfig, m ProfilingMetrics, a ProfilingAudit, logger *logrus.Logger, )
RegisterPprofRoutes mounts profiling handlers on mux under /debug/pprof. It is a no-op when cfg.Enabled is false.
The caller is responsible for the authn / rate-limit middleware (the admin Server already chains those on every request). The semaphore for long-running endpoints and the seconds= validator are handled internally.
func WriteAdminErrorWithRotation ¶
func WriteAdminErrorWithRotation(w http.ResponseWriter, status int, code, message, rotationID string)
WriteAdminErrorWithRotation writes a JSON error response including a rotation_id.
Types ¶
type MPUAbortFunc ¶
MPUAbortFunc is called by the admin abort endpoint to also abort the backend upload.
type MPUStateStore ¶
type MPUStateStore interface {
Get(ctx context.Context, uploadID string) (*mpu.UploadState, error)
Delete(ctx context.Context, uploadID string) error
List(ctx context.Context) ([]mpu.UploadState, error)
}
MPUStateStore is the subset of mpu.StateStore used by the admin handlers. Separating the interface allows mocking in tests without the full store.
type ProfilingAudit ¶
type ProfilingAudit interface {
// LogAccessWithMetadata emits an audit event for each profile fetch.
LogAccessWithMetadata(eventType, bucket, key, clientIP, userAgent, requestID string,
success bool, err error, duration time.Duration, metadata map[string]interface{})
}
ProfilingAudit is the subset of audit.Logger required by the pprof handlers.
type ProfilingMetrics ¶
type ProfilingMetrics interface {
// RecordPprofRequest increments the bounded-cardinality counter
// s3_gateway_admin_pprof_requests_total{endpoint, outcome}.
RecordPprofRequest(endpoint, outcome string)
// SetAdminProfilingEnabled sets the gateway_admin_profiling_enabled gauge.
SetAdminProfilingEnabled(v bool)
}
ProfilingMetrics is the subset of metrics.Metrics required by the pprof handlers. Keeping it as a narrow interface preserves testability and avoids a hard dep on internal/metrics from internal/admin.
type RateLimiter ¶
type RateLimiter struct {
// contains filtered or unexported fields
}
RateLimiter implements a simple token-bucket rate limiter per source IP for the admin listener. Admin endpoints are low-QPS, so a simple implementation suffices.
func NewRateLimiter ¶
func NewRateLimiter(requestsPerMinute int, logger *logrus.Logger) *RateLimiter
NewRateLimiter creates a new per-IP rate limiter.
func (*RateLimiter) Middleware ¶
func (rl *RateLimiter) Middleware(next http.Handler) http.Handler
Middleware returns HTTP middleware that enforces rate limiting.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server owns the admin HTTP listener and mux.
func NewServer ¶
func NewServer(cfg config.AdminConfig, logger *logrus.Logger) *Server
NewServer creates a new admin Server. The caller must call RegisterRoutes before Start to mount handlers on the admin mux.
func (*Server) BoundAddr ¶
BoundAddr returns the address the server is listening on. Returns empty string if not yet started.
func (*Server) Shutdown ¶
Shutdown gracefully shuts down the admin server. It is safe to call concurrently with Start: if Start has not yet published the http.Server, Shutdown returns nil and the subsequent Start will see the listener close and exit cleanly.
func (*Server) Start ¶
Start begins listening on the admin address. It blocks until the context is cancelled or Shutdown is called.
func (*Server) WithAuditLogger ¶
WithAuditLogger configures the admin server to emit auth.failure audit events via the provided logger. When not called (or called with nil), auth-failure events are silently skipped.
Source Files