alepha 0.18.2 → 0.18.3

package/src/cli/platform/services/DockerComposeGenerator.ts

@@ -82,6 +82,9 @@ export class DockerComposeGenerator {
         this.anyAppHas(options.apps, "hasQueue")) &&
       !options.envVars.REDIS_URL;
 
+    const needsRustFS =
+      this.anyAppHas(options.apps, "hasBucket") && !options.envVars.S3_ENDPOINT;
+
     if (needsPostgres) {
       const dbName = `${options.project}_${options.env}`.replace(/-/g, "_");
       services.push(
@@ -110,6 +113,22 @@ export class DockerComposeGenerator {
       );
     }
 
+    if (needsRustFS) {
+      services.push(
+        [
+          "  rustfs:",
+          "    image: rustfs/rustfs:latest",
+          '    ports: ["9000:9000"]',
+          "    environment:",
+          "      RUSTFS_ROOT_USER: alepha",
+          "      RUSTFS_ROOT_PASSWORD: alepha",
+          "    volumes:",
+          "      - rustfs_data:/data",
+        ].join("\n"),
+      );
+      volumes.push("  rustfs_data:");
+    }
+
     if (services.length === 0) {
       return null;
     }
@@ -197,6 +216,9 @@ export class DockerComposeGenerator {
       ) {
         deps.push("      - redis");
       }
+      if (app.resources.hasBucket && !options.envVars.S3_ENDPOINT) {
+        deps.push("      - rustfs");
+      }
       if (deps.length > 0) {
         appLines.push("    depends_on:", ...deps);
       }
@@ -244,6 +266,28 @@ export class DockerComposeGenerator {
       services.push(redisLines.join("\n"));
     }
 
+    // RustFS (S3-compatible object storage)
+    const needsRustFS =
+      this.anyAppHas(options.apps, "hasBucket") && !options.envVars.S3_ENDPOINT;
+
+    if (needsRustFS) {
+      const rustfsLines = [
+        "  rustfs:",
+        "    image: rustfs/rustfs:latest",
+        "    environment:",
+        "      RUSTFS_ROOT_USER: alepha",
+        "      RUSTFS_ROOT_PASSWORD: ${S3_SECRET_KEY}",
+        "    volumes:",
+        "      - rustfs_data:/data",
+      ];
+      if (hasDomain) {
+        rustfsLines.push("    networks:", "      - internal");
+      }
+      rustfsLines.push("    restart: unless-stopped");
+      services.push(rustfsLines.join("\n"));
+      volumes.push("  rustfs_data:");
+    }
+
     const parts = [
       "# Auto-generated by Alepha. Do not edit.",
       "services:",
@@ -302,7 +346,8 @@ export class DockerComposeGenerator {
     return (
       (this.anyAppHas(apps, "hasDatabase") && !envVars.DATABASE_URL) ||
       ((this.anyAppHas(apps, "hasKV") || this.anyAppHas(apps, "hasQueue")) &&
-        !envVars.REDIS_URL)
+        !envVars.REDIS_URL) ||
+      (this.anyAppHas(apps, "hasBucket") && !envVars.S3_ENDPOINT)
     );
   }
 }

package/src/cli/platform/services/SecretFilterService.spec.ts

