hero_sync_gmail

Gmail synchronisation service for the Hero ecosystem. Syncs Gmail messages and exposes them via a JSON-RPC API over Unix domain sockets.

Components

Crate	Role	Port	Socket
hero_sync_gmail_server	JSON-RPC daemon	3745	$PATH_SOCKETS/hero_sync_gmail/rpc.sock
hero_sync_gmail_admin	Admin dashboard	3746	$PATH_SOCKETS/hero_sync_gmail/admin.sock
hero_sync_gmail_cli	CLI client	—	—
hero_sync_gmail_sdk	Generated typed client	—	—
hero_sync_gmail_app	Dioxus web frontend	3647 (dev)	$PATH_SOCKETS/hero_sync_gmail_app/web_app.sock

Prerequisites

# Rust 1.96 (stable)
rustup show

# For the Dioxus frontend only:
rustup target add wasm32-unknown-unknown
cargo install dioxus-cli --locked

Quick Start

Open separate terminals for each component.

# Terminal 1 — server
make server

# Terminal 2 — admin dashboard
make admin

# Terminal 3 — CLI
make cli ARGS="ping"
make cli ARGS="sync"
make cli ARGS="status"

# Terminal 4 — Dioxus frontend (requires dx CLI)
make app

Build

make build    # cargo build --release --workspace
make check    # cargo check --workspace
make test     # cargo test --workspace

Smoke Testing (server must be running)

# Health check
curl --unix-socket "$PATH_SOCKETS/hero_sync_gmail/rpc.sock" http://localhost/health

# OpenRPC spec
curl --unix-socket "$PATH_SOCKETS/hero_sync_gmail/rpc.sock" http://localhost/openrpc.json

# Ping via RPC
curl --unix-socket "$PATH_SOCKETS/hero_sync_gmail/rpc.sock" \
     -X POST http://localhost/rpc \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"gmail_sync_service.ping"}'

# Or via TCP (port 3745)
curl -s -X POST http://localhost:3745/rpc \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"gmail_sync_service.ping"}'

Service Manifests

Each binary crate embeds a service.toml at its crate root and answers --info:

make server-info   # hero_sync_gmail_server --info --json
make admin-info    # hero_sync_gmail_admin --info --json
make cli-info      # hero_sync_gmail_cli --info --json

Architecture

The server uses the oschema-first pipeline:

oschema/main/gmail.oschema
        │
        │  openrpc_server!(spec = "oschema", service_toml = "service.toml")
        ▼
  pub mod main          ← GmailSyncServiceApi trait + all Input/Output types
  serve_domains(impl)   ← mounts rpc.sock + TCP 3745
        │
        └── $PATH_SOCKETS/hero_sync_gmail/rpc.sock

The schema defines a Message rootobject (auto-generates 8 CRUD methods) and a GmailSyncService block with ping, sync, and status custom methods.

The SDK (hero_sync_gmail_sdk) is generated from openrpc/openrpc_main.json via openrpc_client! after the server is built.

Validation

lab infocheck   # validates all binary crates in this repo