Document custom HTTP clients

client-sdks/reference/flutter.mdx

@@ -348,10 +348,57 @@ class TodosWidget extends StatelessWidget {
   }
 }
 ```
+
 ## Configure Logging
 
 Since version 1.1.2 of the SDK, logging is enabled by default and outputs logs from PowerSync to the console in debug mode.
 
+To disable this, or to configure logging in release-mode configurations, use the `logger` parameter on the `PowerSyncDatabase` constructor.
+PowerSync uses [`package:logging`](https://pub.dev/packages/logging) to emit logs. See that package for additional information.
+
+## Custom HTTP Clients and Headers
+
+PowerSync uses a streaming HTTP response to connect to the PowerSync Service. The SDK uses the default `Client()` from the
+[http package](https://pub.dev/packages/http) for that, which relies on `HttpClient` from `dart:io` on native platforms and `fetch()`
+on the web.
+
+You can also supply a custom HTTP client. This can be used to enable a faster HTTP implementation like [`cronet_http`](https://pub.dev/packages/cronet_http),
+or to add custom request headers that may be required if you run the PowerSync Service behind a reverse-proxy.
+
+```dart
+import 'package:http/http.dart';
+import 'package:powersync/powersync.dart';
+
+final class _AddHeaderClient extends BaseClient {
+  final Client inner;
+
+  _AddHeaderClient([Client? inner]) : inner = inner ?? Client();
+
+  @override
+  Future<StreamedResponse> send(BaseRequest request) {
+    request.headers['x-my-custom-header'] = 'set for all requests';
+    return inner.send(request);
+  }
+
+  @override
+  void close() => inner.close();
+}
+
+Future<void> connect(PowerSyncDatabase db) async {
+  await db.connect(
+    connector: MyBackendConnector(db),
+    options: SyncOptions(
+      httpClient: _AddHeaderClient.new
+    ),
+  );
+}
+```
+
+<Note>
+  On the web, PowerSync uses a shared worker for the sync process. As Dart objects cannot be shared between tabs and workers, the worker will use a
+  random tab as a proxy to send requests. This can slow down the sync process slightly.
+</Note>
+
 ## Additional Usage Examples
 
 For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page.

client-sdks/reference/kotlin.mdx

@@ -320,6 +320,49 @@ Logger.e("Some error");
 ...
 ```
 
+## Custom HTTP Clients and Headers
+
+PowerSync uses streaming HTTP responses or WebSockets to connect to the PowerSync Service. The SDK uses
+[ktor](https://ktor.io/) as a cross-platform HTTP client. `com.powersync:core` depends on an OkHttp-based
+implementation on Android and JVM targets, and on the Darwin engine for native Apple targets.
+
+Configure how the PowerSync SDK sets up client engines by passing an instance of `SyncClientConfiguration.ExtendedConfig`
+in `SyncOptions`:
+
+```kotlin
+import com.powersync.sync.SyncClientConfiguration
+import com.powersync.sync.SyncOptions
+import io.ktor.client.plugins.defaultRequest
+import io.ktor.client.request.header
+
+db.connect(
+    connector,
+    options = SyncOptions(
+        clientConfiguration = SyncClientConfiguration.ExtendedConfig {
+            // For more options, see https://ktor.io/docs/client-create-and-configure.html#plugins
+            defaultRequest {
+                header("X-Custom-Header", "Used by PowerSync")
+            }
+        }
+    )
+)
+```
+
+If you want to use a custom HTTP client engine instead, use `SyncClientConfiguration.ExistingClient`:
+
+```kotlin
+import com.powersync.sync.configureSyncHttpClient
+
+db.connect(
+    connector,
+    options = SyncOptions(
+        clientConfiguration = SyncClientConfiguration.ExistingClient(HttpClient(YourPreferredClientEngine) {
+            // Important: This configures a minimal set of plugins required by the PowerSync sync client.
+            configureSyncHttpClient()
+        })
+    )
+)
+```
 
 ## Additional Usage Examples
 

client-sdks/reference/swift.mdx

@@ -26,7 +26,7 @@
 </CardGroup>
 
 <Note>
   Earlier versions of the Swift SDK (up to v1.13) shipped a PowerSync Kotlin XCFramework under the hood and abstracted it behind Swift protocols.
 
   From v1.14 onward, the Kotlin dependency has been removed entirely. The SDK is now implemented natively in Swift, with the PowerSync sync protocol and SQLite extension handled by our [Rust core](https://github.com/powersync-ja/powersync-sqlite-core). 
 </Note>
@@ -296,7 +296,7 @@
    writes. Outside of SQLite using file locks, there is no additional coordination for multi-process access.
     - Consider using [`PRAGMA busy_timeout`](https://sqlite.org/pragma.html#pragma_busy_timeout) to make SQLite wait longer.
     - Be ready to handle `SQLITE_BUSY` errors if multiple processes attempt to write to the database.
-2. Do not call `connect()` in more than one process: If two processes attempt to connect to the PowerSync service for
+2. Do not call `connect()` in more than one process: If two processes attempt to connect to the PowerSync Service for
    the same database, this wastes resources and can also lead to concurrency issues. If you share databases with extensions
    or app groups, ensure there is only one context responsible for connecting.
 3. Avoid multiple versions of the Swift SDK: While the SQLite file format is stable and databases can safely be accessed
@@ -306,6 +306,30 @@
    This is not a concern for app extensions released as part of the same bundle, but something to be aware of for
    app groups.
 
+## Custom HTTP Clients and Headers
+
+PowerSync uses a streaming HTTP response to connect to the PowerSync Service. By default, the Swift SDK uses `URLSession.shared`
+to run HTTP requests.
+
+You can provide a custom `URLSession` as a sync option. This can be used to add custom HTTP headers, for example:
+
+```swift
+let config = URLSessionConfiguration.ephemeral
+config.httpAdditionalHeaders = ["x-my-custom-header": "example"]
+let session = URLSession(configuration: config)
+
+try await db.connect(
+    connector: connector,
+    options: ConnectOptions(
+        clientConfiguration: SyncClientConfiguration(
+            urlSession: session
+        )
+    )
+)
+```
+
+For more information, see Apple's documentation on [`URLSessionConfiguration`](https://developer.apple.com/documentation/foundation/urlsessionconfiguration).
+
 ## Additional Usage Examples
 
 For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page.