palyra-control-plane crate provides a high-level Rust client and a set of shared data models used for communicating with the Palyra Daemon’s administrative and console APIs. It acts as the primary bridge between the CLI/Web Console and the core orchestration engine, abstracting HTTP transport, CSRF management, and API contract validation.
Architecture and Client Lifecycle
The core entity is theControlPlaneClient, which wraps a reqwest::Client with specialized logic for session management and CSRF token handling. It is designed to interact with the /console/v1 and /admin/v1 API surfaces of the daemon.
Client Configuration
The client is initialized usingControlPlaneClientConfig, which defines the base URL and timeout parameters crates/palyra-control-plane/src/client.rs#15-30.
Session and CSRF Management
The client maintains internal state for CSRF protection. When a user logs in vialogin(), the resulting ConsoleSession contains a csrf_token that the client stores and automatically includes in subsequent state-changing requests (POST/PUT/DELETE) crates/palyra-control-plane/src/client.rs#75-83.
Request Pipeline
Most API methods follow a pattern of callingrequest_json, which handles:
- URL normalization (ensuring trailing slashes) crates/palyra-control-plane/src/client.rs#56-59.
- Injecting the
X-CSRF-Tokenheader if required crates/palyra-control-plane/src/client.rs#645-647. - Deserializing responses into typed envelopes or returning a
ControlPlaneClientErrorcontaining anErrorEnvelopecrates/palyra-control-plane/src/client.rs#660-680.
Data Flow: Client to Daemon
The following diagram illustrates how theControlPlaneClient interacts with the palyrad transport layer.
Control Plane Communication Flow
Sources: crates/palyra-control-plane/src/client.rs#75-83, crates/palyra-daemon/src/app/state.rs#29-59, crates/palyra-control-plane/src/client.rs#93-107
Shared Models and Contracts
Thepalyra-control-plane crate defines the “source of truth” for the JSON API schema.
ContractDescriptor
Every response envelope includes aContractDescriptor crates/palyra-control-plane/src/models.rs#49. This allows the client to verify that the daemon it is talking to supports the expected API version and features.
Key Models
| Model | Description | Source |
|---|---|---|
ConsoleSession | Represents an active authenticated session for a principal. | crates/palyra-control-plane/src/models.rs#8-16 |
DeploymentPostureSummary | Security and network configuration status of the daemon. | crates/palyra-control-plane/src/models.rs#48-61 |
AgentRecord | Configuration and metadata for a specific agent. | crates/palyra-control-plane/src/models.rs#177-190 |
SecretMetadata | Non-sensitive metadata about stored secrets (key, scope, size). | crates/palyra-control-plane/src/models.rs#82-88 |
InventoryDeviceRecord | Combined view of device identity and live node heartbeat. | crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#151-175 |
Daemon Integration
Thepalyra-daemon consumes these models within its HTTP handlers to ensure parity between the internal state and the external API.
AppState and Runtime Context
TheAppState struct in the daemon acts as the central registry for all live objects required by the handlers crates/palyra-daemon/src/app/state.rs#29-59. It is constructed during the daemon boot process in build_app_state crates/palyra-daemon/src/app/runtime.rs#42-84.
Entity Mapping: State to API
Sources: crates/palyra-daemon/src/app/state.rs#29-59, crates/palyra-daemon/src/transport/http/handlers/console/devices.rs#11-19, crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#14-40
Inventory and Diagnostics
TheInventorySection in the Web Console relies on the console_inventory_list_handler crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#14-40. This handler aggregates data from:
- Identity Manager: For device trust state and certificate fingerprints crates/palyra-daemon/src/transport/http/handlers/console/devices.rs#160-166.
- Node Runtime: For live heartbeat, capabilities, and platform information crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#81-85.
Compatibility Handler (Legacy API)
The daemon includes a “Compat API” surface located intransport/http/handlers/compat.rs. This provides an OpenAI-compatible interface for legacy tools that cannot use the native gRPC or A2UI protocols.
Feature Flags and Permissions
The Compat API is guarded by specific feature flags and permissions:FEATURE_COMPAT_API: Must be enabled in the access registry crates/palyra-daemon/src/transport/http/handlers/compat.rs#4.PERMISSION_COMPAT_CHAT_CREATE: Required for the/v1/chat/completionsendpoint crates/palyra-daemon/src/transport/http/handlers/compat.rs#141.
Rate Limiting
The Compat API uses a specialized rate limiter tracked inAppState::compat_api_rate_limit crates/palyra-daemon/src/app/state.rs#44. This enforces limits based on the API token used rather than just the IP address crates/palyra-daemon/src/transport/http/handlers/compat.rs#111.
Sources: crates/palyra-daemon/src/transport/http/handlers/compat.rs#1-126, crates/palyra-daemon/src/app/state.rs#44, crates/palyra-daemon/src/access_control.rs#18-36