toiljs 0.0.115 → 0.0.117

package/src/devserver/config/env.ts

@@ -1,30 +0,0 @@
-/**
- * Dev-only source for `Environment.get` / `getSecure`, mirroring the edge's
- * per-tenant env store. Reads two optional dotenv files at the project root via
- * the shared loader (`./dotenv.ts`):
- *
- *   - `.env`          -> plain vars  (`Environment.get`); `process.env` overlays
- *   - `.env.secrets`  -> secrets     (`Environment.getSecure`); keep gitignored
- *
- * DISJOINT like the edge: `get` sees only vars, `getSecure` only secrets, so a
- * secret never comes back through `get`. Framework-reserved `TOIL_*` keys are
- * host-only (the email backend config reads them) and never a tenant var/secret.
- *
- * Cached after first read; restart `toiljs dev` to pick up edits. The edge
- * resolves this PER TENANT from `$TOIL_ENV_DIR/<host>.env` + `<host>.env.secrets`
- * (and the edge DB later) through a lazy, bounded cache; dev has a single
- * project, so two files are enough and no eviction is needed.
- */
-import { loadEnvFiles } from './dotenv.js';
-
-/** A plain var by exact key, or `null`. Reads ONLY the `.env` (vars) bucket. */
-export function devEnvGet(key: string): string | null {
-    const v = loadEnvFiles(process.cwd()).vars.get(key);
-    return v === undefined ? null : v;
-}
-
-/** A secret by exact key, or `null`. Reads ONLY the `.env.secrets` bucket. */
-export function devEnvGetSecure(key: string): string | null {
-    const v = loadEnvFiles(process.cwd()).secrets.get(key);
-    return v === undefined ? null : v;
-}

package/src/devserver/config/ratelimit.ts

@@ -1,123 +0,0 @@
-/**
- * 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>();
-
-/** Drop all limiter state (tests). Each dev wasm dispatch shares this module-level
- *  registry, so a test that fires many `@ratelimit`-decorated routes in one file
- *  would otherwise carry counts across cases; reset between cases for isolation. */
-export function __resetRatelimitForTests(): void {
-    registry.clear();
-}
-
-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)) };
-}

package/src/devserver/daemon/catalog.ts

