axum framework and serves as the primary gateway for web-based management, canvas interactions, and third-party LLM integrations. It handles request routing, authentication via session cookies and bearer tokens, CSRF protection, and multi-tier rate limiting.
Router Architecture
The central router is constructed incrates/palyra-daemon/src/transport/http/router.rs and divides the API surface into four distinct domains, each with its own middleware stack and security requirements.
API Surface Overview
| API Domain | Path Prefix | Purpose | Auth Mechanism |
|---|---|---|---|
| Admin API | /admin/v1/* | System-level control and diagnostics. | Bearer Token / Custom Headers |
| Console API | /console/v1/* | Backend for the React Web Console. | Session Cookie + CSRF Header |
| Canvas API | /canvas/v1/* | Interactive UI component streaming. | Session Cookie |
| OpenAI Compat | /v1/* | OpenAI-compatible completions API. | API Key (Bearer) |
| Web UI | / | Static asset serving for the dashboard. | Public (Internal Redirects) |
Router Construction Data Flow
Thebuild_router function crates/palyra-daemon/src/transport/http/router.rs#17-17 composes these routes and applies specialized layers.
Sources: crates/palyra-daemon/src/transport/http/router.rs#17-258, crates/palyra-daemon/src/transport/http/middleware.rs#28-204
Security and Middleware
Authentication and Session Management
The daemon supports several authentication flows:- Admin Bearer Auth: Used by the CLI and local tools. Validates the
Authorization: Bearer <token>header against the configuredadmin_tokencrates/palyra-daemon/tests/admin_surface.rs#19-19. - Console Sessions: Issued via
/console/v1/auth/login. It sets aSET_COOKIEheader with a secure, HTTP-only session token crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#105-106. - CSRF Protection: Console mutations require a
x-palyra-csrf-tokenheader which is validated against the session state stored inAppState.console_sessionscrates/palyra-daemon/src/app/state.rs#50-50.
Rate Limiting
Rate limiting is enforced at the IP level for Admin and Canvas APIs, and at the Token level for the Compatibility API.- Admin API: Limits are defined by
ADMIN_RATE_LIMIT_MAX_REQUESTS_PER_WINDOWcrates/palyra-daemon/src/transport/http/middleware.rs#23-23. Loopback addresses receive a higher budget crates/palyra-daemon/src/transport/http/middleware.rs#129-131. - Compatibility API: Enforced per API token using
enforce_compat_rate_limitcrates/palyra-daemon/src/transport/http/handlers/compat.rs#111-111.
Security Headers
Theapply_admin_console_security_headers function crates/palyra-daemon/src/transport/http/middleware.rs#37-37 injects protective headers:
Cache-Control: no-storeX-Content-Type-Options: nosniffX-Frame-Options: DENYContent-Security-Policy: frame-ancestors 'none'
API Surface Details
Admin API (/admin/v1)
Provides low-level access to the daemon’s internal state.
- Status:
/admin/v1/statusreturns gateway health, gRPC ports, and auth requirements crates/palyra-daemon/tests/admin_surface.rs#40-70. - Journal:
/admin/v1/journal/recentallows querying the event log crates/palyra-daemon/tests/admin_surface.rs#84-106. - Policy Explain:
/admin/v1/policy/explainallows dry-running Cedar policy evaluations crates/palyra-daemon/tests/admin_surface.rs#119-148.
Console API (/console/v1)
Supports the Web Console’s rich features.
- Diagnostics:
/console/v1/diagnosticsaggregates state from the Model Provider, Browser Service, Skills, and Memory subsystems crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-84. - Browser Handoff: Supports secure transition from the Desktop app to the Web Console via
/console/v1/auth/browser-handoffcrates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-159.
OpenAI Compatibility API (/v1)
Implements the OpenAI Chat Completions and Models schema to allow drop-in replacement for existing AI tools.
- Chat Completions:
/v1/chat/completionsmaps incoming messages to aRunStreamRequestand executes an Orchestrator run crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-175. - Models:
/v1/modelslists available models based on theModelProviderstatus snapshot crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-126.
Code Entity Mapping
This diagram associates natural language API concepts with the specific Rust structs and handlers in the codebase. Sources: crates/palyra-daemon/src/app/state.rs#30-61, crates/palyra-daemon/src/transport/http/router.rs#17-157, crates/palyra-daemon/src/transport/http/middleware.rs#1-204Implementation Flow: Console Login
The following sequence describes the transition from raw HTTP request to an established session. Sources: crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111, crates/palyra-daemon/src/app/state.rs#73-73Static Asset Serving
The Web UI is served viaweb_ui_entry_handler crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#16-16. It attempts to resolve the dashboard root from the following locations:
PALYRA_WEB_DIST_DIRenvironment variable crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#13-13.- The
web/directory relative to the executable crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#135-135. - The
apps/web/distpath within the repository crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#138-138.