@powersync/service-core 0.0.0-dev-20250618131818 → 0.0.0-dev-20250714115156

package/package.json

@@ -5,7 +5,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.0-dev-20250618131818",
+  "version": "0.0.0-dev-20250714115156",
   "main": "dist/index.js",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -32,11 +32,11 @@
     "uuid": "^11.1.0",
     "winston": "^3.13.0",
     "yaml": "^2.3.2",
-    "@powersync/lib-services-framework": "0.0.0-dev-20250618131818",
+    "@powersync/lib-services-framework": "0.7.0",
     "@powersync/service-jsonbig": "0.17.10",
-    "@powersync/service-rsocket-router": "0.0.0-dev-20250618131818",
+    "@powersync/service-rsocket-router": "0.1.1",
     "@powersync/service-sync-rules": "0.27.0",
-    "@powersync/service-types": "0.0.0-dev-20250618131818"
+    "@powersync/service-types": "0.0.0-dev-20250714115156"
   },
   "devDependencies": {
     "@types/async": "^3.2.24",

package/src/auth/CachedKeyCollector.ts

@@ -3,7 +3,7 @@ import timers from 'timers/promises';
 import { KeySpec } from './KeySpec.js';
 import { LeakyBucket } from './LeakyBucket.js';
 import { KeyCollector, KeyResult } from './KeyCollector.js';
-import { AuthorizationError } from '@powersync/lib-services-framework';
+import { AuthorizationError, ErrorCode, logger } from '@powersync/lib-services-framework';
 import { mapAuthConfigError } from './utils.js';
 
 /**
@@ -70,8 +70,21 @@ export class CachedKeyCollector implements KeyCollector {
       // e.g. in the case of waiting for error retries.
       // In the case of very slow requests, we don't wait for it to complete, but the
       // request can still complete in the background.
-      const timeout = timers.setTimeout(3000);
-      await Promise.race([this.refreshPromise, timeout]);
+      const WAIT_TIMEOUT_SECONDS = 3;
+      const timeout = timers.setTimeout(WAIT_TIMEOUT_SECONDS * 1000).then(() => {
+        throw new AuthorizationError(ErrorCode.PSYNC_S2204, `JWKS request failed`, {
+          cause: { message: `Key request timed out in ${WAIT_TIMEOUT_SECONDS}s`, name: 'AbortError' }
+        });
+      });
+      try {
+        await Promise.race([this.refreshPromise, timeout]);
+      } catch (e) {
+        if (e instanceof AuthorizationError) {
+          return { keys: this.currentKeys, errors: [...this.currentErrors, e] };
+        } else {
+          throw e;
+        }
+      }
     }
 
     return { keys: this.currentKeys, errors: this.currentErrors };
@@ -102,7 +115,16 @@ export class CachedKeyCollector implements KeyCollector {
       this.currentErrors = errors;
       this.keyTimestamp = Date.now();
       this.error = false;
+
+      // Due to caching and background refresh behavior, errors are not always propagated to the request handler,
+      // so we log them here.
+      for (let error of errors) {
+        logger.error(`Soft key refresh error`, error);
+      }
     } catch (e) {
+      // Due to caching and background refresh behavior, errors are not always propagated to the request handler,
+      // so we log them here.
+      logger.error(`Hard key refresh error`, e);
       this.error = true;
       // No result - keep previous keys
       this.currentErrors = [mapAuthConfigError(e)];

package/src/auth/KeySpec.ts

@@ -40,6 +40,20 @@ export class KeySpec {
     return this.source.kid;
   }
 
+  get description(): string {
+    let details: string[] = [];
+    details.push(`kid: ${this.kid ?? '*'}`);
+    details.push(`kty: ${this.source.kty}`);
+    if (this.source.alg != null) {
+      details.push(`alg: ${this.source.alg}`);
+    }
+    if (this.options.requiresAudience != null) {
+      details.push(`aud: ${this.options.requiresAudience.join(', ')}`);
+    }
+
+    return `<${details.filter((x) => x != null).join(', ')}>`;
+  }
+
   matchesAlgorithm(jwtAlg: string): boolean {
     if (this.source.alg) {
       return jwtAlg === this.source.alg;

package/src/auth/KeyStore.ts

@@ -1,4 +1,4 @@
-import { logger, errors, AuthorizationError, ErrorCode } from '@powersync/lib-services-framework';
+import { AuthorizationError, ErrorCode, logger } from '@powersync/lib-services-framework';
 import * as jose from 'jose';
 import secs from '../util/secs.js';
 import { JwtPayload } from './JwtPayload.js';
@@ -169,7 +169,7 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
         ErrorCode.PSYNC_S2101,
         'Could not find an appropriate key in the keystore. The key is missing or no key matched the token KID',
         {
-          configurationDetails: `Known kid values: ${keys.map((key) => key.kid ?? '*').join(', ')}`
+          configurationDetails: `Known keys: ${keys.map((key) => key.description).join(', ')}`
           // tokenDetails automatically populated later
         }
       );

package/src/auth/RemoteJWKSCollector.ts

@@ -49,9 +49,10 @@ export class RemoteJWKSCollector implements KeyCollector {
 
   private async getJwksData(): Promise<any> {
     const abortController = new AbortController();
+    const REQUEST_TIMEOUT_SECONDS = 30;
     const timeout = setTimeout(() => {
       abortController.abort();
-    }, 30_000);
+    }, REQUEST_TIMEOUT_SECONDS * 1000);
 
     try {
       const res = await fetch(this.url, {
@@ -71,11 +72,14 @@ export class RemoteJWKSCollector implements KeyCollector {
 
       return (await res.json()) as any;
     } catch (e) {
+      if (e instanceof Error && e.name === 'AbortError') {
+        e = { message: `Request timed out in ${REQUEST_TIMEOUT_SECONDS}s`, name: 'AbortError' };
+      }
       throw new AuthorizationError(ErrorCode.PSYNC_S2204, `JWKS request failed`, {
         configurationDetails: `JWKS URL: ${this.url}`,
         // This covers most cases of FetchError
         // `cause: e` could lose the error message
-        cause: { message: e.message, code: e.code }
+        cause: { message: e.message, code: e.code, name: e.name }
       });
     } finally {
       clearTimeout(timeout);

package/src/emitters/AbstractEmitterEngine.ts

@@ -0,0 +1,64 @@
+import { EmitterEvent, EmitterEventData, EventNames, isEventError } from './emitter-interfaces.js';
+import * as storage from '../storage/storage-index.js';
+import EventEmitter from 'node:events';
+import { logger } from '@powersync/lib-services-framework';
+import { EventError } from './event-error.js';
+
+export abstract class AbstractEmitterEngine {
+  private emitter: EventEmitter;
+  storageEngine: storage.StorageEngine;
+  eventsMap: Map<EventNames, EmitterEvent> = new Map();
+
+  protected constructor(storage: storage.StorageEngine) {
+    this.emitter = new EventEmitter({ captureRejections: true });
+    this.storageEngine = storage;
+    this.emitter.on('error', (error: Error | EventError) => {
+      if (isEventError(error) && this.eventsMap.has(error.eventName)) {
+        const event = this.eventsMap.get(error.eventName)!;
+        const errorHandler =
+          event.errorhandler ??
+          ((error) => {
+            logger.error(error.message);
+          });
+        errorHandler(error);
+      }
+    });
+  }
+
+  get events(): EventNames[] {
+    return this.emitter.eventNames() as EventNames[];
+  }
+
+  protected bindEvents(events: EmitterEvent[]): void {
+    const eventNames = this.emitter.eventNames();
+    for (const event of events) {
+      if (!eventNames.includes(event.name)) {
+        this.eventsMap.set(event.name, event);
+        this.emitter.on(event.name, event.handler(this.storageEngine).bind(event));
+      } else {
+        logger.warn(`Event ${event.name} is already registered. Skipping.`);
+      }
+    }
+  }
+
+  protected emit(eventName: EventNames, data: EmitterEventData): void {
+    if (!this.emitter.eventNames().includes(eventName)) {
+      throw new Error(`Event ${eventName} is not registered.`);
+    }
+    this.emitter.emit(eventName, data);
+  }
+
+  protected removeListeners(eventName?: EventNames): void {
+    if (eventName) {
+      this.emitter.removeAllListeners(eventName);
+      logger.info(`Removed all listeners for event: ${eventName}`);
+    } else {
+      this.stop();
+    }
+  }
+
+  protected stop(): void {
+    this.emitter.removeAllListeners();
+    logger.info('Emitter engine shut down and all listeners removed.');
+  }
+}

package/src/emitters/EmitterEngine.ts

@@ -0,0 +1,41 @@
+import { BaseEmitterEngine, EmitterEvent, EmitterEventData, EventNames } from './emitter-interfaces.js';
+import * as storage from '../storage/storage-index.js';
+import { AbstractEmitterEngine } from './AbstractEmitterEngine.js';
+import { logger } from '@powersync/lib-services-framework';
+
+export class EmitterEngine extends AbstractEmitterEngine implements BaseEmitterEngine {
+  private active: boolean;
+  constructor(events: EmitterEvent[], storageRef: storage.StorageEngine) {
+    super(storageRef);
+    this.active = process.env.MICRO_SERVICE_NAME === 'powersync';
+    logger.info(`EmitterEngine initialized with active status: ${this.active}`);
+    this.bindEvents(events);
+  }
+
+  event(eventName: EventNames): EmitterEvent {
+    const event = this.eventsMap.get(eventName);
+    if (!event) {
+      throw new Error(`Event ${eventName} is not registered.`);
+    }
+    return event;
+  }
+
+  removeListeners(eventName?: EventNames): void {
+    if (eventName) {
+      this.removeListeners(eventName);
+    }
+  }
+  eventNames(): EventNames[] {
+    return this.events;
+  }
+
+  emitEvent(eventName: EventNames, data: EmitterEventData): void {
+    if (this.active) {
+      return this.emit(eventName, data);
+    }
+  }
+
+  async shutDown(): Promise<void> {
+    this.stop();
+  }
+}

package/src/emitters/emitter-interfaces.ts

@@ -0,0 +1,47 @@
+import { JwtPayload } from '../auth/JwtPayload.js';
+import * as storage from '../storage/storage-index.js';
+import { EventError } from './event-error.js';
+
+export enum EventNames {
+  // SdK events
+  SDK_CONNECT_EVENT = 'sdk-connect-event',
+  SDK_DISCONNECT_EVENT = 'sdk-disconnect-event'
+}
+
+export type SdkEvent = {
+  client_id?: string;
+  user_id: string;
+  user_agent: string;
+  jwt_token?: JwtPayload;
+};
+
+export type EventConnectData = {
+  type: EventNames.SDK_CONNECT_EVENT;
+  connect_at: number;
+} & SdkEvent;
+
+export type EventDisconnectData = {
+  type: EventNames.SDK_DISCONNECT_EVENT;
+  disconnect_at: number;
+} & SdkEvent;
+
+export type EmitterEventData = EventConnectData | EventDisconnectData;
+export type EventHandler = (data: EmitterEventData) => Promise<void>;
+export type StorageHandler = (storageEngine: storage.StorageEngine) => EventHandler;
+export interface EmitterEvent {
+  name: EventNames;
+  handler: StorageHandler;
+  errorhandler?: (error: Error | EventError) => void;
+}
+
+export interface BaseEmitterEngine {
+  eventNames(): EventNames[];
+  emitEvent(eventName: EventNames, data: EmitterEventData): void;
+  removeListeners(eventName?: EventNames): void;
+  event(eventName: EventNames): EmitterEvent;
+  shutDown(): Promise<void>;
+}
+
+export function isEventError(error: Error | EventError): error is EventError {
+  return (error as EventError).eventName !== undefined;
+}

package/src/emitters/event-error.ts

@@ -0,0 +1,10 @@
+import { EventNames } from './emitter-interfaces.js';
+
+export class EventError extends Error {
+  constructor(
+    public eventName: EventNames,
+    message: string
+  ) {
+    super(message);
+  }
+}

package/src/emitters/events/connect-event.ts

@@ -0,0 +1,34 @@
+import { EmitterEvent, EmitterEventData, EventConnectData, EventHandler, EventNames } from '../emitter-interfaces.js';
+import * as storage from '../../storage/storage-index.js';
+import { EventError } from '../event-error.js';
+import { logger } from '@powersync/lib-services-framework';
+
+export class ConnectEvent implements EmitterEvent {
+  private type = EventNames.SDK_CONNECT_EVENT;
+  get name(): EventNames {
+    return this.type;
+  }
+  errorhandler(error: Error | EventError): void {
+    if (error instanceof EventError) {
+      logger.error(`EventError in ${error.eventName}:`, error.message);
+    } else {
+      logger.error(error.message);
+    }
+  }
+  handler(storageEngine: storage.StorageEngine): EventHandler {
+    // TODO: USE STORAGE ENGINE
+    const storage = storageEngine.activeStorage.storage;
+    return async (data: EmitterEventData) => {
+      try {
+        const disconnectData = data as EventConnectData;
+        console.log(
+          `Connect event triggered for user: ${disconnectData.user_id} at ${new Date(disconnectData.connect_at).toISOString()}`
+        );
+      } catch (error) {
+        throw new EventError(this.type, error.message);
+      }
+    };
+  }
+}
+
+export const connectEvent = new ConnectEvent();

package/src/emitters/events/disconnect-event.ts

@@ -0,0 +1,36 @@
+import {
+  EmitterEvent,
+  EmitterEventData,
+  EventDisconnectData,
+  EventHandler,
+  EventNames
+} from '../emitter-interfaces.js';
+import * as storage from '../../storage/storage-index.js';
+import { EventError } from '../event-error.js';
+import { logger } from '@powersync/lib-services-framework';
+
+export class DisconnectEvent implements EmitterEvent {
+  private type = EventNames.SDK_DISCONNECT_EVENT;
+  get name(): EventNames {
+    return this.type;
+  }
+  errorhandler(error: Error | EventError): void {
+    if (error instanceof EventError) {
+      logger.error(`EventError in ${error.eventName}:`, error.message);
+    } else {
+      logger.error(error.message);
+    }
+  }
+  handler(storageEngine: storage.StorageEngine): EventHandler {
+    // TODO: USE STORAGE ENGINE
+    const storage = storageEngine.activeStorage.storage;
+    return async (data: EmitterEventData) => {
+      const disconnectData = data as EventDisconnectData;
+      console.log(
+        `Disconnect event triggered for user: ${disconnectData.user_id} at ${new Date(disconnectData.disconnect_at).toISOString()}`
+      );
+    };
+  }
+}
+
+export const disconnectEvent = new DisconnectEvent();

package/src/emitters/events/index.ts

@@ -0,0 +1,4 @@
+import { disconnectEvent } from './disconnect-event.js';
+import { connectEvent } from './connect-event.js';
+
+export const events = [disconnectEvent, connectEvent];

package/src/replication/AbstractReplicator.ts

@@ -1,14 +1,14 @@
 import { container, logger } from '@powersync/lib-services-framework';
+import { ReplicationMetric } from '@powersync/service-types';
 import { hrtime } from 'node:process';
 import winston from 'winston';
+import { MetricsEngine } from '../metrics/MetricsEngine.js';
 import * as storage from '../storage/storage-index.js';
 import { StorageEngine } from '../storage/storage-index.js';
 import { SyncRulesProvider } from '../util/config/sync-rules/sync-rules-provider.js';
 import { AbstractReplicationJob } from './AbstractReplicationJob.js';
 import { ErrorRateLimiter } from './ErrorRateLimiter.js';
 import { ConnectionTestResult } from './ReplicationModule.js';
-import { MetricsEngine } from '../metrics/MetricsEngine.js';
-import { ReplicationMetric } from '@powersync/service-types';
 
 // 5 minutes
 const PING_INTERVAL = 1_000_000_000n * 300n;
@@ -40,9 +40,17 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
   /**
    *  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.
-   *  @private
    */
   private replicationJobs = new Map<number, T>();
+
+  /**
+   * Map of sync rule ids to promises that are clearing the sync rule configuration.
+   *
+   * We primarily do this to keep track of what we're currently clearing, but don't currently
+   * use the Promise value.
+   */
+  private clearingJobs = new Map<number, Promise<void>>();
+
   /**
    * Used for replication lag computation.
    */
@@ -242,16 +250,26 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
       }
     }
 
