alepha 0.22.0 → 0.24.0

package/src/server/cookies/__tests__/AtomCookieBinding.spec.ts

@@ -0,0 +1,80 @@
+import { $atom, $inject, Alepha, z } from "alepha";
+import { $action, AlephaServer } from "alepha/server";
+import { describe, expect, it } from "vitest";
+import { $cookie, AlephaServerCookies } from "../index.ts";
+
+/**
+ * Regression coverage for the cross-request contamination found in
+ * `StateManager.register()`.
+ *
+ * `$cookie({ key: atom.key })` writes the raw cookie into the request's ALS
+ * layer during `server:onRequest`, BEFORE anything ever reads the atom. So on
+ * a request that carries the cookie, the atom's very first registration
+ * happens inside a fork that already holds its key — and the app-level store
+ * never received the declared default. Every later, cookie-LESS request then
+ * resolved `undefined` (no fork value, no app value) instead of the default:
+ * one user's cookied request permanently defined what every cookie-less user
+ * saw.
+ *
+ * The atom is deliberately NOT declared with `$state(...)` here: it must
+ * register lazily, from inside the request, which is exactly what the
+ * framework's own `uiAtom` does during SSR.
+ */
+const themeAtom = $atom({
+  name: "test.cookie.binding.theme",
+  schema: z.object({ theme: z.string() }),
+  default: { theme: "light" },
+});
+
+class CookieBoundApp {
+  protected readonly alepha = $inject(Alepha);
+
+  theme = $cookie({
+    key: themeAtom.key,
+    name: "test-cookie-binding-theme",
+    schema: z.object({ theme: z.string() }),
+  });
+
+  read = $action({
+    schema: {
+      response: z.object({ theme: z.string() }),
+    },
+    // Lazy: the atom is first registered here, inside the request.
+    handler: () => ({ theme: this.alepha.store.get(themeAtom).theme }),
+  });
+}
+
+const alepha = Alepha.create().with(AlephaServer).with(AlephaServerCookies);
+const app = alepha.inject(CookieBoundApp);
+
+const cookieHeader = `test-cookie-binding-theme=${encodeURIComponent(
+  JSON.stringify({ theme: "dark" }),
+)}`;
+
+describe("atom bound to a $cookie, first registered inside a request", () => {
+  it("serves the default to a cookie-less request that follows a cookied one", async () => {
+    // Request 1 — WITH the cookie. This is the request that registers the
+    // atom, from inside a fork that already carries its key.
+    const first = await app.read.fetch(
+      {},
+      {
+        key: "binding-with-cookie",
+        request: { headers: { cookie: cookieHeader } },
+      },
+    );
+    expect(first.data.theme).toBe("dark");
+
+    // Request 2 — WITHOUT any cookie. Before the fix this resolved
+    // `undefined` (the app store never got the default), which then blew up
+    // as a TypeError on any direct `.theme` read.
+    const second = await app.read.fetch(
+      {},
+      { key: "binding-no-cookie", request: { headers: { cookie: "" } } },
+    );
+    expect(second.data.theme).toBe("light");
+
+    // The app-level store holds the declared DEFAULT — not `undefined`, and
+    // not the first request's cookie value.
+    expect(alepha.store.get(themeAtom, "app")).toEqual({ theme: "light" });
+  });
+});

package/src/server/cookies/__tests__/AtomCookiePersistence.browser.spec.ts

