/** * The WIT type encoder: a resolved document's world, as the type and * import sections of a component binary. * * This is the encoding half of what `wasm-tools component embed` does — * each imported interface becomes an instance type whose declarations * spell out its types and functions, and the component imports one * instance per interface. The compiler's component target consumes the * emitted pieces to head its own component; `encodeTypesOnlyComponent` * wraps the same pieces in a bare component so the encoding can be * verified on its own, by handing the bytes back to * `wasm-tools component wit`. * * The encoding rules that are easy to get wrong, verified against * `wasm-tools 1.252.0` byte for byte: * * - A type index in *value-type position* is a signed LEB128, because * the primitive opcodes (`0x64`–`0x7f`) are its negative range. An * index of 79 is two bytes. Indices in every other position (type * bounds, `own`, export declarations) are unsigned. * - Every WIT-*named* type — record, variant, enum, flags, resource, * `type` alias — must be **exported** from the instance type, and it * is the *export* that creates the index everything else refers to. * An instance type that keeps a record anonymous validates on its * own and then fails at the import with "instance not valid to be * used as import". Anonymous constructors (`list`, `tuple`, * `option`, `result`, `own`, `borrow`) need no export. * - A `use`d type crosses instances in two hops: at component level an * `alias export` pulls it out of the already-imported source * instance, and inside the dependent instance type an `alias outer` * (count 1: the enclosing component) brings it back in, where it is * re-exported under its local name. * - A method's `self: borrow` parameter is implicit in WIT and * explicit in the binary; a constructor returns `own` the same * way. Resource function export names carry the `[constructor]r` / * `[method]r.f` / `[static]r.f` prefixes. * * What this does not encode yet, each a loud `EncodeError` rather than * wrong bytes: `future`, `stream`, `map` and `error-context` (their * runtime is C6), fixed-length lists, world-level `use` and type * definitions, and `include`. A world's *exports* are skipped rather * than rejected — a types-only component has nothing to implement them * with, and the compiler's own export machinery is what lifts real * functions — and the skipped names are reported on the result so a * caller can say so. */ import { ByteBuffer } from 'zena:core'; import { Ast, AstItem, AstItemTag, InterfaceDef, WorldDef, InterfaceItem, InterfaceItemTag, TypeDef, TypeDefTag, Type, TypeTag, NamedFunc, Func, ResourceFunc, ResourceFuncTag, Use, UsePath, UsePathTag, IdUsePath, PackageUsePath, PackageName, WorldItem, WorldItemTag, Import, Export, ExternKind, ExternKindTag, Id, Include, Field, Case, EnumCaseDef, FlagDef, Parser, Docs, AttributeTag, } from './parser.zena'; /** A failure to encode: a construct the encoder cannot express yet. */ export class EncodeError extends Error { new(message: String) : super(message); } /** * A WIT type expression, parsed alone: wrapped in a one-alias * document so the ordinary parser reads it, then unwrapped. Names * stay syntactic — the caller resolves them against an interface. */ function parseTypeText(text: String): Type { let ast = Parser.parse( `package canon:payload;\ninterface t {\n type p = ${text};\n}\n`); for (let item in ast.items) { if (item.tag != AstItemTag.Interface) { continue; } for (let ii in (item.interfaceDef as InterfaceDef).items) { if (ii.tag != InterfaceItemTag.TypeDef) { continue; } let td = ii.typeDef as TypeDef; if (td.tag == TypeDefTag.Alias) { return td.aliasType as Type; } } } throw new EncodeError(`cannot parse the canon type payload '${text}'`); } // Component binary section ids. They are not core wasm's — a component // numbers its sections differently. export let sectionCoreModule = 1; export let sectionType = 7; export let sectionAlias = 6; export let sectionImport = 10; export let sectionExport = 11; /** The name a nested component imports the export `name` under: the * resource and the kind spelled out, as wit-component names them. */ function nestedFuncImportName(name: String) { if (name.startsWith("[constructor]")) { return "import-constructor-" + name.sliceBytes(13, name.length); } if (name.startsWith("[method]") || name.startsWith("[static]")) { let kind = name.sliceBytes(1, 7); let rest = name.sliceBytes(9, name.length); var out = `import-${kind}-`; for (var i = 0; i < rest.length; i += 1) { let c = rest.getByteAt(i); out = out + (if (c == 46) "-" else rest.sliceBytes(i, i + 1)); // '.' } return out; } return "import-func-" + name; } /** * One section of the component head, in emission order. The ids repeat — * a type section per instance type, an import section per import — which * the format allows and `wasm-tools` itself produces; interleaving is * what lets an alias name the import before it. */ export final class SectionPiece { id: i32; payload: ByteBuffer; new(this.id, this.payload); } /** * A value-type code: a local type index when `>= 0`, and a primitive's * opcode negated when `< 0`. The two need one representation because a * field or parameter holds either, and the sign is what keeps an index * of 0x73 distinct from `string`. */ function primCode(opcode: i32) { return 0 - opcode; } function writeValType(buf: ByteBuffer, code: i32) { if (code < 0) { buf.writeByte(0 - code); } else { // Signed on purpose: this position's grammar is // `typeidx | primvaltype`, and the primitives are the negative // SLEB128 space. An unsigned encoding of 64..127 would collide. buf.writeSLEB128(code); } } function writeName(buf: ByteBuffer, name: String) { buf.writeULEB128(name.length); for (var i = 0; i < name.length; i += 1) { buf.writeByte(name.getByteAt(i)); } } /** An import or export name: the plain-name discriminant, then the name. */ function writeExternName(buf: ByteBuffer, name: String) { buf.writeByte(0x00); writeName(buf, name); } function primOpcodeOf(tag: TypeTag): i32 { if (tag == TypeTag.Bool) { return 0x7f; } if (tag == TypeTag.S8) { return 0x7e; } if (tag == TypeTag.U8) { return 0x7d; } if (tag == TypeTag.S16) { return 0x7c; } if (tag == TypeTag.U16) { return 0x7b; } if (tag == TypeTag.S32) { return 0x7a; } if (tag == TypeTag.U32) { return 0x79; } if (tag == TypeTag.S64) { return 0x78; } if (tag == TypeTag.U64) { return 0x77; } if (tag == TypeTag.F32) { return 0x76; } if (tag == TypeTag.F64) { return 0x75; } if (tag == TypeTag.Char) { return 0x74; } if (tag == TypeTag.String) { return 0x73; } return -1; } /** * Where a `use`d name comes from: the qualified name of the interface * that declares it, and the name it has there (a `use` may rename). */ final class UseHop { source: String; typeName: String; new(this.source, this.typeName); } /** One interface the document defines, under its import name. */ final class RegisteredInterface { /** The name the component imports it by: `ns:pkg/iface@version`. */ qualifiedName: String; items: Array; /** * The package the interface was declared in. A bare `use foo` from * inside it resolves against this package, not the document's main * one — nested packages have their own name spaces. */ packageName: PackageName | null; new(this.qualifiedName, this.items, this.packageName = null); } /** * Where declarations land while one signature's types are encoded. * * An *instance* scope buffers instance declarations — `0x01` type, * `0x04` export — to become one instance type, and its indices are * local to it. The *component* scope (for a world-level function's * types) writes each type as a component-level type section instead, * and its indices are the component's. `#declareType` is the one place * that knows the difference. */ final class Scope { /** Buffered instance declarations; unused at component level. */ decls = new ByteBuffer(); var declCount = 0; var typeCount = 0; /** WIT type name → the local index its *export* created. */ named = new HashMap(); /** * The named indices that are resources. A resource name in value * position means `own` of it — `open: func() -> bucket` returns a * handle — so `#encodeType` has to know which lookups to wrap, and * a `use`d resource is still one. */ resourceIndices = new HashMap(); /** Structural key of an anonymous type → its index here. */ anon = new HashMap(); /** * The interface's type definitions not encoded yet, by name: a * reference to one encodes it on the spot, so an interface may * declare its types in any order — upstream WASI does, and the * encoding's own order is first use. */ pending = new HashMap(); var atComponentLevel = false; /** * Component-level only: the interface whose declarations resolve * named types this scope meets, each alias-exported from the * imported instance on first use. Set for a canon builtin's type — * a `future, error-code>>` names the * interface's types from outside any instance scope. */ var aliasSource: RegisteredInterface | null = null; /** * Set while encoding into a nested component (an exported * interface's): declared types go to its sections and count in its * own index space, and a named type of the interface is imported * into it on first use rather than aliased. */ var nested: NestedComponent | null = null; /** * The nested component's hooks, installed by its encoder: where a * declared type goes, and how a named type is met. Closures rather * than calls on `nested`, because a program that never builds a * nested component (the encoder's own round-trip tool) never * constructs the class, and the compiler refuses a method call on * a class it never constructed even on a path that cannot run * (issue #447); a closure that is never created reaches nothing. */ var nestedDeclare: ((body: ByteBuffer) => void) | null = null; var nestedNamed: ((name: String) => i32) | null = null; } /** * A type a nested component imports from the enclosing one: the * import's name, and the enclosing component's type index the * instantiation supplies for it. */ export final class NestedTypeImport { name: String; outerIndex: i32; new(this.name, this.outerIndex); } /** * An exported interface realized as a nested component, the shape an * exported resource needs: a component's own exports name a resource * (`export "surface" (type $r)`), and a `[method]surface.size` export * is validated against the names in that context, which an instance * built from a bag of exports never has. The nested component imports * each resource as a subtype of `resource` and each non-resource type * as `eq` of a local copy, imports the enclosing component's lifted * functions at types naming those, exports the resources and fresh * copies of the other types under their names, and exports each * function with a type naming the exported ones — what wit-component * emits. `funcImports` are the function import names, one per export * name the encoding was asked for, in that order. */ export final class NestedExport { bytes = new ByteBuffer(); typeImports = new GrowableArray(); funcImports = new GrowableArray(); } /** A nested component under construction. */ final class NestedComponent { out: NestedExport; var funcCount = 0; /** The interface's own non-resource types imported so far, to * export again once the resources have their names. */ ownTypes = new GrowableArray(); /** Whether the export phase has begun: a named type met now is * exported as a fresh copy rather than imported. */ var exporting = false; new(this.out); section(id: i32, payload: ByteBuffer): void { this.out.bytes.writeByte(id); this.out.bytes.writeULEB128(payload.length); this.out.bytes.writeBuffer(payload); } } /** * A resource the program provides, in the order its type was encoded: * the k-th one's destructor is core function k. The emitter keeps that * promise with a shim core module it instantiates before anything * else — a table of function references and one trampoline per slot, * aliased as the first core functions — and fills the table with the * program's destructor exports once the program instance exists. The * indirection is what lets the resource type name a destructor that * lives in an instance which cannot exist yet: the program's core * module imports `resource.new` for the type, so the type comes first. */ export final class DtorSlot { qualified: String; name: String; new(this.qualified, this.name); } /** What `encodeWorld` produced. */ /** One type an exported interface declares itself: its name in the * interface, and the component-level type index it was encoded at. */ export final class ExportedTypeIndex { name: String; index: i32; new(this.name, this.index); } export final class EncodedWorld { /** The component-head sections, in order. */ pieces = new GrowableArray(); /** * The types each exported interface declares itself, by the * interface's qualified name, in encoding order. Encoded at * component level as a function type of the interface first names * them; the exported instance exports each under its name, so the * interface reads back with its own types. */ exportedTypes = new HashMap>(); /** The program's resources with a destructor slot each (`DtorSlot`). */ dtorSlots = new GrowableArray(); /** How many component-level types the pieces defined. */ var typeCount = 0; /** How many instances the pieces imported. */ var instanceCount = 0; /** How many component-level functions the pieces imported. */ var funcImportCount = 0; /** * Each imported interface's component-level instance index, by its * qualified name. Interfaces are imported in dependency order, not * request order, so a consumer aliasing functions out of an instance * looks the index up rather than assuming it. */ instanceIndices = new HashMap(); /** World exports the encoding skipped, for the caller to report. */ skippedExports = new GrowableArray(); } export final class ComponentTypeEncoder { #ast: Ast; #result = new EncodedWorld(); /** Everything importable by qualified name, main package and nested. */ #interfaces = new GrowableArray(); /** Qualified interface name → component-level instance index. */ #instanceIndex = new HashMap(); /** * `qualifiedInterface + '#' + typeName` → the component-level type * index its `alias export` created. One alias serves every interface * that uses the type. */ #aliasedTypes = new HashMap(); new(ast: Ast) : #ast = ast { this.#registerPackage(ast.packageName, ast.items); for (let nested in ast.nestedPackages) { this.#registerPackage(nested.name, nested.items); } } #registerPackage(pkgName: PackageName | null, items: Array): void { for (let item in items) { if (item.tag == AstItemTag.Interface) { let def = item.interfaceDef as InterfaceDef; this.#interfaces.push(new RegisteredInterface( qualifiedInterfaceName(pkgName, def.name.name), def.items, pkgName)); } } } /** * Encode the world's imports. Interfaces are imported in first-use * order with their `use` dependencies ahead of them — WIT implies the * import of anything a used type comes from, so a dependency absent * from the world's own list still gets an instance. An `include` * brings the included world's imports and exports * (expandedWorldItems). */ encodeWorld(worldName: String): EncodedWorld { let world = this.#findWorld(worldName); for (let item in expandedWorldItems(this.#ast, world)) { if (item.tag == WorldItemTag.Import) { this.#encodeWorldImport((item.importItem as Import).kind); } else if (item.tag == WorldItemTag.Export) { this.#result.skippedExports.push(externName( (item.exportItem as Export).kind)); } else if (item.tag == WorldItemTag.Use) { throw new EncodeError("world-level `use` is not encodable yet"); } else if (item.tag == WorldItemTag.TypeDef) { throw new EncodeError( "world-level type definitions are not encodable yet"); } else { throw new EncodeError("world `include` is not encodable yet"); } } return this.#result; } #encodeWorldImport(kind: ExternKind): void { if (kind.tag == ExternKindTag.Path) { this.#importInterface(this.#resolveInterface(kind.path as UsePath)); } else if (kind.tag == ExternKindTag.Func) { this.#importWorldFunc((kind.name as Id).name, kind.funcDef as Func); } else { // An inline interface: the same encoding, imported under the // plain name its declaration gave it. this.#importNamedInterface(new RegisteredInterface( (kind.name as Id).name, kind.items as GrowableArray)); } } /** * A world-level function import: its types live at component level, * each in a type section of its own, then the import names the * functype. Only structural types can appear here — a named type * would have arrived through world-level `use` or a world type * definition, both rejected before this runs. */ #importWorldFunc(name: String, func: Func): void { let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; let funcType = this.#encodeFuncType(scope, func, -1, func.isAsync); let imp = new ByteBuffer(); imp.writeULEB128(1); writeExternName(imp, name); imp.writeByte(0x01); // externdesc: func imp.writeULEB128(funcType); this.#result.pieces.push(new SectionPiece(sectionImport, imp)); this.#result.funcImportCount += 1; } #resolveInterface( path: UsePath, contextPackage: PackageName | null = null ): RegisteredInterface { let qualified = if (path.tag == UsePathTag.Id) { // A bare name resolves within the package the `use` sits in; // only a top-level world's imports resolve against the main one. qualifiedInterfaceName( contextPackage ?? this.#ast.packageName, (path.id as Id).name) } else { qualifiedInterfaceName(path.packageId, (path.name as Id).name) }; for (let r in this.#interfaces) { if (r.qualifiedName == qualified) { return r; } } throw new EncodeError("interface '" + qualified + "' is not defined in this document; cross-document " + "dependencies are not resolvable yet"); } #importInterface(reg: RegisteredInterface): void { if (this.#instanceIndex.has(reg.qualifiedName)) { return; } // Dependencies first: an `alias export` can only name an instance // that is already imported. for (let item in reg.items) { if (item.tag == InterfaceItemTag.Use) { this.#importInterface(this.#resolveInterface( (item.use as Use).from, reg.packageName)); } } this.#importNamedInterface(reg); } #importNamedInterface(reg: RegisteredInterface): void { let scope = new Scope(); for (let item in reg.items) { if (item.tag == InterfaceItemTag.TypeDef) { let td = item.typeDef as TypeDef; scope.pending[td.name.name] = td; } } for (let item in reg.items) { if (item.tag == InterfaceItemTag.Use) { this.#encodeUse(scope, item.use as Use, reg.packageName); } else if (item.tag == InterfaceItemTag.TypeDef) { let td = item.typeDef as TypeDef; // Unless a reference already encoded it. if (scope.pending.has(td.name.name)) { this.#encodeTypeDef(scope, td); } } else { this.#encodeInterfaceFunc(scope, item.func as NamedFunc, "", -1); } } let types = new ByteBuffer(); types.writeULEB128(1); types.writeByte(0x42); // instance type types.writeULEB128(scope.declCount); types.writeBuffer(scope.decls); this.#result.pieces.push(new SectionPiece(sectionType, types)); let instanceTypeIndex = this.#result.typeCount; this.#result.typeCount += 1; let imp = new ByteBuffer(); imp.writeULEB128(1); writeExternName(imp, reg.qualifiedName); imp.writeByte(0x05); // externdesc: instance imp.writeULEB128(instanceTypeIndex); this.#result.pieces.push(new SectionPiece(sectionImport, imp)); this.#instanceIndex[reg.qualifiedName] = this.#result.instanceCount; this.#result.instanceIndices[reg.qualifiedName] = this.#result.instanceCount; this.#result.instanceCount += 1; } /** * A `use`: each named type is aliased out of its source instance at * component level (once, however many interfaces use it), aliased * back in through `outer`, and re-exported under its local name — * which may differ, `use` renames. */ #encodeUse( scope: Scope, use: Use, contextPackage: PackageName | null ): void { let source = this.#resolveInterface(use.from, contextPackage); for (let n in use.names) { let componentIndex = this.#usedTypeIndex(new UseHop(source.qualifiedName, n.name.name)); scope.decls.writeByte(0x02); // instancedecl: alias scope.decls.writeByte(0x03); // sort: type scope.decls.writeByte(0x02); // target: outer scope.decls.writeULEB128(1); // count 1: the enclosing component scope.decls.writeULEB128(componentIndex); scope.declCount += 1; let inner = scope.typeCount; scope.typeCount += 1; let asName = n.asName; let localName = asName?.name ?? n.name.name; let exported = this.#exportType(scope, localName, inner); scope.named[localName] = exported; if (this.#isResource(source, n.name.name)) { scope.resourceIndices[exported] = true; } } } /** * Whether `name` in `reg` is a resource — directly, through a `use`, * or through a `type` alias of either. Resource-ness survives every * hop, and it decides whether a value-position mention is a handle. */ /** * The interface `reg` `use`s `name` from, and the name there, or * null when `reg` does not `use` it. */ #useSourceOf(reg: RegisteredInterface, name: String): UseHop | null { for (let item in reg.items) { if (item.tag != InterfaceItemTag.Use) { continue; } let use = item.use as Use; for (let n in use.names) { let asName = n.asName; let localName = asName?.name ?? n.name.name; if (localName == name) { let source = this.#resolveInterface(use.from, reg.packageName); return new UseHop(source.qualifiedName, n.name.name); } } } return null; } #isResource(reg: RegisteredInterface, name: String): boolean { for (let item in reg.items) { if (item.tag == InterfaceItemTag.TypeDef) { let td = item.typeDef as TypeDef; if (td.name.name == name) { if (td.tag == TypeDefTag.Resource) { return true; } if (td.tag == TypeDefTag.Alias) { let target = td.aliasType as Type; if (target.tag == TypeTag.Name) { return this.#isResource(reg, (target.name as Id).name); } } return false; } } else if (item.tag == InterfaceItemTag.Use) { let use = item.use as Use; for (let n in use.names) { let asName = n.asName; let localName = asName?.name ?? n.name.name; if (localName == name) { return this.#isResource( this.#resolveInterface(use.from, reg.packageName), n.name.name); } } } } return false; } /** * The component-level type index of `typeName` exported by an * already-imported interface, alias-exporting it on first use. * Public for the canon builtins: `resource.drop` takes the imported * resource's own (nominal) type as its immediate, which only an * alias can name. */ aliasResourceType(qualifiedInterface: String, typeName: String): i32 { let reg = this.#findRegistered(qualifiedInterface); if (reg == null || !this.#isResource( reg, typeName)) { throw new EncodeError("'" + typeName + "' is not a resource of '" + qualifiedInterface + "'"); } if (!this.#instanceIndex.has(qualifiedInterface)) { // No instance to alias from: the interface is exported, and the // resource is the program's own — `resource.new` and // `resource.rep` name its component-level type. return this.#encodeExportedOwnType(reg, typeName); } return this.#aliasTypeExport(qualifiedInterface, typeName); } /** * The component-level type index of `future`, the * payload parsed as WIT against `qualifiedInterface`'s declarations * — named types alias-exported from the imported instance on first * use, or, for an exported interface, from the imported source its * `use` names. Public for the canon builtins: the future.* family's * canon entry carries the future's own component type, and a payload * like `result, error-code>` names the interface's * types from outside any instance scope. An empty `payloadText` is * the bare `future`; an empty `qualifiedInterface` is a world-level * function's future, whose payload is structural. */ aliasFutureType(qualifiedInterface: String, payloadText: String): i32 { return this.#aliasEndType(0x65, "future", qualifiedInterface, payloadText); } /** * The component-level type index of `stream`, the * element parsed against `qualifiedInterface`'s declarations the * way a future's payload is. Public for the canon builtins: the * stream.* family's canon entry carries the stream's own type. */ aliasStreamType(qualifiedInterface: String, elementText: String): i32 { return this.#aliasEndType(0x66, "stream", qualifiedInterface, elementText); } /** `future

