toiljs 0.0.39 → 0.0.41

package/src/compiler/emails.ts

@@ -0,0 +1,311 @@
+/**
+ * Build-time email pipeline: compile `emails/*.tsx` React components into a
+ * generated AssemblyScript module the server WASM uses to send mail.
+ *
+ * Why build-time: email clients run NO JavaScript and strip `<style>`/external
+ * CSS, and the edge server is WASM (no React at send time). So each email is
+ * rendered to STATIC, inline-CSS HTML once at build, with `{{token}}` holes
+ * where component props were read; the edge fills those holes per send via the
+ * `EmailTemplate` global (see `server/globals/email.ts`) and calls `email_send`.
+ *
+ * Per-send data is therefore FIELD SUBSTITUTION only (`{{name}}`, `{{code}}`) --
+ * a build-time `{items.map(...)}` or conditional bakes into the output, it does
+ * not re-run per send. Plenty for transactional / 2FA / confirmation email.
+ *
+ * The dynamic fields are discovered without parsing types: the component is
+ * rendered with a Proxy whose every prop read returns the literal `{{prop}}`
+ * and records the name, so `({name}) => <h1>Hi {name}` renders `Hi {{name}}`
+ * and we learn the field is `name`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { createServer } from 'vite';
+
+import type { ResolvedToilConfig } from './config.js';
+import { createViteConfig } from './vite.js';
+
+/** What an `emails/*.tsx` module may export. `default` is the React component. */
+interface EmailModule {
+    default: unknown;
+    /** Subject line, a token template (e.g. `'Welcome, {{name}}'`). Defaults to the name. */
+    subject?: unknown;
+    /** Optional plain-text body template; derived by stripping the HTML when absent. */
+    text?: unknown;
+    /** Optional dedup/abuse `purpose` tag; defaults to the email name lowercased. */
+    purpose?: unknown;
+}
+
+/** One email rendered to its baked, token-holed parts. */
+interface RenderedEmail {
+    name: string;
+    subject: string;
+    html: string;
+    text: string;
+    /** Sorted, unique `{{token}}` field names this email interpolates. */
+    tokens: string[];
+    purpose: string;
+}
+
+/** Keys React (or the renderer) reads on props that must never become tokens. */
+const REACT_INTERNAL = new Set([
+    'children',
+    'key',
+    'ref',
+    '$$typeof',
+    '__self',
+    '__source',
+    'toJSON',
+    'prototype',
+    'constructor',
+    'then', // so a thenable check never tokenizes
+]);
+
+const TOKEN_RE = /\{\{\s*([A-Za-z_$][\w$]*)\s*\}\}/g;
+
+function extractTokens(s: string): string[] {
+    const out: string[] = [];
+    let m: RegExpExecArray | null;
+    TOKEN_RE.lastIndex = 0;
+    while ((m = TOKEN_RE.exec(s)) !== null) out.push(m[1]!);
+    return out;
+}
+
+/**
+ * A props object whose every (non-internal) read returns the literal `{{key}}`
+ * and records `key`. Renders the component with placeholders and discovers the
+ * field names in one pass — no TS type parsing.
+ */
+function tokenProps(seen: Set<string>): Record<string, unknown> {
+    return new Proxy(
+        {},
+        {
+            get(_target, key): unknown {
+                if (typeof key !== 'string' || REACT_INTERNAL.has(key)) return undefined;
+                seen.add(key);
+                return `{{${key}}}`;
+            },
+        },
+    );
+}
+
+/** Inline `<style>`/CSS into element `style=""` (juice) so email clients honor it.
+ *  Optional: without juice installed, inline `style={{}}` props still work. */
+async function inlineCss(html: string): Promise<string> {
+    try {
+        // Variable specifier: keep `juice` an OPTIONAL dependency (tsc won't
+        // require its types, and a missing install falls back below).
+        const specifier = 'juice';
+        const mod = (await import(specifier)) as { default: (html: string) => string };
+        return mod.default(html);
+    } catch {
+        return html;
+    }
+}
+
+/** A crude HTML→text fallback for the plain-text part (better deliverability). */
+function htmlToText(html: string): string {
+    return html
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        .replace(/<(?:br|\/p|\/h[1-6]|\/tr|\/div)\s*\/?>/gi, '\n')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&#x27;|&#39;/g, "'")
+        .replace(/&quot;|&#34;/g, '"')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&') // last: so "&amp;lt;" -> "&lt;", not "<"
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/[ \t]*\n[ \t]*/g, '\n')
+        .trim();
+}
+
+/** Render one loaded email module to its baked parts, or `null` if it has no
+ *  component. The default export must be a FUNCTION component (not a class) of
+ *  its props: we call it directly with the token Proxy and render the element
+ *  tree it returns. Going through `createElement(Component, proxy)` would not
+ *  work -- React copies the config into a plain props object, so the component
+ *  would never see the Proxy and every field would render empty. */
+async function renderModule(
+    name: string,
+    mod: EmailModule,
+    render: (el: unknown) => string,
+): Promise<RenderedEmail | null> {
+    if (typeof mod.default !== 'function') return null;
+
+    const seen = new Set<string>();
+    const component = mod.default as (props: unknown) => unknown;
+    let html = render(component(tokenProps(seen)));
+    html = await inlineCss(html);
+
+    const subject = typeof mod.subject === 'string' ? mod.subject : name;
+    const text = typeof mod.text === 'string' ? mod.text : htmlToText(html);
+    const purpose =
+        typeof mod.purpose === 'string' && mod.purpose.length > 0
+            ? mod.purpose
+            : name.toLowerCase();
+
+    // Union the proxy-observed fields with any literal {{token}} authored in the
+    // subject/text/html, so a hand-written placeholder is also a parameter.
+    const tokens = [
+        ...new Set([
+            ...seen,
+            ...extractTokens(subject),
+            ...extractTokens(html),
+            ...extractTokens(text),
+        ]),
+    ].sort();
+
+    return { name, subject, html, text, tokens, purpose };
+}
+
+/** `welcome-email` / `welcome_email` -> `WelcomeEmail`. */
+function toPascal(base: string): string {
+    return base
+        .split(/[-_\s.]+/)
+        .filter(Boolean)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join('');
+}
+
+/** Server source dir (where the generated module must live to be compiled): the
+ *  dir of the first toilconfig entry, else `<root>/server`. */
+function serverDir(root: string): string {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
+            entries?: unknown;
+        };
+        const first = Array.isArray(cfg.entries)
+            ? cfg.entries.find((e): e is string => typeof e === 'string')
+            : undefined;
+        if (first) return path.dirname(path.resolve(root, first));
+    } catch {
+        // fall through to the default
+    }
+    return path.join(root, 'server');
+}
+
+/** A valid AS/JS string literal for `s` (double-quoted, fully escaped). */
+function asLit(s: string): string {
+    return JSON.stringify(s);
+}
+
+/** A unique, valid AS parameter identifier for `token`, avoiding the fixed
+ *  `to`/`purpose` params, AS keywords, and earlier tokens. */
+function paramName(token: string, used: Set<string>): string {
+    const RESERVED = new Set(['to', 'purpose', 'class', 'function', 'new', 'this', 'type', 'in']);
+    let p = token;
+    while (used.has(p) || RESERVED.has(p)) p = p + '_';
+    used.add(p);
+    return p;
+}
+
+/** Codegen the `Emails` AssemblyScript module from the rendered set. */
+function renderModuleSource(rendered: RenderedEmail[]): string {
+    const out: string[] = [];
+    out.push('// GENERATED by toiljs from emails/*.tsx -- DO NOT EDIT.');
+    out.push('// Each email is rendered to static, inline-CSS HTML at build time;');
+    out.push('// {{tokens}} are filled per send. `EmailTemplate`/`EmailStatus` are');
+    out.push('// toiljs globals (server/globals/email.ts), so no import is needed.');
+    out.push('');
+    out.push('export namespace Emails {');
+    for (const e of rendered) {
+        out.push(`  export namespace ${e.name} {`);
+        out.push(`    const SUBJECT: string = ${asLit(e.subject)};`);
+        out.push(`    const TEXT: string = ${asLit(e.text)};`);
+        out.push(`    const HTML: string = ${asLit(e.html)};`);
+        const used = new Set<string>();
+        const params = e.tokens.map((t) => ({ token: t, param: paramName(t, used) }));
+        const sig = ['to: string']
+            .concat(params.map((p) => `${p.param}: string`))
+            .concat(`purpose: string = ${asLit(e.purpose)}`)
+            .join(', ');
+        out.push(`    /** Render and send this email to \`to\`. Returns the send's EmailStatus. */`);
+        out.push(`    export function send(${sig}): EmailStatus {`);
+        out.push(`      const __v = new Map<string, string>();`);
+        for (const p of params) out.push(`      __v.set(${asLit(p.token)}, ${p.param});`);
+        out.push(`      return new EmailTemplate(SUBJECT, TEXT, HTML).send(to, __v, purpose);`);
+        out.push(`    }`);
+        out.push(`  }`);
+    }
+    out.push('}');
+    return out.join('\n') + '\n';
+}
+
+const GENERATED_BASENAME = '_emails.ts';
+
+function warn(msg: string): void {
+    process.stderr.write(`  toil: emails ${msg}\n`);
+}
+
+/**
+ * Render every `emails/*.tsx` and (re)write the generated `<server>/_emails.ts`
+ * module, BEFORE the toilscript server build so it is compiled in. A no-op when
+ * there is no `emails/` directory. Removes a stale generated module when the
+ * directory becomes empty.
+ */
+export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
+    const emailsDir = path.join(cfg.root, 'emails');
+    const generatedPath = path.join(serverDir(cfg.root), GENERATED_BASENAME);
+
+    if (!fs.existsSync(emailsDir)) return;
+    const files = fs
+        .readdirSync(emailsDir)
+        .filter((f) => /\.(tsx|jsx)$/.test(f))
+        .sort();
+    if (files.length === 0) {
+        if (fs.existsSync(generatedPath)) fs.rmSync(generatedPath);
+        return;
+    }
+
+    // React DOM is only needed when a project actually has emails; load it
+    // lazily so a server-only project without emails never pays for it.
+    const { renderToStaticMarkup } = await import('react-dom/server');
+
+    const server = await createServer({
+        ...(await createViteConfig(cfg)),
+        server: { middlewareMode: true, hmr: false },
+        appType: 'custom',
+        logLevel: 'silent',
+    });
+
+    const rendered: RenderedEmail[] = [];
+    try {
+        for (const file of files) {
+            const name = toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, ''));
+            let mod: EmailModule;
+            try {
+                mod = (await server.ssrLoadModule(path.join(emailsDir, file))) as EmailModule;
+            } catch (err) {
+                warn(`skipped ${file} (${err instanceof Error ? err.message : String(err)})`);
+                continue;
+            }
+            const r = await renderModule(name, mod, renderToStaticMarkup as (el: unknown) => string);
+            if (r) rendered.push(r);
+            else warn(`skipped ${file} (no default-exported component)`);
+        }
+    } finally {
+        await server.close();
+    }
+
+    if (rendered.length === 0) return;
+    // Only (re)write when the output actually changed: an unconditional write
+    // bumps the file's mtime every rebuild, which under `dev` would re-trigger
+    // the watcher. (The watcher also ignores this file by name; this is belt-and-
+    // suspenders and avoids needless work.)
+    const next = renderModuleSource(rendered);
+    const prev = fs.existsSync(generatedPath) ? fs.readFileSync(generatedPath, 'utf8') : null;
+    if (prev === next) return;
+    fs.mkdirSync(path.dirname(generatedPath), { recursive: true });
+    fs.writeFileSync(generatedPath, next);
+    process.stdout.write(
+        `  ✓ emails: generated ${String(rendered.length)} template${rendered.length === 1 ? '' : 's'} (${rendered
+            .map((r) => r.name)
+            .join(', ')})\n`,
+    );
+}
+
+// Exported for unit testing the pure render/codegen without a Vite server.
+export const __test = { renderModule, renderModuleSource, tokenProps, htmlToText, toPascal };

