Tauri IPC reference
This is a contributor reference for the Ratspeak 1.0.40 app source at 15831404cd792dbdc56aa682ba9221a9039821f5. The Tauri command/event surface connects the app’s WebView to its Rust backend. It is internal to the app and is not a stable public SDK or a remote automation service.
The versioned command registration and command modules are the authority for signatures and feature gates. Recheck them when changing app versions.
How IPC works in Ratspeak
The shell registers commands with tauri::generate_handler!. JavaScript calls them through Tauri’s invoke bridge; Rust emits named events through the app’s Emitter implementation. Tauri handles the platform WebView/backend communication. It is misleading to treat this as one JavaScript/Rust process or a network socket API.
Many commands return AppResult<T> with a serializable result. Shell commands can have other return/error types. Platform and Cargo feature gates also change which commands are registered. The app does not expose this command set as a supported localhost HTTP/WebSocket server for outside clients.
Calling a command
const { invoke } = window.__TAURI__.core;
try {
const conversations = await invoke("api_lxmf_conversations");
console.log(conversations);
} catch (err) {
// Application errors normally have code/message; bridge errors may differ.
console.error(err);
}
For direct command parameters, use the Tauri argument names registered by Rust. Many Ratspeak commands take a single nested args struct; those nested fields intentionally mirror the Rust struct and may be snake_case, for example dest_hash, delivery_method, and client_msg_id in send_lxmf_message. Treat the source and dashboard callers as canonical when wiring a new integration.
Listening for events
const { listen } = window.__TAURI__.event;
const unlisten = await listen("lxmf_message", (e) => {
// e.payload is the event body, shape depends on event name
console.log(e.payload);
});
// later
unlisten();
The Tauri emitter broadcasts by event name. Payloads are JSON values and may be objects or arrays; inspect the emitting site and dashboard consumer. Runtime identity/session checks can suppress stale emissions. An event stream is not a durable replay log: subscribe, request the relevant initial snapshot, and handle identity changes.
Command domains
The registered domains include the following. This is a map to the source, not a count-based API guarantee.
| Domain | Responsibility |
|---|---|
interfaces | Interface configuration, radio discovery/readiness, transport mode and several app settings. |
network | Announces, paths, propagation, blackholes and network diagnostics. |
network_ownership | App-owned/shared-instance network state and selection. |
system | Startup, setup, lifecycle, app metadata and data-clear/reset operations. |
identity | Software identities, import/export, activation, names, status and locks. |
hardware | Desktop PIV identity operations; platform/feature gated. |
messaging | Conversations, messages, attachments, transfers and cancellation. |
contacts / contact_card | Contact records, trust/block state and contact-card exchange. |
peers | Peer snapshots. |
ble | Bluetooth Peer and BLE operations. |
channels | Client hub/room sessions, history and unread state. |
channel_hub | Hosting and managing a Channels hub. |
activity | Activity/diagnostic views and controls. |
games | LRGP sessions and game actions. |
voice | Calls, audio state and voice memos; lxst-voice gated. |
Some shell functions, such as secret clipboard and native sharing helpers, live under src-tauri/src instead. Search both registrations and implementations from the Ratspeak repository root:
rg -n '#\[tauri::command\]|generate_handler!' \
crates/ratspeak-tauri/src/commands src-tauri/src
A function existing in a command module does not establish that a particular platform build registers it.
Event vocabulary
Names the core broadcasts; subscribe to whichever your integration cares about.
| Event | Payload |
|---|---|
system_status | Coarse lifecycle marker, for example ready, stopping, or stopped. |
lxmf_identity | Active identity hash and display name when loaded or switched. |
contacts_update | Contact list snapshot. |
conversations_update | Conversation roster — last message, unread, peer hash. |
lxmf_message | A single inbound or outbound LXMF message in canonical form. |
lxmf_step | Per-message send or attachment progress, including validation errors. |
unread_total | Aggregate unread count across all conversations. |
stats_update | Transport, link, and traffic counters; see Notes for cadence. |
peers_updated | Peer updates; a payload may contain only changed peers, so check the consumer’s merge behavior. |
all_game_sessions | LRGP session-list snapshot. |
node_operation_status | Interface add/remove/update progress for long-running network operations. |
propagation_sync_result | Propagation-node sync completion or failure. |
voice_call_update | Active LXST call lifecycle: status changes, profile, audio side state. Only emitted when the lxst-voice Cargo feature is on. |
voice_incoming_call | A new incoming LXST call that passed the policy for contacts or recognized direct peers. |
Other narrower events exist (identity_reset, identity_switched, auto_announce_updated, propagation_update, ble_peer_status_update, hub_interfaces_update, transport_mode_updated, etc.). Check the versioned source before depending on their shape or ordering. On the desktop, download_result ({ "url": string, "status": "saved" | "cancelled" | "failed" }) reports how a download the page started ended, once its save dialog and the write are done.
Error model
Commands using AppResult<T> serialize AppError with a machine-readable code and a human-readable message, for example:
{ "code": "not_found", "message": "no contact for hash a1b2c3d4" }
Standard codes in use:
bad_request— argument validation failureunauthorized/forbidden— an authentication, confirmation or command policy check refused the callnot_found— referenced row, hash, or session does not existconflict— state precondition violated (e.g. duplicate identity, or no active identity)locked— the active identity is locked, and only app settings, setup and identity management answer until it is unlockedservice_unavailable— RNS or transport not ready yetdatabase_unavailable— the command could not obtain the database service/connectionlxmf_not_initialized— LXMF stack not up; retry aftersystem_statusreports readyfiles_not_removed— the messages were deleted, but some associated files remain queued for cleanup retryphrase_not_saved— the new identity's recovery phrase could not be stored, so the identity was not createdinternal_error— unexpected failure; the message is human-readable (process logging is opt-in in production)startup_error— the core could not open its data at startup, so no command runs (see Startup errors below)
Other codes include database_error and serialization_error; bridge-level failures can have a different shape. Handle an unknown error as failure of that call and preserve its detail. Do not parse the human-readable message as a stable code.
Notes for integrators
Subscribe and initialize. Listen for changes and use the domain’s snapshot command to initialize a view. Do not assume an event sent before subscription will be repeated. Match the existing dashboard’s identity and request-generation checks when applying asynchronous results.
Stats cadence. The normal runtime polling interval is 2.5 seconds. Builds with mobile throttling use 15 seconds in the background, and explicit refreshes can also publish stats. Listen for stats_update; do not treat its spacing as a clock or liveness guarantee.
Wait for readiness. Use api_startup_progress and the setup/identity state before enabling dependent actions. Messaging calls can return lxmf_not_initialized or service_unavailable while services start. Identity management and app settings have different admission rules; a system_status event is not permission to bypass a locked/no-identity gate.
Startup errors. If the core can't open its data, no command is available: every invoke fails with startup_error, and the window shows a screen with the cause instead of the app. The window's initialization script sets window.__RATSPEAK_STARTUP_ERROR__ to { "code": string }, where code is profile_in_use (another Ratspeak app holds the same data), schema_newer (the database was written by a newer version; found and supported give both schema versions) or storage. Data in use by another app is left untouched. The data of a newer version is not reconciled, and its database is only read, never written. On Android, leaving that screen in any way (Back, Home, another app or the lock screen) closes Ratspeak and removes it from the recent apps, which ends its process, so opening it again retries. On iOS, swiping Ratspeak away in the app switcher ends it; Home only moves it to the background. On a drive that can't lock files, the core starts but can't refuse a second app, and api_startup_progress reports profile_lock_warning next to storage_warning.
Identity context
Current identity and switching. Most operational commands use the active identity; identity-management commands can also target an explicit identity. api_set_display_name (args.identity_id) and set_identity_status (identityId) take the identity the caller shows: when another identity is active they answer conflict and change nothing.
Rename, status, block_contact and unblock_contact wait for an identity switch in progress; one asked for before or during the switch then answers conflict. A switch can overtake a block or unblock that has already begun: its database changes still apply to the identity it was asked for, and its events reach no window. If that identity's runtime stopped before taking the network block or lift, the block waits until that identity next receives the contact's announce, and the lift until that identity's runtime is up again; blocking the contact before then cancels the lift.
Listen for identity_switched to know when that context changes underneath you. A switch that begins (identity_switching) but doesn't finish ends with identity_switch_failed ({ "hash": string, "generation": string, "error": string }) instead, and the previous identity, if there was one, runs again; with none, no identity is left active. A switch to an identity that fails to open does not count as its use. A start whose plain identity cannot load ends in the error startup stage, without starting the network.
Hardware operations. A hw_activate_and_unlock that cannot activate its identity sends identity_switch_failed too, with no identity_switching before it, and the previous identity runs again. Removing the active hardware identity makes the most recently used remaining identity active; a protected one comes up locked. Switching away from a protected identity and back asks for its passcode or PIN again. A hardware PIN unlock does not survive a runtime restart. hw_provision_recoverable, hw_provision_hardware_only, hw_restore and hw_reset_piv on the security key of the active hardware identity leave that identity locked, whether or not they succeed, and hw_activate_and_unlock keeps its identity locked until the PIN has been checked.
Locked identities and Auto-Lock. unlock_identity answers bad_request when no identity is locked. While the active identity is locked, a command that works on its data answers locked; api_setup_complete, api_lxmf_limits and voice_status also answer locked. App settings, the Bluetooth availability probes and identity management remain available.
hardware_locked ({ "hash": string, "kind": "hardware" | "passcode", "reason": string }) reports a lock: reason is secret_required when the identity loads locked and timeout for Auto-Lock, which locks it once the set time has passed since its unlock, counting time the device slept, whether or not its network is running. set_identity_passcode on the active, unlocked identity starts its Auto-Lock over, and remove_identity_passcode ends it. A failed protected-identity load can instead emit { "hash": string, "kind": "hardware" | "passcode", "error": string }.
No active identity. While no identity is active, a command that works on an identity's data may answer conflict with the message no active identity. The admission check in front of every command refuses such calls only once Ratspeak knows that no identity is active. With no active identity, app settings, first-run setup, platform probes and identity management remain available.
Other command behavior
Keys and secrets. export_shared_access, api_export_identity_reticulum_base64 and api_export_identity_reticulum_base32 take the identity's passcode when it has one, otherwise confirmed: true; api_export_identity_backup_base64 takes them as identityPasscode and confirmed, beside the backup's own passcode. Exports work while the identity is locked. api_setup_complete, api_create_identity, restore_seed_identity and an import of a backup that holds a recovery phrase store the phrase before they create the identity: one whose phrase cannot be stored answers phrase_not_saved and creates nothing, and one that arrives while another identity encryption runs answers service_unavailable. reveal_identity_mnemonic takes args.passcode or args.confirmed the same way as the exports, and answers forbidden for an identity that isn't active. A missing or wrong PIN answers unauthorized, and a missing confirmation bad_request. copy_secret ({ text }) puts a key or phrase on the clipboard, out of clipboard history where the platform allows, and clears it after a minute unless something else was copied since; on Android, while the app is in the background, it clears it either way.
Notifications. api_notification_settings answers { "enabled": bool, "ios_stubbed": bool, "preview": string }. set_notification_preview takes preview, one of name_and_message, name_only or neither, answers the same object and keeps the choice across restarts; any other value answers bad_request. Both answer while no identity is active or the active one is locked.
Bulk clears. api_clear_messages, api_clear_contacts and api_reset_database act on the active identity only and keep its blocked users. A clear that waited out an identity switch answers conflict and deletes nothing. After the database clear commits, the command emits identity_data_cleared ({ "messages": bool, "contacts": bool }) and refreshes contacts_update, unread_total and conversations_update when the identity generation is still current and the reads succeed. A clear or delete_conversation can answer files_not_removed after deleting messages: that reports incomplete file cleanup, not a rollback of the database change.
Attachments. The app exposes its current message, attachment, efficient-resource, and Offline Inbox/propagation-node transfer limits through api_lxmf_limits. Do not hard-code UI limits; they depend on the protocol resource ceiling and, for Offline Inbox delivery, the selected propagation node's advertised transfer limit.
Threading. Backend work may complete asynchronously, and events can arrive while a request is pending. Keep frontend handlers safe against stale identity/view state. Contributors must move blocking database or expensive work onto the established worker paths; an async signature alone does not make blocking work harmless.
Versioning. The IPC surface is not a stable public API. Pin to a Ratspeak release for contributor tooling and re-verify against the versioned source on upgrade.