Deep Dive: How Supabase Functions Handle Autoscaling for 50k Concurrent Users

/**
 * Core autoscaler logic for Supabase Functions, based on the open-source
 * implementation in https://github.com/supabase/functions/tree/main/packages/autoscaler
 * Handles concurrency-based scaling with V8 isolate pooling and cold start mitigation.
 */
import { Logger } from "https://deno.land/std@0.207.0/log/mod.ts";
import { Redis } from "https://deno.land/x/redis@v0.32.0/mod.ts";

const logger = new Logger({ level: "INFO" });
const CONCURRENCY_PER_INSTANCE = 500; // Max concurrent requests per function instance
const COLD_START_THRESHOLD_MS = 300; // Max acceptable cold start time
const SCALE_UP_COOLDOWN_MS = 2000; // Prevent rapid scaling flapping
const SCALE_DOWN_COOLDOWN_MS = 30000; // Longer cooldown for scale down to avoid thrashing

interface InstanceMetrics {
  id: string;
  activeConnections: number;
  cpuUsage: number;
  memoryUsage: number;
  lastHeartbeat: number;
}

interface ScalingDecision {
  action: "scale_up" | "scale_down" | "no_action";
  targetInstances: number;
  reason: string;
}

export class FunctionsAutoscaler {
  private redisClient: Redis;
  private currentInstances: Map = new Map();
  private lastScaleAction: number = 0;

  constructor(redisUrl: string) {
    try {
      this.redisClient = new Redis({
        url: redisUrl,
        // Connection pool settings to avoid Redis overload during traffic spikes
        maxRetries: 3,
        retryDelay: 100,
        poolSize: 10,
      });
      logger.info("Autoscaler Redis client initialized");
    } catch (error) {
      logger.error(`Failed to initialize Redis client: ${error.message}`);
      throw new Error(`Autoscaler initialization failed: ${error.message}`);
    }
  }

  /**
   * Fetches real-time concurrency metrics from Redis, where Supabase
   * Edge Gateway pushes per-instance request counts every 100ms.
   */
  async fetchCurrentMetrics(): Promise {
    try {
      const rawMetrics = await this.redisClient.hgetall("functions:instance_metrics");
      const metrics: InstanceMetrics[] = [];

      for (const [instanceId, rawValue] of Object.entries(rawMetrics)) {
        try {
          const parsed: InstanceMetrics = JSON.parse(rawValue as string);
          // Validate metric freshness: ignore instances with no heartbeat in 5s
          if (Date.now() - parsed.lastHeartbeat < 5000) {
            metrics.push(parsed);
            this.currentInstances.set(instanceId, parsed);
          } else {
            logger.warn(`Stale metrics for instance ${instanceId}, removing from pool`);
            await this.redisClient.hdel("functions:instance_metrics", instanceId);
          }
        } catch (parseError) {
          logger.error(`Failed to parse metrics for ${instanceId}: ${parseError.message}`);
        }
      }
      return metrics;
    } catch (error) {
      logger.error(`Failed to fetch metrics from Redis: ${error.message}`);
      throw new Error(`Metrics fetch failed: ${error.message}`);
    }
  }

  /**
   * Core scaling decision logic: evaluates current concurrency against
   * target thresholds, applies cooldown rules, and returns scaling action.
   */
  async evaluateScaling(): Promise {
    const now = Date.now();
    const metrics = await this.fetchCurrentMetrics();
    const totalActive = metrics.reduce((sum, m) => sum + m.activeConnections, 0);
    const currentInstanceCount = metrics.length;
    const targetInstanceCount = Math.ceil(totalActive / CONCURRENCY_PER_INSTANCE);

    // Enforce scale up cooldown to prevent flapping
    if (now - this.lastScaleAction < SCALE_UP_COOLDOWN_MS && targetInstanceCount > currentInstanceCount) {
      return {
        action: "no_action",
        targetInstances: currentInstanceCount,
        reason: `Scale up cooldown active (${SCALE_UP_COOLDOWN_MS}ms remaining)`,
      };
    }

    // Enforce longer scale down cooldown to avoid unnecessary termination
    if (now - this.lastScaleAction < SCALE_DOWN_COOLDOWN_MS && targetInstanceCount < currentInstanceCount) {
      return {
        action: "no_action",
        targetInstances: currentInstanceCount,
        reason: `Scale down cooldown active (${SCALE_DOWN_COOLDOWN_MS}ms remaining)`,
      };
    }

    if (targetInstanceCount > currentInstanceCount) {
      this.lastScaleAction = now;
      return {
        action: "scale_up",
        targetInstances: targetInstanceCount,
        reason: `Total active connections ${totalActive} exceeds per-instance limit (${CONCURRENCY_PER_INSTANCE})`,
      };
    } else if (targetInstanceCount < currentInstanceCount) {
      this.lastScaleAction = now;
      return {
        action: "scale_down",
        targetInstances: targetInstanceCount,
        reason: `Total active connections ${totalActive} below threshold for current instances`,
      };
    }

    return {
      action: "no_action",
      targetInstances: currentInstanceCount,
      reason: "Current instance count matches target",
    };
  }
}

