Skip to content

test: Add a browser contract test service that uses the HTTP SSE client - #360

Open
joker23 wants to merge 7 commits into
mainfrom
skz/sdk-3443/contract-test-capabilities
Open

joker23 wants to merge 7 commits into
mainfrom
skz/sdk-3443/contract-test-capabilities

Conversation

@joker23

@joker23 joker23 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Adds apps/flutter_web_contract_test_service, a contract test service that runs the Flutter SDK in headless Chrome. The SDK streams with the HTTP-based SSE client through eventSource: SSEClient.http. The browser native EventSource cannot send a request body or report an HTTP error. This is the only contract test run that covers usePost and HTTP error handling for streaming on web.
  • The contract test harness speaks REST, and a browser cannot listen for requests. So bin/adapter.dart runs on the Dart VM, serves the REST API, starts Chrome, and relays each request to a Flutter web app over a websocket. The same design is used by the JS browser SDK contract tests.
  • The browser reports its capabilities when it connects. It declares client-use-post and client-event-source-http-errors because it always uses the HTTP-based SSE client. It also declares context-type and polling-gzip, which pass on web.
  • Adds browser-contract-tests to the CI workflow (FDv1 and FDv2 runs), and the client-web-contract-tests and client-web-contract-tests-fdv2 melos scripts.
  • The suppression files start from the lists of the JS browser SDK fetch event source runs, and each file states where it differs. Both lists skip the kind: null context type test, as the existing Flutter service does.
  • Adds the missing harness step to the README of the existing contract test service.

Notes

  • auto-env-attributes is not declared, as in the JS browser SDK. Hooks are not mapped yet.
  • The mapping code in lib/src/entity.dart repeats code from the existing service. That service uses generated types that need dart:io, so it cannot share them yet.

Note

Overview
Adds apps/flutter_web_contract_test_service, a harness-facing contract test run that executes the Flutter client SDK in headless Chrome with eventSource: SSEClient.http, so usePost and HTTP streaming error scenarios are covered—behavior the native browser EventSource path cannot exercise.

A VM bin/adapter.dart exposes the harness REST API, serves the web build, launches Chrome, and relays requests over WebSocket to a minimal lib/main.dart entity that drives LDClient and advertises capabilities including client-use-post and client-event-source-http-errors.

CI gains a browser-contract-tests job (FDv1 + FDv2 harness runs, adapter restarts between runs, adapter log artifacts). melos.yaml adds client-web-contract-tests / client-web-contract-tests-fdv2. Harness suppression lists (FDv1/FDv2) document web/CORS tag-header skips. The existing flutter_client_contract_test_service README documents how to run the harness locally.

Reviewed by Cursor Bugbot for commit 91dc808. Bugbot is set up for automated code reviews on this repo. Configure here.

@joker23
joker23 added this pull request to stack #361 November 2, 2026 20:17
@joker23 joker23 closed this Nov 2, 2026
@joker23
joker23 force-pushed the skz/sdk-3443/contract-test-capabilities branch from 6dd55ca to 458d103 Compare November 2, 2026 21:58
@joker23 joker23 reopened this Nov 2, 2026
@joker23 joker23 changed the title fix: Advertise streaming capabilities only when the SSE client supports them test: Add a browser contract test service that uses the HTTP SSE client Nov 2, 2026
@joker23
joker23 force-pushed the skz/sdk-3443/contract-test-capabilities branch 14 times, most recently from dd2985a to 84ee448 Compare November 5, 2026 22:53
@joker23
joker23 marked this pull request as ready for review November 6, 2026 18:06
@joker23
joker23 requested a review from a team as a code owner November 6, 2026 18:06

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 2 potential issues.

Devin Review

Comment on lines +503 to +505
sdks:
dart: ">=3.11.0 <4.0.0"
flutter: ">=3.41.0"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 Browser tests cannot use committed dependency graph

