@volter/world-core 2.0.0

package/dist/src/git/objects.js

@@ -0,0 +1,161 @@
+// GIT OBJECTS OVER THE BLOB SEAM (docs/contributing/architecture.md#the-engine-slot): loose objects — `<type>
+// <size>\0<payload>`, zlib-deflated, addressed by the SHA-1 of the uncompressed form — written
+// and read through the active BlobStore under `<prefix>/objects/<ab>/<rest>`, the exact layout
+// a bare repository keeps. Pure JS: SHA-1 through WebCrypto, loose objects stored uncompressed in zlib framing (storeZlib),
+// a pack deflated through the standard CompressionStream, inflate through ./inflate.ts (it reports consumed bytes, which a packfile
+// reader needs). Bun and workerd alike; no `git` binary anywhere.
+import { inflateZlib } from "./inflate.js";
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+export async function sha1Hex(bytes) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-1', bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)));
+    return [...digest].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+export function hexToBytes(hex) { const out = new Uint8Array(hex.length / 2); for (let i = 0; i < out.length; i++)
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16); return out; }
+export function bytesToHex(b) { return [...b].map((byte) => byte.toString(16).padStart(2, '0')).join(''); }
+export function concat(...parts) { const n = parts.reduce((s, p) => s + p.length, 0); const out = new Uint8Array(n); let o = 0; for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+} return out; }
+/** The loose-object form: header + payload (what the sha is computed over). */
+export function encodeLoose(type, payload) { return concat(ENC.encode(`${type} ${payload.length}\0`), payload); }
+export function decodeLoose(bytes) {
+    const nul = bytes.indexOf(0);
+    if (nul < 0)
+        throw new Error('git object: no header');
+    const [type, size] = DEC.decode(bytes.subarray(0, nul)).split(' ');
+    const payload = bytes.subarray(nul + 1);
+    if (Number(size) !== payload.length)
+        throw new Error(`git object: header says ${size} bytes, payload is ${payload.length}`);
+    return { type: type, payload };
+}
+export async function hashObject(type, payload) { return sha1Hex(encodeLoose(type, payload)); }
+export async function deflateZlib(bytes) {
+    const cs = new CompressionStream('deflate');
+    const w = cs.writable.getWriter();
+    void w.write(new Uint8Array(bytes));
+    void w.close();
+    return new Uint8Array(await new Response(cs.readable).arrayBuffer());
+}
+/** zlib with stored (uncompressed) deflate blocks: what git writes at `core.compression 0`, and what every
+ *  inflater reads. A loose object is written on every commit a World makes; compressing each one through the
+ *  asynchronous CompressionStream made a write's cost the stream's round trips, not the object's size. */
+export function storeZlib(bytes) {
+    const blocks = Math.max(1, Math.ceil(bytes.length / 0xffff));
+    const out = new Uint8Array(2 + bytes.length + blocks * 5 + 4);
+    out[0] = 0x78;
+    out[1] = 0x01;
+    let o = 2;
+    for (let b = 0; b < blocks; b++) {
+        const start = b * 0xffff;
+        const len = Math.min(0xffff, bytes.length - start);
+        out[o++] = b === blocks - 1 ? 1 : 0;
+        out[o++] = len & 0xff;
+        out[o++] = len >>> 8;
+        out[o++] = ~len & 0xff;
+        out[o++] = (~len >>> 8) & 0xff;
+        out.set(bytes.subarray(start, start + len), o);
+        o += len;
+    }
+    let a = 1;
+    let d = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        a = (a + bytes[i]) % 65521;
+        d = (d + a) % 65521;
+    }
+    const adler = ((d << 16) | a) >>> 0;
+    out[o++] = adler >>> 24;
+    out[o++] = (adler >>> 16) & 0xff;
+    out[o++] = (adler >>> 8) & 0xff;
+    out[o++] = adler & 0xff;
+    return out;
+}
+/** The object store: one bare repo's objects under a key prefix in the blob seam. */
+export class GitObjectStore {
+    blobs;
+    prefix;
+    constructor(blobs, prefix) {
+        this.blobs = blobs;
+        this.prefix = prefix;
+    }
+    key(sha) { return `${this.prefix}/objects/${sha.slice(0, 2)}/${sha.slice(2)}`; }
+    async has(sha) { return this.blobs.exists(this.key(sha)); }
+    async write(type, payload) {
+        const loose = encodeLoose(type, payload);
+        const sha = await sha1Hex(loose);
+        if (!(await this.blobs.exists(this.key(sha))))
+            await this.blobs.put(this.key(sha), storeZlib(loose));
+        return sha;
+    }
+    async read(sha) {
+        const z = await this.blobs.get(this.key(sha));
+        if (z === null)
+            return null;
+        return decodeLoose(inflateZlib(z).out);
+    }
+}
+/** git sorts tree entries by name, with a directory's name compared as if it ended in '/'. */
+export function sortTreeEntries(entries) {
+    const k = (e) => (e.mode === '40000' || e.mode === '040000' ? `${e.name}/` : e.name);
+    return [...entries].sort((a, b) => (k(a) < k(b) ? -1 : k(a) > k(b) ? 1 : 0));
+}
+export function encodeTree(entries) {
+    return concat(...sortTreeEntries(entries).map((e) => concat(ENC.encode(`${e.mode.replace(/^0+(?=\d)/, '')} ${e.name}\0`), hexToBytes(e.sha))));
+}
+export function decodeTree(payload) {
+    const out = [];
+    let i = 0;
+    while (i < payload.length) {
+        const sp = payload.indexOf(0x20, i);
+        const nul = payload.indexOf(0, sp);
+        out.push({ mode: DEC.decode(payload.subarray(i, sp)), name: DEC.decode(payload.subarray(sp + 1, nul)), sha: bytesToHex(payload.subarray(nul + 1, nul + 21)) });
+        i = nul + 21;
+    }
+    return out;
+}
+const ident = (i) => `${i.name} <${i.email}> ${i.time} ${i.tz}`;
+export function encodeCommit(c) {
+    return ENC.encode(`tree ${c.tree}\n${c.parents.map((p) => `parent ${p}\n`).join('')}author ${ident(c.author)}\ncommitter ${ident(c.committer)}\n\n${c.message}`);
+}
+function parseIdent(s) { const m = /^(.*) <([^>]*)> (\d+) ([+-]\d{4})$/.exec(s); if (!m)
+    throw new Error(`git ident: ${s}`); return { name: m[1], email: m[2], time: Number(m[3]), tz: m[4] }; }
+export function decodeCommit(payload) {
+    const text = DEC.decode(payload);
+    const sep = text.indexOf('\n\n');
+    const head = text.slice(0, sep);
+    const message = text.slice(sep + 2);
+    const c = { tree: '', parents: [], author: undefined, committer: undefined, message };
+    for (const line of head.split('\n')) {
+        const sp = line.indexOf(' ');
+        const k = line.slice(0, sp), v = line.slice(sp + 1);
+        if (k === 'tree')
+            c.tree = v;
+        else if (k === 'parent')
+            c.parents.push(v);
+        else if (k === 'author')
+            c.author = parseIdent(v);
+        else if (k === 'committer')
+            c.committer = parseIdent(v);
+    }
+    return c;
+}
+export function encodeTag(t) { return ENC.encode(`object ${t.object}\ntype ${t.type}\ntag ${t.tag}\n${t.tagger ? `tagger ${ident(t.tagger)}\n` : ''}\n${t.message}`); }
+export function decodeTag(payload) {
+    const text = DEC.decode(payload);
+    const sep = text.indexOf('\n\n');
+    const t = { object: '', type: 'commit', tag: '', message: text.slice(sep + 2) };
+    for (const line of text.slice(0, sep).split('\n')) {
+        const sp = line.indexOf(' ');
+        const k = line.slice(0, sp), v = line.slice(sp + 1);
+        if (k === 'object')
+            t.object = v;
+        else if (k === 'type')
+            t.type = v;
+        else if (k === 'tag')
+            t.tag = v;
+        else if (k === 'tagger')
+            t.tagger = parseIdent(v);
+    }
+    return t;
+}

