toiljs 0.0.111 → 0.0.113

package/src/devserver/analytics/index.ts

@@ -15,8 +15,19 @@ import type { DbDevState } from '../db/index.js';
 import type { MemoryRef } from '../runtime/host.js';
 
 /** Frame version + counter count, kept in lockstep with the edge (`analytics.rs` / `metric_id.rs`). */
-const FRAME_VERSION = 2;
+const FRAME_VERSION = 3;
 const METRIC_COUNTERS = 42;
+
+/** The sustained-rate window: requests are metered over a 3-minute ROLLING window. A plan's
+ *  `sustained_rps` (X) allows `X * BURST_WINDOW_SECS` requests across it; instantaneous spikes above
+ *  that are NOT capped per-tier (only the box `firewall.global_pps` DDoS backstop applies). */
+export const BURST_WINDOW_SECS = 180;
+
+/** The plan's sustained rate in requests/second, derived from the rolling window's allowance.
+ *  `0` means unmetered (no sustained cap), and must NOT be divided into a rate. */
+export function sustainedRpsCap(reqBurstCap: number): number {
+    return reqBurstCap === 0 ? 0 : reqBurstCap / BURST_WINDOW_SECS;
+}
 /** MetricId indices we seed with sample data (others default 0). Mirrors the AUTHORITATIVE edge wire
  *  contract EXACTLY (`toil-backend/src/analytics/metric_id.rs`): counter ids 0..=41, gauge ids
  *  ConnectedStreamsAvg=42, CommittedMemoryAvg=44. There is NO WasmDispatches (removed + reindexed); the
@@ -43,10 +54,16 @@ interface DevTenantStats {
     life: bigint[]; // length METRIC_COUNTERS, indexed by MetricId
     connectedStreams: number;
     committedMemory: number;
-    reqMinuteUsed: number;
-    reqMinuteCap: number;
-    reqDayUsed: number;
-    reqDayCap: number;
+    // Fleet-global requests in the trailing 3-minute ROLLING window, and its allowance
+    // (= sustained_rps * BURST_WINDOW_SECS; 0 = unmetered). Spikes are not tier-capped.
+    reqBurstUsed: number;
+    reqBurstCap: number;
+    // Fleet-global requests in the current 30-day tumbling bucket, and the 30-day quota (0 = unmetered).
+    req30dUsed: number;
+    req30dCap: number;
+    // Derived (NOT part of the wire frame): the plan's sustained request rate, `reqBurstCap /
+    // BURST_WINDOW_SECS` (0 = unmetered). Surfaced so a dev dashboard can show "X sustained rps".
+    sustainedRpsCap: number;
     // LIVE per-second rates (f64), appended after the windows. Mirrors the edge `encode_stats`.
     rps: number;
     bytesInPerSec: number;
@@ -76,14 +93,18 @@ function devStats(): DevTenantStats {
     life[MID.MemGrownBytes] = 262144n;
     life[MID.CacheHits] = 900n;
     life[MID.CacheMisses] = 100n;
+    // Free tier: sustained 1000 rps -> a 3-minute burst cap of 1000 * 180 = 180_000, plus a 30-day
+    // quota of 10_000_000. `used` values are small so the dashboard shows plenty of headroom.
+    const reqBurstCap: number = 180_000;
     return {
         life,
         connectedStreams: 3,
         committedMemory: 65536,
-        reqMinuteUsed: 5,
-        reqMinuteCap: 100,
-        reqDayUsed: 42,
-        reqDayCap: 5000,
+        reqBurstUsed: 1_200,
+        reqBurstCap,
+        req30dUsed: 250_000,
+        req30dCap: 10_000_000,
+        sustainedRpsCap: sustainedRpsCap(reqBurstCap),
         // Plausible non-zero live rates so a dev dashboard shows moving gauges.
         rps: 0.7,
         bytesInPerSec: 68.2,
@@ -97,10 +118,12 @@ function devStats(): DevTenantStats {
 }
 
 /**
- * Encode the v2 snapshot frame BYTE-FOR-BYTE like the edge (`analytics.rs` `encode_stats`), FIXED
- * layout (no strings). Counters/levels are u64; the 7 trailing LIVE per-second rates are f64:
+ * Encode the v3 snapshot frame BYTE-FOR-BYTE like the edge (`analytics.rs` `encode_stats`), FIXED
+ * layout (no strings). The v2 -> v3 bump renamed two u64 pairs (req_minute_* -> req_burst_*,
+ * req_day_* -> req_30d_*); the BYTE LAYOUT is UNCHANGED (same field count, order, and widths).
+ * Counters/levels are u64; the 7 trailing LIVE per-second rates are f64:
  *   u16 version | u64 now_ms | u32 count | u64 × count | u64 connectedStreams | u64 committedMemory |
- *   u64 reqMinuteUsed | u64 reqMinuteCap | u64 reqDayUsed | u64 reqDayCap |
+ *   u64 reqBurstUsed | u64 reqBurstCap | u64 req30dUsed | u64 req30dCap |
  *   f64 rps | f64 bytesInPerSec | f64 bytesOutPerSec | f64 streamBytesInPerSec |
  *   f64 streamBytesOutPerSec | f64 dbOpsPerSec | f64 gasPerSec
  * The rates are APPENDED (version-gated by length): the guest's bounds-checked reader yields 0.0 for a
@@ -120,10 +143,10 @@ function encodeStats(s: DevTenantStats): Buffer {
     }
     body.writeBigUInt64LE(BigInt(s.connectedStreams), o); o += 8;
     body.writeBigUInt64LE(BigInt(s.committedMemory), o); o += 8;
-    body.writeBigUInt64LE(BigInt(s.reqMinuteUsed), o); o += 8;
-    body.writeBigUInt64LE(BigInt(s.reqMinuteCap), o); o += 8;
-    body.writeBigUInt64LE(BigInt(s.reqDayUsed), o); o += 8;
-    body.writeBigUInt64LE(BigInt(s.reqDayCap), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.reqBurstUsed), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.reqBurstCap), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.req30dUsed), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.req30dCap), o); o += 8;
     body.writeDoubleLE(s.rps, o); o += 8;
     body.writeDoubleLE(s.bytesInPerSec, o); o += 8;
     body.writeDoubleLE(s.bytesOutPerSec, o); o += 8;
@@ -165,7 +188,7 @@ function rangeShape(range: number, metricId: number): { count: number; bucketSec
 }
 
 /**
- * Encode the v2 series frame BYTE-FOR-BYTE like the edge `encode_series` (points are u64 now):
+ * Encode the v3 series frame BYTE-FOR-BYTE like the edge `encode_series` (points are u64 now):
  *   u16 version | u16 metricId | u32 bucketSecs | u64 headMs | u32 count | u64 × count
  * A synthetic gentle ramp so a dev dashboard draws a non-flat line.
  */

package/src/devserver/db/database.ts

@@ -186,6 +186,7 @@ enum DbOp {
     Exists,
     Create,
     Patch,
+    Upsert,
     Delete,
     GetDelete,
     Enqueue,
@@ -211,6 +212,13 @@ enum DbOp {
     EventsSince,
 }
 
+/** `data.upsert` return tags (ABI.md), mirroring the guest `UpsertResult` enum. */
+enum UpsertResult {
+    Created = 0,
+    Updated = 1,
+    Conflict = 2,
+}
+
 function isReadOp(op: DbOp): boolean {
     return (
         op === DbOp.Get ||
@@ -238,6 +246,7 @@ function kindAllows(kind: DbFunctionKind, op: DbOp): boolean {
             (isReadOp(op) && !isScanOp(op)) ||
             op === DbOp.Create ||
             op === DbOp.Patch ||
+            op === DbOp.Upsert ||
             op === DbOp.Delete ||
             op === DbOp.GetDelete ||
             op === DbOp.Enqueue ||
@@ -821,6 +830,39 @@ export class DevDatabase {
         return this.replayRecordOutcome(db, outcome);
     }
 
+    // Create-or-overwrite in ONE op: a blind last-writer-wins put. Returns
+    // UPSERT_CREATED (0) / UPSERT_UPDATED (1), or UPSERT_CONFLICT (2) when a
+    // @unique value is held by ANOTHER record (nothing written). A blind put is
+    // naturally idempotent (re-applying the same value is a no-op beyond the
+    // Created/Updated tag), so `idem` needs no dedup ledger; it is accepted for
+    // ABI parity and ignored, mirroring how the edge merely threads it into the
+    // oplog env.
+    upsert(
+        ref: MemoryRef,
+        db: DbDevState,
+        handle: number,
+        keyPtr: number,
+        keyLen: number,
+        valPtr: number,
+        valLen: number,
+        _idemPtr: number,
+    ): number {
+        const coll = collForOp(db, handle, DbOp.Upsert, CollectionFamily.Record);
+        if (typeof coll === 'number') return coll;
+        if (keyLen > MAX_KEY || valLen > MAX_VALUE) throw new Error('data: key/value too large');
+        const key = readKey(ref, keyPtr, keyLen);
+        const value = readCopy(ref, valPtr, valLen);
+        const sk = storeKey(coll.name, key);
+        // @unique: a value already held by ANOTHER record blocks the upsert (the
+        // one outcome a blind put cannot auto-resolve), exactly like the edge op.
+        if (this.uniqueConflict(coll, value, sk)) return UpsertResult.Conflict;
+        const existed = this.store.has(sk);
+        this.store.set(sk, value);
+        this.stampVersion(coll, sk); // stamp the value type's current schema version
+        this.recordWrite(db, coll);
+        return existed ? UpsertResult.Updated : UpsertResult.Created;
+    }
+
     delete(
         ref: MemoryRef,
         db: DbDevState,
@@ -1603,6 +1645,15 @@ export function buildDatabaseImports(
             idemPtr: number,
         ): number => devDb.patch(ref, db, handle, keyPtr, keyLen, patchPtr, patchLen, idemPtr),
 
+        'data.upsert': (
+            handle: number,
+            keyPtr: number,
+            keyLen: number,
+            valPtr: number,
+            valLen: number,
+            idemPtr: number,
+        ): number => devDb.upsert(ref, db, handle, keyPtr, keyLen, valPtr, valLen, idemPtr),
+
         'data.delete': (handle: number, keyPtr: number, keyLen: number, idemPtr: number): number =>
             devDb.delete(ref, db, handle, keyPtr, keyLen, idemPtr),
 

package/src/devserver/runtime/module.ts

@@ -139,6 +139,7 @@ const PROVIDED_IMPORTS = new Set([
     'data.exists',
     'data.create',
     'data.patch',
+    'data.upsert',
     'data.delete',
     'data.get_delete',
     'data.unique_lookup',

package/test/analytics-dev.test.ts

@@ -1,6 +1,6 @@
 /**
  * Dev-server analytics stub parity: the `env.analytics_read` / `env.analytics_series` dev imports must
- * encode the v2 frames BYTE-FOR-BYTE like the edge (`analytics.rs`), so a guest's toilscript `Analytics`
+ * encode the v3 frames BYTE-FOR-BYTE like the edge (`analytics.rs`), so a guest's toilscript `Analytics`
  * decode is identical in dev and prod. We decode the stashed frame positionally, exactly as the guest.
  */
 import { describe, expect, it } from 'vitest';
@@ -16,7 +16,7 @@ function harness() {
     return { imports: buildAnalyticsImports(ref, db), db };
 }
 
-describe('dev analytics stub v2 frame parity', () => {
+describe('dev analytics stub v3 frame parity', () => {
     it('analytics_read encodes the fixed-layout snapshot frame', () => {
         const { imports, db } = harness();
         const n = imports.analytics_read(0, 0);
@@ -29,7 +29,7 @@ describe('dev analytics stub v2 frame parity', () => {
         const u64 = () => { const v = buf.readBigUInt64LE(p); p += 8; return v; };
         const f64 = () => { const v = buf.readDoubleLE(p); p += 8; return v; };
 
-        expect(u16()).toBe(2); // FRAME_VERSION
+        expect(u16()).toBe(3); // FRAME_VERSION
         u64(); // now_ms
         const count = u32();
         expect(count).toBe(42); // METRIC_COUNTERS (edge N_COUNTERS; no WasmDispatches)
@@ -44,10 +44,10 @@ describe('dev analytics stub v2 frame parity', () => {
         expect(life[41]).toBe(100n); // CacheMisses (id 41, was 42)
         expect(u64()).toBe(3n); // connectedStreams
         expect(u64()).toBe(65536n); // committedMemory
-        expect(u64()).toBe(5n); // reqMinuteUsed
-        expect(u64()).toBe(100n); // reqMinuteCap
-        expect(u64()).toBe(42n); // reqDayUsed
-        expect(u64()).toBe(5000n); // reqDayCap
+        expect(u64()).toBe(1_200n); // reqBurstUsed (current 3-min tumbling bucket)
+        expect(u64()).toBe(180_000n); // reqBurstCap (sustained 1000 rps * 180s window)
+        expect(u64()).toBe(250_000n); // req30dUsed (current 30-day bucket)
+        expect(u64()).toBe(10_000_000n); // req30dCap (30-day quota)
         // 7 LIVE per-second rates (f64 LE), appended after the windows.
         expect(f64()).toBeCloseTo(0.7); // rps
         expect(f64()).toBeCloseTo(68.2); // bytesInPerSec
@@ -66,7 +66,7 @@ describe('dev analytics stub v2 frame parity', () => {
         const buf = db.lastResult as unknown as Buffer;
         expect(n).toBe(buf.length);
         let p = 0;
-        expect(buf.readUInt16LE(p)).toBe(2); p += 2; // version
+        expect(buf.readUInt16LE(p)).toBe(3); p += 2; // version
         expect(buf.readUInt16LE(p)).toBe(0); p += 2; // metric id
         expect(buf.readUInt32LE(p)).toBe(3600); p += 4; // bucketSecs
         p += 8; // headMs