@@ -0,0 +1,111 @@
+import { Alepha } from "alepha";
+import { describe, test } from "vitest";
+import { SecretFilterService } from "./SecretFilterService.ts";
+
+describe("SecretFilterService", () => {
+  const createFilter = () => {
+    const alepha = Alepha.create();
+    return alepha.inject(SecretFilterService);
+  };
+
+  test("keeps normal secret keys", ({ expect }) => {
+    const filter = createFilter();
+    const result = filter.filter({
+      API_KEY: "abc123",
+      REDIS_URL: "redis://localhost",
+    });
+
+    expect(result).toEqual({
+      API_KEY: "abc123",
+      REDIS_URL: "redis://localhost",
+    });
+  });
+
+  test("keeps DATABASE_URL and POSTGRES_SCHEMA", ({ expect }) => {
+    const filter = createFilter();
+    const result = filter.filter({
+      DATABASE_URL: "postgres://localhost/db",
+      POSTGRES_SCHEMA: "public",
+    });
+
+    expect(result).toEqual({
+      DATABASE_URL: "postgres://localhost/db",
+      POSTGRES_SCHEMA: "public",
+    });
+  });
+
+  test("excludes NODE_ENV", ({ expect }) => {
+    const filter = createFilter();
+    const result = filter.filter({
+      NODE_ENV: "production",
+      API_KEY: "abc123",
+    });
+
+    expect(result).toEqual({ API_KEY: "abc123" });
+  });
+
+  test("excludes VITE_ prefixed keys", ({ expect }) => {
+    const filter = createFilter();
+    const result = filter.filter({
+      VITE_APP_TITLE: "My App",
+      VITE_PUBLIC_KEY: "pk_123",
+      API_KEY: "abc123",
+    });
+
+    expect(result).toEqual({ API_KEY: "abc123" });
+  });
+
+  test("excludes empty values", ({ expect }) => {
+    const filter = createFilter();
+    const result = filter.filter({
+      API_KEY: "abc123",
+      EMPTY_VAR: "",
+    });
+
+    expect(result).toEqual({ API_KEY: "abc123" });
+  });
+
+  test("returns empty record when all filtered", ({ expect }) => {
+    const filter = createFilter();
+    const result = filter.filter({
+      NODE_ENV: "production",
+      VITE_KEY: "value",
+      EMPTY: "",
+    });
+
+    expect(result).toEqual({});
+  });
+
+  describe("toRemoteName", () => {
+    test("prefixes GITHUB_ keys with APP_", ({ expect }) => {
+      const filter = createFilter();
+      expect(filter.toRemoteName("GITHUB_CLIENT_ID")).toBe(
+        "APP_GITHUB_CLIENT_ID",
+      );
+      expect(filter.toRemoteName("GITHUB_CLIENT_SECRET")).toBe(
+        "APP_GITHUB_CLIENT_SECRET",
+      );
+    });
+
+    test("leaves non-GITHUB_ keys unchanged", ({ expect }) => {
+      const filter = createFilter();
+      expect(filter.toRemoteName("DATABASE_URL")).toBe("DATABASE_URL");
+      expect(filter.toRemoteName("API_KEY")).toBe("API_KEY");
+    });
+  });
+
+  describe("toLocalName", () => {
+    test("strips APP_ prefix from APP_GITHUB_ keys", ({ expect }) => {
+      const filter = createFilter();
+      expect(filter.toLocalName("APP_GITHUB_CLIENT_ID")).toBe(
+        "GITHUB_CLIENT_ID",
+      );
+    });
+
+    test("leaves non-APP_GITHUB_ keys unchanged", ({ expect }) => {
+      const filter = createFilter();
+      expect(filter.toLocalName("DATABASE_URL")).toBe("DATABASE_URL");
+      expect(filter.toLocalName("APP_SECRET")).toBe("APP_SECRET");
+    });
+  });
+});

package/src/cli/platform/services/SecretFilterService.ts

