Crate polaris_app 

Shared HTTP server runtime for Polaris products.

polaris_app provides an axum-based HTTP server that integrates with the Polaris plugin lifecycle. Plugins register route fragments during build() via the HttpRouter API, and AppPlugin merges and serves them with Tower middleware (CORS, tracing, request ID).

This crate is the shared infrastructure for polaris-http, polaris-mcp (SSE transport), and any future product that needs an HTTP interface.

Architecture

AppPlugin (axum server lifecycle)
  ├── HttpRouter API (route and auth registration)
  ├── WsRouter API (WebSocket route registration, `ws` feature)
  ├── AppConfig (host, port, CORS)
  ├── ServerHandle (shutdown signal, API)
  ├── AuthProvider trait (pluggable authentication)
  ├── Tower middleware (CORS, tracing, request ID, auth)
  └── RequestContextPlugin (trace/correlation/request IDs)

Request Context

RequestContext carries trace_id, correlation_id, and request_id for observability and propagation. Two entry points:

• Custom axum handlers — RequestContext implements FromRequestParts with Rejection = Infallible, so handlers can accept it as an argument.
• Session graphs — handlers insert HttpHeaders into the setup closure, and RequestContextPlugin’s OnGraphStart hook turns them into a RequestContext that systems read via Res<RequestContext>.

The pure core is RequestContext::from_headers, lenient by design: missing headers become None, never a rejection.

Feature Flags

• ws — enables WsRouter for plugin-contributed WebSocket routes

Quick Start

use polaris_system::server::Server;
use polaris_app::{AppPlugin, AppConfig, HttpRouter};
use axum::{Router, routing::get};

let mut server = Server::new();
server.add_plugins(
    AppPlugin::new(AppConfig::new().with_port(8080))
);
// Other plugins register routes via HttpRouter in their build()

Plugin Route Registration

Any plugin that depends on AppPlugin can register routes:

use polaris_system::plugin::{Plugin, PluginId, Version};
use polaris_system::server::Server;
use polaris_app::{AppPlugin, HttpRouter};
use axum::{Router, routing::get};

struct HealthPlugin;

impl Plugin for HealthPlugin {
    const ID: &'static str = "myapp::health";
    const VERSION: Version = Version::new(0, 1, 0);

    fn build(&self, server: &mut Server) {
        let router = Router::new().route("/healthz", get(|| async { "ok" }));
        server.api::<HttpRouter>()
            .expect("AppPlugin must be added first")
            .add_routes(router);
    }

    fn dependencies(&self) -> Vec<PluginId> {
        vec![PluginId::of::<AppPlugin>()]
    }
}

See Also

For the full framework guide, deferred router construction (add_routes_with), and HTTP integration patterns, see the polaris-ai crate documentation.

Re-exports

pub use auth::AuthProvider;

pub use config::AppConfig;

pub use plugin::AppPlugin;

pub use plugin::ServerHandle;

pub use public_route::PublicPath;

pub use public_route::PublicPrefix;

pub use public_route::PublicRouteError;

pub use request_context::HttpHeaders;

pub use request_context::RequestContext;

pub use request_context::RequestContextPlugin;

pub use router::HttpRouter;

pub use ws::WsRouter;ws

Modules

auth

Pluggable authentication for HTTP routes.

config

HTTP server configuration.

plugin

AppPlugin — HTTP server lifecycle management.

public_route

Validated newtypes for public-route configuration.

request_context

Request context plugin for propagating trace and correlation IDs.

router

Route registration API for plugins.

wsws

WebSocket route registration API for plugins.