HTTP handler

http/handler.go (1,755 lines) builds the http.Handler mux that fronts every Vault API endpoint. It translates HTTP requests into logical.Request objects, hands them to vault.Core, and translates the response back. Source: http/ (everything except web_ui/ is the API plane).

Purpose

• Bind every route Vault exposes (/v1/..., /sys/..., /.well-known/..., raft, CORS preflight, healthcheck, init/unseal) into a single net/http mux.
• Apply HTTP-level concerns (CORS, max body size, request priority, gzip, request IDs).
• Enforce TLS, parse forwarding headers, attach client IP and user agent to the request.
• Serialize errors into Vault's standard JSON shape.

Directory layout

http/
├── handler.go                # main mux, ~1,755 lines
├── handler_stubs_oss.go      # CE stubs for Enterprise hooks
├── logical.go                # generic /v1/<path> handler that calls Core.HandleRequest
├── help.go                   # /v1/<path>?help=1
├── sys_health.go             # /v1/sys/health
├── sys_init.go               # /v1/sys/init (PUT to initialize)
├── sys_seal.go               # /v1/sys/seal-status, /sys/seal, /sys/unseal
├── sys_rekey.go              # /v1/sys/rekey, /sys/rekey-recovery-key
├── sys_generate_root.go      # /v1/sys/generate-root
├── sys_leader.go             # /v1/sys/leader
├── sys_raft.go               # raft snapshot/restore endpoints
├── sys_metrics.go            # /v1/sys/metrics (Prometheus etc.)
├── sys_in_flight_requests.go # /v1/sys/in-flight-req
├── sys_feature_flags.go      # /v1/sys/internal/ui/feature-flags
├── cors.go                   # CORS preflight + middleware
├── options.go                # HandlerProperties (TLS info, listener config)
├── util.go, util_oss.go      # helpers; CE stub
├── assets.go, assets_stub.go # embeds the UI bundle
├── priority/                 # request prioritization
└── web_ui/                   # the embedded UI dist

Key abstractions

Symbol	File	Description
Handler	http/handler.go	The wrapping http.Handler that builds the mux per listener.
HandlerProperties	http/options.go	Per-listener config: TLS, max request size, CORS, audit sockets.
handleSysSeal / handleSysUnseal / handleSysInit	http/sys_*.go	Pre-unseal endpoints that don't go through Core.
handleLogical	http/logical.go	The generic per-path handler used for everything that isn't a sys/ special case.
errInjectedHandler	http/handler.go	Test-only handler that injects errors.

How a request flows

sequenceDiagram
    participant L as TLS listener
    participant H as http.Handler
    participant C as cors.go
    participant Mux as ServeMux
    participant LH as handleLogical
    participant Core as vault.Core
    L->>H: net/http request
    H->>H: parse client IP, user agent, request ID
    H->>C: CORS preflight if OPTIONS
    H->>Mux: route by URL prefix
    Mux->>LH: /v1/* (everything except sys/init|seal|unseal)
    LH->>Core: Core.HandleRequest(*logical.Request)
    Core-->>LH: *logical.Response or error
    LH->>L: JSON body, headers

Special endpoints

Some endpoints are handled directly by http/ without going through Core.HandleRequest:

• /v1/sys/init, /v1/sys/init-status
• /v1/sys/seal, /v1/sys/unseal, /v1/sys/seal-status
• /v1/sys/raft/snapshot, /v1/sys/storage/raft/...
• /v1/sys/metrics and pprof endpoints
• /v1/sys/health (always responds, even when sealed)
• /v1/sys/in-flight-req (debug)
• /v1/sys/wrapping/* (response wrapping)

These are special because they need to work pre-unseal or because they bypass policy checks that don't make sense for them.

Headers

http/handler.go defines and parses a lot of Vault-specific headers:

Header	Purpose
X-Vault-Token	Authentication token.
X-Vault-Wrap-TTL, X-Vault-Wrap-Format	Request response wrapping.
X-Vault-No-Request-Forwarding	Don't forward to active node from a standby.
X-Vault-MFA	Login MFA credentials.
X-Vault-Policy-Override	Override soft-mandatory Sentinel policies.
X-Vault-Index, X-Vault-Inconsistent, X-Vault-Forward	Read-after-write consistency negotiation.
X-Vault-Namespace	Namespace selection.

Integration points

• Built by command/server.go per listener and wrapped with TLS, mlock, gzip.
• Calls into vault.Core for everything that isn't a special endpoint.
• Embeds the UI bundle from http/web_ui/ and serves it at /ui.
• Registers raft snapshot endpoints used by vault operator raft snapshot save|restore.
• Honors internalshared/configutil/'s Listener settings (CORS, max request size, …).

Entry points for modification

• Add a new top-level endpoint: register it in http/handler.go's Handler builder. Keep generic logical paths under /v1/<mount>/....
• Add a new pre-unseal handler: model after http/sys_seal.go — these handlers must never call methods that require the barrier to be open.
• Tweak CORS: see http/cors.go and vault/cors.go.
• Add a request-prioritization tier: http/priority/.