Crate stateset_http 

StateSet HTTP

HTTP service layer (REST + SSE) for the StateSet embedded commerce engine.

Turns stateset_embedded::Commerce into a real HTTP API powered by axum, complete with JSON endpoints, pagination, Server-Sent Events, CORS, request-ID tracing, and structured error responses.

Quick Start

use stateset_embedded::Commerce;
use stateset_http::ServerBuilder;
use std::net::SocketAddr;

let commerce = Commerce::new(":memory:")?;
let addr: SocketAddr = "0.0.0.0:3000".parse()?;

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

Architecture

┌────────────────────────────────────────────────┐
│                  HTTP Client                   │
│  ┌──────────────────────────────────────────┐  │
│  │         axum Router (this crate)         │  │
│  │  ┌────────────────────────────────────┐  │  │
│  │  │  stateset-embedded (Commerce)      │  │  │
│  │  │  ┌──────────────────────────────┐  │  │  │
│  │  │  │  SQLite / PostgreSQL         │  │  │  │
│  │  │  └──────────────────────────────┘  │  │  │
│  │  └────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘

Re-exports

pub use routes::api_router;

Modules

etag

ETag generation and conditional request helpers.

openapi

OpenAPI specification generation.

routes

Route modules and router assembly.

Structs

AddressDto

Address DTO shared by orders and customers.

AppState

Shared application state injected into every route handler via axum::extract::State.

CreateCustomerRequest

Request body for POST /api/v1/customers.

CreateInvoiceRequest

Request body for POST /api/v1/invoices.

CreateOrderItemRequest

A single line item in a create-order request.

CreateOrderRequest

Request body for POST /api/v1/orders.

CreatePaymentRequest

Request body for POST /api/v1/payments.

CreateProductRequest

Request body for POST /api/v1/products.

CreateRefundRequest

Request body for POST /api/v1/payments/:id/refund.

CreateReturnItemRequest

A single item in a create-return request.

CreateReturnRequest

Request body for POST /api/v1/returns.

CreateShipmentRequest

Request body for POST /api/v1/shipments.

CustomerFilterParams

Query parameters for GET /api/v1/customers with filtering.

CustomerListResponse

Response body for GET /api/v1/customers (list).

CustomerResponse

Response body for a single customer.

EventStreamParams

Query parameters for the SSE event stream endpoint.

HealthResponse

Response body for GET /health.

InventoryAdjustRequest

Request body for POST /api/v1/inventory/:sku/adjust.

InventoryFilterParams

Query parameters for GET /api/v1/inventory with filtering.

InventoryItemResponse

Response body for a single inventory item (list view).

InventoryListResponse

Response body for GET /api/v1/inventory (list).

InventoryResponse

Response body for inventory stock levels.

InvoiceFilterParams

Query parameters for GET /api/v1/invoices with filtering.

InvoiceListResponse

Response body for GET /api/v1/invoices (list).

InvoiceResponse

Response body for a single invoice.

IpCidr

CIDR block used for trusted proxy checks.

MetricsHeaderLimits

Maximum accepted byte lengths for metrics-related forwarding headers.

OrderFilterParams

Query parameters for GET /api/v1/orders with filtering.

OrderItemResponse

A single line item in an order response.

OrderListResponse

Response body for GET /api/v1/orders (list).

OrderResponse

Response body for a single order.

PaginationParams

Query parameters for paginated list endpoints.

PaymentFilterParams

Query parameters for GET /api/v1/payments with filtering.

PaymentListResponse

Response body for GET /api/v1/payments (list).

PaymentResponse

Response body for a single payment.

ProductFilterParams

Query parameters for GET /api/v1/products with filtering.

ProductListResponse

Response body for GET /api/v1/products (list).

ProductResponse

Response body for a single product.

ReadyResponse

Response body for GET /health/ready.

RecordInvoicePaymentRequest

Request body for POST /api/v1/invoices/:id/payments.

ReturnFilterParams

Query parameters for GET /api/v1/returns with filtering.

ReturnListResponse

Response body for GET /api/v1/returns (list).

ReturnResponse

Response body for a single return.

ServerBuilder

Builder for configuring and launching the HTTP server.

ShipmentFilterParams

Query parameters for GET /api/v1/shipments with filtering.

ShipmentListResponse

Response body for GET /api/v1/shipments (list).

ShipmentResponse

Response body for a single shipment.

TenantCacheResponse

Tenant cache status included in health and readiness responses.

UpdateCustomerRequest

Request body for PATCH /api/v1/customers/:id.

UpdateProductRequest

Request body for PATCH /api/v1/products/:id.

VersionResponse

Response body for GET /version — build & release metadata.

Enums

HttpError

HTTP error wrapper that maps domain errors to appropriate HTTP responses.

Functions

decode_cursor

Decode a keyset cursor into (sort_key, id).

encode_cursor

Encode a keyset cursor from (sort_key, id).

finalize_page

Trim an overfetched page back to the requested size and return has_more.

overfetch_limit

Request one extra row to detect whether another page exists.