Documentation
¶
Overview ¶
Package server mounts the parsec HTTP surface: the centrifuge websocket transport, the rpc Twirp-JSON handler, an SSE fallback for the CLI `subscribe` probe, and /healthz.
Index ¶
- func AccessLog(opts AccessLogOptions, next http.Handler) http.Handler
- func LogAuthFailure(ctx context.Context, code string)
- func MountWebTransport(node *centrifuge.Node, opts WebTransportOptions, logger *slog.Logger) (http.Handler, error)
- func New(p *parsec.Parsec, svc *service.Service, logger *slog.Logger, ...) http.Handler
- func RequestID(ctx context.Context) string
- type AccessLogOptions
- type BearerValidator
- type SubjectExtractor
- type WebTransportOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AccessLog ¶
func AccessLog(opts AccessLogOptions, next http.Handler) http.Handler
AccessLog returns an HTTP middleware that emits one slog INFO line per request and one WARN line per auth failure recorded via LogAuthFailure.
Fields:
- method, path, status, duration_ms
- remote_addr (X-Forwarded-For aware via TrustedProxies)
- request_id (X-Request-ID; auto-generated if missing)
- bearer_subject (best-effort: base64-decoded JWT sub, NOT verified)
- trace_id (from the active OTel span if any; "" otherwise)
Token contents are NEVER logged. The bearer_subject value is best-effort decoded from the public JWT payload purely for operational correlation, not authorization.
func LogAuthFailure ¶
LogAuthFailure emits a WARN log for a token verification failure. Code is the PARSEC_AUTH_* code from the verifier. The token itself is never included.
func MountWebTransport ¶
func MountWebTransport(node *centrifuge.Node, opts WebTransportOptions, logger *slog.Logger) (http.Handler, error)
MountWebTransport returns an HTTP handler that upgrades requests to WebTransport and bridges each session to a centrifuge.Client. The handler is mounted at the path the caller chooses (typically "/connection/webtransport"). The returned shutdown function closes the WT server on operator request.
func New ¶
func New(p *parsec.Parsec, svc *service.Service, logger *slog.Logger, validate BearerValidator) http.Handler
New returns the composed http.Handler. p must be running (or about to be); svc is the business-logic layer; logger may be nil. validate is the bearer-token validator for the RPC surface; pass nil to disable bearer auth (tests only).
Types ¶
type AccessLogOptions ¶
type AccessLogOptions struct {
// Logger receives the JSON-shaped INFO line per request. Required;
// access-log wiring is skipped when nil.
Logger *slog.Logger
// TrustedProxies is the list of CIDRs/IPs Parsec will honor an
// X-Forwarded-For chain from. When the immediate remote is not in
// this list, X-Forwarded-For is ignored and the TCP peer is logged.
TrustedProxies []net.IPNet
// Region is the operator-configured region label. When non-empty
// it is stamped on every access-log line so operators can grep /
// slice their multi-region logs. Empty omits the field entirely so
// single-region logs stay lean.
Region string
}
AccessLogOptions configures the access-log middleware.
type BearerValidator ¶
BearerValidator decides whether the incoming Authorization: Bearer token is acceptable. New injects one via the bearer middleware; nil means "no auth required" and is intended for tests only.
func MgmtValidator ¶
func MgmtValidator(p *parsec.Parsec) BearerValidator
MgmtValidator returns a BearerValidator that accepts any valid mgmt token signed by the parsec instance's secret. When the parsec instance has an OIDC verifier wired (Options.OIDCConfig non-nil), the validator also accepts ID tokens from the configured issuer — HMAC is tried first, OIDC is the fallback. A deployment without OIDCConfig only accepts HMAC tokens.
type SubjectExtractor ¶
SubjectExtractor returns the token's sub claim (and any per-token rate-limit override) given the raw bearer string. Optional — when nil the bearer middleware does not stamp a subject in the request context, and downstream rate-limit gates fall back to the remote IP key.
func MgmtExtractor ¶
func MgmtExtractor(p *parsec.Parsec) SubjectExtractor
MgmtExtractor returns a SubjectExtractor that decodes the mgmt bearer's claims so the bearer middleware can stamp the subject (and any per-token rate-limit override) into the request context. Verification errors are swallowed — validate runs first; if validate accepted, the claims are guaranteed to parse. When OIDC is wired the extractor pulls claims via the composite verifier so OIDC-issued bearers also stamp a subject.
type WebTransportOptions ¶
type WebTransportOptions struct {
// Addr is the UDP listen address for the QUIC/HTTP3 listener (e.g. ":8443").
Addr string
// TLSCertFile + TLSKeyFile are the cert pair. WebTransport REQUIRES
// TLS; there is no plaintext mode.
TLSCertFile string
TLSKeyFile string
// AllowedOrigins gates incoming WT requests. Empty slice means
// "allow all" (dev mode). In production, list every origin that
// should be allowed to connect.
AllowedOrigins []string
}
WebTransportOptions configures the optional HTTP/3 WebTransport listener.
func (WebTransportOptions) Enabled ¶
func (o WebTransportOptions) Enabled() bool
Enabled reports whether the WT options describe an active listener.
Source Files