@nimbus-sh/worker 0.1.0

package/dist/bindings/kv.js

@@ -0,0 +1,290 @@
+/**
+ * binding-kv.ts — KV namespace emulator for nimbus-wrangler.
+ *
+ * Implements the Workers KV runtime API
+ * (https://developers.cloudflare.com/kv/api/) backed by SqliteVFS file
+ * blobs. The emulator is constructed inline by NimbusWrangler.buildInnerEnv()
+ * and attached as `env.<binding>` on the inner Worker.
+ *
+ * Storage layout:
+ *   <root>/.nimbus/kv/<binding>/<key>             — body (raw bytes)
+ *   <root>/.nimbus/kv/<binding>/<key>.meta        — sidecar JSON:
+ *      { exp?: number,           // unix seconds, absolute expiration
+ *        meta?: any,              // user-supplied metadata
+ *        v: 1 }                   // schema version
+ *
+ * Keys are URL-encoded so that '/' / '\\' / '\0' / '#' / etc. don't break
+ * the VFS path. We then add ".meta" to derive the sidecar path.
+ *
+ * Concurrency: KV semantics permit eventual consistency. We do not use
+ * VFS writeBatch for the body+meta pair (a torn write surfaces as a meta
+ * read mismatch which we treat as no-metadata; the body still resolves).
+ *
+ * Test seam: `_setKvNow(() => ts)` replaces the wall clock (Date.now/1000)
+ * for TTL probes. Production reads Date.now() / 1000.
+ */
+// ── Test seam: clock ────────────────────────────────────────────────────
+let _kvNow = () => Math.floor(Date.now() / 1000);
+export function _setKvNow(fn) { _kvNow = fn; }
+// ── Path helpers ────────────────────────────────────────────────────────
+function encKey(key) {
+    // Match KV's accepted key alphabet: any UTF-8 string up to 512 bytes. We
+    // URL-encode to make every key VFS-path-safe.
+    return encodeURIComponent(key);
+}
+function decKey(encoded) {
+    try {
+        return decodeURIComponent(encoded);
+    }
+    catch {
+        return encoded;
+    }
+}
+// ── KvEmulator ─────────────────────────────────────────────────────────
+export class KvEmulator {
+    vfs;
+    dir;
+    metaCache = new Map();
+    onLog;
+    constructor(opts) {
+        this.vfs = opts.vfs;
+        const root = String(opts.root).replace(/^\/+/, '').replace(/\/+$/, '');
+        this.dir = (root ? root + '/' : '') + '.nimbus/kv/' + opts.binding;
+        this.onLog = opts.onLog || (() => { });
+    }
+    // ── public API ────────────────────────────────────────────────────────
+    async get(key, options) {
+        const opts = typeof options === 'string' ? { type: options } : (options || {});
+        const r = await this._readResolved(key);
+        if (r == null)
+            return null;
+        return this._project(r.body, opts.type);
+    }
+    async getWithMetadata(key, options) {
+        const opts = typeof options === 'string' ? { type: options } : (options || {});
+        const r = await this._readResolved(key);
+        if (r == null)
+            return { value: null, metadata: null, cacheStatus: null };
+        const value = this._project(r.body, opts.type);
+        return { value, metadata: (r.meta?.meta ?? null), cacheStatus: null };
+    }
+    async put(key, value, options) {
+        const enc = encKey(key);
+        const bodyBlob = await this._coerceBody(value);
+        this._ensureDir();
+        this.vfs.writeFile(this.dir + '/' + enc, bodyBlob);
+        // Build sidecar
+        const meta = { v: 1 };
+        if (options?.expiration != null)
+            meta.exp = options.expiration;
+        else if (options?.expirationTtl != null)
+            meta.exp = _kvNow() + options.expirationTtl;
+        if (options?.metadata !== undefined)
+            meta.meta = options.metadata;
+        const metaPath = this.dir + '/' + enc + '.meta';
+        if (meta.exp != null || meta.meta !== undefined) {
+            this.vfs.writeFile(metaPath, JSON.stringify(meta));
+            this.metaCache.set(enc, meta);
+        }
+        else {
+            // Overwrite-without-metadata clears the sidecar (per probe contract:
+            // 'overwrite WITHOUT metadata clears metadata').
+            try {
+                if (this.vfs.exists(metaPath))
+                    this.vfs.unlink(metaPath);
+            }
+            catch { }
+            this.metaCache.delete(enc);
+        }
+    }
+    async delete(key) {
+        const enc = encKey(key);
+        const bp = this.dir + '/' + enc;
+        const mp = bp + '.meta';
+        try {
+            if (this.vfs.exists(bp))
+                this.vfs.unlink(bp);
+        }
+        catch { }
+        try {
+            if (this.vfs.exists(mp))
+                this.vfs.unlink(mp);
+        }
+        catch { }
+        this.metaCache.delete(enc);
+    }
+    async list(options) {
+        const prefix = options?.prefix || '';
+        const limit = options?.limit ?? 1000;
+        const cursorOff = options?.cursor ? this._decodeCursor(options.cursor) : 0;
+        let entries = [];
+        try {
+            const dirents = this.vfs.readdir(this.dir);
+            for (const e of dirents) {
+                if (e.type === 'directory')
+                    continue;
+                if (e.name.endsWith('.meta'))
+                    continue;
+                const decoded = decKey(e.name);
+                if (!decoded.startsWith(prefix))
+                    continue;
+                const meta = this._readMeta(e.name);
+                // Skip expired
+                if (meta?.exp != null && meta.exp <= _kvNow()) {
+                    this._lazyDelete(e.name);
+                    continue;
+                }
+                const out = { name: decoded };
+                if (meta?.exp != null)
+                    out.expiration = meta.exp;
+                if (meta?.meta !== undefined)
+                    out.metadata = meta.meta;
+                entries.push(out);
+            }
+        }
+        catch {
+            // Empty dir: no keys
+            entries = [];
+        }
+        entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        const slice = entries.slice(cursorOff, cursorOff + limit);
+        const next = cursorOff + slice.length;
+        const list_complete = next >= entries.length;
+        const out = {
+            keys: slice,
+            list_complete,
+            cacheStatus: null,
+        };
+        if (!list_complete)
+            out.cursor = this._encodeCursor(next);
+        return out;
+    }
+    // ── internals ─────────────────────────────────────────────────────────
+    _ensureDir() {
+        if (!this.vfs.exists(this.dir)) {
+            this.vfs.mkdir(this.dir, { recursive: true });
+        }
+    }
+    async _coerceBody(value) {
+        if (value == null)
+            return new Uint8Array(0);
+        if (typeof value === 'string')
+            return new TextEncoder().encode(value);
+        if (value instanceof Uint8Array)
+            return value;
+        if (value instanceof ArrayBuffer)
+            return new Uint8Array(value);
+        if (ArrayBuffer.isView(value))
+            return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        if (typeof value === 'object' && typeof value.getReader === 'function') {
+            // ReadableStream — drain
+            const chunks = [];
+            let total = 0;
+            const reader = value.getReader();
+            while (true) {
+                const { value: chunk, done } = await reader.read();
+                if (done)
+                    break;
+                const u = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+                chunks.push(u);
+                total += u.length;
+            }
+            const out = new Uint8Array(total);
+            let off = 0;
+            for (const c of chunks) {
+                out.set(c, off);
+                off += c.length;
+            }
+            return out;
+        }
+        // Fallback — try toString
+        return new TextEncoder().encode(String(value));
+    }
+    _project(body, type) {
+        const t = type || 'text';
+        if (t === 'text')
+            return new TextDecoder().decode(body);
+        if (t === 'json') {
+            const txt = new TextDecoder().decode(body);
+            return JSON.parse(txt);
+        }
+        if (t === 'arrayBuffer') {
+            // Return a fresh ArrayBuffer (not a view into a shared buffer).
+            const ab = new ArrayBuffer(body.byteLength);
+            new Uint8Array(ab).set(body);
+            return ab;
+        }
+        if (t === 'stream') {
+            const u = body;
+            return new ReadableStream({
+                type: 'bytes',
+                start(controller) {
+                    controller.enqueue(u);
+                    controller.close();
+                },
+            });
+        }
+        return new TextDecoder().decode(body);
+    }
+    async _readResolved(key) {
+        const enc = encKey(key);
+        const path = this.dir + '/' + enc;
+        if (!this.vfs.exists(path))
+            return null;
+        const meta = this._readMeta(enc);
+        if (meta?.exp != null && meta.exp <= _kvNow()) {
+            this._lazyDelete(enc);
+            return null;
+        }
+        const body = this.vfs.readFileBytes ? this.vfs.readFileBytes(path) : this.vfs.readFile(path);
+        return { body, meta };
+    }
+    _readMeta(encName) {
+        if (this.metaCache.has(encName))
+            return this.metaCache.get(encName);
+        const mp = this.dir + '/' + encName + '.meta';
+        if (!this.vfs.exists(mp))
+            return null;
+        try {
+            const raw = this.vfs.readFileString(mp);
+            const m = JSON.parse(raw);
+            this.metaCache.set(encName, m);
+            return m;
+        }
+        catch (e) {
+            // Torn meta — treat as absent
+            return null;
+        }
+    }
+    _lazyDelete(encName) {
+        const bp = this.dir + '/' + encName;
+        const mp = bp + '.meta';
+        try {
+            if (this.vfs.exists(bp))
+                this.vfs.unlink(bp);
+        }
+        catch { }
+        try {
+            if (this.vfs.exists(mp))
+                this.vfs.unlink(mp);
+        }
+        catch { }
+        this.metaCache.delete(encName);
+    }
+    _encodeCursor(off) {
+        // base64url-encode the offset record. We use btoa (Web Standard,
+        // available in workerd and Bun) and patch base64 → base64url.
+        const b64 = btoa(JSON.stringify({ off }));
+        return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    _decodeCursor(c) {
+        try {
+            const b64 = String(c).replace(/-/g, '+').replace(/_/g, '/');
+            const j = JSON.parse(atob(b64));
+            return Number(j.off) || 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+}

package/dist/bindings/r2.d.ts

@@ -0,0 +1,137 @@
+/**
+ * binding-r2.ts — R2 bucket emulator for nimbus-wrangler.
+ *
+ * Implements the Workers R2 runtime API
+ * (https://developers.cloudflare.com/r2/api/workers/workers-api-reference/)
+ * backed by SqliteVFS file blobs. Mirrors KV's storage layout:
+ *
+ *   <root>/.nimbus/r2/<binding>/<key>          — body (raw bytes)
+ *   <root>/.nimbus/r2/<binding>/<key>.meta     — sidecar JSON:
+ *      { etag: string,                       // sha256 hex of body
+ *        size: number,
+ *        uploaded: number,                    // unix ms
+ *        httpMetadata?: R2HTTPMetadata,
+ *        customMetadata?: Record<string,string>,
+ *        v: 1 }
+ *
+ * Out of scope for W10 (W10.5 candidates):
+ *   - Multipart uploads (createMultipartUpload / resumeMultipartUpload
+ *     throw "not supported" errors with a clear message)
+ *   - Server-side checksums (md5/sha1/sha256/sha512 verifies passed via
+ *     `options` are honored only loosely — we compute sha256 ourselves
+ *     and compare; mismatched verify hashes cause put() to throw)
+ *
+ * Range reads return bodies sliced from the in-memory Uint8Array.
+ *
+ * The `R2ObjectBody` returned by get() carries a fresh ReadableStream on
+ * every call (the body is one-shot per real-R2 contract), plus convenience
+ * helpers text() / arrayBuffer() / json() / blob().
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+export interface R2HTTPMetadata {
+    contentType?: string;
+    contentLanguage?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    cacheControl?: string;
+    cacheExpiry?: Date;
+}
+export interface R2Conditional {
+    etagMatches?: string;
+    etagDoesNotMatch?: string;
+    uploadedBefore?: Date;
+    uploadedAfter?: Date;
+}
+export interface R2Range {
+    offset?: number;
+    length?: number;
+    suffix?: number;
+}
+export interface R2PutOptions {
+    httpMetadata?: R2HTTPMetadata;
+    customMetadata?: Record<string, string>;
+    md5?: string | ArrayBuffer;
+    sha1?: string | ArrayBuffer;
+    sha256?: string | ArrayBuffer;
+    sha512?: string | ArrayBuffer;
+    onlyIf?: R2Conditional;
+}
+export interface R2GetOptions {
+    onlyIf?: R2Conditional;
+    range?: R2Range;
+}
+export interface R2ListOptions {
+    prefix?: string;
+    delimiter?: string;
+    cursor?: string;
+    limit?: number;
+    include?: ('httpMetadata' | 'customMetadata')[];
+}
+export interface R2EmulatorOptions {
+    vfs: SqliteVFS | any;
+    root: string;
+    binding: string;
+    onLog?: (msg: string) => void;
+}
+interface R2Sidecar {
+    etag: string;
+    size: number;
+    uploaded: number;
+    httpMetadata?: R2HTTPMetadata;
+    customMetadata?: Record<string, string>;
+    v: 1;
+}
+export declare class R2Object {
+    key: string;
+    version: string;
+    size: number;
+    etag: string;
+    httpEtag: string;
+    uploaded: Date;
+    httpMetadata: R2HTTPMetadata;
+    customMetadata: Record<string, string>;
+    constructor(key: string, side: R2Sidecar);
+}
+export declare class R2ObjectBody extends R2Object {
+    /** @internal */
+    private _body;
+    constructor(key: string, side: R2Sidecar, body: Uint8Array);
+    get body(): ReadableStream<Uint8Array>;
+    get bodyUsed(): boolean;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    json<T = any>(): Promise<T>;
+    blob(): Promise<Blob>;
+}
+export declare class R2Emulator {
+    private vfs;
+    private dir;
+    private onLog;
+    constructor(opts: R2EmulatorOptions);
+    head(key: string): Promise<R2Object | null>;
+    get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
+    put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | Uint8Array | string | null, options?: R2PutOptions): Promise<R2Object | null>;
+    delete(keys: string | string[]): Promise<void>;
+    list(options?: R2ListOptions): Promise<{
+        objects: R2Object[];
+        truncated: boolean;
+        cursor?: string;
+        delimitedPrefixes: string[];
+    }>;
+    createMultipartUpload(_key: string, _options?: any): Promise<never>;
+    resumeMultipartUpload(_key: string, _uploadId: string): Promise<never>;
+    private _ensureDir;
+    private _coerceBody;
+    private _readSide;
+    private _readSideEnc;
+    private _readBody;
+    private _evalConditional;
+    private _normalizeEtag;
+    private _applyRange;
+    private _sha256Hex;
+    private _normalizeHash;
+    private _encodeCursor;
+    private _decodeCursor;
+}
+export {};
+//# sourceMappingURL=r2.d.ts.map

package/dist/bindings/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/bindings/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAItD,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,CAAC,cAAc,GAAG,gBAAgB,CAAC,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,SAAS,GAAG,GAAG,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC,EAAE,CAAC,CAAC;CACN;AAaD,qBAAa,QAAQ;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC;IACf,YAAY,EAAE,cAAc,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAE3B,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS;CAUzC;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,gBAAgB;IAChB,OAAO,CAAC,KAAK,CAAa;gBAEd,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU;IAK1D,IAAI,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC,CASrC;IAED,IAAI,QAAQ,IAAI,OAAO,CAAuD;IAExE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAGvB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAKnC,IAAI,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC;IAG3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAsB;gBAEvB,IAAI,EAAE,iBAAiB;IAS7B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAM3C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAYtE,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,cAAc,GAAG,WAAW,GAAG,eAAe,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,EAClF,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA8CrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9C,IAAI,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,CAAC;QACpB,SAAS,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC;IAsDI,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC;IAGnE,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAM5E,OAAO,CAAC,UAAU;YAMJ,WAAW;IA6BzB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,WAAW;YAWL,UAAU;IAUxB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;CAOtB"}