Struct ServerBuilder 

pub struct ServerBuilder { /* private fields */ }

Builder for configuring and launching the HTTP server.

Example

use stateset_embedded::Commerce;
use stateset_http::ServerBuilder;

let commerce = Commerce::new(":memory:")?;

ServerBuilder::new_from_env(commerce)?
    .bind("0.0.0.0:8080".parse()?)
    .with_cors()
    .with_request_id()
    .with_bearer_auth("replace-me-with-a-secret")
    .serve()
    .await?;

Implementations

impl ServerBuilder

pub fn new(commerce: Commerce) -> Self

Create a new server builder wrapping a Commerce instance.

pub fn new_from_env(commerce: Commerce) -> Result<Self, HttpError>

Create a new server builder and apply /metrics network policy from environment.

This is useful for startup wiring where operators configure network policy via:

• STATESET_HTTP_METRICS_IP_ALLOWLIST
• STATESET_HTTP_METRICS_IP_CIDR_ALLOWLIST
• STATESET_HTTP_METRICS_TRUSTED_PROXIES
• STATESET_HTTP_METRICS_FORWARDED_MAX_BYTES
• STATESET_HTTP_METRICS_X_FORWARDED_FOR_MAX_BYTES
• STATESET_HTTP_METRICS_X_REAL_IP_MAX_BYTES
• STATESET_HTTP_METRICS_AUTHORIZATION_MAX_BYTES
• STATESET_HTTP_ALLOW_UNAUTHENTICATED

pub fn with_allow_unauthenticated_from_env(self) -> Result<Self, HttpError>

Apply the unauthenticated opt-out from STATESET_HTTP_ALLOW_UNAUTHENTICATED.

Accepts true/false (also 1/0, yes/no). Unset or empty leaves the secure default (false) in place.

pub const fn require_idempotency_keys(self, require: bool) -> Self

Require an Idempotency-Key header on money-moving create endpoints (POST /orders, /payments, /payments/{id}/refund, /ap/payments), returning HTTP 428 (Precondition Required) when it is missing.

Defaults to true; pass false to let existing deployments opt out.

pub fn with_require_idempotency_keys_from_env(self) -> Result<Self, HttpError>

Apply the required-idempotency-key opt-out from STATESET_HTTP_REQUIRE_IDEMPOTENCY_KEYS.

Accepts true/false (also 1/0, yes/no). Unset or empty leaves the secure default (true) in place.

pub const fn bind(self, addr: SocketAddr) -> Self

Set the bind address.

pub const fn with_cors(self) -> Self

Enable CORS middleware with explicit defaults and optional env override.

Set STATESET_HTTP_ALLOWED_ORIGINS to a comma-separated list of origins to override the localhost-only defaults.

pub const fn with_request_id(self) -> Self

Enable request-ID middleware (generates UUID, propagates in headers).

pub fn with_bearer_auth(self, token: impl Into<String>) -> Self