package/dist/src/git/pack.d.ts

@@ -0,0 +1,14 @@
+import { GitObjectStore, type GitObjectType } from './objects.js';
+/** Apply a git delta (copy / insert ops) to a base payload. */
+export declare function applyDelta(base: Uint8Array, delta: Uint8Array): Uint8Array;
+export type PackedObject = {
+    type: GitObjectType;
+    sha: string;
+};
+/** Read a pack, resolve every object, write them to `store`; returns each object's type and sha in pack order. */
+export declare function readPack(pack: Uint8Array, store: GitObjectStore): Promise<PackedObject[]>;
+/** Write a pack of undeltified objects, trailer included. */
+export declare function writePack(objects: Array<{
+    type: GitObjectType;
+    payload: Uint8Array;
+}>): Promise<Uint8Array>;

package/dist/src/git/pack.js

@@ -0,0 +1,199 @@
+// PACKFILES (gitformat-pack): what a client sends on push and what a server sends on fetch.
+// READ: parse a v2 pack — undeltified objects (zlib at an offset, consumed bytes from the kernel
+// inflater), OFS_DELTA and REF_DELTA resolved against earlier objects in the pack or the object
+// store, the trailing SHA-1 verified — and write every resolved object to the store. WRITE: a pack
+// of undeltified objects with the trailer, which every git accepts (deltas are an optimization a
+// twin does not owe a client).
+import { inflateZlib } from "./inflate.js";
+import { bytesToHex, concat, deflateZlib, sha1Hex } from "./objects.js";
+const TYPE_BY_CODE = { 1: 'commit', 2: 'tree', 3: 'blob', 4: 'tag' };
+const CODE_BY_TYPE = { commit: 1, tree: 2, blob: 3, tag: 4 };
+const OFS_DELTA = 6, REF_DELTA = 7;
+function readVarSize(input, at) {
+    let c = input[at];
+    const type = (c >> 4) & 7;
+    let value = c & 15;
+    let shift = 4;
+    let i = at + 1;
+    while (c & 0x80) {
+        c = input[i++];
+        value += (c & 0x7f) * 2 ** shift;
+        shift += 7;
+    }
+    return { value, type, next: i };
+}
+function readDeltaSize(d, at) {
+    let value = 0, shift = 0, i = at, c;
+    do {
+        c = d[i++];
+        value += (c & 0x7f) * 2 ** shift;
+        shift += 7;
+    } while (c & 0x80);
+    return { value, next: i };
+}
+/** Apply a git delta (copy / insert ops) to a base payload. */
+export function applyDelta(base, delta) {
+    let p = 0;
+    const src = readDeltaSize(delta, p);
+    p = src.next;
+    if (src.value !== base.length)
+        throw new Error(`delta: base size ${src.value} != ${base.length}`);
+    const dst = readDeltaSize(delta, p);
+    p = dst.next;
+    const out = new Uint8Array(dst.value);
+    let o = 0;
+    while (p < delta.length) {
+        const op = delta[p++];
+        if (op & 0x80) {
+            let off = 0, len = 0;
+            if (op & 0x01)
+                off |= delta[p++];
+            if (op & 0x02)
+                off |= delta[p++] << 8;
+            if (op & 0x04)
+                off |= delta[p++] << 16;
+            if (op & 0x08)
+                off |= delta[p++] * 2 ** 24;
+            if (op & 0x10)
+                len |= delta[p++];
+            if (op & 0x20)
+                len |= delta[p++] << 8;
+            if (op & 0x40)
+                len |= delta[p++] << 16;
+            if (len === 0)
+                len = 0x10000;
+            out.set(base.subarray(off, off + len), o);
+            o += len;
+        }
+        else if (op > 0) {
+            out.set(delta.subarray(p, p + op), o);
+            o += op;
+            p += op;
+        }
+        else
+            throw new Error('delta: reserved op 0');
+    }
+    if (o !== dst.value)
+        throw new Error(`delta: produced ${o} bytes, expected ${dst.value}`);
+    return out;
+}
+// Delta bases are re-read from the store they were just written to; only this many bytes of
+// resolved payloads stay in memory (git's own core.deltaBaseCacheLimit is 96 MiB). Holding every
+// payload until the pack ends made a full-history push cost the repository's whole inflated size.
+const DELTA_BASE_CACHE_BYTES = 96 * 1024 * 1024;
+/** Read a pack, resolve every object, write them to `store`; returns each object's type and sha in pack order. */
+export async function readPack(pack, store) {
+    const dec = new TextDecoder();
+    if (dec.decode(pack.subarray(0, 4)) !== 'PACK')
+        throw new Error('pack: bad signature');
+    const version = (pack[4] << 24) | (pack[5] << 16) | (pack[6] << 8) | pack[7];
+    if (version !== 2 && version !== 3)
+        throw new Error(`pack: version ${version}`);
+    const count = ((pack[8] << 24) | (pack[9] << 16) | (pack[10] << 8) | pack[11]) >>> 0;
+    const trailer = bytesToHex(pack.subarray(pack.length - 20));
+    const expected = await sha1Hex(pack.subarray(0, pack.length - 20));
+    if (trailer !== expected)
+        throw new Error('pack: checksum mismatch');
+    const cache = new Map();
+    let cached = 0;
+    const remember = (sha, obj) => {
+        if (obj.payload.length > DELTA_BASE_CACHE_BYTES || cache.has(sha))
+            return;
+        cache.set(sha, obj);
+        cached += obj.payload.length;
+        for (const [old, { payload }] of cache) {
+            if (cached <= DELTA_BASE_CACHE_BYTES)
+                break;
+            cache.delete(old);
+            cached -= payload.length;
+        }
+    };
+    const payloadOf = async (sha) => {
+        const hit = cache.get(sha);
+        if (!hit)
+            return store.read(sha);
+        cache.delete(sha);
+        cache.set(sha, hit);
+        return hit;
+    };
+    const byOffset = new Map();
+    const out = [];
+    let at = 12;
+    for (let n = 0; n < count; n++) {
+        const start = at;
+        const h = readVarSize(pack, at);
+        at = h.next;
+        let type;
+        let payload;
+        if (h.type === OFS_DELTA || h.type === REF_DELTA) {
+            let baseSha;
+            if (h.type === OFS_DELTA) {
+                let c = pack[at++];
+                let off = c & 0x7f;
+                while (c & 0x80) {
+                    c = pack[at++];
+                    off = ((off + 1) * 128) + (c & 0x7f);
+                }
+                const entry = byOffset.get(start - off);
+                if (!entry)
+                    throw new Error(`pack: ofs-delta base at ${start - off} not found`);
+                baseSha = entry.sha;
+            }
+            else {
+                baseSha = bytesToHex(pack.subarray(at, at + 20));
+                at += 20;
+            }
+            const base = await payloadOf(baseSha);
+            if (!base)
+                throw new Error(`pack: ${h.type === OFS_DELTA ? 'ofs' : 'ref'}-delta base ${baseSha} not found`);
+            const z = inflateZlib(pack, at);
+            at += z.consumed;
+            type = base.type;
+            payload = applyDelta(base.payload, z.out);
+        }
+        else {
+            const known = TYPE_BY_CODE[h.type];
+            if (!known)
+                throw new Error(`pack: object type ${h.type}`);
+            const z = inflateZlib(pack, at);
+            at += z.consumed;
+            if (z.out.length !== h.value)
+                throw new Error(`pack: object size ${z.out.length} != ${h.value}`);
+            type = known;
+            payload = z.out;
+        }
+        const obj = { type, sha: await store.write(type, payload) };
+        remember(obj.sha, { type, payload });
+        byOffset.set(start, obj);
+        out.push(obj);
+    }
+    return out;
+}
+function encodeVarSize(type, size) {
+    const bytes = [];
+    let c = (type << 4) | (size & 15);
+    size = Math.floor(size / 16);
+    while (size > 0) {
+        bytes.push(c | 0x80);
+        c = size & 0x7f;
+        size = Math.floor(size / 128);
+    }
+    bytes.push(c);
+    return new Uint8Array(bytes);
+}
+/** Write a pack of undeltified objects, trailer included. */
+export async function writePack(objects) {
+    const header = new Uint8Array(12);
+    header.set(new TextEncoder().encode('PACK'), 0);
+    header[7] = 2;
+    header[8] = (objects.length >>> 24) & 255;
+    header[9] = (objects.length >>> 16) & 255;
+    header[10] = (objects.length >>> 8) & 255;
+    header[11] = objects.length & 255;
+    const parts = [header];
+    for (const o of objects)
+        parts.push(encodeVarSize(CODE_BY_TYPE[o.type], o.payload.length), await deflateZlib(o.payload));
+    const body = concat(...parts);
+    const trailer = await sha1Hex(body);
+    return concat(body, new Uint8Array(trailer.match(/../g).map((h) => parseInt(h, 16))));
+}