/**
 * V8 Isolate Pool manager for Supabase Functions: reuses V8 isolates across
 * requests to avoid cold start overhead. Based on Deno's isolate pooling
 * implementation in https://github.com/denoland/deno/tree/main/runtime/isolate_pool
 */
import { assert } from "https://deno.land/std@0.207.0/testing/asserts.ts";
import { Errors } from "./errors.ts";

const MAX_ISOLATES_PER_INSTANCE = 100; // Max isolates per function instance (matches 500 concurrency / 5 req/isolate)
const ISOLATE_IDLE_TIMEOUT_MS = 60000; // Terminate idle isolates after 60s
const ISOLATE_INIT_TIMEOUT_MS = 2000; // Max time to initialize a new isolate

interface IsolateConfig {
  runtimeVersion: string;
  envVars: Record;
  functionSlug: string;
}

interface PooledIsolate {
  id: string;
  config: IsolateConfig;
  lastUsed: number;
  isBusy: boolean;
  v8Context: object; // Opaque V8 context reference from Deno runtime
}

export class IsolatePool {
  private pool: Map = new Map();
  private pendingIsolates: Set = new Set();

  constructor() {
    // Periodic cleanup of idle isolates every 30s
    setInterval(() => this.cleanupIdleIsolates(), 30000).unref();
    console.info(`Isolate pool initialized with max ${MAX_ISOLATES_PER_INSTANCE} isolates per instance`);
  }

  /**
   * Acquires an existing idle isolate or spins up a new one if pool is not full.
   * Throws an error if pool is full and no isolates are available.
   */
  async acquireIsolate(config: IsolateConfig): Promise {
    const existingIsolate = this.findIdleIsolate(config);
    if (existingIsolate) {
      existingIsolate.isBusy = true;
      existingIsolate.lastUsed = Date.now();
      console.debug(`Reusing isolate ${existingIsolate.id} for function ${config.functionSlug}`);
      return existingIsolate;
    }

    if (this.pool.size >= MAX_ISOLATES_PER_INSTANCE) {
      throw new Errors.PoolFullError(
        `Isolate pool full (${this.pool.size}/${MAX_ISOLATES_PER_INSTANCE}). Retry later.`
      );
    }

    // Prevent duplicate isolate creation for the same config
    const configHash = this.hashConfig(config);
    if (this.pendingIsolates.has(configHash)) {
      console.debug(`Isolate creation pending for ${config.functionSlug}, waiting...`);
      await this.waitForPendingIsolate(configHash);
      return this.acquireIsolate(config); // Retry after pending isolate is ready
    }

    this.pendingIsolates.add(configHash);
    try {
      const newIsolate = await this.createIsolate(config);
      this.pool.set(newIsolate.id, newIsolate);
      console.info(`Created new isolate ${newIsolate.id} for function ${config.functionSlug}`);
      return newIsolate;
    } catch (error) {
      console.error(`Failed to create isolate for ${config.functionSlug}: ${error.message}`);
      throw new Errors.IsolateCreationError(`Isolate creation failed: ${error.message}`);
    } finally {
      this.pendingIsolates.delete(configHash);
    }
  }

  /**
   * Releases an isolate back to the pool after request processing completes.
   */
  releaseIsolate(isolateId: string): void {
    const isolate = this.pool.get(isolateId);
    if (!isolate) {
      console.warn(`Attempted to release non-existent isolate ${isolateId}`);
      return;
    }
    isolate.isBusy = false;
    isolate.lastUsed = Date.now();
    console.debug(`Released isolate ${isolateId} back to pool`);
  }

  private findIdleIsolate(config: IsolateConfig): PooledIsolate | null {
    for (const isolate of this.pool.values()) {
      if (
        !isolate.isBusy &&
        isolate.config.functionSlug === config.functionSlug &&
        isolate.config.runtimeVersion === config.runtimeVersion &&
        this.hashConfig(isolate.config) === this.hashConfig(config)
      ) {
        return isolate;
      }
    }
    return null;
  }

  private async createIsolate(config: IsolateConfig): Promise {
    const initStart = Date.now();
    // Simulate Deno's V8 isolate creation (real implementation calls Deno.core.newIsolate)
    const v8Context = {}; // Opaque reference in real code
    const initTime = Date.now() - initStart;
    if (initTime > ISOLATE_INIT_TIMEOUT_MS) {
      throw new Error(`Isolate initialization timed out after ${initTime}ms`);
    }
    return {
      id: crypto.randomUUID(),
      config,
      lastUsed: Date.now(),
      isBusy: true,
      v8Context,
    };
  }

  private cleanupIdleIsolates(): void {
    const now = Date.now();
    let cleaned = 0;
    for (const [id, isolate] of this.pool.entries()) {
      if (!isolate.isBusy && now - isolate.lastUsed > ISOLATE_IDLE_TIMEOUT_MS) {
        this.pool.delete(id);
        cleaned++;
        console.debug(`Terminated idle isolate ${id}`);
      }
    }
    if (cleaned > 0) {
      console.info(`Cleaned up ${cleaned} idle isolates`);
    }
  }

  private hashConfig(config: IsolateConfig): string {
    return `${config.functionSlug}:${config.runtimeVersion}:${JSON.stringify(config.envVars)}`;
  }

  private async waitForPendingIsolate(configHash: string, timeoutMs = 5000): Promise {
    const start = Date.now();
    while (this.pendingIsolates.has(configHash) && Date.now() - start < timeoutMs) {
      await new Promise((resolve) => setTimeout(resolve, 100));
    }
    if (this.pendingIsolates.has(configHash)) {
      throw new Error(`Timeout waiting for pending isolate creation`);
    }
  }
}

/**
 * Benchmark script to verify Supabase Functions autoscaling under 50k concurrent users.
 * Run with: deno run --allow-net --allow-env benchmark.ts
 * Results are logged to console and exported to JSON for reporting.
 */
import { assertEquals } from "https://deno.land/std@0.207.0/testing/asserts.ts";
import { delay } from "https://deno.land/std@0.207.0/async/delay.ts";

const FUNCTION_URL = Deno.env.get("FUNCTION_URL") || "https://.functions.supabase.co/hello";
const CONCURRENT_USERS = 50000;
const REQUESTS_PER_USER = 1;
const BENCHMARK_DURATION_MS = 300000; // 5 minute benchmark
const TIMEOUT_MS = 10000; // 10s per request timeout

interface BenchmarkResult {
  totalRequests: number;
  successfulRequests: number;
  failedRequests: number;
  p50LatencyMs: number;
  p95LatencyMs: number;
  p99LatencyMs: number;
  avgLatencyMs: number;
  errors: Record;
}

class ConcurrentBenchmark {
  private results: number[] = [];
  private errors: Record = {};
  private successful = 0;
  private failed = 0;

  async run(): Promise {
    console.log(`Starting benchmark: ${CONCURRENT_USERS} concurrent users, ${REQUESTS_PER_USER} req/user`);
    const start = Date.now();
    const userPromises: Promise[] = [];

    for (let i = 0; i < CONCURRENT_USERS; i++) {
      userPromises.push(this.simulateUser(i));
      // Throttle user creation to avoid local resource exhaustion
      if (i % 1000 === 0) {
        await delay(10);
      }
    }

    await Promise.all(userPromises);
    const duration = Date.now() - start;
    console.log(`Benchmark completed in ${duration}ms`);

    return this.generateReport();
  }

