feat(poc/bridge): add flutter_rust_bridge hello spike
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.
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user