elm-ssr 0.2.0 → 0.3.0

package/docs/sessions.md

@@ -1,218 +0,0 @@
-# Sessions and CSRF
-
-Signed-cookie sessions backed by a pluggable store, plus CSRF protection for
-form submissions. The whole stack is opt-in via two flags on
-`createWorkerApp`. The Elm side picks the session up via four new effects:
-`Loader.session`, `Loader.csrfToken`, `Loader.setSession`, and
-`Loader.clearSession`.
-
-## Quickstart
-
-```ts
-import { createWorkerApp } from "elm-ssr";
-import { memorySessionStore, cacheStore } from "elm-ssr/sessions";
-import { redisCache } from "elm-ssr/backends";
-
-const worker = createWorkerApp({
-  // ... your usual options (elmModule, routes, createFlags, effects, ...)
-
-  // Enable signed-cookie sessions + auto-wrap your effect runner with
-  // sessionEffects so Loader.session / setSession work.
-  sessions: {
-    secret: env.SESSION_SECRET, // 32+ random bytes; do not leak
-    store: cacheStore(redisCache(myRedisClient)),
-    // Defaults: cookieName "session", maxAgeSeconds 7 days,
-    //           cookiePath "/", secure true, sameSite "lax", HttpOnly.
-  },
-
-  // Enable CSRF (requires sessions). `true` uses defaults; pass an object to customize.
-  csrf: true
-});
-```
-
-In dev / tests, swap in `memorySessionStore()` and `secure: false` so the
-cookie works over plain HTTP.
-
-## The flow
-
-1. **Request arrives.** `sessionMiddleware` reads the configured cookie, HMAC-verifies it, looks up the record in the store. If anything's missing/tampered, it **mints a fresh session** (with a new CSRF token) so downstream code never has to nil-check.
-2. **Effects run.** `sessionEffects` (auto-wired when `sessions:` is set) intercepts four Elm-facing effect kinds and reads/writes `context.session`:
-   - `session` → returns `session.data` or `null`.
-   - `csrfToken` → returns `session.csrf`.
-   - `setSession` → mutates `session.data`, marks `dirty`.
-   - `clearSession` → marks `destroyed`.
-3. **Response comes back.** `sessionMiddleware`:
-   - If `destroyed`: deletes the record and emits a `Max-Age=0` Set-Cookie.
-   - If `dirty` or new: persists to the store and emits a fresh signed Set-Cookie.
-   - Else: leaves the response alone.
-4. **`csrfMiddleware` runs in between.** For POST/PUT/PATCH/DELETE it requires a token matching `context.session.csrf`. Token comes from the `X-CSRF-Token` header or a `_csrf` form field. Mismatch → 403 (JSON for `/api/*`, plain text otherwise). Safe verbs pass through untouched.
-
-## Stores
-
-```ts
-interface SessionStore {
-  get(id: string): Promise<SessionRecord | null>;
-  set(id: string, record: SessionRecord): Promise<void>;
-  delete(id: string): Promise<void>;
-}
-
-interface SessionRecord {
-  data: unknown;          // your app's payload (JSON-serialisable)
-  csrf: string;
-  expiresAt?: number;     // epoch ms
-}
-```
-
-Two built-ins:
-
-- **`memorySessionStore()`** — a `Map`-backed store. Useful for tests and dev; sessions vanish when the process restarts.
-- **`cacheStore(backend, options?)`** — wraps any [`CacheBackend`](backends.md) (so `redisCache(...)`, a KV-backed wrapper, etc.). Sessions are prefixed (default `"elm-ssr:session:"`) to avoid colliding with your other cache uses, and TTLs come from each record's `expiresAt`.
-
-For SQL-backed sessions, implement `SessionStore` against your driver — that's three async functions.
-
-## Authoring in Elm
-
-### Read the session
-
-```elm
-import Json.Decode as Decode
-import ElmSsr.Loader as Loader exposing (Loader)
-
-
-type alias User =
-    { id : String, email : String }
-
-
-userDecoder : Decode.Decoder User
-userDecoder =
-    Decode.map2 User
-        (Decode.field "id" Decode.string)
-        (Decode.field "email" Decode.string)
-
-
-currentUser : Loader (Maybe User)
-currentUser =
-    Loader.session userDecoder
-```
-
-`Loader.session` returns `Nothing` when no session payload has been set yet
-(fresh anonymous visitor).
-
-### Read the CSRF token (to embed in a form)
-
-```elm
-form
-    [ Attr.method "post", Attr.action "/profile" ]
-    (csrfHidden token ++ [ {- inputs, button -} ])
-
-
-csrfHidden : Maybe String -> List (Node msg)
-csrfHidden token =
-    case token of
-        Just value ->
-            [ input [ Attr.type_ "hidden", Attr.name "_csrf", Attr.value value ] ]
-
-        Nothing ->
-            []
-```
-
-A page that needs both the session AND the token at once:
-
-```elm
-page _ =
-    Loader.map2 view
-        (Loader.session userDecoder)
-        Loader.csrfToken
-```
-
-### Write the session (login)
-
-```elm
-import Json.Encode as Encode
-import ElmSsr.Action as Action exposing (Action)
-import ElmSsr.Loader as Loader
-
-
-action : Request -> Action (Document Never)
-action request =
-    case Route.formValue "username" request of
-        Just username ->
-            Action.fromLoader
-                (Loader.setSession
-                    (Encode.object [ ( "username", Encode.string username ) ]))
-                |> Action.andThen (\_ -> Action.redirect "/dashboard")
-
-        Nothing ->
-            Action.fail 422 "Username is required"
-```
-
-`Loader.setSession` takes a `Json.Encode.Value` — that's the only constraint
-on payload shape. The middleware persists and rolls the signed cookie when
-the response is built.
-
-### Destroy the session (logout)
-
-```elm
-action _ =
-    Action.fromLoader Loader.clearSession
-        |> Action.andThen (\_ -> Action.redirect "/")
-```
-
-The middleware deletes the record and clears the cookie.
-
-## CSRF in detail
-
-`csrfMiddleware` enforces CSRF tokens for unsafe HTTP methods:
-
-| Method | Token required? |
-| ------ | --------------- |
-| GET, HEAD, OPTIONS | No |
-| POST, PUT, PATCH, DELETE, anything else | Yes |
-
-The token is looked up in this order:
-
-1. The `X-CSRF-Token` request header (configurable via `headerName`).
-2. The `_csrf` field of a URL-encoded or multipart form body (configurable via `fieldName`).
-
-Either matches the current request's `context.session.csrf`. Mismatch ⇒ 403.
-
-```ts
-csrf: {
-  headerName: "x-csrf-token",  // default
-  fieldName: "_csrf",          // default
-  skipPaths: ["/webhooks/"]    // prefixes to bypass — useful for inbound webhooks
-}
-```
-
-`csrfMiddleware` reads the form body via `request.clone().formData()` so the
-downstream route handler can still read it.
-
-## Security notes
-
-- **Secret rotation.** The HMAC secret signs every cookie. Rotating it
-  invalidates all existing sessions (next request mints a new one). Treat as
-  a Cloudflare secret binding, never commit.
-- **Cookie attributes.** Defaults are `HttpOnly` + `Secure` + `SameSite=Lax`
-  + 7-day Max-Age + `Path=/`. Override `secure: false` only when developing
-  on plain HTTP (`http://localhost`).
-- **CSRF tokens.** 32 bytes from `crypto.getRandomValues`, URL-safe Base64.
-  Rotated on session destroy (the new session minted afterward gets a fresh
-  token).
-- **Constant-time signature check.** `verifyValue` uses constant-time byte
-  comparison.
-- **Cookie size.** The signed cookie value is just the session id + signature
-  (~120 bytes). Payload lives in the store, never in the cookie — that
-  avoids the 4 KB cookie limit + lets you change session data without
-  re-signing on every response.
-
-## End-to-end example
-
-[examples/basic/src/Example/Basic/Routes/Profile.elm](../examples/basic/src/Example/Basic/Routes/Profile.elm)
-is the full login/logout flow over the API above. The session-enabled worker
-that runs it is exported as `createSessionExampleWorker` in
-[examples/basic/runtime.ts](../examples/basic/runtime.ts).
-
-## Source
-
-- [packages/elm-ssr/src/sessions/](../packages/elm-ssr/src/sessions/) — `crypto.ts`, `types.ts`, `store.ts`, `middleware.ts`, `effects.ts`, `index.ts`.
-- Tests: [test/sessions.test.ts](../test/sessions.test.ts), [test/profile.test.ts](../test/profile.test.ts).