@@ -0,0 +1,54 @@
+/**
+ * Filters environment variables for secret store syncing.
+ *
+ * Excludes platform-managed vars (NODE_ENV), build-time vars (VITE_*),
+ * and empty values. Keeps everything else — including DATABASE_URL
+ * and POSTGRES_SCHEMA which GitHub Actions needs.
+ *
+ * Also handles renaming GITHUB_* keys since GitHub Actions rejects
+ * secret names starting with GITHUB_.
+ */
+export class SecretFilterService {
+  protected static readonly EXCLUDED_KEYS = new Set(["NODE_ENV"]);
+  protected static readonly GITHUB_PREFIX = "GITHUB_";
+  protected static readonly REMOTE_PREFIX = "APP_GITHUB_";
+
+  /**
+   * Return only the entries that should be pushed to a secret store.
+   */
+  public filter(envVars: Record<string, string>): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(envVars)) {
+      if (!value) continue;
+      if (SecretFilterService.EXCLUDED_KEYS.has(key)) continue;
+      if (key.startsWith("VITE_")) continue;
+      result[key] = value;
+    }
+
+    return result;
+  }
+
+  /**
+   * Convert a local env key to a remote secret name.
+   *
+   * GITHUB_* keys are prefixed with APP_ since GitHub Actions rejects
+   * secret names starting with GITHUB_.
+   */
+  public toRemoteName(key: string): string {
+    if (key.startsWith(SecretFilterService.GITHUB_PREFIX)) {
+      return `${SecretFilterService.REMOTE_PREFIX}${key.slice(SecretFilterService.GITHUB_PREFIX.length)}`;
+    }
+    return key;
+  }
+
+  /**
+   * Convert a remote secret name back to the local env key.
+   */
+  public toLocalName(remoteName: string): string {
+    if (remoteName.startsWith(SecretFilterService.REMOTE_PREFIX)) {
+      return `${SecretFilterService.GITHUB_PREFIX}${remoteName.slice(SecretFilterService.REMOTE_PREFIX.length)}`;
+    }
+    return remoteName;
+  }
+}

package/src/core/Alepha.ts