package/src/compiler/generate.ts

@@ -107,7 +107,18 @@ export const TOIL_SERVER_ENV_DTS =
     `declare const Cookies: typeof import('toiljs/server/runtime/http/cookies').Cookies;\n` +
     `type Cookies = import('toiljs/server/runtime/http/cookies').Cookies;\n` +
     `declare const SecureCookies: typeof import('toiljs/server/runtime/http/securecookies').SecureCookies;\n` +
-    `type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;\n`;
+    `type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;\n` +
+    `// Email, rate-limit, 2FA, and auth globals (server/globals/*), hand-declared\n` +
+    `// because their AssemblyScript source can't be type-aliased from tsc.\n` +
+    `declare enum EmailStatus { Sent, Disabled, Budget, RecipientCapped, Deduped, TryLater, BadRecipient, ProviderError }\n` +
+    `declare namespace EmailService { function send(to: string, subject: string, body: string, purpose?: string, html?: string): EmailStatus; }\n` +
+    `declare class RenderedEmail { subject: string; body: string; html: string; constructor(subject: string, body: string, html: string); }\n` +
+    `declare class EmailTemplate { constructor(subject: string, body: string, html?: string); render(vars: Map<string, string>): RenderedEmail; send(to: string, vars: Map<string, string>, purpose?: string): EmailStatus; }\n` +
+    `declare enum RateLimit { FixedWindow, SlidingWindow, TokenBucket }\n` +
+    `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +
+    `declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }\n` +
+    `declare namespace TwoFactor { function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }\n` +
+    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n`;
 
 /**
  * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use

package/src/compiler/index.ts

@@ -11,7 +11,8 @@ import { build as viteBuild, createServer, mergeConfig, type ViteDevServer } fro
 // lazily; `create`/`build`/`doctor` must never touch the native binary.
 import type { RunningBackend } from 'toiljs/backend';
 
-import { loadConfig } from './config.js';
+import { loadConfig, type ResolvedToilConfig } from './config.js';
+import { renderEmails } from './emails.js';
 import { generate, TOIL_SERVER_ENV_DTS } from './generate.js';
 import { prerenderStaticParams } from './ssg.js';
 import { extractTemplates } from './template-build.js';
@@ -165,9 +166,11 @@ async function buildServer(root: string): Promise<void> {
  * delivering events on Linux after editors replace files via rename, which left hot reload
  * working exactly once. A no-op for client-only projects.
  */