package/docs/tasks.md

@@ -1,149 +0,0 @@
-# Tasks and queues
-
-Background work that runs **after** the response goes out — emails, cache
-warming, webhooks, anything you don't want blocking the user.
-
-`Loader.enqueue { task, payload }` is the Elm-side entry point. What happens
-to that payload depends on which adapter you wrap the runner with:
-
-- **`withTasks(runner, handlers)`** — runs the task inline after the
-  response, kept alive by `ctx.waitUntil` on Cloudflare, fire-and-forget on
-  Bun. Best for fast, idempotent work.
-- **`withQueueProducer(runner, { queueBinding })`** — sends the task to a
-  Cloudflare Queue (durable, retried on failure). A separate consumer Worker
-  picks it up with `createQueueConsumer(handlers)`.
-
-Both wrap any existing runner, so they compose with `withCache`,
-`cloudflareEffects`, `inMemoryEffects`, etc.
-
-## Enqueueing from Elm
-
-```elm
-import Json.Encode as Encode
-import ElmSsr.Action as Action
-import ElmSsr.Loader as Loader
-
-
-sendThankYou : String -> Loader ()
-sendThankYou email =
-    Loader.enqueue
-        { task = "sendEmail"
-        , payload =
-            Encode.object
-                [ ( "to", Encode.string email )
-                , ( "subject", Encode.string "Thanks!" )
-                ]
-        }
-
-
-action : Request -> Action (Document Never)
-action request =
-    case Route.formValue "email" request of
-        Just email ->
-            Action.fromLoader (saveSubscriber email)
-                |> Action.andThen (\_ -> Action.fromLoader (sendThankYou email))
-                |> Action.andThen (\_ -> Action.redirect "/thanks")
-
-        Nothing ->
-            Action.fail 422 "Email is required"
-```
-
-The action returns its response right after `saveSubscriber`; `sendEmail` runs
-afterward (with `waitUntil`), so the user isn't waiting for SMTP.
-
-## `withTasks` (inline, fastest)
-
-```ts
-import { withTasks } from "elm-ssr/tasks";
-import { cloudflareEffects } from "elm-ssr/effects";
-
-const effects = withTasks(cloudflareEffects(), {
-  sendEmail: async (payload, ctx) => {
-    await fetch("https://api.sendgrid.com/v3/mail/send", {
-      method: "POST",
-      headers: { authorization: `Bearer ${ctx.env?.SENDGRID_KEY}` },
-      body: JSON.stringify(payload)
-    });
-  },
-  warmCache: async (_payload, ctx) => {
-    /* … */
-  }
-});
-```
-
-Each handler receives `(payload, effectContext)`. The context has `env`,
-`request`, and `waitUntil` — same shape every effect sees.
-
-**Behavior:**
-- On Cloudflare: scheduled via `ctx.waitUntil(handler(...))`. The isolate
-  stays alive long enough to finish.
-- On Bun (no `waitUntil`): runs detached (`void promise`). Survives only as
-  long as the process does.
-- Handler throws → `console.error("elm-ssr: background task \"NAME\" failed",
-  error)`; the request is unaffected.
-- Unknown task name → the **`enqueue`** effect fails (`No task handler
-  registered for "NAME"`), so the action surfaces the error to the caller.
-
-## `withQueueProducer` + `createQueueConsumer` (durable)
-
-For work that **must** survive a Worker restart or retry on failure, use a
-Cloudflare Queue. The producer Worker enqueues; a separate consumer Worker
-(or the same Worker with a `queue` handler) processes the messages.
-
-### Producer
-
-```ts
-import { withQueueProducer } from "elm-ssr/tasks";
-
-const effects = withQueueProducer(cloudflareEffects(), {
-  queueBinding: "JOBS" // default "QUEUE"
-});
-```
-
-`Loader.enqueue { task: "warmCache", payload: ... }` sends
-`{ task: "warmCache", payload: ... }` to `env.JOBS.send(...)`. If the binding
-is missing, the effect fails with `Missing queue binding "JOBS"`.
-
-### Consumer
-
-```ts
-import { createQueueConsumer } from "elm-ssr/tasks";
-
-export default {
-  fetch: worker.fetch, // from createWorkerApp
-  queue: createQueueConsumer({
-    warmCache: async (payload, ctx) => { /* … */ },
-    sendEmail: async (payload, ctx) => { /* … */ }
-  })
-};
-```
-
-The consumer reads each message's `{ task, payload }`, dispatches to the
-named handler, and:
-- **`message.ack()`** on success.
-- **`message.retry()`** if the handler throws or the task name has no
-  handler.
-
-Bind the queue in `wrangler.jsonc`:
-
-```jsonc
-{
-  "queues": {
-    "producers": [{ "queue": "elm-ssr-jobs", "binding": "JOBS" }],
-    "consumers": [{ "queue": "elm-ssr-jobs", "max_batch_size": 10 }]
-  }
-}
-```
-
-## Choosing
-
-| Need | Use |
-| ---- | --- |
-| Quick post-response work, fine to lose on crash | `withTasks` |
-| Durable jobs, retry on failure, backpressure | `withQueueProducer` + `createQueueConsumer` |
-| Both (some inline, some durable) | Wrap the runner with **both** — `enqueue` is intercepted by the outermost matching adapter, so order matters. Put the more-specific one outside, or split task names cleanly. |
-
-## Source
-
-- [packages/elm-ssr/src/tasks.ts](../packages/elm-ssr/src/tasks.ts)
-- [packages/elm-ssr/elm-src/ElmSsr/Loader.elm](../packages/elm-ssr/elm-src/ElmSsr/Loader.elm) (`enqueue`)

