Add custom error handler to honour content-encoding (#649)

Author: joshuabrink

.changeset/fix-error-handler-content-encoding.md

@@ -0,0 +1,5 @@
+---
+'@powersync/service-core': patch
+---
+
+Add a custom Fastify error handler so uncaught errors honour the negotiated `Content-Encoding` (gzip/zstd) instead of returning a header that doesn't match the body.

packages/service-core/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

packages/service-core/src/routes/route-register.ts

@@ -1,7 +1,8 @@
 import type fastify from 'fastify';
+import * as zlib from 'node:zlib';
 import * as uuid from 'uuid';
 
-import { errors, HTTPMethod, logger, RouteNotFound, router, ServiceError } from '@powersync/lib-services-framework';
+import { errors, HTTPMethod, logger, RouteNotFound, router } from '@powersync/lib-services-framework';
 import { FastifyReply } from 'fastify';
 import { Context, ContextProvider, RequestEndpoint, RequestEndpointHandlerPayload } from './router.js';
 
@@ -105,18 +106,86 @@ export function registerFastifyNotFoundHandler(app: fastify.FastifyInstance) {
   });
 }
 
-function serviceErrorToResponse(error: ServiceError): router.RouterResponse {
+/** Registers a custom error handler that emits service-error JSON honouring any negotiated `Content-Encoding`. */
+export function registerFastifyErrorHandler(app: fastify.FastifyInstance) {
+  app.setErrorHandler<Error>(async (error, _request, reply) => {
+    if (reply.raw.headersSent) {
+      // Headers already flushed - reply.code/header would throw ERR_HTTP_HEADERS_SENT.
+      reply.raw.destroy(error);
+      return;
+    }
+
+    const { status, data } = fastifyErrorToResponse(error);
+    if (status >= 500) {
+      logger.error('Request failed', error);
+    } else {
+      logger.warn(`Request failed: ${error.message}`, {
+        status,
+        code: data.error.code
+      });
+    }
+
+    const json = JSON.stringify(data);
+
+    // Fastify's default handler leaves `content-encoding` intact when it rewrites the body.
+    const encoding = reply.getHeader('content-encoding');
+    let body: string | Buffer = json;
+    if (encoding === 'gzip') {
+      body = zlib.gzipSync(json);
+    } else if (encoding === 'zstd') {
+      body = zlib.zstdCompressSync(json);
+    } else {
+      reply.removeHeader('content-encoding');
+    }
+
+    reply
+      .code(status)
+      .header('content-type', 'application/json; charset=utf-8')
+      .header('content-length', Buffer.byteLength(body))
+      .send(body);
+  });
+}
+
+type ErrorResponseData = { error: errors.ErrorData };
+
+function serviceErrorToResponse(serviceError: errors.ServiceError): router.RouterResponse<ErrorResponseData> {
   return new router.RouterResponse({
-    status: error.errorData.status || 500,
+    status: serviceError.errorData.status || 500,
     headers: {
       'Content-Type': 'application/json'
     },
     data: {
-      error: error.errorData
+      error: serviceError.errorData
     }
   });
 }
 
+function fastifyErrorToResponse(error: any): router.RouterResponse<ErrorResponseData> {
+  // Preserve 4xx status from Fastify built-ins (validation, invalid JSON body, etc.) instead of collapsing to 500.
+  if (
+    typeof error?.statusCode === 'number' &&
+    error.statusCode >= 400 &&
+    error.statusCode < 500 &&
+    typeof error.code === 'string'
+  ) {
+    return new router.RouterResponse({
+      status: error.statusCode,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      data: {
+        error: {
+          name: error.name,
+          code: error.code,
+          status: error.statusCode,
+          description: error.message
+        }
+      }
+    });
+  }
+  return serviceErrorToResponse(errors.asServiceError(error));
+}
+
 async function respond(reply: FastifyReply, response: router.RouterResponse) {
   Object.keys(response.headers).forEach((key) => {
     reply.header(key, response.headers[key]);