toiljs 0.0.85 → 0.0.87

package/docs/email.md

@@ -1,326 +0,0 @@
-# Email
-
-toiljs can send transactional email from a route handler. A handler calls
-`EmailService.send(...)` (or a typed `EmailTemplate` / `Emails.*` from the
-`emails/` folder, or the stateless `TwoFactor` helper); the edge hands the
-message to a single off-core mailer thread that talks to the provider over the
-kernel network (never the worker cores), and **suspends** the wasm call until the
-provider responds, so a slow send never blocks the worker.
-
-Everything here is an ambient **global** (no import), like `crypto` and
-`AuthService`. A tenant that never sends email pulls none of it into its build.
-
-- **`EmailService`**, send one email.
-- **`EmailTemplate`**, a reusable template with `{{placeholder}}` substitution
-  (plain text and/or HTML).
-- **`emails/*.tsx`**, author emails as React components; the build renders them
-  to static HTML and generates a typed `Emails.<Name>.send(...)`.
-- **`TwoFactor`**, stateless email verification codes (2FA / confirm), no DB.
-
-> **The one rule of HTML email:** email clients run **no JavaScript** and strip
-> `<style>`/external CSS. So HTML email is a static, inline-styled string, and
-> any "rendering" (React, CSS files) happens at **build time**, not at send time.
-> See [React email templates](#react-email-templates).
-
-## Configure email
-
-Email is a **framework-reserved namespace of the tenant's environment**, the
-same out-of-band [Environment](./environment.md) store that backs
-`Environment.get` / `getSecure`, but the `[email]` block is **host-only**: it is
-read and used in Rust (the off-core mailer) and is **never exposed to the
-`.wasm`**. The provider key never lives in the deployed module or in the
-inotify-watched `hosts/<host>.toml`.
-
-On the edge today it lives in the tenant's env secrets file,
-`$TOIL_ENV_DIR/<host>.env.secrets` (default dir `/run/toil/env`), kept `0600` and
-**out of `hosts/`** so the config watcher never sees a credential (the dashboard /
-edge DB replaces this file later). Email config is a set of **reserved
-`TOIL_EMAIL_*` keys**, host-only, stripped from the guest buckets, so a tenant
-can never read them via `Environment.getSecure`:
-
-```bash
-# $TOIL_ENV_DIR/<host>.env.secrets   (mode 0600; NOT under hosts/, NOT in the .wasm)
-
-TOIL_EMAIL_ENABLED=true
-TOIL_EMAIL_FROM=you@example.com       # validated; single address, no CRLF
-TOIL_EMAIL_PROVIDER=resend            # resend | gmail | smtp
-TOIL_EMAIL_API_KEY=re_xxxxxxxxxxxx    # the provider credential
-TOIL_EMAIL_MAX_PER_MIN=60             # per-host send budget: rolling 1-minute cap
-TOIL_EMAIL_MAX_PER_DAY=0              # per-host send budget: rolling 24-hour cap (0 = unlimited)
-TOIL_EMAIL_MAX_PER_RECIPIENT_PER_HOUR=5   # anti-abuse cap per recipient
-```
-
-The same file also carries the tenant's own secrets (and `<host>.env` their plain
-vars; see [Environment](./environment.md)); the `TOIL_EMAIL_*` keys are just the
-reserved namespace the framework consumes.
-
-When `enabled` is `false` (the default) the host has no email capability and
-`EmailService.send` returns `Disabled`. The env is loaded **lazily** (on the
-first send) and the `api_key` is materialized into a zeroizing secret in host
-memory, never written to logs or `/_admin`. A malformed `[email]` block is
-treated as "no email" (the host returns `Disabled`); validate config on the
-dashboard before deploying.
-
-### Providers
-
-**Resend** (`provider = "resend"`), a JSON API; `api_key` holds the API key.
-
-**Gmail** (`TOIL_EMAIL_PROVIDER=gmail`), SMTP with Gmail defaults:
-`smtp.gmail.com`, port `587` (STARTTLS), username = `from`. `TOIL_EMAIL_API_KEY`
-holds a Gmail **App Password** (create one at
-<https://myaccount.google.com/apppasswords>; the account needs 2-Step
-Verification). No extra keys needed:
-
-```bash
-TOIL_EMAIL_ENABLED=true
-TOIL_EMAIL_FROM=you@gmail.com
-TOIL_EMAIL_PROVIDER=gmail
-TOIL_EMAIL_API_KEY=abcd efgh ijkl mnop
-```
-
-**Generic SMTP** (`TOIL_EMAIL_PROVIDER=smtp`), any submission server (Outlook,
-SendGrid/Mailgun SMTP, your own). Requires `TOIL_EMAIL_SMTP_HOST`; port defaults
-to `587` (STARTTLS), or set `465` for implicit TLS. `TOIL_EMAIL_SMTP_USER`
-defaults to `from`.
-
-```bash
-TOIL_EMAIL_ENABLED=true
-TOIL_EMAIL_FROM=noreply@example.com
-TOIL_EMAIL_PROVIDER=smtp
-TOIL_EMAIL_API_KEY=the-smtp-password
-TOIL_EMAIL_SMTP_HOST=smtp.example.com
-TOIL_EMAIL_SMTP_PORT=587
-TOIL_EMAIL_SMTP_USER=noreply@example.com
-```
-
-### In dev
-
-`toiljs dev` runs the **full email pipeline** in Node, recipient validation,
-dedup, and the per-minute / per-day / per-recipient caps all behave exactly like
-the edge, and **really sends** once you configure a provider. Configure it in
-`toil.config.ts` (non-secret) with the API key in `.env.secrets`:
-
-```ts
-// toil.config.ts
-import { defineConfig } from 'toiljs/compiler';
-export default defineConfig({
-    server: {
-        email: { provider: 'resend', from: 'you@example.com', maxPerMin: 60 },
-    },
-});
-```
-
-```bash
-# .env.secrets  (gitignored)
-TOIL_EMAIL_API_KEY=re_xxxxxxxxxxxx
-```
-
-`TOIL_EMAIL_*` env vars override the config file (so the same `.env.secrets` the
-edge uses works in dev too). Supports `resend` and `gmail`/`smtp` (SMTP via
-nodemailer). **Not configured?** `EmailService.send` stays a log-only mock and
-returns `Sent`, so a flow that sends email still works without setup.
-
-> Because the dev server runs the guest **synchronously**, the actual network
-> send is fire-and-forget: validation + caps return their exact status
-> immediately, but a `Sent` is optimistic and the real delivery outcome (or
-> `ProviderError`) is logged, not returned. The ABI is identical to the edge, so
-> code that runs in dev runs on the edge.
-
-## Sending email
-
-```ts
-import { Response, RouteContext } from 'toiljs/server/runtime';
-
-@rest('notify')
-class Notify {
-    @post('/welcome')
-    welcome(ctx: RouteContext): Response {
-        const status = EmailService.send(
-            'alice@example.com',
-            'Welcome!',
-            'Thanks for signing up.', // plain-text body
-            'welcome', // purpose tag (dedup / abuse keying)
-            '<h1>Thanks for signing up.</h1>', // optional HTML body
-        );
-        return status == EmailStatus.Sent
-            ? Response.text('sent\n')
-            : Response.text('could not send\n', 503);
-    }
-}
-```
-
-`send(to, subject, body, purpose = 'tx', html = '')` returns an **`EmailStatus`**:
-
-| Status            | Meaning                                                     | Retry?           |
-| ----------------- | ----------------------------------------------------------- | ---------------- |
-| `Sent`            | Accepted by the provider                                    |, |
-| `Deduped`         | An identical recent `(recipient, purpose)` was collapsed    | treat as sent    |
-| `Budget`          | The host's per-minute budget is exhausted                   | yes, later       |
-| `TryLater`        | The mailer was saturated / a queue was full                 | yes, back off    |
-| `RecipientCapped` | The per-recipient hourly cap was hit                        | no (this window) |
-| `BadRecipient`    | The address failed validation (CRLF, multiple addresses)    | no               |
-| `Disabled`        | This host has no `[email]` capability                       | no               |
-| `ProviderError`   | The provider rejected it, or transport failed after retries | no               |
-
-`purpose` is a short, non-PII tag (`"welcome"`, `"reset"`, …). The mailer folds
-it into the **dedup** key (identical `(host, recipient, purpose)` within ~30s is
-collapsed to one send) and the abuse counters. It is never logged in the clear.
-
-The recipient is validated host-side (exactly one address, no CR/LF/`<>`), so a
-guest can never smuggle a second envelope recipient or a header into the send.
-
-## Templates
-
-`EmailTemplate` is a reusable message with `{{placeholder}}` substitution, for
-when the same email is sent with different values:
-
-```ts
-const welcome = new EmailTemplate(
-    'Welcome, {{name}}!', // subject
-    'Hi {{name}}, your code is {{code}}.', // plain-text body
-    '<h1>Welcome, {{name}}</h1><p>Code: <b>{{code}}</b></p>', // html (optional)
-);
-
-const vars = new Map<string, string>();
-vars.set('name', 'Alice');
-vars.set('code', '123456');
-const status = welcome.send('alice@example.com', vars, 'welcome');
-```
-
-- `{{ name }}` (with surrounding spaces) is accepted; an unknown placeholder
-  renders to the empty string.
-- Omit the `html` argument for a plain-text template.
-- `template.render(vars)` returns the rendered `{ subject, body, html }` without
-  sending (useful for preview/testing).
-
-For anything richer than `{{token}}` substitution, real layout, CSS, brand,
-author the email as a React component instead.
-
-## React email templates
-
-Write emails as React components in an **`emails/`** folder. At `toiljs build`
-each one is rendered **once, at build time**, to static inline-CSS HTML (because
-the inbox runs no JS), with the component's props turned into `{{token}}` holes;
-the build then generates a typed `Emails.<Name>.send(...)` your server calls.
-
-```tsx
-// emails/Welcome.tsx
-export const subject = 'Welcome, {{name}}!';
-
-export default function Welcome({ name, code }: { name: string; code: string }) {
-    return (
-        <table
-            width="100%"
-            style={{ fontFamily: 'Arial, sans-serif' }}>
-            <tbody>
-                <tr>
-                    <td style={{ padding: '24px' }}>
-                        <h1 style={{ color: '#111' }}>Welcome, {name}!</h1>
-                        <p>
-                            Your code is <b>{code}</b>.
-                        </p>
-                    </td>
-                </tr>
-            </tbody>
-        </table>
-    );
-}
-```
-
-The generated `Emails.Welcome.send(...)` takes the recipient, then one argument
-per `{{token}}` **in alphabetical order**, then an optional `purpose`:
-
-```ts
-// emails/Welcome.tsx uses {{code}} and {{name}}  ->  params are (code, name)
-const status = Emails.Welcome.send('alice@example.com', '123456', 'Alice');
-```
-
-Authoring notes:
-
-- **Styles must end up inline.** Email clients strip `<style>`/external CSS, so
-  write inline `style={{ ... }}`, or import a stylesheet and its rules are
-  inlined into element `style="…"` for you at build (a bare CSS import has no
-  effect on its own under SSR). Keep email-only styles next to the email, e.g.
-  `import './styles/email.css'`, or **reuse existing project CSS** with `import
-'client/styles/…'` (the `client/*` alias points at your client source).
-- **Optional exports:** `export const subject` (a token template; defaults to the
-  email name), `export const text` (a plain-text alternative; otherwise derived
-  from the HTML), `export const purpose`.
-- **Build-time, field substitution only.** Because the component renders once at
-  build, per-send data is `{{token}}` substitution, a runtime `{items.map(...)}`
-  or conditional bakes in at build, it does not re-run per recipient. That covers
-  transactional / 2FA / confirmation email; dynamic lists need a different
-  approach.
-- The generated `server/_emails.ts` is regenerated on `build`/`dev` and should be
-  gitignored.
-
-### Preview while you author
-
-While `toiljs dev` runs, open **`/__toil/emails`** (the dev banner prints the
-link). It lists every `emails/*.tsx`, renders the selected one exactly as the
-build does (imported `client/*` CSS inlined), lets you fill each `{{token}}` to
-see the result, toggle the HTML and plain-text parts, and open the file in your
-editor. It refreshes live as you edit the template or its CSS.
-
-## Email verification codes (`TwoFactor`)
-
-`TwoFactor` is a **stateless** email-code primitive (2FA, email confirmation,
-magic codes), no database. It emails a random code and returns a signed
-**token** that commits to the code via HMAC, without putting the code in the
-token (the code is only in the email). Verification recomputes the HMAC from the
-token plus the user-entered code, so a valid `(token, code)` pair can only come
-from someone who both received the email and holds the token.
-
-```ts
-// 1. Issue + email a code; hand `token` to the client (a cookie or hidden field).
-const challenge = TwoFactor.send('alice@example.com', 'login'); // emails the code
-// challenge.token  -> give to the client
-// challenge.status -> the EmailStatus of the send
-
-// 2. Later, verify what the user typed.
-const ok: bool = TwoFactor.verify(challenge.token, 'alice@example.com', userEntered);
-```
-
-- **`send(recipient, purpose, ttlSecs = 600, digits = 6)`**, issues a code,
-  emails it with a built-in template, returns `{ token, status }`.
-- **`issue(recipient, purpose, ttlSecs, digits)`**, returns `{ code, token }`
-  **without** sending, so you can email `code` with your own `EmailTemplate` /
-  `Emails.*` for a branded message.
-- **`verify(token, recipient, code)`**, `true` only for a code issued for that
-  recipient that hasn't expired. Constant-time compare.
-- **`TwoFactor.setSecret(secret)`**, the HMAC secret for the tokens. Call once
-  at startup in `main.ts`; it must be identical on every edge instance and out of
-  any client bundle. (This is separate from the provider `api_key`.)
-
-**Limitation:** this gives integrity + expiry but **not single-use**, a valid
-code verifies repeatedly within its TTL, because there is no server state to burn
-it. Keep the TTL short; for true single-use, store a per-recipient
-last-verified-at and reject at or before it.
-
-## Limits and abuse controls
-
-All enforced authoritatively in the single mailer (so the counts are exact across
-all workers):
-
-- **Per-host budget**, two rolling windows, both enforced: a 1-minute cap
-  (`max_per_min`) and a 24-hour cap (`max_per_day`, `0` = unlimited). Over either
-  one → `Budget`. Each host's caps, in-window sends, and reject counts are visible
-  per host at `GET /_admin/email`.
-- **Per-recipient cap**, `max_per_recipient_per_hour`. Over it →
-  `RecipientCapped`.
-- **Dedup**, identical `(host, recipient, purpose)` within ~30s → `Deduped`.
-
-Editing these in the host config takes effect on the next send (no restart).
-
-## Observability
-
-`GET /_admin/email` returns process-wide counters by reason (JSON), e.g.
-`submitted`, `sent`, `deduped`, `budget`, `recipient_capped`, `try_later`,
-`bad_recipient`, `provider_error`. It exposes **counts only**, never a
-recipient, code, subject, body, or secret.
-
-## See also
-
-- [Rate limiting](./ratelimit.md), protect your routes (including any email
-  trigger) with `@ratelimit`.
-- [Web Crypto](./crypto.md), the `crypto` global `TwoFactor` builds on.

