@powersync/service-core 1.20.5 → 1.22.0

package/package.json

@@ -5,7 +5,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.20.5",
+  "version": "1.22.0",
   "main": "dist/index.js",
   "license": "FSL-1.1-ALv2",
   "type": "module",
@@ -24,26 +24,26 @@
     "ipaddr.js": "^2.1.0",
     "ix": "^5.0.0",
     "jose": "^4.15.1",
-    "lodash": "^4.17.21",
+    "lodash": "^4.18.1",
     "lru-cache": "^10.2.2",
     "negotiator": "^1.0.0",
     "node-fetch": "^3.3.2",
     "ts-codec": "^1.3.0",
     "uri-js": "^4.4.1",
-    "uuid": "^11.1.0",
+    "uuid": "^14.0.0",
     "winston": "^3.13.0",
-    "yaml": "^2.3.2",
-    "@powersync/lib-services-framework": "0.9.3",
-    "@powersync/service-rsocket-router": "0.2.19",
-    "@powersync/service-jsonbig": "0.17.12",
-    "@powersync/service-sync-rules": "0.35.0",
-    "@powersync/service-types": "0.15.1"
+    "yaml": "^2.8.3",
+    "@powersync/lib-services-framework": "0.9.5",
+    "@powersync/service-jsonbig": "0.17.13",
+    "@powersync/service-rsocket-router": "0.2.21",
+    "@powersync/service-sync-rules": "0.37.0",
+    "@powersync/service-types": "0.15.2"
   },
   "devDependencies": {
     "@types/async": "^3.2.24",
-    "@types/negotiator": "^0.6.4",
     "@types/lodash": "^4.17.5",
-    "fastify": "^5.8.2",
+    "@types/negotiator": "^0.6.4",
+    "fastify": "^5.8.5",
     "fastify-plugin": "^5.0.1"
   },
   "scripts": {

package/src/api/RouteAPI.ts

@@ -43,7 +43,7 @@ export interface RouteAPI {
    * Generates replication table information from a given pattern of tables.
    *
    * @param tablePatterns A set of table patterns which typically come from
-   *          the tables listed in sync rules definitions.
+   *          the tables listed in sync config definitions.
    *
    * @param sqlSyncRules
    * @returns A result of all the tables and columns which should be replicated
@@ -76,7 +76,7 @@ export interface RouteAPI {
 
   /**
    * @returns The schema for tables inside the connected database. This is typically
-   *          used to validate sync rules.
+   *          used to validate sync config.
    */
   getConnectionSchema(): Promise<types.DatabaseSchema[]>;
 
@@ -92,7 +92,7 @@ export interface RouteAPI {
   shutdown(): Promise<void>;
 
   /**
-   * Get the default schema (or database) when only a table name is specified in sync rules.
+   * Get the default schema (or database) when only a table name is specified in sync config.
    */
   getParseSyncRulesOptions(): ParseSyncRulesOptions;
 }

package/src/api/diagnostics.ts

@@ -1,5 +1,5 @@
 import { logger } from '@powersync/lib-services-framework';
-import { DEFAULT_TAG, SourceTableInterface, SyncConfigWithErrors } from '@powersync/service-sync-rules';
+import { DEFAULT_TAG, SourceTableRef, SyncConfigWithErrors } from '@powersync/service-sync-rules';
 import { ReplicationError, SyncRulesStatus, TableInfo } from '@powersync/service-types';
 
 import * as storage from '../storage/storage-index.js';
@@ -8,7 +8,7 @@ import { RouteAPI, SlotWalBudgetInfo } from './RouteAPI.js';
 
 export interface DiagnosticsOptions {
   /**
-   * Include sync rules content in response.
+   * Include sync config content in response.
    */
   include_content?: boolean;
 
@@ -46,7 +46,7 @@ export async function getSyncRulesStatus(
   let persisted: storage.PersistedSyncRules;
   try {
     persisted = sync_rules.parsed(apiHandler.getParseSyncRulesOptions());
-    parsed = persisted.sync_rules;
+    parsed = persisted.syncConfigWithErrors;
   } catch (e) {
     return {
       content: include_content ? sync_rules.sync_rules_content : undefined,
@@ -90,7 +90,7 @@ export async function getSyncRulesStatus(
         logger.warn(`Unable to get replication lag`, e);
       }
 
-      if (apiHandler.getSlotWalBudget) {
+      if (apiHandler.getSlotWalBudget && sync_rules.slot_name) {
         try {
           slot_wal_budget = await apiHandler.getSlotWalBudget({
             slotName: sync_rules.slot_name
@@ -116,7 +116,7 @@ export async function getSyncRulesStatus(
           errors: [{ level: 'fatal', message: 'connection failed', ts: now }]
         };
       } else {
-        const source: SourceTableInterface = {
+        const source: SourceTableRef = {
           connectionTag: tag,
           schema: pattern.schema,
           name: pattern.tablePattern
@@ -145,8 +145,31 @@ export async function getSyncRulesStatus(
   }
   errors.push(...syncRuleErrors.map((error) => syncConfigYamlErrorToReplicationError(error, now)));
 
+  if (
+    slot_wal_budget &&
+    slot_wal_budget.wal_status !== 'lost' &&
+    slot_wal_budget.safe_wal_size != null &&
+    slot_wal_budget.max_slot_wal_keep_size != null &&
+    slot_wal_budget.max_slot_wal_keep_size > 0
+  ) {
+    const budgetPct = Math.max(
+      0,
+      Math.round((slot_wal_budget.safe_wal_size / slot_wal_budget.max_slot_wal_keep_size) * 100)
+    );
+    if (budgetPct <= 50) {
+      errors.push({
+        level: 'warning',
+        message:
+          `WAL budget is low: ${budgetPct}% remaining. ` +
+          `The replication slot may be invalidated if WAL consumption ` +
+          `continues at this rate. Consider increasing max_slot_wal_keep_size.`,
+        ts: now
+      });
+    }
+  }
+
   if (live_status && status?.active) {
-    // Check replication lag for active sync rules.
+    // Check replication lag for active replication stream.
     // Right now we exclude mysql, since it we don't have consistent keepalives for it.
     if (sync_rules.last_checkpoint_ts == null && sync_rules.last_keepalive_ts == null) {
       errors.push({

package/src/auth/RemoteJWKSCollector.ts

@@ -5,6 +5,7 @@ import fetch from 'node-fetch';
 import {
   AuthorizationError,
   ErrorCode,
+  hostnameFromSocketAddress,
   LookupOptions,
   makeHostnameLookupFunction,
   ServiceAssertionError,
@@ -140,7 +141,8 @@ export class RemoteJWKSCollector implements KeyCollector {
    */
   resolveAgent(): http.Agent | https.Agent {
     const lookupOptions = this.options?.lookupOptions ?? { reject_ip_ranges: [] };
-    const lookup = makeHostnameLookupFunction(this.url.hostname, lookupOptions);
+    const hostname = hostnameFromSocketAddress(this.url.hostname);
+    const lookup = makeHostnameLookupFunction(hostname, lookupOptions);
 
     const options: http.AgentOptions = {
       lookup

package/src/entry/commands/teardown-action.ts

@@ -13,7 +13,7 @@ export function registerTearDownAction(program: Command) {
 
   return teardownCommand
     .argument('[ack]', 'Type `TEARDOWN` to confirm teardown should occur')
-    .description('Terminate all replicating sync rules, clear remote configuration and remove all data')
+    .description('Terminate all replicating replication streams, clear remote configuration and remove all data')
     .action(async (ack, options) => {
       if (ack !== 'TEARDOWN') {
         throw new ServiceError(ErrorCode.PSYNC_S0102, 'TEARDOWN was not acknowledged.');

package/src/index.ts

@@ -42,4 +42,6 @@ export * as utils from './util/util-index.js';
 export * from './streams/streams-index.js';
 export * as streams from './streams/streams-index.js';
 
+export * from './tracing/PerformanceTracer.js';
+
 export * as bson from 'bson';

package/src/modules/AbstractModule.ts

@@ -5,7 +5,7 @@ import { ServiceContextContainer } from '../system/ServiceContext.js';
 
 export interface TearDownOptions {
   /**
-   *  If required, tear down any configuration/state for the specific sync rules
+   *  If required, tear down any configuration/state for the specific replication stream
    */
   syncRules?: PersistedSyncRulesContent[];
 }

package/src/replication/AbstractReplicationJob.ts

@@ -54,7 +54,7 @@ export abstract class AbstractReplicationJob {
    *  Safely stop the replication process
    */
   public async stop(): Promise<void> {
-    this.logger.info(`Stopping replication job for sync rule iteration: ${this.storage.group_id}`);
+    this.logger.info(`Stopping replication job`);
     this.abortController.abort();
     await this.isReplicatingPromise;
   }

package/src/replication/AbstractReplicator.ts

@@ -32,19 +32,19 @@ export interface AbstractReplicatorOptions {
 /**
  *   A replicator manages the mechanics for replicating data from a data source to a storage bucket.
  *   This includes copying across the original data set and then keeping it in sync with the data source using Replication Jobs.
- *   It also handles any changes to the sync rules.
+ *   It also handles any changes to the sync config.
  */
 export abstract class AbstractReplicator<T extends AbstractReplicationJob = AbstractReplicationJob> {
   protected logger: winston.Logger;
   private lockAlerted: boolean = false;
   /**
-   *  Map of replication jobs by sync rule id. Usually there is only one running job, but there could be two when
-   *  transitioning to a new set of sync rules.
+   *  Map of replication jobs by replication stream id. Usually there is only one running job, but there could be two when
+   *  transitioning to a new replication stream.
    */
   private replicationJobs = new Map<number, T>();
 
   /**
-   * Map of sync rule ids to promises that are clearing the sync rule configuration.
+   * Map of replciation stream ids to promises that are clearing the replication stream.
    *
    * We primarily do this to keep track of what we're currently clearing, but don't currently
    * use the Promise value.
@@ -68,8 +68,8 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
   abstract createJob(options: CreateJobOptions): T;
 
   /**
-   *  Clean up any configuration or state for the specified sync rule on the datasource.
-   *  Should be a no-op if the configuration has already been cleared
+   * Clean up any configuration or state for the specified replication stream on the datasource.
+   * Should be a no-op if the replication stream has already been cleared
    */
   abstract cleanUp(syncRuleStorage: storage.SyncRulesBucketStorage): Promise<void>;
 
@@ -100,7 +100,7 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
   public async start(): Promise<void> {
     this.abortController = new AbortController();
     this.runLoop().catch((e) => {
-      this.logger.error('Data source fatal replication error', e);
+      this.logger.error('Fatal replication error', e);
       container.reporter.captureException(e);
       setTimeout(() => {
         process.exit(1);
@@ -135,9 +135,9 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
 
     let configuredLock: storage.ReplicationLock | undefined = undefined;
     if (syncRules != null) {
-      this.logger.info('Loaded sync rules');
+      this.logger.info('Loaded sync config');
       try {
-        // Configure new sync rules, if they have changed.
+        // Configure new sync config, if they have changed.
         // In that case, also immediately take out a lock, so that another process doesn't start replication on it.
 
         const { lock } = await this.storage.configureSyncRules(
@@ -149,11 +149,11 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
       } catch (e) {
         // Log and re-raise to exit.
         // Should only reach this due to validation errors if exit_on_error is true.
-        this.logger.error(`Failed to update sync rules from configuration`, e);
+        this.logger.error(`Failed to update sync config`, e);
         throw e;
       }
     } else {
-      this.logger.info('No sync rules configured - configure via API');
+      this.logger.info('No sync streams or rules configured - configure via API');
     }
     while (!this.stopped) {
       await container.probes.touch();
@@ -206,7 +206,7 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         // Remove from the list. Next refresh call will restart the job.
         existingJobs.delete(syncRules.id);
       } else {
-        // New sync rules were found (or resume after restart)
+        // New sync config was found (or resume after restart)
         try {
           let lock: storage.ReplicationLock;
           if (configuredLock?.sync_rules_id == syncRules.id) {
@@ -229,15 +229,15 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         } catch (e) {
           if (e?.errorData?.code === ErrorCode.PSYNC_S1003) {
             if (!this.lockAlerted) {
-              this.logger.info(`[${e.errorData.code}] ${e.errorData.description}`);
+              syncRules.logger.info(`[${e.errorData.code}] ${e.errorData.description}`);
               this.lockAlerted = true;
             }
           } else {
-            // Could be a sync rules parse error,
+            // Could be a sync config parse error,
             // for example from stricter validation that was added.
             // This will be retried every couple of seconds.
-            // When new (valid) sync rules are deployed and processed, this one be disabled.
-            this.logger.error('Failed to start replication for new sync rules', e);
+            // When new (valid) sync config is deployed and processed, this one be disabled.
+            syncRules.logger.error('Failed to start replication for new sync config', e);
           }
         }
       }
@@ -246,7 +246,7 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
     this.replicationJobs = newJobs;
     this.activeReplicationJob = activeJob;
 
-    // Stop any orphaned jobs that no longer have sync rules.
+    // Stop any orphaned jobs that no longer have a replication stream.
     // Termination happens below
     for (let job of existingJobs.values()) {
       // Old - stop and clean up
@@ -254,11 +254,11 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         await job.stop();
       } catch (e) {
         // This will be retried
-        this.logger.warn('Failed to stop old replication job}', e);
+        job.storage.logger.warn('Failed to stop old replication job', e);
       }
     }
 
-    // Sync rules stopped previously, including by a different process.
+    // Replication stream stopped previously, including by a different process.
     const stopped = await this.storage.getStoppedSyncRules();
     for (let syncRules of stopped) {
       if (this.clearingJobs.has(syncRules.id)) {
@@ -268,11 +268,11 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
 
       // We clear storage asynchronously.
       // It is important to be able to continue running the refresh loop, otherwise we cannot
-      // retry locked sync rules, for example.
+      // retry locked replication stream, for example.
       const syncRuleStorage = this.storage.getInstance(syncRules, { skipLifecycleHooks: true });
       const promise = this.terminateSyncRules(syncRuleStorage)
         .catch((e) => {
-          this.logger.warn(`Failed clean up replication config for sync rule: ${syncRules.id}`, e);
+          syncRuleStorage.logger.warn(`Failed clean up replication config`, e);
         })
         .finally(() => {
           this.clearingJobs.delete(syncRules.id);
@@ -286,12 +286,12 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
   }
 
   protected async terminateSyncRules(syncRuleStorage: storage.SyncRulesBucketStorage) {
-    this.logger.info(`Terminating sync rules: ${syncRuleStorage.group_id}...`);
+    syncRuleStorage.logger.info(`Terminating replication stream...`);
     // This deletes postgres replication slots - should complete quickly.
     // It is safe to do before or after clearing the data in the storage.
     await this.cleanUp(syncRuleStorage);
     await syncRuleStorage.terminate({ signal: this.abortController?.signal, clearStorage: true });
-    this.logger.info(`Successfully terminated sync rules: ${syncRuleStorage.group_id}`);
+    syncRuleStorage.logger.info(`Successfully terminated replication stream`);
   }
 
   abstract testConnection(): Promise<ConnectionTestResult>;

package/src/replication/RelationCache.ts

@@ -1,24 +1,43 @@
 import { SourceTable } from '../storage/SourceTable.js';
 
 export class RelationCache<T> {
-  private cache = new Map<string | number, SourceTable>();
+  private cache = new Map<string | number, SourceTable[]>();
   private idFunction: (item: T | SourceTable) => string | number;
 
   constructor(idFunction: (item: T | SourceTable) => string | number) {
     this.idFunction = idFunction;
   }
 
+  /**
+   * Update a single table in-place - use when the snapshot status of the table has changed.
+   */
   update(table: SourceTable) {
     const id = this.idFunction(table);
-    this.cache.set(id, table);
+    const existing = this.cache.get(id) ?? [];
+    const replacementIndex = existing.findIndex((candidate) => candidate.id == table.id);
+    if (replacementIndex == -1) {
+      this.cache.set(id, [...existing, table]);
+    } else {
+      const next = [...existing];
+      next[replacementIndex] = table;
+      this.cache.set(id, next);
+    }
   }
 
-  get(source: T | SourceTable): SourceTable | undefined {
+  /**
+   * Set the full set of tables for a specific reference.
+   */
+  updateAll(ref: T, tables: SourceTable[]) {
+    const id = this.idFunction(ref);
+    this.cache.set(id, tables);
+  }
+
+  getAll(source: T | SourceTable): SourceTable[] | undefined {
     const id = this.idFunction(source);
     return this.cache.get(id);
   }
 
-  delete(source: T | SourceTable): boolean {
+  delete(source: T): boolean {
     const id = this.idFunction(source);
     return this.cache.delete(id);
   }

package/src/routes/configure-fastify.ts

@@ -1,6 +1,10 @@
 import type fastify from 'fastify';
 
-import { registerFastifyNotFoundHandler, registerFastifyRoutes } from './route-register.js';
+import {
+  registerFastifyErrorHandler,
+  registerFastifyNotFoundHandler,
+  registerFastifyRoutes
+} from './route-register.js';
 
 import * as system from '../system/system-index.js';
 
@@ -66,6 +70,9 @@ export function configureFastifyServer(server: fastify.FastifyInstance, options:
     };
   };
 
+  // Set on the outer server so both child scopes inherit.
+  registerFastifyErrorHandler(server);
+
   /**
    * Fastify creates an encapsulated context for each `.register` call.
    * Creating a separate context here to separate the concurrency limits for Admin APIs

package/src/routes/endpoints/admin.ts

@@ -1,5 +1,7 @@
+import * as sqlite from 'node:sqlite';
+
 import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
-import { SourceSchema, SqlSyncRules, StaticSchema } from '@powersync/service-sync-rules';
+import { nodeSqlite, SourceSchema, SqlSyncRules, StaticSchema } from '@powersync/service-sync-rules';
 import { internal_routes } from '@powersync/service-types';
 
 import { DEFAULT_HYDRATION_STATE } from '@powersync/service-sync-rules';
@@ -119,7 +121,7 @@ export const reprocess = routeDefinition({
     const apiHandler = service_context.routerEngine.getAPI();
     const next = await activeBucketStorage.getNextSyncRules(apiHandler.getParseSyncRulesOptions());
     if (next != null) {
-      throw new Error(`Busy processing sync rules - cannot reprocess`);
+      throw new Error(`Busy processing sync config - cannot reprocess`);
     }
 
     const active = await activeBucketStorage.getActiveSyncRules(apiHandler.getParseSyncRulesOptions());
@@ -127,13 +129,17 @@ export const reprocess = routeDefinition({
       throw new errors.ServiceError({
         status: 422,
         code: ErrorCode.PSYNC_S4104,
-        description: 'No active sync rules'
+        description: 'No active sync config'
       });
     }
 
+    // There are some differences between this and using asUpdateOptions():
+    // 1. This always re-parses the source YAML. If there are changes to the sync stream compiler, that can affect the sync plan.
+    // 2. If the source does not set the storage version, this will update it do the current version.
+    // We can consider tweaking this behavior in the future.
     const new_rules = await activeBucketStorage.updateSyncRules(
-      storage.updateSyncRulesFromYaml(active.sync_rules.config.content, {
-        // These sync rules already passed validation. But if the rules are not valid anymore due
+      storage.updateSyncRulesFromYaml(active.syncConfigWithErrors.config.content, {
+        // This sync config already passed validation. But if the config is not valid anymore due
         // to a service change, we do want to report the error here.
         validate: true
       })
@@ -172,13 +178,16 @@ class FakeSyncRulesContentForValidation extends storage.PersistedSyncRulesConten
   parsed(options: storage.ParseSyncRulesOptions): storage.PersistedSyncRules {
     return {
       ...this,
-      sync_rules: SqlSyncRules.fromYaml(this.sync_rules_content, {
+      syncConfigWithErrors: SqlSyncRules.fromYaml(this.sync_rules_content, {
         ...this.apiHandler.getParseSyncRulesOptions(),
         schema: this.schema
       }),
       hydrationState: DEFAULT_HYDRATION_STATE,
-      hydratedSyncRules() {
-        return this.sync_rules.config.hydrate({ hydrationState: DEFAULT_HYDRATION_STATE });
+      hydratedSyncConfig() {
+        return this.syncConfigWithErrors.config.hydrate({
+          hydrationState: DEFAULT_HYDRATION_STATE,
+          sqlite: nodeSqlite(sqlite)
+        });
       }
     };
   }

package/src/routes/endpoints/checkpointing.ts

@@ -33,7 +33,7 @@ export const writeCheckpoint = routeDefinition({
       const bucketStorage = await service_context.storageEngine.activeBucketStorage.getActiveStorage();
       const cp = await bucketStorage?.getCheckpoint();
       if (cp == null) {
-        throw new Error('No sync rules available');
+        throw new Error('No sync config available');
       }
       if (cp.lsn && cp.lsn >= head) {
         logger.info(`Got write checkpoint: ${head} : ${cp.checkpoint}`);

package/src/routes/endpoints/socket-route.ts

@@ -77,7 +77,7 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
           new errors.ServiceError({
             status: 500,
             code: ErrorCode.PSYNC_S2302,
-            description: 'No sync rules available'
+            description: 'No sync config available'
           })
         );
         responder.onComplete();

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

@@ -43,12 +43,12 @@ export const deploySyncRules = routeDefinition({
     const { storageEngine } = service_context;
 
     if (service_context.configuration.sync_rules.present) {
-      // If sync rules are configured via the config, disable deploy via the API.
+      // If sync config is configured via the service config, disable deploy via the API.
       throw new errors.ServiceError({
         status: 422,
         code: ErrorCode.PSYNC_S4105,
-        description: 'Sync rules API disabled',
-        details: 'Use the management API to deploy sync rules'
+        description: 'Sync config API disabled',
+        details: 'Update sync config in the service configuration'
       });
     }
     const content = payload.params.content;
@@ -65,7 +65,7 @@ export const deploySyncRules = routeDefinition({
       throw new errors.ServiceError({
         status: 422,
         code: ErrorCode.PSYNC_R0001,
-        description: 'Sync rules parsing failed',
+        description: 'Sync config parsing failed',
         details: e.message
       });
     }
@@ -115,7 +115,7 @@ export const currentSyncRules = routeDefinition({
       throw new errors.ServiceError({
         status: 422,
         code: ErrorCode.PSYNC_S4104,
-        description: 'No active sync rules'
+        description: 'No active sync config'
       });
     }
 
@@ -162,13 +162,13 @@ export const reprocessSyncRules = routeDefinition({
       throw new errors.ServiceError({
         status: 422,
         code: ErrorCode.PSYNC_S4104,
-        description: 'No active sync rules'
+        description: 'No active sync config'
       });
     }
 
     const new_rules = await activeBucketStorage.updateSyncRules(
-      updateSyncRulesFromYaml(sync_rules.sync_rules.config.content, {
-        // These sync rules already passed validation. But if the rules are not valid anymore due
+      updateSyncRulesFromYaml(sync_rules.syncConfigWithErrors.config.content, {
+        // This sync config already passed validation. But if the rules are not valid anymore due
         // to a service change, we do want to report the error here.
         validate: true
       })

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

@@ -68,7 +68,7 @@ export const syncStreamed = routeDefinition({
       throw new errors.ServiceError({
         status: 500,
         code: ErrorCode.PSYNC_S2302,
-        description: 'No sync rules available'
+        description: 'No sync config available'
       });
     }
 
@@ -121,7 +121,7 @@ export const syncStreamed = routeDefinition({
       });
 
       stream.on('end', () => {
-        // Auth failure or switch to new sync rules
+        // Auth failure or switch to new sync config
         closeReason ??= 'service closing stream';
       });