Merge pull request #1206 from deco-cx/fix/sandbox-eager-warm-on-deploy

fix(daemon): robust sandbox cold-start (eager warm + fast-503 + optional warmup)

Author: nicacioliveira

blocks/loader.bench.ts

@@ -1,4 +1,8 @@
-import hash from "https://esm.sh/v135/object-hash@3.0.0";
+// `?no-dts` skips esm.sh's bundled type definitions. Upstream `@types/object-hash`
+// uses a CommonJS `export =` with no synthetic default, which makes Deno's
+// type-check fail with TS1192 ("no default export") on a fresh fetch. The types
+// aren't needed in this benchmark, so dropping them keeps CI deterministic.
+import hash from "https://esm.sh/v135/object-hash@3.0.0?no-dts";
 
 const props = {
   randomObject: {

daemon/main.ts

@@ -38,6 +38,8 @@ import { register, type TunnelConnection } from "./tunnel.ts";
 import {
   createWorker,
   resetWorkerState,
+  WARMUP_HEADER,
+  WARMUP_TOKEN,
   worker,
   type WorkerOptions,
 } from "./worker.ts";
@@ -604,6 +606,41 @@ if (SANDBOX_MODE) {
         branch,
       });
 
+      // Eagerly kick off deps init (git clone, build-cache download, manifest
+      // + blocks generation) as soon as the env is assigned, instead of
+      // waiting for the first HTTP request to trigger it lazily. On a freshly
+      // claimed sandbox this cold-start work can take tens of seconds; paying
+      // it inline on the first request risks exceeding the CDN origin timeout
+      // and surfacing to the user as a 504 (the client abort is logged as a
+      // 499 at the ingress). ensureStarted() is idempotent — the AI-task path
+      // below still awaits gitReady without re-triggering init.
+      currentSite.ensureStarted();
+
+      // Optional deep warmup: once the repo is cloned, issue a single internal
+      // request to the site root so the dev server JIT-compiles and renders the
+      // entry route before the first real user request arrives — otherwise that
+      // compile + render is paid inline on the user's first hit. Off by default
+      // because it triggers one synthetic homepage render (and any server-side
+      // analytics it fires); the x-deco-warmup header (carrying the per-process
+      // token) marks it as our internal warmup so it bypasses the fast-503 gate
+      // and the site can opt out of side effects. Enable with
+      // DECO_SANDBOX_WARMUP=true.
+      if (Deno.env.get("DECO_SANDBOX_WARMUP") === "true") {
+        const { app: siteApp, gitReady } = currentSite;
+        gitReady
+          .then(() =>
+            siteApp.fetch(
+              new Request("http://localhost/", {
+                headers: { [WARMUP_HEADER]: WARMUP_TOKEN },
+              }),
+            )
+          )
+          .then(() => console.log("[sandbox] warmup request completed"))
+          .catch((err) =>
+            console.error("[sandbox] warmup request failed:", err)
+          );
+      }
+
       // Always create AI handlers — OAuth can be used when no API key is set
       aiHandlers = createAIHandlers({
         cwd: Deno.cwd(),
@@ -630,9 +667,6 @@ if (SANDBOX_MODE) {
           Boolean(envs?.ANTHROPIC_PROXY_URL);
         if (hasApiKey) {
           const handlers = aiHandlers;
-          // Eagerly trigger deps init (git clone, etc.) so the task doesn't wait
-          // for the first HTTP request to arrive
-          currentSite.ensureStarted();
           // Wait for git clone to finish before starting the AI task,
           // since the task needs a valid repo (git rev-parse HEAD, etc.)
           currentSite.gitReady.then(async () => {

daemon/worker.ts

@@ -1,7 +1,23 @@
 import { Hono } from "@hono/hono";
 import { broadcast } from "./sse/channel.ts";
+import { SANDBOX_MODE } from "./daemon.ts";
+import { delay } from "../utils/async.ts";
 import { DenoRun } from "./workers/denoRun.ts";
 
+// How long a request waits for a cold dev server to come up before we stop
+// holding the connection open and reply 503 (SANDBOX_MODE only). Kept well
+// under the CDN origin timeout so the env ingress can bounce to the activator
+// and retry, instead of the request hanging until the CDN returns a 504.
+const SANDBOX_READY_GATE_MS = 5_000;
+
+// Header + per-process token used by the daemon's own internal warmup request
+// to bypass the fast-503 gate (it must block until the worker is ready so it
+// can actually render the entry route). The token is random per process so a
+// forged `x-deco-warmup` header on public traffic can't match and is treated
+// as a normal request.
+export const WARMUP_HEADER = "x-deco-warmup";
+export const WARMUP_TOKEN: string = crypto.randomUUID();
+
 export interface WorkerOptions {
   persist: () => void;
   command: Deno.Command;
@@ -97,7 +113,47 @@ export const createWorker = (optionsProvider: WorkerOptionsProvider) => {
   // ensure isolate is up and running
   app.use("/*", async (c, next) => {
     try {
-      await worker();
+      // Warmup requests (and normal, non-sandbox mode) keep the original
+      // blocking behavior: wait for the worker to be fully ready, then proxy.
+      // This is what lets the warmup request actually JIT-compile and render
+      // the entry route — a fast-503 gate would skip the render entirely.
+      const isWarmup = c.req.header(WARMUP_HEADER) === WARMUP_TOKEN;
+      if (SANDBOX_MODE && !isWarmup) {
+        // worker() boots the dev server (idempotent) and resolves once it is
+        // listening; it rejects if the boot fails (missing dev.ts, crash, ...).
+        // On a cold sandbox the boot can take a while, so rather than hold the
+        // request open the whole time — which lets the CDN time out as a 504 —
+        // we race it against a short gate:
+        //   - still booting at the gate  -> 503 (retryable): the env ingress
+        //     (error_page 502 503 -> @admin) bounces to the activator and the
+        //     boot keeps running in the background, so the retry lands warm.
+        //   - boot rejected              -> 424 (non-retryable): a real failure
+        //     that won't fix itself, so we don't loop the activator forever.
+        // Mapping the rejection inline (not throwing) keeps the loser of the
+        // race from surfacing as an unhandled rejection once we've replied.
+        const boot = worker().then(
+          () => "ready" as const,
+          (err: unknown) => ({ err }),
+        );
+        const outcome = await Promise.race([
+          boot,
+          delay(SANDBOX_READY_GATE_MS).then(() => "timeout" as const),
+        ]);
+        if (outcome === "timeout") {
+          c.res = new Response("Sandbox environment is starting", {
+            status: 503,
+            headers: { "retry-after": "2" },
+          });
+          return;
+        }
+        if (typeof outcome === "object") {
+          console.error(outcome.err);
+          c.res = new Response(`Error while starting worker`, { status: 424 });
+          return;
+        }
+      } else {
+        await worker();
+      }
       await next();
     } catch (error) {
       console.error(error);