@swf2es/player-hosts 0.0.0-stage → 0.1.1

package/dist/thread/codegen/index.js

@@ -0,0 +1,405 @@
+/**
+ * Compiles ABC and AVM1 bytecode to ES modules.
+ *
+ * The compiler itself is AssemblyScript (assembly/), built to codegen.wasm.
+ * This wrapper instantiates it and gives its exports their types. The same wasm runs as the browser JIT
+ * (a module per ABC as its SWF loads) and as the ahead-of-time compiler,
+ * so both produce identical output. See docs/architecture/overview.md.
+ */
+import { AIR_API_VERSION, API_VERSION, checkApiVersion } from "../format/index.js";
+import { instantiate } from "./codegen.js";
+/** Bumped whenever generated code or the runtime ABI it calls changes. */
+export const COMPILER_VERSION = "0.0.0";
+// The API versions the player and the swf2es command reset the compiler
+// with, which module cache keys name: Flash Player's, and AIR's, whose
+// series has the names Flash Player's leaves out. format's, which the
+// runtime takes too.
+export { AIR_API_VERSION, API_VERSION };
+/** The text whose SHA-256 is a LibraryDigest's, for ABC `index`, any added after the first `count`. */
+export function libraryLog(codegen, index, count) {
+    return codegen.context(index, 0, count)?.log ?? "";
+}
+/**
+ * The text of ABC `index`'s module cache key, whose UTF-8's SHA-256 is the
+ * key: what the module depends on, the compiler's identity, the API
+ * version, every ABC its domain sees, by hash and whether it is a library,
+ * those added after it included, its own place among them, and the
+ * compiler's log about them (see Codegen.context), the libraries' part by
+ * its digest once taken. The player's module cache and the swf2es command
+ * both key by it, so that the command's modules are the cache's. Null
+ * where there is no context.
+ */
+export function moduleKey(codegen, index, abcs, libraries) {
+    const context = codegen.context(index, libraries?.count ?? 0);
+    if (!context) {
+        return null;
+    }
+    return JSON.stringify({
+        compiler: codegen.identity,
+        api: codegen.apiVersion,
+        abcs: context.abcs.map((i) => `${abcs.builtins[i] ? "builtin " : ""}${abcs.hashes[i]}`),
+        own: context.own,
+        libraries,
+        log: context.log,
+    });
+}
+/**
+ * The text of the module cache key of a SWF's AVM1 module, whose UTF-8's
+ * SHA-256 is the key: the compiler's identity, the SWF's version, which
+ * picks the operations its code calls, and `hash`, the SHA-256 of the
+ * SWF's decompressed bytes, which hold its blocks. An AVM1 module links to
+ * nothing, so nothing else goes in.
+ */
+export function actionsKey(codegen, hash, version) {
+    return JSON.stringify({ compiler: codegen.identity, avm1: version, swf: hash });
+}
+/**
+ * Instantiate the compiler from a compiled codegen.wasm module. Loading the
+ * bytes is left to the caller (fetch in browsers, fs in node), which keeps
+ * this package free of I/O. The file ships as `@swf2es/codegen/codegen.wasm`.
+ */
+export async function createCodegen(module) {
+    const wasm = await instantiate(module, { env: {} });
+    const version = wasm.compilerVersion();
+    if (version !== COMPILER_VERSION) {
+        throw new Error(`codegen.wasm is version ${version} but the wrapper expects ${COMPILER_VERSION}`);
+    }
+    // Of the same version, but built before its modules were handed out in
+    // place: its *Bytes exports return copies, which this wrapper cannot read.
+    // Asked of the module, as the bindings define every export they know of.
+    if (!WebAssembly.Module.exports(module).some((e) => e.name === "outputLength")) {
+        throw new Error("codegen.wasm has no outputLength export, which the wrapper expects: it is older than the wrapper");
+    }
+    // codegen.wasm uses AssemblyScript's minimal runtime, which collects
+    // garbage only when asked. Nothing runs in wasm between calls, so that is
+    // when: every COLLECT_EVERY calls, and after a call that grew memory.
+    // Memory never shrinks, so collecting only on growth would let each
+    // cycle's garbage grow it a little further.
+    let size = wasm.memory.buffer.byteLength;
+    let calls = 0;
+    let methodBytes = 0;
+    // Whether the domain has an ABC to compile: asking before is a mistake worth a message, not a trap.
+    let added = 0;
+    const last = (what) => {
+        if (added === 0) {
+            throw new Error(`${what}: no ABC has been added to the domain`);
+        }
+    };
+    // An ABC by its position among those added, -1 for the last.
+    const indexOf = (index) => {
+        if (index >= 0 && (!Number.isInteger(index) || index >= added)) {
+            throw new Error(`ABC ${index}: only ${added} have been added to the domain`);
+        }
+        return index < 0 ? -1 : index;
+    };
+    // ABC `index`'s module, its source map and entries kept for `keep`. A
+    // module is never empty: the ABC was of a dropped application domain.
+    const moduleOf = (hashes, index, keep, lazy = false) => {
+        // Only the hashes the module names: joining every ABC's for each
+        // compile took megabytes of codegen's memory a few thousand loads on.
+        const at = indexOf(index);
+        const own = at < 0 ? added - 1 : at;
+        const linked = collected(wasm.domainLinked(at));
+        const named = [hashes[own] ?? ""];
+        for (const i of linked ? linked.split(",") : []) {
+            named.push(hashes[Number(i)] ?? "");
+        }
+        // Its bytes decoded here: lifted as a string, a module of megabytes took
+        // longer than compiling it. The emitter writes only well-formed UTF-8,
+        // which decodes alike either way.
+        const address = lazy
+            ? wasm.domainLazyModuleBytes(named.join("\n"), at)
+            : wasm.domainModuleBytes(named.join("\n"), at, keep, true);
+        const module = collected(handed(address, wasm.outputLength()), lazy);
+        if (module === "") {
+            throw new Error(`ABC ${index}: its application domain was dropped`);
+        }
+        return module;
+    };
+    const ranges = (actions) => [
+        Int32Array.from(actions.blocks, (b) => b.offset),
+        Int32Array.from(actions.blocks, (b) => b.length),
+    ];
+    // The SWFs whose blocks or units compileActionBlocks and compileActionUnit
+    // compile, which wasm holds by a handle each: the few used last, so that
+    // blocks and units of SWFs that alternate do not copy them in again, each
+    // let go as its bytes are collected.
+    const holding = new WeakMap();
+    const holds = [];
+    let handles = 0;
+    let copies = 0;
+    const release = (handle) => {
+        const at = holds.indexOf(handle);
+        if (at >= 0) {
+            holds.splice(at, 1);
+            wasm.actionsRelease(handle);
+        }
+    };
+    const collectedSwfs = new FinalizationRegistry(release);
+    const hold = (bytes, actions) => {
+        const known = holding.get(bytes);
+        if (known !== undefined && known.actions === actions && holds.includes(known.handle)) {
+            holds.splice(holds.indexOf(known.handle), 1);
+            holds.push(known.handle);
+            return known.handle;
+        }
+        if (known !== undefined) {
+            release(known.handle);
+            collectedSwfs.unregister(known);
+        }
+        const handle = ++handles;
+        const [offsets, lengths] = ranges(actions);
+        wasm.actionsHold(handle, bytes, offsets, lengths);
+        copies++;
+        const record = { handle, actions };
+        holding.set(bytes, record);
+        collectedSwfs.register(bytes, handle, record);
+        holds.push(handle);
+        while (holds.length > HELD_SWFS) {
+            release(holds[0]);
+        }
+        return handle;
+    };
+    const actionsModule = (bytes, actions, keep) => {
+        const [offsets, lengths] = ranges(actions);
+        const address = wasm.actionsModuleBytes(bytes, offsets, lengths, actions.version, keep);
+        return collected(handed(address, wasm.outputLength()));
+    };
+    // UTF-8 a call handed out in codegen's memory, not copied (see handOut in
+    // assembly/output.ts), decoded before anything else calls in: the next
+    // call may grow memory or move them, and a collection may free them.
+    const handed = (address, length) => length === 0 ? "" : utf8.decode(new Uint8Array(wasm.memory.buffer, address, length));
+    const stamps = WebAssembly.Module.customSections(module, "swf2es.build");
+    const identity = stamps.length ? String.fromCharCode(...new Uint8Array(stamps[0])) : null;
+    let epoch = 0;
+    let apiVersion = API_VERSION;
+    const collected = (result, reclaim = false) => {
+        const grown = wasm.memory.buffer.byteLength;
+        if (reclaim || grown > size || ++calls >= COLLECT_EVERY) {
+            wasm.__collect();
+            size = grown;
+            calls = 0;
+            methodBytes = 0;
+        }
+        return result;
+    };
+    return {
+        identity,
+        abcVersion(abc) {
+            const packed = collected(wasm.abcVersion(abc));
+            return packed < 0 ? null : { major: packed >>> 16, minor: packed & 0xffff };
+        },
+        get epoch() {
+            return epoch;
+        },
+        reset(version = API_VERSION) {
+            checkApiVersion(version);
+            added = 0;
+            epoch++;
+            apiVersion = version;
+            collected(wasm.domainReset(version));
+        },
+        get apiVersion() {
+            return apiVersion;
+        },
+        add(abc, builtin = false, appDomain = 0) {
+            const error = collected(wasm.domainAdd(abc, builtin, appDomain));
+            if (error < 0) {
+                throw new Error(`application domain ${appDomain}: never made, or dropped`);
+            }
+            if (error === 0) {
+                added++;
+            }
+            return error;
+        },
+        childDomain(parent) {
+            const domain = collected(wasm.domainChild(parent));
+            if (domain < 0) {
+                throw new Error(`application domain ${parent}: never made, or dropped`);
+            }
+            return domain;
+        },
+        dropDomain(appDomain, of = epoch) {
+            if (of === epoch) {
+                collected(wasm.domainDrop(appDomain));
+            }
+        },
+        evictDomain(appDomain) {
+            collected(wasm.domainEvict(appDomain));
+        },
+        usage() {
+            const [live, dead, memory] = collected(wasm.domainUsage()).split(" ").map(Number);
+            return { live, dead, memory };
+        },
+        compact() {
+            // A rebuild makes new tables while the old are live: what earlier
+            // calls left is collected first, and the old tables once it is done,
+            // before the next call's allocations would grow memory past them.
+            if (!collected(wasm.domainWantsCompact())) {
+                return false;
+            }
+            wasm.__collect();
+            calls = 0;
+            if (!wasm.domainCompact()) {
+                return false;
+            }
+            wasm.__collect();
+            size = wasm.memory.buffer.byteLength;
+            calls = 0;
+            return true;
+        },
+        isLive(appDomain) {
+            return collected(wasm.domainState(appDomain)) === 0;
+        },
+        reviveDomain(appDomain, abcs) {
+            // Its ABCs' bytes are copied into the compiler only if a rebuild let go of them.
+            let revived = collected(wasm.domainRevive(appDomain));
+            if (revived < 0) {
+                for (const [index, bytes] of abcs) {
+                    const error = collected(wasm.domainRestore(index, bytes));
+                    if (error !== 0) {
+                        throw new Error(`ABC ${index}: not of an evicted domain, or rejected (${error})`);
+                    }
+                }
+                revived = collected(wasm.domainRevive(appDomain));
+            }
+            if (revived < 0) {
+                throw new Error(`application domain ${appDomain}: not evicted, its parent not live, or an ABC of it not given`);
+            }
+            if (revived > 0) {
+                wasm.__collect();
+                size = wasm.memory.buffer.byteLength;
+                calls = 0;
+            }
+        },
+        found(d) {
+            collected(wasm.domainFound(d.domain, d.nsKind, d.uri, d.name, d.abc, d.asType));
+        },
+        compile(hashes = [], index = -1) {
+            last("compile");
+            // Each part a call of its own, collected after it: the module's garbage
+            // is gone before its entries are written.
+            const module = moduleOf(hashes, index, true);
+            const sourceMap = collected(wasm.domainSourceMap());
+            const entries = parseEntries(collected(wasm.domainModuleEntries()));
+            return { module, sourceMap, entries };
+        },
+        compileModule(hashes = [], index = -1) {
+            last("compileModule");
+            return moduleOf(hashes, index, false);
+        },
+        compileLazyModule(hashes = [], index = -1) {
+            last("compileLazyModule");
+            return moduleOf(hashes, index, false, true);
+        },
+        context(index = -1, after = 0, upTo = -1) {
+            if (added === 0) {
+                return null;
+            }
+            const text = collected(wasm.domainContext(indexOf(index), after, upTo));
+            if (text === "") {
+                return null;
+            }
+            const first = text.indexOf("\n");
+            const second = text.indexOf("\n", first + 1);
+            const abcs = text.slice(0, first);
+            return {
+                abcs: abcs ? abcs.split(",").map(Number) : [],
+                own: Number(text.slice(first + 1, second < 0 ? text.length : second)),
+                log: second < 0 ? "" : text.slice(second + 1),
+            };
+        },
+        revision() {
+            return `${epoch} ${wasm.domainRevision()}`;
+        },
+        compileModuleLogged(hashes = [], index = -1) {
+            last("compileModuleLogged");
+            const mark = wasm.domainLogMark();
+            const module = moduleOf(hashes, index, false);
+            const log = collected(wasm.domainLogSince(mark, indexOf(index)));
+            return { module, log: log === "!" ? null : log };
+        },
+        replay(log, index = -1) {
+            last("replay");
+            return collected(wasm.domainReplay(log, indexOf(index)));
+        },
+        compileMethods(bodies, index = -1) {
+            last("compileMethods");
+            const indices = bodies.filter((b) => Number.isInteger(b) && b >= 0);
+            if (indices.length === 0) {
+                return new Map();
+            }
+            const address = wasm.domainEmitEachBytes(indices.join(","), true, indexOf(index));
+            const length = wasm.outputLength();
+            methodBytes += length;
+            const text = handed(address, length);
+            return parseEntries(collected(text, methodBytes >= COLLECT_METHOD_BYTES));
+        },
+        compileActions(bytes, actions) {
+            const module = actionsModule(bytes, actions, true);
+            const entries = parseEntries(collected(wasm.actionsModuleEntries()));
+            const units = new Map();
+            for (const item of collected(wasm.actionsModuleUnits()).split("\u0002")) {
+                const [key, numbers, limits, code] = item.split("\u0001");
+                if (code !== undefined) {
+                    const [at, end, bound, five] = numbers.split(",").map(Number);
+                    const [high, reach] = limits.split(",").map(Number);
+                    units.set(key, { code, high, reach, unit: { at, end, bound, five: five !== 0 } });
+                }
+            }
+            return { module, entries: actions.blocks.map((_, k) => entries.get(k) ?? ""), units };
+        },
+        compileActionsModule(bytes, actions) {
+            return actionsModule(bytes, actions, false);
+        },
+        compileActionBlocks(bytes, actions, blocks) {
+            const indices = blocks.filter((b) => Number.isInteger(b) && b >= 0);
+            if (indices.length === 0) {
+                return new Map();
+            }
+            // The SWF held, as for units: a block needs it whole, and copying it
+            // in for each block cost a copy of the SWF in codegen's memory
+            // beside the one held for units, and the time to copy it.
+            const handle = hold(bytes, actions);
+            const address = wasm.actionsHeldEmitEachBytes(handle, actions.version, indices.join(","));
+            const text = handed(address, wasm.outputLength());
+            // A block's analysis can go before the next block runs.
+            return parseEntries(collected(text, true));
+        },
+        compileActionUnit(bytes, actions, { at, end, bound, five }) {
+            const handle = hold(bytes, actions);
+            const address = wasm.actionsHeldUnitBytes(handle, actions.version, at, end, bound, five);
+            const code = handed(address, wasm.outputLength());
+            const [high, reach] = wasm.actionsUnitLimits();
+            return collected({ code, high, reach });
+        },
+        releaseActions(bytes) {
+            const known = holding.get(bytes);
+            if (known !== undefined) {
+                release(known.handle);
+                holding.delete(bytes);
+                collectedSwfs.unregister(known);
+            }
+        },
+        heldActions() {
+            return { held: collected(wasm.actionsHeldCount()), copies };
+        },
+    };
+}
+/** Entries as the wasm writes them: for each, the body's index, U+0001, its entry, U+0002. */
+function parseEntries(text) {
+    const entries = new Map();
+    for (const item of text.split("\u0002")) {
+        const at = item.indexOf("\u0001");
+        if (at > 0) {
+            entries.set(Number(item.slice(0, at)), item.slice(at + 1));
+        }
+    }
+    return entries;
+}
+const COLLECT_EVERY = 64;
+/** How many SWFs whose blocks or units are compiled codegen holds a copy of at most. */
+const HELD_SWFS = 4;
+// Large method entries should not accumulate sixty-four calls of garbage.
+const COLLECT_METHOD_BYTES = 256 * 1024;
+const utf8 = new TextDecoder();

