palyra-browserd service, which provides a high-level gRPC interface for browser automation. It encapsulates the Chromium engine via the headless_chrome crate, managing session lifecycles, security constraints, and state persistence.
BrowserService gRPC Definition
TheBrowserService is the primary interface for all browser-related operations. It is defined in browser.proto and implemented by BrowserServiceImpl in the palyra-browserd crate.
Key RPC Methods
| Method | Description | Implementation |
|---|---|---|
CreateSession | Initializes a new browser instance or attaches to an existing profile. | crates/palyra-browserd/src/transport/grpc/service.rs#29-161 |
Navigate | Directs the browser to a specific URL with safety guards. | crates/palyra-browserd/src/transport/grpc/service.rs#260-316 |
Click | Simulates a mouse click on a DOM element identified by a selector. | crates/palyra-browserd/src/transport/grpc/service.rs#318-372 |
Type | Inputs text into a form field or element. | crates/palyra-browserd/src/transport/grpc/service.rs#374-434 |
Scroll | Adjusts the viewport position. | crates/palyra-browserd/src/transport/grpc/service.rs#436-476 |
Observe | Captures the current page state (DOM, Title, URL). | crates/palyra-browserd/src/transport/grpc/service.rs#524-555 |
RelayAction | Handles communication with the browser extension companion. | crates/palyra-browserd/src/transport/grpc/service.rs#710-754 |
DownloadArtifact | Retrieves files downloaded during a session from the quarantine. | crates/palyra-browserd/src/transport/grpc/service.rs#756-788 |
Chromium Engine Integration
Palyra uses theheadless_chrome crate to control Chromium. The integration supports both a “Real” engine and a “Simulated” mode for testing.
Execution Flow
When a session is created,palyra-browserd launches a Chromium process (if not using an existing profile) and establishes a DevTools Protocol connection.
System Entity Mapping: Natural Language to Code
Title: Browser Action Execution Pipeline
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#318-372, crates/palyra-browserd/src/engine/chromium.rs#60-68, crates/palyra-browserd/src/lib.rs#36-40
SessionBudget Constraints
Every session is governed by aSessionBudget, which enforces resource limits to prevent runaway automation or memory exhaustion.
- Navigation Timeout:
max_navigation_timeout_ms(Default: 15s) crates/palyra-browserd/src/lib.rs#85 - Payload Size:
max_response_bytes(Default: 512KB) crates/palyra-browserd/src/lib.rs#88 - Action Rate:
max_actions_per_window(Default: 20 per second) crates/palyra-browserd/src/lib.rs#93-94 - Data Limits:
max_screenshot_bytes,max_type_input_bytescrates/palyra-browserd/src/lib.rs#87-91
Security and Validation
Target URL Validation
Before any navigation, the service validates the target URL to prevent SSRF or access to restricted internal networks. This is handled bynavigate_with_guards.
- Private Targets: Blocked by default unless
allow_private_targetsis true. - Protocol Enforcement: Only
httpandhttpsare allowed. - DNS Rebinding Protection: The service maintains a
DnsValidationCacheto track resolved IPs.
SOCKS5 Proxy Integration
To enforce network policies at the engine level,palyra-browserd spawns a local SOCKS5 proxy for each session via ChromiumSessionProxy. This proxy intercepts all Chromium traffic to apply allow_private_targets logic.
System Entity Mapping: Proxy Lifecycle
Title: Chromium Network Guarding
Sources: crates/palyra-browserd/src/engine/chromium.rs#71-97, crates/palyra-browserd/src/engine/chromium.rs#198-210
BrowserProfile and Persistence
The service supports persistent browser profiles, allowing sessions to share cookies, local storage, and history.- BrowserProfileRegistry: Manages a collection of profiles per principal. crates/palyra-browserd/src/lib.rs#138-140
- Encryption: Profile metadata and state snapshots are encrypted using
CHACHA20_POLY1305with keys derived fromPALYRA_BROWSERD_STATE_ENCRYPTION_KEY. crates/palyra-browserd/src/lib.rs#123, crates/palyra-browserd/src/lib.rs#132-135 - Persistence IDs: Sessions can be resumed using a
persistence_idwhich links to aPersistedSessionSnapshot. crates/palyra-browserd/src/transport/grpc/service.rs#52-73
Download Artifact Management
Downloads are intercepted and stored in a sandboxed directory structure.- Quarantine: Files are initially placed in a
quarantinedirectory. crates/palyra-browserd/src/domain/downloads.rs#35-36 - Validation: Files are checked against
DOWNLOAD_ALLOWED_EXTENSIONS(e.g., pdf, csv, json) andDOWNLOAD_ALLOWED_MIME_TYPES. crates/palyra-browserd/src/lib.rs#153-162 - Limits: Enforced via
DOWNLOAD_MAX_FILE_BYTES(8MB) andDOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION(32MB). crates/palyra-browserd/src/lib.rs#147-148
Browser Extension Relay
TheRelayAction RPC facilitates communication with the Palyra Browser Extension. This allows the daemon to:
- Capture DOM snapshots from the perspective of the user’s active browser.
- Relay user-initiated selections back to the daemon.
- Inject content scripts for enhanced observation.