The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
socket
Persistent, Rust-native Socket.IO client to the OpenHuman backend. The socket domain owns a single long-lived SocketManager that speaks Engine.IO v4 + Socket.IO v4 directly over a WebSocket (tokio-tungstenite + rustls), maintains the connection with exponential-backoff reconnection, and routes inbound server events onto the in-process event bus for domain-specific handling (webhooks, channel messages, Composio triggers, device tunnel). Outbound emits and connection lifecycle are exposed over JSON-RPC under the socket namespace.
Responsibilities
- Open and maintain a persistent Socket.IO connection to the backend over a raw WebSocket; perform the Engine.IO OPEN and Socket.IO CONNECT handshakes by hand.
- Authenticate the SIO CONNECT with a JWT and reconnect automatically with exponential backoff (1 s → 30 s cap). Every connect attempt (DNS + TCP + TLS + upgrade) is bounded at 10 s per redirect hop (
CONNECT_TIMEOUT), so a path that accepts the connection and then goes silent fails the attempt instead of parking the loop until the far end gives up (#6256). - Follow HTTP 3xx redirects during the upgrade (up to 3 hops) so a
http://-configuredBACKEND_URLbehind a TLS-forcing edge connects cleanly; pin the resolved URL for subsequent reconnects and surface a one-shot "stale BACKEND_URL" warning for permanent redirects. - Refresh the session token before every reconnect via a
TokenProvidercallback (live re-read of the profile store) instead of caching a single token: fixes the "Invalid token" retry storm (#2892 / TAURI-RUST-9C). - Fast-fail on a definitively dead token (server "Invalid token" + no fresher token available) rather than burning the whole backoff budget.
- Track connection status / socket id / last user-visible error / loop liveness (
SharedState::loop_active+loop_stopped_on_failure,SocketManager::is_loop_active/loop_stopped_on_failure, surfaced asconnectivity_diag.socket_loop_active/socket_loop_stopped_on_failure) in shared state and expose it via RPC. A loop that exits because no usable session token exists raises the failure flag so the frontend can say "sign in again" instead of showing nothing. Between attempts the loop reportsReconnecting;Disconnectedmeans the loop is not running (signed out, session expired, shutdown), which is what the frontend's connectivity chip relies on to show "down, retrying" and stay quiet for "never wanted" (#6256). - Parse inbound Socket.IO EVENT frames and publish them as
DomainEvents for other domains to consume; emit outbound events. - Suppress reconnect-storm Sentry noise: route only the 5th consecutive failure through the observability classifier (which demotes offline/transport shapes to a breadcrumb), keep all other retries at
warn.
Key files
| File | Role |
|---|---|
crates/openhuman-core/src/platform/socket/mod.rs |
Module docstring + exports only. Re-exports SocketManager, global_socket_manager, set_global_socket_manager, and the all_socket_controller_schemas / all_socket_registered_controllers pair. |
crates/openhuman-core/src/platform/socket/manager.rs |
SocketManager handle + SharedState; global OnceLock accessor; connect / connect_with_provider / disconnect / emit / emit_with_ack / get_state; spawns the background ws_loop. Holds emit/shutdown channels, ACK waiters, and the loop join handle. |
crates/openhuman-core/src/platform/socket/ws_loop.rs |
The background reconnection loop and a single connection attempt: Engine.IO/Socket.IO handshake, Socket.IO ACK packet dispatch, redirect-following connect, ping-timeout deadline, backoff, invalid-token decision logic, failure-escalation logging. |
crates/openhuman-core/src/platform/socket/event_handlers.rs |
Inbound SIO event dispatch (handle_sio_event), SIO frame parsing (parse_sio_event), outbound frame helper (emit_via_channel). Maps event names → DomainEvent publishes. Redacts payload content from logs. |
crates/openhuman-core/src/platform/socket/token_provider.rs |
TokenProvider type alias + static_token_provider, token_provider_from_config, and is_invalid_token_error (strict double-anchor matcher). |
crates/openhuman-core/src/platform/socket/schemas.rs |
Controller schemas + RPC handlers for the socket namespace. |
crates/openhuman-core/src/platform/socket/types.rs |
WsStream alias, ConnectionOutcome enum, observability event-name constants; re-exports ConnectionStatus / SocketState from crate::platform::socket::models. |
crates/openhuman-core/src/platform/socket/ops.rs |
RPC operations behind schemas.rs (connect_with_session and live-socket reuse). |
crates/openhuman-core/src/platform/socket/*_tests.rs |
Sibling test suites, included via #[path]. |
Public surface
SocketManager: the connection handle. Key methods:new,connect(url, token),connect_with_provider(url, provider),disconnect,emit(event, data),emit_with_ack(event, data, timeout),get_state() -> SocketState,is_connected,set_webhook_router/webhook_router.global_socket_manager() -> Option<&'static Arc<SocketManager>>andset_global_socket_manager(Arc<SocketManager>): the process-global singleton (set once at bootstrap).all_socket_controller_schemas/all_socket_registered_controllers: controller-registry exports wired intocrates/openhuman-core/src/core/all.rs.
Internal-only (pub(crate) / pub(super)): TokenProvider and its builders, SharedState, ConnectionOutcome, WsStream, the ws_loop and event-handler helpers.
RPC / controllers
Namespace socket (called as openhuman.socket_<function>):
| Function | Inputs | Output | Notes |
|---|---|---|---|
connect |
url (str, req), token (str, req) |
status |
Connect with an explicit static token. |
disconnect |
: | status |
Tear down the loop. |
state |
: | state (JSON: status, socket_id, error) |
|
emit |
event (str, req), data (JSON, opt) |
ok (bool) |
Emit a SIO event to the backend. |
connect_with_session |
: | status |
Loads config, derives the API URL, and connects with a live-refresh token provider reading the stored session token from the profile store on every reconnect. |
All handlers go through require_manager() and error with "SocketManager not initialized" if the global singleton is unset.
Events
event_handlers::handle_sio_event is a thin transport router: it does not run domain logic itself. It mutates connection status for ready/error and publishes the following DomainEvents via crate::core::bus::BUS.publish for other domains' bus subscribers:
| Inbound SIO event | Published DomainEvent |
Consumer domain |
|---|---|---|
webhook:request |
WebhookIncomingRequest { request, raw_data } |
webhooks (also emits a webhook:response 400 on parse failure) |
composio:trigger |
ComposioTriggerReceived { toolkit, trigger, metadata_id, metadata_uuid, payload } |
composio |
tunnel:peer-status |
DevicePeerOnline / DevicePeerOffline |
devices |
tunnel:frame |
DeviceTunnelFrame |
devices |
tunnel:evicted |
DevicePeerOffline |
devices |
*:message (suffix match) |
ChannelInboundMessage { event_name, channel, message, sender, reply_target, thread_ts, raw_data } |
channels |
This module is a publisher only: it owns no bus.rs / EventHandler impls.
Persistence
None of its own. State (status, socket_id, error, attached WebhookRouter, pending ACK waiters) lives in-memory in SharedState. The session token is read on demand from the profile store via crate::security::credentials::session_support::get_session_token (live-refresh path); there is no store.rs.
Dependencies
crate::platform::socket::models:ConnectionStatus,SocketStateDTOs.crate::platform::socket::url::websocket_url,config.resolved_endpoints.require_control_plane(the host-resolved control-plane URL),crate::security::credentials::session_support::get_session_token: URL derivation and session-token lookup.crate::core::all:ControllerFuture,RegisteredControllerfor the controller registry.crate::core::{ControllerSchema, FieldSchema, TypeSchema}: RPC schema types.crate::core::bus::BUS.publish/crate::core::events::DomainEvent: for routing inbound events.crate::core::observability::report_error_or_expected: one-shot sustained-outage classification at the failure threshold.crate::skills::webhooks:WebhookRouter(attached for parse-error logging / response emission) andWebhookRequest.crate::integrations::composio:ComposioTriggerEventDTO forcomposio:triggerdeserialization.crate::security::devices::tunnel_client:TunnelPeerStatus,TunnelFrameDTOs for tunnel events.crate::config:Config+rpc::load_config_with_timeoutforconnect_with_session.crate::util::utf8_safe_prefix_at_byte_boundary: UTF-8-safe log truncation of raw packets.
Used by
crates/openhuman-core/src/core/all.rs: registers the socket controllers.crates/openhuman-core/src/core/runtime/bootstrap.rs(set_global_socket_managerat bootstrap),crates/openhuman-core/src/core/runtime/services.rs(backend auto-connect withtoken_provider_from_config),crates/openhuman-core/src/core/observability.rs: reference the socket namespace/state.crates/openhuman-core/src/platform/connectivity/rpc.rs: connectivity/status surfacing.crates/openhuman-core/src/skills/webhooks/{ops.rs,bus.rs}: emit webhook responses back through the global manager.crates/openhuman-core/src/security/devices/tunnel_client.rs: emits tunnel frames/registration over the socket.
Notes / gotchas
- Event-name constants in
types.rs(runtime:socket-state-changed,server:event) are grep-anchored: the frontend subscribes to those exact strings; a rename silently breaks the Tauri event bridge (locked by a test). - Payload content is never logged at any level: webhook bodies / channel messages / Composio payloads can carry PII, secrets, or tokens. Only byte-length and structural shape are logged. This also dodged a UTF-8 char-boundary panic that used to slice raw payloads at byte 500 (OPENHUMAN-TAURI-KC / #1814).
connectrejects an empty/whitespace token immediately rather than spawning a doomed retry loop;connect_with_providerdoes the same eager pre-check via the provider.- The reconnect loop bounds "fresh-token immediate retry" to one per cycle so a provider that returns a different non-empty token every call cannot hot-loop without sleeping or escalating (CodeRabbit Major, #2905).
- A genuinely fresh token from the invalid-token decision is carried forward (
pending_token) so the next iteration uses the exact validated value, avoiding a redundant profile-store lock/disk read. - Sentry escalation fires exactly once, on the 5th consecutive failure (~15 s of accumulated backoff), and is routed through the observability classifier so offline/transport shapes demote to a breadcrumb (OPENHUMAN-TAURI-8M / -BH).
- A connect attempt that outlives
CONNECT_TIMEOUTis rendered asWsError::Io(TimedOut)with theoperation timed outphrase on purpose: that is the substringis_network_unreachable_messagedemotes, so a sustained blackhole never pages. Keep the wording if you touch it. - The ping-timeout warning carries the connection age, the number of Engine.IO pings the connection ever received, and the frames sent since the last server frame; a successful handshake after an outage logs
Reconnected after Ns (N failed attempt(s)). Both exist so a drop report can be root-caused from the log alone (#6256): drops that always land at the same connection age point at a lifetime ceiling on the path (#5603), zero pings on a minutes-old connection point at the server. - Redirect following only persists the "update BACKEND_URL" warning for permanent redirects (301/308); temporary (302/307) hops don't (CodeRabbit, #1547).
- No agent tools and no
bus.rs: this is a transport domain that publishes events for others to handle.