refactor: abstract platform dependencies for testability and add auth tests (#526)

# Add Testing Utilities for Edge Worker Platform Abstraction

This PR adds a new `/testing` entry point to the edge-worker package that provides utilities for testing Supabase platform integrations. The key improvements include:

1. Created a platform dependency abstraction layer that decouples the SupabasePlatformAdapter from Deno globals
2. Added a `configurePlatform()` utility for overriding platform dependencies in tests
3. Implemented comprehensive unit tests for SupabasePlatformAdapter
4. Added E2E tests for authorization validation in production environments

The implementation:
- Extracts platform dependencies (env, serve, shutdown, etc.) into a dedicated interface
- Provides a default implementation using Deno globals
- Allows tests to override these dependencies without mocking globals
- Includes a new auth_test edge function for E2E testing of authorization

This approach makes the edge worker more testable while maintaining the same runtime behavior in production.

Author: jumski

PLAN.md

@@ -15,6 +15,10 @@
     "./_internal": {
       "types": "./dist/_internal.d.ts",
       "import": "./dist/_internal.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "files": [

pkgs/edge-worker/package.json

@@ -57,6 +57,12 @@ cat > "$VENDOR_DIR/@pgflow/edge-worker/_internal.ts" << 'EOF'
 export * from './src/_internal.ts';
 EOF
 
+# Create testing.ts redirect for test utilities
+cat > "$VENDOR_DIR/@pgflow/edge-worker/testing.ts" << 'EOF'
+// Re-export from the src directory to maintain compatibility
+export * from './src/testing.ts';
+EOF
+
 # Verify key files exist
 if [ ! -f "$VENDOR_DIR/@pgflow/core/index.js" ]; then
     echo "⚠️  Warning: @pgflow/core/index.js not found after copy"

pkgs/edge-worker/scripts/sync-e2e-deps.sh

@@ -16,13 +16,7 @@ import {
   resolveSqlConnection,
 } from './resolveConnection.js';
 import { Queries } from '../core/Queries.js';
-
-/**
- * Supabase Edge Runtime type (without global augmentation to comply with JSR)
- */
-interface EdgeRuntimeType {
-  waitUntil(promise: Promise<unknown>): void;
-}
+import { getPlatformDeps, type SupabasePlatformDeps } from './deps.js';
 
 /**
  * Supabase-specific environment variables
@@ -54,13 +48,19 @@ export class SupabasePlatformAdapter implements PlatformAdapter<SupabaseResource
   private validatedEnv: SupabaseEnv;
   private _connectionString: string | undefined;
   private queries: Queries;
+  private deps: SupabasePlatformDeps;
 
   // Logging factory with dynamic workerId support
   private loggingFactory = createLoggingFactory();
 
-  constructor(options?: { sql?: Sql; connectionString?: string }) {
+  constructor(
+    options?: { sql?: Sql; connectionString?: string },
+    deps: SupabasePlatformDeps = getPlatformDeps()
+  ) {
+    this.deps = deps;
+
     // Validate environment variables once at startup
-    const env = Deno.env.toObject();
+    const env = deps.getEnv();
     this.assertSupabaseEnv(env);
     this.validatedEnv = env;
 
@@ -173,7 +173,7 @@ export class SupabasePlatformAdapter implements PlatformAdapter<SupabaseResource
   }
 
   private setupShutdownHandler(): void {
-    globalThis.onbeforeunload = async () => {
+    this.deps.onShutdown(async () => {
       this.logger.debug('Shutting down...');
 
       if (this.worker) {
@@ -184,7 +184,7 @@ export class SupabasePlatformAdapter implements PlatformAdapter<SupabaseResource
       }
 
       await this.stopWorker();
-    };
+    });
   }
 
   /**
@@ -195,15 +195,14 @@ export class SupabasePlatformAdapter implements PlatformAdapter<SupabaseResource
    * by passing a promise that never resolves.
    */
   private extendLifetimeOfEdgeFunction(): void {
-    // EdgeRuntime is available in Supabase Edge Functions runtime
     const promiseThatNeverResolves = new Promise(() => {
       // Intentionally empty - this promise never resolves to extend function lifetime
     });
-    (globalThis as typeof globalThis & { EdgeRuntime: EdgeRuntimeType }).EdgeRuntime.waitUntil(promiseThatNeverResolves);
+    this.deps.extendLifetime(promiseThatNeverResolves);
   }
 
   private setupStartupHandler(createWorkerFn: CreateWorkerFn): void {
-    Deno.serve({}, (req: Request) => {
+    this.deps.serve((req: Request) => {
       // Validate auth header in production (skipped in local mode)
       const authResult = validateServiceRoleAuth(req, this.validatedEnv);
       if (!authResult.valid) {

pkgs/edge-worker/src/platform/SupabasePlatformAdapter.ts

@@ -2,6 +2,7 @@ import type { PlatformAdapter } from './types.js';
 import { SupabasePlatformAdapter } from './SupabasePlatformAdapter.js';
 import type { SupabaseResources } from '@pgflow/dsl/supabase';
 import type { Sql } from 'postgres';
+import { getPlatformDeps } from './deps.js';
 
 interface AdapterOptions {
   sql?: Sql;
@@ -15,7 +16,7 @@ export function createAdapter(options?: AdapterOptions): PlatformAdapter<Supabas
   if (isDenoEnvironment()) {
     // For now, always use SupabasePlatformAdapter for Deno
     // In the future, we could detect Supabase vs other Deno environments
-    const adapter = new SupabasePlatformAdapter(options);
+    const adapter = new SupabasePlatformAdapter(options, getPlatformDeps());
     return adapter;
   }
 

pkgs/edge-worker/src/platform/createAdapter.ts

@@ -0,0 +1,55 @@
+/**
+ * Platform dependencies interface for abstracting Deno/EdgeRuntime globals.
+ * This enables unit testing of SupabasePlatformAdapter without mocking globals.
+ */
+export interface SupabasePlatformDeps {
+  getEnv: () => Record<string, string | undefined>;
+  onShutdown: (handler: () => void | Promise<void>) => void;
+  extendLifetime: (promise: Promise<unknown>) => void;
+  serve: (handler: (req: Request) => Response | Promise<Response>) => void;
+}
+
+/**
+ * Type for globalThis with EdgeRuntime available (Supabase Edge Functions).
+ */
+type EdgeRuntimeGlobal = typeof globalThis & {
+  EdgeRuntime: { waitUntil(p: Promise<unknown>): void };
+};
+
+/**
+ * Default implementation using Deno runtime globals.
+ */
+const defaultDeps: SupabasePlatformDeps = {
+  getEnv: () => Deno.env.toObject(),
+  onShutdown: (h) => {
+    globalThis.onbeforeunload = h;
+  },
+  extendLifetime: (p) => (globalThis as EdgeRuntimeGlobal).EdgeRuntime.waitUntil(p),
+  serve: (h) => Deno.serve({}, h),
+};
+
+let currentDeps = defaultDeps;
+
+/**
+ * Get current platform dependencies.
+ * Used by createAdapter() to pass deps to SupabasePlatformAdapter.
+ */
+export const getPlatformDeps = (): SupabasePlatformDeps => currentDeps;
+
+/**
+ * Configure platform dependencies for testing.
+ * Exported via /testing entry point.
+ *
+ * WARNING: This is a permanent override for the lifetime of the process.
+ * There is no reset function - once configured, the overrides stay active.
+ * This is intentional for edge functions where the mock must persist across
+ * all HTTP requests. If scoped mocking with cleanup is needed in the future,
+ * consider adding resetPlatform() and withMockPlatform() utilities.
+ */
+export function configurePlatform(overrides: Partial<SupabasePlatformDeps>): void {
+  console.warn(
+    '[pgflow] configurePlatform() called - platform deps permanently overridden:',
+    Object.keys(overrides).join(', ')
+  );
+  currentDeps = { ...defaultDeps, ...overrides };
+}

pkgs/edge-worker/src/platform/deps.ts

@@ -1,3 +1,4 @@
 export * from './types.js';
 export { createAdapter } from './createAdapter.js';
 export { SupabasePlatformAdapter } from './SupabasePlatformAdapter.js';
+export type { SupabasePlatformDeps } from './deps.js';

pkgs/edge-worker/src/platform/index.ts

@@ -14,7 +14,3 @@ export function isLocalSupabaseEnv(env: Record<string, string | undefined>): boo
   return anonKey === KNOWN_LOCAL_ANON_KEY ||
          serviceRoleKey === KNOWN_LOCAL_SERVICE_ROLE_KEY;
 }
-
-export function isLocalSupabase(): boolean {
-  return isLocalSupabaseEnv(Deno.env.toObject());
-}

pkgs/edge-worker/src/shared/localDetection.ts

@@ -0,0 +1,10 @@
+/**
+ * Test utilities for @pgflow/edge-worker
+ *
+ * Import via: import { ... } from '@pgflow/edge-worker/testing';
+ */
+
+export {
+  configurePlatform,
+  type SupabasePlatformDeps,
+} from './platform/deps.js';

pkgs/edge-worker/src/testing.ts

@@ -56,3 +56,45 @@ enabled = true
 verify_jwt = false
 import_map = "./functions/deno.json"
 entrypoint = "./functions/pgflow/index.ts"
+
+[functions.auth_test]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/auth_test/index.ts"
+
+[functions.conn_zero_config]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/conn_zero_config/index.ts"
+
+[functions.conn_string]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/conn_string/index.ts"
+
+[functions.conn_env_var]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/conn_env_var/index.ts"
+
+[functions.conn_custom_sql]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/conn_custom_sql/index.ts"
+
+[functions.stopped_at_test]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/stopped_at_test/index.ts"
+
+[functions.retry-demo]
+enabled = true
+verify_jwt = false
+import_map = "./functions/deno.json"
+entrypoint = "./functions/retry-demo/index.ts"