palyra-common crate provides the foundational primitives used across the Palyra platform for filesystem manipulation, configuration management, and data sanitization. It implements the “fail-closed” philosophy of the platform by enforcing strict limits and validation before any side effects occur.
Workspace Patching Pipeline
The workspace patching system allows for atomic, multi-file updates to a local workspace. This is primarily used by the daemon and CLI to apply code changes generated by models or automated routines. The pipeline is designed to be safe, providing dry-run capabilities, path sanitization, and automatic rollback on failure.Implementation Flow
Theapply_workspace_patch function crates/palyra-common/src/workspace_patch.rs#207-211 orchestrates the four-stage pipeline:
- Parse: Converts the raw patch string into a sequence of
PatchOperationenums (Add, Update, Delete) crates/palyra-common/src/workspace_patch.rs#159-163. - Plan: Validates all operations against
WorkspacePatchLimitscrates/palyra-common/src/workspace_patch.rs#23-28 and ensures all paths are contained within the providedworkspace_roots. It generates aPatchPlancrates/palyra-common/src/workspace_patch.rs#184-187. - Execute: Performs the actual filesystem mutations. Writes are performed using a temporary file pattern to ensure atomicity.
- Rollback: If any operation fails during execution, the system attempts to restore the workspace to its previous state using
before_sha256attestations crates/palyra-common/src/workspace_patch.rs#136-138.
Patching Data Flow
The following diagram illustrates the transformation from a raw patch string to a successful outcome. Workspace Patch Execution Logic Sources: crates/palyra-common/src/workspace_patch.rs#23-28, crates/palyra-common/src/workspace_patch.rs#67-71, crates/palyra-common/src/workspace_patch.rs#159-163, crates/palyra-common/src/workspace_patch.rs#207-211Redaction and Safety
TheWorkspacePatchRedactionPolicy crates/palyra-common/src/workspace_patch.rs#45-48 ensures that sensitive information (e.g., API keys, secrets) is not leaked in the redacted_preview returned in the WorkspacePatchOutcome crates/palyra-common/src/workspace_patch.rs#92-98.
| Feature | Implementation |
|---|---|
| Path Sanitization | Validates that paths do not contain traversal components (..) and stay within roots crates/palyra-common/src/workspace_patch.rs#113-116. |
| Atomic Writes | Uses temporary files and fs::rename to ensure files are never partially written. |
| Size Limits | Enforces max_patch_bytes and max_file_bytes before starting execution crates/palyra-common/src/workspace_patch.rs#23-28. |
| Attestation | Emits WorkspacePatchFileAttestation for every touched file, including SHA256 hashes crates/palyra-common/src/workspace_patch.rs#75-88. |
Configuration System
Theconfig_system module manages TOML-based configuration files for the daemon and CLI. It supports versioning, migrations, and nested path access.
Key Functions
parse_document_with_migration: Parses a TOML string and automatically upgrades it toCONFIG_VERSION_V1crates/palyra-common/src/config_system.rs#89-99.get_value_at_path: Retrieves a value using a dot-notated string (e.g.,daemon.port) crates/palyra-common/src/config_system.rs#153-156.set_value_at_path: Modifies or creates a value at a specific path, creating parent tables as needed crates/palyra-common/src/config_system.rs#174-178.rotate_config_backup: Manages file backups (e.g.,.bak.1,.bak.2) to prevent data loss during manual or automated edits crates/palyra-common/src/config_system.rs#15.
Configuration CLI Integration
The CLI uses these utilities to provideconfig get, set, and unset commands. On Unix systems, the system preserves existing secure permissions (e.g., 0o600) when updating files crates/palyra-cli/tests/config_mutation.rs#107-146.
Sources: crates/palyra-common/src/config_system.rs#14-15, crates/palyra-common/src/config_system.rs#89-99, crates/palyra-common/src/config_system.rs#153-156, crates/palyra-cli/tests/config_mutation.rs#107-146
Redaction Utilities
Theredaction module provides specialized routines for identifying and masking sensitive data in logs, HTTP headers, and URLs.
Sensitive Key Identification
The system maintains a list ofSENSITIVE_KEY_MARKERS crates/palyra-common/src/redaction.rs#5-22 including:
access_token,api_key,authorization,bearerclient_secret,cookie,password,private_keysession,token,vault_ref
is_sensitive_key crates/palyra-common/src/redaction.rs#25-28 uses these markers to determine if a value should be masked.
Specialized Redactors
| Function | Description |
|---|---|
redact_url | Strips credentials from userinfo and redacts sensitive query parameters crates/palyra-common/src/redaction.rs#63-86. |
redact_header | Redacts headers like Authorization or Cookie, and applies URL redaction to Location and Referer crates/palyra-common/src/redaction.rs#49-60. |
redact_auth_error | Parses error messages to find and mask Bearer tokens or assignment patterns crates/palyra-common/src/redaction.rs#89-111. |
redact_url_segments_in_text | Scans a block of text for URLs and redacts each one individually crates/palyra-common/src/redaction.rs#114-130. |
Media and Runtime Constants
Thepalyra-daemon utilizes palyra-common primitives to define its MediaRuntimeConfig crates/palyra-daemon/src/media.rs#49-69. This includes:
- Allowed Hosts: Defaults to Discord CDNs crates/palyra-daemon/src/media.rs#25-26.
- Content Types: Strict allowlists for images and text crates/palyra-daemon/src/media.rs#27-31.
- Retention: Default TTL of 7 days for stored artifacts crates/palyra-daemon/src/media.rs#38.