@@ -1,120 +0,0 @@
-/**
- * Parse a compiled COLD server wasm's `toildaemon.catalog` custom section into the
- * dev daemon scheduler's task list. Emitted by the toilscript cold pass
- * (`buildToilDaemonCatalog`) into `release-cold.wasm` when a `@daemon` class
- * exists. Cron schedules are PRECOMPUTED BITMASKS (RECONCILIATION F6): the reader
- * does bit tests, NEVER a runtime cron-string parse.
- *
- * Byte layout (RECONCILIATION Part 5, all little-endian; mirrors the toilscript
- * `CatWriter` emitter byte-for-byte):
- *
- *   u16 format_version = 1
- *   u8  has_daemon
- *   u16 n_scheduled
- *   per task:
- *     str name                  (u32 len + UTF-8)
- *     u16 task_index            (the scheduled_tick(task_id) argument)
- *     u8  schedule_kind         (0 = interval, 1 = cron)
- *     u64 interval_ms           (used when schedule_kind = 0, else 0)
- *     u64 cron_minute_mask      (bits 0..59)
- *     u32 cron_hour_mask        (bits 0..23)
- *     u32 cron_dom_mask         (bits 1..31)
- *     u16 cron_month_mask       (bits 1..12)
- *     u8  cron_dow_mask         (bits 0..6)
- *     u8  overlap_policy        (0 = skip-if-running)
- *     u8  catchup_policy        (0 = no-backfill)
- *     u64 gas_hint
- *
- * Fails closed via `DataReader.ok`: a short read mid-record stops the loop and
- * yields only the cleanly-decoded prefix, never over-reading. An absent or wholly
- * unparseable section returns `null`, so the daemon emulator simply does not start
- * (fail-closed = never run an unknown daemon).
- */
-
-import { DataReader } from 'toiljs/io';
-
-import { customSection } from '../wasm/sections.js';
-
-/** The five precomputed cron field bitmasks (RECONCILIATION Part 5 / F6). */
-export interface CronMasks {
-    /** u64, bits 0..59 (one per minute). */
-    readonly minute: bigint;
-    /** u32, bits 0..23 (one per hour). */
-    readonly hour: number;
-    /** u32, bits 1..31 (one per day-of-month). */
-    readonly dom: number;
-    /** u16, bits 1..12 (one per month). */
-    readonly month: number;
-    /** u8, bits 0..6 (one per day-of-week, 0 = Sunday). */
-    readonly dow: number;
-}
-
-/** One `@scheduled` task the dev scheduler drives. */
-export interface ScheduledTask {
-    readonly name: string;
-    /** The `scheduled_tick(task_id)` argument; equals declaration order. */
-    readonly taskIndex: number;
-    readonly schedule:
-        | { readonly kind: 'interval'; readonly ms: number }
-        | { readonly kind: 'cron'; readonly masks: CronMasks };
-    /** 0 = skip-if-running (the at-most-once default). */
-    readonly overlapPolicy: number;
-    /** 0 = no-backfill (the at-most-once default). */
-    readonly catchupPolicy: number;
-    readonly gasHint: bigint;
-}
-
-export interface DaemonCatalog {
-    readonly hasDaemon: boolean;
-    readonly tasks: readonly ScheduledTask[];
-}
-
-export function parseDaemonCatalog(wasm: Buffer): DaemonCatalog | null {
-    let sec: Buffer | null;
-    try {
-        sec = customSection(wasm, 'toildaemon.catalog');
-    } catch {
-        return null; // garbage section table (mid-rebuild) -> no daemon
-    }
-    if (sec === null) return null;
-
-    const r = new DataReader(sec);
-    r.readU16(); // format_version
-    const hasDaemon = r.readU8() === 1;
-    const n = r.readU16(); // n_scheduled
-    // The 5-byte header must read cleanly; a short read here is a garbage section
-    // (fail closed -> no daemon). A `hasDaemon` byte salvaged from a too-short
-    // version field is not trustworthy.
-    if (!r.ok) return null;
-    const tasks: ScheduledTask[] = [];
-    for (let i = 0; i < n && r.ok; i++) {
-        const name = r.readString();
-        const taskIndex = r.readU16();
-        const kind = r.readU8(); // schedule_kind: 0 = interval, 1 = cron
-        const intervalMs = r.readU64(); // bigint; 0 when kind = 1
-        const minute = r.readU64(); // cron_minute_mask (bits 0..59)
-        const hour = r.readU32(); // cron_hour_mask
-        const dom = r.readU32(); // cron_dom_mask
-        const month = r.readU16(); // cron_month_mask
-        const dow = r.readU8(); // cron_dow_mask
-        const overlapPolicy = r.readU8();
-        const catchupPolicy = r.readU8();
-        const gasHint = r.readU64();
-        if (r.ok)
-            tasks.push({
-                name,
-                taskIndex,
-                schedule:
-                    kind === 1
-                        ? { kind: 'cron', masks: { minute, hour, dom, month, dow } }
-                        : { kind: 'interval', ms: Number(intervalMs) },
-                overlapPolicy,
-                catchupPolicy,
-                gasHint,
-            });
-    }
-    // A section that decoded nothing AND claims no daemon is indistinguishable
-    // from garbage -> fail closed (no daemon).
-    if (!r.ok && tasks.length === 0 && !hasDaemon) return null;
-    return { hasDaemon, tasks };
-}

package/src/devserver/daemon/cron.ts

