feat(SDK-2185): FDv2 streaming base, initializer, and synchronizer

[kinyoklion]

Stacked on #266 (SSE capability surface). Mark this PR ready for review only after #266 merges and the base is rebased onto main.

Jira: SDK-2185

Scope

Phase B1 from the parallel plan — the streaming half of FDv2 sources, mirroring the polling vertical that landed in SDK-2183 / SDK-2184.

Three new files in packages/common_client/lib/src/data_sources/fdv2/:

streaming_base.dart — FDv2StreamingBase

Wraps an SSEClient with FDv2 protocol semantics. Single-subscription StreamController<FDv2SourceResult>:

• onListen → builds a fresh FDv2ProtocolHandler, subscribes to the SSE client's stream.
• onCancel → tears down without emitting shutdown (subscriber-initiated).
• close() → emits shutdown then closes; idempotent.

Per event:

• Named SSE events get parsed as JSON, wrapped in an FDv2Event, fed to the handler.
• ActionPayload → ChangeSetResult with persist: true.
• ActionGoodbye → goodbye StatusResult; closes the connection (server told us to disconnect).
• ActionServerError / ActionError → interrupted StatusResult; SSE client's built-in backoff handles reconnect.
• ActionNone → no emission.
• Legacy ping events → injected PingHandler (one-shot poll); result is forwarded.
• x-ld-fd-fallback: true on the OpenEvent → terminalError with fdv1Fallback: true; closes.
• SSE transport error → interrupted; reconnect via SSE client.

Closed-ness tracked via a single Completer<void> _stoppedSignal (matches the polling synchronizer pattern from SDK-2184).

streaming_initializer.dart — FDv2StreamingInitializer

Implements Initializer. Subscribes to the base, completes run() with the first emission, then closes the connection. close() before the first emission yields a shutdown result.

streaming_synchronizer.dart — FDv2StreamingSynchronizer

Implements Synchronizer. Thin adapter forwarding the base's stream and close(), so the orchestrator can treat polling and streaming uniformly.

Auth wiring (deferred to orchestrator)

FDv2StreamingBase does not build URLs or set headers. The orchestrator (SDK-2186) constructs the SSEClient, deciding via sseClient.hasCapability(SSECapability.requestHeaders) whether to set the credential in the Authorization header or as the auth URL query parameter. The streaming source consumes whatever client it's handed.

Verification

• 25 new tests across the three files; full FDv2 directory now at 185 tests.
• dart analyze lib test clean in common_client/.
• melos run analyze and melos run test both pass workspace-wide.

Follow-up (out of scope)

• The orchestrator (C1 / SDK-2186) is what actually wires FDv2StreamingBase into the SDK. This PR delivers the building blocks.

---

Note

Medium Risk
Introduces new long-lived SSE streaming source logic and lifecycle/error handling, which can affect SDK update delivery and reconnect behavior. Risk is mitigated by extensive new unit tests, but the change touches core data-source plumbing.

Overview
Adds an FDv2 SSE-based streaming implementation (FDv2StreamingBase) that translates SSE events into FDv2SourceResults, including handling goodbye, server errors, legacy ping (poll bridge), reconnects (per-OpenEvent handler reset), and x-ld-fd-fallback termination; transport errors are surfaced as interrupted with sanitized logging.

Adds streaming adapters for orchestrator integration: a one-shot FDv2StreamingInitializer that returns the first streaming result then tears down, and a FDv2StreamingSynchronizer that exposes the base as a Synchronizer.

Tightens FDv2 protocol error logging to include payload id (or '<unknown>') and reason, and extends test infrastructure (TestSseClient.isClosed) plus comprehensive new tests covering lifecycle, parsing failures, reconnect safety, ping de-duping, and log sanitization.

^{Reviewed by Cursor Bugbot for commit 892fc8b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

I am undecided if we should support this. If we don't then we can combine the base into the synchronizer and discard it.

Flutter does run on web, but it is inherently a single page app. So I don't think one-shot mode is nearly as important as it is for js.

[kinyoklion]

In practice this last-event-id part isn't relevant to us.

[cursor]

Cursor Bugbot has reviewed your changes using default mode and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 892fc8b. Configure here.}

[cursor]

Missing unawaited() for fire-and-forget async call

Low Severity

_handleMessage(message) is a Future<void> async function called from the sync _handleEvent callback, but the returned Future is silently discarded without wrapping it in unawaited(). The team convention (demonstrated in polling_synchronizer.dart line 82 where unawaited(_doPoll()) is used in its _onListen callback) requires using unawaited() from dart:async to explicitly signal fire-and-forget intent when a sync callback kicks off async work.

 

^{Triggered by learned rule: Use unawaited() not Future.microtask() for fire-and-forget async calls}

^{Reviewed by Cursor Bugbot for commit 892fc8b. Configure here.}

[cursor]

Initializer uses bool instead of Completer for state

Low Severity

FDv2StreamingInitializer implements the Initializer contract but tracks closed state with bool _closed instead of a Completer<void> _stoppedSignal. The team's established pattern for Initializer/Synchronizer implementations (as seen in polling_initializer.dart with _closedSignal and polling_synchronizer.dart with _stoppedSignal) uses a Completer as the single authority for closed/stopped state.

 

^{Triggered by learned rule: Use Completer as single authority for closed/stopped state in data sources}

^{Reviewed by Cursor Bugbot for commit 892fc8b. Configure here.}