server

package
v1.29.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

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 core server 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:

  • jose for token cryptography and JWKS/signing-key lifecycle
  • userdb for local identity resolution
  • rbac for effective authority construction
  • oauth2 for 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:

  1. request deadline
  2. OpenTelemetry
  3. logging
  4. RED metrics
  5. route resolver
  6. CORS

The reasons matter:

  • The request deadline runs first so it bounds all later work. The server's write timeout stops response writes but does not cancel the request context, so the deadline is the shorter of --server-request-timeout and --server-write-timeout minus two seconds. Those two seconds cover organization Lease cleanup and the response write. The server refuses to start if the deadline is shorter than an organization Lease takeover plus its critical section (see pkg/handler/allocations).
  • 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.
  • RED metrics wrap route resolution so unmatched requests are recorded. The resolver supplies matched requests' stable OpenAPI paths, never resource IDs.
  • Route resolution must happen before middleware that depends on OpenAPI operation/schema metadata.
  • CORS comes after route resolution because its schema-driven OPTIONS behaviour 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:

  1. build the OpenAPI schema helper
  2. create the raw router
  3. compute the request deadline and install the shared core middleware stack
  4. install generic NotFound and MethodNotAllowed handling
  5. construct process-wide identity helper services (jose, userdb, rbac, oauth2)
  6. construct identity-specific middleware (local authorizer, validator, audit)
  7. construct the top-level handler implementation
  8. attach everything through the generated OpenAPI router and return http.Server

The command process publishes build metadata for its lifetime. It serves readiness on /readyz on a separate health listener (:6081), which the Service does not expose, so the ingress cannot route to it; other pods can still reach it on the Pod IP unless a NetworkPolicy prevents that, and the chart does not install one. A failing probe gets a bare 503; the cause is logged. A replica is ready when it is not shutting down and it has read the primary token signing key once. The key is cluster-wide state written by the JOSE leader, so on a fresh install every replica stays not ready until the first leader has written it. After that first read the probe does not call the API server, so an API server slowdown cannot take every replica out of service together. Leadership itself, external OIDC providers and the audit collector do not gate readiness.

On SIGTERM the process reports not ready, keeps serving for 5 seconds so endpoint removal reaches every node, then stops the background work and drains in-flight requests for up to 10 seconds. Metrics stay served for 35 seconds after the drain, longer than the 30 second scrape interval, so the drain's requests are scraped. It exits once that has finished. The chart's 60 second termination grace period covers all three; pkg/server/shutdown.go owns the timings.

This makes the trust pipeline an application-level invariant rather than a handler-by-handler convention.

Invariants

  • pkg/server owns runtime composition, not business-domain behaviour
  • the shared core middleware 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, and oauth2 are process-wide shared services in the API server
  • the API server has one synchronized informer cache. The token check, the ACL build, passport exchange and the organization list read only the cache, so they make no API server call. Reads that decide a write, and other handlers' resource reads, use the direct client; see pkg/oauth2 and pkg/handler
  • each API server replica keeps only state it can rebuild locally: its informer cache and its ACL cache. Authorization codes, sessions, allocation admission and quota changes are decided on direct reads or per-organization Kubernetes Leases. A write, a revocation included, reaches a replica's cached reads within that replica's watch lag
  • JOSE key rotation is leader-elected through its Kubernetes Lease. Every replica reads the shared SigningKey resource through its cache, so a rotation reaches it within its watch lag; see pkg/jose
  • generated OpenAPI routing, validation, and schema helpers are load-bearing parts of the runtime model
  • API readiness means this replica can serve a request end to end: not shutting down and signing key read. The read cache syncs before the listener binds, so it needs no check. The unikorn_server_ready metric reports listener ownership only

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.
  • A lost API server that held an organization Lease delays that organization's allocation or quota requests until a contender has seen the Lease unchanged for its three-second duration and takes it over. The default eight-second request deadline leaves time for that and the critical section; a request that runs out of time gets a retryable HTTP 409. Other organizations and login traffic continue through remaining replicas.

Documentation

Index

Constants

View Source
const HealthListenAddress = ":6081"

HealthListenAddress serves the readiness probe. The Service does not expose it, so the ingress cannot route to it.

Variables

This section is empty.

Functions

func NewHealthServer added in v1.27.0

func NewHealthServer(ready *readiness.Checker) *http.Server

NewHealthServer serves the readiness probe on /readyz.

func Serve added in v1.27.0

func Serve(serve func() error, server Shutdowner, ready *readiness.Checker, stopBackground, stopMetrics context.CancelFunc, stop <-chan struct{}) error

Serve runs serve until stop closes, then takes the replica out of service with server's Shutdown. It returns once the drain has finished and metrics have been served for one more scrape, so the process does not exit while requests are in flight or before the drain's metrics are collected.

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.

func (*Options) AddFlags

func (o *Options) AddFlags(f *pflag.FlagSet)

addFlags allows server options to be modified.

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

	// AuditOptions optionally ship audit records to an external collector,
	// in addition to the structured log, which is always emitted.
	AuditOptions *audit.Options
}

func (*Server) AddFlags

func (s *Server) AddFlags(flags *pflag.FlagSet)

func (*Server) GetServer

func (s *Server) GetServer(ctx context.Context, client client.Client, readCache client.Reader, ready *readiness.Checker) (*http.Server, error)

GetServer assembles the HTTP server. Background work it starts, such as the JOSE leader election, stops when ctx ends. The readiness checker gains the conditions the handler graph adds. client writes and serves the reads that decide a write; readCache, the informer cache, serves every other read, so the per-request token check, ACL build and passport exchange make no API server call.

func (*Server) SetupLogging

func (s *Server) SetupLogging()

type Shutdowner added in v1.27.0

type Shutdowner interface {
	Shutdown(ctx context.Context) error
}

Shutdowner is the part of http.Server that drains and stops it.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL