/** * The component's imported interfaces, encoded by the WIT type encoder. * * The emitter used to hand-write each imported interface's instance * type — possible only while every signature was flat scalars. Now the * shape's imports are rendered as a WIT document and pushed through * `wit-parser`'s component encoder, the same code path that round-trips * real WIT through `wasm-tools component wit`. For scalar interfaces * the bytes are identical to the hand-written ones; what changes is * what becomes *possible*, because the encoder already speaks records, * variants, resources and `use`, and the emitter no longer has an * opinion. * * The derivation is per-interface WIT text, not per-program: each * `@external("ns:pkg/iface@ver", "field")` group becomes an interface * in a nested package, and a synthetic world imports them all. When an * interface's true WIT is richer than a Zena declaration can spell * (resources, lists — stdio's case), this is where its real source * will be substituted for the derived one. */ import { StringBuilder } from 'zena:core'; import { parse, parseSyntax, resolve } from 'zena-lang:wit-parser'; import { ComponentTypeEncoder, EncodedWorld, funcFlatMeta, worldFuncFlatMeta, interfaceExportFlatMeta, WitFuncMeta, expandedWorldItems, worldNames, qualifiedInterfaceName, NestedExport } from 'zena-lang:wit-parser/component-encoder'; import { Ast, AstItemTag, WorldDef, WorldItemTag, Import, Export, ExternKind, ExternKindTag, UsePath, UsePathTag, Id, Func, Type, TypeTag, PackageName, AstItem, InterfaceDef, InterfaceItem, InterfaceItemTag, NamedFunc, TypeDef, TypeDefTag, ResourceFunc, ResourceFuncTag, NestedPackage, Docs, Use } from 'zena-lang:wit-parser/parser'; import { ComponentShape, ComponentImportFunc, ComponentExportFunc, ComponentFuncType, noComponentResult, EncodedImports, EncodedImportPiece, ImportTypeEncoder, ExportedInstanceType, NestedInstanceExport, NestedInstanceArg, ResourceDtorSlot } from './component-emitter.zena'; import { HashMap } from 'zena:collections'; /** The WIT spelling of a flat-scalar component value type opcode. */ function scalarWitName(opcode: i32): String { if (opcode == 0x7f) { return "bool"; } if (opcode == 0x7e) { return "s8"; } if (opcode == 0x7d) { return "u8"; } if (opcode == 0x7c) { return "s16"; } if (opcode == 0x7b) { return "u16"; } if (opcode == 0x7a) { return "s32"; } if (opcode == 0x79) { return "u32"; } if (opcode == 0x78) { return "s64"; } if (opcode == 0x77) { return "u64"; } if (opcode == 0x76) { return "f32"; } if (opcode == 0x75) { return "f64"; } if (opcode == 0x74) { return "char"; } if (opcode == 0x73) { return "string"; } // Only the shape builder produces these opcodes, and it only // produces the scalars and string; anything else is a bug there. throw new Error( "no WIT spelling for component type opcode " + i32ToString(opcode)); } /** One imported interface: its qualified name split into WIT's parts. */ final class InterfacePath { /** `ns:pkg`, the package half. */ packageName: String; /** The interface's own name. */ interfaceName: String; /** The `@version`, or empty. */ version: String; new(this.packageName, this.interfaceName, this.version); } function splitInterfaceName(name: String) { var slash = -1; for (var i = 0; i < name.length; i += 1) { if (name.getByteAt(i) == 47) { // '/' slash = i; } } if (slash < 0) { throw new Error( "The component target cannot import from '" + name + "': a WIT interface is named ns:pkg/interface, optionally with " + "@version, and this has no '/'."); } let packageName = name.sliceBytes(0, slash); var rest = name.sliceBytes(slash + 1, name.length); var version = ""; var at = -1; for (var i = 0; i < rest.length; i += 1) { if (rest.getByteAt(i) == 64) { // '@' at = i; } } if (at >= 0) { version = rest.sliceBytes(at + 1, rest.length); rest = rest.sliceBytes(0, at); } return new InterfacePath(packageName, rest, version); } /** One function of an interface, as WIT source. */ function renderFunc(sb: StringBuilder, f: ComponentImportFunc) { let sig = f.signature; sb.append(" ").append(f.fieldName).append(": "); if (sig.isAsync) { sb.append("async "); } sb.append("func("); for (var i = 0; i < sig.paramTypes.length; i += 1) { if (i > 0) { sb.append(", "); } sb.append(sig.paramNames[i]).append(": ") .append(scalarWitName(sig.paramTypes[i])); } sb.append(")"); if (sig.result != noComponentResult) { sb.append(" -> ").append(scalarWitName(sig.result)); } sb.append(";\n"); } /** The name of the synthetic world the derived document declares. */ let derivedWorldName = "imports"; /** * Whether a parsed document declares the interface `qualified` names — * package, interface and version all matching. This is what makes a * WIT-backed package's interfaces "provided": their real source * substitutes for the derived spelling, exactly as the compiler's own * baked WASI blocks do. */ /** * The WIT-backed packages' document, parsed once per source text. The * stdlib's vendored WASI is most of it, and every component compiled * in a process reads the same text: a test runner compiling hundreds * of programs paid a parse of the corpus for each, and the parse was * nearly all of the compile. */ var memoPackagesWit = ""; var memoPackagesAst: Ast | null = null; function packagesAstOf(packagesWit: String): Ast | null { if (packagesWit == "") { return null; } let cached = memoPackagesAst; if (cached != null && memoPackagesWit == packagesWit) { return cached; } let parsed = parse(packagesWit); memoPackagesWit = packagesWit; memoPackagesAst = parsed; return parsed; } /** * Add the packages `packages` declares to `into`, as nested packages: * what splicing their text at the end of `into`'s document parsed to, * when the document was built as text. The corpus's main package is * wrapped; its nested ones are shared as they are. */ function addPackages(into: Ast, packages: Ast) { let main = packages.packageName; if (main != null) { let name = main as PackageName; var docs = packages.packageDocs; if (docs == null) { docs = new Docs(name.span); } let pkg = new NestedPackage(docs as Docs, name); pkg.items = packages.items; into.nestedPackages.push(pkg); } for (let nested in packages.nestedPackages) { into.nestedPackages.push(nested); } } /** Whether `ast` declares the package `ns:pkg@version`, in its main * package or a nested one. */ function docDeclaresPackage(ast: Ast, packageKey: String): boolean { let keyOf = (pkg: PackageName | null) => { if (pkg == null) { return ""; } let p = pkg as PackageName; var key = `${p.namespace.name}:${p.name.name}`; if (p.version != null) { key = `${key}@${p.version as String}`; } return key; }; if (keyOf(ast.packageName) == packageKey) { return true; } for (let nested in ast.nestedPackages) { if (keyOf(nested.name) == packageKey) { return true; } } return false; } function docDeclaresInterface(ast: Ast, qualified: String): boolean { let path = splitInterfaceName(qualified); let matches = (pkg: PackageName | null, items: GrowableArray): boolean => { if (pkg == null) { return false; } let p = pkg as PackageName; if (`${p.namespace.name}:${p.name.name}` != path.packageName) { return false; } let version = if (p.version != null) p.version as String else ""; if (version != path.version) { return false; } for (let item in items) { if (item.tag != AstItemTag.Interface) { continue; } if ((item.interfaceDef as InterfaceDef).name.name == path.interfaceName) { return true; } } return false; }; if (matches(ast.packageName, ast.items)) { return true; } for (let nested in ast.nestedPackages) { if (matches(nested.name, nested.items)) { return true; } } return false; } /** * The shape's imports as a WIT document: one interface per `@external` * namespace, grouped into their packages, and a world importing each. * * `packagesWit` is the concatenated source of the program's WIT-backed * packages. An interface it declares is spliced whole rather than * derived, like the compiler's own baked WASI blocks — the synthesized * declarations for such interfaces are canonically flattened core * shapes, and deriving from those would declare the flattening as the * interface's type. */ export function deriveImportsWit( shape: ComponentShape, packagesWit: String = "" ): String { let packagesAst = packagesAstOf(packagesWit); let provided = (name: String) => packagesAst != null && docDeclaresInterface(packagesAst as Ast, name); // Group by interface, preserving first-appearance order (the same // grouping the emitter's aliases use), then group interfaces by // package for the nested-package declarations. let interfaceNames = new Array(); for (let imp in shape.imports) { var seen = false; for (let n in interfaceNames) { if (n == imp.interfaceName) { seen = true; } } if (!seen) { interfaceNames.push(imp.interfaceName); } } let sb = new StringBuilder(); sb.append("package zena:derived;\n\n"); // Interfaces whose real WIT a WIT-backed package carries — the // stdlib's vendored WASI, a manifest package's — are not derived: // `encodeImportTypes` adds the packages' parsed document to this // one, and the world imports them by name like any other. let renderedPackages = new Array(); for (let name in interfaceNames) { if (provided(name)) { continue; } let path = splitInterfaceName(name); let packageKey = `${path.packageName}@${path.version}`; if (packagesAst != null && docDeclaresPackage(packagesAst as Ast, packageKey)) { throw new Error( "The component target cannot import '" + name + "': its package " + "is one the program's WIT-backed packages carry real WIT for, " + "and this interface is not in it."); } var rendered = false; for (let p in renderedPackages) { if (p == packageKey) { rendered = true; } } if (rendered) { continue; } renderedPackages.push(packageKey); sb.append("package ").append(path.packageName); if (path.version != "") { sb.append("@").append(path.version); } sb.append(" {\n"); // Every interface of this package, in first-appearance order. for (let other in interfaceNames) { if (provided(other)) { continue; } let otherPath = splitInterfaceName(other); if (`${otherPath.packageName}@${otherPath.version}` != packageKey) { continue; } sb.append(" interface ").append(otherPath.interfaceName) .append(" {\n"); for (let imp in shape.imports) { if (imp.interfaceName == other) { renderFunc(sb, imp); } } sb.append(" }\n"); } sb.append("}\n\n"); } sb.append("world ").append(derivedWorldName).append(" {\n"); for (let name in interfaceNames) { sb.append(" import ").append(name).append(";\n"); } sb.append("}\n"); return sb.toString(); } /** * Encode the shape's imported interfaces; the emitter's front matter. * * Also the point where WIT-provided imports meet the document: each is * checked to actually exist in its interface, and its flattening * decides whether the lowering carries the canonical memory options. * An empty import list encodes to an empty world — no pieces, every * count zero — so the caller need not special-case it. A typed * `task.return` (a `return:` canon type) is still encoded then, against * a world with no imports: an async `main` returning a `String` needs * its `string` type whether or not the program imports anything. */ export function encodeImportTypes( shape: ComponentShape, packagesWit: String = "" ): EncodedImports { var typedReturn = false; for (let b in shape.builtins) { if (b.canonType.startsWith("return:")) { typedReturn = true; } } if (shape.imports.length == 0 && !typedReturn) { return new EncodedImports(); } let text = deriveImportsWit(shape, packagesWit); // Resolved once the packages are in: the derived world imports // their interfaces by name. let ast = parseSyntax(text); let packagesAst = packagesAstOf(packagesWit); if (packagesAst != null) { addPackages(ast, packagesAst as Ast); } resolve(ast); for (let imp in shape.imports) { if (!imp.witProvided) { continue; } let meta = funcFlatMeta(ast, imp.interfaceName, imp.fieldName); if (meta == null) { throw new Error( "The component target cannot import '" + imp.fieldName + "' from '" + imp.interfaceName + "': the interface's WIT " + "declares no such function."); } imp.needsMemoryLower = (meta as WitFuncMeta).needsMemory; } let encoder = new ComponentTypeEncoder(ast); let world = encoder.encodeWorld(derivedWorldName); let canonTypes = resolveCanonTypes(encoder, shape); // Mirrored after everything is encoded: the canon types appended // component-level types the count has to include. let out = mirrorEncodedWorld(world); copyIndices(canonTypes, out.canonTypeIndices); return out; } /** Copy every entry of `from` into `into`. */ function copyIndices(from: HashMap, into: HashMap): void { let keys = from.keys(); for (let key in keys) { into[key] = from[key]; } } /** * The type immediates the canon builtins need, by their `canonType` * spelling. A `resource.drop`'s type is the imported instance's own, * reachable only through an alias the encoder appends; a * `future:#` is the future's own component * type, its payload's named types alias-exported from the interface's * imported instance; a `return:#` is the result * type a typed `task.return` carries, named against the interface, or * structural at the component level when the interface is empty. * Resolved after the world so the instances exist, before mirroring so * the alias pieces travel. The FIRST '#' splits — a qualified interface * name contains none, a type may. */ function resolveCanonTypes( encoder: ComponentTypeEncoder, shape: ComponentShape ): HashMap { let indices = new Map(); let split = (canonType: String, prefixLength: i32, expected: String): (String, String) => { let spec = canonType.sliceBytes(prefixLength, canonType.length); var hashAt = -1; for (var i = 0; i < spec.length; i += 1) { if (spec.getByteAt(i) == 35) { hashAt = i; break; } // '#' } if (hashAt < 0) { throw new Error("Malformed canon type '" + canonType + "' (expected " + expected + ")"); } return (spec.sliceBytes(0, hashAt), spec.sliceBytes(hashAt + 1, spec.length)); }; for (let b in shape.builtins) { let canonType = b.canonType; if (indices.has(canonType)) { continue; } if (canonType.startsWith("resource:")) { let (iface, name) = split(canonType, 9, "resource:#"); indices[canonType] = encoder.aliasResourceType(iface, name); } else if (canonType.startsWith("future:")) { let (iface, payload) = split(canonType, 7, "future:#"); indices[canonType] = encoder.aliasFutureType(iface, payload); } else if (canonType.startsWith("stream:")) { let (iface, element) = split(canonType, 7, "stream:#"); indices[canonType] = encoder.aliasStreamType(iface, element); } else if (canonType.startsWith("return:")) { let (iface, text) = split(canonType, 7, "return:#"); indices[canonType] = encoder.encodeTypeText(iface, text); } } return indices; } /** `EncodedWorld`, mirrored into codegen's own classes. */ function mirrorEncodedWorld(world: EncodedWorld): EncodedImports { let out = new EncodedImports(); for (let piece in world.pieces) { out.pieces.push(new EncodedImportPiece(piece.id, piece.payload)); } out.typeCount = world.typeCount; out.instanceCount = world.instanceCount; for (let slot in world.dtorSlots) { out.dtorSlots.push(new ResourceDtorSlot(slot.qualified, slot.name)); } let names = world.instanceIndices.keys(); for (let name in names) { out.instanceIndices[name] = world.instanceIndices[name]; } let exporting = world.exportedTypes.keys(); for (let iface in exporting) { let mirrored = new GrowableArray(); for (let t in world.exportedTypes[iface]) { mirrored.push(new ExportedInstanceType(t.name, t.index)); } out.exportedTypes[iface] = mirrored; } return out; } /** * The default encoder: no world was declared, so each interface's WIT * is derived from the Zena declarations, except for the interfaces the * compiler carries real source for. */ final class DerivedImportEncoder implements ImportTypeEncoder { /** The concatenated WIT of the program's WIT-backed packages. */ #packagesWit: String; new(packagesWit: String = "") : #packagesWit = packagesWit; witProvided(interfaceName: String): boolean { let packagesAst = packagesAstOf(this.#packagesWit); return packagesAst != null && docDeclaresInterface(packagesAst as Ast, interfaceName); } encode(shape: ComponentShape): EncodedImports { return encodeImportTypes(shape, this.#packagesWit); } } /** The WIT spelling of a declared export's WIT type, for messages. */ function witTypeName(t: Type) { let opcode = exportableWitOpcode(t); if (opcode >= 0) { return scalarWitName(opcode); } return ""; } /** * The component opcode of a WIT type a program export can carry today — * the flat scalars and `string` — or -1. Richer world exports need the * marshaling C-track work and are rejected by name. */ function exportableWitOpcode(t: Type): i32 { if (t.tag == TypeTag.Bool) { return 0x7f; } if (t.tag == TypeTag.S8) { return 0x7e; } if (t.tag == TypeTag.U8) { return 0x7d; } if (t.tag == TypeTag.S16) { return 0x7c; } if (t.tag == TypeTag.U16) { return 0x7b; } if (t.tag == TypeTag.S32) { return 0x7a; } if (t.tag == TypeTag.U32) { return 0x79; } if (t.tag == TypeTag.S64) { return 0x78; } if (t.tag == TypeTag.U64) { return 0x77; } if (t.tag == TypeTag.F32) { return 0x76; } if (t.tag == TypeTag.F64) { return 0x75; } if (t.tag == TypeTag.String) { return 0x73; } return -1; } /** * Parse a declared world's document, with the program's WIT-backed * packages riding along so a world can `import wasi:cli/stdout@0.3.0;` * without vendoring it — unless the document declares those packages * itself, in which case its definitions win and theirs stay out of the * way. */ function parseWithWasi(witSource: String, packagesWit: String = "") { return parse(withWasiPackages(witSource, packagesWit)); } /** * `witSource` with the program's WIT-backed packages appended — the * stdlib's vendored WASI among them — so a declared world can import * their interfaces by name (`wasi:cli/stdout`, `wasi:http/types`) * without vendoring them. Unless the document declares one of those * packages itself, in which case its definitions win and the packages * stay out of the way, all of them: a document that vendors a package * is taken to be self-contained. */ /** * `witSource` with the program's WIT-backed packages appended — the * stdlib's vendored WASI among them — so a declared world can import * their interfaces by name (`wasi:cli/stdout`, `wasi:http/types`) * without vendoring them. Packages that `witSource` already declares * are omitted so they do not conflict. */ export function withWasiPackages(witSource: String, packagesWit: String = ""): String { if (packagesWit == "") { return witSource; } let lines = packagesWit.split("\n"); let sb = new StringBuilder(); sb.append(witSource); var currentSkipping = false; var hasAppended = false; for (let line in lines) { if (line.startsWith("package ")) { var end = line.length; for (var i = 8; i < line.length; i += 1) { let c = line.getByteAt(i); if (c == 59 || c == 32 || c == 123) { end = i; break; } // ';' ' ' '{' } let name = line.sliceBytes(0, end); currentSkipping = witSource.contains(name + ";") || witSource.contains(name + " {"); } if (!currentSkipping) { if (!hasAppended) { sb.append("\n"); hasAppended = true; } sb.append(line).append("\n"); } } return sb.toString(); } /** * One function export a declared world demands of the program: a * world-level function, or a function of an exported interface, whose * qualified name is `instanceName` (empty at world level). */ final class DeclaredExport { name: String; func: Func; instanceName: String; new(this.name, this.func, this.instanceName = ""); } /** * The encoder for a program compiled against a declared world * (`--wit`/`--world`): the world is the authority, emission follows it, * and every disagreement between the WIT and the Zena program is a * compile error. * * Concretely: the component imports exactly what the world imports, * with its `include`s expanded (expandedWorldItems), plus the interfaces * those imports and the world's exports `use` types from, which WIT * implies; every `@external` must name a function of one of those * interfaces, with a core signature matching the WIT's canonical * flattening; and the * export surfaces must agree in both directions — a world export the * program does not provide, or a program export the world does not * declare, is an error, as is a type or asyncness mismatch on one they * share. */ final class DeclaredWorldEncoder implements ImportTypeEncoder { #ast: Ast; var #worldName = ""; /** * The world's interface imports, by qualified name: the ones it names, * then the ones they and its exports `use` types from. */ #importedInterfaces = new Array(); /** The world's exported interfaces, by qualified name. */ #exportedInterfaces = new Array(); /** The world's function exports, in declaration order. */ #declaredExports = new Array(); new(witSource: String, worldName: String, packagesWit: String = "") : #ast = parseWithWasi(witSource, packagesWit) { var name = worldName; if (name == "") { let names = worldNames(this.#ast); if (names.length != 1) { var listed = ""; for (let n in names) { if (listed != "") { listed = listed + ", "; } listed = `${listed}'${n}'`; } throw new Error(if (names.length == 0) { "--wit names a document with no world; declare one, or pass " + "--world if it lives in another file." } else { "--wit names a document with more than one world (" + listed + "); say which with --world." }); } name = names[0]; } this.#worldName = name; var found = false; for (let item in this.#ast.items) { if (item.tag != AstItemTag.World) { continue; } let world = item.worldDef as WorldDef; if (world.name.name != name) { continue; } found = true; for (let wi in expandedWorldItems(this.#ast, world)) { if (wi.tag == WorldItemTag.Import) { this.#collectImport((wi.importItem as Import).kind); } else if (wi.tag == WorldItemTag.Export) { this.#collectExport((wi.exportItem as Export).kind); } // use / typedef fail in the encoder with their own messages; // collecting nothing here keeps that the one error. } } if (!found) { throw new Error("--world '" + name + "' is not a world the --wit " + "document declares."); } this.#addUsedInterfaces(); } /** * Adds the interfaces the world's imports and exports `use` types * from, and the ones those use, to its imports. WIT imports each of * them whether or not the world names it, and so does the encoder, so * a program may call into one: the stdlib's `wasi:http/service` world * reaches `types` only through `client` and `handler`. */ #addUsedInterfaces(): void { let pending = new Array(); for (let q in this.#importedInterfaces) { pending.push(q); } for (let q in this.#exportedInterfaces) { pending.push(q); } var i = 0; while (i < pending.length) { let qualified = pending[i]; i += 1; for (let used in this.#usedInterfaces(qualified)) { var known = false; for (let q in this.#importedInterfaces) { if (q == used) { known = true; } } if (!known) { this.#importedInterfaces.push(used); pending.push(used); } } } } /** The interfaces the interface `qualified` uses types from, by qualified name. */ #usedInterfaces(qualified: String): GrowableArray { let used = new Array(); let collect = (pkg: PackageName | null, items: GrowableArray) => { for (let item in items) { if (item.tag != AstItemTag.Interface) { continue; } let def = item.interfaceDef as InterfaceDef; if (qualifiedInterfaceName(pkg, def.name.name) != qualified) { continue; } for (let member in def.items) { if (member.tag != InterfaceItemTag.Use) { continue; } let from = (member.use as Use).from; used.push(if (from.tag == UsePathTag.Id) { qualifiedInterfaceName(pkg, (from.id as Id).name) } else { qualifiedInterfaceName(from.packageId, (from.name as Id).name) }); } } }; collect(this.#ast.packageName, this.#ast.items); for (let nested in this.#ast.nestedPackages) { collect(nested.name, nested.items); } return used; } #collectImport(kind: ExternKind): void { if (kind.tag == ExternKindTag.Path) { let path = kind.path as UsePath; let qualified = if (path.tag == UsePathTag.Id) { qualifiedInterfaceName(this.#ast.packageName, (path.id as Id).name) } else { qualifiedInterfaceName(path.packageId, (path.name as Id).name) }; this.#importedInterfaces.push(qualified); } else if (kind.tag == ExternKindTag.Interface) { // An inline interface imports under its plain name. this.#importedInterfaces.push((kind.name as Id).name); } // A world-level function import is legal WIT and is encoded, but a // program has no way to bind one yet — `@external` names an // interface and a field — so it is import surface the program // simply does not call. } #collectExport(kind: ExternKind): void { if (kind.tag == ExternKindTag.Func) { this.#declaredExports.push( new DeclaredExport((kind.name as Id).name, kind.funcDef as Func)); return; } if (kind.tag == ExternKindTag.Path) { // An exported interface: the component exports an instance of // that name, and each of the interface's functions is one export // the program provides, lifted into it. let path = kind.path as UsePath; let qualified = if (path.tag == UsePathTag.Id) { qualifiedInterfaceName(this.#ast.packageName, (path.id as Id).name) } else { qualifiedInterfaceName(path.packageId, (path.name as Id).name) }; let items = this.#interfaceItems(qualified); if (items == null) { throw new Error("The declared world exports '" + qualified + "', which the document does not declare."); } this.#exportedInterfaces.push(qualified); for (let item in items as GrowableArray) { if (item.tag == InterfaceItemTag.Func) { let nf = item.func as NamedFunc; this.#declaredExports.push( new DeclaredExport(nf.name.name, nf.func, qualified)); } else if (item.tag == InterfaceItemTag.TypeDef && (item.typeDef as TypeDef).tag == TypeDefTag.Resource) { // A resource is a class of the program's; its constructor, // methods and statics are exports under the canonical ABI's // mangled names, each implemented by a wrapper the compiler // writes around the class. let td = item.typeDef as TypeDef; let resourceName = td.name.name; for (let rf in td.resourceFuncs as GrowableArray) { let exported = if (rf.tag == ResourceFuncTag.Constructor) { "[constructor]" + resourceName } else if (rf.tag == ResourceFuncTag.Method) { `[method]${resourceName}.${rf.func.name.name}` } else { `[static]${resourceName}.${rf.func.name.name}` }; this.#declaredExports.push( new DeclaredExport(exported, rf.func.func, qualified)); } } } return; } throw new Error("The declared world exports an inline interface, " + "which a program cannot implement yet."); } /** The items of the interface `qualified` declares, or null. */ #interfaceItems(qualified: String): GrowableArray | null { for (let item in this.#ast.items) { if (item.tag != AstItemTag.Interface) { continue; } let def = item.interfaceDef as InterfaceDef; if (qualifiedInterfaceName(this.#ast.packageName, def.name.name) == qualified) { return def.items; } } for (let nested in this.#ast.nestedPackages) { for (let item in nested.items) { if (item.tag != AstItemTag.Interface) { continue; } let def = item.interfaceDef as InterfaceDef; if (qualifiedInterfaceName(nested.name, def.name.name) == qualified) { return def.items; } } } return null; } witProvided(interfaceName: String): boolean { return true; } encode(shape: ComponentShape): EncodedImports { this.#checkImports(shape); this.#checkExports(shape); let encoder = new ComponentTypeEncoder(this.#ast); let world = encoder.encodeWorld(this.#worldName); let canonTypes = resolveCanonTypes(encoder, shape); // An async export's lifted type is the WIT's, encoded here rather // than derived from a core signature: its parameters and result // may be any WIT type the wrapper marshals. Its memory need // decides the lift's options, and its typed return's, together. let exportTypes = new Map(); for (let e in shape.exports) { if (!e.witTyped) { continue; } var meta: WitFuncMeta | null = null; if (e.instanceName == "") { exportTypes[e.typeKey()] = encoder.encodeWorldExportFuncType(this.#worldName, e.exportName); meta = worldFuncFlatMeta(this.#ast, this.#worldName, e.exportName); } else { exportTypes[e.typeKey()] = encoder.encodeExportedInterfaceFuncType( e.instanceName, e.exportName); meta = interfaceExportFlatMeta(this.#ast, e.instanceName, e.exportName); } if (meta != null) { let m = meta as WitFuncMeta; e.needsMemoryLift = m.needsMemory; // A synchronous lift returns at most one core value; a result // flattening past that comes back as a return area's address, // which the host reads and then hands to `post-return`. e.needsPostReturnLift = !m.isAsync && m.resultFlatCount > 1; // The return area is in linear memory, so such a lift carries the // memory options whether or not any string or list is involved: // `func() -> size`, two bare floats, needs them. if (e.needsPostReturnLift) { e.needsMemoryLift = true; } } } let out = mirrorEncodedWorld(world); copyIndices(canonTypes, out.canonTypeIndices); copyIndices(exportTypes, out.exportTypeIndices); // An exported interface with a resource of its own is realized as // a nested component (NestedInstanceExport): encoded here, after // the world and every type the lifts name exist at component // level, with the instance's exports in the order the emitter // lifts them. let instanceNames = new Array(); for (let e in shape.exports) { if (e.instanceName == "") { continue; } var seen = false; for (let name in instanceNames) { if (name == e.instanceName) { seen = true; } } if (!seen) { instanceNames.push(e.instanceName); } } for (let name in instanceNames) { if (!encoder.interfaceDeclaresResource(name)) { continue; } let exportNames = new Array(); for (let e in shape.exports) { if (e.instanceName == name) { exportNames.push(e.exportName); } } let nested = encoder.encodeExportedInterfaceComponent(name, exportNames); let mirrored = new NestedInstanceExport(nested.bytes); for (let t in nested.typeImports) { mirrored.typeArgs.push(new NestedInstanceArg(t.name, t.outerIndex)); } for (let f in nested.funcImports) { mirrored.funcImports.push(f); } out.nestedExports[name] = mirrored; } return out; } /** * Every `@external` must name a function of an interface the world * explicitly imports, and the Zena declaration's core signature must * match the WIT's canonical flattening. The flattening determines * counts, not core value types, so this is a count-level check — * enough to catch a missing retptr, a forgotten parameter, or a sync * declaration against an async function. */ #checkImports(shape: ComponentShape): void { for (let imp in shape.imports) { var declared = false; for (let name in this.#importedInterfaces) { if (name == imp.interfaceName) { declared = true; } } if (!declared) { throw new Error("The program imports '" + imp.fieldName + "' from '" + imp.interfaceName + "', which the declared " + "world does not import. Add `import " + imp.interfaceName + ";` to the world, or drop the @external."); } let metaOpt = funcFlatMeta(this.#ast, imp.interfaceName, imp.fieldName); if (metaOpt == null) { throw new Error("The program imports '" + imp.fieldName + "' from '" + imp.interfaceName + "', and the interface's WIT " + "declares no such function."); } let meta = metaOpt as WitFuncMeta; if (imp.lowerAsync != meta.isAsync) { throw new Error("The program and the WIT disagree about whether '" + imp.fieldName + "' of '" + imp.interfaceName + "' is async: " + (if (meta.isAsync) { "the WIT says async, so the @external needs the \"async\" " + "option." } else { "the @external says async, and the WIT function is not." })); } // The core signature the canonical ABI will call with: flattened // parameters (or one pointer once they spill past sixteen), a // trailing return-area address when the result flattens to more // than one value, and for an async lowering a subtask handle as // the one result. var expectedParams = if (meta.paramFlatCount > 16) 1 else meta.paramFlatCount; var expectedResults = 0; if (imp.lowerAsync) { // The async lowering flattens at most four parameter core // values before spilling all of them through one pointer, any // result rides a trailing return-area address, and the one // core result is the packed subtask. expectedParams = if (meta.paramFlatCount > 4) 1 else meta.paramFlatCount; if (meta.resultFlatCount > 0) { expectedParams += 1; } expectedResults = 1; } else if (meta.resultFlatCount > 1) { expectedParams += 1; } else { expectedResults = meta.resultFlatCount; } if (imp.coreParamCount != expectedParams || imp.coreResultCount != expectedResults) { throw new Error("The @external declaration for '" + imp.fieldName + "' of '" + imp.interfaceName + "' does not match the WIT's " + "canonical flattening: the declaration has " + i32ToString(imp.coreParamCount) + " parameter(s) and " + i32ToString(imp.coreResultCount) + " result(s), and the " + "flattening needs " + i32ToString(expectedParams) + " and " + i32ToString(expectedResults) + "."); } imp.needsMemoryLower = meta.needsMemory; } } /** * The export surfaces must agree exactly: name for name, type for * type, and async for async. The world's export types are limited to * what the program can marshal today — flat scalars and `string` — * and anything richer is rejected by name rather than emitted as a * lift the wrappers cannot satisfy. */ #checkExports(shape: ComponentShape): void { for (let declared in this.#declaredExports) { var found = false; for (let e in shape.exports) { if (e.exportName == declared.name) { found = true; } } if (!found) { throw new Error("The declared world exports '" + declared.name + "', and the program does not export it."); } } for (let e in shape.exports) { var declaredOpt: DeclaredExport | null = null; for (let d in this.#declaredExports) { if (d.name == e.exportName) { declaredOpt = d; } } if (declaredOpt == null) { throw new Error("The program exports '" + e.exportName + "', which the declared world does not export. Add `export " + e.exportName + ": func(...);` to the world, or stop " + "exporting it."); } let declared = declaredOpt as DeclaredExport; // The export lands in the instance the world puts it in. Names // are matched across the world's exports as a whole, so one // name in two exported interfaces is not supported yet. e.instanceName = declared.instanceName; if (declared.func.isAsync) { // Implemented through the wrapper the compiler wrote for it // (wit-module-synth's `synthesizeExportWrapper`), lifted with // the callback and typed from the WIT in `encode`. The program's // own signature was checked against the WIT when the wrapper // was written. if (e.callbackCoreName == "") { throw new Error("The declared world exports '" + e.exportName + "' as an async function, and the program's export is " + "synchronous. Declare it `export async function " + e.exportName + "(...)`."); } continue; } if (e.callbackCoreName != "") { if (e.exportName == "main") { // A program that blocks has its entry lifted async whatever // the world says, because only a task the host lifted async // may block; a synchronous declaration is satisfied by it, // the value arriving through `task.return` as the host // waits. Its result was typed from the program's own // annotation (lib/component-entry.zena). continue; } throw new Error("The program's '" + e.exportName + "' is async, " + "and the declared world exports it as a synchronous function."); } if (e.witTyped) { // A synchronous export richer than scalars and strings: the // wrapper the compiler wrote marshals it, typed from the WIT. continue; } this.#checkExportSignature(declared, e); } } #checkExportSignature(declared: DeclaredExport, e: ComponentExportFunc): void { let witFunc = declared.func; let sig = e.signature; if (witFunc.isAsync != sig.isAsync) { throw new Error("The program and the WIT disagree about whether " + "export '" + declared.name + "' is async" + (if (sig.isAsync) { " — a program that sleeps is entered through an async lift, " + "so the world must declare `export " + declared.name + ": async func();`." } else { "." })); } if (witFunc.params.length != sig.paramTypes.length) { throw new Error("Export '" + declared.name + "': the WIT declares " + i32ToString(witFunc.params.length) + " parameter(s) and the " + "program's signature has " + i32ToString(sig.paramTypes.length) + "."); } for (var i = 0; i < witFunc.params.length; i += 1) { let want = exportableWitOpcode(witFunc.params[i].type); if (want < 0) { throw new Error("Export '" + declared.name + "', parameter '" + witFunc.params[i].name.name + "': the WIT type is not yet " + "expressible by a program export — only flat scalars and " + "string cross today."); } if (want != sig.paramTypes[i]) { throw new Error("Export '" + declared.name + "', parameter '" + witFunc.params[i].name.name + "': the WIT says '" + witTypeName(witFunc.params[i].type) + "' and the program's " + "signature says '" + scalarWitName(sig.paramTypes[i]) + "'."); } } let witResult = witFunc.result; if (witResult == null) { if (sig.result != noComponentResult) { throw new Error("Export '" + declared.name + "': the WIT declares " + "no result and the program's signature returns '" + scalarWitName(sig.result) + "'."); } return; } let want = exportableWitOpcode(witResult as Type); if (want < 0) { throw new Error("Export '" + declared.name + "': the WIT result " + "type is not yet expressible by a program export — only flat " + "scalars and string cross today."); } if (sig.result == noComponentResult) { throw new Error("Export '" + declared.name + "': the WIT declares " + "a '" + witTypeName(witResult as Type) + "' result and the " + "program's signature returns nothing."); } if (want != sig.result) { throw new Error("Export '" + declared.name + "': the WIT says '" + witTypeName(witResult as Type) + "' and the program's " + "signature says '" + scalarWitName(sig.result) + "'."); } } } /** * The encoder as drivers inject it (`BinaryGenerator.importEncoder`) — * the one edge from the compiler's build to the WIT parser. With no * arguments, the derived-world default; with `--wit`'s document text * (and `--world`'s name, or "" to take the document's sole world), the * declared world becomes the authority and disagreements are errors. */ export function makeImportEncoder( witSource: String | null = null, worldName: String = "", packagesWit: String = "" ): ImportTypeEncoder { if (witSource == null) { return new DerivedImportEncoder(packagesWit); } return new DeclaredWorldEncoder(witSource as String, worldName, packagesWit); }