palyrad) exposes a multi-surface HTTP transport layer built on the Axum framework. This layer serves as the primary interface for the Web Console, the Canvas interactive environment, and OpenAI-compatible client integrations. It operates alongside the gRPC Gateway service, sharing a unified AppState but implementing distinct security, rate-limiting, and session management policies for each API surface.
System Architecture and Data Flow
The HTTP transport layer is initialized viabuild_router, which assembles the routing tree and attaches middleware pipelines based on the path prefix.
HTTP Surface Organization
| Prefix | Purpose | Auth Mechanism |
|---|---|---|
/admin/v1 | Low-level daemon management and diagnostics. | Bearer Token / Principal Headers |
/console/v1 | Backend for the React-based Operator Dashboard. | Session Cookie + CSRF Token |
/canvas/v1 | Interactive “Canvas” tool execution and state. | Canvas-specific Tokens |
/v1 | OpenAI-compatible Chat Completions and Models API. | API Tokens (Managed in Access Registry) |
/ | Serves the static SPA assets for the Web Dashboard. | Public (Assets) / Protected (Logic) |
Code Entity Map: HTTP Routing
The following diagram maps the logical API surfaces to their implementation handlers and the shared state. Title: HTTP Routing and State Association Sources: crates/palyra-daemon/src/transport/http/router.rs#17-157, crates/palyra-daemon/src/app/state.rs#30-61Middleware Pipeline and Security Guards
Palyra implements a layered middleware strategy to enforce security boundaries between the local CLI, remote admin tools, and the web-based console.1. Security Headers
All responses from the/admin, /console, and web UI surfaces are injected with strict security headers via apply_admin_console_security_headers crates/palyra-daemon/src/transport/http/middleware.rs#37-52. This includes:
Cache-Control: no-storeX-Frame-Options: DENYContent-Security-Policy: frame-ancestors 'none'X-Content-Type-Options: nosniff
2. Rate Limiting
Rate limiting is enforced per-IP bucket using a window-based approach. The/admin surface has a higher budget for loopback (CLI) traffic compared to external IPs.
- Logic:
consume_admin_rate_limit_with_nowcrates/palyra-daemon/src/transport/http/middleware.rs#135-170 - Buckets: Managed in
AppState.admin_rate_limitcrates/palyra-daemon/src/app/state.rs#44-46.
3. Console Session & CSRF
The/console/v1 surface uses a “Double Submit Cookie” pattern for CSRF protection.
- Session Issuance: Performed during
console_login_handlercrates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111. It returns aSET_COOKIEheader and acsrf_tokenin the JSON body. - Validation: Handlers call
authorize_console_sessionwhich checks thex-palyra-csrfheader against the session stored inAppState.console_sessionscrates/palyra-daemon/src/transport/http/handlers/console/auth.rs#117-118.
API Surface Implementation
Admin API (/admin/v1)
Primarily used for diagnostics and low-level control of the daemon. It requires x-palyra-principal and x-palyra-device-id headers for context.
- Status & Diagnostics:
admin_status_handlerprovides a snapshot of the runtime, including gRPC ports and auth requirements crates/palyra-daemon/src/transport/http/router.rs#19-24. - Channel Management: Allows querying logs, replaying dead letters, and pausing/resuming connector queues crates/palyra-daemon/src/transport/http/router.rs#25-89.
Console API (/console/v1)
A rich API surface designed for the React Dashboard (apps/web).
- Diagnostics:
console_diagnostics_handlercrates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-83 aggregates status from model providers, skills, browserd, and the memory maintenance loop. - Browser Handoff: Supports a “Desktop Handoff” flow where a local CLI session can mint a short-lived token to open the Web Dashboard with pre-authenticated credentials via
console_browser_handoff_handlercrates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-159.
OpenAI-Compatible API (/v1)
Allows standard LLM clients to use Palyra as a provider.
- Chat Completions:
compat_chat_completions_handlercrates/palyra-daemon/src/transport/http/handlers/compat.rs#128-175 maps OpenAImessagesto Palyra’s internalRunStreamRequest. - Auth: Uses
AuthenticatedApiTokenmanaged in theAccessRegistrycrates/palyra-daemon/src/transport/http/handlers/compat.rs#110-111.
Handler Organization and Data Transformation
Handlers are organized into modules undertransport::http::handlers. They serve as a translation layer between HTTP/JSON and the internal Protobuf-based service logic.
| Module | Responsibility | Key Entities |
|---|---|---|
admin::core | Core daemon status and run control. | admin_status_handler |
console::diagnostics | Aggregated health for the UI. | console_diagnostics_handler |
compat | OpenAI protocol translation. | CompatChatCompletionsRequest |
web_ui | Static asset serving for the SPA. | web_ui_entry_handler |
Static Asset Serving
Theweb_ui_entry_handler crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#16-34 resolves the dashboard location by checking:
PALYRA_WEB_DIST_DIRenvironment variable.- A
web/directory relative to the current executable. - The
apps/web/distpath in the source tree.
index.html for all non-file paths to support SPA client-side routing crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#191-193.
Sources: crates/palyra-daemon/src/transport/http/handlers/console/mod.rs#1-30, crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#125-148