@powersync/service-core 1.27.1 → 1.28.0

package/dist/system/SyncConfigEngine.js

@@ -0,0 +1,186 @@
+import { ErrorCode, logger, ServiceError } from '@powersync/lib-services-framework';
+import { parseSyncConfig, SyncConfigErrors } from '@powersync/service-sync-rules';
+import { updateSyncRulesFromConfig } from '../storage/BucketStorageFactory.js';
+import { ConfigurationFileSyncRulesProvider } from '../util/config/sync-rules/sync-rules-provider.js';
+import { syncConfigYamlErrorToReplicationError } from '../util/errors.js';
+/**
+ * Outcome of loading or validating sync config, independent of persisted replication state.
+ */
+export var SyncConfigResultStatus;
+(function (SyncConfigResultStatus) {
+    /**
+     * No sync config is supplied through service configuration; use API-managed deployments.
+     */
+    SyncConfigResultStatus["ABSENT"] = "absent";
+    /**
+     * Configured input could not be loaded. This is distinct from invalid YAML and API-managed mode.
+     */
+    SyncConfigResultStatus["UNAVAILABLE"] = "unavailable";
+    /**
+     * Parsing and source-capability checks passed without fatal diagnostics; warnings may remain.
+     */
+    SyncConfigResultStatus["ACCEPTED"] = "accepted";
+    /**
+     * Parsing, compilation, or source-capability checks failed; the input cannot be deployed.
+     */
+    SyncConfigResultStatus["REJECTED"] = "rejected";
+})(SyncConfigResultStatus || (SyncConfigResultStatus = {}));
+/**
+ * Validation stage responsible for rejecting a sync config.
+ */
+export var SyncConfigRejectionReason;
+(function (SyncConfigRejectionReason) {
+    /**
+     * YAML parsing, query validation, or compilation failed.
+     */
+    SyncConfigRejectionReason["PARSE"] = "parse";
+    /**
+     * The source adapter rejected required execution capabilities or its capability check failed.
+     */
+    SyncConfigRejectionReason["CAPABILITY"] = "capability";
+})(SyncConfigRejectionReason || (SyncConfigRejectionReason = {}));
+/**
+ * Owns admission of configured and submitted YAML. "Configured" means supplied through service
+ * configuration from a filesystem path, Base64 input, or inline YAML, excluding deployment API submissions.
+ * Each process caches its configured result;
+ * replication jobs retain their storage-owned parsed configs and hydration identity.
+ */
+export class SyncConfigEngine {
+    settings;
+    getRouteAPI;
+    configured;
+    /**
+     * @param settings Input source and startup policy from service configuration. Raw YAML is loaded
+     * on the first call to `getConfigured()`.
+     * @param getRouteAPI Resolves the registered source adapter only when YAML validation is needed.
+     * Adapter shutdown remains owned by the router lifecycle.
+     */
+    constructor(settings, getRouteAPI) {
+        this.settings = settings;
+        this.getRouteAPI = getRouteAPI;
+    }
+    /**
+     * Evaluate YAML supplied through service configuration (filesystem, Base64, or inline content),
+     * excluding deployment API submissions. Concurrent consumers share the same promise
+     * and result until restart. Reads configured input once on first use, then retains the loaded,
+     * parsed, or unavailable result without rereading files or mutating storage.
+     * Input load failures return `UNAVAILABLE`; absent configured input selects API-managed mode.
+     */
+    getConfigured() {
+        return (this.configured ??= this.evaluateConfigured());
+    }
+    async evaluateConfigured() {
+        if (!this.settings.present) {
+            return { status: SyncConfigResultStatus.ABSENT };
+        }
+        let content;
+        try {
+            content = await new ConfigurationFileSyncRulesProvider(this.settings).get();
+            if (content == null) {
+                throw new Error('Sync config is configured but no content or file path is available');
+            }
+        }
+        catch (error) {
+            logger.warn('Unable to read local sync config', error);
+            return { status: SyncConfigResultStatus.UNAVAILABLE, error };
+        }
+        return this.validate(content);
+    }
+    /**
+     * Parse supplied YAML, validate source capabilities even when the returned parse has fatal diagnostics,
+     * and prepare accepted input for storage. A parser exception with no config skips capability checks.
+     * Does not replace the configured snapshot or mutate storage. Validation failures become rejected
+     * results; source lookup or failures obtaining adapter parse options reject the promise.
+     */
+    async validate(content) {
+        const routeAPI = this.getRouteAPI();
+        const parseOptions = routeAPI.getParseSyncRulesOptions();
+        const now = new Date().toISOString();
+        const diagnostics = [];
+        let parsed;
+        try {
+            parsed = parseSyncConfig(content, { ...parseOptions, schema: undefined, throwOnError: false });
+            diagnostics.push(...parsed.errors.map((error) => syncConfigYamlErrorToReplicationError(error, now)));
+            const hasFatalParseErrors = diagnostics.some((error) => error.level === 'fatal');
+            try {
+                diagnostics.push(...((await routeAPI.validateSourceCapabilities?.(parsed.config)) ?? []).map((diagnostic) => ({
+                    ...diagnostic,
+                    ts: diagnostic.ts ?? now
+                })));
+            }
+            catch (error) {
+                diagnostics.push(...validationFailureDiagnostics(error, now));
+            }
+            if (diagnostics.some((error) => error.level === 'fatal')) {
+                return {
+                    status: SyncConfigResultStatus.REJECTED,
+                    reason: hasFatalParseErrors ? SyncConfigRejectionReason.PARSE : SyncConfigRejectionReason.CAPABILITY,
+                    content,
+                    parsed,
+                    diagnostics
+                };
+            }
+            return {
+                status: SyncConfigResultStatus.ACCEPTED,
+                content,
+                compiled: updateSyncRulesFromConfig(parsed).config,
+                diagnostics
+            };
+        }
+        catch (error) {
+            diagnostics.push(...validationFailureDiagnostics(error, now));
+            return {
+                status: SyncConfigResultStatus.REJECTED,
+                reason: SyncConfigRejectionReason.PARSE,
+                content,
+                parsed,
+                diagnostics
+            };
+        }
+    }
+}
+function validationFailureDiagnostics(error, ts) {
+    return error instanceof SyncConfigErrors
+        ? error.errors.map((error) => syncConfigYamlErrorToReplicationError(error, ts))
+        : [{ level: 'fatal', message: error instanceof Error ? error.message : String(error), ts }];
+}
+/**
+ * Return deployable input from an accepted result.
+ * @throws A 422 `PSYNC_R0001` service error containing fatal diagnostics when the input was rejected.
+ */
+export function assertAcceptedSyncConfig(result) {
+    if (result.status === SyncConfigResultStatus.ACCEPTED) {
+        return result.compiled;
+    }
+    throw new ServiceError({
+        status: 422,
+        code: ErrorCode.PSYNC_R0001,
+        description: result.reason === SyncConfigRejectionReason.PARSE
+            ? 'Sync config parsing failed'
+            : 'Source capability validation failed',
+        details: result.diagnostics
+            .filter((error) => error.level === 'fatal')
+            .map((error) => error.message)
+            .join('\n')
+    });
+}
+/**
+ * Check local admission before manual reprocessing; callers separately check stored processing work.
+ * Both manual reprocess endpoints use this guard; automatic recovery does not.
+ * @throws A 409 `PSYNC_S4106` service error for rejected input, or the original input load failure.
+ */
+export async function assertConfiguredSyncConfigValid(engine) {
+    const result = await engine.getConfigured();
+    if (result.status === SyncConfigResultStatus.REJECTED) {
+        throw new ServiceError({
+            status: 409,
+            code: ErrorCode.PSYNC_S4106,
+            description: 'Cannot reprocess while the configured sync config is invalid',
+            details: 'Correct the sync config and restart the affected service processes'
+        });
+    }
+    if (result.status === SyncConfigResultStatus.UNAVAILABLE) {
+        throw result.error;
+    }
+}
+//# sourceMappingURL=SyncConfigEngine.js.map

