Skip to content

Commit cf9f3f6

Browse files
catamorphismcatamorphism
committed
Revise and expand on 'Component Model Concepts' section and its subsections
1 parent 571f250 commit cf9f3f6

6 files changed

Lines changed: 275 additions & 38 deletions

File tree

‎component-model/src/design/component-model-concepts.md‎

Lines changed: 88 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,101 @@
11
## Component Model Concepts
22

3-
This section introduces the core concepts and [rationale](./why-component-model.md) of the component model.
4-
5-
* A [WebAssembly Component](./components.md) is the next evolution of core WebAssembly binaries.
6-
* WebAssembly components are *nestable* -- they may contain one or more core modules and/or sub-components composed together.
7-
* The Component Model extends core WebAssembly by introducing higher level types and interface-driven development
8-
* [WebAssembly Interface Types (WIT)][wit] is the [IDL (Interface Definition Language)][wiki-idl] used to formally define functionality for WebAssembly modules.
9-
* With WIT, WebAssembly components gain the ability to conform an language-agnostic and encode that support, so any WebAssembly component binary can be interrogated *and* executed.
10-
* An [Interface](./interfaces.md) describes the types and functions used for a specific, focused bit of functionality.
11-
* A [World](./worlds.md) assembles interfaces to express what features a component offers, and what features it depends on.
12-
* A [Package](./packages.md) is a set of WIT files containing a related set of interfaces and worlds.
13-
* The Component Model introduces the idea of a "platform" to core WebAssembly -- enabling the structured, standardized use of "host" functionality for WebAssembly "guest"s.
14-
* The WebAssembly System Interface (WASI) defines in WIT a family of interfaces for common system-level functions.
15-
* WASI defines common execution environments such as the command line (`wasi:cli`) or a HTTP server (`wasi:http`).
16-
* The Component Model makes core WebAssembly composable -- components that provide functionality and those that use them can be composed together into *one* resulting component
3+
The WebAssembly Component Model extends core WebAssembly
4+
by introducing higher-level types
5+
and interface-driven development.
6+
The Component Model makes core WebAssembly composable:
7+
components that provide functionality and those that use them
8+
can be composed together into *one* resulting component.
9+
10+
This section introduces the core concepts behind the component model.
11+
For the rationale behind the component model, see [the previous section](./why-component-model.md).
12+
13+
### Components
14+
15+
A [WebAssembly Component](./components.md) is a core module extended with higher-level types and interfaces.
16+
WebAssembly components are *nestable*:
17+
they may contain one or more core modules and/or sub-components composed together.
18+
For example, a component implementing a simple calculator might be written
19+
by composing together a component that parses strings to floating-point numbers
20+
with a component that does the main arithmetic.
21+
22+
### WebAssembly Interface Types (WIT)
23+
24+
[WebAssembly Interface Types (WIT)][wit] is the [IDL (Interface Definition Language)][wiki-idl]
25+
used to formally define functionality for WebAssembly modules.
26+
WIT gives WebAssembly components the ability to express type signatures
27+
in a language-agnostic way,
28+
so any component binary can be both checked and executed.
29+
30+
### Interfaces
31+
32+
An [_interface_](./interfaces.md) is a collection of type definitions
33+
and function declarations (function names accompanied by type signatures).
34+
Typically, a single interface describes a specific, focused bit
35+
of functionality.
36+
For example, in [wasi-cli][wasi-cli-stdio],
37+
three separate interfaces are used to implement `stdin`, `stdout`, and `stderr`
38+
(the three input and output streams typically available
39+
in a command-line environment.)
40+
41+
### Worlds
42+
43+
A [_world_](./worlds.md) is a collection of interfaces
44+
that expresses what features a component offers
45+
and what features it depends on.
46+
For example, wasi-cli includes the [`stdio` world][wasi-cli-stdio],
47+
which collects together three separate interfaces
48+
that represent the `stdin`, `stdout`, and `stderr` streams.
49+
Any component implementing the `stdio` world
50+
must implement those three interfaces.
51+
52+
### Packages
53+
54+
A [_package_](./packages.md) is a set of WIT files
55+
containing a related set of interfaces and worlds.
56+
For example, the wasi-cli package includes
57+
the `stdio` world and the `environment` world, among others,
58+
with each defined in its own WIT file.
59+
60+
### Platforms
61+
62+
In the context of WebAssembly, the _host_ is the browser or stand-alone runtime
63+
that runs WebAssembly modules.
64+
The _guest_ is the WebAssembly module that is executed by the host.
65+
(These terms come from virtualization, where a guest is
66+
a software-based virtual machine that runs on physical hardware,
67+
which is the "host")
68+
69+
The Component Model introduces the idea of a _platform_
70+
to core WebAssembly—enabling the structured, standardized use
71+
of host functionality for WebAssembly guests.
72+
73+
## WASI
74+
75+
The WebAssembly System Interface ([WASI][wasi]) defines in WIT
76+
a family of interfaces for common system-level functions.
77+
WASI standardizes the functionality provided by platforms,
78+
so that component writers can rely on functionality
79+
that is guaranteed to be available on any conformant platform.
80+
81+
WASI defines common collections of functionality
82+
such as the command line ([`wasi:cli`][wasi-cli])
83+
or an HTTP server ([`wasi:http`][wasi-http]).
1784

