Files

T

EdisonJwa 2bbad5feb9 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.

2026-05-14 12:26:09 +08:00

3.2 KiB

Raw Blame History

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` §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

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).

# 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.

3.2 KiB Raw Blame History