package/dist/system/SyncConfigEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncConfigEngine.js","sourceRoot":"","sources":["../../src/system/SyncConfigEngine.ts"],"names":[],"mappings":"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"}

package/dist/system/system-index.d.ts

@@ -1 +1,2 @@
 export * from './ServiceContext.js';
+export * from './SyncConfigEngine.js';

package/dist/system/system-index.js

@@ -1,2 +1,3 @@
 export * from './ServiceContext.js';
+export * from './SyncConfigEngine.js';
 //# sourceMappingURL=system-index.js.map

package/dist/system/system-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-index.js","sourceRoot":"","sources":["../../src/system/system-index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"system-index.js","sourceRoot":"","sources":["../../src/system/system-index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/util/config/types.d.ts

@@ -15,6 +15,10 @@ export type MigrationContext = {
     runner_config: RunnerConfig;
 };
 export type Runner = (config: RunnerConfig) => Promise<void>;
+/**
+ * Sync config supplied through service configuration: a filesystem path, Base64 input, or inline YAML.
+ * This excludes configs submitted through the deployment API; `present: false` selects API-managed mode.
+ */
 export type SyncRulesConfig = {
     present: boolean;
     version_label?: string;

package/package.json

@@ -4,8 +4,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.27.1",
-  "license": "FSL-1.1-ALv2",
+  "version": "1.28.0",
+  "license": "Apache-2.0",
   "type": "module",
   "exports": "./dist/index.js",
   "dependencies": {
@@ -22,7 +22,6 @@
     "commander": "^12.0.0",
     "cors": "^2.8.5",
     "ipaddr.js": "^2.1.0",
-    "ix": "^5.0.0",
     "jose": "^4.15.1",
     "lodash": "^4.18.1",
     "lru-cache": "^10.2.2",
@@ -33,17 +32,17 @@
     "uuid": "^14.0.0",
     "winston": "^3.13.0",
     "yaml": "^2.8.3",
-    "@powersync/service-rsocket-router": "0.2.29",
-    "@powersync/service-jsonbig": "0.17.13",
-    "@powersync/service-types": "0.20.0",
-    "@powersync/service-sync-rules": "0.44.0",
-    "@powersync/lib-services-framework": "0.10.4"
+    "@powersync/lib-services-framework": "0.10.5",
+    "@powersync/service-jsonbig": "0.17.14",
+    "@powersync/service-rsocket-router": "0.3.0",
+    "@powersync/service-sync-rules": "0.45.0",
+    "@powersync/service-types": "0.21.0"
   },
   "devDependencies": {
     "@types/async": "^3.2.24",
     "@types/lodash": "^4.17.5",
     "@types/negotiator": "^0.6.4",
-    "fastify": "^5.12.5",
+    "fastify": "^5.12.7",
     "fastify-plugin": "^5.0.1"
   },
   "scripts": {

package/src/api/RouteAPI.ts

@@ -44,6 +44,12 @@ export interface RouteAPI {
   /**
    * Checks whether the source supports the capabilities required by this sync config.
    * Must not modify the source. Return advisory warnings and fatal validation diagnostics.
+   * May receive a partial config with fatal parser diagnostics; report capability issues independently.
+   * SyncConfigEngine currently caches admission results for the configured snapshot until restart,
+   * including fatal diagnostics created from unexpected validation exceptions. Temporary failures
+   * can therefore leave diagnostics reporting a stale rejection. Retrying failed validation attempts
+   * from diagnostics without reloading the configured YAML is a future improvement.
+   * Check configured executor capabilities here; live connectivity and table metadata checks are separate.
    * An empty array means no issues; throw only for unexpected failures.
    */
   validateSourceCapabilities?(syncConfig: SyncConfig): Promise<types.ValidationDiagnostic[]>;

package/src/api/api-metrics.ts

@@ -27,6 +27,11 @@ export function createCoreAPIMetrics(engine: MetricsEngine): void {
     name: APIMetric.CONCURRENT_CONNECTIONS,
     description: 'Number of concurrent sync connections'
   });
+
+  engine.createCounter({
+    name: APIMetric.SYNC_CONNECTIONS,
+    description: 'Sync stream closes and setup rejections, by outcome, close_reason, error_code and transport'
+  });
 }
 
 /**

package/src/api/diagnostics.ts

@@ -1,8 +1,9 @@
 import { logger, ServiceAssertionError } from '@powersync/lib-services-framework';
-import { DEFAULT_TAG, SourceTableRef, SyncConfigWithErrors, SyncRulesErrors } from '@powersync/service-sync-rules';
+import { DEFAULT_TAG, SourceTableRef, SyncConfigErrors, SyncConfigWithErrors } from '@powersync/service-sync-rules';
 import { ReplicationError, SyncRulesStatus, TableInfo } from '@powersync/service-types';
 
 import * as storage from '../storage/storage-index.js';
+import { ConfiguredSyncConfigResult, SyncConfigResultStatus } from '../system/SyncConfigEngine.js';
 import { syncConfigYamlErrorToReplicationError } from '../util/errors.js';
 import { RouteAPI, SlotWalBudgetInfo } from './RouteAPI.js';
 
@@ -32,6 +33,25 @@ export interface DiagnosticsOptions {
 
 export const DEFAULT_DATASOURCE_ID = 'default';
 
+/**
+ * Project the cached local admission result without creating a persisted deployment.
+ */
+export function getInvalidLocalSyncConfigStatus(
+  result: ConfiguredSyncConfigResult,
+  includeContent: boolean,
+  versionLabel?: string
+): SyncRulesStatus | undefined {
+  if (result.status !== SyncConfigResultStatus.REJECTED) {
+    return undefined;
+  }
+  return {
+    version_label: versionLabel,
+    content: includeContent ? result.content : undefined,
+    connections: [],
+    errors: result.diagnostics
+  };
+}
+
 export async function getSyncRulesStatus(
   apiHandler: RouteAPI,
   syncConfig: storage.PersistedSyncConfigContent | null,
@@ -70,7 +90,7 @@ export async function getSyncRulesStatus(
       connections: [],
       // Report each sync config error separately, retaining its source location.
       errors:
-        e instanceof SyncRulesErrors
+        e instanceof SyncConfigErrors
           ? e.errors.map((error) => syncConfigYamlErrorToReplicationError(error, now))
           : [{ level: 'fatal', message: e.message, ts: now }]
     };

package/src/metrics/connection-metrics.ts

@@ -0,0 +1,75 @@
+import { ErrorCode, errors } from '@powersync/lib-services-framework';
+import { APIMetric } from '@powersync/service-types';
+import type { MetricsEngine } from './MetricsEngine.js';
+import type { MetricAttributes } from './metrics-interfaces.js';
+
+export enum SyncCloseReason {
+  /** Routine client disconnect/reconnect. */
+  ClientClosed = 'client_closed',
+  /** Server-side close: auth expiry or switch to a new sync config. */
+  ServiceClosed = 'service_closed',
+  ProcessShutdown = 'process_shutdown',
+  StreamError = 'stream_error',
+  ServiceUnavailable = 'service_unavailable',
+  NoSyncConfig = 'no_sync_config',
+  StorageError = 'storage_error',
+  SyncConfigError = 'sync_config_error',
+  ConcurrencyLimit = 'concurrency_limit',
+  Unknown = 'unknown'
+}
+
+export enum SyncTransport {
+  HttpStream = 'http_stream',
+  RSocket = 'rsocket'
+}
+
+type SyncConnectionReasonPolicy = Readonly<{
+  outcome: 'ok' | 'error' | 'rejected';
+  logText: string;
+}>;
+
+const SYNC_CONNECTION_REASON_POLICY = {
+  [SyncCloseReason.ClientClosed]: { outcome: 'ok', logText: 'client closing stream' },
+  [SyncCloseReason.ServiceClosed]: { outcome: 'ok', logText: 'service closing stream' },
+  [SyncCloseReason.ProcessShutdown]: { outcome: 'ok', logText: 'process shutdown' },
+  [SyncCloseReason.StreamError]: { outcome: 'error', logText: 'stream error' },
+  [SyncCloseReason.ServiceUnavailable]: { outcome: 'rejected', logText: 'service unavailable' },
+  [SyncCloseReason.NoSyncConfig]: { outcome: 'rejected', logText: 'no sync config' },
+  [SyncCloseReason.StorageError]: { outcome: 'rejected', logText: 'storage error' },
+  [SyncCloseReason.SyncConfigError]: { outcome: 'rejected', logText: 'sync config error' },
+  [SyncCloseReason.ConcurrencyLimit]: { outcome: 'rejected', logText: 'concurrency limit' },
+  // Nothing was thrown or reported, so the stream ended cleanly without a specific reason.
+  [SyncCloseReason.Unknown]: { outcome: 'ok', logText: 'unknown' }
+} as const satisfies Readonly<Record<SyncCloseReason, SyncConnectionReasonPolicy>>;
+
+/** Wording used by existing log-based dashboards for the `close_reason` field. */
+export function syncConnectionCloseReasonLogText(closeReason?: SyncCloseReason): string {
+  return SYNC_CONNECTION_REASON_POLICY[closeReason ?? SyncCloseReason.Unknown].logText;
+}
+
+export interface SyncConnectionMetric {
+  transport: SyncTransport;
+  closeReason: SyncCloseReason;
+  /** The original failure, before any transport-specific wrapping. */
+  error?: unknown;
+}
+
+const ERROR_CODES: ReadonlySet<string> = new Set(Object.values(ErrorCode));
+
+export function recordSyncConnection(engine: MetricsEngine, metric: SyncConnectionMetric): void {
+  const { outcome } = SYNC_CONNECTION_REASON_POLICY[metric.closeReason];
+
+  const attributes: MetricAttributes = {
+    outcome,
+    close_reason: metric.closeReason,
+    transport: metric.transport
+  };
+
+  if (outcome !== 'ok') {
+    const code = errors.ServiceError.isServiceError(metric.error) ? metric.error.errorData?.code : undefined;
+    const errorCode = typeof code == 'string' && ERROR_CODES.has(code) ? code : 'other';
+    attributes.error_code = errorCode;
+  }
+
+  engine.getCounter(APIMetric.SYNC_CONNECTIONS).add(1, attributes);
+}

package/src/metrics/metrics-index.ts

@@ -1,3 +1,4 @@
+export * from './connection-metrics.js';
 export * from './metrics-interfaces.js';
 export * from './MetricsEngine.js';
 export * from './open-telemetry/OpenTelemetryMetricsFactory.js';

package/src/metrics/metrics-interfaces.ts

@@ -1,9 +1,16 @@
+/**
+ *  Bounded-cardinality attributes (labels) attached to a metric data point.
+ *  Only use low-cardinality enum-like values here — never user/client/request identifiers.
+ */
+export type MetricAttributes = Record<string, string | number | boolean>;
+
 export interface Counter {
   /**
    *  Increment the counter by the given value. Only positive numbers are valid.
    *  @param value
+   *  @param attributes optional low-cardinality labels for this increment
    */
-  add(value: number): void;
+  add(value: number, attributes?: MetricAttributes): void;
 }
 
 export interface UpDownCounter {

package/src/modules/loader.ts

@@ -1,3 +1,4 @@
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import { ResolvedPowerSyncConfig } from '../util/util-index.js';
 import { AbstractModule } from './AbstractModule.js';
 
@@ -9,6 +10,11 @@ export interface ModuleLoaders {
   storage: DynamicModuleMap;
   connection: DynamicModuleMap;
 }
+
+function quoteList(values: string[]): string {
+  return values.map((value) => `"${value}"`).join(', ');
+}
+
 /**
  * Utility function to dynamically load and instantiate modules.
  */
@@ -30,13 +36,21 @@ export async function loadModules(config: ResolvedPowerSyncConfig, loaders: Modu
 
   // Fail if any connection types are not found.
   if (missingConnectionModules.length > 0) {
-    throw new Error(`Invalid connection types: "${[...missingConnectionModules].join(', ')}"`);
+    const validConnections = Object.keys(loaders.connection);
+    throw new ServiceError(
+      ErrorCode.PSYNC_S3201,
+      `Invalid connection types: ${quoteList(missingConnectionModules)}${validConnections.length > 0 ? `. Supported types: ${quoteList(validConnections)}.` : ''}`
+    );
   }
 
   if (loaders.storage[config.storage.type] !== undefined) {
     modulePromises.push(loaders.storage[config.storage.type]());
   } else {
-    throw new Error(`Invalid storage type: "${config.storage.type}"`);
+    const validStorage = Object.keys(loaders.storage);
+    throw new ServiceError(
+      ErrorCode.PSYNC_S3201,
+      `Invalid storage type: "${config.storage.type}"${validStorage.length > 0 ? `. Supported types: ${quoteList(validStorage)}.` : ''}`
+    );
   }
 
   // 2. Dynamically import and instantiate module classes and resolve all promises

package/src/replication/AbstractReplicationJob.ts

@@ -1,4 +1,4 @@
-import { container, logger } from '@powersync/lib-services-framework';
+import { container, logger, ReplicationAbortedError } from '@powersync/lib-services-framework';
 import winston from 'winston';
 import { MetricsEngine } from '../metrics/MetricsEngine.js';
 import type { CreateJobOptions } from './AbstractReplicator.js';
@@ -73,6 +73,22 @@ export abstract class AbstractReplicationJob {
     return this.options.rateLimiter;
   }
 
+  /** Log expected restarts without reporting them as replication failures. */
+  protected shouldReportReplicationError(error: unknown): boolean {
+    if (this.isStopped) {
+      return false;
+    }
+    if (error instanceof ReplicationAbortedError) {
+      if (error.cause != null) {
+        this.logger.warn('Replication aborted', error);
+      } else {
+        this.logger.info('Replication aborted', error);
+      }
+      return false;
+    }
+    return true;
+  }
+
   public get isStopped(): boolean {
     return this.abortController.signal.aborted;
   }