EdisonJwa
2bbad5feb9
Proof-of-concept proving the Flutter/Rust bridge exit criterion from docs/architecture/proof-of-concept-plan.md §2: "Flutter can call Rust and receive event stream data." The spike exposes one synchronous fallible command (greet) returning a typed GreetResult / GreetError DTO, and one async event stream (counter_stream) emitting typed CounterTick events. The Flutter app demonstrates both flows on a Material 3 surface; the headless test suite in test/poc_verification_test.dart exercises the same API directly through dart:ffi. Verified on 2026-05-13 (Linux desktop, Flutter 3.41.9 / Dart 3.11.5, flutter_rust_bridge 2.12.0, Rust 1.95). All three tests pass: - greet() returns typed result for valid input - greet() surfaces typed error for empty input - counterStream() delivers the expected event sequence Authority: PoC plan §2, DEC-014 (typed Flutter/Rust bridge), SAD-068, SDD-079, SysDes-049. Naming note: the PoC plan lists this as flutter-rust-bridge-hello, but Dart pubspec.yaml package names require underscores; the directory uses underscores accordingly. Not product code; not promoted into chanora_bridge. Layout note: includes the full Flutter platform scaffold (android, ios, macos, windows, web, linux). Only the Linux desktop target has been built and verified.
89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
# flutter_rust_bridge Hello Spike
|
|
|
|
Chanora proof-of-concept. **Not product code.**
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| PoC name | `flutter_rust_bridge_hello` (dir kept underscored for Dart-package naming) |
|
|
| PoC plan | [`docs/architecture/proof-of-concept-plan.md`](../../docs/architecture/proof-of-concept-plan.md) §2 |
|
|
| Purpose | Prove the command / result / event DTO boundary between Flutter and Rust |
|
|
| Exit criterion | "Flutter can call Rust and receive event stream data" |
|
|
|
|
> **Naming note.** The PoC plan lists this spike as
|
|
> `flutter-rust-bridge-hello`. Dart pubspec package names require
|
|
> underscores, so the on-disk directory is `flutter_rust_bridge_hello`.
|
|
> This is a naming convention, not a scope change.
|
|
|
|
## What it does
|
|
|
|
| API | Direction | Demonstrates |
|
|
|---|---|---|
|
|
| `greet(name)` | Dart → Rust → Dart (sync) | Typed `GreetResult` DTO + typed `GreetError` (Result-style fallible command) |
|
|
| `counterStream(count, intervalMs)` | Rust → Dart (async stream) | Typed `CounterTick` event stream with ordered delivery and clean close |
|
|
|
|
The `lib/main.dart` demo wires both into a Material 3 surface (button +
|
|
text field + live tick list). This UI is illustrative only — the
|
|
Chanora Design System belongs to the product Flutter app, not this PoC.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
flutter_rust_bridge_hello/
|
|
rust/ # Rust crate (cdylib + staticlib)
|
|
src/
|
|
lib.rs # crate root; declares api + frb_generated
|
|
api/
|
|
mod.rs
|
|
simple.rs # public API (greet, counter_stream, DTOs)
|
|
frb_generated.rs # autogenerated; do not edit
|
|
Cargo.toml
|
|
lib/
|
|
main.dart # demo UI
|
|
src/rust/ # autogenerated Dart bindings; do not edit
|
|
test/
|
|
poc_verification_test.dart # headless verification (flutter test)
|
|
integration_test/
|
|
simple_test.dart # same checks, runs under integration_test driver
|
|
flutter_rust_bridge.yaml
|
|
pubspec.yaml
|
|
linux/ android/ ios/ macos/ windows/ web/
|
|
rust_builder/ # cargokit build hook (generated)
|
|
```
|
|
|
|
## Reproduce
|
|
|
|
Requires Flutter stable (developed against 3.41.9 / Dart 3.11.5),
|
|
`flutter_rust_bridge_codegen` 2.12.0, Rust stable (developed against 1.95).
|
|
Linux desktop toolchain (clang, cmake, ninja, GTK3) for the build path
|
|
proven here. Network access required for first build (cargo + pub).
|
|
|
|
```bash
|
|
# Generate bindings whenever rust/src/api/*.rs changes
|
|
flutter_rust_bridge_codegen generate
|
|
|
|
# Build for Linux desktop (also builds the cdylib via cargokit)
|
|
flutter build linux --debug
|
|
|
|
# Headless verification — exercises the same API the demo UI uses.
|
|
LD_LIBRARY_PATH="$PWD/build/linux/x64/debug/bundle/lib:$LD_LIBRARY_PATH" \
|
|
flutter test test/poc_verification_test.dart
|
|
|
|
# Interactive run (requires a display)
|
|
flutter run -d linux
|
|
```
|
|
|
|
## Scope boundaries
|
|
|
|
- No TeamSpeak / `tsclientlib` integration (covered by
|
|
`tsclientlib-connect-spike`).
|
|
- No platform secure storage, SQLite, or audio (separate PoCs).
|
|
- No real DTO catalogue, no error taxonomy, no event-key conventions —
|
|
`chanora_bridge` will own those per SAD §7.2.
|
|
- Only the Linux desktop target has been built and verified. Android,
|
|
iOS, macOS, Windows are scaffolded by `flutter create` but unverified
|
|
here.
|
|
|
|
## Verification log
|
|
|
|
See `VERIFICATION.md` in this directory.
|