package/dist/thread/format/abc-names.js

@@ -0,0 +1,126 @@
+// The names an ABC refers to, read from its constant pool alone: each
+// qualified name, "package::Name" as avmplus writes a definition's (a
+// top-level one bare), from the pool's QNames in a package's namespace,
+// and from each Multiname, once for every package namespace in its set,
+// as a lookup that names the class unqualified finds it in one of them.
+// What it may name is enough to tell which libraries a SWF expects, as the
+// web element tells an AIR application's SWF from one for the browser.
+import { utf8 } from "./display.js";
+const CONSTANT_Namespace = 0x08;
+const CONSTANT_PackageNamespace = 0x16;
+const CONSTANT_QName = 0x07;
+const CONSTANT_QNameA = 0x0d;
+const CONSTANT_RTQName = 0x0f;
+const CONSTANT_RTQNameA = 0x10;
+const CONSTANT_RTQNameL = 0x11;
+const CONSTANT_RTQNameLA = 0x12;
+const CONSTANT_Multiname = 0x09;
+const CONSTANT_MultinameA = 0x0e;
+const CONSTANT_MultinameL = 0x1b;
+const CONSTANT_MultinameLA = 0x1c;
+const CONSTANT_TypeName = 0x1d;
+/** The qualified names `abc` may refer to; what it cannot read stops the reading, keeping what came before. */
+export function abcReferences(abc) {
+    const names = new Set();
+    let at = 4;
+    const u30 = () => {
+        let value = 0;
+        for (let shift = 0; shift < 35; shift += 7) {
+            if (at >= abc.length) {
+                throw new RangeError("ABC cut short");
+            }
+            const b = abc[at++];
+            value += (b & 0x7f) * 2 ** shift;
+            if ((b & 0x80) === 0) {
+                break;
+            }
+        }
+        return value;
+    };
+    const skipU30s = (count) => {
+        for (let i = 1; i < count; i++) {
+            u30();
+        }
+    };
+    try {
+        skipU30s(u30()); // ints
+        skipU30s(u30()); // uints
+        const doubles = u30();
+        at += Math.max(0, doubles - 1) * 8;
+        // From 47.16 AIR's ABCs have a pool of 4-byte floats next (codegen's parse.ts).
+        const minor = abc[0] | (abc[1] << 8);
+        const major = abc[2] | (abc[3] << 8);
+        if (major === 47 && minor >= 16) {
+            const floats = u30();
+            at += Math.max(0, floats - 1) * 4;
+        }
+        const strings = [""];
+        for (let i = 1, n = u30(); i < n; i++) {
+            const length = u30();
+            strings.push(utf8(abc.subarray(at, at + length)));
+            at += length;
+        }
+        // A package's namespace by its URI; null for any other kind.
+        const namespaces = [null];
+        for (let i = 1, n = u30(); i < n; i++) {
+            const kind = abc[at++];
+            const name = strings[u30()] ?? "";
+            namespaces.push(kind === CONSTANT_PackageNamespace || kind === CONSTANT_Namespace ? name : null);
+        }
+        const sets = [[]];
+        for (let i = 1, n = u30(); i < n; i++) {
+            const set = [];
+            for (let j = 0, count = u30(); j < count; j++) {
+                set.push(u30());
+            }
+            sets.push(set);
+        }
+        const add = (ns, name) => {
+            if (ns !== null && ns !== undefined && name) {
+                names.add(ns === "" ? name : `${ns}::${name}`);
+            }
+        };
+        for (let i = 1, n = u30(); i < n; i++) {
+            const kind = abc[at++];
+            switch (kind) {
+                case CONSTANT_QName:
+                case CONSTANT_QNameA: {
+                    const ns = u30();
+                    add(namespaces[ns], strings[u30()]);
+                    break;
+                }
+                case CONSTANT_RTQName:
+                case CONSTANT_RTQNameA:
+                    u30();
+                    break;
+                case CONSTANT_RTQNameL:
+                case CONSTANT_RTQNameLA:
+                    break;
+                case CONSTANT_Multiname:
+                case CONSTANT_MultinameA: {
+                    const name = strings[u30()];
+                    for (const ns of sets[u30()] ?? []) {
+                        add(namespaces[ns], name);
+                    }
+                    break;
+                }
+                case CONSTANT_MultinameL:
+                case CONSTANT_MultinameLA:
+                    u30();
+                    break;
+                case CONSTANT_TypeName: {
+                    u30();
+                    skipU30s(u30() + 1);
+                    break;
+                }
+                default:
+                    // A kind no ABC has: what follows cannot be read.
+                    return names;
+            }
+        }
+    }
+    catch {
+        // Cut short: what was read is what it names.
+    }
+    return names;
+}