README
¶
pkg/server/middleware
Intention
pkg/server/middleware provides the canonical shared middleware stack for platform APIs. It contains the common request-pipeline components that platform services are expected to compose before adding any service-specific middleware of their own.
The subpackages are cooperative and order-sensitive rather than interchangeable. They establish trace context and correlated logging context, resolve OpenAPI route metadata, implement schema-driven CORS behavior, and add request-context timeouts. The root package also provides generic response-capture helpers used by tests and by middleware patterns that need to inspect responses.
This package does not try to own every middleware concern in the platform. Service-specific middleware still belongs with the service that owns the behavior, for example identity-specific authentication and authorization layers.
For the OpenAPI route-resolution contract that this stack depends on, see pkg/openapi/README.md.
Invariants And Guard Rails
- This is the canonical shared middleware stack for platform APIs, not a miscellaneous collection of unrelated HTTP helpers.
- Middleware in this directory is designed to cooperate as a request pipeline. Ordering is part of the contract.
opentelemetrymust establish trace context early because the trace ID is a customer-facing correlation handle for failures and a primary way to connect support requests to logs and telemetry.loggingdepends on request context and response metrics to produce useful request and response records without exposing obviously sensitive headers.routeresolveris load-bearing shared middleware. It resolves OpenAPI route metadata once and stashes it in context for downstream consumers. See pkg/openapi/README.md.corsdepends on that resolved route information, especially for emulatedOPTIONShandling.timeoutadds request-context deadlines. Downstream handlers and middleware must respect context cancellation for it to be effective.- Service packages may add their own middleware, but domain-specific concerns should live with the package that owns the behavior rather than being pushed into this shared stack.
Caveats
- The root package boundary is slightly awkward:
Captureis generic response-capture infrastructure, while most of the real behavior lives in subpackages. - Middleware ordering is not optional. Reordering pieces such as route resolution and CORS can change behavior or break schema-driven handling.
timeoutis intentionally simple context wrapping, not a full response-timeout or request-abort framework. Work that ignores context can outlive the intended deadline.- The canonical shared stack is not exhaustive. Service-specific packages will still define additional middleware where the behavior is not platform-generic.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capture ¶ added in v1.4.0
type Capture struct {
// contains filtered or unexported fields
}
func CaptureResponse ¶ added in v1.4.0
CaptureResponse runs the given http.Handler and returns the captured response. To see headers, look at `w.Header()`, which will be mutated by the handler.
func NewCapture ¶ added in v1.4.0
func NewCapture() *Capture
NewCapture creates a ready-to-use Capture. You use it by calling `Wrap` on an `http.ResponseWriter`, using the result in a handler, then examining the capture StatusCode() and Body(). The convenience `CaptureResponse(...)` below does the above given the http.Handler, and hands you back the capture.
func (*Capture) StatusCode ¶ added in v1.4.0
func (*Capture) Wrap ¶ added in v1.4.0
func (c *Capture) Wrap(w http.ResponseWriter) http.ResponseWriter
Wrap creates a http.ResponseWriter which will capture the response in the method receiver so it can be examined after being used in a handler. Consider using `CaptureResponse()`, which does this for you.
type LoggingResponseWriter ¶
type LoggingResponseWriter struct {
http.ResponseWriter
*Capture
}
LoggingResponseWriter wraps a ResponseWriter in such a way that the response status code, body and headers can be examined after its been used to serve a response. This is deprecated: use Capture.Wrap(w) instead, because it wraps the ResponseWriter such that additional interfaces (e.g., io.ReaderFrom) that may be present on the supplied ResponseWriter are still supported in the wrapper.
func NewLoggingResponseWriter ¶
func NewLoggingResponseWriter(next http.ResponseWriter) *LoggingResponseWriter
Source Files
Directories