palyrad daemon and a complex React hook to manage global application state, authentication lifecycles, and automatic data refreshing.
ConsoleApiClient
TheConsoleApiClient is the primary interface for the web frontend to interact with the daemon’s /console/v1/* endpoints. It encapsulates authentication, CSRF token management, and specialized handling for streaming responses.
API Groupings and Implementation
The client is organized into functional domains, reflecting the backend’s API structure. It supports both standard JSON requests and NDJSON (Newline Delimited JSON) streaming for real-time run updates.| Feature | Implementation Detail |
|---|---|
| CSRF Management | Mutating requests (POST, PUT, DELETE) automatically include the x-palyra-csrf-token header if a session is active apps/web/src/consoleApi.test.ts#82-90. |
| Error Handling | Throws ControlPlaneApiError which captures the HTTP status code and error message from the daemon apps/web/src/consoleApi.ts#16-17. |
| Streaming | Supports NDJSON via ReadableStream for run transcripts and terminal output apps/web/src/consoleApi.ts#8-9. |
CSRF Token Lifecycle
The client enforces a “fail closed” policy where mutating requests will throw an error if a CSRF token has not been acquired through a successful session bootstrap or login apps/web/src/consoleApi.test.ts#92-106. Console API Interaction Flow Title: ConsoleApiClient Request Lifecycle Sources: apps/web/src/consoleApi.ts#1-17, apps/web/src/consoleApi.test.ts#44-90Application State Management
TheuseConsoleAppState hook serves as the “brain” of the web application. It manages the transition from a booting state to an authenticated operator session and handles the complex “handoff” logic from the Palyra Desktop companion.
Bootstrap Sequence
The application follows a strict multi-stage boot sequence to ensure the operator is authenticated before accessing any privileged sections.- Initial Boot: The
bootingstate is set totrueapps/web/src/console/useConsoleAppState.tsx#173. - Session Discovery: The app attempts to load a session via
loadBootstrapSession. This includes up to 5 retries with exponential backoff to handle transient daemon startup delays or rate limiting apps/web/src/console/useConsoleAppState.tsx#93-108. - Desktop Handoff: If the URL contains a
desktop_handoff_token, the app attempts to consume it to automatically sign in the operator apps/web/src/console/useConsoleAppState.tsx#110-124. - Auth Fallback: If no session is found, the
bootingstate is cleared, and theConsoleAuthScreenis rendered apps/web/src/App.tsx#16-30.
Desktop Handoff Strategy
When the web console is launched from the Palyra Desktop application, it uses a one-time token to bridge the desktop’s mTLS-secured session to the browser’s cookie-based session.| Parameter | Value | Description |
|---|---|---|
| Query Param | desktop_handoff_token | The Onetime token provided by the Desktop companion apps/web/src/console/useConsoleAppState.tsx#61. |
| Retry Delay | 750ms | Delay between recovery attempts if the daemon is still initializing apps/web/src/console/useConsoleAppState.tsx#59. |
| Max Attempts | 8 | Total attempts to recover a session on localhost apps/web/src/console/useConsoleAppState.tsx#60. |
Auto-Refresh and TTL Strategy
To keep the dashboard data fresh without overloading the daemon,useConsoleAppState implements a TTL (Time-To-Live) strategy for different UI sections.
| Section | TTL (ms) | Source |
|---|---|---|
overview | 10,000 | apps/web/src/console/useConsoleAppState.tsx#44 |
channels | 8,000 | apps/web/src/console/useConsoleAppState.tsx#46 |
config | 15,000 | apps/web/src/console/useConsoleAppState.tsx#50 |
support | 10,000 | apps/web/src/console/useConsoleAppState.tsx#54 |
shouldAutoRefreshSection checks the lastRefreshedAt timestamp against these constants to determine if a background data fetch is necessary when the operator navigates back to a section apps/web/src/console/useConsoleAppState.tsx#63-73.
Section Routing and Domains
The state hook decomposes the application into specialized “domains” (e.g.,useOverviewDomain, useConfigDomain, useSupportDomain). These domains manage the specific sub-state and API calls for their respective sections.
- Overview Domain: Aggregates capability catalogs, deployment posture, and usage insights apps/web/src/console/hooks/useOverviewDomain.ts#22-33.
- Config Domain: Manages
palyra.tomlinspection, validation, and secret redaction apps/web/src/console/hooks/useConfigDomain.ts#61-80. - Support Domain: Handles node pairing, support bundles, and diagnostic recovery jobs apps/web/src/console/hooks/useSupportDomain.ts#56-74.