package/docs/environment.md

@@ -1,97 +0,0 @@
-# Environment variables & secrets
-
-`Environment` gives a tenant **per-app environment variables and secrets**, set
-out of band (a dashboard, like GitHub Actions) so the deployed `.wasm` carries
-**no credentials**. It is read-only from app code, there is no `set`; values are
-configured on the deployment side, never from the module.
-
-```ts
-import { Response, RouteContext } from 'toiljs/server/runtime';
-
-@rest('cfg')
-class Cfg {
-    @get('/')
-    show(ctx: RouteContext): Response {
-        const base = Environment.get('PUBLIC_API_BASE'); // plain var, or null
-        const key = Environment.getSecure('STRIPE_KEY'); // secret, or null
-        // Use `key` to call a third party; never log it or return it to a client.
-        return Response.text(base != null ? base : 'unset');
-    }
-}
-```
-
-`Environment` is a global, no import needed (like `EmailService` / `AuthService`).
-
-## Two disjoint buckets
-
-Just like GitHub Actions' `vars` vs `secrets`:
-
-- **`Environment.get(key)`** reads **plain vars**, non-sensitive config (a public
-  API base URL, a feature flag, a region). Returns the string, or `null`.
-- **`Environment.getSecure(key)`** reads **secrets**, sensitive values (a
-  third-party API key). Returns the string, or `null`.
-
-The buckets are **disjoint**: a secret is **never** returned by `get()`, and a
-plain var is never returned by `getSecure()`. That keeps a secret from leaking
-through a code path that logs the result of a `get()`. Keys are case-sensitive,
-exact-match.
-
-> Secrets you read with `getSecure` are plaintext in your module at runtime
-> (that's the point, you need them to call out). Don't log them, don't put them
-> in a response, and don't copy them into a client bundle.
-
-## What is NOT here
-
-Framework-reserved namespaces (today: **email** provider config) are **host-only**,
-resolved and used in Rust where the framework needs them, and **never exposed to
-the `.wasm`**. There is no `Environment.email`; you configure email in the
-`[email]` block of the same env file and the platform uses it for you (see
-[Email](./email.md)). The env imports only ever see your own `vars` / `secrets`.
-
-## Where values live
-
-Vars and secrets live in **two separate dotenv (`.env`) files**, so the disjoint
-split is structural and the secrets file can be locked down on its own. On the
-edge they are per host, **out of `hosts/`** (so the config watcher never sees a
-credential), the dashboard / edge database replaces them later:
-
-```bash
-# $TOIL_ENV_DIR/<host>.env          (default dir /run/toil/env)
-PUBLIC_API_BASE=https://api.example.com   # -> Environment.get("PUBLIC_API_BASE")
-REGION=eu
-
-# $TOIL_ENV_DIR/<host>.env.secrets  (mode 0600)
-STRIPE_KEY=sk_live_xxx                     # -> Environment.getSecure("STRIPE_KEY")
-
-# host-only email config, reserved TOIL_EMAIL_* keys, NEVER exposed to the .wasm
-TOIL_EMAIL_ENABLED=true
-TOIL_EMAIL_PROVIDER=resend
-TOIL_EMAIL_FROM=noreply@example.com
-TOIL_EMAIL_API_KEY=re_xxx
-```
-
-Each file is plain dotenv: `KEY=value` per line, `#` comments, optional `export`,
-optional quotes. Keys with the reserved **`TOIL_`** prefix are framework/host-only
-and are stripped from BOTH guest buckets, a tenant can never read them via
-`get`/`getSecure` (see [Email](./email.md) for `TOIL_EMAIL_*`).
-
-On the edge, env is loaded **lazily** (the first time your code reads it) into a
-**bounded, shared, read-only cache** with idle eviction: the data lives in one
-place and is never copied per request, a host that never reads env costs nothing,
-secrets are wiped when a host goes cold, and a flood of requests to many distinct
-hosts can never grow memory without bound.
-
-## In dev
-
-`toiljs dev` reads `.env` (vars) and `.env.secrets` (secrets) at your project
-root, and overlays `process.env` as plain vars for convenience. Both are
-gitignored by the scaffold. The ABI is identical to the edge, so code that runs
-in dev runs on the edge.
-
-```bash
-# .env  (vars)
-PUBLIC_API_BASE=http://localhost:4000
-
-# .env.secrets  (secrets; 0600; gitignored)
-STRIPE_KEY=sk_test_xxx
-```

package/docs/getting-started.md

@@ -1,128 +0,0 @@
-# Getting started
-
-A toiljs app has two halves that build and ship together:
-
-- a **server** written in ToilScript, compiled to a single WebAssembly module
-  (`build/server/release.wasm`), and
-- a **client** (Vite + React) that talks to the server through a generated,
-  fully typed `Server` proxy.
-
-The server runs one fresh wasm instance per request, identically on the dev
-server and on the edge. There is no Node.js in the request path: your handler is
-wasm.
-
-## Project layout
-
-```
-project/
-  toilconfig.json          server (wasm) build config: entries, target, AS options
-  toil.config.ts           client config (defineConfig: dev/build/SEO options)
-
-  server/
-    main.ts                wires Server.handler, re-exports the wasm exports + abort
-    routes/*.ts            @rest controllers           (auto-discovered)
-    services/*.ts          @service / @remote          (auto-discovered)
-    core/AppHandler.ts     your top-level ToilHandler
-    models/*.ts            @data / @user classes
-
-  shared/
-    server.ts              GENERATED by the server build (--rpcModule): the typed
-                           client surface (Server proxy, @data codecs, getUser)
-
-  client/
-    routes/*.tsx           file-based pages
-    layout.tsx, 404.tsx    root layout / not-found
-    styles/*.css
-
-  build/
-    server/release.wasm    compiled server (+ release.wat text form)
-    client/                Vite output
-```
-
-The compiler discovers every `.ts` under `server/` that declares a decorated
-surface (`@rest`, `@service`, `@remote`, `@data`, `@user`) on its own. Importing
-those modules from `main.ts` is still good practice: it keeps a direct
-`toilscript` run (which only sees the `toilconfig.json` entries) building the
-exact same server.
-
-## `main.ts`
-
-Three things are required, and the comments in the scaffold say so:
-
-```ts
-import { Server } from 'toiljs/server/runtime';
-import { revertOnError } from 'toiljs/server/runtime/abort/abort';
-
-import { AppHandler } from './core/AppHandler';
-
-// Pull every decorated surface into a direct `toilscript` build.
-import './routes/Players';
-import './services/Stats';
-
-// 1. The handler factory: one fresh handler instance per request.
-Server.handler = () => new AppHandler();
-
-// 2. Re-export the wasm entrypoints (`handle`, `render`).
-export * from 'toiljs/server/runtime/exports';
-
-// 3. The AssemblyScript trap hook.
-export function abort(message: string, fileName: string, line: u32, column: u32): void {
-    revertOnError(message, fileName, line, column);
-}
-```
-
-If all you need is `@rest` routing, your handler can be `RestHandler` (see
-[Routing](./routing.md)) and you do not have to write an `AppHandler` at all.
-
-## The request lifecycle
-
-For each request the runtime (`server/runtime/exports`):
-
-1. decodes the request envelope into a [`Request`](./routing.md#request),
-2. publishes it ambiently as `Server.currentRequest` (so `AuthService.getUser()`
-   and friends can read its cookies with no argument),
-3. builds the handler via `Server.handler()` and calls
-   `onRequestStarted` → `handle(req)` → `onRequestCompleted`,
-4. encodes the returned [`Response`](./routing.md#response) and clears the
-   ambient request.
-
-Because the instance is fresh and memory is wiped between requests, **nothing in
-module globals survives across requests.** Anything that must persist (accounts,
-sessions you do not put in a cookie, rate-limit counters) belongs in an external
-store reached through a host binding.
-
-## CLI
-
-The `toiljs` CLI drives both halves:
-
-| Command                | What it does                                                                                                                                                                                  |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `toiljs create [name]` | Scaffold a new app (templates, styling, options).                                                                                                                                             |
-| `toiljs dev`           | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |
-| `toiljs build`         | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only).                               |
-| `toiljs start`         | Self-host a built app with production uWS/static workers, no Vite. Flags: `--root`, `--port`, `--host`, `--threads`.                                                                          |
-| `toiljs doctor`        | Diagnose setup/deps (`--json`, `--fix`).                                                                                                                                                      |
-
-In dev, requests whose method matches a dispatchable verb go into the wasm
-first; if the guest reports "no route matched" (the `x-toil-unhandled` marker)
-the request falls through to Vite, so client routes and assets just work
-alongside your API.
-
-## Building the server by hand
-
-`toiljs build` runs toilscript for you, but you can invoke it directly (this is
-what the examples do):
-
-```sh
-toilscript --target release --rpcModule shared/server.ts
-```
-
-`--target release` reads `toilconfig.json` and emits the wasm at
-`targets.release.outFile`; `--rpcModule shared/server.ts` writes the generated
-typed client (see [RPC](./rpc.md)).
-
-## Next
-
-- [Routing](./routing.md) to expose HTTP endpoints.
-- [Data codec](./data.md) for request/response bodies.
-- [Auth](./auth.md) for login and sessions.

package/docs/index.md

@@ -1,30 +0,0 @@
-# toiljs
-
-A full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a
-toilscript-to-WebAssembly server target.
-
-## Project layout
-
-- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,
-  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).
-- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.
-  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see [server.md](./server.md)).
-- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).
-- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient
-  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,
-  emitted by the server build; import `@data` classes from `shared/server`).
-
-## Key ideas
-
-- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,
-  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the
-  generated `Server` RPC surface are globals too.
-- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),
-  `npm start` (self-host the build).
-- Compute tiers: the server can span L1 request (`server/main.ts`, `@rest`/`@service`/`@remote`),
-  L2/L3 stream (`server/main.stream.ts`, `@stream`), and L4 daemon (`server/main.daemon.ts`,
-  `@daemon`/`@scheduled`); each tier compiles into its own artifact. See [tiers.md](./tiers.md).
-
-See [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),
-[server.md](./server.md), [ssr.md](./ssr.md), [rpc.md](./rpc.md), [tiers.md](./tiers.md),
-[streams.md](./streams.md), [daemon.md](./daemon.md), [derive.md](./derive.md), [cli.md](./cli.md).

