Crate product_os_server

Expand description

Product OS Server

A server library supporting HTTP/HTTPS, TLS, WebSockets, Server-Sent Events (SSE), and command-and-control distributed networking.

§Features

HTTP/HTTPS Servers: Full-featured web servers with TLS support
Dual Protocol Support: Serve both HTTP and HTTPS simultaneously
Security: Built-in CSP, CSRF protection, security headers
Compression: Gzip, Deflate, and Brotli compression support
WebSockets: Native WebSocket handler support
SSE: Server-Sent Events for real-time updates
CORS: Configurable Cross-Origin Resource Sharing
Command & Control: Distributed network capabilities with authentication
Flexible Executors: Support for Tokio and custom executors
no_std Support: Can be used in embedded environments with appropriate features

§Example

use product_os_server::{ProductOSServer, StatusCode, Response, Body};
use product_os_server::ServerConfig;
use product_os_async_executor::TokioExecutor;

// Create server with default configuration
let config = ServerConfig::new();
let mut server: ProductOSServer<(), TokioExecutor, _> = 
    ProductOSServer::new_with_config(config);

// Add a simple GET handler
async fn hello_handler() -> Result<Response<Body>, StatusCode> {
    Ok(Response::new(Body::empty()))
}

server.add_get("/hello", hello_handler);

// Start the server (non-blocking)
// server.start(false).await?;

§Feature Flags

core: Core server functionality (hyper, axum, tracing)
executor_tokio: Tokio executor support
tls: HTTPS/TLS support via rustls
dual_server: Dual HTTP/HTTPS protocol support
cors: CORS middleware
ws: WebSocket support
sse: Server-Sent Events support
compression: Response compression (gzip, deflate, brotli)
cspolicy: Content Security Policy headers
csrf: CSRF protection
controller: Command and control distributed networking. Route handlers use Axum extractors, so this feature requires framework_axum or flow_axum_compat. Pure framework_flow supports the controller lifecycle but not the HTTP command endpoints.
middleware: Extended middleware support
extract_headers: Typed header extraction (requires framework_axum or flow_axum_compat)

§Framework Selection

Choose exactly one framework (they are mutually exclusive):

Framework	Cargo flags	Notes
Axum (default)	`--features framework_axum,core,executor_tokio`	Full feature support
Flow + Axum compat	`--no-default-features --features flow_axum_compat,core,executor_tokio`	Flow router with Axum types
Pure Flow	`--no-default-features --features framework_flow,core,executor_tokio`	Minimal, no Axum dependency

Important: When using framework_flow or flow_axum_compat, you must pass --no-default-features because the default features include framework_axum.

§Safety and Security

This crate provides security features including:

TLS/HTTPS with rustls
Content Security Policy configuration
CSRF token validation
Security headers (HSTS, X-Frame-Options, etc.)
Authentication for command-and-control operations

Always review your configuration for your specific security requirements.

Re-exports§

pub use error::ProductOSServerError;
pub use error::Result as ServerResult;
pub use config::ServerConfig;
pub use config::Network;
pub use config::Certificate;
pub use config::CertificateFiles;
pub use config::CertificateFilesKind;
pub use config::Compression;

Modules§

config: Server configuration types (Network, Certificate, Compression, ServerConfig) Server configuration types
error: Error types for server operations. Error types for Product OS Server

Structs§

Body: The body type used in axum requests and responses.
BodyBytes: A concrete implementation of an HTTP body.
Bytes: A cheaply cloneable and sliceable chunk of contiguous memory.
ConnectInfo: Extractor for getting connection information produced by a Connected.
Extension: Extractor that gets a value from request extensions.
Form: URL encoded extractor and response.
Json: JSON Extractor / Response.
Path: Extractor that will get captures from the URL and parse them using serde.
ProductOSServer: The main server struct for Product OS Server
Query: Extractor that deserializes query strings into some type.
Request: Represents an HTTP request.
RequestId: Request ID extractor.
Response: Represents an HTTP response
Scheme: Represents the scheme component of a URI
ServiceBuilder: Declaratively construct Service values.
State: Extractor for state.
StatusCode: An HTTP status code (status-code in RFC 9110 et al.).
TraceContext: Parsed W3C traceparent header.
Uri: The URI component of a request.

Enums§

ExecutorType: Specifies which async executor implementation to use for the server.
Method: HTTP request method enumeration
ProductOSRouter: Main router enum for Product OS Router

Traits§

Handler: Trait for async functions that can be used to handle requests.
HttpBody: Trait representing a streaming body of a Request or Response.
IntoResponse: Trait for generating responses.
Layer: Decorates a Service, transforming either the request or the response.
Service: An asynchronous function from a Request to a Response.
ServiceExt: An extension trait for Services that provides a variety of convenient adapters

Functions§

service_fn: Returns a new ServiceFn with the given closure.

Type Aliases§

BoxError: Alias for a type-erased error type.