Document custom HTTP clients

client-sdks/reference/flutter.mdx

@@ -348,10 +348,57 @@
   }
 }
 ```
+
 ## 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 @@
 ...
 ```
 
+## 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>
@@ -277,6 +277,30 @@
 
 The `DefaultLogger` supports the following severity levels: `.debug`, `.info`, `.warn`, `.error`. 
 
+## 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.