` (0x65) or `stream` (0x66) at component level, * memoized per interface and payload spelling. */ #aliasEndType(opcode: i32, head: String, qualifiedInterface: String, payloadText: String): i32 { let key = `${qualifiedInterface}#${head}<${payloadText}>`; if (let (true, existing) = this.#aliasedTypes.get(key)) { return existing; } let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; if (qualifiedInterface != "") { let reg = this.#findRegistered(qualifiedInterface); if (reg == null) { throw new EncodeError(`'${qualifiedInterface}' is not a known interface`); } scope.aliasSource = reg; } let inner = if (payloadText != "") { this.#encodeType(scope, parseTypeText(payloadText)) } else { -1 }; let body = new ByteBuffer(); body.writeByte(opcode); if (payloadText != "") { body.writeByte(0x01); writeValType(body, inner); } else { body.writeByte(0x00); } let index = this.#declareType(scope, body); this.#aliasedTypes[key] = index; return index; } /** * The component-level valtype — a primitive's code, or a type * index — of the WIT type `typeText`. Parsed against * `qualifiedInterface`'s declarations when one is named, its named * types alias-exported from the imported instance on first use; * at the component's own level when the name is empty, where only * structural types can appear. Public for the canon builtins: a * typed `task.return` carries the result type of the export it * returns for. */ encodeTypeText(qualifiedInterface: String, typeText: String): i32 { let key = `${qualifiedInterface}#type:${typeText}`; if (let (true, existing) = this.#aliasedTypes.get(key)) { return existing; } let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; if (qualifiedInterface != "") { // Imported or exported: an exported interface's named types // reach it through `use`, and `#namedIndex` follows the use to // the imported source. let reg = this.#findRegistered(qualifiedInterface); if (reg == null) { throw new EncodeError(`'${qualifiedInterface}' is not a known interface`); } scope.aliasSource = reg; } let code = this.#encodeType(scope, parseTypeText(typeText)); this.#aliasedTypes[key] = code; return code; } /** * The component-level function type of `funcName` in the exported * interface `qualifiedInterface`, for the lift of the core function * implementing it. Its named types come through the interface's * `use`s, alias-exported from the imported sources; a type the * exported interface declares itself is not encodable yet. */ encodeExportedInterfaceFuncType( qualifiedInterface: String, funcName: String ): i32 { let reg = this.#findRegistered(qualifiedInterface); if (reg == null) { throw new EncodeError(`'${qualifiedInterface}' is not a known interface`); } for (let item in reg.items) { if (item.tag != InterfaceItemTag.Func) { continue; } let nf = item.func as NamedFunc; if (nf.name.name != funcName) { continue; } let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; scope.aliasSource = reg; return this.#encodeFuncType(scope, nf.func, -1, nf.func.isAsync); } // A resource's function, exported under its mangled name: the // program's resource type is encoded (or found) at component // level, and a method's `self` is a borrow of it. let found = resourceFuncNamed(reg.items, funcName); if (found != null) { let rf = found.rf; let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; scope.aliasSource = reg; let resourceIndex = this.#namedIndex(scope, found.resourceName); if (rf.tag == ResourceFuncTag.Constructor) { return this.#constructorFuncType(scope, rf.func.func, resourceIndex); } if (rf.tag == ResourceFuncTag.Method) { let borrowIndex = this.#handleType(scope, 0x68, resourceIndex); return this.#encodeFuncType(scope, rf.func.func, borrowIndex, rf.func.func.isAsync); } return this.#encodeFuncType(scope, rf.func.func, -1, rf.func.func.isAsync); } throw new EncodeError("'" + qualifiedInterface + "' declares no function '" + funcName + "'"); } /** Whether the interface `qualified` declares a resource of its own. */ interfaceDeclaresResource(qualified: String): boolean { let reg = this.#findRegistered(qualified); if (reg == null) { return false; } for (let item in reg.items) { if (item.tag == InterfaceItemTag.TypeDef && (item.typeDef as TypeDef).tag == TypeDefTag.Resource) { return true; } } return false; } /** * The nested component realizing the exported interface * `qualifiedInterface` (see `NestedExport`), with the functions the * program exports under `exportNames` — every function of the * interface, in the order the emitter lifts them. */ encodeExportedInterfaceComponent(qualifiedInterface: String, exportNames: Array): NestedExport { let regOpt = this.#findRegistered(qualifiedInterface); if (regOpt == null) { throw new EncodeError(`'${qualifiedInterface}' is not a known interface`); } let reg = regOpt; let out = new NestedExport(); let nested = new NestedComponent(out); out.bytes.writeU32(0x6D736100); // \0asm out.bytes.writeU32(0x0001000D); // version 0x0d, layer 1: a component let scope = new Scope(); scope.nested = nested; scope.aliasSource = reg; scope.nestedDeclare = (body: ByteBuffer) => { let section = new ByteBuffer(); section.writeULEB128(1); section.writeBuffer(body); nested.section(sectionType, section); }; scope.nestedNamed = (name: String) => this.#nestedNamedIndex(scope, name); // 1. Every resource the interface declares or `use`s, imported as // a subtype of `resource`; the enclosing component's own resource // type, or its alias of an imported instance's, instantiates it. let resources = new GrowableArray(); for (let item in reg.items) { if (item.tag == InterfaceItemTag.TypeDef) { let td = item.typeDef as TypeDef; if (td.tag == TypeDefTag.Resource) { resources.push(td.name.name); } } else if (item.tag == InterfaceItemTag.Use) { for (let n in (item.use as Use).names) { let asName = n.asName; let localName = asName?.name ?? n.name.name; if (this.#isResource(reg, localName)) { resources.push(localName); } } } } for (let r in resources) { let hop = this.#useSourceOf(reg, r); let outerIndex = if (hop == null) { this.#encodeExportedOwnType(reg, r) } else { this.#usedTypeIndex(hop) }; let imp = new ByteBuffer(); imp.writeULEB128(1); writeExternName(imp, "import-type-" + r); imp.writeByte(0x03); // externdesc: type imp.writeByte(0x01); // typebound: sub resource nested.section(sectionImport, imp); let index = scope.typeCount; scope.typeCount += 1; scope.named[r] = index; scope.resourceIndices[index] = true; out.typeImports.push(new NestedTypeImport("import-type-" + r, outerIndex)); } // 2. The functions, imported at types naming the imported // resources (an import may name only imported types). for (let name in exportNames) { let typeIndex = this.#nestedFuncType(scope, reg, name); let importName = nestedFuncImportName(name); let imp = new ByteBuffer(); imp.writeULEB128(1); writeExternName(imp, importName); imp.writeByte(0x01); // externdesc: func imp.writeULEB128(typeIndex); nested.section(sectionImport, imp); out.funcImports.push(importName); nested.funcCount += 1; } // 3. The exports: the resources under their names — which is what // names them for the method-style exports — then fresh copies of // the interface's other types, then each function at a type naming // the exported ones, ascribed on the export. nested.exporting = true; scope.anon.clear(); for (let name in nested.ownTypes) { scope.named.delete(name); } for (let r in resources) { let imported = scope.named[r]; let index = this.#nestedExportType(scope, r, imported); scope.named[r] = index; scope.resourceIndices[index] = true; } let ownTypes = new GrowableArray(); for (let name in nested.ownTypes) { ownTypes.push(name); } for (let name in ownTypes) { this.#namedIndex(scope, name); } for (var i = 0; i < exportNames.length; i += 1) { let ascribed = this.#nestedFuncType(scope, reg, exportNames[i]); let exp = new ByteBuffer(); exp.writeULEB128(1); writeExternName(exp, exportNames[i]); exp.writeByte(0x01); // sort: func exp.writeULEB128(i); exp.writeByte(0x01); // an ascribed type follows exp.writeByte(0x01); // externdesc: func exp.writeULEB128(ascribed); nested.section(sectionExport, exp); } return out; } /** Exports nested type `index` under `name`; the export's own index. */ #nestedExportType(scope: Scope, name: String, index: i32): i32 { let nested = scope.nested as NestedComponent; let exp = new ByteBuffer(); exp.writeULEB128(1); writeExternName(exp, name); exp.writeByte(0x03); // sort: type exp.writeULEB128(index); exp.writeByte(0x00); // no ascribed type nested.section(sectionExport, exp); let exported = scope.typeCount; scope.typeCount += 1; return exported; } /** * A named non-resource type met inside a nested component: its * structure declared there, resolved against the interface that * declares it, then imported as `eq` of that declaration (the * enclosing component's type instantiates it) — or, in the export * phase, exported as a fresh copy under its name. */ #nestedNamedIndex(scope: Scope, name: String): i32 { let nested = scope.nested as NestedComponent; let reg = scope.aliasSource as RegisteredInterface; if (this.#isResource(reg, name)) { throw new EncodeError("resource '" + name + "' of '" + reg.qualifiedName + "' was not imported into its exported instance"); } var owner = reg; var tdName = name; var outerIndex = -1; let hop = this.#useSourceOf(reg, name); if (hop == null) { if (!this.#declaresType(reg, name)) { throw new EncodeError("'" + reg.qualifiedName + "' declares no type '" + name + "'"); } outerIndex = this.#encodeExportedOwnType(reg, name); } else { let h = hop; let source = this.#findRegistered(h.source); if (source == null) { throw new EncodeError(`'${h.source}' is not a known interface`); } owner = source; tdName = h.typeName; outerIndex = this.#usedTypeIndex(h); } var found: TypeDef | null = null; for (let item in owner.items) { if (item.tag != InterfaceItemTag.TypeDef) { continue; } let td = item.typeDef as TypeDef; if (td.name.name == tdName) { found = td; } } if (found == null) { throw new EncodeError("'" + owner.qualifiedName + "' declares no type '" + tdName + "'"); } let td = found; let savedSource = scope.aliasSource; scope.aliasSource = owner; var local = -1; if (td.tag == TypeDefTag.Alias) { let target = td.aliasType as Type; if (target.tag == TypeTag.Name) { local = this.#namedIndex(scope, (target.name as Id).name); } else { let encoded = this.#encodeType(scope, target); if (encoded < 0) { let body = new ByteBuffer(); body.writeByte(0 - encoded); local = this.#declareType(scope, body); } else { local = encoded; } } } else { local = this.#encodeTypeBody(scope, td); } scope.aliasSource = savedSource; if (nested.exporting) { let index = this.#nestedExportType(scope, name, local); scope.named[name] = index; return index; } let imp = new ByteBuffer(); imp.writeULEB128(1); writeExternName(imp, "import-type-" + name); imp.writeByte(0x03); // externdesc: type imp.writeByte(0x00); // typebound: eq imp.writeULEB128(local); nested.section(sectionImport, imp); let index = scope.typeCount; scope.typeCount += 1; scope.named[name] = index; nested.out.typeImports.push( new NestedTypeImport("import-type-" + name, outerIndex)); if (hop == null) { nested.ownTypes.push(name); } return index; } /** * The function type of the export `name` of `reg` in `scope` — a * free function's, or a resource function's found by its mangled * name, with a constructor's implicit `own` result and a method's * `self` borrow. */ #nestedFuncType(scope: Scope, reg: RegisteredInterface, name: String): i32 { for (let item in reg.items) { if (item.tag != InterfaceItemTag.Func) { continue; } let nf = item.func as NamedFunc; if (nf.name.name == name) { return this.#encodeFuncType(scope, nf.func, -1, nf.func.isAsync); } } let found = resourceFuncNamed(reg.items, name); if (found == null) { throw new EncodeError("'" + reg.qualifiedName + "' declares no function '" + name + "'"); } let rf = found.rf; let resourceIndex = scope.named[found.resourceName]; if (rf.tag == ResourceFuncTag.Constructor) { return this.#constructorFuncType(scope, rf.func.func, resourceIndex); } if (rf.tag == ResourceFuncTag.Method) { let borrowIndex = this.#handleType(scope, 0x68, resourceIndex); return this.#encodeFuncType(scope, rf.func.func, borrowIndex, rf.func.func.isAsync); } return this.#encodeFuncType(scope, rf.func.func, -1, rf.func.func.isAsync); } /** A constructor's function type: its parameters, and `own` of the * resource as the result. */ #constructorFuncType(scope: Scope, func: Func, resourceIndex: i32): i32 { let ownIndex = this.#handleType(scope, 0x69, resourceIndex); let paramCodes = new GrowableArray(); for (let p in func.params) { paramCodes.push(this.#encodeType(scope, p.type)); } let body = new ByteBuffer(); body.writeByte(0x40); body.writeULEB128(func.params.length); for (var i = 0; i < func.params.length; i += 1) { writeName(body, func.params[i].name.name); writeValType(body, paramCodes[i]); } body.writeByte(0x00); writeValType(body, ownIndex); return this.#declareType(scope, body); } /** * The component-level function type of the world's function export * `exportName`, for the lift of the core function implementing it. * Its types are structural, like a world-level import's: a named * type would need world-level `use` encoding. */ encodeWorldExportFuncType(worldName: String, exportName: String): i32 { let world = this.#findWorld(worldName); for (let item in expandedWorldItems(this.#ast, world)) { if (item.tag != WorldItemTag.Export) { continue; } let kind = (item.exportItem as Export).kind; if (kind.tag != ExternKindTag.Func) { continue; } if ((kind.name as Id).name != exportName) { continue; } let func = kind.funcDef as Func; let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; return this.#encodeFuncType(scope, func, -1, func.isAsync); } throw new EncodeError("world '" + worldName + "' exports no function named '" + exportName + "'"); } #findWorld(worldName: String): WorldDef { for (let item in this.#ast.items) { if (item.tag == AstItemTag.World) { let def = item.worldDef as WorldDef; if (def.name.name == worldName) { return def; } } } throw new EncodeError( `no world named '${worldName}' in this document`); } /** The registered interface named `qualified`, or null. */ #findRegistered(qualified: String): RegisteredInterface | null { for (let reg in this.#interfaces) { if (reg.qualifiedName == qualified) { return reg; } } return null; } /** * The component-level type index of the type a `use` hop names: an * alias out of the source's instance when the source is imported, * or, when the source is an exported interface, its own declaration * at component level (`#encodeExportedOwnType`), following a further * `use` of the source's first. An exported interface may `use` a * type another exported interface declares, as a plugin kind uses * the resources of the views it vends. */ #usedTypeIndex(hop: UseHop): i32 { if (this.#instanceIndex.has(hop.source)) { return this.#aliasTypeExport(hop.source, hop.typeName); } let source = this.#findRegistered(hop.source); if (source == null) { throw new EncodeError(`'${hop.source}' is not a known interface`); } let further = this.#useSourceOf(source, hop.typeName); if (further != null) { return this.#usedTypeIndex(further); } return this.#encodeExportedOwnType(source, hop.typeName); } #aliasTypeExport(qualifiedInterface: String, typeName: String): i32 { let key = `${qualifiedInterface}#${typeName}`; if (let (true, existing) = this.#aliasedTypes.get(key)) { return existing; } if (!this.#instanceIndex.has(qualifiedInterface)) { throw new EncodeError("'" + qualifiedInterface + "' is not imported yet, so nothing can use its types"); } let alias = new ByteBuffer(); alias.writeULEB128(1); alias.writeByte(0x03); // sort: type alias.writeByte(0x00); // target: instance export alias.writeULEB128(this.#instanceIndex[qualifiedInterface]); writeName(alias, typeName); this.#result.pieces.push(new SectionPiece(sectionAlias, alias)); let index = this.#result.typeCount; this.#result.typeCount += 1; this.#aliasedTypes[key] = index; return index; } /** Export local type `index` under `name`; the export's own index. */ #exportType(scope: Scope, name: String, index: i32): i32 { scope.decls.writeByte(0x04); // instancedecl: export writeExternName(scope.decls, name); scope.decls.writeByte(0x03); // externdesc: type scope.decls.writeByte(0x00); // typebound: eq scope.decls.writeULEB128(index); scope.declCount += 1; let exported = scope.typeCount; scope.typeCount += 1; return exported; } /** Declare an anonymous type from `body`; the index it gets. */ #declareType(scope: Scope, body: ByteBuffer): i32 { let nestedDeclare = scope.nestedDeclare; if (nestedDeclare != null) { nestedDeclare(body); } else if (scope.atComponentLevel) { let section = new ByteBuffer(); section.writeULEB128(1); section.writeBuffer(body); this.#result.pieces.push(new SectionPiece(sectionType, section)); this.#result.typeCount += 1; } else { scope.decls.writeByte(0x01); // instancedecl: type scope.decls.writeBuffer(body); scope.declCount += 1; } let index = scope.typeCount; scope.typeCount += 1; return index; } #encodeTypeDef(scope: Scope, td: TypeDef): void { let name = td.name.name; scope.pending.delete(name); if (td.tag == TypeDefTag.Resource) { // A resource has no structure to declare — the export itself is // the declaration, and `sub resource` is its bound. scope.decls.writeByte(0x04); writeExternName(scope.decls, name); scope.decls.writeByte(0x03); scope.decls.writeByte(0x01); // typebound: sub resource scope.declCount += 1; let resourceIndex = scope.typeCount; scope.typeCount += 1; scope.named[name] = resourceIndex; scope.resourceIndices[resourceIndex] = true; for (let rf in td.resourceFuncs as GrowableArray) { this.#encodeResourceFunc(scope, rf, name, resourceIndex); } return; } var code = 0; if (td.tag == TypeDefTag.Record || td.tag == TypeDefTag.Variant || td.tag == TypeDefTag.Enum || td.tag == TypeDefTag.Flags) { code = this.#encodeTypeBody(scope, td); } else { // `type name = t`: encode the target, and export an index for it. // A primitive target still needs a declared type to bound the // export to — `eq` takes an index, not an opcode. A named target // is looked up raw so that `type b = bucket` aliases the resource // itself rather than an `own` of it. let target = td.aliasType as Type; var isResource = false; if (target.tag == TypeTag.Name) { code = this.#namedIndex(scope, (target.name as Id).name); isResource = scope.resourceIndices.has(code); } else { let encoded = this.#encodeType(scope, target); if (encoded < 0) { let body = new ByteBuffer(); body.writeByte(0 - encoded); code = this.#declareType(scope, body); } else { code = encoded; } } let exportedAlias = this.#exportType(scope, name, code); scope.named[name] = exportedAlias; if (isResource) { scope.resourceIndices[exportedAlias] = true; } return; } scope.named[name] = this.#exportType(scope, name, code); } /** The declared index of a record, variant, enum or flags body in * `scope`, its parts encoded first. */ #encodeTypeBody(scope: Scope, td: TypeDef): i32 { var code = 0; if (td.tag == TypeDefTag.Record) { let fields = td.fields as GrowableArray; let fieldCodes = new GrowableArray(); for (let f in fields) { fieldCodes.push(this.#encodeType(scope, f.type)); } let body = new ByteBuffer(); body.writeByte(0x72); body.writeULEB128(fields.length); for (var i = 0; i < fields.length; i += 1) { writeName(body, fields[i].name.name); writeValType(body, fieldCodes[i]); } code = this.#declareType(scope, body); } else if (td.tag == TypeDefTag.Variant) { let cases = td.cases as GrowableArray; let caseCodes = new GrowableArray(); for (let c in cases) { let payload = c.type; caseCodes.push( if (payload == null) 0 else this.#encodeType(scope, payload)); } let body = new ByteBuffer(); body.writeByte(0x71); body.writeULEB128(cases.length); for (var i = 0; i < cases.length; i += 1) { writeName(body, cases[i].name.name); if (cases[i].type == null) { body.writeByte(0x00); // no payload } else { body.writeByte(0x01); writeValType(body, caseCodes[i]); } body.writeByte(0x00); // refines: none (the format still asks) } code = this.#declareType(scope, body); } else if (td.tag == TypeDefTag.Enum) { let cases = td.enumCases as GrowableArray; let body = new ByteBuffer(); body.writeByte(0x6d); body.writeULEB128(cases.length); for (let c in cases) { writeName(body, c.name.name); } code = this.#declareType(scope, body); } else { let flags = td.flags as GrowableArray; let body = new ByteBuffer(); body.writeByte(0x6e); body.writeULEB128(flags.length); for (let f in flags) { writeName(body, f.name.name); } code = this.#declareType(scope, body); } return code; } /** * A type expression, as a value-type code. Named constructors were * handled by `#encodeTypeDef` — this resolves references to them and * builds the anonymous ones, one declaration per distinct shape. */ #encodeType(scope: Scope, t: Type): i32 { let prim = primOpcodeOf(t.tag); if (prim >= 0) { return primCode(prim); } if (t.tag == TypeTag.Name) { let index = this.#namedIndex(scope, (t.name as Id).name); if (scope.resourceIndices.has(index)) { // A resource name in value position is a handle: `-> bucket` // returns `own`. The explicit `own`/`borrow` arms below // are the ones that look the name up raw. return this.#handleType(scope, 0x69, index); } return index; } if (t.tag == TypeTag.Future || t.tag == TypeTag.Stream) { // `stream`/`future` — a handle to one end. The payload is // optional in the grammar (`0x66 t?`), and the absent form is a // real type (`future` alone signals completion), encoded as a // present/absent byte like a defaulted case payload. let opcode = if (t.tag == TypeTag.Stream) 0x66 else 0x65; let innerType = t.inner; var inner = -1; var key = i32ToString(opcode) + "("; if (innerType != null) { inner = this.#encodeType(scope, innerType); key = key + i32ToString(inner); } key = key + ")"; if (let (true, existing) = scope.anon.get(key)) { return existing; } let body = new ByteBuffer(); body.writeByte(opcode); if (innerType != null) { body.writeByte(0x01); writeValType(body, inner); } else { body.writeByte(0x00); } let index = this.#declareType(scope, body); scope.anon[key] = index; return index; } if (t.tag == TypeTag.Map) { throw new EncodeError("map types are not encodable yet"); } if (t.tag == TypeTag.ErrorContext) { throw new EncodeError("error-context types are not encodable yet"); } if (t.tag == TypeTag.List && t.fixedLength >= 0) { throw new EncodeError("fixed-length lists are not encodable yet"); } if (t.tag == TypeTag.List || t.tag == TypeTag.Option) { let inner = this.#encodeType(scope, t.inner as Type); let opcode = if (t.tag == TypeTag.List) 0x70 else 0x6b; let key = `${i32ToString(opcode)}(${i32ToString(inner)})`; if (let (true, existing) = scope.anon.get(key)) { return existing; } let body = new ByteBuffer(); body.writeByte(opcode); writeValType(body, inner); let index = this.#declareType(scope, body); scope.anon[key] = index; return index; } if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) { let inner = t.inner as Type; if (inner.tag != TypeTag.Name) { throw new EncodeError("own/borrow take a resource by name"); } let resource = this.#namedIndex(scope, (inner.name as Id).name); let opcode = if (t.tag == TypeTag.Own) 0x69 else 0x68; return this.#handleType(scope, opcode, resource); } if (t.tag == TypeTag.Tuple) { let members = t.types as GrowableArray; let codes = new GrowableArray(); var key = "tuple("; for (let m in members) { let c = this.#encodeType(scope, m); codes.push(c); key = `${key}${i32ToString(c)},`; } key = key + ")"; if (let (true, existing) = scope.anon.get(key)) { return existing; } let body = new ByteBuffer(); body.writeByte(0x6f); body.writeULEB128(codes.length); for (let c in codes) { writeValType(body, c); } let index = this.#declareType(scope, body); scope.anon[key] = index; return index; } if (t.tag == TypeTag.Result) { let ok = t.okType; let err = t.errType; let okCode = if (ok == null) 0 else this.#encodeType(scope, ok); let errCode = if (err == null) 0 else this.#encodeType(scope, err); let key = "result(" + (if (ok == null) "" else i32ToString(okCode)) + "," + (if (err == null) "" else i32ToString(errCode)) + ")"; if (let (true, existing) = scope.anon.get(key)) { return existing; } let body = new ByteBuffer(); body.writeByte(0x6a); if (ok == null) { body.writeByte(0x00); } else { body.writeByte(0x01); writeValType(body, okCode); } if (err == null) { body.writeByte(0x00); } else { body.writeByte(0x01); writeValType(body, errCode); } let index = this.#declareType(scope, body); scope.anon[key] = index; return index; } throw new EncodeError("unhandled type tag in the WIT encoder"); } /** * A function type declaration; the index it gets. `selfBorrow` is a * borrow handle's index for a method and -1 otherwise. */ #encodeFuncType( scope: Scope, func: Func, selfBorrow: i32, isAsync: boolean ): i32 { let paramCodes = new GrowableArray(); for (let p in func.params) { paramCodes.push(this.#encodeType(scope, p.type)); } let result = func.result; let resultCode = if (result == null) 0 else this.#encodeType(scope, result); let body = new ByteBuffer(); body.writeByte(if (isAsync) 0x43 else 0x40); body.writeULEB128( func.params.length + (if (selfBorrow >= 0) 1 else 0)); if (selfBorrow >= 0) { writeName(body, "self"); writeValType(body, selfBorrow); } for (var i = 0; i < func.params.length; i += 1) { writeName(body, func.params[i].name.name); writeValType(body, paramCodes[i]); } if (result == null) { body.writeByte(0x01); // the named-results arm of resultlist, body.writeByte(0x00); // holding none } else { body.writeByte(0x00); // one unnamed result writeValType(body, resultCode); } return this.#declareType(scope, body); } #exportFunc(scope: Scope, name: String, typeIndex: i32): void { scope.decls.writeByte(0x04); writeExternName(scope.decls, name); scope.decls.writeByte(0x01); // externdesc: func scope.decls.writeULEB128(typeIndex); scope.declCount += 1; } #encodeInterfaceFunc( scope: Scope, nf: NamedFunc, exportPrefix: String, selfBorrow: i32 ): void { let typeIndex = this.#encodeFuncType(scope, nf.func, selfBorrow, nf.func.isAsync); this.#exportFunc(scope, exportPrefix + nf.name.name, typeIndex); } #encodeResourceFunc( scope: Scope, rf: ResourceFunc, resourceName: String, resourceIndex: i32 ): void { if (rf.tag == ResourceFuncTag.Constructor) { // A constructor's declared result is nothing; its real one is // `own` of the resource it builds. let ownIndex = this.#handleType(scope, 0x69, resourceIndex); let func = rf.func.func; let paramCodes = new GrowableArray(); for (let p in func.params) { paramCodes.push(this.#encodeType(scope, p.type)); } let body = new ByteBuffer(); body.writeByte(0x40); body.writeULEB128(func.params.length); for (var i = 0; i < func.params.length; i += 1) { writeName(body, func.params[i].name.name); writeValType(body, paramCodes[i]); } body.writeByte(0x00); writeValType(body, ownIndex); let typeIndex = this.#declareType(scope, body); this.#exportFunc(scope, "[constructor]" + resourceName, typeIndex); } else if (rf.tag == ResourceFuncTag.Method) { let borrowIndex = this.#handleType(scope, 0x68, resourceIndex); this.#encodeInterfaceFunc(scope, rf.func, `[method]${resourceName}.`, borrowIndex); } else { this.#encodeInterfaceFunc(scope, rf.func, `[static]${resourceName}.`, -1); } } /** The index `name` exports here, with no handle wrapping. */ #namedIndex(scope: Scope, name: String): i32 { if (let (true, index) = scope.named.get(name)) { return index; } let nestedNamed = scope.nestedNamed; if (nestedNamed != null) { return nestedNamed(name); } if (let (true, td) = scope.pending.get(name)) { // Declared later in the interface: encode it now, first use // being the encoding order. this.#encodeTypeDef(scope, td); return scope.named[name]; } let source = scope.aliasSource; if (source != null) { let reg = source; if (!this.#declaresType(reg, name)) { throw new EncodeError("'" + reg.qualifiedName + "' declares no type '" + name + "'"); } // An imported interface's types alias out of its instance. An // exported interface has no instance to alias from; a type it // `use`s comes from its source instead, under the source's own // name for it: an alias out of an imported source's instance, or // an exported source's own component-level declaration. var index = -1; if (this.#instanceIndex.has(reg.qualifiedName)) { index = this.#aliasTypeExport(reg.qualifiedName, name); } else { let hop = this.#useSourceOf(reg, name); if (hop == null) { // The exported interface's own declaration: encoded at // component level, and exported from its instance. index = this.#encodeExportedOwnType(reg, name); } else { index = this.#usedTypeIndex(hop); } } // The alias appended a component-level type; a component-level // scope counts the same index space, so it catches up. scope.typeCount = this.#result.typeCount; scope.named[name] = index; if (this.#isResource(reg, name)) { scope.resourceIndices[index] = true; } return index; } if (scope.atComponentLevel) { throw new EncodeError("a world-level function names type '" + name + "', which needs world-level `use` encoding"); } throw new EncodeError(`type '${name}' is not declared in this interface`); } /** * The component-level type index of `name`, a type the exported * interface `reg` declares itself, encoding it on first use — its * body as a component-level type, its named parts resolved against * the interface the same way (a record's enum field, a variant's * record payload) — and recording it for the instance to export. A * resource is a component-level resource type whose representation * is an `i32` — the index into the entry wrapper's table of the * program's instances — which the canon `resource.new` and * `resource.rep` builtins mint handles for and read back. Its * destructor is a shim trampoline (`DtorSlot`): the program's own * destructor lives in an instance that cannot exist before this type * does, since the core module imports `resource.new` for it. */ #encodeExportedOwnType(reg: RegisteredInterface, name: String): i32 { let key = `${reg.qualifiedName}#own:${name}`; if (let (true, existing) = this.#aliasedTypes.get(key)) { return existing; } var found: TypeDef | null = null; for (let item in reg.items) { if (item.tag != InterfaceItemTag.TypeDef) { continue; } let td = item.typeDef as TypeDef; if (td.name.name == name) { found = td; } } if (found == null) { throw new EncodeError(`'${reg.qualifiedName}' declares no type '${name}'`); } let td = found; let scope = new Scope(); scope.atComponentLevel = true; scope.typeCount = this.#result.typeCount; scope.aliasSource = reg; var index = -1; if (td.tag == TypeDefTag.Resource) { // The destructor is core function `slot`: the emitter's shim // trampoline for this resource (see `DtorSlot`). let slot = this.#result.dtorSlots.length; this.#result.dtorSlots.push(new DtorSlot(reg.qualifiedName, name)); let body = new ByteBuffer(); body.writeByte(0x3f); // resource body.writeByte(0x7f); // rep: i32 body.writeByte(0x01); // a destructor: body.writeULEB128(slot); index = this.#declareType(scope, body); } else if (td.tag == TypeDefTag.Alias) { let target = td.aliasType as Type; if (target.tag == TypeTag.Name) { index = this.#namedIndex(scope, (target.name as Id).name); } else { let encoded = this.#encodeType(scope, target); if (encoded < 0) { // A primitive alias still needs a declared type for the // instance to export under the name. let body = new ByteBuffer(); body.writeByte(0 - encoded); index = this.#declareType(scope, body); } else { index = encoded; } } } else { index = this.#encodeTypeBody(scope, td); } this.#aliasedTypes[key] = index; let list = if (let (true, l) = this.#result.exportedTypes.get( reg.qualifiedName)) l else new GrowableArray(); list.push(new ExportedTypeIndex(name, index)); this.#result.exportedTypes[reg.qualifiedName] = list; return index; } /** Whether `reg` declares `name` — as a type definition or a `use`d * name — so an alias export of it can be valid. */ #declaresType(reg: RegisteredInterface, name: String): boolean { for (let item in reg.items) { if (item.tag == InterfaceItemTag.TypeDef) { if ((item.typeDef as TypeDef).name.name == name) { return true; } } else if (item.tag == InterfaceItemTag.Use) { for (let n in (item.use as Use).names) { let asName = n.asName; let localName = asName?.name ?? n.name.name; if (localName == name) { return true; } } } } return false; } /** An `own`/`borrow` of `resourceIndex`, deduplicated like any anon. */ #handleType(scope: Scope, opcode: i32, resourceIndex: i32): i32 { let key = `${i32ToString(opcode)}(${i32ToString(resourceIndex)})`; if (let (true, existing) = scope.anon.get(key)) { return existing; } let body = new ByteBuffer(); body.writeByte(opcode); body.writeULEB128(resourceIndex); // an index position: unsigned let index = this.#declareType(scope, body); scope.anon[key] = index; return index; } } /** `ns:pkg/name@version`, or the bare name when there is no package. */ export function qualifiedInterfaceName( pkg: PackageName | null, interfaceName: String ): String { if (pkg == null) { return interfaceName; } let p = pkg; var name = `${p.namespace.name}:${p.name.name}/${interfaceName}`; let version = p.version; if (version != null) { name = `${name}@${version}`; } return name; } function externName(kind: ExternKind): String { if (kind.tag == ExternKindTag.Path) { return (kind.path as UsePath).getName().name; } return (kind.name as Id).name; } // ============================================================================ // Canonical flattening metadata // ============================================================================ /** * How a WIT type crosses the core boundary: how many flat core values * it occupies, and whether it needs linear memory to cross at all. * * This is the *counting* half of the canonical ABI's `flatten` — enough * to decide two things a `canon lower` depends on: whether the options * must name a memory and a realloc (a `string` or `list` anywhere in * the signature), and whether the result is returned indirectly * (flattened results exceeding one mean the caller passes a return * area's address as a trailing `i32` parameter, and so does a * parameter list flattening past sixteen). */ export final class WitFlatMeta { // No field initializers: a defaulted `this.x` parameter on a field // that also has an initializer fails ZIR lowering ("auto-box to // any") — see elematic/zena#102. var flatCount: i32; var needsMemory: boolean; new(this.flatCount = 0, this.needsMemory = false); } /** One function's flattening, plus whether the lookup found it at all. */ export final class WitFuncMeta { var paramFlatCount = 0; var resultFlatCount = 0; /** Whether lowering this function needs the canonical memory options. */ var needsMemory = false; /** Whether the WIT declares the function `async`. */ var isAsync = false; } /** One interface, as the flattening walker sees the document. */ final class FlatIface { name: String; items: Array; new(this.name, this.items); } function flatMetaOfType( interfaces: Array, owner: FlatIface, t: Type ): WitFlatMeta { let prim = primOpcodeOf(t.tag); if (prim >= 0) { if (t.tag == TypeTag.String) { return new WitFlatMeta(2, true); } return new WitFlatMeta(1, false); } if (t.tag == TypeTag.List) { return new WitFlatMeta(2, true); } if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) { return new WitFlatMeta(1, false); } if (t.tag == TypeTag.Tuple) { let meta = new WitFlatMeta(); for (let m in t.types as GrowableArray) { let inner = flatMetaOfType(interfaces, owner, m); meta.flatCount += inner.flatCount; if (inner.needsMemory) { meta.needsMemory = true; } } return meta; } if (t.tag == TypeTag.Option) { let inner = flatMetaOfType(interfaces, owner, t.inner as Type); return new WitFlatMeta(1 + inner.flatCount, inner.needsMemory); } if (t.tag == TypeTag.Result) { // A variant of two cases: the discriminant, then the larger payload // (the join's *count* is the maximum; the exact core types do not // matter for what this decides). var payload = 0; var mem = false; let ok = t.okType; if (ok != null) { let m = flatMetaOfType(interfaces, owner, ok); payload = m.flatCount; if (m.needsMemory) { mem = true; } } let err = t.errType; if (err != null) { let m = flatMetaOfType(interfaces, owner, err); if (m.flatCount > payload) { payload = m.flatCount; } if (m.needsMemory) { mem = true; } } return new WitFlatMeta(1 + payload, mem); } if (t.tag == TypeTag.Name) { return flatMetaOfName(interfaces, owner, (t.name as Id).name); } // stream/future: a handle end, one core i32, no memory of its own — // the real answer, not a fallback. map/error-context: the encoder // still refuses those before metadata is asked for; one word keeps a // caller that asks anyway from being lied to about memory. return new WitFlatMeta(1, false); } function flatMetaOfName( interfaces: Array, owner: FlatIface, name: String ): WitFlatMeta { for (let item in owner.items) { if (item.tag == InterfaceItemTag.TypeDef) { let td = item.typeDef as TypeDef; if (td.name.name != name) { continue; } if (td.tag == TypeDefTag.Resource) { // A resource name in value position is a handle. return new WitFlatMeta(1, false); } if (td.tag == TypeDefTag.Enum || td.tag == TypeDefTag.Flags) { return new WitFlatMeta(1, false); } if (td.tag == TypeDefTag.Record) { let meta = new WitFlatMeta(); for (let f in td.fields as GrowableArray) { let inner = flatMetaOfType(interfaces, owner, f.type); meta.flatCount += inner.flatCount; if (inner.needsMemory) { meta.needsMemory = true; } } return meta; } if (td.tag == TypeDefTag.Variant) { var payload = 0; var mem = false; for (let c in td.cases as GrowableArray) { let payloadType = c.type; if (payloadType != null) { let m = flatMetaOfType(interfaces, owner, payloadType); if (m.flatCount > payload) { payload = m.flatCount; } if (m.needsMemory) { mem = true; } } } return new WitFlatMeta(1 + payload, mem); } return flatMetaOfType(interfaces, owner, td.aliasType as Type); } else if (item.tag == InterfaceItemTag.Use) { let use = item.use as Use; for (let n in use.names) { let asName = n.asName; let localName = asName?.name ?? n.name.name; if (localName != name) { continue; } // The wanted interface, package-qualified. A bare `use foo` // means the OWNER's package's `foo` — matching by trailing // name alone resolved wasi:http/client's `use types` to // wasi:cli/types, whichever registered first — and a // package-path use spells its package outright. let sourceName = use.from.getName().name; let from = use.from; var wantPackage = ""; if (from is PackageUsePath) { let p = from.packageId as PackageName; wantPackage = `${p.namespace.name}:${p.name.name}`; } else { var slashAt = -1; for (var i = 0; i < owner.name.length; i += 1) { if (owner.name.getByteAt(i) == 47) { slashAt = i; } // '/' } if (slashAt > 0) { wantPackage = owner.name.sliceBytes(0, slashAt); } } let want = `${wantPackage}/${sourceName}`; for (let iface in interfaces) { if (iface.name == want || iface.name.startsWith(want + "@")) { return flatMetaOfName(interfaces, iface, n.name.name); } } } } } var known = ""; for (let iface in interfaces) { known = `${known} ${iface.name}`; } throw new EncodeError("flattening cannot resolve type '" + name + "' (interfaces:" + known + ")"); } function funcMetaOf( interfaces: Array, owner: FlatIface, func: Func, selfParams: i32 ) { let meta = new WitFuncMeta(); meta.isAsync = func.isAsync; meta.paramFlatCount = selfParams; for (let p in func.params) { let m = flatMetaOfType(interfaces, owner, p.type); meta.paramFlatCount += m.flatCount; if (m.needsMemory) { meta.needsMemory = true; } } let result = func.result; if (result != null) { let m = flatMetaOfType(interfaces, owner, result); meta.resultFlatCount = m.flatCount; if (m.needsMemory) { meta.needsMemory = true; } } if (meta.paramFlatCount > 16 || meta.resultFlatCount > 1) { // Spilled parameters land in memory; an indirect result needs a // return area. Either way the options must say where. meta.needsMemory = true; } if (meta.isAsync && (meta.resultFlatCount > 0 || meta.paramFlatCount > 4)) { // The async lowering spills any result through a return area, and // parameters past four core values through one pointer. meta.needsMemory = true; } return meta; } /** * The flattening of one function of one interface, by the names a core * module imports them under — the qualified interface, and the field * (`get-stdout`, `[method]output-stream.blocking-write-and-flush`). * Null when the interface or the function is not in the document, * which callers treat as its own loud error. */ /** Every interface of the document, main package and nested. */ function registeredFlatIfaces(ast: Ast) { let interfaces = new GrowableArray(); let register = (pkg: PackageName | null, items: Array) => { for (let item in items) { if (item.tag == AstItemTag.Interface) { let def = item.interfaceDef as InterfaceDef; interfaces.push(new FlatIface( qualifiedInterfaceName(pkg, def.name.name), def.items)); } } }; register(ast.packageName, ast.items); for (let nested in ast.nestedPackages) { register(nested.name, nested.items); } return interfaces; } /** * An export's flattening: the lift moves parameters and result * through memory when a type of theirs does, or when either spills * past sixteen core values. An async import's result spills through a * return area; an async export's goes through `task.return`, whose * flat parameters carry it, so the import rule does not apply. */ function exportMetaOf( interfaces: Array, owner: FlatIface, func: Func, selfParams: i32 = 0 ) { let meta = new WitFuncMeta(); meta.isAsync = func.isAsync; meta.paramFlatCount = selfParams; for (let p in func.params) { let m = flatMetaOfType(interfaces, owner, p.type); meta.paramFlatCount += m.flatCount; if (m.needsMemory) { meta.needsMemory = true; } } let result = func.result; if (result != null) { let m = flatMetaOfType(interfaces, owner, result); meta.resultFlatCount = m.flatCount; if (m.needsMemory) { meta.needsMemory = true; } } if (meta.paramFlatCount > 16 || meta.resultFlatCount > 16) { meta.needsMemory = true; } return meta; } /** * The flattening of the world's function export `exportName`, or null * when the world exports no function by that name. A world-level * function's types are structural, so they resolve against no * interface. * * The memory need is an export's, not an import's: the lift moves * parameters and result through memory when a type of theirs does, or * when either spills past sixteen core values. An async import's * result spills through a return area; an async export's goes through * `task.return`, whose flat parameters carry it. */ export function worldFuncFlatMeta( ast: Ast, worldName: String, exportName: String ): WitFuncMeta | null { let interfaces = new GrowableArray(); for (let item in ast.items) { if (item.tag == AstItemTag.Interface) { let def = item.interfaceDef as InterfaceDef; interfaces.push(new FlatIface( qualifiedInterfaceName(ast.packageName, def.name.name), def.items)); } } let owner = new FlatIface("", new GrowableArray()); for (let item in ast.items) { if (item.tag != AstItemTag.World) { continue; } let def = item.worldDef as WorldDef; if (def.name.name != worldName) { continue; } for (let wi in expandedWorldItems(ast, def)) { if (wi.tag != WorldItemTag.Export) { continue; } let kind = (wi.exportItem as Export).kind; if (kind.tag != ExternKindTag.Func) { continue; } if ((kind.name as Id).name != exportName) { continue; } return exportMetaOf(interfaces, owner, kind.funcDef as Func); } } return null; } /** * The flattening of `funcName` in the exported interface * `interfaceName`, or null when no such function exists. The memory * need is an export's, as `worldFuncFlatMeta` computes it. */ export function interfaceExportFlatMeta( ast: Ast, interfaceName: String, funcName: String ): WitFuncMeta | null { let interfaces = registeredFlatIfaces(ast); for (let iface in interfaces) { if (iface.name != interfaceName) { continue; } for (let item in iface.items) { if (item.tag != InterfaceItemTag.Func) { continue; } let nf = item.func as NamedFunc; if (nf.name.name == funcName) { return exportMetaOf(interfaces, iface, nf.func); } } // A resource's function under its mangled export name: a method's // `self` is one core value, and a constructor returns the handle. let found = resourceFuncNamed(iface.items, funcName); if (found != null) { let rf = found.rf; let selfParams = if (rf.tag == ResourceFuncTag.Method) 1 else 0; let meta = exportMetaOf(interfaces, iface, rf.func.func, selfParams); if (rf.tag == ResourceFuncTag.Constructor) { meta.resultFlatCount = 1; // the own handle } return meta; } } return null; } /** A resource's function found by its mangled export name. */ final class NamedResourceFunc { resourceName: String; rf: ResourceFunc; new(this.resourceName, this.rf); } /** * The resource function `items` exports as `fieldName` — a * `[constructor]r`, `[method]r.f` or `[static]r.f` — or null. */ function resourceFuncNamed(items: Array, fieldName: String): NamedResourceFunc | null { for (let item in items) { if (item.tag != InterfaceItemTag.TypeDef) { continue; } let td = item.typeDef as TypeDef; if (td.tag != TypeDefTag.Resource) { continue; } 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}` }; if (exported == fieldName) { return new NamedResourceFunc(resourceName, rf); } } } return null; } export function funcFlatMeta( ast: Ast, interfaceName: String, fieldName: String ): WitFuncMeta | null { let interfaces = new GrowableArray(); let register = (pkg: PackageName | null, items: Array) => { for (let item in items) { if (item.tag == AstItemTag.Interface) { let def = item.interfaceDef as InterfaceDef; interfaces.push(new FlatIface( qualifiedInterfaceName(pkg, def.name.name), def.items)); } } }; register(ast.packageName, ast.items); for (let nested in ast.nestedPackages) { register(nested.name, nested.items); } for (let iface in interfaces) { if (iface.name != interfaceName) { continue; } for (let item in iface.items) { if (item.tag == InterfaceItemTag.Func) { let nf = item.func as NamedFunc; if (nf.name.name == fieldName) { return funcMetaOf(interfaces, iface, nf.func, 0); } } else if (item.tag == InterfaceItemTag.TypeDef) { let td = item.typeDef as TypeDef; if (td.tag != TypeDefTag.Resource) { continue; } let resourceName = td.name.name; for (let rf in td.resourceFuncs as GrowableArray) { var exported = ""; var selfParams = 0; if (rf.tag == ResourceFuncTag.Constructor) { exported = "[constructor]" + resourceName; } else if (rf.tag == ResourceFuncTag.Method) { exported = `[method]${resourceName}.${rf.func.name.name}`; selfParams = 1; } else { exported = `[static]${resourceName}.${rf.func.name.name}`; } if (exported != fieldName) { continue; } let meta = funcMetaOf(interfaces, iface, rf.func.func, selfParams); if (rf.tag == ResourceFuncTag.Constructor) { meta.resultFlatCount = 1; // the own handle } return meta; } } } return null; } return null; } /** * The items of `world`, a world of the document's main package, with * every `include` expanded in place: the included world's imports and * exports, its own includes expanded too, in order. An include names a * world of the including world's package by a bare name, or of another * package by path. An item that an included world names an interface by * a bare name means that world's package's interface, so its path comes * back qualified with the package. An import or export that two * includes both bring is kept once, as WIT merges them. An item gated * `@unstable(feature = ...)` is left out, as WIT tooling leaves it out * while no feature is enabled: `wasi:clocks/imports` gates `timezone`, * which hosts do not provide. */ export function expandedWorldItems(ast: Ast, world: WorldDef): GrowableArray { let out = new GrowableArray(); appendWorldItems(ast, world, ast.packageName, false, out, new GrowableArray(), 0); return out; } function appendWorldItems(ast: Ast, world: WorldDef, pkg: PackageName | null, included: boolean, out: GrowableArray, seen: GrowableArray, depth: i32): void { if (depth > 32) { throw new EncodeError(`world '${world.name.name}' includes itself`); } for (let item in world.items) { if (item.tag == WorldItemTag.Include) { let inc = item.include as Include; if (isUnstable(inc.docs)) { continue; } if (inc.names.length > 0) { throw new EncodeError("an `include` that renames with `with` is not encodable yet"); } let from = inc.from; if (from.tag == UsePathTag.Id) { let name = (from.id as Id).name; appendWorldItems(ast, findPackageWorld(ast, pkg, name), pkg, true, out, seen, depth + 1); } else { let fromPkg = from.packageId as PackageName; appendWorldItems(ast, findPackageWorld(ast, fromPkg, (from.name as Id).name), fromPkg, true, out, seen, depth + 1); } continue; } if (item.tag != WorldItemTag.Import && item.tag != WorldItemTag.Export) { out.push(item); continue; } let isImport = item.tag == WorldItemTag.Import; let docs = if (isImport) (item.importItem as Import).docs else (item.exportItem as Export).docs; if (isUnstable(docs)) { continue; } let kind = if (isImport) (item.importItem as Import).kind else (item.exportItem as Export).kind; let key = `${if (isImport) 'import' else 'export'} ${externKey(kind, pkg)}`; var known = false; for (let k in seen) { if (k == key) { known = true; } } if (known) { continue; } seen.push(key); let path = kind.path; if (!included || kind.tag != ExternKindTag.Path || path == null || path.tag != UsePathTag.Id || pkg == null) { out.push(item); continue; } let qualified = ExternKind.fromPath(UsePath.fromPackage(pkg, path.id as Id)); out.push(if (isImport) { WorldItem.fromImport(new Import((item.importItem as Import).docs, qualified)) } else { WorldItem.fromExport(new Export((item.exportItem as Export).docs, qualified)) }); } } /** Whether an item is gated behind a feature with `@unstable`. */ function isUnstable(docs: Docs): boolean { let attributes = docs.attributes; if (attributes == null) { return false; } for (let attribute in attributes) { if (attribute.tag == AttributeTag.Unstable) { return true; } } return false; } /** What identifies an import or export: its qualified interface, or its name. */ function externKey(kind: ExternKind, pkg: PackageName | null): String { let path = kind.path; if (kind.tag == ExternKindTag.Path && path != null) { return if (path.tag == UsePathTag.Id) { qualifiedInterfaceName(pkg, (path.id as Id).name) } else { qualifiedInterfaceName(path.packageId, (path.name as Id).name) }; } return (kind.name as Id).name; } /** The world named `name` in package `pkg`: the main one, or a nested one. */ function findPackageWorld(ast: Ast, pkg: PackageName | null, name: String): WorldDef { let wanted = qualifiedInterfaceName(pkg, name); if (qualifiedInterfaceName(ast.packageName, name) == wanted) { for (let item in ast.items) { if (item.tag == AstItemTag.World && (item.worldDef as WorldDef).name.name == name) { return item.worldDef as WorldDef; } } } for (let nested in ast.nestedPackages) { if (qualifiedInterfaceName(nested.name, name) != wanted) { continue; } for (let item in nested.items) { if (item.tag == AstItemTag.World && (item.worldDef as WorldDef).name.name == name) { return item.worldDef as WorldDef; } } } throw new EncodeError(`no world '${wanted}' to include in this document`); } /** The names of the worlds the document's main package defines. */ export function worldNames(ast: Ast): Array { let names = new GrowableArray(); for (let item in ast.items) { if (item.tag == AstItemTag.World) { names.push((item.worldDef as WorldDef).name.name); } } return names; } /** A world's encoding, plus the bytes as a complete component. */ export final class TypesOnlyComponent { bytes: ByteBuffer; encoded: EncodedWorld; new(this.bytes, this.encoded); } /** * The pieces as a complete, importing-only component: the head sections * with nothing behind them. Valid on its own — which is the point, as * `wasm-tools component wit` will read the world back out of it. */ export function encodeTypesOnlyComponent( ast: Ast, worldName: String ): TypesOnlyComponent { let encoder = new ComponentTypeEncoder(ast); let encoded = encoder.encodeWorld(worldName); let out = new ByteBuffer(); out.writeU32(0x6D736100); // \0asm out.writeU32(0x0001000D); // version 0x0d, layer 1: a component for (let piece in encoded.pieces) { out.writeByte(piece.id); out.writeULEB128(piece.payload.length); out.writeBuffer(piece.payload); } return new TypesOnlyComponent(out, encoded); }