Use UTC for consistent tests

Author: simolus3

dart/test/goldens/simple_iteration.json

@@ -137,7 +137,7 @@
             "priority_status": [
               {
                 "priority": 2147483647,
-                "last_synced_at": 1740819600,
+                "last_synced_at": 1740823200,
                 "has_synced": true
               }
             ],

dart/test/sync_test.dart

@@ -18,7 +18,7 @@ import 'utils/native_test_utils.dart';
 void syncTest(String description, void Function(FakeAsync controller) body) {
   return test(description, () {
     // Give each test the same starting time to make goldens easier to compare.
-    fakeAsync(body, initialTime: DateTime(2025, 3, 1, 10));
+    fakeAsync(body, initialTime: DateTime.utc(2025, 3, 1, 10));
   });
 }
 
@@ -254,7 +254,7 @@ void _syncTests<T>({
         // Make sure there's only a single row in last_synced_at
         expect(
           db.select(
-              "SELECT datetime(last_synced_at, 'localtime') AS last_synced_at FROM ps_sync_state WHERE priority = ?",
+              "SELECT datetime(last_synced_at) AS last_synced_at FROM ps_sync_state WHERE priority = ?",
               [prio ?? 2147483647]),
           [
             {'last_synced_at': '2025-03-01 ${10 + i}:00:00'}
@@ -264,7 +264,7 @@ void _syncTests<T>({
         if (prio == null) {
           expect(
             db.select(
-                "SELECT datetime(powersync_last_synced_at(), 'localtime') AS last_synced_at"),
+                "SELECT datetime(powersync_last_synced_at()) AS last_synced_at"),
             [
               {'last_synced_at': '2025-03-01 ${10 + i}:00:00'}
             ],

docs/sync.md

@@ -0,0 +1,79 @@
+## Sync interface
+
+The core extension implements the state machine and necessary SQL handling to decode and apply
+sync line sent from a PowerSync service instance.
+
+After registering the PowerSync extension, this client is available through the `powersync_control`
+function, which takes two arguments: A command (text), and a payload (text, blob, or null).
+
+The following commands are supported:
+
+1. `start`: Payload is a JSON-encoded object. This requests the client to start a sync iteration, specifying
+   parameters.
+2. `stop`: No payload, requests the current sync iteration (if any) to be shut down.
+3. `line_text`: Payload is a serialized JSON object received from the sync service.
+4. `line_binary`: Payload is a BSON-encoded object received from the sync service.
+5. `refreshed_token`: Notify the sync client that the JWT used to authenticate to the PowerSync service has
+   changed.
+   - The client will emit an instruction to stop the current stream, clients should restart by sending another `start`
+     command.
+6. `completed_upload`: Notify the sync implementation that all local changes have been uploaded.
+
+`powersync_control` returns a JSON-encoded array of instructions for the client:
+
+```typescript
+type Instruction = { LogLine: LogLine }
+   | { UpdateSyncStatus: UpdateSyncStatus }
+   | { EstablishSyncStream: EstablishSyncStream }
+   | { FetchCredentials: FetchCredentials }
+   // Close a connection previously started after EstablishSyncStream
+   | { CloseSyncStream: {} }
+   // For the Dart web client, flush the (otherwise non-durable) file system.
+   | { FlushFileSystem: {} }
+   // Notify clients that a checkpoint was completed. Clients can clear the
+   // download error state in response to this.
+   | { DidCompleteSync: {} }
+
+interface LogLine {
+  severity: 'DEBUG' | 'INFO' | 'WARNING',
+  line: String,
+}
+
+// Instructs client SDKs to open a connection to the sync service.
+interface EstablishSyncStream {
+  request: any // The JSON-encoded StreamingSyncRequest to send to the sync service
+}
+
+// Instructs SDKS to update the downloading state of their SyncStatus.
+interface UpdateSyncStatus {
+  connected: boolean,
+  connecting: boolean,
+  priority_status: [],
+  downloading: null | DownloadProgress,
+}
+
+// Instructs SDKs to refresh credentials from the backend connector.
+// They don't necessary have to close the connection, a CloseSyncStream instruction
+// will be sent when the token has already expired.
+interface FetchCredentials {
+  // Set as an option in case fetching and prefetching should be handled differently.
+  did_expire: boolean
+}
+
+interface SyncPriorityStatus {
+  priority: int,
+  last_synced_at: null | int,
+  has_synced: null | boolean,
+}
+
+interface DownloadProgress {
+  buckets: Record<string, BucketProgress>
+}
+
+interface BucketProgress {
+  priority: int,
+  at_last: int,
+  since_last: int,
+  target_count: int
+}
+```