-function watchServer(root: string, watcher: ViteDevServer['watcher']): void {
+function watchServer(cfg: ResolvedToilConfig, watcher: ViteDevServer['watcher']): void {
+    const root = cfg.root;
     const dirs = serverDirs(root);
     if (dirs.length === 0) return;
+    const emailsDir = path.join(root, 'emails');
 
     let building = false;
     let queued = false;
@@ -178,7 +181,10 @@ function watchServer(root: string, watcher: ViteDevServer['watcher']): void {
         }
         building = true;
         process.stdout.write(pc.dim('  server changed, rebuilding…') + '\n');
-        buildServer(root)
+        // Recompile emails/*.tsx -> the generated module before the server build,
+        // so editing an email template hot-reloads like any other server change.
+        renderEmails(cfg)
+            .then(() => buildServer(root))
             .then(() => process.stdout.write(pc.green('  ✓ ') + pc.dim('server rebuilt') + '\n'))
             .catch((e: unknown) =>
                 process.stdout.write(pc.red(`  ✗ server rebuild failed: ${String(e)}`) + '\n'),
@@ -196,10 +202,15 @@ function watchServer(root: string, watcher: ViteDevServer['watcher']): void {
     const isServerSource = (file: string): boolean =>
         file.endsWith('.ts') &&
         !file.endsWith('.d.ts') &&
+        // `_emails.ts` is GENERATED by renderEmails on every rebuild; reacting to
+        // our own output would loop forever (rebuild -> write -> rebuild -> ...).
+        path.basename(file) !== '_emails.ts' &&
         dirs.some((dir) => file === dir || file.startsWith(dir + path.sep));
-    watcher.add(dirs);
+    const isEmailSource = (file: string): boolean =>
+        /\.(tsx|jsx)$/.test(file) && (file === emailsDir || file.startsWith(emailsDir + path.sep));
+    watcher.add([...dirs, emailsDir]);
     watcher.on('all', (_event, file) => {
-        if (!isServerSource(file)) return;
+        if (!isServerSource(file) && !isEmailSource(file)) return;
         if (timer) clearTimeout(timer);
         timer = setTimeout(rebuild, 150); // debounce bursts (save-all, formatters)
     });
@@ -260,6 +271,8 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     // Server first: build it (regenerating shared/server.ts) before the client dev server starts.
     const hasServer = fs.existsSync(path.join(cfg.root, 'toilconfig.json'));
     if (hasServer) process.stdout.write(pc.dim('  building the server (toilscript)…') + '\n');
+    // Compile emails/*.tsx -> generated server module BEFORE toilscript builds it in.
+    await renderEmails(cfg);
     await buildServer(cfg.root);
     if (hasServer) process.stdout.write(pc.green('  ✓ ') + pc.dim('server built') + '\n');
     generate(cfg);
@@ -302,7 +315,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
 
     // Rebuild the server on server-file changes; Vite HMRs the regenerated shared/server.ts
     // and the dev server hot-swaps the recompiled wasm module.
-    watchServer(cfg.root, server.watcher);
+    watchServer(cfg, server.watcher);
     return server;
 }
 
@@ -316,6 +329,8 @@ export async function build(opts: ToilCommandOptions = {}): Promise<void> {
     const hasServer = fs.existsSync(path.join(cfg.root, 'toilconfig.json'));
     if (hasServer && !opts.serverOnly)
         process.stdout.write(pc.dim('  building the server (toilscript)…') + '\n');
+    // Compile emails/*.tsx -> generated server module BEFORE toilscript builds it in.
+    await renderEmails(cfg);
     await buildServer(cfg.root);
     if (opts.serverOnly) return;
     if (hasServer)

package/src/devserver/envelope.ts

@@ -41,6 +41,9 @@ export interface EnvelopeRequest {
     /** Full request header list, passed through to the guest. */
     readonly headers: readonly (readonly [string, string])[];
     readonly body: Uint8Array;
+    /** The connecting client's IP for the `client_ip` import / `ctx.clientIp()`.
+     *  The edge uses the unspoofable socket peer; the dev server best-efforts it. */
+    readonly clientIp?: string;
 }
 
 /** The decoded guest response envelope. */

package/src/devserver/host.ts

@@ -18,6 +18,7 @@
  */
 
 import { buildCryptoImports, freshCryptoState, type CryptoState } from './crypto.js';
+import { ratelimitCheck } from './ratelimit.js';
 
 /** Limits identical to the edge's `set_header` / `respond_file` bounds. */
 const MAX_TOTAL_HEADERS_BYTES = 64 * 1024;
@@ -49,13 +50,23 @@ export interface DispatchState {
     headerBytes: number;
     /** File path from `respond_file`, or `null`; when set, the envelope body is ignored. */
     sendfile: string | null;
+    /** The connecting client's IP for `client_ip` (the edge uses the socket peer);
+     *  set per dispatch from the Node request's `socket.remoteAddress`, '' if unknown. */
+    clientIp: string;
     /** Per-dispatch Web Crypto keystore + result scratch (mirrors the edge). */
     crypto: CryptoState;
 }
 
 /** A fresh, zeroed per-dispatch state (the edge resets the same way before each request). */
 export function freshDispatchState(): DispatchState {
-    return { status: null, headers: [], headerBytes: 0, sendfile: null, crypto: freshCryptoState() };
+    return {
+        status: null,
+        headers: [],
+        headerBytes: 0,
+        sendfile: null,
+        clientIp: '',
+        crypto: freshCryptoState(),
+    };
 }
 
 /**
@@ -135,6 +146,60 @@ export function buildHostImports(ref: MemoryRef, state: DispatchState): WebAssem
                 state.sendfile = readBytes(ref, pathPtr, pathLen).toString('utf8');
             },
 
+            // Write the client's IP (set per dispatch from the connection's
+            // remote address) into the guest buffer. Returns the byte length,
+            // 0 if unknown, -1 if the buffer is too small. Mirrors the edge's
+            // `client_ip_import.rs`.
+            client_ip: (outPtr: number, cap: number): number => {
+                const ip = state.clientIp;
+                if (ip.length === 0) return 0;
+                const bytes = Buffer.from(ip, 'utf8');
+                if (bytes.length > cap) return -1;
+                const m = mem(ref);
+                if (outPtr < 0 || outPtr + bytes.length > m.length)
+                    throw new Error('client_ip write out of bounds');
+                bytes.copy(m, outPtr);
+                return bytes.length;
+            },
+
+            // `@ratelimit` decorator hook. Accounts one event for this request
+            // against the dev limiter, keyed on the explicit guest key when
+            // given (`keyLen > 0`), else the client IP. Returns the remaining
+            // budget (>= 0, allowed) or a negative `Retry-After` in seconds
+            // (denied). Mirrors the edge's `ratelimit_check_import.rs`.
+            ratelimit_check: (
+                routeId: number,
+                strategy: number,
+                limit: number,
+                window: number,
+                keyPtr: number,
+                keyLen: number,
+            ): number => {
+                const identity =
+                    keyLen > 0
+                        ? readBytes(ref, keyPtr, keyLen).toString('utf8')
+                        : state.clientIp || '0';
+                const d = ratelimitCheck(routeId, strategy, limit, window, identity, Date.now());
+                return d.allowed ? 1 : -Math.max(1, d.retryAfterSecs);
+            },
+
+            // `env::email_send`: the dev server has no email provider, so it
+            // parses the recipient for a log line and reports Sent (0), the same
+            // i32 contract the edge returns. The suspension is a host-side concern
+            // on the edge (call_async); the wasm just sees an i32 either way.
+            email_send: (reqPtr: number, reqLen: number): number => {
+                // Header: u16 to_len | u16 subj_len | u16 purpose_len | u32 body_len
+                // | u32 html_len (14 bytes), then payloads; `to` is first.
+                const raw = readBytes(ref, reqPtr, reqLen);
+                let to = '<unparsed>';
+                if (raw.length >= 14) {
+                    const toLen = raw.readUInt16LE(0);
+                    if (14 + toLen <= raw.length) to = raw.toString('utf8', 14, 14 + toLen);
+                }
+                process.stdout.write(`  ✉ dev email_send -> ${to} (not actually sent)\n`);
+                return 0; // EmailStatus.Sent
+            },
+
             thread_spawn: (_startArg: number): number => -1,
 
             // `Date.now()` -> wall-clock milliseconds, matching the edge host.

package/src/devserver/index.ts

@@ -108,12 +108,19 @@ function resolveSendfile(root: string, file: string): string | null {
 async function toEnvelopeRequest(request: Request): Promise<EnvelopeRequest> {
     const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
     const body = hasBody ? new Uint8Array(await request.buffer()) : new Uint8Array(0);
+    // Dev parity for `client_ip`: the edge keys on the unspoofable socket peer,
+    // but the dev server has no DPDK socket, so best-effort from a proxy's
+    // `x-forwarded-for`, else localhost, so `ctx.clientIp()` returns a value.
+    const xff = request.headers['x-forwarded-for'];
+    const clientIp =
+        typeof xff === 'string' && xff.length > 0 ? xff.split(',')[0]!.trim() : '127.0.0.1';
     return {
         method: request.method,
         // `url` keeps the query string; the guest's RouteContext parses it off the path.
         path: request.url,
         headers: Object.entries(request.headers),
         body,
+        clientIp,
     };
 }
 

package/src/devserver/module.ts

@@ -53,6 +53,7 @@ interface HandleExports {
 /** Host functions the dev server provides under `env` (see `host.ts`). */
 const PROVIDED_IMPORTS = new Set([
     'abort', 'set_status', 'set_header', 'respond_file', 'thread_spawn', 'Date.now',
+    'client_ip', 'ratelimit_check', 'email_send',
     // Web Crypto host functions (see ./crypto.ts).
     'crypto.fill_random', 'crypto.random_uuid', 'crypto.take_result', 'crypto.digest',
     'crypto.import_key', 'crypto.export_key', 'crypto.encrypt', 'crypto.decrypt',
@@ -109,6 +110,7 @@ export class WasmServerModule {
 
         const ref: MemoryRef = { memory: null };
         const state = freshDispatchState();
+        state.clientIp = req.clientIp ?? '';
         const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
         const exports = instance.exports as unknown as HandleExports;
         ref.memory = exports.memory;
@@ -165,6 +167,7 @@ export class WasmServerModule {
         const envelope = encodeRequestEnvelope(req);
         const ref: MemoryRef = { memory: null };
         const state = freshDispatchState();
+        state.clientIp = req.clientIp ?? '';
         const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
         const exports = instance.exports as unknown as HandleExports & {
             render?: (reqOfs: number, reqLen: number) => bigint;

package/src/devserver/ratelimit.ts

@@ -0,0 +1,116 @@
+/**
+ * Dev-server rate limiter: a single-process mirror of the edge's
+ * `toil-backend/src/ratelimit.rs` strategies, so a tenant using the
+ * `@ratelimit(...)` decorator behaves the same under `toiljs dev` as on the
+ * edge. The edge runs an EXACT limiter shared across 14 workers; dev is one
+ * process, so a plain module-level registry is already "global".
+ *
+ * State lives here (module scope), NOT in the per-request DispatchState, because
+ * a limiter must persist across requests (the dev server builds a fresh wasm
+ * instance per request, exactly like the edge pools).
+ */
+
+/** Mirror of the host's strategy tags (`Strategy` in `ratelimit.rs`). */
+export const STRATEGY_FIXED = 0;
+export const STRATEGY_SLIDING = 1;
+export const STRATEGY_TOKEN_BUCKET = 2;
+
+interface KeyState {
+    /** Token bucket: tokens * 1000 (sub-token refill without floats). */
+    tokensMilli: number;
+    /** Window strategies: aligned index of the current bucket. */
+    window: number;
+    cur: number;
+    prev: number;
+    lastMs: number;
+}
+
+interface RouteLimiter {
+    strategy: number;
+    /** `limit`/`window_secs` for windows; `burst`/`refill_per_sec` for the bucket. */
+    a: number;
+    b: number;
+    keys: Map<string, KeyState>;
+}
+
+/** `(routeId) -> limiter`, created lazily with the route's first-seen params. */
+const registry = new Map<number, RouteLimiter>();
+
+export interface DevDecision {
+    allowed: boolean;
+    /** Whole seconds to wait before retrying (>= 1 when denied, 0 when allowed). */
+    retryAfterSecs: number;
+}
+
+/**
+ * Account one event for `identity` against route `routeId` and return the
+ * verdict. Mirrors `SharedLimiter::check` semantics. `now` is wall-clock ms
+ * (`Date.now()`), which is fine for a single dev process.
+ */
+export function ratelimitCheck(
+    routeId: number,
+    strategy: number,
+    limit: number,
+    window: number,
+    identity: string,
+    now: number,
+): DevDecision {
+    let rl = registry.get(routeId);
+    if (rl === undefined) {
+        rl = { strategy, a: Math.max(1, limit), b: Math.max(1, window), keys: new Map() };
+        registry.set(routeId, rl);
+    }
+    if (rl.strategy === STRATEGY_TOKEN_BUCKET) return checkBucket(rl, identity, now);
+    return checkWindow(rl, identity, now, rl.strategy === STRATEGY_SLIDING);
+}
+
+function checkBucket(rl: RouteLimiter, key: string, now: number): DevDecision {
+    const capMilli = rl.a * 1000;
+    const refillPerSec = rl.b;
+    let st = rl.keys.get(key);
+    if (st === undefined) {
+        st = { tokensMilli: capMilli, window: 0, cur: 0, prev: 0, lastMs: now };
+        rl.keys.set(key, st);
+    }
+    const elapsed = Math.max(0, now - st.lastMs);
+    st.tokensMilli = Math.min(capMilli, st.tokensMilli + elapsed * refillPerSec);
+    st.lastMs = now;
+    if (st.tokensMilli >= 1000) {
+        st.tokensMilli -= 1000;
+        return { allowed: true, retryAfterSecs: 0 };
+    }
+    const needed = 1000 - st.tokensMilli;
+    const waitMs = Math.ceil(needed / refillPerSec);
+    return { allowed: false, retryAfterSecs: Math.max(1, Math.ceil(waitMs / 1000)) };
+}
+
+function checkWindow(rl: RouteLimiter, key: string, now: number, sliding: boolean): DevDecision {
+    const limit = rl.a;
+    const windowMs = rl.b * 1000;
+    const curWindow = Math.floor(now / windowMs);
+    let st = rl.keys.get(key);
+    if (st === undefined) {
+        st = { tokensMilli: 0, window: curWindow, cur: 0, prev: 0, lastMs: now };
+        rl.keys.set(key, st);
+    }
+    if (curWindow === st.window + 1) {
+        st.prev = st.cur;
+        st.cur = 0;
+        st.window = curWindow;
+    } else if (curWindow > st.window) {
+        st.prev = 0;
+        st.cur = 0;
+        st.window = curWindow;
+    }
+    st.lastMs = now;
+    const posInWindow = now % windowMs;
+    const effective = sliding
+        ? Math.floor((st.prev * (windowMs - posInWindow)) / windowMs) + st.cur
+        : st.cur;
+    if (effective < limit) {
+        st.cur += 1;
+        return { allowed: true, retryAfterSecs: 0 };
+    }
+    const waitMs = windowMs - posInWindow;
+    return { allowed: false, retryAfterSecs: Math.max(1, Math.ceil(waitMs / 1000)) };
+}