@powersync/service-core 0.0.0-dev-20250507132759 → 0.0.0-dev-20250507151436

package/src/util/config/collectors/config-collector.ts

@@ -1,29 +1,22 @@
+import { configFile } from '@powersync/service-types';
+import * as t from 'ts-codec';
 import * as yaml from 'yaml';
 
 import { schema } from '@powersync/lib-services-framework';
-import { configFile } from '@powersync/service-types';
-
 import { RunnerConfig } from '../types.js';
+import { YamlEnvTag } from './impl/yaml-env.js';
 
 export enum ConfigFileFormat {
   YAML = 'yaml',
   JSON = 'json'
 }
 
-/**
- * Environment variables can be substituted into the YAML config
- * when parsing if the environment variable name starts with this prefix.
- * Attempting to substitute any other environment variable will throw an exception.
- *
- * Example of substitution:
- * storage:
- *    type: mongodb
- *    uri: !env PS_MONGO_URI
- */
-const YAML_ENV_PREFIX = 'PS_';
-
 // ts-codec itself doesn't give great validation errors, so we use json schema for that
-const configSchemaValidator = schema.parseJSONSchema(configFile.PowerSyncConfigJSONSchema).validator();
+const configSchemaValidator = schema
+  .parseJSONSchema(
+    t.generateJSONSchema(configFile.powerSyncConfig, { allowAdditional: true, parsers: [configFile.portParser] })
+  )
+  .validator();
 
 export abstract class ConfigCollector {
   abstract get name(): string;
@@ -100,27 +93,7 @@ export abstract class ConfigCollector {
       schema: 'core',
       keepSourceTokens: true,
       lineCounter,
-      customTags: [
-        {
-          tag: '!env',
-          resolve(envName: string, onError: (error: string) => void) {
-            if (!envName.startsWith(YAML_ENV_PREFIX)) {
-              onError(
-                `Attempting to substitute environment variable ${envName} is not allowed. Variables must start with "${YAML_ENV_PREFIX}"`
-              );
-              return envName;
-            }
-            const value = process.env[envName];
-            if (typeof value == 'undefined') {
-              onError(
-                `Attempted to substitute environment variable "${envName}" which is undefined. Set this variable on the environment.`
-              );
-              return envName;
-            }
-            return value;
-          }
-        }
-      ]
+      customTags: [YamlEnvTag]
     });
 
     if (parsed.errors.length) {

package/src/util/config/collectors/impl/yaml-env.ts

@@ -0,0 +1,67 @@
+import * as yaml from 'yaml';
+
+/**
+ * Environment variables can be substituted into the YAML config
+ * when parsing if the environment variable name starts with this prefix.
+ * Attempting to substitute any other environment variable will throw an exception.
+ *
+ * Example of substitution:
+ * storage:
+ *    type: mongodb
+ *    uri: !env PS_MONGO_URI
+ */
+const YAML_ENV_PREFIX = 'PS_';
+
+/**
+ * Custom YAML tag which performs string environment variable substitution
+ * Allows for type casting string environment variables to boolean or number
+ * by using the syntax !env PS_MONGO_PORT::number or !env PS_USE_SUPABASE::boolean
+ */
+export const YamlEnvTag: yaml.ScalarTag = {
+  tag: '!env',
+  resolve(envName: string, onError: (error: string) => void) {
+    if (!envName.startsWith(YAML_ENV_PREFIX)) {
+      onError(
+        `Attempting to substitute environment variable ${envName} is not allowed. Variables must start with "${YAML_ENV_PREFIX}"`
+      );
+      return envName;
+    }
+
+    // allow type casting if the envName contains a type suffix
+    // e.g. PS_MONGO_PORT::number or PS_USE_SUPABASE::boolean
+    const [name, type = 'string'] = envName.split('::');
+
+    let value = process.env[name];
+
+    if (typeof value == 'undefined') {
+      onError(
+        `Attempted to substitute environment variable "${envName}" which is undefined. Set this variable on the environment.`
+      );
+      return envName;
+    }
+
+    switch (type) {
+      case 'string':
+        return value;
+      case 'number':
+        const numberValue = Number(value);
+        if (Number.isNaN(numberValue)) {
+          onError(`Environment variable "${envName}" is not a valid number. Got: "${value}".`);
+          return envName;
+        }
+        return numberValue;
+      case 'boolean':
+        if (value?.toLowerCase() == 'true') {
+          return true;
+        } else if (value?.toLowerCase() == 'false') {
+          return false;
+        } else {
+          onError(`Environment variable "${envName}" is not a boolean. Expected "true" or "false", got "${value}".`);
+          return envName;
+        }
+      default:
+        onError(`Environment variable "${envName}" has an invalid type suffix "${type}".`);
+        return envName;
+    }
+  }
+};

package/src/util/config/compound-config-collector.ts

@@ -5,11 +5,6 @@ import { ConfigCollector } from './collectors/config-collector.js';
 import { Base64ConfigCollector } from './collectors/impl/base64-config-collector.js';
 import { FallbackConfigCollector } from './collectors/impl/fallback-config-collector.js';
 import { FileSystemConfigCollector } from './collectors/impl/filesystem-config-collector.js';
-import { Base64SyncRulesCollector } from './sync-rules/impl/base64-sync-rules-collector.js';
-import { FileSystemSyncRulesCollector } from './sync-rules/impl/filesystem-sync-rules-collector.js';
-import { InlineSyncRulesCollector } from './sync-rules/impl/inline-sync-rules-collector.js';
-import { SyncRulesCollector } from './sync-rules/sync-collector.js';
-import { ResolvedPowerSyncConfig, RunnerConfig, SyncRulesConfig } from './types.js';
 import {
   DEFAULT_MAX_BUCKETS_PER_CONNECTION,
   DEFAULT_MAX_CONCURRENT_CONNECTIONS,
@@ -17,6 +12,11 @@ import {
   DEFAULT_MAX_PARAMETER_QUERY_RESULTS,
   DEFAULT_MAX_POOL_SIZE
 } from './defaults.js';
+import { Base64SyncRulesCollector } from './sync-rules/impl/base64-sync-rules-collector.js';
+import { FileSystemSyncRulesCollector } from './sync-rules/impl/filesystem-sync-rules-collector.js';
+import { InlineSyncRulesCollector } from './sync-rules/impl/inline-sync-rules-collector.js';
+import { SyncRulesCollector } from './sync-rules/sync-collector.js';
+import { ResolvedPowerSyncConfig, RunnerConfig, SyncRulesConfig } from './types.js';
 
 export type CompoundConfigCollectorOptions = {
   /**
@@ -159,6 +159,23 @@ export class CompoundConfigCollector {
         internal_service_endpoint:
           baseConfig.telemetry?.internal_service_endpoint ?? 'https://pulse.journeyapps.com/v1/metrics'
       },
+      healthcheck: {
+        /**
+         * Default to legacy mode if no probes config is provided.
+         * If users provide a config, all options require explicit opt-in.
+         */
+        probes: baseConfig.healthcheck?.probes
+          ? {
+              use_filesystem: baseConfig.healthcheck.probes.use_filesystem ?? false,
+              use_http: baseConfig.healthcheck.probes.use_http ?? false,
+              use_legacy: baseConfig.healthcheck.probes.use_legacy ?? false
+            }
+          : {
+              use_filesystem: false,
+              use_http: false,
+              use_legacy: true
+            }
+      },
       api_parameters: {
         max_buckets_per_connection:
           baseConfig.api?.parameters?.max_buckets_per_connection ?? DEFAULT_MAX_BUCKETS_PER_CONNECTION,

package/src/util/config/types.ts

@@ -69,5 +69,18 @@ export type ResolvedPowerSyncConfig = {
 
   /** Prefix for postgres replication slot names. May eventually be connection-specific. */
   slot_name_prefix: string;
+
+  healthcheck: {
+    probes: {
+      use_filesystem: boolean;
+      use_http: boolean;
+      /**
+       * @deprecated This maintains backwards compatibility with the legacy default.
+       * Explicit probe configuration should be used instead.
+       */
+      use_legacy: boolean;
+    };
+  };
+
   parameters: Record<string, number | string | boolean | null>;
 };

package/test/src/config.test.ts

@@ -0,0 +1,72 @@
+// Vitest Unit Tests
+import { CompoundConfigCollector } from '@/index.js';
+import { describe, expect, it, vi } from 'vitest';
+
+describe('Config', () => {
+  it('should substitute env variables in YAML config', {}, async () => {
+    const type = 'mongodb';
+    vi.stubEnv('PS_MONGO_TYPE', type);
+
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: !env PS_MONGO_TYPE
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.storage.type).toBe(type);
+  });
+
+  it('should substitute boolean env variables in YAML config', {}, async () => {
+    vi.stubEnv('PS_MONGO_HEALTHCHECK', 'true');
+
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+      healthcheck:
+        probes:
+          use_http: !env PS_MONGO_HEALTHCHECK::boolean
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.healthcheck.probes.use_http).toBe(true);
+  });
+
+  it('should substitute number env variables in YAML config', {}, async () => {
+    vi.stubEnv('PS_MAX_BUCKETS', '1');
+
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+      api:
+        parameters:
+          max_buckets_per_connection: !env PS_MAX_BUCKETS::number
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.api_parameters.max_buckets_per_connection).toBe(1);
+  });
+});