# Sample bridge: hello-rust

## What this is

`hello-rust` is a **minimal third-party bridge** for Adom Desktop, written in ~140 lines of Rust using `tiny_http` + `serde`. It builds to a **single static 300-KB binary** — no runtime install on the user's machine. Use this as your starting point when:

- You don't want to require Python (or any runtime) on your end users' boxes
- You want type-safe verb dispatch
- The work is CPU-bound and you want native speed
- You're more comfortable in Rust than Python

Pair it with its twin [`hello-python`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-python-bridge) (same surface, different language) for a side-by-side comparison of `kind: "exe"` (native single-binary) vs. `kind: "python"` (interpreted).

If you're getting started, also read the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) for the `bridge.json` schema and packaging conventions.

## Try it in 30 seconds

```bash
# 1. Install from the wiki (anonymous, no GitHub account needed)
adom-desktop bridge_install '{"manifestUrl":"https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-rust-bridge-manifest.json"}'

# 2. Ping it (auto-spawns the bridge process)
adom-desktop hellors_ping
# → {"success":true,"output":"Hello from the Rust sample bridge v1.2.0!","language":"rust",...}

# 3. Echo something back
adom-desktop hellors_echo '{"message":"world"}'
# → {"success":true,"output":"echo (rust): world","echoed":"world","language":"rust"}

# 4. Confirm it's registered
adom-desktop bridge_list   # look for "hello-rust" with verbs hellors_*

# 5. Uninstall when done
adom-desktop bridge_uninstall '{"name":"hello-rust"}'
```

`hello-python` and `hello-rust` use different verb prefixes (`hellopy_` vs `hellors_`) so both can be installed at the same time without collision — useful for an A/B comparison.

## What's in the box

```
hello-rust/
├── bridge.json         ← manifest (verb prefixes, spawn config, platforms)
├── BRIDGE_VERSION      ← semver
├── Cargo.toml          ← single dep: tiny_http + serde
├── src/main.rs         ← ~140 lines
├── hello-rust.exe      ← pre-built x64 Windows binary (~300 KB)
└── README.md           ← lifecycle notes
```

The pre-built `hello-rust.exe` ships in the zip so end users don't need a Rust toolchain. For macOS/Linux you'd rebuild with `cargo build --release` and re-zip.

## The two endpoints every bridge exposes

Identical to the Python flavor:

| Endpoint | When | What it returns |
|---|---|---|
| `GET /status` | Adom Desktop polls this after spawn to confirm the bridge is alive | `{"ok": true, "bridge": "hello-rust", "version": "...", "uptimeSec": N}` |
| `POST /command` | Every CLI verb call routes through here | `{"success": bool, "output": ..., "error": ...}` |

## How verb routing works

1. `bridge.json` declares `verbPrefixes: ["hellors_"]` and `spawn.kind: "exe"`
2. Adom Desktop's registry records that `hellors_*` belongs to this bridge
3. When you type `adom-desktop hellors_ping`, the Tauri runtime:
   - Spawns `hello-rust.exe --port <ephemeral>` if not already running
   - Polls `/status` until ready
   - POSTs `{"command":"hellors_ping","args":{}}` to `/command`
   - Streams the JSON response back through the CLI

For `kind: "exe"` bridges, Adom Desktop runs the entrypoint directly — no Python/Node lookup needed.

## The two verbs

| Verb | Args | Returns |
|---|---|---|
| `hellors_ping` | (none) | `{success, output, bridge, language: "rust", version, uptimeSec, _hint}` |
| `hellors_echo` | `{"message": "<str>"}` | `{success, output, echoed, language: "rust"}` |

## Forking for your own bridge

```bash
# 1. Get the source (anonymous — no GitHub account needed)
curl -O https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/hello-rust-bridge.zip
unzip hello-rust-bridge.zip && cd hello-rust

# 2. Rename the crate + bridge
#    - Cargo.toml: change "name" + "version"
#    - bridge.json: change "name", "displayName", "verbPrefixes", "verbs"
#    - bridge.json: change spawn.entrypoint + spawn.killImageName to your exe name
#    - src/main.rs: rename the match arms in handle_command()

# 3. Replace the verb implementations with calls into your tool's SDK
#    (vendor C lib via FFI, instrument driver, your REST API, etc.)

# 4. Build + test
cargo build --release
target/release/your-bridge.exe --port 8891   # in one terminal
adom-desktop bridge_install '{"manifestUrl":"file:///abs/path/to/your/bridge.json"}'

# 5. Package + ship — see the SDK guide
```

The full source tree is at [`scripts/sample-bridges/hello-rust/`](https://github.com/adom-inc/adom-desktop/tree/main/scripts/sample-bridges/hello-rust) in the Adom Desktop repo.

## When Rust is the right choice

Pick `hello-rust` (vs. the Python flavor) when:

- **Zero runtime install.** Your users don't need Python/Node/Java/.NET to be on the machine. The bridge is a single executable.
- **Native speed.** CPU-bound verbs (image processing, large data parsing, real-time instrument control) benefit from compilation.
- **Type safety.** `serde`'s `Deserialize` makes ill-formed args fail at parse time, not deep inside your handler.
- **Cross-compile to anywhere.** `cargo build --target x86_64-pc-windows-msvc` from Linux, etc.

Pick [`hello-python`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-python-bridge) when you need fast dev-iter loops, Python ecosystem libraries, or your tool's SDK is Python-first.

## Platform notes

| Platform | Status | Notes |
|---|---|---|
| Windows x64 | ✅ supported | Pre-built `hello-rust.exe` ships in the zip |
| macOS | rebuild required | `cargo build --release` on a Mac, then re-zip |
| Linux | rebuild required | `cargo build --release` on Linux, then re-zip |

For a forked third-party bridge that needs multi-OS distribution, the recommended pattern is GitHub Actions building per-target binaries on tag push, then a single zip with all three.

## License

MIT. Fork freely, sell what you build on top.

## See also

- [Adom Desktop bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) — `bridge.json` schema, packaging, lifecycle
- [`hello-python`](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-hello-python-bridge) — Python port of this same surface
- [Bridges registry](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) — community-maintained list of installable bridges
- [Reference bridges: KiCad, Fusion 360, Puppeteer](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges-registry) — full-complexity production examples