Error codes

.changeset/fast-taxis-rush.md

@@ -0,0 +1,6 @@
+---
+'@powersync/service-core': patch
+'@powersync/service-image': patch
+---
+
+Add "test-connection" CLI command

.changeset/neat-cycles-trade.md

@@ -0,0 +1,5 @@
+---
+'@powersync/service-sync-rules': patch
+---
+
+Improved error message for "null" bucket definitions.

.changeset/tasty-lamps-remember.md

@@ -0,0 +1,5 @@
+---
+'@powersync/service-module-mongodb': patch
+---
+
+Improved error messages for "Test Connection".

.changeset/wicked-tigers-eat.md

@@ -0,0 +1,17 @@
+---
+'@powersync/service-module-postgres-storage': patch
+'@powersync/service-module-mongodb-storage': patch
+'@powersync/service-module-postgres': patch
+'@powersync/service-rsocket-router': patch
+'@powersync/service-errors': patch
+'@powersync/service-module-mongodb': patch
+'@powersync/service-core': patch
+'@powersync/service-module-mysql': patch
+'@powersync/service-sync-rules': patch
+'@powersync/lib-service-postgres': patch
+'@powersync/lib-services-framework': patch
+'@powersync/lib-service-mongodb': patch
+'@powersync/service-image': patch
+---
+
+Introduce standard error codes

libs/lib-mongodb/src/db/db-index.ts

@@ -1 +1,2 @@
 export * from './mongo.js';
+export * from './errors.js';

libs/lib-mongodb/src/db/errors.ts

@@ -0,0 +1,71 @@
+import { DatabaseConnectionError, ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import { isMongoServerError } from './mongo.js';
+import { MongoNetworkError, MongoServerSelectionError } from 'mongodb';
+
+export function mapConnectionError(err: any): ServiceError {
+  const cause = err.cause;
+  if (ServiceError.isServiceError(err)) {
+    return err;
+  } else if (isMongoServerError(err)) {
+    if (err.codeName == 'AuthenticationFailed') {
+      return new DatabaseConnectionError(
+        ErrorCode.PSYNC_S1306,
+        'MongoDB authentication failed. Check the username and password.',
+        err
+      );
+    } else if (err.codeName == 'Unauthorized') {
+      return new DatabaseConnectionError(
+        ErrorCode.PSYNC_S1307,
+        'MongoDB authorization issue. Check that the user has the required permissions.',
+        err
+      );
+    }
+    // Fallback
+    return new DatabaseConnectionError(ErrorCode.PSYNC_S1301, `MongoDB server error: ${err.codeName}`, err);
+  } else if (isNetworkError(cause)) {
+    if (hasCode(cause.cause, 'ERR_SSL_TLSV1_ALERT_INTERNAL_ERROR')) {
+      // This specifically happens on shared Atlas clusters where the IP Access List is not set up correctly.
+      // Since it's a shared cluster, the connection is not blocked completely, but closes during the TLS setup.
+      return new DatabaseConnectionError(
+        ErrorCode.PSYNC_S1303,
+        'Internal TLS Error. Check IP Access List on the cluster.',
+        err
+      );
+    } else if (hasCode(cause.cause, 'ENOTFOUND')) {
+      return new DatabaseConnectionError(
+        ErrorCode.PSYNC_S1304,
+        'DNS lookup error. Check that the hostname is correct.',
+        err
+      );
+    }
+    // Fallback
+    return new DatabaseConnectionError(ErrorCode.PSYNC_S1302, 'MongoDB network error', err);
+  } else if (err.code == 'ENOTFOUND') {
+    return new DatabaseConnectionError(
+      ErrorCode.PSYNC_S1304,
+      'DNS lookup error. Check that the hostname is correct.',
+      err
+    );
+  } else if (isMongoServerSelectionError(err) && err.message.includes('Server selection timed out')) {
+    return new DatabaseConnectionError(
+      ErrorCode.PSYNC_S1305,
+      'Connection timed out. Check the IP Access List on the cluster.',
+      err
+    );
+  } else {
+    // Fallback
+    return new DatabaseConnectionError(ErrorCode.PSYNC_S1301, 'MongoDB connection error', err);
+  }
+}
+
+function isNetworkError(err: any): err is MongoNetworkError {
+  return err?.name === 'MongoNetworkError';
+}
+
+function isMongoServerSelectionError(err: any): err is MongoServerSelectionError {
+  return err?.name === 'MongoServerSelectionError';
+}
+
+function hasCode(err: any, code: string): boolean {
+  return err?.code == code;
+}

libs/lib-mongodb/src/types/types.ts

@@ -1,4 +1,4 @@
-import { LookupOptions, makeHostnameLookupFunction } from '@powersync/lib-services-framework';
+import { ErrorCode, LookupOptions, makeHostnameLookupFunction, ServiceError } from '@powersync/lib-services-framework';
 import * as t from 'ts-codec';
 import * as urijs from 'uri-js';
 
@@ -44,7 +44,7 @@ export function normalizeMongoConfig(options: BaseMongoConfigDecoded) {
   const password = options.password ?? userInfo?.[1];
 
   if (database == '') {
-    throw new Error(`database required`);
+    throw new ServiceError(ErrorCode.PSYNC_S1105, `MongoDB connection: database required`);
   }
 
   delete uri.userinfo;

libs/lib-mongodb/tsconfig.json

@@ -8,5 +8,5 @@
     "sourceMap": true
   },
   "include": ["src"],
-  "references": []
+  "references": [{ "path": "../lib-services" }]
 }

libs/lib-postgres/src/types/types.ts

@@ -1,4 +1,4 @@
-import { makeHostnameLookupFunction } from '@powersync/lib-services-framework';
+import { ErrorCode, makeHostnameLookupFunction, ServiceError } from '@powersync/lib-services-framework';
 import type * as jpgwire from '@powersync/service-jpgwire';
 import * as service_types from '@powersync/service-types';
 import * as t from 'ts-codec';
@@ -58,7 +58,10 @@ export function normalizeConnectionConfig(options: BasePostgresConnectionConfigD
   if (options.uri) {
     uri = urijs.parse(options.uri);
     if (uri.scheme != 'postgresql' && uri.scheme != 'postgres') {
-      `Invalid URI - protocol must be postgresql, got ${uri.scheme}`;
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1109,
+        `Invalid URI - protocol must be postgresql, got ${JSON.stringify(uri.scheme)}`
+      );
     } else if (uri.scheme != 'postgresql') {
       uri.scheme = 'postgresql';
     }
@@ -80,23 +83,26 @@ export function normalizeConnectionConfig(options: BasePostgresConnectionConfigD
   const cacert = options.cacert;
 
   if (sslmode == 'verify-ca' && cacert == null) {
-    throw new Error('Explicit cacert is required for sslmode=verify-ca');
+    throw new ServiceError(
+      ErrorCode.PSYNC_S1104,
+      'Postgres connection: Explicit cacert is required for `sslmode: verify-ca`'
+    );
   }
 
   if (hostname == '') {
-    throw new Error(`hostname required`);
+    throw new ServiceError(ErrorCode.PSYNC_S1106, `Postgres connection: hostname required`);
   }
 
   if (username == '') {
-    throw new Error(`username required`);
+    throw new ServiceError(ErrorCode.PSYNC_S1107, `Postgres connection: username required`);
   }
 
   if (password == '') {
-    throw new Error(`password required`);
+    throw new ServiceError(ErrorCode.PSYNC_S1108, `Postgres connection: password required`);
   }
 
   if (database == '') {
-    throw new Error(`database required`);
+    throw new ServiceError(ErrorCode.PSYNC_S1105, `Postgres connection: database required`);
   }
 
   const lookupOptions = { reject_ip_ranges: options.reject_ip_ranges ?? [] };
@@ -132,8 +138,8 @@ export function validatePort(port: string | number): number {
   if (typeof port == 'string') {
     port = parseInt(port);
   }
-  if (port < 1024) {
-    throw new Error(`Port ${port} not supported`);
+  if (port < 1024 || port > 65535) {
+    throw new ServiceError(ErrorCode.PSYNC_S1110, `Port ${port} not supported`);
   }
   return port;
 }

libs/lib-postgres/src/utils/pgwire_utils.ts

@@ -2,7 +2,7 @@
 
 import * as pgwire from '@powersync/service-jpgwire';
 
-import { logger } from '@powersync/lib-services-framework';
+import { logger, ServiceAssertionError } from '@powersync/lib-services-framework';
 
 export function escapeIdentifier(identifier: string) {
   return `"${identifier.replace(/"/g, '""').replace(/\./g, '"."')}"`;
@@ -24,7 +24,7 @@ export function autoParameter(arg: any): pgwire.StatementParam {
   } else if (typeof arg == 'bigint') {
     return { type: 'int8', value: arg };
   } else {
-    throw new Error(`Unsupported query parameter: ${typeof arg}`);
+    throw new ServiceAssertionError(`Unsupported query parameter: ${typeof arg}`);
   }
 }
 

libs/lib-postgres/tsconfig.json

@@ -8,5 +8,5 @@
     "sourceMap": true
   },
   "include": ["src"],
-  "references": [{ "path": "../../packages/jpgwire" }, { "path": "../lib-services" }]
+  "references": [{ "path": "../lib-services" }, { "path": "../../packages/jpgwire" }]
 }

libs/lib-services/package.json

@@ -20,6 +20,7 @@
   },
   "keywords": [],
   "dependencies": {
+    "@powersync/service-errors": "workspace:*",
     "ajv": "^8.12.0",
     "better-ajv-errors": "^1.2.0",
     "bson": "^6.8.0",

libs/lib-services/src/container.ts

@@ -3,6 +3,7 @@ import { ErrorReporter } from './alerts/definitions.js';
 import { NoOpReporter } from './alerts/no-op-reporter.js';
 import { MigrationManager } from './migrations/MigrationManager.js';
 import { ProbeModule, TerminationHandler, createFSProbe, createTerminationHandler } from './signals/signals-index.js';
+import { ServiceAssertionError } from '@powersync/service-errors';
 
 export enum ContainerImplementation {
   REPORTER = 'reporter',
@@ -100,7 +101,7 @@ export class Container {
   getImplementation<T>(identifier: ServiceIdentifier<T>): T {
     const implementation = this.implementations.get(identifier);
     if (!implementation) {
-      throw new Error(`Implementation for ${String(identifier)} has not been registered.`);
+      throw new ServiceAssertionError(`Implementation for ${String(identifier)} has not been registered.`);
     }
     return implementation;
   }

libs/lib-services/src/errors/errors-index.ts

@@ -1,2 +1 @@
-export * from './framework-errors.js';
-export * from './utils.js';
+export * from '@powersync/service-errors';