Support for configuring the browser `fetch` credentials mode in `BrowserClient`. by mauriceraguseinit · Pull Request #1937 · dart-lang/http

mauriceraguseinit · 2026-06-02T11:44:55Z

This PR adds support for configuring the browser fetch credentials mode in BrowserClient.

Currently BrowserClient only exposes a boolean withCredentials option, which maps to either same-origin (when false) or include (when true). The browser fetch API, however, supports a third credentials mode, omit, which cannot be expressed through the existing boolean API. The only way to use omit today is to fork or copy BrowserClient and change the RequestInit manually.

Closes #1936.

What this changes

Adds a new BrowserCredentialsMode enum with the values omit, sameOrigin, and include, matching the three credentials modes defined by the [Fetch standard](https://fetch.spec.whatwg.org/#requestcredentials).
Adds a credentialsMode property and constructor parameter to BrowserClient, defaulting to BrowserCredentialsMode.sameOrigin to preserve the existing default behavior.
The RequestInit.credentials value is now derived from credentialsMode.

Backward compatibility

The existing withCredentials property is kept and continues to work, but is now deprecated because a boolean cannot represent all three credentials modes.
It is implemented as a compatibility adapter on top of credentialsMode:
- the getter returns true only when credentialsMode is include;
- the setter maps true to include and false to sameOrigin.
Existing code such as BrowserClient()..withCredentials = true keeps producing the same fetch behavior as before.

New usage

final client = BrowserClient(
  credentialsMode: BrowserCredentialsMode.omit,
);

I’ve reviewed the contributor guide and applied the relevant portions to this PR.

google-cla · 2026-06-02T11:45:07Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

brianquinlan

It it possible to construct tests for this? Also update CHANGELOG.md.

brianquinlan · 2026-06-22T23:49:51Z

+  ///
+  /// Defaults to [BrowserCredentialsMode.sameOrigin], which matches the
+  /// previous behavior when [withCredentials] was `false`.
+  BrowserCredentialsMode credentialsMode;


Can we make this private? I think that mutating it after construction is error-prone in any case.

I agree that mutating this after construction is error-prone. However, withCredentials was a mutable public field in the original code. Making requestCredentials final and removing or disabling the withCredentials setter would break backwards compatibility for users who configure the client after instantiation.
How do we want to deal with this?

How about we make credentialsMode non-final but private. The withCredentials setter can mutate it. When withCredentials is removed, we can make credentialsMode final. WDYT?

brianquinlan · 2026-06-22T23:50:47Z

+///
+/// See also:
+/// - https://fetch.spec.whatwg.org/#requestcredentials
+enum BrowserCredentialsMode {


Do we want to call this RequestCredentials to match the spec?

brianquinlan · 2026-06-22T23:52:26Z

+  /// This corresponds to the browser `fetch` credentials mode `omit`.
+  omit('omit'),
+
+  /// Send credentials for same-origin requests only.


and only include credentials in same-origin replies.

brianquinlan · 2026-06-22T23:52:54Z

+  /// This corresponds to the browser `fetch` credentials mode `same-origin`.
+  sameOrigin('same-origin'),
+
+  /// Always send credentials, even for cross-origin requests.


...and include them in all responses.

…ch credentials modes - Introduce `RequestCredentials` enum (`omit`, `same-origin`, `include`). - Deprecate `withCredentials` getter and setter while maintaining full backwards compatibility. - Update README.md with instructions on how to use the new parameter. - Add unit tests verifying correct constructor initialization and fallback behaviors.

mauriceraguseinit · 2026-06-23T07:34:44Z

I have taken the comments regarding the implementation into account and adjusted the code.

github-actions · 2026-06-23T16:23:55Z

PR Health

Unused Dependencies

⚠️

Package	Status
http	❗ Show Issues These packages may be unused, or you may be using assets from these packages: * dart_flutter_team_lints * shelf

For details on how to fix these, see dependency_validator.

This check can be disabled by tagging the PR with skip-unused-dependencies-check.

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?
http	Non-Breaking	1.6.0	1.6.2-wip	1.6.2-wip	✔️

This check can be disabled by tagging the PR with skip-breaking-check.

API leaks

⚠️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources
http	RequestCredentials	browser_client.dart::BrowserClient::requestCredentials browser_client.dart::RequestCredentials::omit browser_client.dart::RequestCredentials::sameOrigin browser_client.dart::RequestCredentials::include browser_client.dart::RequestCredentials::values browser_client.dart::BrowserClient::new::requestCredentials

This check can be disabled by tagging the PR with skip-leaking-check.

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Coverage

⚠️

File	Coverage
pkgs/http/lib/src/browser_client.dart	💔 Not covered

This check for test coverage is informational (issues shown here will not fail the PR).

This check can be disabled by tagging the PR with skip-coverage-check.

License Headers ✔️

// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/cupertino_http/example/example.dart
pkgs/http/example/main.dart
pkgs/http_multi_server/test/cert.dart

This check can be disabled by tagging the PR with skip-license-check.

brianquinlan · 2026-06-23T16:31:08Z

@@ -1,3 +1,7 @@
+## 1.6.2-wip


1.6.1-wip (the -wip means Work-In-Progress) has not yet been released so you don't need to add a new version - just add your note to the 1.6.1-wip section.

brianquinlan · 2026-06-23T16:31:23Z

@@ -1,3 +1,7 @@
+## 1.6.2-wip
+
+* Add `BrowserCredentialsMode` and `BrowserClient.credentialsMode` to support the `omit` browser fetch credentials mode. Deprecate `withCredentials`.


80 columns please

brianquinlan · 2026-06-23T16:31:32Z

@@ -1,5 +1,5 @@
 name: http
-version: 1.6.1-wip
+version: 1.6.2-wip


You can revert this.

brianquinlan · 2026-06-23T16:34:07Z

@@ -0,0 +1,47 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file


I was imagining that these tests could actually verify the client/server interaction by running an HTTP server. But now I'm not sure if that is possible without actually server the Dart-compiled Javascript from the same host/port as the test server. If it is not possible, then I don't think that these tests are valuable and you can delete them. Sorry for asking you to do this unnecessary work.

brianquinlan · 2026-06-23T16:34:46Z

 | [`package:fetch_client`][fetch] — [`FetchClient`][fetchclient] | Web | Dart, Flutter | ✅︎ | ✅︎ | ✅︎ |

+> [!NOTE]
+> [`BrowserClient`][browserclient] allows you to configure the browser `fetch` credentials mode (e.g., `omit`, `same-origin`, `include`) by passing the `requestCredentials` parameter to its constructor.


80 columns

But this actually feels out of place to mention a client's feature here. Maybe add this to the dartdoc for BrowserClient?

brianquinlan · 2026-06-23T16:36:45Z

 class BrowserClient extends BaseClient {
+  /// Create a [BrowserClient].
+  ///
+  /// By default, credentials are sent for same-origin requests only, which


I would remove. Most people will not be aware of the past behavior.

mauriceraguseinit added 2 commits June 2, 2026 13:30

add enum for omit value

15c7647

add changelog and new version

cf337e4

github-actions Bot added the package:http label Jun 2, 2026

brianquinlan self-requested a review June 22, 2026 23:44

brianquinlan requested changes Jun 22, 2026

View reviewed changes

mauriceraguseinit requested a review from brianquinlan June 23, 2026 07:37

brianquinlan reviewed Jun 23, 2026

View reviewed changes

		@@ -1,3 +1,7 @@
		## 1.6.2-wip

		* Add `BrowserCredentialsMode` and `BrowserClient.credentialsMode` to support the `omit` browser fetch credentials mode. Deprecate `withCredentials`.

		@@ -0,0 +1,47 @@
		// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file

Conversation

mauriceraguseinit commented Jun 2, 2026

What this changes

Backward compatibility

New usage

Uh oh!

google-cla Bot commented Jun 2, 2026

Uh oh!

brianquinlan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mauriceraguseinit commented Jun 23, 2026

Uh oh!

github-actions Bot commented Jun 23, 2026

PR Health

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants