Node Runtime and Lifecycle
TheNodeRuntimeState manages the persistence and in-memory state of paired devices and active nodes crates/palyra-daemon/src/node_runtime.rs#208-213. It tracks pairing codes, active requests, and the registered capabilities of each node crates/palyra-daemon/src/node_runtime.rs#141-151.
Node Enrollment (Pairing)
Nodes enroll into the platform using a multi-step pairing handshake. This process transitions through several states to ensure secure identity establishment.- Code Generation: A pairing code (PIN or QR) is generated with a specific TTL crates/palyra-daemon/src/node_runtime.rs#20-23.
- Request Initiation: The node client initiates a pairing request using the code crates/palyra-daemon/src/node_rpc.rs#150-170.
- Approval Workflow: A
DevicePairingRequestRecordis created, which triggers anApprovalRecordin the daemon’s journal crates/palyra-daemon/src/node_rpc.rs#187-200. - Material Issuance: Upon approval, the daemon generates mTLS material, including a client certificate and the gateway CA certificate crates/palyra-daemon/src/node_runtime.rs#80-88.
- Completion: The node downloads the material and establishes an mTLS-secured gRPC connection crates/palyra-cli/src/commands/node.rs#143-146.
Node Control Flow Diagram
The following diagram illustrates the relationship between the CLI-based Node Host and the Daemon’s RPC services. Node Host to Daemon Interaction Sources: crates/palyra-daemon/src/node_rpc.rs#45-54, crates/palyra-daemon/src/node_rpc.rs#207-215, crates/palyra-daemon/src/node_rpc.rs#230-240, crates/palyra-cli/src/commands/node.rs#207-215Node Capability Invocation
Capabilities are named functions (e.g.,system.health, desktop.open_url) that a node advertises as available crates/palyra-cli/src/commands/node.rs#119-125.
Invocation Lifecycle
When a capability is invoked (via the Console or API), theNodeRuntimeState manages the dispatch:
- Queued: The request is stored in
queued_by_devicecrates/palyra-daemon/src/node_runtime.rs#198. - Dispatched: The request is sent over the active
NodeEventStreamto the specific node crates/palyra-daemon/src/node_rpc.rs#245-255. - Mediation: Some capabilities require “Local Mediation” (operator interaction on the node itself) crates/palyra-daemon/src/node_runtime.rs#173.
- Completion: The node returns a
CapabilityExecutionResult, resolving theoneshotwaiter in the daemon crates/palyra-daemon/src/node_runtime.rs#200.
Capability Execution Data Flow
Sources: crates/palyra-daemon/src/node_runtime.rs#154-166, crates/palyra-daemon/src/node_rpc.rs#230-245, crates/palyra-cli/src/commands/node.rs#218-230Inventory Management
The Control Plane provides a unified “Inventory” view that aggregates identity, trust, and runtime presence.Data Models
| Entity | Code Symbol | Description |
|---|---|---|
| Device Record | InventoryDeviceRecord | Aggregates DeviceRecord, NodeRecord, and NodePairingRequestView crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#161-166. |
| Instance Record | InventoryInstanceRecord | Represents a live runtime instance (e.g., a specific daemon or sidecar) crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#24. |
| Trust State | inventory_device_trust_state | Determines if a device is trusted, untrusted, or revoked based on certificate validity crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#174. |
| Presence State | inventory_device_presence_state | Calculates status (online, stale, offline, degraded) based on heartbeat age crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#172-173. |
Presence Logic
The system uses specific timeouts to categorize node health crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#11-12:- Stale: Heartbeat > 5 minutes.
- Offline: Heartbeat > 30 minutes.
Control Plane Coordination
TheControlPlaneClient is the primary interface for multi-node coordination and administrative tasks. It abstracts the HTTP/REST interface of the daemon’s control surface.
Key Capabilities
- Session Management: Authentication and CSRF token handling crates/palyra-control-plane/src/client.rs#67-83.
- Browser Automation: Coordination of
palyra-browserdinstances crates/palyra-control-plane/src/client.rs#179-212. - Configuration: Management of daemon configuration snapshots and backups crates/palyra-control-plane/src/models.rs#147-164.
- Secret Management: Vault access for sensitive materials crates/palyra-control-plane/src/models.rs#95-110.
Access Control Integration
All control plane actions are gated by theAccessRegistry crates/palyra-daemon/src/access_control.rs#13-14. Tokens are validated against specific permissions (e.g., trust.operate, observability.read) before allowing node or inventory mutations crates/palyra-daemon/src/access_control.rs#31-32.
Entity Mapping: API to Implementation
| API Route | Handler Function | Permission Required |
|---|---|---|
GET /console/v1/inventory | console_inventory_list_handler | observability.read |
GET /console/v1/inventory/devices/:id | console_inventory_device_detail_handler | observability.read |
POST /node/v1/register | NodeRpcServiceImpl::register_node | mTLS Certificate Bound |
POST /node/v1/event-stream | NodeRpcServiceImpl::node_event_stream | mTLS Certificate Bound |