@@ -0,0 +1,169 @@
+import { $atom, Alepha, z } from "alepha";
+import { beforeEach, describe, expect, it } from "vitest";
+import { AtomCookiePersistence } from "../providers/AtomCookiePersistence.browser.ts";
+
+const schema = z.object({ theme: z.string() });
+
+/**
+ * Clears every cookie the previous test may have left behind. jsdom's
+ * `document.cookie` jar persists across tests within the same suite run.
+ */
+const clearAllCookies = (): void => {
+  for (const part of document.cookie.split(";")) {
+    const name = part.split("=")[0]?.trim();
+    if (name) {
+      document.cookie = `${name}=; Path=/; Max-Age=0`;
+    }
+  }
+};
+
+/**
+ * Read a single cookie's raw (still encoded) value directly off
+ * `document.cookie`, bypassing the adapter under test.
+ */
+const readRawCookie = (name: string): string | undefined => {
+  const match = document.cookie
+    .split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${name}=`));
+  return match ? match.slice(name.length + 1) : undefined;
+};
+
+describe("AtomCookiePersistence (browser)", () => {
+  beforeEach(() => {
+    clearAllCookies();
+  });
+
+  it("hydrates from an existing document.cookie on register", () => {
+    document.cookie = `test.cookie.browser.read=${encodeURIComponent(
+      JSON.stringify({ theme: "dark" }),
+    )}; Path=/`;
+
+    const prefs = $atom({
+      name: "test.cookie.browser.read",
+      schema,
+      default: { theme: "light" },
+      persist: "cookie",
+    });
+
+    const alepha = Alepha.create();
+    alepha.inject(AtomCookiePersistence);
+
+    expect(alepha.store.get(prefs)).toEqual({ theme: "dark" });
+  });
+
+  it("reads and writes an atom that registered BEFORE the adapter existed", async () => {
+    // The `$module({ atoms, imports, services })` shape: `atoms[]` register
+    // before `services[]` are injected, so the adapter never sees the
+    // atom's one-shot `state:register` event. Discovering atoms from the
+    // state manager's registry (instead of from that event) is what makes
+    // this work.
+    document.cookie = `test.cookie.browser.module=${encodeURIComponent(
+      JSON.stringify({ theme: "dark" }),
+    )}; Path=/`;
+
+    const prefs = $atom({
+      name: "test.cookie.browser.module",
+      schema,
+      default: { theme: "light" },
+      persist: "cookie",
+    });
+
+    const alepha = Alepha.create();
+    alepha.store.register(prefs);
+    alepha.inject(AtomCookiePersistence);
+    await alepha.start();
+
+    expect(alepha.store.get(prefs)).toEqual({ theme: "dark" });
+
+    alepha.store.set(prefs, { theme: "solarized" });
+    const raw = readRawCookie("test.cookie.browser.module");
+    expect(raw).toBeDefined();
+    expect(JSON.parse(decodeURIComponent(raw!))).toEqual({
+      theme: "solarized",
+    });
+  });
+
+  it("falls back to the default when there is no cookie", () => {
+    const prefs = $atom({
+      name: "test.cookie.browser.none",
+      schema,
+      default: { theme: "light" },
+      persist: "cookie",
+    });
+
+    const alepha = Alepha.create();
+    alepha.inject(AtomCookiePersistence);
+
+    expect(alepha.store.get(prefs)).toEqual({ theme: "light" });
+  });
+
+  it("writes document.cookie back on mutation, using the bare (unprefixed) atom key", () => {
+    const prefs = $atom({
+      name: "test.cookie.browser.write",
+      schema,
+      default: { theme: "light" },
+      persist: "cookie",
+    });
+
+    const alepha = Alepha.create();
+    alepha.inject(AtomCookiePersistence);
+    alepha.store.set(prefs, { theme: "dark" });
+
+    const raw = readRawCookie("test.cookie.browser.write");
+    expect(raw).toBeDefined();
+    expect(JSON.parse(decodeURIComponent(raw!))).toEqual({ theme: "dark" });
+
+    // No APP_NAME namespace: the browser cannot see APP_NAME (see this
+    // class's JSDoc), and the server side (AtomCookiePersistence.ts)
+    // matches by passing `prefix: false` for atom cookies specifically —
+    // see AtomCookiePersistence.spec.ts's "cookie-name symmetry with
+    // APP_NAME set" suite for the server-side half of this proof.
+    expect(readRawCookie("rdm.test.cookie.browser.write")).toBeUndefined();
+  });
+
+  it("clears the cookie instead of writing the literal 'undefined' when the atom's value is cleared", () => {
+    const prefs = $atom({
+      name: "test.cookie.browser.delete",
+      schema,
+      default: { theme: "light" },
+      persist: "cookie",
+    });
+
+    const alepha = Alepha.create();
+    alepha.inject(AtomCookiePersistence);
+    alepha.store.set(prefs, { theme: "dark" });
+    expect(readRawCookie("test.cookie.browser.delete")).toBeDefined();
+
+    // Bypass the Atom-typed overload deliberately: `set(key, undefined)` is
+    // exactly what `StateManager.del()` does internally, and is the only
+    // way to drive the atom back to "no value", which is what triggers the
+    // `value === undefined` branch under test.
+    alepha.store.set(prefs.key as any, undefined);
+
+    // Must be gone entirely — never the literal string "undefined", which
+    // would make the next register()'s `JSON.parse("undefined")` throw.
+    expect(readRawCookie("test.cookie.browser.delete")).toBeUndefined();
+  });
+
+  it("clears a corrupted cookie instead of leaving it to throw on every future read", () => {
+    document.cookie = "test.cookie.browser.corrupt=not-json-at-all; Path=/";
+
+    const prefs = $atom({
+      name: "test.cookie.browser.corrupt",
+      schema,
+      default: { theme: "light" },
+      persist: "cookie",
+    });
+
+    const alepha = Alepha.create();
+    alepha.inject(AtomCookiePersistence);
+
+    // Corrupted value is discarded; the default is used instead of throwing.
+    expect(alepha.store.get(prefs)).toEqual({ theme: "light" });
+
+    // And the corrupted cookie itself is cleared, not left behind to keep
+    // failing on every future page load.
+    expect(readRawCookie("test.cookie.browser.corrupt")).toBeUndefined();
+  });
+});

package/src/server/cookies/__tests__/AtomCookiePersistence.spec.ts

@@ -0,0 +1,294 @@
+import { $atom, $inject, $module, $state, Alepha, z } from "alepha";
+import { $action, AlephaServer } from "alepha/server";
+import { describe, expect, it } from "vitest";
+import { AlephaServerCookies } from "../index.ts";
+
+const settingsAtom = $atom({
+  name: "test.cookie.settings",
+  schema: z.object({ theme: z.string() }),
+  default: { theme: "light" },
+  persist: "cookie",
+});
+
+class CookieAtomApp {
+  protected readonly alepha = $inject(Alepha);
+
+  /**
+   * Registers the atom at configure time so the adapter tracks it before
+   * the first request.
+   */
+  settings = $state(settingsAtom);
+
+  read = $action({
+    schema: {
+      response: z.object({ theme: z.string() }),
+    },
+    handler: () => ({ theme: this.settings.theme }),
+  });
+
+  update = $action({
+    schema: {
+      body: z.object({ theme: z.string() }),
+      response: z.object({ ok: z.boolean() }),
+    },
+    handler: ({ body }) => {
+      this.alepha.store.set(settingsAtom, { theme: body.theme });
+      return { ok: true };
+    },
+  });
+}
+
+const alepha = Alepha.create().with(AlephaServer).with(AlephaServerCookies);
+
+const app = alepha.inject(CookieAtomApp);
+
+describe("AtomCookiePersistence", () => {
+  it("writes a Set-Cookie when a persisted atom mutates during a request", async () => {
+    const response = await app.update.fetch({ body: { theme: "dark" } });
+    const setCookie = response.raw?.headers.get("set-cookie");
+
+    expect(setCookie).toBeDefined();
+    const value = JSON.parse(
+      decodeURIComponent(
+        setCookie!.match(/test\.cookie\.settings=([^;]*)/)![1],
+      ),
+    );
+    expect(value).toEqual({ theme: "dark" });
+  });
+
+  it("seeds request-scoped state from the incoming cookie", async () => {
+    const cookieHeader = `test.cookie.settings=${encodeURIComponent(
+      JSON.stringify({ theme: "dark" }),
+    )}`;
+
+    const response = await app.read.fetch(
+      {},
+      { request: { headers: { cookie: cookieHeader } } },
+    );
+
+    expect(response.data.theme).toBe("dark");
+  });
+
+  it("falls back to the default without a cookie", async () => {
+    const response = await app.read.fetch(
+      {},
+      { request: { headers: { cookie: "" } } },
+    );
+
+    expect(response.data.theme).toBe("light");
+  });
+});
+
+describe("registration order: atoms declared on a $module, before the adapter exists", () => {
+  // The documented usage shape — and the one that used to make
+  // `persist: "cookie"` a silent no-op in BOTH directions.
+  //
+  // `$module.register()` registers `options.atoms` FIRST, then wires
+  // `imports[]`, then injects `services[]`. So by the time
+  // `AtomCookiePersistence` is instantiated (via the `AlephaServerCookies`
+  // import), the atom has already registered and its one-shot
+  // `state:register` event has already been emitted and dropped —
+  // `EventManager` has no replay buffer. An adapter that discovered atoms
+  // from that event kept an empty map forever: no cookie read on request, no
+  // Set-Cookie on mutation, no warning.
+  //
+  // A test that injects the adapter before touching the atom proves nothing;
+  // it just reproduces the fragile ordering that happened to work.
+  const modulePrefs = $atom({
+    name: "test.cookie.module.prefs",
+    schema: z.object({ theme: z.string() }),
+    default: { theme: "light" },
+    persist: "cookie",
+  });
+
+  class ModuleCookieApp {
+    protected readonly alepha = $inject(Alepha);
+
+    read = $action({
+      schema: {
+        response: z.object({ theme: z.string() }),
+      },
+      handler: () => ({ theme: this.alepha.store.get(modulePrefs).theme }),
+    });
+
+    update = $action({
+      schema: {
+        body: z.object({ theme: z.string() }),
+        response: z.object({ ok: z.boolean() }),
+      },
+      handler: ({ body }) => {
+        this.alepha.store.set(modulePrefs, { theme: body.theme });
+        return { ok: true };
+      },
+    });
+  }
+
+  const CookieAtomModule = $module({
+    name: "test.cookie.module",
+    atoms: [modulePrefs],
+    imports: [AlephaServerCookies],
+    services: [ModuleCookieApp],
+  });
+
+  const moduleAlepha = Alepha.create().with(CookieAtomModule);
+  const moduleApp = moduleAlepha.inject(ModuleCookieApp);
+
+  it("seeds request state from the incoming cookie", async () => {
+    const cookieHeader = `test.cookie.module.prefs=${encodeURIComponent(
+      JSON.stringify({ theme: "dark" }),
+    )}`;
+
+    const response = await moduleApp.read.fetch(
+      {},
+      {
+        key: "module-read",
+        request: { headers: { cookie: cookieHeader } },
+      },
+    );
+
+    expect(response.data.theme).toBe("dark");
+  });
+
+  it("emits a Set-Cookie when the atom mutates", async () => {
+    const response = await moduleApp.update.fetch({ body: { theme: "dark" } });
+    const setCookie = response.raw?.headers.get("set-cookie");
+
+    expect(setCookie).toBeDefined();
+    expect(setCookie).not.toBeNull();
+    const value = JSON.parse(
+      decodeURIComponent(
+        setCookie!.match(/test\.cookie\.module\.prefs=([^;]*)/)![1],
+      ),
+    );
+    expect(value).toEqual({ theme: "dark" });
+  });
+
+  it("falls back to the default without a cookie", async () => {
+    const response = await moduleApp.read.fetch(
+      {},
+      { key: "module-read-none", request: { headers: { cookie: "" } } },
+    );
+
+    expect(response.data.theme).toBe("light");
+  });
+});
+
+describe("cookie-name symmetry with APP_NAME set", () => {
+  // ServerCookiesProvider.getCookie/setCookie normally namespace every
+  // cookie under `${APP_NAME.toLowerCase()}.${name}`. The browser variant
+  // of this adapter (AtomCookiePersistence.browser.ts) can never see
+  // APP_NAME — it is not baked into the client bundle and not part of SSR
+  // hydration — so it always reads/writes the BARE atom key. Without the
+  // `prefix: false` override in AtomCookiePersistence.cookieOptions(), a
+  // client-side mutation would write `theme`, the server would look for
+  // `rdm.theme`, miss, and SSR the default — flash of wrong state on every
+  // reload. These tests must run with APP_NAME set: without it, both sides
+  // collapse to the bare key and the asymmetry is invisible.
+  const appNameSettingsAtom = $atom({
+    name: "test.cookie.appname",
+    schema: z.object({ theme: z.string() }),
+    default: { theme: "light" },
+    persist: "cookie",
+  });
+
+  class AppNameCookieAtomApp {
+    protected readonly alepha = $inject(Alepha);
+
+    settings = $state(appNameSettingsAtom);
+
+    read = $action({
+      schema: {
+        response: z.object({ theme: z.string() }),
+      },
+      handler: () => ({ theme: this.settings.theme }),
+    });
+
+    update = $action({
+      schema: {
+        body: z.object({ theme: z.string() }),
+        response: z.object({ ok: z.boolean() }),
+      },
+      handler: ({ body }) => {
+        this.alepha.store.set(appNameSettingsAtom, { theme: body.theme });
+        return { ok: true };
+      },
+    });
+  }
+
+  const appNameAlepha = Alepha.create({ env: { APP_NAME: "RDM" } })
+    .with(AlephaServer)
+    .with(AlephaServerCookies);
+
+  const appNameApp = appNameAlepha.inject(AppNameCookieAtomApp);
+
+  it("writes the bare (unprefixed) cookie name — the same name the browser variant writes", async () => {
+    const response = await appNameApp.update.fetch({
+      body: { theme: "dark" },
+    });
+    const setCookie = response.raw?.headers.get("set-cookie");
+
+    expect(setCookie).toBeDefined();
+    expect(setCookie).toMatch(/^test\.cookie\.appname=/);
+    // The bug this guards against: the namespaced name showing up instead.
+    expect(setCookie).not.toMatch(/rdm\.test\.cookie\.appname/);
+  });
+
+  it("reads back a bare-named incoming cookie — the same name the browser variant reads", async () => {
+    const cookieHeader = `test.cookie.appname=${encodeURIComponent(
+      JSON.stringify({ theme: "dark" }),
+    )}`;
+
+    const response = await appNameApp.read.fetch(
+      {},
+      { request: { headers: { cookie: cookieHeader } } },
+    );
+
+    expect(response.data.theme).toBe("dark");
+  });
+});
+
+describe("request isolation (cookie-seeded state never leaks across concurrent requests)", () => {
+  // Permanent regression coverage for the invariant confirmed during
+  // review: cookie-seeded atom state stays fork-local (each request runs
+  // inside its own AsyncLocalStorage fork — see ServerRouterProvider /
+  // AlsProvider), and the app-level store never sees a request's value.
+  // GET requests dedupe by `{url, method}` in HttpClient (ignoring
+  // headers), so each concurrent call below needs a distinct `key` to
+  // actually hit the server three times instead of sharing one response.
+  it("keeps concurrent requests' cookie-seeded values isolated, and never touches the app-level store", async () => {
+    const cookieFor = (theme: string) =>
+      `test.cookie.settings=${encodeURIComponent(JSON.stringify({ theme }))}`;
+
+    const [alice, bob, none] = await Promise.all([
+      app.read.fetch(
+        {},
+        {
+          key: "isolation-alice",
+          request: { headers: { cookie: cookieFor("alice") } },
+        },
+      ),
+      app.read.fetch(
+        {},
+        {
+          key: "isolation-bob",
+          request: { headers: { cookie: cookieFor("bob") } },
+        },
+      ),
+      app.read.fetch(
+        {},
+        {
+          key: "isolation-none",
+          request: { headers: { cookie: "" } },
+        },
+      ),
+    ]);
+
+    expect(alice.data.theme).toBe("alice");
+    expect(bob.data.theme).toBe("bob");
+    expect(none.data.theme).toBe("light"); // default, not a leaked neighbor value
+
+    // The root (app-level) store must never have been mutated by a
+    // request-scoped cookie read.
+    expect(alepha.store.get(settingsAtom, "app")).toEqual({ theme: "light" });
+  });
+});

package/src/server/cookies/__tests__/ServerCookiesProvider.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { $action, AlephaServer } from "alepha/server";
 import { describe, expect, test } from "vitest";
 import { $cookie, AlephaServerCookies } from "../index.ts";
@@ -12,27 +12,27 @@ class CookieTestApp {
   // 1. Basic Cookie
   session = $cookie({
     name: "session",
-    schema: t.object({ userId: t.number(), role: t.text() }),
+    schema: z.object({ userId: z.number(), role: z.text() }),
   });
 
   // 2. Signed Cookie
   signed = $cookie({
     name: "signed_session",
-    schema: t.text(),
+    schema: z.text(),
     sign: true,
   });
 
   // 3. Encrypted Cookie
   encrypted = $cookie({
     name: "encrypted_secret",
-    schema: t.object({ apiKey: t.text() }),
+    schema: z.object({ apiKey: z.text() }),
     encrypt: true,
   });
 
   // 4. Compressed, Signed, and Encrypted Cookie with TTL
   secure_all = $cookie({
     name: "ultra_secure",
-    schema: t.object({ data: t.text() }),
+    schema: z.object({ data: z.text() }),
     compress: true,
     sign: true,
     encrypt: true,
@@ -42,11 +42,11 @@ class CookieTestApp {
   // An action to test the cookie functionality in a request cycle
   cookie_test = $action({
     schema: {
-      response: t.object({
-        incomingSession: t.optional(this.session.options.schema),
-        reqCookies: t.object({
-          req: t.record(t.text(), t.text()),
-          res: t.record(t.text(), t.any()),
+      response: z.object({
+        incomingSession: this.session.options.schema.optional(),
+        reqCookies: z.object({
+          req: z.record(z.text(), z.text()),
+          res: z.record(z.text(), z.any()),
         }),
       }),
     },
@@ -198,7 +198,7 @@ describe("ServerCookiesProvider", () => {
     class AttrApp {
       advanced = $cookie({
         name: "advanced",
-        schema: t.text(),
+        schema: z.text(),
         path: "/admin",
         ttl: [30, "minutes"],
         httpOnly: true,
@@ -232,11 +232,81 @@ describe("ServerCookiesProvider", () => {
     // Secure flag is not added in tests unless protocol is https, which is handled by the provider
   });
 
+  describe("APP_NAME namespacing", () => {
+    class TokenApp {
+      tokens = $cookie({
+        name: "tokens",
+        schema: z.object({ value: z.text() }),
+      });
+      set = $action({
+        handler: () => {
+          this.tokens.set({ value: "from-app" });
+        },
+      });
+      read = $action({
+        schema: {
+          response: z.object({ value: z.text().optional() }),
+        },
+        handler: ({ cookies }) => {
+          return { value: this.tokens.get({ cookies })?.value };
+        },
+      });
+    }
+
+    const makeApp = (appName: string) =>
+      Alepha.create({
+        env: { COOKIE_SECRET: TEST_COOKIE_SECRET, APP_NAME: appName },
+      })
+        .with(AlephaServer)
+        .with(AlephaServerCookies)
+        .with(TokenApp);
+
+    test("prefixes the cookie name with the lowercased APP_NAME", async () => {
+      const appA = makeApp("AppA");
+      await appA.start();
+
+      const response = await appA.inject(TokenApp).set.fetch();
+      const setCookieHeader = response.headers.get("set-cookie");
+
+      // Cookie is written under the namespaced name, not the bare "tokens".
+      expect(setCookieHeader).toContain("appa.tokens=");
+      expect(setCookieHeader).not.toMatch(/(^|; )tokens=/);
+    });
+
+    test("two apps sharing a cookie jar do not collide", async () => {
+      const appA = makeApp("AppA");
+      const appB = makeApp("AppB");
+      await appA.start();
+      await appB.start();
+
+      // App A writes its cookie.
+      const responseA = await appA.inject(TokenApp).set.fetch();
+      const cookieA = responseA.headers
+        .get("set-cookie")!
+        .match(/appa\.tokens=([^;]*)/)![1];
+
+      // App A reads its own cookie back from the shared jar — works.
+      const incoming = `appa.tokens=${cookieA}`;
+      const readA = await appA
+        .inject(TokenApp)
+        .read.fetch({}, { request: { headers: { cookie: incoming } } });
+      expect(readA.data.value).toBe("from-app");
+
+      // App B sees the SAME jar (same host:localhost), but reads under
+      // "appb.tokens" — so App A's cookie is invisible to it. No collision,
+      // no failed-decrypt-then-delete logout.
+      const readB = await appB
+        .inject(TokenApp)
+        .read.fetch({}, { request: { headers: { cookie: incoming } } });
+      expect(readB.data.value).toBeUndefined();
+    });
+  });
+
   // test("should throw if secret is missing for secure cookies", async () => {
   // 	class AppWithMissingSecret {
   // 		badCookie = $cookie({
   // 			name: "bad",
-  // 			schema: t.text(),
+  // 			schema: z.text(),
   // 			sign: true,
   // 		});
   // 	}