package/dist/src/git/refs.d.ts

@@ -0,0 +1,19 @@
+import type { WorldStore } from '../world-store.js';
+export declare class GitRefs {
+    private readonly store;
+    private readonly prefix;
+    constructor(store: WorldStore, prefix: string);
+    private path;
+    get(name: string): string | null;
+    set(name: string, sha: string): void;
+    delete(name: string): void;
+    head(): string;
+    setHead(target: string): void;
+    /** Run `fn` holding the repository's ref lock (the world store's exclusive lock). */
+    withLock<T>(fn: () => T): T;
+    /** Every `refs/...` name with its sha, sorted by name. */
+    list(): Array<{
+        name: string;
+        sha: string;
+    }>;
+}

package/dist/src/git/refs.js

@@ -0,0 +1,35 @@
+export class GitRefs {
+    store;
+    prefix;
+    constructor(store, prefix) {
+        this.store = store;
+        this.prefix = prefix;
+    }
+    path(name) { return `${this.prefix}/${name}`; }
+    get(name) { const v = this.store.read(this.path(name)); return v === null ? null : v.trim(); }
+    set(name, sha) { this.store.write(this.path(name), `${sha}\n`); }
+    delete(name) { if (this.store.exists(this.path(name)))
+        this.store.remove(this.path(name)); }
+    head() { const v = this.store.read(this.path('HEAD')); return v === null ? 'refs/heads/main' : v.trim().replace(/^ref: /, ''); }
+    setHead(target) { this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
+    /** Run `fn` holding the repository's ref lock (the world store's exclusive lock). */
+    withLock(fn) { return this.store.withLock(this.path('refs.lock'), fn); }
+    /** Every `refs/...` name with its sha, sorted by name. */
+    list() {
+        const out = [];
+        // stat before read: on the fs store a directory read throws (EISDIR); the memory store answers null
+        const walk = (dir, rel) => { for (const child of this.store.list(dir)) {
+            const p = `${dir}/${child}`;
+            const r = `${rel}/${child}`;
+            if (this.store.stat(p)?.isDirectory) {
+                walk(p, r);
+                continue;
+            }
+            const sha = this.store.read(p);
+            if (sha !== null)
+                out.push({ name: r, sha: sha.trim() });
+        } };
+        walk(this.path('refs'), 'refs');
+        return out.sort((a, b) => (a.name < b.name ? -1 : 1));
+    }
+}

package/dist/src/git/smart-http.d.ts

@@ -0,0 +1,45 @@
+import { GitObjectStore } from './objects.js';
+import type { GitRefs } from './refs.js';
+export declare const ZERO_SHA: string;
+export declare const FLUSH: Uint8Array<ArrayBuffer>;
+export declare function pktLine(s: string | Uint8Array): Uint8Array;
+/** Pkt-lines up to and including the first flush; `rest` is what follows (a pack, on push). */
+export declare function readPktLines(bytes: Uint8Array): {
+    lines: string[];
+    rest: Uint8Array;
+};
+/** Every pkt-line in the body across all flushes (stateless clients batch haves between flushes); `rest` follows the first flush. */
+export declare function readAllPktLines(bytes: Uint8Array): {
+    lines: string[];
+    rest: Uint8Array;
+};
+export type Service = 'git-upload-pack' | 'git-receive-pack';
+/** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
+export declare function advertisement(service: Service, refs: GitRefs): Uint8Array;
+/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. */
+export declare function uploadPack(body: Uint8Array, store: GitObjectStore): Promise<Uint8Array>;
+export type RefCommand = {
+    old: string;
+    new: string;
+    name: string; /** false when `new` does not descend from `old` (a force push); true for creates, deletes and fast-forwards. */
+    fastForward: boolean;
+};
+/** Bounded ancestry walk: is `ancestor` reachable from `sha` through parents? */
+export declare function isAncestor(store: GitObjectStore, ancestor: string, sha: string, limit?: number): Promise<boolean>;
+export type PushPolicy = (cmd: RefCommand) => string | null | Promise<string | null>;
+/** `POST git-receive-pack`: commands and a pack in, refs updated under `policy`, report-status out. */
+export declare function receivePack(body: Uint8Array, store: GitObjectStore, refs: GitRefs, policy?: PushPolicy): Promise<{
+    response: Uint8Array;
+    applied: RefCommand[];
+}>;
+export type GitRepo = {
+    store: GitObjectStore;
+    refs: GitRefs;
+    policy?: PushPolicy;
+    onPush?: (applied: RefCommand[]) => void | Promise<void>;
+};
+/** Route one request under a repo: returns null when the path is not a smart-HTTP endpoint. */
+export declare function serveSmartHttp(req: Request, repo: GitRepo, tailPath: string): Promise<Response | null>;
+/** The POST half of `serveSmartHttp` for a caller that already holds the body: a push pack is
+ *  the size of the repository, so re-wrapping it in a Request only to read it back is a full copy. */
+export declare function serveSmartHttpPost(body: Uint8Array, contentEncoding: string, repo: GitRepo, tailPath: 'git-upload-pack' | 'git-receive-pack'): Promise<Response>;