@powersync/service-core 0.0.0-dev-20250507151436 → 0.0.0-dev-20250611110033

package/src/routes/endpoints/sync-stream.ts

@@ -20,11 +20,19 @@ export const syncStreamed = routeDefinition({
   authorize: authUser,
   validator: schema.createTsCodecValidator(util.StreamingSyncRequest, { allowAdditional: true }),
   handler: async (payload) => {
-    const { service_context } = payload.context;
+    const { service_context, logger } = payload.context;
     const { routerEngine, storageEngine, metricsEngine, syncContext } = service_context;
     const headers = payload.request.headers;
     const userAgent = headers['x-user-agent'] ?? headers['user-agent'];
     const clientId = payload.params.client_id;
+    const streamStart = Date.now();
+
+    logger.defaultMeta = {
+      ...logger.defaultMeta,
+      user_agent: userAgent,
+      client_id: clientId,
+      user_id: payload.context.user_id
+    };
 
     if (routerEngine.closed) {
       throw new errors.ServiceError({
@@ -64,7 +72,8 @@ export const syncStreamed = routeDefinition({
               syncParams,
               token: payload.context.token_payload!,
               tracker,
-              signal: controller.signal
+              signal: controller.signal,
+              logger
             })
           ),
           tracker
@@ -72,16 +81,29 @@ export const syncStreamed = routeDefinition({
         { objectMode: false, highWaterMark: 16 * 1024 }
       );
 
+      // Best effort guess on why the stream was closed.
+      // We use the `??=` operator everywhere, so that we catch the first relevant
+      // event, which is usually the most specific.
+      let closeReason: string | undefined = undefined;
+
       const deregister = routerEngine.addStopHandler(() => {
         // This error is not currently propagated to the client
         controller.abort();
+        closeReason ??= 'process shutdown';
         stream.destroy(new Error('Shutting down system'));
       });
+
+      stream.on('end', () => {
+        // Auth failure or switch to new sync rules
+        closeReason ??= 'service closing stream';
+      });
+
       stream.on('close', () => {
         deregister();
       });
 
       stream.on('error', (error) => {
+        closeReason ??= 'stream error';
         controller.abort();
         // Note: This appears as a 200 response in the logs.
         if (error.message != 'Shutting down system') {
@@ -95,15 +117,16 @@ export const syncStreamed = routeDefinition({
           'Content-Type': 'application/x-ndjson'
         },
         data: stream,
-        afterSend: async () => {
+        afterSend: async (details) => {
+          if (details.clientClosed) {
+            closeReason ??= 'client closing stream';
+          }
           controller.abort();
           metricsEngine.getUpDownCounter(APIMetric.CONCURRENT_CONNECTIONS).add(-1);
           logger.info(`Sync stream complete`, {
-            user_id: syncParams.user_id,
-            client_id: clientId,
-            user_agent: userAgent,
-            operations_synced: tracker.operationsSynced,
-            data_synced_bytes: tracker.dataSyncedBytes
+            ...tracker.getLogMeta(),
+            stream_ms: Date.now() - streamStart,
+            close_reason: closeReason ?? 'unknown'
           });
         }
       });

package/src/routes/route-register.ts

@@ -1,4 +1,5 @@
 import type fastify from 'fastify';
+import * as uuid from 'uuid';
 
 import { errors, HTTPMethod, logger, router } from '@powersync/lib-services-framework';
 import { Context, ContextProvider, RequestEndpoint, RequestEndpointHandlerPayload } from './router.js';
@@ -25,9 +26,12 @@ export function registerFastifyRoutes(
         handler: async (request, reply) => {
           const startTime = new Date();
           let response: router.RouterResponse;
+          const requestLogger = logger.child({
+            route: e.path,
+            rid: `h/${uuid.v7()}`
+          });
           try {
-            const context = await contextProvider(request);
-
+            const context = await contextProvider(request, { logger: requestLogger });
             let combined = {
               ...(request.params as any),
               ...(request.query as any)
@@ -63,7 +67,7 @@ export function registerFastifyRoutes(
             }
           } catch (ex) {
             const serviceError = errors.asServiceError(ex);
-            logger.error(`Request failed`, serviceError);
+            requestLogger.error(`Request failed`, serviceError);
 
             response = new router.RouterResponse({
               status: serviceError.errorData.status || 500,
@@ -83,13 +87,12 @@ export function registerFastifyRoutes(
           try {
             await reply.send(response.data);
           } finally {
-            await response.afterSend?.();
-            logger.info(`${e.method} ${request.url}`, {
+            await response.afterSend?.({ clientClosed: request.socket.closed });
+            requestLogger.info(`${e.method} ${request.url}`, {
               duration_ms: Math.round(new Date().valueOf() - startTime.valueOf() + Number.EPSILON),
               status: response.status,
               method: e.method,
-              path: request.url,
-              route: e.path
+              path: request.url
             });
           }
         }

package/src/routes/router.ts

@@ -1,4 +1,4 @@
-import { router } from '@powersync/lib-services-framework';
+import { router, ServiceError, Logger } from '@powersync/lib-services-framework';
 import type { JwtPayload } from '../auth/auth-index.js';
 import { ServiceContext } from '../system/ServiceContext.js';
 import { RouterEngine } from './RouterEngine.js';
@@ -17,11 +17,13 @@ export type Context = {
   service_context: RouterServiceContext;
 
   token_payload?: JwtPayload;
-  token_errors?: string[];
+  token_error?: ServiceError;
   /**
    * Only on websocket endpoints.
    */
   user_agent?: string;
+
+  logger: Logger;
 };
 
 export type BasicRouterRequest = {
@@ -30,7 +32,11 @@ export type BasicRouterRequest = {
   hostname: string;
 };
 
-export type ContextProvider = (request: BasicRouterRequest) => Promise<Context>;
+export type ConextProviderOptions = {
+  logger: Logger;
+};
+
+export type ContextProvider = (request: BasicRouterRequest, options: ConextProviderOptions) => Promise<Context>;
 
 export type RequestEndpoint<
   I,

package/src/storage/BucketStorageBatch.ts

@@ -2,12 +2,13 @@ import { ObserverClient } from '@powersync/lib-services-framework';
 import { EvaluatedParameters, EvaluatedRow, SqliteRow, ToastableSqliteRow } from '@powersync/service-sync-rules';
 import { BSON } from 'bson';
 import { ReplicationEventPayload } from './ReplicationEventPayload.js';
-import { SourceTable } from './SourceTable.js';
+import { SourceTable, TableSnapshotStatus } from './SourceTable.js';
 import { BatchedCustomWriteCheckpointOptions } from './storage-index.js';
 import { InternalOpId } from '../util/utils.js';
 
 export const DEFAULT_BUCKET_BATCH_COMMIT_OPTIONS: ResolvedBucketBatchCommitOptions = {
-  createEmptyCheckpoints: true
+  createEmptyCheckpoints: true,
+  oldestUncommittedChange: null
 };
 
 export interface BucketStorageBatch extends ObserverClient<BucketBatchStorageListener>, AsyncDisposable {
@@ -44,6 +45,8 @@ export interface BucketStorageBatch extends ObserverClient<BucketBatchStorageLis
    * Flush and commit any saved ops. This creates a new checkpoint by default.
    *
    * Only call this after a transaction.
+   *
+   * Returns true if either (1) a new checkpoint was created, or (2) there are no changes to commit.
    */
   commit(lsn: string, options?: BucketBatchCommitOptions): Promise<boolean>;
 
@@ -56,6 +59,14 @@ export interface BucketStorageBatch extends ObserverClient<BucketBatchStorageLis
    */
   keepalive(lsn: string): Promise<boolean>;
 
+  /**
+   * Set the LSN for a snapshot, before starting replication.
+   *
+   * Not required if the source database keeps track of this, for example with
+   * PostgreSQL logical replication slots.
+   */
+  setSnapshotLsn(lsn: string): Promise<void>;
+
   /**
    * Get the last checkpoint LSN, from either commit or keepalive.
    */
@@ -63,6 +74,8 @@ export interface BucketStorageBatch extends ObserverClient<BucketBatchStorageLis
 
   markSnapshotDone(tables: SourceTable[], no_checkpoint_before_lsn: string): Promise<SourceTable[]>;
 
+  updateTableProgress(table: SourceTable, progress: Partial<TableSnapshotStatus>): Promise<SourceTable>;
+
   /**
    * Queues the creation of a custom Write Checkpoint. This will be persisted after operations are flushed.
    */
@@ -154,6 +167,13 @@ export interface BucketBatchCommitOptions {
    * Defaults to true.
    */
   createEmptyCheckpoints?: boolean;
+
+  /**
+   * The timestamp of the first change in this batch, according to the source database.
+   *
+   * Used to estimate replication lag.
+   */
+  oldestUncommittedChange?: Date | null;
 }
 
 export type ResolvedBucketBatchCommitOptions = Required<BucketBatchCommitOptions>;

package/src/storage/PersistedSyncRulesContent.ts

@@ -9,6 +9,12 @@ export interface PersistedSyncRulesContent {
   readonly id: number;
   readonly sync_rules_content: string;
   readonly slot_name: string;
+  /**
+   * True if this is the "active" copy of the sync rules.
+   */
+  readonly active: boolean;
+
+  readonly last_checkpoint_lsn: string | null;
 
   readonly last_fatal_error?: string | null;
   readonly last_keepalive_ts?: Date | null;

package/src/storage/SourceTable.ts

@@ -2,6 +2,12 @@ import { DEFAULT_TAG } from '@powersync/service-sync-rules';
 import * as util from '../util/util-index.js';
 import { ColumnDescriptor } from './SourceEntity.js';
 
+export interface TableSnapshotStatus {
+  totalEstimatedCount: number;
+  replicatedCount: number;
+  lastKey: Uint8Array | null;
+}
+
 export class SourceTable {
   static readonly DEFAULT_TAG = DEFAULT_TAG;
 
@@ -32,6 +38,13 @@ export class SourceTable {
    */
   public syncEvent = true;
 
+  /**
+   * Always undefined if snapshotComplete = true.
+   *
+   * May be set if snapshotComplete = false.
+   */
+  public snapshotStatus: TableSnapshotStatus | undefined = undefined;
+
   constructor(
     public readonly id: any,
     public readonly connectionTag: string,
@@ -40,7 +53,7 @@ export class SourceTable {
     public readonly table: string,
 
     public readonly replicaIdColumns: ColumnDescriptor[],
-    public readonly snapshotComplete: boolean
+    public snapshotComplete: boolean
   ) {}
 
   get hasReplicaIdentity() {
@@ -68,4 +81,34 @@ export class SourceTable {
   get syncAny() {
     return this.syncData || this.syncParameters || this.syncEvent;
   }
+
+  /**
+   * In-memory clone of the table status.
+   */
+  clone() {
+    const copy = new SourceTable(
+      this.id,
+      this.connectionTag,
+      this.objectId,
+      this.schema,
+      this.table,
+      this.replicaIdColumns,
+      this.snapshotComplete
+    );
+    copy.syncData = this.syncData;
+    copy.syncParameters = this.syncParameters;
+    copy.snapshotStatus = this.snapshotStatus;
+    return copy;
+  }
+
+  formatSnapshotProgress() {
+    if (this.snapshotComplete || this.snapshotStatus == null) {
+      // Should not happen
+      return '-';
+    } else if (this.snapshotStatus.totalEstimatedCount < 0) {
+      return `${this.snapshotStatus.replicatedCount}/?`;
+    } else {
+      return `${this.snapshotStatus.replicatedCount}/~${this.snapshotStatus.totalEstimatedCount}`;
+    }
+  }
 }

package/src/storage/SyncRulesBucketStorage.ts

@@ -1,7 +1,7 @@
-import { ObserverClient } from '@powersync/lib-services-framework';
+import { Logger, ObserverClient } from '@powersync/lib-services-framework';
 import { ParameterLookup, SqlSyncRules, SqliteJsonRow } from '@powersync/service-sync-rules';
 import * as util from '../util/util-index.js';
-import { BucketStorageBatch, FlushedResult } from './BucketStorageBatch.js';
+import { BucketStorageBatch, FlushedResult, SaveUpdate } from './BucketStorageBatch.js';
 import { BucketStorageFactory } from './BucketStorageFactory.js';
 import { ParseSyncRulesOptions } from './PersistedSyncRulesContent.js';
 import { SourceEntityDescriptor } from './SourceEntity.js';
@@ -125,6 +125,7 @@ export interface SyncRuleStatus {
   checkpoint_lsn: string | null;
   active: boolean;
   snapshot_done: boolean;
+  snapshot_lsn: string | null;
 }
 export interface ResolveTableOptions {
   group_id: number;
@@ -159,6 +160,15 @@ export interface StartBatchOptions extends ParseSyncRulesOptions {
    * This will avoid creating new operations for rows previously replicated.
    */
   skipExistingRows?: boolean;
+
+  /**
+   * Callback called if we streamed an update to a record that we don't have yet.
+   *
+   * This is expected to happen in some initial replication edge cases, only if storeCurrentData = true.
+   */
+  markRecordUnavailable?: BucketStorageMarkRecordUnavailable;
+
+  logger?: Logger;
 }
 
 export interface CompactOptions {
@@ -274,3 +284,5 @@ export const CHECKPOINT_INVALIDATE_ALL: CheckpointChanges = {
   updatedParameterLookups: new Set<string>(),
   invalidateParameterBuckets: true
 };
+
+export type BucketStorageMarkRecordUnavailable = (record: SaveUpdate) => void;

package/src/storage/bson.ts

@@ -10,7 +10,10 @@ type NodeBuffer = Buffer<ArrayBuffer>;
  */
 export const BSON_DESERIALIZE_INTERNAL_OPTIONS: bson.DeserializeOptions = {
   // use bigint instead of Long
-  useBigInt64: true
+  useBigInt64: true,
+  // We cannot use promoteBuffers: true, since that also converst UUID to Buffer
+  // Instead, we need to handle bson.Binary when reading data
+  promoteBuffers: false
 };
 
 /**