Configure bearer authentication for /api/v1/* endpoints.

Requests to API routes must include Authorization: Bearer <token>.

pub fn with_metrics_bearer_auth(self, token: impl Into<String>) -> Self

Configure bearer authentication for /metrics.

pub fn without_metrics_auth(self) -> Self

Disable authentication for /metrics.

pub fn with_metrics_ip_allowlist<I>(self, ips: I) -> Self

where I: IntoIterator<Item = IpAddr>,

Configure a client IP allowlist for /metrics.

pub fn without_metrics_ip_allowlist(self) -> Self

Disable /metrics IP allowlist checks.

pub fn with_metrics_ip_cidr_allowlist<I>(self, cidrs: I) -> Self

where I: IntoIterator<Item = IpCidr>,

Configure a CIDR-based client IP allowlist for /metrics.

pub fn without_metrics_ip_cidr_allowlist(self) -> Self

Disable CIDR-based /metrics IP allowlist checks.

pub fn with_metrics_trusted_proxies<I>(self, cidrs: I) -> Self

where I: IntoIterator<Item = IpCidr>,

Configure trusted proxy CIDRs for /metrics.

pub fn with_metrics_header_limits(self, limits: MetricsHeaderLimits) -> Self

Configure max accepted forwarding header lengths for /metrics.

pub fn with_metrics_network_policy_from_env(self) -> Result<Self, HttpError>

Apply /metrics network policy from environment variables.

Supported variables (comma-separated entries):

• STATESET_HTTP_METRICS_IP_ALLOWLIST (exact IPs)
• STATESET_HTTP_METRICS_IP_CIDR_ALLOWLIST (CIDRs and/or IPs)
• STATESET_HTTP_METRICS_TRUSTED_PROXIES (CIDRs and/or IPs)

If a variable is present but empty, the corresponding config is disabled.

pub fn with_metrics_header_limits_from_env(self) -> Result<Self, HttpError>

Apply /metrics forwarding header limits from environment variables.

Supported variables (positive integers in bytes):

• STATESET_HTTP_METRICS_FORWARDED_MAX_BYTES
• STATESET_HTTP_METRICS_X_FORWARDED_FOR_MAX_BYTES
• STATESET_HTTP_METRICS_X_REAL_IP_MAX_BYTES
• STATESET_HTTP_METRICS_AUTHORIZATION_MAX_BYTES

pub fn with_request_body_limit_from_env(self) -> Result<Self, HttpError>

Apply the request body size limit from STATESET_HTTP_MAX_BODY_BYTES.

pub fn without_metrics_trusted_proxies(self) -> Self

Disable trusted proxy checks for /metrics.

pub fn bind_auth_tenant(self, tenant_id: impl Into<String>) -> Self

Bind the configured bearer token to a single tenant.

Requests using this token must present the same x-tenant-id.

pub fn bind_auth_actor(self, actor_id: impl Into<String>) -> Self

Bind the configured bearer token to a single actor.

When set, authenticated API requests are treated as this actor during authorization checks, and any conflicting x-actor-id header is rejected.

pub fn with_bearer_auth_for_tenant( self, token: impl Into<String>, tenant_id: impl Into<String>, ) -> Self

Configure bearer authentication and bind it to a tenant in one call.

pub fn with_bearer_auth_for_actor( self, token: impl Into<String>, actor_id: impl Into<String>, ) -> Self

Configure bearer authentication and bind it to an actor in one call.

pub fn add_bearer_auth(self, token: impl Into<String>) -> Self

Add an additional bearer token for /api/v1/* endpoints.

This leaves the primary configured API token unchanged.

pub fn add_bearer_auth_for_tenant( self, token: impl Into<String>, tenant_id: impl Into<String>, ) -> Self

Add an additional bearer token bound to a tenant.

pub fn add_bearer_auth_for_actor( self, token: impl Into<String>, actor_id: impl Into<String>, ) -> Self

Add an additional bearer token bound to an actor.

pub fn add_bearer_auth_for_actor_and_tenant( self, token: impl Into<String>, actor_id: impl Into<String>, tenant_id: impl Into<String>, ) -> Self

Add an additional bearer token bound to both an actor and a tenant.

pub fn with_tenant_db_dir(self, base_dir: impl Into<PathBuf>) -> Self

Enable per-tenant storage using <base_dir>/<tenant>.db.

pub fn with_ignore_tenant_header(self) -> Self

Ignore x-tenant-id headers when per-tenant routing is disabled.

By default such requests are rejected with 400 instead of silently being served shared data. Use this escape hatch only for deployments that intentionally front a multi-tenant proxy which handles tenant isolation upstream.

pub fn with_max_tenant_dbs(self, max_tenant_dbs: usize) -> Self

Set the maximum number of lazily created tenant databases kept in-memory.

pub const fn with_max_request_body_bytes( self, max_request_body_bytes: usize, ) -> Self

Set the maximum accepted request body size for extractor-based endpoints.

pub fn with_authz_engine(self, engine: AuthzEngine) -> Self

Enable request authorization for /api/v1/* using a provided authz engine.

By default, authorization expects actor identity to come from actor-bound bearer tokens. If you want to trust x-actor-id request headers instead, also call Self::trust_actor_headers_for_authz.

pub const fn trust_actor_headers_for_authz(self) -> Self

Explicitly trust x-actor-id request headers for authorization.

Use this only behind a trusted upstream that authenticates callers and strips or overwrites any client-supplied actor header.

pub const fn allow_unauthenticated(self) -> Self

Explicitly opt out of the fail-closed authentication startup check.

By default the server refuses to start on a non-loopback bind address when no API bearer tokens are configured. Call this (or set STATESET_HTTP_ALLOW_UNAUTHENTICATED=true) to acknowledge the risk and serve unauthenticated API traffic anyway.

pub const fn with_strict_authz(self) -> Self

Fail closed on authorization for unmapped API paths.

By default, /api/v1 paths that the authorization layer cannot map to a resource/action pair bypass authorization (authentication still applies). When strict mode is enabled, such requests are denied with HTTP 403 instead. Only takes effect when authorization is configured via Self::with_authz_engine.

pub fn without_auth(self) -> Self

Disable API authentication (not recommended for untrusted networks).

pub const fn with_rate_limit( self, requests_per_second: u64, burst_size: u64, ) -> Self

Enable global rate limiting with a token bucket.

requests_per_second controls steady-state throughput; burst_size controls how many requests can be served in a burst before throttling. Requests exceeding the limit receive HTTP 429.

pub fn bearer_auth_token(&self) -> Option<&str>

Return the configured bearer token, if auth is enabled.

pub fn metrics_bearer_auth_token(&self) -> Option<&str>

Return the configured bearer token for /metrics, if enabled.

pub fn metrics_ip_allowlist(&self) -> Option<Vec<IpAddr>>

Return configured metrics IP allowlist entries, if any.

pub fn metrics_ip_cidr_allowlist(&self) -> Option<Vec<IpCidr>>

Return configured CIDR-based metrics IP allowlist entries, if any.

pub fn metrics_trusted_proxies(&self) -> Option<Vec<IpCidr>>

Return configured trusted proxy CIDRs for /metrics, if any.

pub const fn metrics_header_limits(&self) -> MetricsHeaderLimits

Return configured max accepted forwarding header lengths for /metrics.

pub fn build(self) -> Router

Build the axum Router without starting the server.

Useful for testing or embedding in a larger application.

pub async fn serve(self) -> Result<(), HttpError>

Build the router and start serving HTTP requests.

This method will block until the server is shut down.

Trait Implementations

impl Debug for ServerBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.