@powersync/service-core 0.0.0-dev-20260313100403 → 0.0.0-dev-20260515144844

package/src/api/RouteAPI.ts

@@ -14,6 +14,16 @@ export interface ReplicationLagOptions {
   bucketStorage: SyncRulesBucketStorage;
 }
 
+export interface SlotWalBudgetInfo {
+  wal_status: string;
+  safe_wal_size?: number;
+  max_slot_wal_keep_size?: number;
+}
+
+export interface SlotWalBudgetOptions {
+  slotName: string;
+}
+
 /**
  *  Describes all the methods currently required to service the sync API endpoints.
  */
@@ -33,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
@@ -49,6 +59,13 @@ export interface RouteAPI {
    */
   getReplicationLagBytes(options: ReplicationLagOptions): Promise<number | undefined>;
 
+  /**
+   * @returns WAL budget information for the replication slot, or undefined
+   *          if the slot doesn't exist or the source doesn't support this.
+   *          Only implemented by the Postgres adapter.
+   */
+  getSlotWalBudget?(options: SlotWalBudgetOptions): Promise<SlotWalBudgetInfo | undefined>;
+
   /**
    * Get the current LSN or equivalent replication HEAD position identifier.
    *
@@ -59,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[]>;
 
@@ -75,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/api-index.ts

@@ -1,4 +1,4 @@
+export * from './api-metrics.js';
 export * from './diagnostics.js';
 export * from './RouteAPI.js';
 export * from './schema.js';
-export * from './api-metrics.js';

package/src/api/api-metrics.ts

@@ -1,5 +1,5 @@
-import { MetricsEngine } from '../metrics/MetricsEngine.js';
 import { APIMetric } from '@powersync/service-types';
+import { MetricsEngine } from '../metrics/MetricsEngine.js';
 
 /**
  *  Create and register the core API metrics.

package/src/api/diagnostics.ts

@@ -1,13 +1,14 @@
 import { logger } from '@powersync/lib-services-framework';
-import { DEFAULT_TAG, SourceTableInterface, SqlSyncRules, SyncConfigWithErrors } from '@powersync/service-sync-rules';
+import { DEFAULT_TAG, SourceTableInterface, SyncConfigWithErrors } from '@powersync/service-sync-rules';
 import { ReplicationError, SyncRulesStatus, TableInfo } from '@powersync/service-types';
 
 import * as storage from '../storage/storage-index.js';
-import { RouteAPI } from './RouteAPI.js';
+import { syncConfigYamlErrorToReplicationError } from '../util/errors.js';
+import { RouteAPI, SlotWalBudgetInfo } from './RouteAPI.js';
 
 export interface DiagnosticsOptions {
   /**
-   * Include sync rules content in response.
+   * Include sync config content in response.
    */
   include_content?: boolean;
 
@@ -62,6 +63,7 @@ export async function getSyncRulesStatus(
   const systemStorage = live_status ? bucketStorage.getInstance(sync_rules) : undefined;
   const status = await systemStorage?.getStatus();
   let replication_lag_bytes: number | undefined = undefined;
+  let slot_wal_budget: SlotWalBudgetInfo | undefined = undefined;
 
   let tables_flat: TableInfo[] = [];
 
@@ -87,6 +89,16 @@ export async function getSyncRulesStatus(
         // Ignore
         logger.warn(`Unable to get replication lag`, e);
       }
+
+      if (apiHandler.getSlotWalBudget && sync_rules.slot_name) {
+        try {
+          slot_wal_budget = await apiHandler.getSlotWalBudget({
+            slotName: sync_rules.slot_name
+          });
+        } catch (e) {
+          logger.warn(`Unable to get WAL budget`, e);
+        }
+      }
     }
   } else {
     const source_table_patterns = rules.getSourceTables();
@@ -131,26 +143,33 @@ export async function getSyncRulesStatus(
       ts: sync_rules.last_fatal_error_ts?.toISOString()
     });
   }