The lockfile requires Dart >=3.11.0 and Flutter >=3.41.0; browser-contract-tests installs 3.7.2 and 3.29.3. CI therefore resolves other dependency versions rather than exercising this lockfile.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This matches the sibling apps/flutter_client_contract_test_service/pubspec.lock, whose footer is also above the oldest CI toolchain. CI runs melos bootstrap, which re-resolves the lock for the installed SDK, and both the 3.22.3 / 3.4.4 job and browser-contract-tests pass on this head.

cursor[bot]

This comment was marked as resolved.

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 1 new potential issue.

Devin Review

_stopping = true;
// Release the port first. The next harness run binds it while the
// browser is still on its way out.
await _server.close();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Outstanding commands can block adapter shutdown

When a browser command remains unanswered, shutdown() waits for its HTTP request to finish before stopping Chrome. The request awaits a websocket reply in _rest, leaving shutdown stuck and the browser running.

Learn more

Closing an HttpServer without force waits for active HTTP requests to finish. A command request remains active while _rest awaits _send; its pending reply is completed when the browser replies or disconnects. With an unanswered command, shutdown() waits on the server before killing Chrome or closing the relay. Stopping the adapter therefore cannot release that request.

Example: A harness POST waits on a browser command that never replies, then the harness sends DELETE /. The DELETE initiates shutdown, but the POST remains active, so the adapter neither stops Chrome nor completes shutdown.

Recommended fix: Stop Chrome and close the websocket before waiting for a graceful server close, as this releases pending command requests. If the port must be released first, initiate closure without awaiting it and ensure outstanding requests are completed or use a bounded forced close.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dart's HttpServer.close() without force only closes the listening socket and idle connections. The returned future does not wait for active requests (see _HttpServer.close in the SDK's http_impl.dart). DELETE / also runs shutdown() unawaited, and main calls exit(0) once stopped completes, so a parked command does not block the Chrome teardown.