@@ -236,9 +236,22 @@ export class Alepha {
   protected ready = false;
 
   /**
-   * A promise that resolves when the App has started.
+   * In-flight startup promise returned by boot().
+   *
+   * Concurrent callers of start() share this same promise. Cleared on
+   * success, failure, or stale-detection.
+   */
+  protected startPromise?: Promise<this>;
+
+  /**
+   * Timestamp (performance.now) when the current boot() began.
+   *
+   * In serverless environments (e.g. Cloudflare Workers), the runtime can
+   * kill an invocation mid-startup without running cleanup. The global
+   * Alepha instance persists, leaving startPromise as a never-settling
+   * promise. We detect this by comparing elapsed time against STARTUP_TIMEOUT.
    */
-  protected starting?: PromiseWithResolvers<this>;
+  protected startedAt = 0;
 
   /**
    * During the instantiation process, we keep a list of pending instantiations.
@@ -479,6 +492,17 @@ export class Alepha {
 
   // -------------------------------------------------------------------------------------------------------------------
 
+  /**
+   * Max time (ms) a boot() is allowed to run before being considered stale.
+   *
+   * In serverless runtimes (Cloudflare Workers, etc.) an invocation can be
+   * killed mid-startup. The global Alepha instance survives, but
+   * `startPromise` becomes a zombie that never settles.
+   * Any new invocation that sees an older-than-STARTUP_TIMEOUT promise
+   * discards it and boots fresh.
+   */
+  protected static readonly STARTUP_TIMEOUT = 30_000;
+
   /**
    * Starts the App.
    *
@@ -487,6 +511,10 @@ export class Alepha {
    * - Run "start" hook for all services. Providers will connect/listen/...
    * - Run "ready" hook for all services. This is the point where the App is ready to serve requests.
    *
+   * Concurrent callers share the same boot promise. If a previous boot was
+   * abandoned (serverless invocation killed), the stale promise is detected
+   * and a fresh boot is triggered.
+   *
    * @return A promise that resolves when the App has started.
    */
   public async start(): Promise<this> {
@@ -495,19 +523,36 @@ export class Alepha {
       return this;
     }
 
-    // make sure that start is called only once
-    if (this.starting) {
-      this.log?.warn("App is already starting, waiting for it to finish...");
-      return this.starting.promise;
+    if (this.startPromise) {
+      const elapsed = performance.now() - this.startedAt;
+      if (elapsed > Alepha.STARTUP_TIMEOUT) {
+        this.log?.warn(
+          `Previous start attempt is stale (${Math.round(elapsed)}ms ago), resetting...`,
+        );
+        this.resetStartup();
+      } else {
+        this.log?.warn("App is already starting, waiting for it to finish...");
+        return this.startPromise;
+      }
     }
 
-    this.starting = Promise.withResolvers();
-
-    try {
-      const now = performance.now();
+    this.startedAt = performance.now();
+    this.startPromise = this.boot();
+    return this.startPromise;
+  }
 
-      this.log?.info("Starting App...");
+  /**
+   * Perform the actual startup sequence.
+   *
+   * Separated from start() so that start() remains a thin state-machine
+   * and boot() owns the real work. The promise returned here is stored as
+   * `startPromise` and shared with concurrent callers.
+   */
+  protected async boot(): Promise<this> {
+    const now = performance.now();
+    this.log?.info("Starting App...");
 
+    try {
       for (const [key] of this.substitutions.entries()) {
         this.inject(key);
       }
@@ -544,17 +589,27 @@ export class Alepha {
       );
 
       this.ready = true;
+      return this;
     } catch (error) {
-      this.starting.reject(error);
-      const promise = this.starting.promise;
-      this.starting = undefined;
-      return promise;
+      this.resetStartup();
+      throw error;
     }
+  }
 
-    this.starting.resolve(this);
-    this.starting = undefined;
-
-    return this;
+  /**
+   * Reset startup state so that a fresh boot() can be attempted.
+   *
+   * Called when:
+   * - boot() fails (error during configure/start/ready hooks)
+   * - a stale startPromise is detected (serverless invocation was killed)
+   */
+  protected resetStartup(): void {
+    this.startPromise = undefined;
+    this.startedAt = 0;
+    this.locked = false;
+    this.configured = false;
+    this.started = false;
+    this.ready = false;
   }
 
   /**
@@ -580,6 +635,8 @@ export class Alepha {
 
     this.started = false;
     this.ready = false;
+    this.startPromise = undefined;
+    this.startedAt = 0;
   }
 
   /**
@@ -893,13 +950,20 @@ export class Alepha {
 
     const config = this.codec.validate(schema, this.env) as Record<string, any>;
 
-    for (const key in config) {
-      if (typeof config[key] === "string") {
+    // Resolve $KEY references. Multiple passes handle transitive references
+    // where a replacement introduces a new $KEY that was already checked
+    // (e.g. C=$B, B=$A, A=value — single pass leaves C as "$A").
+    let changed = true;
+    for (let pass = 0; changed && pass < 10; pass++) {
+      changed = false;
+      for (const key in config) {
+        if (typeof config[key] !== "string") continue;
         for (const env in config) {
-          config[key] = (config[key] as string).replaceAll(
-            `$${env}`,
-            String(config[env] ?? ""),
-          );
+          const before = config[key] as string;
+          config[key] = before.replaceAll(`$${env}`, String(config[env] ?? ""));
+          if (config[key] !== before) {
+            changed = true;
+          }
         }
       }
     }
@@ -1160,6 +1224,11 @@ export interface Env {
    * Optional root module name.
    */
   MODULE_NAME?: string;
+
+  /**
+   * The secret key used for signing JWTs, encrypting cookies, and other security features.
+   */
+  APP_SECRET?: string;
 }
 
 // ---------------------------------------------------------------------------------------------------------------------

package/src/core/__tests__/Alepha-parseEnv.spec.ts

@@ -84,6 +84,26 @@ describe("Alepha#parseEnv", () => {
     expect(env.URL).toBe("$host");
   });
 
+  it("should resolve transitive $KEY references", async () => {
+    const schema = t.object({
+      A: t.optional(t.text()),
+      B: t.optional(t.text()),
+      C: t.optional(t.text()),
+    });
+
+    const alepha = Alepha.create({
+      env: {
+        A: "value",
+        B: "$A",
+        C: "$B",
+      },
+    });
+
+    const env = alepha.parseEnv(schema);
+    expect(env.B).toBe("value");
+    expect(env.C).toBe("value");
+  });
+
   it("should return cached result for same schema", async () => {
     const schema = t.object({
       FOO: t.optional(t.text()),

package/src/core/primitives/$memoize.ts

@@ -1,21 +1,5 @@
 import { createMiddleware, type Middleware } from "alepha";
 
-export interface MemoizeOptions {
-  /**
-   * Maximum number of entries to keep in the cache.
-   * When exceeded, the oldest entry is evicted (FIFO).
-   *
-   * @default 1000
-   */
-  max?: number;
-
-  /**
-   * Custom key function. Receives the handler's arguments.
-   * By default, `JSON.stringify(args)` is used.
-   */
-  key?: (...args: any[]) => string;
-}
-
 /**
  * Lightweight in-process memoization middleware.
  *
@@ -48,20 +32,48 @@ export const $memoize = (options?: MemoizeOptions): Middleware => {
           return store.get(key);
         }
 
-        const result = await next(...args);
+        // Store the promise immediately to deduplicate concurrent calls
+        // for the same key (thundering herd prevention).
+        const promise = next(...args);
+        store.set(key, promise);
 
-        // Evict oldest if at capacity
-        if (store.size >= maxSize) {
-          const firstKey = store.keys().next().value;
-          if (firstKey !== undefined) {
-            store.delete(firstKey);
-          }
-        }
+        try {
+          const result = await promise;
 
-        store.set(key, result);
+          // Replace the promise with the resolved value
+          store.set(key, result);
 
-        return result;
+          // Evict oldest if at capacity
+          if (store.size > maxSize) {
+            const firstKey = store.keys().next().value;
+            if (firstKey !== undefined) {
+              store.delete(firstKey);
+            }
+          }
+
+          return result;
+        } catch (error) {
+          // Don't cache failed results
+          store.delete(key);
+          throw error;
+        }
       };
     },
   });
 };
+
+export interface MemoizeOptions {
+  /**
+   * Maximum number of entries to keep in the cache.
+   * When exceeded, the oldest entry is evicted (FIFO).
+   *
+   * @default 1000
+   */
+  max?: number;
+
+  /**
+   * Custom key function. Receives the handler's arguments.
+   * By default, `JSON.stringify(args)` is used.
+   */
+  key?: (...args: any[]) => string;
+}

package/src/core/providers/AlsProvider.ts

@@ -27,6 +27,8 @@ export class AlsProvider {
 
     const parent = this.als.getStore() ?? undefined;
 
+    // Intentional mutation: set defaults on the input object to avoid
+    // allocating an intermediate copy. Callers always pass a fresh literal.
     data.registry ??= new Map();
     data.context ??= this.createContextId();
 

package/src/core/providers/EventManager.ts

@@ -238,6 +238,10 @@ export class EventManager {
     }
 
     const catchErrors = options.catch ?? false;
+
+    // Logger is captured at compile time. Since compilation happens after
+    // start() (on first emit), the logger is already fully configured and
+    // won't change afterwards — this is safe.
     const log = this.log;
 
     // Once the first async hook is encountered, all remaining hooks

package/src/core/providers/KeylessJsonSchemaCodec.spec.ts

@@ -836,12 +836,9 @@ describe("KeylessJsonSchemaCodec", () => {
       const alepha = Alepha.create();
       const codec = alepha.inject(KeylessJsonSchemaCodec);
 
-      // Configure all options
+      // Configure options
       codec.configure({
         useFunctionCompilation: false,
-        maxArrayLength: 100,
-        maxStringLength: 1000,
-        maxDepth: 10,
       });
 
       // Test that configuration works by encoding/decoding