FlutterwareServer class

The primitives a Dart server reports through.

This is the whole public runtime surface: event, span/spanSync, handle, and zone correlation. Adapters — a shelf middleware, a query interceptor, a log listener — are copy-paste snippets over these four, deliberately not code in this package.

There is no init call. The first reported event activates the inspector: it binds a unix socket in ~/.flutterware/run, publishes a srv-*.json handle, and replays its ring to whoever attaches. When the gates say no — a release build, a machine without a run dir, FW_SERVER_INSPECT=0 — every primitive is a cheap no-op and the server runs exactly as if this library were not there.

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

correlationId → Object?: The correlation id of the current zone, if an adapter installed one.
no setter
step → String?: The step the current work runs under, or null outside one.
no setter

Static Methods

configure({String? name, String? root}) → void: Overrides the defaults — the entrypoint basename for the name, Directory.current for the project root. Must run before the first event: after activation the handle file is already published, and a silently ignored override would be worse than this error.
debugAttachInspector(ServerInspector inspector) → void: Routes the primitives to inspector — a test's temp-dir instance — instead of letting the gates decide against the real environment.
event(String channel, Map<String, Object?> payload, {Map<String, Object?>? details}) → void: Reports one event on channel. Fire-and-forget and safe everywhere: when the inspector is inert this is a null check and a return.
handle(String channel, String method, ServerCommandHandler handler) → void: Registers the handler an attacher's req frames on channel/method reach. This is what makes queries explainable: the handler runs inside the server, against its own live connections.
identify(String user, {String? phone, String? email}) → void: Says which user the current request is — once auth knows. The world maps the id to a person.
info(ServerInfo value) → void: Publishes the server's self-description — base URL, environment, links, connections, config. Call it once startup knows its facts (after serve returns, so the port is real); call it again any time to update only the sections the new value names (ServerInfo.fromEvents merges per section on the attacher side).
inStep<R>(String? step, R body()) → R: Runs body under step, as the request that caused it did: every event below it carries the step. A null step runs body as it is.
job<T>(String name, FutureOr<T> body(), {String? step, Object? id, String? queue}) → Future<T>: Runs body as a job: work a request handed off, run later by a queue's worker. It runs under step — the step of the request that queued it, which the queue keeps with the job (FlutterwareServer.step) — or, with none, under the current zone's; and as a request of its own, so what it writes, sends and runs gathers beneath one line of the world's trace: job thumbnail on jobs, done in 1.2 s, 31 statements.
onReassemble(FutureOr<void> callback()) → void: Runs callback after every hot reload of this process, once the new code is in: where a server builds again what it built once from the old code — its router, its middleware, an app object holding both.
reach(String user, String what) → void: Says the server delivered what to user outside any response to them: a WebSocket frame, a sync, a push. The one kind of consequence no device records, because it arrives on a connection nobody asked on.
reassemble() → Future<List<Object>>: Runs every onReassemble callback, as the world does after it reloads this process, through reassembleExtension; answers what they threw.
reloadable<A, R>(R Function(A) build()) → R Function(A): build's result, built again onReassemble: the handler itself, for a server whose state lives elsewhere and whose handler is all it needs to make again. What build is handed is kept; make the handler in a named function, since the closure build is keeps its old body.
reset() → Future<void>: Tears down the active inspector, forgets every onReassemble callback and re-arms the gates, so a test can run several activations in one process. Not part of the server-facing API.
span<T>(String channel, Map<String, Object?> payload, Future<T> body()) → Future<T>: Runs body and reports it as a timed event on channel — duration in fractional milliseconds under ms, the error under error if it threw. The error is rethrown; this observes, it never swallows.
spanSync<T>(String channel, Map<String, Object?> payload, T body()) → T: span for synchronous work — a sqlite call should not become async just to be observed.

Constants

requestIdKey → const Symbol: The zone key the correlation id travels under. A request-scoped adapter (the shelf middleware) runs its handler in runZoned(zoneValues: {FlutterwareServer.requestIdKey: id}, …), and every event and span emitted below it is stamped automatically.
stepKey → const Symbol: The zone key a device's step travels under — the tap, by a person or an agent, that caused the request. The adapter reads it from the request's x-fw-step header and puts it in the zone beside requestIdKey; every event emitted below it then carries it as step, so one tap's consequences — queries, messages, broadcasts — gather as one trace.