@joker23
joker23 force-pushed the skz/sdk-3443/contract-test-capabilities branch 5 times, most recently from ce1d5df to 68dc044 Compare November 10, 2026 20:44
joker23 added a commit that referenced this pull request Nov 12, 2026
… streaming (#358)

## Summary

- Adds `eventSource` to `LDCommonConfig`, an optional
`SseClientBuilder`. When it is null, the SDK uses the default client for
the platform. On web, that is the browser `EventSource`, which cannot
send a request body or report an HTTP error. An app passes
`SSEClient.http` to stream with `fetch()` instead, so `useReport` and
`usePost` work on web. On other platforms the default client is already
`SSEClient.http`.
- The app passes the implementation, so a web build that leaves the
option null never references the HTTP SSE client and the compiler
removes it. A runtime bool would keep both clients reachable. Measured
with `dart compile js -O2` against `common_client`: 324 KB without the
option, 354 KB with `SSEClient.http`.
- `SSEClient` and `SseClientBuilder` are exported from `common_client`.
No other SSE type is exported.
- A supplied builder is treated as able to send POST and REPORT. Without
one, `useReport` on web falls back to GET with a warning, and `usePost`
on web skips the streaming sources and polls, as before.
- On web, the SDK drops the application tags header from the streaming
request. The CORS allow-list of the streaming service does not include
it. The unused `streamingReportSupported` platform getters are removed.
- FDv1 streaming uses the client-side ID as the environment ID when the
connect headers are present but lack it, as happens after CORS
filtering.
- Both streaming data sources build their client through the same
builder type, so tests inject a fake client the same way on both paths.
- Adds a Chrome test file for the web-only decisions and a CI step that
runs it with `dart test -p chrome`.

## Additional context

This PR moves the exact pin of `launchdarkly_event_source_client` in
`common_client` from 3.0.1 to 3.1.0, which ships `SSEClient.http`.

This PR is the bottom of a stack. #359 and #360 build on it.

## Related tickets

- sdk-3441

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> Adds **`LDCommonConfig.eventSource`**, an optional `SseClientBuilder`,
and wires it through FDv1 `StreamingDataSource` and FDv2
`FDv2DataSystem` so apps can supply **`SSEClient.http`** on web and
enable **POST/REPORT** streaming instead of default browser **GET** or
polling fallbacks.
> 
> Introduces **`streaming_client.dart`** with shared
**`streamingRequestHeaders`** (drops **`x-launchdarkly-tags`** on web
for CORS) and **`streamingCustomMethodSupported`** to decide POST/REPORT
vs fallbacks. Platform defaults replace **`streamingReportSupported`**
with **`streamingPostSupported`** and
**`streamingTagsHeaderSupported`**. FDv1 streaming now falls back to the
client-side ID for environment ID when connect headers omit it after
CORS filtering.
> 
> Exports **`SseClientBuilder`** and **`SSEClient`**, bumps
**`launchdarkly_event_source_client`** to **3.1.0**, and adds Chrome CI
plus VM/browser tests for web-only streaming behavior.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
1cfae3d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
@joker23
joker23 force-pushed the skz/sdk-3443/contract-test-capabilities branch 2 times, most recently from 801d6fb to f9e3c8c Compare November 12, 2026 19:12
Base automatically changed from skz/sdk-3442/event-source-factory-config to main November 12, 2026 20:05
joker23 added a commit that referenced this pull request Nov 12, 2026
## Summary

- Adds an optional `eventSource` to `LDConfig` and passes it to the
common config. Exports `SSEClient` and `SseClientBuilder` from the
Flutter package so an app can pass `SSEClient.http`.
- The API docs describe the web default, the fallbacks it causes for
`useReport` and `usePost`, and that a web build that leaves the option
null does not include the HTTP-based client. Most applications do not
need it.
- Default behavior is unchanged when the option is not set.

## Additional context

This PR also moves the exact pin of `launchdarkly_common_client` in
`flutter_client_sdk` from 1.15.1 to 1.16.0, which ships the
`eventSource` option on `LDCommonConfig`.

This PR is the bottom of a stack. #360 builds on it.

## Related tickets

- sdk-3442

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> The Flutter SDK now exposes an optional **`eventSource`** on
**`LDConfig`**, forwarding to the shared common config so apps can
choose which SSE client handles flag streaming.
> 
> **`SSEClient`** and **`SseClientBuilder`** are re-exported from the
package entrypoint (e.g. so web apps can pass **`SSEClient.http`** for
`fetch()`-based streaming). API docs spell out the web default
(`EventSource`), related fallbacks for **`useReport`** / **`usePost`**,
and that leaving the option null keeps the HTTP client out of web
builds.
> 
> Behavior is unchanged when **`eventSource`** is omitted; tests assert
default null and that a supplied builder is retained.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
11a4bd3. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
@joker23
joker23 force-pushed the skz/sdk-3443/contract-test-capabilities branch from f9e3c8c to b08837d Compare November 12, 2026 20:05

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 2 new potential issues.

Devin Review

if (segments.isNotEmpty && segments.first == _appPath) {
return staticHandler(request.change(path: _appPath));
}
return adapter._rest(request);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟥 Local processes can control test clients

Any local process can POST to Adapter and create clients with arbitrary service endpoints or stop the running service. The REST interface has no authentication despite controlling the browser and SDK network requests.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a local test harness. The adapter binds to the loopback interface only, and the websocket accepts only the origin that this adapter serves. The other contract test services in this repo are also unauthenticated, and the harness cannot send credentials. Not changing.

_profile = await Directory.systemTemp.createTemp('flutter-web-entity');
final browser = _browser = await Process.start(executable, [
'--headless=new',
'--no-sandbox',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟨 Headless Chrome runs without sandbox isolation

Every adapter launch disables Chrome’s sandbox, even when Chrome runs as a non-root user. Malicious content reached during browser tests gains a less isolated browser process.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Headless Chrome runs in a CI container or runner, and it needs --no-sandbox there. The adapter loads only the test app that it serves itself and the SDK's test endpoints. This is a test-only tool. Not changing.

@joker23
joker23 force-pushed the skz/sdk-3443/contract-test-capabilities branch from b08837d to 91dc808 Compare November 12, 2026 20:46

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant