srvhttp

Documentation

Index

• type Config
  • func (cfg *Config[T]) Build() (any, error)
• type HTTPMetrics
  • func (m *HTTPMetrics) AddInflightRequests(ctx context.Context, props metrics.HTTPProperties, quantity int)
  • func (m *HTTPMetrics) ObserveHTTPRequestDuration(ctx context.Context, props metrics.HTTPReqProperties, duration time.Duration)
  • func (m *HTTPMetrics) ObserveHTTPResponseSize(ctx context.Context, props metrics.HTTPReqProperties, sizeBytes int64)
  • func (m *HTTPMetrics) RegisterMetrics(reg *prometheus.Registry) error
• type MetricsContributor
• type Option
  • func WithMiddleware[T http.Handler](mw ...func(http.Handler) http.Handler) Option[T]
• type Server
  • func New[T http.Handler](opts ...Option[T]) *Server[T]
  • func (t *Server[T]) BuildConfig() (app.Materializer, error)
  • func (t *Server[T]) Close() error
  • func (t *Server[T]) Deps() []any
  • func (t *Server[T]) DisableGate()
  • func (t *Server[T]) HealthCheck(_ context.Context) error
  • func (t *Server[T]) Inject(args []any)
  • func (t *Server[T]) ProbeReady(ctx context.Context) error
  • func (t *Server[T]) Start(ctx context.Context) (func(context.Context) error, error)

Types

type Config

type Config[T http.Handler] struct {
	Label common.Label
	Host  common.Host
	Port  common.Port
	// contains filtered or unexported fields
}

Config is the HTTP server spec (Label, Host, Port); ecfg fills before Build.

func (*Config[T]) Build

func (cfg *Config[T]) Build() (any, error)

type HTTPMetrics

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

HTTPMetrics is a singleton pool resource: contributor + shared slok Recorder for all srv-http servers. rec is an atomic.Pointer, not a plain field: RegisterMetrics can run concurrently with Observe*/AddInflightRequests from in-flight request goroutines on other srv-http.Server instances sharing this singleton — a plain metrics.Recorder field would be a data race on a 2-word interface value (torn type/data read), same class of bug [Server.err] already guards against with atomic.Error.

func (*HTTPMetrics) AddInflightRequests

func (m *HTTPMetrics) AddInflightRequests(ctx context.Context, props metrics.HTTPProperties, quantity int)

func (*HTTPMetrics) ObserveHTTPRequestDuration

func (m *HTTPMetrics) ObserveHTTPRequestDuration(ctx context.Context, props metrics.HTTPReqProperties, duration time.Duration)

func (*HTTPMetrics) ObserveHTTPResponseSize

func (m *HTTPMetrics) ObserveHTTPResponseSize(ctx context.Context, props metrics.HTTPReqProperties, sizeBytes int64)

func (*HTTPMetrics) RegisterMetrics

func (m *HTTPMetrics) RegisterMetrics(reg *prometheus.Registry) error

type MetricsContributor

type MetricsContributor interface {
	RegisterMetrics(reg *prometheus.Registry) error
}

MetricsContributor registers HTTP metrics collectors into a shared registry. Same method signature as github.com/omcrgnt/ops/metrics.MetricsContributor.

type Option

type Option[T http.Handler] func(*Server[T])

Option configures a Server at construction time, for values ecfg can't fill (e.g. middleware functions) — see New.

func WithMiddleware

func WithMiddleware[T http.Handler](mw ...func(http.Handler) http.Handler) Option[T]

WithMiddleware appends middleware run in addition to (not instead of) the metrics/gate wrapping this package always installs, closest to the real handler — see Config.Build's initFn for exact placement.

type Server

type Server[T http.Handler] struct {
	http.Server
	// contains filtered or unexported fields
}

Server is the HTTP server resource bound to handler type T. Catalog field: *Server[T] (Configurable); materialized *Server[T] is the runtime instance after Config.Build. Runtime methods: Start (returns a cleanup that stops the server), HealthCheck, ProbeReady. Close also exists (see its own doc comment) but only to shadow the embedded http.Server's promoted Close — prefer the cleanup Start returns.

func New

func New[T http.Handler](opts ...Option[T]) *Server[T]

New constructs a Server[T] with the given options applied. The catalog field holding it must be assigned this (non-nil) in the app's resources literal — left nil (the zero-value default), these options are lost when Build constructs a fresh instance. See client-grpc's Client.New.

func (*Server[T]) BuildConfig

func (t *Server[T]) BuildConfig() (app.Materializer, error)

BuildConfig returns the config spec for materialize, carrying over whatever options New was called with.

func (*Server[T]) Close

func (t *Server[T]) Close() error

Close shadows the http.Server.Close this type embeds: without an explicitly declared Close of its own, Server[T] promotes the embedded http.Server's zero-arg, non-graceful Close() error — a hard reset that drops in-flight connections instead of the graceful stop above. Anyone calling the old Close(ctx) convention by habit gets a compile error, not a silently different shutdown.

func (*Server[T]) Deps

func (t *Server[T]) Deps() []any

func (*Server[T]) DisableGate

func (t *Server[T]) DisableGate()

DisableGate permanently turns off gate-checking for this instance — for servers that must never be traffic-gated (e.g. ops's own readiness endpoint, which would otherwise mask its own status behind a blanket 503, and could false-fail a liveness check sharing the same listener).

Must be called before Start, synchronously by the same caller that wires this Server: initFn reads t.gate/t.gateDisabled once, while building the request pipeline, and never again — a call after Start has already run is a silent no-op.

func (*Server[T]) HealthCheck

func (t *Server[T]) HealthCheck(_ context.Context) error

func (*Server[T]) Inject

func (t *Server[T]) Inject(args []any)

func (*Server[T]) ProbeReady

func (t *Server[T]) ProbeReady(ctx context.Context) error

ProbeReady reports traffic readiness (SDI duck typing; no ops import): non-nil if Serve failed after Start (same as HealthCheck), or if a gate is wired, enabled, and not yet open — a caller relying only on HealthCheck would see this Server as ready while every real request is still answered 503 by the gate handler.

func (*Server[T]) Start

func (t *Server[T]) Start(ctx context.Context) (func(context.Context) error, error)