@@ -1,87 +0,0 @@
-/**
- * Cron BITMASK evaluation for the dev daemon scheduler. The catalog carries five
- * precomputed bitmasks (RECONCILIATION F6 / Part 5); this module does bit tests
- * against a wall-clock minute, NEVER a cron-string parse. The bit semantics match
- * the toilscript emitter (`expandCronField` in `dbcatalog.ts`):
- *
- *   minute  bits 0..59   hour bits 0..23   dom bits 1..31
- *   month   bits 1..12   dow  bits 0..6 (0 = Sunday)
- *
- * Standard cron semantics for day-of-month vs day-of-week: when BOTH fields are
- * restricted (not all bits set) the match is the UNION (either matches); when one
- * is unrestricted it does not constrain. The dev evaluator walks forward
- * minute-by-minute from "now" to the next matching minute, exactly as the edge
- * evaluates the same masks.
- */
-
-import type { CronMasks } from './catalog.js';
-
-/** All 60 minute bits set (bits 0..59). A field the emitter left fully open. */
-const ALL_MINUTES = (1n << 60n) - 1n;
-/** All 24 hour bits set (bits 0..23). */
-const ALL_HOURS = (1 << 24) - 1;
-/** dom bits 1..31 all set (bit 0 unused). `1 << 32` overflows in JS, so spell it. */
-const ALL_DOM = 0xfffffffe;
-/** month bits 1..12 all set (bit 0 unused). */
-const ALL_MONTH = ((1 << 13) - 1) & ~1;
-/** dow bits 0..6 all set. */
-const ALL_DOW = (1 << 7) - 1;
-
-function minuteBit(masks: CronMasks, minute: number): boolean {
-    return (masks.minute & (1n << BigInt(minute))) !== 0n;
-}
-
-/** True when every cron field's bit is set for `date`'s local-time components. */
-export function cronMatches(masks: CronMasks, date: Date): boolean {
-    if (!minuteBit(masks, date.getMinutes())) return false;
-    if ((masks.hour & (1 << date.getHours())) === 0) return false;
-    if ((masks.month & (1 << date.getMonth() + 1)) === 0) return false;
-
-    // dom/dow union rule (POSIX cron): if both are restricted, either may match.
-    const domRestricted = (masks.dom & ALL_DOM) !== ALL_DOM;
-    const dowRestricted = (masks.dow & ALL_DOW) !== ALL_DOW;
-    const domHit = (masks.dom & (1 << date.getDate())) !== 0;
-    const dowHit = (masks.dow & (1 << date.getDay())) !== 0;
-    if (domRestricted && dowRestricted) {
-        if (!domHit && !dowHit) return false;
-    } else if (domRestricted) {
-        if (!domHit) return false;
-    } else if (dowRestricted) {
-        if (!dowHit) return false;
-    }
-    return true;
-}
-
-/** True when a mask can never fire (all-zero) -> the schedule is rejected. */
-export function cronNeverFires(masks: CronMasks): boolean {
-    return (
-        (masks.minute & ALL_MINUTES) === 0n ||
-        (masks.hour & ALL_HOURS) === 0 ||
-        (masks.month & ALL_MONTH) === 0 ||
-        // dom OR dow must be able to fire (union); both empty => never.
-        ((masks.dom & ALL_DOM) === 0 && (masks.dow & ALL_DOW) === 0)
-    );
-}
-
-/**
- * The epoch-ms of the next minute (strictly after `fromMs`) whose components all
- * pass the masks, walking forward minute-by-minute. Returns `null` when no match
- * is found within `horizonMinutes` (a safety bound; an all-zero mask is caught by
- * {@link cronNeverFires} before this is called). Fires land on the :00 second of
- * the matching minute.
- */
-export function nextCronFireMs(
-    masks: CronMasks,
-    fromMs: number,
-    horizonMinutes = 366 * 24 * 60,
-): number | null {
-    // Start at the next whole minute boundary strictly after `fromMs`.
-    const d = new Date(fromMs);
-    d.setSeconds(0, 0);
-    d.setMinutes(d.getMinutes() + 1);
-    for (let i = 0; i < horizonMinutes; i++) {
-        if (cronMatches(masks, d)) return d.getTime();
-        d.setMinutes(d.getMinutes() + 1);
-    }
-    return null;
-}

package/src/devserver/daemon/host.ts

@@ -1,134 +0,0 @@
-/**
- * Host-import surface for the dev daemon (cold) box, mirroring the production
- * edge's `daemon.*` imports. DAEMON path only (streams are Phase 4).
- *
- * Per RECONCILIATION:
- *   - Part 4 `daemon.*`: is_leader / current_epoch / yield / sleep_ms / task_count
- *     / next_fire_ms / http_call. In a single dev process the leader
- *     stub is always true and the lease never expires (section 5.2). Fenced DB
- *     writes are TRANSPARENT (no `daemon.db_write_fenced` import).
- *   - Part 3 error bridge: a u16 subsystem code `c` is returned as `-(0x10000 + c)`;
- *     the buffer sentinels `-1` (TOO_SMALL) / `-2` (ABSENT) are unchanged.
- *
- * These live in their OWN wasm module namespace, `daemon`, with BARE names, exactly
- * as the edge registers them (toil-backend `src/wasm/cold/imports.rs`, `NS_DAEMON`).
- * They are NOT dotted names under `env` like `data.*` / `crypto.*` are: a cold box
- * that declares them that way resolves here and then trap-stubs at the edge, which
- * is the one shape of drift a dev emulator must never hide.
- *
- * The cold box also imports the request-surface `env.*` MINUS the response/stream
- * functions it must not have (no `set_status`/`set_header`/`respond_file`/
- * `client_ip`/`ratelimit_check`); it keeps `@data`/crypto/env/`Date.now`/email so a
- * daemon can read+write the DB and send mail. The two allow-lists live in
- * `runtime/module.ts`.
- */
-
-import { buildDatabaseImports, type DbDevState, freshDbState } from '../db/index.js';
-import { buildCryptoImports, type CryptoState, freshCryptoState } from '../runtime/crypto.js';
-import { buildEnvImports, type MemoryRef } from '../runtime/host.js';
-
-/**
- * Resolved daemon (L4) config the dev scheduler reads. Structurally identical to
- * the compiler's `ResolvedDaemonConfig`; declared here so the devserver package has
- * no source dependency on the compiler package (its tsconfig is isolated to
- * `src/devserver`). The compiler's resolved config is passed in verbatim.
- */
-export interface ResolvedDaemonConfig {
-    readonly region: string | null;
-    readonly standbyRegion: string | null;
-    readonly defaultIntervalMs: number;
-    readonly tickBudgetMs: number;
-    readonly gasTick: number;
-    readonly maxTasks: number;
-}
-
-/** RECONCILIATION Part 3 u16 error registry (the subset the daemon imports use). */
-export const enum AbiError {
-    DaemonNotLeader = 0x0401,
-    DaemonLeaseLost = 0x0402,
-    DaemonCallFailed = 0x0405,
-}
-
-/** The edge's `EPOCH_NONE` / "no such task" sentinel: a plain -1, not a bridged error. */
-const DAEMON_NONE = -1n;
-
-/** Encode a u16 subsystem error per the Part 3 negative-return bridge:
- *  `code = (-v) - 0x10000`, so `v = -(0x10000 + code)`. */
-export function encodeAbiError(code: number): number {
-    return -(0x10000 + code);
-}
-
-/** The minimal scheduler/leader view the `daemon.*` imports read. Implemented by
- *  the resident `DaemonHost`. */
-export interface DaemonRuntime {
-    isLeader(): boolean;
-    /** Monotonic fencing token; bumps on each (re)start. */
-    epoch(): bigint;
-    /** Number of registered `@scheduled` tasks. */
-    taskCount(): number;
-    /** Next computed fire time (epoch ms) for `taskId`, or `null` if unknown. */
-    nextFireMs(taskId: number): number | null;
-}
-
-/** A host-import map: each value is a function over i32 args (i64 params are typed
- *  `number | bigint` individually, matching the existing db/crypto import maps). */
-type HostFnMap = Record<string, (...args: number[]) => number | bigint>;
-
-/** Build the `daemon` namespace, closing over the resident `DaemonRuntime`. The names
- *  are BARE (`is_leader`, not `daemon.is_leader`): they are keyed under the `daemon`
- *  wasm module, matching the edge. These imports do not read guest memory (they answer
- *  from the resident scheduler state), so they take no `MemoryRef`. */
-export function buildDaemonNamespace(rt: DaemonRuntime): HostFnMap {
-    return {
-        is_leader: (): number => (rt.isLeader() ? 1 : 0),
-        // The edge answers -1 (EPOCH_NONE) when this node does not hold the lease.
-        current_epoch: (): bigint => (rt.isLeader() ? rt.epoch() : DAEMON_NONE),
-        // The dev lease never expires, so yield/sleep never report LEASE_LOST.
-        yield: (): number => 0,
-        sleep_ms: (_ms: number | bigint): number => 0,
-        task_count: (): number => rt.taskCount(),
-        // An unknown / never-firing task is -1 at the edge, NOT a bridged error.
-        next_fire_ms: (taskId: number): bigint => {
-            const at = rt.nextFireMs(taskId);
-            return at === null ? DAEMON_NONE : BigInt(at);
-        },
-        // Outbound HTTP call stub: dev returns a "call failed" sentinel rather than
-        // performing real network I/O from a synchronous wasm import (section 5.4).
-        http_call: (
-            _reqPtr: number,
-            _reqLen: number,
-            _outPtr: number,
-            _outCap: number,
-        ): bigint => BigInt(encodeAbiError(AbiError.DaemonCallFailed)),
-    };
-}
-
-/** Per-cold-box host state (DB + crypto scratch), analogous to `DispatchState`. */
-export interface DaemonState {
-    crypto: CryptoState;
-    db: DbDevState;
-}
-
-export function freshDaemonState(): DaemonState {
-    return { crypto: freshCryptoState(), db: freshDbState() };
-}
-
-/**
- * The import object for the cold daemon box: the request-surface `env` MINUS the
- * response/stream functions (built by `buildEnvImports`), plus the separate
- * `daemon` module. The cold box has no `handle` entry and no response surface.
- */
-export function buildDaemonImports(
-    ref: MemoryRef,
-    state: DaemonState,
-    rt: DaemonRuntime,
-): WebAssembly.Imports {
-    return {
-        env: {
-            ...buildEnvImports(ref, state),
-            ...buildCryptoImports(ref, state.crypto),
-            ...buildDatabaseImports(ref, state.db),
-        },
-        daemon: buildDaemonNamespace(rt),
-    };
-}