1885
> [!NOTE]
19-
> The Component Model is stewarded by the Bytecode Alliance and designed [in the open][cm-repo].
86+
> The Component Model is stewarded by the [Bytecode Alliance](https://bytecodealliance.org/) and designed [in the open][cm-repo].
2087
>
21-
> See the [`WebAssembly/component-model`][cm-repo] repository for [Goals][goals],[use cases][use-cases], and [high level design choices][design-choices].
88+
> See the [`WebAssembly/component-model`][cm-repo] repository for [goals][goals], [use cases][use-cases], and [high level design choices][design-choices].
2289
2390
[cm-repo]: https://github.com/WebAssembly/component-model
24-
[wiki-idl]: https://en.wikipedia.org/wiki/Web_IDL
91+
[wiki-idl]: https://en.wikipedia.org/wiki/Interface_description_language
2592
[goals]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Goals.md
2693
[use-cases]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/UseCases.md
2794
[design-choices]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Choices.md
2895
[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
96+
[wasi]: https://wasi.dev/
97+
[wasi-cli]: https://github.com/WebAssembly/wasi-cli/
98+
[wasi-cli-stdio]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/stdio.wit
99+
[wasi-http]: https://github.com/WebAssembly/wasi-http
29100

30101
[!NOTE]: #

‎component-model/src/design/components.md‎

Lines changed: 48 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,52 @@
11
# Components
22

3-
* Logically, components are containers for modules - or other components - which express their [interfaces](./interfaces.md) and dependencies via [WIT](./wit.md).
4-
* Conceptually, components are self-describing units of code that interact only through interfaces instead of shared memory.
5-
* Physically, a **component** is a specially-formatted WebAssembly file. Internally, the component could include multiple traditional ("core") WebAssembly modules, and sub-components, composed via their imports and exports.
3+
Conceptually, a component is a self-describing unit of code
4+
that interacts only through interfaces
5+
instead of shared memory.
6+
Let's break down what each of these terms means:
67

7-
The external interface of a component - its imports and exports - corresponds to a [world](./worlds.md). The component, however, internally defines how that world is implemented.
8+
* _Self-describing_: Like a WebAssembly core module,
9+
a component includes import and export declarations
10+
that declare both the names and types of
11+
imported and exported functions.
12+
Compared to core modules, components use a richer type system
13+
to describe these types, so it's easier to understand
14+
what functionality a module provides
15+
and what functionality it relies on.
16+
* _Interacts_: When a component interacts with other components,
17+
that means either that it calls a function defined in a different component,
18+
or that another component calls a function defined in it.
19+
Interfaces specify what kinds of function calls are valid.
20+
* _Shared memory_: In the ["Why the Component Model?"](./why-component-model.md) section,
21+
we showed how WebAssembly core modules can only exchange compound data
22+
through shared memory.
23+
Components use memory in the same way that core modules do,
24+
except that in components, memories are never exported or imported;
25+
they are not shared.
826

9-
> For a more formal definition of what a component is, take a look at the [Component Model specification](https://github.com/WebAssembly/component-model).
27+
Logically, a component is a structure
28+
that may contain core modules and/or other components.
29+
The component encodes the interfaces of these contained
30+
modules and sub-components using [WIT](./wit.md).
31+
32+
The on-disk representation of a component
33+
is a specially-formatted WebAssembly file.
34+
Internally, this file could include representations
35+
of one or many traditional ("core") WebAssembly modules
36+
and sub-components,
37+
`composed` via their imports and exports.
38+
Two modules or components can be composed if the
39+
imports of one are satisfied by the exports of another.
40+
Composition can be repeated arbitarily, composing a
41+
single component out of many interlocking modules and components.
42+
[Interfaces](./interfaces.md) enable checking that
43+
a particular composition makes sense.
44+
45+
Each component is described by a [world](./worlds.md),
46+
which potentially collects together multiple interfaces
47+
to describe all the imports and exports of the component.
48+
The world only describes the types of imported and exported functions;
49+
the component internally defines the code to implement the world.
50+
51+
> For a more formal definition of a component,
52+
> take a look at the [Component Model specification](https://github.com/WebAssembly/component-model).

‎component-model/src/design/interfaces.md‎

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,52 @@
11
# Interfaces
22

3-
An **interface** describes a single-focus, composable contract, through which components can interact with each other and with hosts. Interfaces describe the types and functions used to carry out that interaction. For example:
3+
Interfaces are based on the idea of [design by contract][wp-contract].
4+
In software design, a _contract_ is a specification
5+
of how a unit of code should behave.
46

5-
* A "receive HTTP requests" interface might have only a single "handle request" function, but contain types representing incoming requests, outgoing responses, HTTP methods and headers, and so on.
6-
* A "wall clock" interface might have two functions, one to get the current time and one to get the granularity of the timer. It would also include a type to represent an instant in time.
7+
Conceptually, an _interface_ describes a single-focus,
8+
composable contract
9+
through which components can interact with each other
10+
and with hosts.
11+
* _Single-focus_: By convention, an interface describes
12+
types and functions that are related to each other
13+
and collectively provide a relatively small unit of
14+
functionality,
15+
such as reading from the standard input stream
16+
in a command-line environment.
17+
* _Composable_: Interfaces can be imported and exported.
18+
One component's interfaces can be built
19+
on top of interfaces defined in a different component.
20+
Interfaces enable typechecking so that interfaces can
21+
be composed only when it makes sense to do so.
22+
23+
Concretely, an interface is a collection of type definitions
24+
and function declarations
25+
that are used to carry out interactions between components.
26+
For example:
27+
28+
* A "receive HTTP requests" interface might declare
29+
a single "handle request" function,
30+
along with definitions of types representing
31+
incoming requests, outgoing responses,
32+
HTTP methods and headers, and other data structures.
33+
* A "wall clock" interface might declare two functions,
34+
one to get the current time
35+
and one to get the granularity of the timer (whether time
36+
is measured in seconds, milliseconds, nanoseconds, or another unit).
37+
It would also define a type to represent an instant in time.
38+
39+
As an example of composing interfaces together,
40+
imagine defining a "timer" interface that declares two functions,
41+
one to start a timer and one to query whether the timeout
42+
has been exceeded.
43+
This interface could be defined by importing the "wall clock"
44+
interface.
45+
The result is an interface that exports the timer functionality,
46+
and imports anything imported by the "wall clock" interface.
747

848
Interfaces are defined using [the WIT language](./wit.md).
949

10-
> For a more formal definition of what an interface is, take a look at the [WIT specification](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md).
50+
[wp-contract]: https://en.wikipedia.org/wiki/Design_by_contract
51+
52+
> For a more formal definition of an interface, take a look at the [WIT specification](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md).

‎component-model/src/design/packages.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,18 @@
11
# WIT Packages
22

3-
A **WIT package** is a set of one or more [WIT (Wasm Interface Type)](./wit.md) files containing a related set of interfaces and worlds. WIT is an IDL (interface definition language) for the Component Model. Packages provide a way for worlds and interfaces to refer to each other, and thus for an ecosystem of components to share common definitions.
3+
A **WIT package** is a set of one or more [WIT (Wasm Interface Type)](./wit.md) files
4+
that, taken together, contain a set of interfaces and worlds that are related to each other.
5+
WIT is an IDL (interface definition language) for the component model.
6+
Packages provide a way for worlds and interfaces to refer to each other,
7+
and thus for an ecosystem of components to share common definitions.
48

5-
A WIT package is not a [world](./worlds.md). It's a way of grouping related interfaces and worlds together for ease of discovery and reference, more like a namespace.
9+
A WIT package is like a namespace for grouping related interfaces and worlds together
10+
for ease of discovery and reference.
11+
A package is not a [world](./worlds.md).
612

7-
* The WebAssembly System Interface (WASI) defines a number of packages, including one named `wasi:clocks`. Our HTTP proxy world could import the `wall-clock` interface from the `wasi:clocks` package, rather than having to define a custom clock interface.
13+
* The WebAssembly System Interface (WASI) defines a number of packages,
14+
including one named `wasi:clocks`.
15+
Our HTTP proxy world could import the `wall-clock` interface from the `wasi:clocks` package,
16+
rather than having to define a custom clock interface.
817

918
> For a more formal definition of what a WIT package is, take a look at the [WIT specification](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md).

‎component-model/src/design/why-component-model.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@ Kinds of definitions include:
4646
* And others; see [the Core Specification](https://webassembly.github.io/spec/core/syntax/modules.html)
4747
for the complete list.
4848

49-
Core modules can be run in the browser,
49+
A compiled core module is sometimes called a "WebAssembly binary",
50+
and usually corresponds to a single `.wasm` file.
51+
These modules can be run in the browser,
5052
or via a separate runtime such as [Wasmtime](https://wasmtime.dev/)
5153
or [WAMR](https://github.com/bytecodealliance/wasm-micro-runtime).
5254

0 commit comments

Comments
 (0)