Skip to content

Commit

Permalink
Document proposed WIT to enable component Worlds
Browse files Browse the repository at this point in the history
This PR sketches out the initial format for WebAssembly profiles,
i.e. world files.

Signed-off-by: Brian H <brian.hardock@fermyon.com>
  • Loading branch information
fibonacci1729 committed Sep 26, 2022
1 parent ca2851c commit 8f3228d
Showing 1 changed file with 77 additions and 0 deletions.
77 changes: 77 additions & 0 deletions design/mvp/WORLD.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Component Worlds (i.e. `world` syntax in `WIT`)
TODO -- Some background and purpose

## Syntax
The following sections reflect the syntactic additions to `WIT` to enable component Worlds. Lexical structure is identical to that of [WIT.md](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) with the addition of the following keywords:
```
interface world import export
```

Additionally, a new `WIT` token is introduced to allow parsing [URL](https://url.spec.whatwg.org/):
```
token ::= whitespace
| ...
| quoted-string
```

### Item: `interface`
TODO

### Item: `world`

A `world` describes a set of imports and exports. From the perspective of a component targeting a `world`, the imports declared in the `world` describe the maximum set of imports that the component may choose to import, whereas the exports declared describe the minimum set of imports that the component must export.

Conversely, from the perspective of a host implementing the same `world`, the imports declared by the `world` describe the minimum set of functions that must be implemented by the host and supplied as imports to components running on that host, whereas the exports declared describe the maximum set of functions that the host may call in response to host events. Thus, there are inherently two opposite perspectives on each `world`: the host perspective and the guest perspective.

Because import and export in the syntax shown below go in the same direction as they are defined in a guest component, we can say that a `world` is written from the guest perspective.

Because the Component Model allows one component to instantiate and link another component, wasm components can technically take either the host or guest perspective for a given `world` (although it will be far more common for components to take the guest perspective). Native host runtimes traditionally only take the host perspective, but in theory a native runtime could natively implement a component that is imported and instantiated by a wasm component, with the native runtime thereby taking the guest perspective.

By way of metaphor, a `world` is like a function type:
* `world` imports and exports are like parameters and results
* `world` hosts are like the callers of a given function type
* `world` guests are like functions that have a given function type
* The rules for when a given guest is compatible with a given host are like traditional function subtyping

From a component-model POV:
* a `world` is syntax for a [componenttype](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions)
* an `interface` is syntax for an [instancetype](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions)

Thus, given any component `.wasm`, one should be able to automatically derive a `WIT` file containing a `world` that is the syntax for that `.wasm`'s component type.

Conceretely, the structure of a `World` file is:

```
world ::= 'world' id? '{' (import | export)* '}'
```

TODO: Example

#### Item: `import`

An `import` statement imports an interface/instance.

The structure of an import statment is:

```
import ::= 'import' (id ':')? url
import-kind ::= url | interface
```

TODO: Example

#### Item: `export`

An `export` statement exports interface/instance.

The structure of an export statment is:

```
export ::= 'export' (id ':')? url
export-kind ::= url | interface
```

TODO: Example

## Name resolution
TODO

0 comments on commit 8f3228d

Please sign in to comment.