package/docs/ratelimit.md

@@ -1,95 +0,0 @@
-# Rate limiting
-
-The `@ratelimit` decorator throttles **any** `@rest` route, a login, a signup, a
-public API, an email trigger, anything. It is enforced at the edge, before your
-handler runs, and keyed by default on the connecting client's **unspoofable** IP,
-so it works as an abuse / brute-force control out of the box.
-
-It composes with the other route decorators and is independent of email or auth.
-
-## Using `@ratelimit`
-
-Add it to a route alongside the verb decorator:
-
-```ts
-import { Response, RouteContext } from 'toiljs/server/runtime';
-
-@rest('auth')
-class Auth {
-    // At most 5 login attempts per 60 seconds per client IP.
-    @ratelimit(RateLimit.SlidingWindow, 5, 60)
-    @post('/login')
-    login(ctx: RouteContext): Response {
-        // ... only runs if under the limit ...
-        return Response.text('ok\n');
-    }
-}
-```
-
-`@ratelimit(strategy, limit, window)`:
-
-- **`strategy`**, a `RateLimit` value (ambient global, no import):
-  `RateLimit.FixedWindow`, `RateLimit.SlidingWindow`, or `RateLimit.TokenBucket`.
-- **`limit`** and **`window`**, integer literals whose meaning depends on the
-  strategy (see below).
-
-When a request is over the limit the edge returns **`429 Too Many Requests`**
-with a **`Retry-After`** header (whole seconds), and your handler never runs. The
-guard runs **before `@auth`**, so unauthenticated floods are limited too.
-
-> Both arguments must be **integer literals** and the strategy a `RateLimit`
-> member (or a bare integer tag). A malformed decorator emits no guard rather
-> than miscompiling, the same fail-safe rule as `@cache`.
-
-## Strategies
-
-| Strategy | `limit`, `window` mean | Behavior |
-| --- | --- | --- |
-| `FixedWindow` | `limit` events per `window` seconds | Cheapest. Counts in aligned wall-clock buckets; a caller hammering a boundary can briefly get up to ~2× `limit` across two adjacent windows. |
-| `SlidingWindow` | `limit` events per `window` seconds | Smooths the fixed-window boundary by weighting the previous window. Best general choice for "N per period". |
-| `TokenBucket` | `limit` = burst size, `window` = refill **per second** | Allows an initial burst of `limit`, then a steady `window` tokens/sec. Good for bursty-but-bounded APIs. |
-
-Examples:
-
-```ts
-// 100 requests / minute, smoothed:
-@ratelimit(RateLimit.SlidingWindow, 100, 60)
-
-// Burst of 20, then 5 per second sustained:
-@ratelimit(RateLimit.TokenBucket, 20, 5)
-
-// Exactly 3 per hour, cheapest:
-@ratelimit(RateLimit.FixedWindow, 3, 3600)
-```
-
-## How requests are keyed
-
-By default the limiter keys on the **client IP**, specifically the TCP peer
-address the edge observed (`ctx.clientIp()`), **not** a header like
-`X-Forwarded-For`, which a client can forge. That makes it a real abuse control:
-a caller can't reset their bucket by spoofing a header.
-
-The count is **exact across all 14 edge workers** (a given IP always maps to one
-authoritative shard), so the limit is global per route, not per worker. Only
-routes that opt in with `@ratelimit` ever pay anything, the lock-free fast path
-for everything else is untouched.
-
-> Each rate-limited route has its own independent limiter, a limit on `/login`
-> does not consume the budget of `/signup`.
-
-## Notes and limits
-
-- **Route-level only.** Put `@ratelimit` on each route you want limited; there is
-  no controller-wide form yet (unlike `@auth`).
-- **Keyed on IP.** The decorator keys on the peer IP today. (A per-user / custom
-  key, limiting by account instead of IP, exists in the runtime but is not yet
-  exposed through the decorator.)
-- **In dev.** `toiljs dev` runs a single-process mirror of the same three
-  strategies, so a limited route behaves the same locally as on the edge.
-
-## See also
-
-- [Email](./email.md), `@ratelimit` pairs well with email triggers (verification
-  codes, password resets) to blunt abuse.
-- [Auth, sessions, and `@user`](./auth.md), `@ratelimit` runs before the `@auth`
-  guard, so it protects the login itself.