-    // Sync rules stopped previously or by a different process.
+    // Sync rules stopped previously, including by a different process.
     const stopped = await this.storage.getStoppedSyncRules();
     for (let syncRules of stopped) {
-      try {
-        // TODO: Do this in the "background", allowing the periodic refresh to continue
-        const syncRuleStorage = this.storage.getInstance(syncRules, { skipLifecycleHooks: true });
-        await this.terminateSyncRules(syncRuleStorage);
-      } catch (e) {
-        this.logger.warn(`Failed clean up replication config for sync rule: ${syncRules.id}`, e);
+      if (this.clearingJobs.has(syncRules.id)) {
+        // Already in progress
+        continue;
       }
+
+      // 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.
+      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);
+        })
+        .finally(() => {
+          this.clearingJobs.delete(syncRules.id);
+        });
+      this.clearingJobs.set(syncRules.id, promise);
     }
   }
 
@@ -261,6 +279,8 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
 
   protected async terminateSyncRules(syncRuleStorage: storage.SyncRulesBucketStorage) {
     this.logger.info(`Terminating sync rules: ${syncRuleStorage.group_id}...`);
+    // 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}`);

package/src/routes/auth.ts

@@ -1,10 +1,7 @@
-import * as jose from 'jose';
-
+import { AuthorizationError, AuthorizationResponse, ErrorCode } from '@powersync/lib-services-framework';
 import * as auth from '../auth/auth-index.js';
 import { ServiceContext } from '../system/ServiceContext.js';
-import * as util from '../util/util-index.js';
 import { BasicRouterRequest, Context, RequestEndpointHandlerPayload } from './router.js';
-import { AuthorizationError, AuthorizationResponse, ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 
 export function endpoint(req: BasicRouterRequest) {
   const protocol = req.headers['x-forwarded-proto'] ?? req.protocol;
@@ -12,81 +9,6 @@ export function endpoint(req: BasicRouterRequest) {
   return `${protocol}://${host}`;
 }
 
-function devAudience(req: BasicRouterRequest): string {
-  return `${endpoint(req)}/dev`;
-}
-
-/**
- * @deprecated
- *
- * Will be replaced by temporary tokens issued by PowerSync Management service.
- */
-export async function issueDevToken(req: BasicRouterRequest, user_id: string, config: util.ResolvedPowerSyncConfig) {
-  const iss = devAudience(req);
-  const aud = devAudience(req);
-
-  const key = config.dev.dev_key;
-  if (key == null) {
-    throw new Error('Auth disabled');
-  }
-
-  return await new jose.SignJWT({})
-    .setProtectedHeader({ alg: key.source.alg!, kid: key.kid })
-    .setSubject(user_id)
-    .setIssuedAt()
-    .setIssuer(iss)
-    .setAudience(aud)
-    .setExpirationTime('30d')
-    .sign(key.key);
-}
-
-/** @deprecated */
-export async function issueLegacyDevToken(
-  req: BasicRouterRequest,
-  user_id: string,
-  config: util.ResolvedPowerSyncConfig
-) {
-  const iss = devAudience(req);
-  const aud = config.jwt_audiences[0];
-
-  const key = config.dev.dev_key;
-  if (key == null || aud == null) {
-    throw new Error('Auth disabled');
-  }
-
-  return await new jose.SignJWT({})
-    .setProtectedHeader({ alg: key.source.alg!, kid: key.kid })
-    .setSubject(user_id)
-    .setIssuedAt()
-    .setIssuer(iss)
-    .setAudience(aud)
-    .setExpirationTime('60m')
-    .sign(key.key);
-}
-
-export async function issuePowerSyncToken(
-  req: BasicRouterRequest,
-  user_id: string,
-  config: util.ResolvedPowerSyncConfig
-) {
-  const iss = devAudience(req);
-  const aud = config.jwt_audiences[0];
-  const key = config.dev.dev_key;
-  if (key == null || aud == null) {
-    throw new Error('Auth disabled');
-  }
-
-  const jwt = await new jose.SignJWT({})
-    .setProtectedHeader({ alg: key.source.alg!, kid: key.kid })
-    .setSubject(user_id)
-    .setIssuedAt()
-    .setIssuer(iss)
-    .setAudience(aud)
-    .setExpirationTime('5m')
-    .sign(key.key);
-  return jwt;
-}
-
 export function getTokenFromHeader(authHeader: string = ''): string | null {
   const tokenMatch = /^(Token|Bearer) (\S+)$/.exec(authHeader);
   if (!tokenMatch) {
@@ -146,51 +68,6 @@ export async function generateContext(serviceContext: ServiceContext, token: str
   }
 }
 
-/**
- * @deprecated
- */
-export const authDevUser = async (payload: RequestEndpointHandlerPayload) => {
-  const {
-    context: {
-      service_context: { configuration }
-    }
-  } = payload;
-
-  const token = getTokenFromHeader(payload.request.headers.authorization as string);
-  if (!configuration.dev.demo_auth) {
-    return {
-      authorized: false,
-      errors: ['Authentication disabled']
-    };
-  }
-  if (token == null) {
-    return {
-      authorized: false,
-      errors: ['Authentication required']
-    };
-  }
-
-  // Different from the configured audience.
-  // Should also not be changed by keys
-  const audience = [devAudience(payload.request)];
-
-  let tokenPayload: auth.JwtPayload;
-  try {
-    tokenPayload = await configuration.dev_client_keystore.verifyJwt(token, {
-      defaultAudiences: audience,
-      maxAge: '31d'
-    });
-  } catch (err) {
-    return {
-      authorized: false,
-      errors: [err.message]
-    };
-  }
-
-  payload.context.user_id = tokenPayload.sub;
-  return { authorized: true };
-};
-
 export const authApi = (payload: RequestEndpointHandlerPayload) => {
   const {
     context: {

package/src/routes/configure-rsocket.ts

@@ -38,7 +38,9 @@ export function configureRSocket(router: ReactiveSocketRouter<Context>, options:
         const extracted_token = getTokenFromHeader(token);
         if (extracted_token != null) {
           const { context, tokenError } = await generateContext(options.service_context, extracted_token);
-          if (context?.token_payload == null) {
+          if (tokenError != null) {
+            throw tokenError;
+          } else if (context?.token_payload == null) {
             throw new errors.AuthorizationError(ErrorCode.PSYNC_S2106, 'Authentication required');
           }
 
@@ -46,7 +48,6 @@ export function configureRSocket(router: ReactiveSocketRouter<Context>, options:
             token,
             user_agent,
             ...context,
-            token_error: tokenError,
             service_context: service_context as RouterServiceContext,
             logger: connectionLogger
           };