@powersync/service-core 1.11.3 → 1.12.1

package/src/routes/configure-rsocket.ts

@@ -1,8 +1,9 @@
 import { deserialize } from 'bson';
 import * as http from 'http';
+import * as uuid from 'uuid';
 
-import { errors, logger } from '@powersync/lib-services-framework';
-import { ReactiveSocketRouter, RSocketRequestMeta } from '@powersync/service-rsocket-router';
+import { ErrorCode, errors, logger } from '@powersync/lib-services-framework';
+import { ReactiveSocketRouter, RSocketRequestMeta, TypedBuffer } from '@powersync/service-rsocket-router';
 
 import { ServiceContext } from '../system/ServiceContext.js';
 import { generateContext, getTokenFromHeader } from './auth.js';
@@ -22,44 +23,58 @@ export function configureRSocket(router: ReactiveSocketRouter<Context>, options:
   const { route_generators = DEFAULT_SOCKET_ROUTES, server, service_context } = options;
 
   router.applyWebSocketEndpoints(server, {
-    contextProvider: async (data: Buffer) => {
-      const { token, user_agent } = RSocketContextMeta.decode(deserialize(data) as any);
+    contextProvider: async (data: TypedBuffer): Promise<Context & { token: string }> => {
+      const connectionLogger = logger.child({
+        // timestamp-based uuid - useful for requests
+        rid: `s/${uuid.v7()}`
+      });
+      const { token, user_agent } = RSocketContextMeta.decode(decodeTyped(data) as any);
 
       if (!token) {
-        throw new errors.AuthorizationError('No token provided');
+        throw new errors.AuthorizationError(ErrorCode.PSYNC_S2106, 'No token provided');
       }
 
       try {
         const extracted_token = getTokenFromHeader(token);
         if (extracted_token != null) {
-          const { context, errors: token_errors } = await generateContext(options.service_context, extracted_token);
+          const { context, tokenError } = await generateContext(options.service_context, extracted_token);
           if (context?.token_payload == null) {
-            throw new errors.AuthorizationError(token_errors ?? 'Authentication required');
-          }
-
-          if (!service_context.routerEngine) {
-            throw new Error(`RouterEngine has not been registered`);
+            throw new errors.AuthorizationError(ErrorCode.PSYNC_S2106, 'Authentication required');
           }
 
           return {
             token,
             user_agent,
             ...context,
-            token_errors: token_errors,
-            service_context: service_context as RouterServiceContext
+            token_error: tokenError,
+            service_context: service_context as RouterServiceContext,
+            logger: connectionLogger
           };
         } else {
-          throw new errors.AuthorizationError('No token provided');
+          // Token field is present, but did not contain a token.
+          throw new errors.AuthorizationError(ErrorCode.PSYNC_S2106, 'No valid token provided');
         }
       } catch (ex) {
-        logger.error(ex);
+        connectionLogger.error(ex);
         throw ex;
       }
     },
     endpoints: route_generators.map((generator) => generator(router)),
-    metaDecoder: async (meta: Buffer) => {
-      return RSocketRequestMeta.decode(deserialize(meta) as any);
+    metaDecoder: async (meta: TypedBuffer) => {
+      return RSocketRequestMeta.decode(decodeTyped(meta) as any);
     },
-    payloadDecoder: async (rawData?: Buffer) => rawData && deserialize(rawData)
+    payloadDecoder: async (rawData?: TypedBuffer) => rawData && decodeTyped(rawData)
   });
 }
+
+function decodeTyped(data: TypedBuffer) {
+  switch (data.mimeType) {
+    case 'application/json':
+      const decoder = new TextDecoder();
+      return JSON.parse(decoder.decode(data.contents));
+    case 'application/bson':
+      return deserialize(data.contents);
+  }
+
+  throw new errors.UnsupportedMediaType(`Expected JSON or BSON request, got ${data.mimeType}`);
+}

package/src/routes/endpoints/admin.ts

@@ -19,7 +19,7 @@ export const executeSql = routeDefinition({
       }
     } = payload;
 
-    const apiHandler = payload.context.service_context.routerEngine!.getAPI();
+    const apiHandler = payload.context.service_context.routerEngine.getAPI();
 
     const sourceConfig = await apiHandler.getSourceConfig();
     if (!sourceConfig.debug_api) {
@@ -47,7 +47,7 @@ export const diagnostics = routeDefinition({
     const { service_context } = context;
     const include_content = payload.params.sync_rules_content ?? false;
 
-    const apiHandler = service_context.routerEngine!.getAPI();
+    const apiHandler = service_context.routerEngine.getAPI();
 
     const status = await apiHandler.getConnectionStatus();
     if (!status) {
@@ -94,7 +94,7 @@ export const getSchema = routeDefinition({
   authorize: authApi,
   validator: schema.createTsCodecValidator(internal_routes.GetSchemaRequest, { allowAdditional: true }),
   handler: async (payload) => {
-    const apiHandler = payload.context.service_context.routerEngine!.getAPI();
+    const apiHandler = payload.context.service_context.routerEngine.getAPI();
 
     return internal_routes.GetSchemaResponse.encode(await api.getConnectionsSchema(apiHandler));
   }
@@ -112,7 +112,7 @@ export const reprocess = routeDefinition({
     const {
       storageEngine: { activeBucketStorage }
     } = service_context;
-    const apiHandler = service_context.routerEngine!.getAPI();
+    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`);
@@ -159,7 +159,7 @@ export const validate = routeDefinition({
       context: { service_context }
     } = payload;
     const content = payload.params.sync_rules;
-    const apiHandler = service_context.routerEngine!.getAPI();
+    const apiHandler = service_context.routerEngine.getAPI();
 
     const schemaData = await api.getConnectionsSchema(apiHandler);
     const schema = new StaticSchema(schemaData.connections);

package/src/routes/endpoints/checkpointing.ts

@@ -18,7 +18,7 @@ export const writeCheckpoint = routeDefinition({
     const {
       context: { service_context }
     } = payload;
-    const apiHandler = service_context.routerEngine!.getAPI();
+    const apiHandler = service_context.routerEngine.getAPI();
 
     // This old API needs a persisted checkpoint id.
     // Since we don't use LSNs anymore, the only way to get that is to wait.
@@ -54,7 +54,7 @@ export const writeCheckpoint2 = routeDefinition({
   handler: async (payload) => {
     const { user_id, service_context } = payload.context;
 
-    const apiHandler = service_context.routerEngine!.getAPI();
+    const apiHandler = service_context.routerEngine.getAPI();
 
     const { replicationHead, writeCheckpoint } = await util.createWriteCheckpoint({
       userId: user_id,

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

@@ -1,5 +1,6 @@
 export * from './admin.js';
 export * from './checkpointing.js';
+export * from './probes.js';
 export * from './socket-route.js';
 export * from './sync-rules.js';
 export * from './sync-stream.js';

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

@@ -1,4 +1,4 @@
-import { ErrorCode, errors, logger, schema } from '@powersync/lib-services-framework';
+import { ErrorCode, errors, schema } from '@powersync/lib-services-framework';
 import { RequestParameters } from '@powersync/service-sync-rules';
 import { serialize } from 'bson';
 
@@ -13,12 +13,26 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
   router.reactiveStream<util.StreamingSyncRequest, any>(SyncRoutes.STREAM, {
     validator: schema.createTsCodecValidator(util.StreamingSyncRequest, { allowAdditional: true }),
     handler: async ({ context, params, responder, observer, initialN, signal: upstreamSignal }) => {
-      const { service_context } = context;
+      const { service_context, logger } = context;
       const { routerEngine, metricsEngine, syncContext } = service_context;
 
+      logger.defaultMeta = {
+        ...logger.defaultMeta,
+        user_id: context.token_payload?.sub,
+        client_id: params.client_id,
+        user_agent: context.user_agent
+      };
+      const streamStart = Date.now();
+
+      // 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;
+
       // Create our own controller that we can abort directly
       const controller = new AbortController();
       upstreamSignal.addEventListener('abort', () => {
+        closeReason ??= 'client closing stream';
         controller.abort();
       });
       if (upstreamSignal.aborted) {
@@ -33,7 +47,7 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
         }
       });
 
-      if (routerEngine!.closed) {
+      if (routerEngine.closed) {
         responder.onError(
           new errors.ServiceError({
             status: 503,
@@ -64,9 +78,10 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
         return;
       }
 
-      const syncRules = bucketStorage.getParsedSyncRules(routerEngine!.getAPI().getParseSyncRulesOptions());
+      const syncRules = bucketStorage.getParsedSyncRules(routerEngine.getAPI().getParseSyncRulesOptions());
 
-      const removeStopHandler = routerEngine!.addStopHandler(() => {
+      const removeStopHandler = routerEngine.addStopHandler(() => {
+        closeReason ??= 'process shutdown';
         controller.abort();
       });
 
@@ -88,7 +103,8 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
             keep_alive: false
           },
           tracker,
-          signal
+          signal,
+          logger
         })) {
           if (signal.aborted) {
             break;
@@ -131,22 +147,22 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
             });
           }
         }
+        closeReason ??= 'service closing stream';
       } catch (ex) {
         // Convert to our standard form before responding.
         // This ensures the error can be serialized.
         const error = new errors.InternalServerError(ex);
         logger.error('Sync stream error', error);
+        closeReason ??= 'stream error';
         responder.onError(error);
       } finally {
         responder.onComplete();
         removeStopHandler();
         disposer();
         logger.info(`Sync stream complete`, {
-          user_id: syncParams.user_id,
-          client_id: params.client_id,
-          user_agent: context.user_agent,
-          operations_synced: tracker.operationsSynced,
-          data_synced_bytes: tracker.dataSyncedBytes
+          ...tracker.getLogMeta(),
+          stream_ms: Date.now() - streamStart,
+          close_reason: closeReason ?? 'unknown'
         });
         metricsEngine.getUpDownCounter(APIMetric.CONCURRENT_CONNECTIONS).add(-1);
       }

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

@@ -53,7 +53,7 @@ export const deploySyncRules = routeDefinition({
     const content = payload.params.content;
 
     try {
-      const apiHandler = service_context.routerEngine!.getAPI();
+      const apiHandler = service_context.routerEngine.getAPI();
       SqlSyncRules.fromYaml(payload.params.content, {
         ...apiHandler.getParseSyncRulesOptions(),
         // We don't do any schema-level validation at this point
@@ -94,7 +94,7 @@ export const validateSyncRules = routeDefinition({
   handler: async (payload) => {
     const content = payload.params.content;
     const { service_context } = payload.context;
-    const apiHandler = service_context.routerEngine!.getAPI();
+    const apiHandler = service_context.routerEngine.getAPI();
 
     const info = await debugSyncRules(apiHandler, content);
 
@@ -121,7 +121,7 @@ export const currentSyncRules = routeDefinition({
       });
     }
 
-    const apiHandler = service_context.routerEngine!.getAPI();
+    const apiHandler = service_context.routerEngine.getAPI();
     const info = await debugSyncRules(apiHandler, sync_rules.sync_rules_content);
     const next = await activeBucketStorage.getNextSyncRulesContent();
 
@@ -158,7 +158,7 @@ export const reprocessSyncRules = routeDefinition({
     const {
       storageEngine: { activeBucketStorage }
     } = payload.context.service_context;
-    const apiHandler = payload.context.service_context.routerEngine!.getAPI();
+    const apiHandler = payload.context.service_context.routerEngine.getAPI();
     const sync_rules = await activeBucketStorage.getActiveSyncRules(apiHandler.getParseSyncRulesOptions());
     if (sync_rules == null) {
       throw new errors.ServiceError({
@@ -202,13 +202,13 @@ async function debugSyncRules(apiHandler: RouteAPI, sync_rules: string) {
 
     return {
       valid: true,
-      bucket_definitions: rules.bucket_descriptors.map((d) => {
-        let all_parameter_queries = [...d.parameter_queries.values()].flat();
-        let all_data_queries = [...d.data_queries.values()].flat();
+      bucket_definitions: rules.bucketDescriptors.map((d) => {
+        let all_parameter_queries = [...d.parameterQueries.values()].flat();
+        let all_data_queries = [...d.dataQueries.values()].flat();
         return {
           name: d.name,
-          bucket_parameters: d.bucket_parameters,
-          global_parameter_queries: d.global_parameter_queries.map((q) => {
+          bucket_parameters: d.bucketParameters,
+          global_parameter_queries: d.globalParameterQueries.map((q) => {
             return {
               sql: q.sql
             };
@@ -217,7 +217,7 @@ async function debugSyncRules(apiHandler: RouteAPI, sync_rules: string) {
             return {
               sql: q.sql,
               table: q.sourceTable,
-              input_parameters: q.input_parameters
+              input_parameters: q.inputParameters
             };
           }),
 

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

@@ -20,13 +20,21 @@ 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();
 
-    if (routerEngine!.closed) {
+    logger.defaultMeta = {
+      ...logger.defaultMeta,
+      user_agent: userAgent,
+      client_id: clientId,
+      user_id: payload.context.user_id
+    };
+
+    if (routerEngine.closed) {
       throw new errors.ServiceError({
         status: 503,
         code: ErrorCode.PSYNC_S2003,
@@ -47,7 +55,7 @@ export const syncStreamed = routeDefinition({
       });
     }
 
-    const syncRules = bucketStorage.getParsedSyncRules(routerEngine!.getAPI().getParseSyncRulesOptions());
+    const syncRules = bucketStorage.getParsedSyncRules(routerEngine.getAPI().getParseSyncRulesOptions());
 
     const controller = new AbortController();
     const tracker = new sync.RequestTracker(metricsEngine);
@@ -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 }
       );
 
-      const deregister = routerEngine!.addStopHandler(() => {
+      // 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';
@@ -6,7 +6,8 @@ import { RouterEngine } from './RouterEngine.js';
 /**
  * The {@link RouterEngine} must be provided for these routes
  */
-export type RouterServiceContext = ServiceContext & { routerEngine: RouterEngine };
+export type RouterServiceContext = ServiceContext;
+
 /**
  * Common context for routes
  */
@@ -16,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 = {
@@ -29,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/runner/teardown.ts

@@ -14,7 +14,11 @@ export async function teardown(runnerConfig: utils.RunnerConfig) {
   try {
     logger.info(`Tearing down PowerSync instance...`);
     const config = await utils.loadConfig(runnerConfig);
-    const serviceContext = new system.ServiceContextContainer(config);
+    const serviceContext = new system.ServiceContextContainer({
+      serviceMode: system.ServiceContextMode.TEARDOWN,
+      configuration: config
+    });
+
     const moduleManager = container.getImplementation(modules.ModuleManager);
     await moduleManager.initialize(serviceContext);
     // This is mostly done to ensure that the storage is ready