README
¶
pkg/server
This package is the runtime assembly layer for the identity API process.
Intent
pkg/server is where the identity service turns its documented building blocks into one running
HTTP server.
It does not own the shared generic server framework in the way ../core/pkg/server does, and it
does not own business behaviour in the way handlers do. Instead it composes:
- the shared
coreserver substrate - identity-specific authn/authz and trust middleware
- the concrete handler layer
- the helper services those layers depend on
into one application-level runtime pipeline.
What Is Specific Here
Identity Runtime Composition
This package wires together the process-wide services that the rest of the API stack relies on:
josefor token cryptography and JWKS/signing-key lifecycleuserdbfor local identity resolutionrbacfor effective authority constructionoauth2for built-in token and session handling- middleware for request-time trust assembly
- handlers for resource-specific API behaviour
That makes pkg/server the place where separately documented packages become one coherent identity
service.
Shared Core Stack Plus Local Trust Stack
The package deliberately composes two layers of middleware:
- the shared pre-routing server pipeline from
core - the identity-specific post-routing trust pipeline
This split is important because it preserves platform-wide request behaviour while still allowing identity to inject its own authentication, authorization, principal, validation, and audit model.
Middleware Ordering
The ordering here is intentional and should be read as precedent for other API services.
Pre-Routing Shared Middleware
The core middleware stack is applied directly to the raw router in this order:
- OpenTelemetry
- logging
- route resolver
- CORS
The reasons matter:
- OpenTelemetry must run first so trace context exists before anything else happens.
- Logging must run early so even requests that fail before deep routing or service-specific middleware still get captured, and so those logs can include the trace context established earlier.
- Route resolution must happen before middleware that depends on OpenAPI operation/schema metadata.
- CORS comes after route resolution because its schema-driven
OPTIONSbehaviour depends on the resolved route information.
This is dependency layering, not arbitrary taste. Each stage establishes context the next stage needs.
Post-Routing Identity Middleware
Identity-specific middleware is then attached through the generated OpenAPI server wrapper.
The current stack is:
- OpenAPI validator / local authorizer
- audit
Those are applied in reverse by the generated router wrapper, so the validator/authorizer becomes the inner trust-establishing layer around handlers, and audit wraps the resulting handler execution with normalized identity and authorization context already available.
The important architectural rule is:
- generic transport/request context first
- route/schema context next
- service-specific trust context after routing
- audit and handlers after trust context exists
Runtime Flow
At a high level, GetServer() does the following:
- build the OpenAPI schema helper
- create the raw router
- install the shared
coremiddleware stack - install generic
NotFoundandMethodNotAllowedhandling - construct process-wide identity helper services (
jose,userdb,rbac,oauth2) - construct identity-specific middleware (
localauthorizer, validator, audit) - construct the top-level handler implementation
- attach everything through the generated OpenAPI router and return
http.Server
This makes the trust pipeline an application-level invariant rather than a handler-by-handler convention.
Invariants
pkg/serverowns runtime composition, not business-domain behaviour- the shared
coremiddleware stack runs before identity-specific middleware - middleware ordering is part of the package contract because later stages depend on context from earlier stages
jose,userdb,rbac, andoauth2are process-wide shared services in the API server- generated OpenAPI routing, validation, and schema helpers are load-bearing parts of the runtime model
Caveats
- The package is highly ordering-sensitive. Small changes in middleware order can change trust, observability, or schema behaviour materially.
- Because this package is orchestration-heavy, stale documentation here is especially risky: it can give a false picture of how the service actually behaves at runtime.
- The package is intentionally coupled to the current built-in identity stack. Changing the authn or trust model would require coordinated changes across several of the composed subsystems.
Related Documentation
../core/pkg/server, which defines the shared server substrate this package builds on../core/pkg/server/middleware, which defines the canonical shared pre-routing middleware pipeline composed herepkg/middleware, which defines the identity-specific trust pipeline attached after routingpkg/handler, which defines the resource-specific API behaviour invoked once request context has been normalizedpkg/userdb,pkg/rbac,pkg/oauth2, andpkg/jose, which are the main process-wide helper services assembled here
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
Namespace string
// ListenAddress tells the server what to listen on, you shouldn't
// need to change this, its already non-privileged and the default
// should be modified to avoid clashes with other services e.g prometheus.
ListenAddress string
// ReadTimeout defines how long before we give up on the client,
// this should be fairly short.
ReadTimeout time.Duration
// ReadHeaderTimeout defines how long before we give up on the client,
// this should be fairly short.
ReadHeaderTimeout time.Duration
// WriteTimeout defines how long we take to respond before we give up.
// Ideally we'd like this to be short, but Openstack in general sucks
// for performance. Additionally some calls like cluster creation can
// do a cascading create, e.g. create a default control plane, than in
// turn creates a project.
WriteTimeout time.Duration
// RequestTimeout places a hard limit on all requests lengths.
RequestTimeout time.Duration
}
Options allows server options to be overridden.
type Server ¶
type Server struct {
// CoreOptions are all common across everything e.g. namespace.
CoreOptions options.CoreOptions
// ServerOptions are server specific options e.g. listener address etc.
ServerOptions options.ServerOptions
// HandlerOptions sets options for the HTTP handler.
HandlerOptions handler.Options
// JoseOptions sets options for JWE.
JoseOptions jose.Options
// OAuth2Options sets options for the oauth2/oidc authenticator.
OAuth2Options oauth2.Options
// CORSOptions are for remote resource sharing.
CORSOptions cors.Options
// RBACOptions are for RBAC related things.
RBACOptions rbac.Options
// OpenAPIOptions are for OpenAPI processing.
OpenAPIOptions openapimiddleware.Options
}
func (*Server) SetupLogging ¶
func (s *Server) SetupLogging()
Source Files