package/docs/testing.md

@@ -1,84 +0,0 @@
-# Testing
-
-The repo's test loops are split by what they need running. All run through
-`bun test`.
-
-## Scripts
-
-| Script | Brings Docker up? | What runs |
-| ------ | ----------------- | --------- |
-| `bun run test:unit` | No | All `test/*.test.ts` except `test/integration/`. Fast. |
-| `bun run test:integration` | Yes (PG + Redis) | Only `test/integration/`. Tears Docker back down on exit. |
-| `bun run test` | Yes (PG + Redis) | Everything. Tears Docker back down on exit. |
-
-Each Docker-managed script runs `docker compose up -d --wait`, executes the
-suite, and then runs `docker compose down` — even on test failure (it
-preserves the exit code).
-
-## Local quick loop
-
-While writing code, use `test:unit` — no Docker, ~400ms for ~108 tests:
-
-```sh
-bun run test:unit
-```
-
-## Full run
-
-```sh
-bun run test
-```
-
-This compiles the example apps (`bun run build`), brings Docker up, runs
-everything (114 tests as of this writing), tears Docker down. Useful before a
-PR or a release.
-
-## Integration suite
-
-`test/integration/redis-postgres.test.ts` exercises:
-
-- `redisCache` (`withCache`) round-trips against a real Redis (`Bun.redis`).
-- TTL expiration.
-- `runMigrations` / `revertMigrations` / `listMigrations` against real
-  Postgres (`Bun.sql`).
-- `postgresSql` adapter (`query`/`queryOne`/`execute`) against real Postgres.
-
-It **throws** if `DATABASE_URL` / `REDIS_URL` aren't set. That's deliberate
-— it points you at `bun run test:integration` instead of silently
-green-skipping when you actually wanted to run it.
-
-## Docker services
-
-[docker-compose.yml](../docker-compose.yml) defines:
-
-- `postgres:16-alpine` on `localhost:5432`, user/pass/db = `elmssr`.
-- `redis:7-alpine` on `localhost:6379`.
-
-Both have healthchecks; `--wait` blocks until they're ready.
-
-## Writing tests
-
-Each test suite lives in `test/<area>.test.ts`. Pattern:
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { createWorkerApp } from "elm-ssr";
-import { inMemoryEffects } from "elm-ssr/effects";
-
-describe("worker", () => {
-  it("renders a page", async () => {
-    const worker = createWorkerApp({ /* … */, effects: inMemoryEffects() });
-    const response = await worker.fetch(new Request("https://example.com/"));
-    expect(response.status).toBe(200);
-  });
-});
-```
-
-Use `inMemoryEffects` (optionally with `withCache(..., redisCache(...))` /
-`postgresSql(...)`) to test effect interactions without a real backend.
-
-## Source
-
-- Tests: [test/](../test/)
-- Integration: [test/integration/](../test/integration/)
-- Docker: [docker-compose.yml](../docker-compose.yml)

package/elm-ssr.config.json

@@ -1,14 +0,0 @@
-{
-  "apps": [
-    {
-      "name": "basic",
-      "root": "examples/basic",
-      "module": "Example.Basic"
-    },
-    {
-      "name": "crypto-dashboard",
-      "root": "examples/crypto-dashboard",
-      "module": "CryptoDashboard"
-    }
-  ]
-}

package/examples/basic/elm.json

@@ -1,27 +0,0 @@
-{
-  "type": "application",
-  "source-directories": [
-      ".elm-ssr",
-      "src",
-      ".elm-ssr/src"
-  ],
-
-  "elm-version": "0.19.1",
-  "dependencies": {
-    "direct": {
-      "elm/browser": "1.0.2",
-      "elm/core": "1.0.5",
-      "elm/html": "1.0.0",
-      "elm/json": "1.1.3",
-      "elm/url": "1.0.0"
-    },
-    "indirect": {
-      "elm/time": "1.0.0",
-      "elm/virtual-dom": "1.0.3"
-    }
-  },
-  "test-dependencies": {
-    "direct": {},
-    "indirect": {}
-  }
-}

package/examples/basic/migrations/0001_guestbook.down.sql

@@ -1 +0,0 @@
-DROP TABLE entries;

package/examples/basic/migrations/0001_guestbook.sql

@@ -1,10 +0,0 @@
--- The schema for the /guestbook route's `query`/`execute` effects.
--- Portable enough for SQLite and Postgres (`INTEGER PRIMARY KEY` auto-increments
--- in SQLite; in Postgres it's just a primary key — use `SERIAL`/`IDENTITY` if
--- you want server-side sequence generation).
-
-CREATE TABLE entries (
-  id INTEGER PRIMARY KEY,
-  message TEXT NOT NULL,
-  created_at TEXT NOT NULL DEFAULT (CURRENT_TIMESTAMP)
-);

package/examples/basic/package.json

@@ -1,10 +0,0 @@
-{
-  "name": "@elm-ssr/example-basic",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "description": "Reference example app: pages, islands, forms (PRG), server caching, SQL via migrations, background tasks.",
-  "dependencies": {
-    "elm-ssr": "workspace:*"
-  }
-}

package/examples/basic/runtime.ts

@@ -1,148 +0,0 @@
-import { createWorkerApp } from "elm-ssr";
-import { inMemoryEffects, type EffectRunner } from "elm-ssr/effects";
-import { renderApp, type CompiledElmModule } from "elm-ssr/render";
-import type { RouteCatalog } from "elm-ssr/http";
-import { memorySessionStore } from "elm-ssr/sessions";
-import { islands, bundleSource } from "../../generated/examples/basic/islands-manifest";
-import { stylesheet } from "./styles";
-// @ts-expect-error Generated at build time.
-import ElmRuntime from "../../generated/examples/basic/app.mjs";
-
-const elmModule = ElmRuntime as CompiledElmModule;
-
-export const routes: RouteCatalog = {
-  pages: [
-    {
-      path: "/",
-      methods: ["GET", "HEAD"],
-      description: "Stateless landing page rendered from Elm (no client runtime)."
-    },
-    {
-      path: "/status",
-      methods: ["GET", "HEAD"],
-      description: "Stateless page whose Loader fetches data on the server."
-    },
-    {
-      path: "/counter",
-      methods: ["GET", "HEAD"],
-      description: "SSR page that embeds Browser.element islands."
-    },
-    {
-      path: "/greet/:name",
-      methods: ["GET", "HEAD"],
-      description: "Dynamic route; the name segment is captured from the URL."
-    }
-  ],
-  assets: [
-    {
-      path: "/styles.css",
-      methods: ["GET", "HEAD"],
-      description: "Example stylesheet."
-    },
-    {
-      path: "/__elm-ssr/islands.js",
-      methods: ["GET", "HEAD"],
-      description: "Island loader runtime."
-    },
-    {
-      path: "/__elm-ssr/islands-bundle.js",
-      methods: ["GET", "HEAD"],
-      description: "Shared Browser.element island bundle."
-    }
-  ],
-  utility: [
-    {
-      path: "/health",
-      methods: ["GET", "HEAD"],
-      description: "Plain text liveness endpoint."
-    }
-  ],
-  api: [
-    {
-      path: "/api/health",
-      methods: ["GET", "HEAD"],
-      description: "JSON health payload."
-    },
-    {
-      path: "/api/routes",
-      methods: ["GET", "HEAD"],
-      description: "Route registry for the example app."
-    },
-    {
-      path: "/api/render",
-      methods: ["GET", "HEAD"],
-      description: "SSR preview endpoint."
-    }
-  ]
-};
-
-export const createFlags = ({ request, path, formData }: { request?: Request; url?: URL; path: string; formData?: Record<string, string> }) => {
-  const [pathname, search = ""] = path.split("?");
-
-  return {
-    method: request?.method ?? "GET",
-    path: pathname,
-    query: Object.fromEntries(new URLSearchParams(search)),
-    formData: formData ?? {}
-  };
-};
-
-export const statusFixture = { uptime: "99.98%", region: "edge", builds: 128 };
-
-// The Worker owns effect execution. Locally we use the in-memory adapter: a Map
-// cache, env values, and a fixture for the `app://status` fetch its loader uses.
-// On Cloudflare you'd swap in `cloudflareEffects()` (KV/D1/env) without touching
-// any Elm.
-export const exampleEffects: EffectRunner = inMemoryEffects({
-  env: { GREETING: "hello from the server env" },
-  fetchJson: (url) => {
-    if (url === "app://status") {
-      return statusFixture;
-    }
-
-    throw new Error(`Unexpected fetchJson url in example: ${url}`);
-  }
-});
-
-export const renderPath = async (path: string) =>
-  renderApp(elmModule, createFlags({ path }), { effects: exampleEffects });
-
-export const createExampleWorker = (options: { effects?: EffectRunner; log?: (entry: string) => void } = {}) =>
-  createWorkerApp({
-    elmModule,
-    islands,
-    islandsBundle: bundleSource,
-    stylesheet,
-    routes,
-    createFlags,
-    effects: options.effects ?? exampleEffects,
-    log: options.log
-  });
-
-export const worker = createExampleWorker();
-
-/**
- * A second example worker that enables sessions + CSRF (against an in-memory
- * store). Used by the /profile end-to-end tests. The hardened cookie defaults
- * are turned down for the example because tests run over plain HTTP — in
- * production `secure: true` is the default.
- */
-export const createSessionExampleWorker = (
-  options: { effects?: EffectRunner; log?: (entry: string) => void; secret?: string } = {}
-) =>
-  createWorkerApp({
-    elmModule,
-    islands,
-    islandsBundle: bundleSource,
-    stylesheet,
-    routes,
-    createFlags,
-    effects: options.effects ?? exampleEffects,
-    log: options.log,
-    sessions: {
-      secret: options.secret ?? "elm-ssr-example-dev-secret-do-not-use-in-prod",
-      store: memorySessionStore(),
-      secure: false
-    },
-    csrf: true
-  });