Backend API

Overview

zudotext uses Tauri v2 for native OS integration, with no Node.js main process. The cloud workspace is accessed through TypeScript bridge domains. Rust commands cover native concerns such as windows, device-local configuration, file pickers, and the deliberately local External File Editor surface.

The backend exposes functionality to the frontend through two mechanisms:

• Commands — synchronous or async request/response calls (like RPC)

• Events — backend-to-frontend push notifications (like pub/sub)

How the Frontend Calls the Backend

Commands via invoke()

The frontend calls Rust functions using Tauri's invoke(). The @takazudo/backend-bridge package abstracts this so that production code uses real Tauri calls while tests and Storybook use an in-memory mock adapter.

import { invoke } from '@tauri-apps/api/core';

// Read an explicitly local file (External File Editor)
const content = await invoke<string>('files_read_text', {
  path: '/Users/example/notes/local.md',
});

Events via listen()

The backend pushes real-time notifications to the frontend using Tauri's event system. The frontend subscribes with listen().

import { listen } from '@tauri-apps/api/event';

// Listen for a file opened in External File Editor changing on disk
const unlisten = await listen<{ path: string }>('files:externalChange', (event) => {
  console.log('File changed:', event.payload.path);
});

Command Naming Convention

All Tauri commands use snake_case naming, grouped by domain:

Application State

All commands share a central AppState managed by Tauri's dependency injection:

pub struct AppState {
    pub file_searches: Mutex<HashMap<String, MdfindChild>>,
    pub watchers: Mutex<WatcherState>,
    pub app_config_dir: PathBuf,
    pub settings_cache: Mutex<Option<serde_json::Value>>,
    pub settings_mtime: Mutex<u64>,
    pub event_tx: broadcast::Sender<SseEvent>,
}

• app_config_dir — immutable path to the app's config directory (e.g. ~/.config/zudotext/<appname>/); not wrapped in a Mutex because it never changes after initialization

• file_searches — active mdfind subprocess handles keyed by search ID (Spotlight integration)

• watchers — file watcher instances and content/mtime tracking for self-write detection

• settings_cache / settings_mtime — cached settings with mtime-based invalidation

• event_tx — broadcast channel for SSE events (REST adapter)

Native state is synchronized with narrow mutexes; commands avoid holding unrelated locks across I/O.

Page Index

Internal / Unlisted Commands

The following Tauri commands are registered in generate_handler! but are not documented on dedicated pages. They are internal utilities, UI conveniences, or native OS dialogs without a significant contract to specify:

Event Summary

Security

• Path traversal prevention — local file operations use purpose-specific containment and canonicalization guards such as validate_path_in_roots; workspace paths are validated by the cloud workspace layer

• Input validation — settings must be JSON objects, inbox active draft numbers must be 1–99

• Filename sanitization — asset filenames are stripped of path components to prevent traversal