HTTP Transport Layer and API Router

The HTTP Transport Layer in Palyra provides the primary surface for the Web Console, administrative operations, and sandboxed Canvas interactions. Built on the axum framework, it manages three distinct API namespaces, implements critical security middleware (CSRF, Rate Limiting, Session Management), and serves the compiled React frontend.

Core Router Architecture

The central entry point for the HTTP server is the build_router function. It organizes the system into hierarchical route groups, each with specialized middleware stacks.

API Surface	Path Prefix	Purpose
Admin	`/admin/v1`	Low-level system diagnostics, journal inspection, and manual run management.
Console	`/console/v1`	Backend for the React Web Console (Sessions, Agents, Auth, Settings).
Canvas	`/canvas/v1`	Sandboxed environment for agent-generated UI components (A2UI).
Health	`/healthz`	Liveness and readiness probes.
Web UI	`/`	Static file serving for the React dashboard.

Diagram: HTTP Request Flow and Routing Sources: crates/palyra-daemon/src/transport/http/router.rs#17-300, crates/palyra-daemon/src/transport/http/middleware.rs#28-107

API Surface Areas

1. Admin API (`/admin/v1`)

The Admin API is designed for operators and automated scripts. It provides access to the JournalStore and orchestration state.

Journal Inspection: admin_journal_recent_handler allows querying the append-only ledger crates/palyra-daemon/src/transport/http/router.rs#20-20.
Run Control: Handlers like admin_run_cancel_handler allow manual termination of agentic runs crates/palyra-daemon/src/transport/http/router.rs#24-24.
Channel Operations: Provides deep health checks and queue management (pause/resume/drain) for connectors crates/palyra-daemon/src/transport/http/router.rs#43-57.

2. Console API (`/console/v1`)

The Console API powers the React-based management interface. It relies heavily on session-based authentication and CSRF protection.

Chat & Sessions: Manages the conversation lineage, branching, and real-time transcript streaming via console::chat and console::sessions crates/palyra-daemon/src/transport/http/handlers/console/mod.rs#8-23.
Access Control: Handlers in console::access manage API tokens, workspace memberships, and feature flags crates/palyra-daemon/src/transport/http/handlers/console/access.rs#73-150.
Auth Handoff: The console_browser_handoff_handler facilitates moving sessions between the CLI/Desktop and a local browser crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-159.

3. Canvas API (`/canvas/v1`)

The Canvas API provides the backend for the “Agent-to-User Interface” (A2UI). It serves assets and state to sandboxed iframes.

Security: Uses canvas_security_headers_middleware to ensure isolation crates/palyra-daemon/src/transport/http/middleware.rs#109-122.
Rate Limiting: Implements strict IP-based buckets to prevent malicious agent-generated code from DoS-ing the daemon crates/palyra-daemon/src/transport/http/middleware.rs#24-26.

Sources: crates/palyra-daemon/src/transport/http/router.rs#18-240, crates/palyra-daemon/src/transport/http/handlers/console/mod.rs#1-28

Security Middleware and Authentication

The HTTP layer enforces security through a multi-layered middleware approach.

Middleware	File Reference	Functionality
CSRF Protection	`middleware.rs`	Enforced via `console_session_cookie_refresh_middleware` which validates and rotates session tokens crates/palyra-daemon/src/transport/http/middleware.rs#87-107.
Rate Limiting	`middleware.rs`	`admin_rate_limit_middleware` tracks IP buckets using `Instant` to enforce request quotas crates/palyra-daemon/src/transport/http/middleware.rs#172-204.
Security Headers	`middleware.rs`	`apply_admin_console_security_headers` injects `no-store`, `nosniff`, and `frame-ancestors 'none'` crates/palyra-daemon/src/transport/http/middleware.rs#37-52.
Observability	`middleware.rs`	`console_observability_middleware` records all mutations (POST/PUT/DELETE) into the `ObservabilityState` crates/palyra-daemon/src/transport/http/middleware.rs#54-85.

Diagram: Authentication and Session Issuance Sources: crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111, crates/palyra-daemon/src/transport/http/middleware.rs#99-107

Web UI Serving

The web_ui_entry_handler is responsible for serving the React application. It supports multiple resolution strategies to find the dashboard assets, prioritized as follows:

PALYRA_WEB_DIST_DIR environment variable crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#13-13.
Colocated web/ directory relative to the executable crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#135-135.
Development path apps/web/dist within the repository structure crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#138-138.

The handler implements a “Single Page Application” (SPA) fallback: if a requested path does not exist as a file and lacks a file extension, it serves index.html to allow client-side routing crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#187-192. Sources: crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#16-34, crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#125-148

​Core Router Architecture

​API Surface Areas

​1. Admin API (/admin/v1)

​2. Console API (/console/v1)

​3. Canvas API (/canvas/v1)

​Security Middleware and Authentication

​Web UI Serving