-  errors.push(
-    ...syncRuleErrors.map(({ type, message, location }) => {
-      const error: ReplicationError = {
-        level: type,
-        message,
+  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 (location != null) {
-        error.location = {
-          start_offset: location.start,
-          end_offset: location.end
-        };
-      }
-
-      return error;
-    })
-  );
+      });
+    }
+  }
 
   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({
@@ -197,6 +216,9 @@ export async function getSyncRulesStatus(
         last_checkpoint_ts: sync_rules.last_checkpoint_ts?.toISOString(),
         last_keepalive_ts: sync_rules.last_keepalive_ts?.toISOString(),
         replication_lag_bytes: replication_lag_bytes,
+        wal_status: slot_wal_budget?.wal_status,
+        safe_wal_size: slot_wal_budget?.safe_wal_size,
+        max_slot_wal_keep_size: slot_wal_budget?.max_slot_wal_keep_size,
         tables: tables_flat
       }
     ],

package/src/auth/CachedKeyCollector.ts

@@ -1,9 +1,8 @@
-import * as jose from 'jose';
+import { AuthorizationError, ErrorCode, logger } from '@powersync/lib-services-framework';
 import timers from 'timers/promises';
+import { KeyCollector, KeyResult } from './KeyCollector.js';
 import { KeySpec } from './KeySpec.js';
 import { LeakyBucket } from './LeakyBucket.js';
-import { KeyCollector, KeyResult } from './KeyCollector.js';
-import { AuthorizationError, ErrorCode, logger } from '@powersync/lib-services-framework';
 import { mapAuthConfigError } from './utils.js';
 
 /**

package/src/auth/CompoundKeyCollector.ts

@@ -1,7 +1,6 @@
-import * as jose from 'jose';
-import { KeySpec } from './KeySpec.js';
-import { KeyCollector, KeyResult } from './KeyCollector.js';
 import { AuthorizationError } from '@powersync/lib-services-framework';
+import { KeyCollector, KeyResult } from './KeyCollector.js';
+import { KeySpec } from './KeySpec.js';
 
 export class CompoundKeyCollector implements KeyCollector {
   private collectors: KeyCollector[];

package/src/auth/KeyStore.ts

@@ -4,7 +4,7 @@ import secs from '../util/secs.js';
 import { JwtPayload } from './JwtPayload.js';
 import { KeyCollector } from './KeyCollector.js';
 import { KeyOptions, KeySpec, SUPPORTED_ALGORITHMS } from './KeySpec.js';
-import { debugKeyNotFound, mapAuthError, SupabaseAuthDetails, tokenDebugDetails } from './utils.js';
+import { debugKeyNotFound, mapAuthError, SupabaseAuthDetails } from './utils.js';
 
 /**
  * KeyStore to get keys and verify tokens.

package/src/auth/RemoteJWKSCollector.ts

@@ -1,6 +1,5 @@
 import * as http from 'http';
 import * as https from 'https';
-import * as jose from 'jose';
 import fetch from 'node-fetch';
 
 import {

package/src/auth/StaticKeyCollector.ts

@@ -1,6 +1,6 @@
 import * as jose from 'jose';
-import { KeySpec } from './KeySpec.js';
 import { KeyCollector, KeyResult } from './KeyCollector.js';
+import { KeySpec } from './KeySpec.js';
 
 /**
  * Set of static keys.

package/src/auth/StaticSupabaseKeyCollector.ts

@@ -1,6 +1,6 @@
 import * as jose from 'jose';
-import { KeySpec, KeyOptions } from './KeySpec.js';
 import { KeyCollector, KeyResult } from './KeyCollector.js';
+import { KeyOptions, KeySpec } from './KeySpec.js';
 
 export const SUPABASE_KEY_OPTIONS: KeyOptions = {
   requiresAudience: ['authenticated'],

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

@@ -25,7 +25,9 @@ const COMPACT_MEMORY_LIMIT_MB = Math.min(HEAP_LIMIT / 1024 / 1024 - 128, 1024);
 export function registerCompactAction(program: Command) {
   const compactCommand = program
     .command(COMMAND_NAME)
-    .option(`-b, --buckets [buckets]`, 'Full bucket names, comma-separated (e.g., "global[],mybucket[\\"user1\\"]")');
+    .option(`-b, --buckets [buckets]`, 'Full bucket names, comma-separated (e.g., "global[],mybucket[\\"user1\\"]")')
+    .option('-p, --parameter-indexes', 'Compacting parameter indexes. Defaults to set unless --buckets is provided.')
+    .option('--no-parameter-indexes', 'Disabling compacting parameter indexes.');
 
   wrapConfigCommand(compactCommand);
 
@@ -44,16 +46,31 @@ export function registerCompactAction(program: Command) {
         process.exit(1);
       }
     }
+
+    let compactParameters: boolean | null = options.parameterIndexes;
+
     if (buckets == null) {
       logger.info('Compacting storage for all buckets...');
+    } else if (buckets.length == 0) {
+      logger.info('Skipping bucket compaction');
     } else {
       logger.info(`Compacting storage for ${buckets?.join(', ')}...`);
     }
+
     const config = await utils.loadConfig(extractRunnerOptions(options));
     const serviceContext = new system.ServiceContextContainer({
       serviceMode: system.ServiceContextMode.COMPACT,
       configuration: config
     });
+    const abortController = new AbortController();
+    const completion = Promise.withResolvers<void>();
+
+    serviceContext.lifeCycleEngine.withLifecycle(null, {
+      stop: async () => {
+        abortController.abort();
+        await completion.promise;
+      }
+    });
 
     // Register modules in order to allow custom module compacting
     const moduleManager = container.getImplementation(modules.ModuleManager);
@@ -71,22 +88,29 @@ export function registerCompactAction(program: Command) {
         logger.info('No active instance to compact');
         return;
       }
-      logger.info('Performing compaction...');
       if (buckets != null) {
+        logger.info('Performing compaction...');
         await active.compact({
           memoryLimitMB: COMPACT_MEMORY_LIMIT_MB,
           compactBuckets: buckets,
-          compactParameterData: false
+          compactParameterData: compactParameters ?? false,
+          signal: abortController.signal
         });
       } else {
-        await active.compact({ memoryLimitMB: COMPACT_MEMORY_LIMIT_MB, compactParameterData: true });
+        await active.compact({
+          memoryLimitMB: COMPACT_MEMORY_LIMIT_MB,
+          compactParameterData: compactParameters ?? true,
+          signal: abortController.signal
+        });
       }
       logger.info('Successfully compacted storage.');
     } catch (e) {
-      logger.error(`Failed to compact: ${e.toString()}`);
+      logger.error(`Failed to compact:`, e);
       // Indirectly triggers lifeCycleEngine.stop
       process.exit(1);
     } finally {
+      // No need to propagate errors on completion - this merely signals that the process can exit.
+      completion.resolve();
       // Indirectly triggers lifeCycleEngine.stop
       process.exit(0);
     }

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

@@ -1,8 +1,8 @@
 import { Command } from 'commander';
 
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import { teardown } from '../../runner/teardown.js';
 import { extractRunnerOptions, wrapConfigCommand } from './config-command.js';
-import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 
 const COMMAND_NAME = 'teardown';
 
@@ -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/entry/entry-index.ts

@@ -1,6 +1,6 @@
 export * from './cli-entry.js';
+export * from './commands/compact-action.js';
 export * from './commands/config-command.js';
 export * from './commands/migrate-action.js';
 export * from './commands/start-action.js';
 export * from './commands/teardown-action.js';
-export * from './commands/compact-action.js';

package/src/events/EventsEngine.ts

@@ -1,6 +1,6 @@
-import EventEmitter from 'node:events';
 import { logger } from '@powersync/lib-services-framework';
 import { event_types } from '@powersync/service-types';
+import EventEmitter from 'node:events';
 
 export class EventsEngine {
   private emitter: EventEmitter;

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/metrics/MetricsEngine.ts

@@ -1,5 +1,5 @@
 import { logger, ServiceAssertionError } from '@powersync/lib-services-framework';
-import { Counter, UpDownCounter, ObservableGauge, MetricMetadata, MetricsFactory } from './metrics-interfaces.js';
+import { Counter, MetricMetadata, MetricsFactory, ObservableGauge, UpDownCounter } from './metrics-interfaces.js';
 
 export interface MetricsEngineOptions {
   factory: MetricsFactory;

package/src/metrics/RollingBucketMax.ts

@@ -0,0 +1,109 @@
+export interface RollingBucketMaxOptions {
+  bucketSizeMs?: number;
+  windowSizeMs?: number;
+}
+
+interface Bucket {
+  // Absolute bucket id derived from floor(timestamp / bucketSizeMs).
+  id: number;
+  // Maximum reported value seen within this bucket.
+  max: number | undefined;
+}
+
+/**
+ * Tracks a rolling max over a fixed number of time buckets.
+ *
+ * The window is bucket-aligned: with the default 30s window and 5s buckets,
+ * the rolling max covers the current 5s bucket plus the previous 5 buckets.
+ */
+export class RollingBucketMax {
+  private readonly bucketSizeMs: number;
+  private readonly bucketCount: number;
+  // Fixed-size ring buffer keyed by bucket id modulo bucketCount.
+  private readonly buckets: Bucket[];
+
+  constructor(options: RollingBucketMaxOptions = {}) {
+    this.bucketSizeMs = options.bucketSizeMs ?? 5_000;
+    const windowSizeMs = options.windowSizeMs ?? 30_000;
+
+    if (!Number.isInteger(this.bucketSizeMs) || this.bucketSizeMs <= 0) {
+      throw new Error('bucketSizeMs must be a positive integer.');
+    }
+
+    if (!Number.isInteger(windowSizeMs) || windowSizeMs <= 0) {
+      throw new Error('windowSizeMs must be a positive integer.');
+    }
+
+    if (windowSizeMs % this.bucketSizeMs !== 0) {
+      throw new Error('windowSizeMs must be an exact multiple of bucketSizeMs.');
+    }
+
+    this.bucketCount = windowSizeMs / this.bucketSizeMs;
+    this.buckets = Array.from({ length: this.bucketCount }, () => ({
+      id: Number.NaN,
+      max: undefined
+    }));
+  }
+
+  /**
+   * Reports a new observed value into the bucket for the provided timestamp.
+   */
+  report(value: number | undefined, timestampMs = Date.now()): void {
+    if (value == null) {
+      return;
+    }
+    this.assertFiniteNumber(value, 'value');
+    this.assertFiniteNumber(timestampMs, 'timestampMs');
+
+    const bucket = this.getBucket(this.getBucketId(timestampMs));
+    bucket.max = bucket.max === undefined ? value : Math.max(bucket.max, value);
+  }
+
+  /**
+   * Returns the maximum value across the current bucket and prior buckets still
+   * inside the rolling window, or undefined when the window has no samples.
+   */
+  getRollingMax(timestampMs = Date.now()): number | undefined {
+    this.assertFiniteNumber(timestampMs, 'timestampMs');
+
+    const currentBucketId = this.getBucketId(timestampMs);
+    const minimumBucketId = currentBucketId - this.bucketCount + 1;
+
+    let rollingMax: number | undefined;
+    for (const bucket of this.buckets) {
+      if (bucket.max === undefined) {
+        continue;
+      }
+
+      if (bucket.id < minimumBucketId || bucket.id > currentBucketId) {
+        continue;
+      }
+
+      rollingMax = rollingMax === undefined ? bucket.max : Math.max(rollingMax, bucket.max);
+    }
+
+    return rollingMax;
+  }
+
+  private getBucketId(timestampMs: number): number {
+    return Math.floor(timestampMs / this.bucketSizeMs);
+  }
+
+  private getBucket(bucketId: number): Bucket {
+    const index = ((bucketId % this.bucketCount) + this.bucketCount) % this.bucketCount;
+    const bucket = this.buckets[index];
+
+    if (bucket.id !== bucketId) {
+      bucket.id = bucketId;
+      bucket.max = undefined;
+    }
+
+    return bucket;
+  }
+
+  private assertFiniteNumber(value: number, name: string): void {
+    if (!Number.isFinite(value)) {
+      throw new Error(`${name} must be a finite number.`);
+    }
+  }
+}

package/src/metrics/metrics-index.ts

@@ -1,5 +1,6 @@
-export * from './MetricsEngine.js';
 export * from './metrics-interfaces.js';
-export * from './register-metrics.js';
+export * from './MetricsEngine.js';
 export * from './open-telemetry/OpenTelemetryMetricsFactory.js';
 export * from './open-telemetry/util.js';
+export * from './register-metrics.js';
+export * from './RollingBucketMax.js';

package/src/metrics/open-telemetry/util.ts

@@ -6,8 +6,8 @@ import { ServiceContext } from '../../system/ServiceContext.js';
 import { MetricsFactory } from '../metrics-interfaces.js';
 import { OpenTelemetryMetricsFactory } from './OpenTelemetryMetricsFactory.js';
 
-import pkg from '../../../package.json' with { type: 'json' };
 import { resourceFromAttributes } from '@opentelemetry/resources';
+import pkg from '../../../package.json' with { type: 'json' };
 
 export function createOpenTelemetryMetricsFactory(context: ServiceContext): MetricsFactory {
   const { configuration, lifeCycleEngine, storageEngine } = context;

package/src/metrics/register-metrics.ts

@@ -1,9 +1,9 @@
-import { ServiceContextContainer } from '../system/ServiceContext.js';
-import { createOpenTelemetryMetricsFactory } from './open-telemetry/util.js';
-import { MetricsEngine } from './MetricsEngine.js';
 import { createCoreAPIMetrics, initializeCoreAPIMetrics } from '../api/api-metrics.js';
 import { createCoreReplicationMetrics, initializeCoreReplicationMetrics } from '../replication/replication-metrics.js';
 import { createCoreStorageMetrics, initializeCoreStorageMetrics } from '../storage/storage-metrics.js';
+import { ServiceContextContainer } from '../system/ServiceContext.js';
+import { MetricsEngine } from './MetricsEngine.js';
+import { createOpenTelemetryMetricsFactory } from './open-telemetry/util.js';
 
 export enum MetricModes {
   API = 'api',

package/src/modules/AbstractModule.ts

@@ -1,11 +1,11 @@
-import { ServiceContextContainer } from '../system/ServiceContext.js';
 import { logger } from '@powersync/lib-services-framework';
 import winston from 'winston';
 import { PersistedSyncRulesContent } from '../storage/storage-index.js';
+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/modules/modules-index.ts

@@ -1,3 +1,3 @@
-export * from './ModuleManager.js';
 export * from './AbstractModule.js';
 export * from './loader.js';
+export * from './ModuleManager.js';

package/src/replication/AbstractReplicationJob.ts

@@ -1,8 +1,8 @@
 import { container, logger } from '@powersync/lib-services-framework';
 import winston from 'winston';
+import { MetricsEngine } from '../metrics/MetricsEngine.js';
 import * as storage from '../storage/storage-index.js';
 import { ErrorRateLimiter } from './ErrorRateLimiter.js';
-import { MetricsEngine } from '../metrics/MetricsEngine.js';
 
 export interface AbstractReplicationJobOptions {
   id: string;
@@ -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;
   }
@@ -82,5 +82,5 @@ export abstract class AbstractReplicationJob {
   /**
    * Get replication lag for this job in ms.
    */
-  abstract getReplicationLagMillis(): Promise<number | undefined>;
+  abstract getReplicationLagMillis(): number | undefined;
 }