  private async simulateUser(userId: number): Promise {
    for (let req = 0; req < REQUESTS_PER_USER; req++) {
      const reqStart = Date.now();
      try {
        const controller = new AbortController();
        const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);

        const response = await fetch(FUNCTION_URL, {
          method: "GET",
          headers: { "X-User-Id": userId.toString() },
          signal: controller.signal,
        });
        clearTimeout(timeoutId);

        const latency = Date.now() - reqStart;
        this.results.push(latency);

        if (response.ok) {
          this.successful++;
        } else {
          this.failed++;
          const errorKey = `HTTP ${response.status}`;
          this.errors[errorKey] = (this.errors[errorKey] || 0) + 1;
        }
      } catch (error) {
        const latency = Date.now() - reqStart;
        this.results.push(latency);
        this.failed++;
        const errorKey = error.name === "AbortError" ? "Timeout" : error.message;
        this.errors[errorKey] = (this.errors[errorKey] || 0) + 1;
      }
    }
  }

  private generateReport(): BenchmarkResult {
    // Sort results for percentile calculation
    const sorted = [...this.results].sort((a, b) => a - b);
    const total = this.results.length;

    const percentile = (p: number) => {
      const index = Math.floor(p / 100 * total);
      return sorted[index] || 0;
    };

    const avg = sorted.reduce((sum, val) => sum + val, 0) / total;

    const report: BenchmarkResult = {
      totalRequests: total,
      successfulRequests: this.successful,
      failedRequests: this.failed,
      p50LatencyMs: percentile(50),
      p95LatencyMs: percentile(95),
      p99LatencyMs: percentile(99),
      avgLatencyMs: Math.round(avg * 100) / 100,
      errors: this.errors,
    };

    // Log report to console
    console.log("\n=== Benchmark Results ===");
    console.log(`Total Requests: ${report.totalRequests}`);
    console.log(`Success Rate: ${((report.successfulRequests / report.totalRequests) * 100).toFixed(2)}%`);
    console.log(`p50 Latency: ${report.p50LatencyMs}ms`);
    console.log(`p95 Latency: ${report.p95LatencyMs}ms`);
    console.log(`p99 Latency: ${report.p99LatencyMs}ms`);
    console.log(`Avg Latency: ${report.avgLatencyMs}ms`);
    console.log("Errors:", report.errors);

    // Write report to JSON file
    try {
      await Deno.writeTextFile(
        `benchmark-${Date.now()}.json`,
        JSON.stringify(report, null, 2)
      );
      console.log("Report saved to JSON file");
    } catch (error) {
      console.error(`Failed to write report: ${error.message}`);
    }

    // Assert success rate is above 99.9% for valid benchmark
    try {
      assertEquals(
        (report.successfulRequests / report.totalRequests) >= 0.999,
        true,
        "Success rate below 99.9%"
      );
      assertEquals(report.p99LatencyMs < 200, true, "p99 latency above 200ms");
      console.log("All benchmark assertions passed");
    } catch (assertError) {
      console.error(`Benchmark assertions failed: ${assertError.message}`);
    }

    return report;
  }
}

// Run benchmark if this is the main module
if (import.meta.main) {
  try {
    const bench = new ConcurrentBenchmark();
    await bench.run();
    Deno.exit(0);
  } catch (error) {
    console.error(`Benchmark failed to run: ${error.message}`);
    Deno.exit(1);
  }
}

// Scheduled function to pre-warm checkout function 5 mins before flash sale
// Deploy with: supabase functions deploy prewarm-checkout --schedule "*/5 18 * * *" (runs at 6:05 PM daily)
import { serve } from "https://deno.land/std@0.207.0/http/server.ts";

serve(async (req) => {
  const checkoutUrl = "https://.functions.supabase.co/checkout";
  // Send 10 warmup requests to trigger instance creation
  await Promise.all(
    Array.from({ length: 10 }, () => fetch(checkoutUrl, { method: "OPTIONS" }))
  );
  return new Response("Checkout function pre-warmed", { status: 200 });
});

// Bad: Isolate-scoped mutable state (causes reuse issues)
let requestCount = 0; // This persists across requests in the same isolate!
serve(async (req) => {
  requestCount++;
  return new Response(`Request count: ${requestCount}`);
});

// Good: No isolate-scoped state, all state external
import { Redis } from "https://deno.land/x/redis@v0.32.0/mod.ts";
const redis = new Redis({ url: Deno.env.get("REDIS_URL")! });

serve(async (req) => {
  const currentCount = await redis.incr("request_count");
  return new Response(`Request count: ${currentCount}`);
});

// Use Supabase Management API to update autoscaler settings for a function
// Requires SUPABASE_ACCESS_TOKEN and PROJECT_REF env vars
import { assertEquals } from "https://deno.land/std@0.207.0/testing/asserts.ts";

const projectRef = Deno.env.get("PROJECT_REF")!;
const accessToken = Deno.env.get("SUPABASE_ACCESS_TOKEN")!;
const functionSlug = "checkout";

const response = await fetch(
  `https://api.supabase.com/v1/projects/${projectRef}/functions/${functionSlug}/autoscaler`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      concurrency_per_instance: 400,
      scale_up_cooldown_ms: 1000,
      scale_down_cooldown_ms: 60000,
    }),
  }
);

assertEquals(response.status, 200, "Failed to update autoscaler settings");
console.log("Autoscaler settings updated successfully");