Skip to content

Commit 385b7fc

Browse files
catamorphismvados-cosmonic
catamorphism
and
vados-cosmonic
authored
refactor: revise and expand on 'Component Model Concepts' section (#286)
* Revise and expand on 'Component Model Concepts' section and its subsections * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/component-model-concepts.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Integrate review feedback in component-model-concepts.md * Update component-model/src/design/components.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/components.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/components.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/interfaces.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/interfaces.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Integrate review feedback into Components section * Integrate review feedback into Interfaces section * Integrate review feedback into Packages section * Update component-model/src/design/worlds.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/worlds.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Update component-model/src/design/worlds.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> * Integrate review feedback into Worlds section * Integrate suggestions from code review * Rewrite initial para * refactor: acronym link * chore: add some spacing * chore: add more spacing --------- Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com>
1 parent e9fa7ee commit 385b7fc

File tree

6 files changed

+313
-39
lines changed

6 files changed

+313
-39
lines changed

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

Lines changed: 97 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,110 @@
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 in several ways.
4+
The Component Model:
5+
* Adds consistent representation of higher-level types
6+
* Enables interface-driven development
7+
* Makes core WebAssembly composable:
8+
components that provide functionality and those that use them
9+
can be composed together into *one* resulting component.
10+
11+
This section introduces the core concepts behind the component model.
12+
For the rationale behind the component model, see [the previous section](./why-component-model.md).
13+
14+
### Components
15+
16+
A [WebAssembly Component](./components.md) is a binary that
17+
conforms to the [Canonical ABI](../advanced/canonical-abi.md);
18+
often a WebAssembly core module extended with the features
19+
of the Component Model
20+
(higher-level types, interfaces).
21+
WebAssembly components are *nestable*:
22+
they may contain zero or more core modules and/or sub-components composed together.
23+
For example, a component implementing a simple calculator might be written
24+
by composing together a component that parses strings to floating-point numbers
25+
with a component that does the main arithmetic.
26+
27+
### WebAssembly Interface Types (WIT)
28+
29+
[WebAssembly Interface Types (WIT)][wit] is the [Interface Definition Language (IDL)][wiki-idl]
30+
used to formally define functionality for WebAssembly components.
31+
WIT gives WebAssembly components the ability to express type signatures
32+
in a language-agnostic way,
33+
so any component binary can be checked, composed and executed.
34+
35+
#### Interfaces
36+
37+
An [_interface_](./interfaces.md) is a collection of type definitions
38+
and function declarations (function names accompanied by type signatures).
39+
Typically, a single interface describes a specific, focused bit
40+
of functionality.
41+
42+
For example, in [wasi-cli][wasi-cli-stdio],
43+
three separate interfaces are used to implement `stdin`, `stdout`, and `stderr`
44+
(streams typically available in command-line-like environments)
45+
46+
### Worlds
47+
48+
A [_world_](./worlds.md) is a collection of interfaces and types
49+
that expresses what features a component offers
50+
and what features it depends on.
51+
52+
For example, wasi-cli includes the [`command` world][wasi-cli-command],
53+
which depends on interfaces
54+
that represent the `stdin`, `stdout`, and `stderr` streams,
55+
among other things.
56+
A component implementing the `command` world
57+
must be invoked in an environment that implements those interfaces.
58+
59+
### Packages
60+
61+
A [_package_](./packages.md) is a set of WIT files
62+
containing a related set of interfaces and worlds.
63+
64+
For example, the [wasi-http](https://github.com/WebAssembly/wasi-http/blob/main/wit/proxy.wit) package includes
65+
an `imports` world encapsulating the interfaces that an HTTP proxy depends on,
66+
and a `proxy` world that depends on `imports`.
67+
68+
### Platforms
69+
70+
In the context of WebAssembly, a _host_ refers to a WebAssembly runtime
71+
capable of executing WebAssembly binaries.
72+
The runtime can be inside a browser or can stand alone.
73+
A _guest_ refers to the WebAssembly binary that is executed by the host.
74+
(These terms borrow from their analogs in [virtualization](https://en.wikipedia.org/wiki/Virtualization), where a guest is
75+
a software-based virtual machine that runs on physical hardware,
76+
which is the "host")
77+
78+
The Component Model introduces the idea of a _platform_
79+
to core WebAssembly—enabling the structured, standardized use
80+
of host functionality for WebAssembly guests.
81+
Components may import functionality that is provided
82+
by the platform on which they are executed.
83+
84+
### WASI
85+
86+
The WebAssembly System Interface ([WASI][wasi]) defines in WIT
87+
a family of interfaces for common system-level functions.
88+
WASI defines a platform for component writers that mimics
89+
existing programs that developers are familiar with
90+
(for example, `wasi-cli` or `wasi-http`),
91+
standardizing the functionality components depend on.
1792

1893
> [!NOTE]
19-
> The Component Model is stewarded by the Bytecode Alliance and designed [in the open][cm-repo].
94+
> The Component Model is stewarded by the [Bytecode Alliance](https://bytecodealliance.org/) and designed [in the open][cm-repo].
2095
>
21-
> See the [`WebAssembly/component-model`][cm-repo] repository for [Goals][goals],[use cases][use-cases], and [high level design choices][design-choices].
96+
> See the [`WebAssembly/component-model`][cm-repo] repository for [goals][goals], [use cases][use-cases], and [high level design choices][design-choices].
2297
2398
[cm-repo]: https://github.com/WebAssembly/component-model
24-
[wiki-idl]: https://en.wikipedia.org/wiki/Web_IDL
99+
[wiki-idl]: https://en.wikipedia.org/wiki/Interface_description_language
25100
[goals]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Goals.md
26101
[use-cases]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/UseCases.md
27102
[design-choices]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Choices.md
28103
[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
104+
[wasi]: https://wasi.dev/
105+
[wasi-cli]: https://github.com/WebAssembly/wasi-cli/
106+
[wasi-cli-stdio]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/stdio.wit
107+
[wasi-cli-command]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/command.wit
108+
[wasi-http]: https://github.com/WebAssembly/wasi-http
29109

30110
[!NOTE]: #

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

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,60 @@
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 WebAssembly binary
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 [WebAssembly Interface Types (WIT)](./wit.md).
31+
32+
> For a more formal definition of a component,
33+
> take a look at the [Component Model specification](https://github.com/WebAssembly/component-model).
34+
35+
The on-disk representation of a component
36+
is [a specially-formatted WebAssembly binary](../advanced/canonical-abi.md).
37+
Internally, this file could include representations
38+
of one or many traditional ("core") WebAssembly modules and sub-components,
39+
composed together via their imports and exports.
40+
Two modules or components can be composed if the
41+
imports of one are satisfied by the exports of another.
42+
Composition can be repeated arbitarily, composing a
43+
single component out of many interlocking modules and components.
44+
[Interfaces](./interfaces.md) enable checking that
45+
a particular composition makes sense.
46+
47+
Each component is described by a [world](./worlds.md),
48+
which potentially collects together multiple interfaces
49+
to describe all the imports and exports of the component.
50+
The world only describes the types of imported and exported functions;
51+
the component internally defines the code to implement the world.
52+
53+
## Composition
54+
55+
Two modules or components can be composed if the
56+
imports of one are satisfied by the exports of another.
57+
Composition can be repeated arbitarily, composing a
58+
single component out of many interlocking modules and components.
59+
[Interfaces](./interfaces.md) enable checking that
60+
a particular composition makes sense.

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

Lines changed: 52 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,58 @@
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+
Concretely, an interface is a collection of type definitions
8+
and function declarations.
9+
Conceptually, an _interface_ describes a single-focus, composable contract
10+
through which components can interact with each other
11+
and with hosts.
12+
* _Single-focus_: By convention, an interface describes
13+
types and functions that are related to each other
14+
and collectively provide a relatively small unit of
15+
functionality,
16+
such as reading from the standard input stream
17+
in a command-line environment.
18+
* _Composable_: Interfaces can be imported and exported.
19+
One component's interfaces can be built
20+
on top of interfaces defined in a different component.
21+
Interfaces enable typechecking so that interfaces can
22+
be composed only when it makes sense to do so.
23+
24+
The types and functions in an interface
25+
are used to enable interactions between components and hosts.
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+
This might look like the `incoming-handler` interface
34+
in [wasi-http][wasi-http-handler]
35+
* A "wall clock" interface might declare two functions,
36+
one to get the current time
37+
and one to get the granularity of the timer (whether time
38+
is measured in seconds, milliseconds, nanoseconds, or another unit).
39+
It would also define a type to represent an instant in time.
40+
This might look like the `wall-clock` interface
41+
in [wasi-clocks][wasi-clocks-wall-clock].
42+
43+
As an example of composing interfaces together,
44+
imagine defining a "timer" interface that declares two functions,
45+
one to start a timer and one to query whether the timeout
46+
has been exceeded.
47+
This interface could be defined by importing the "wall clock"
48+
interface.
49+
The result is an interface that exports the timer functionality,
50+
and imports anything imported by the "wall clock" interface.
751

852
Interfaces are defined using [the WIT language](./wit.md).
953

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).
54+
[wp-contract]: https://en.wikipedia.org/wiki/Design_by_contract
55+
[wasi-http-handler]: https://github.com/WebAssembly/wasi-http/blob/main/wit/handler.wit
56+
[wasi-clocks-wall-clock]: https://github.com/WebAssembly/wasi-clocks/blob/main/wit/wall-clock.wit
57+
58+
> 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: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,23 @@
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 [WebAssembly Interface Type](./wit.md) (WIT) files
4+
that, taken together, contain a set of interfaces and worlds that are related to each other.
5+
WIT is an [interface definition language][wp-idl] (IDL) 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 groups related interfaces and worlds together
10+
for ease of discovery and reference.
11+
A package is not a [world](./worlds.md): a package maps to one or more files
12+
and contains worlds.
13+
A world is a bundle of imported and exported types and interfaces.
614

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.
15+
* The WebAssembly System Interface (WASI) defines a number of packages,
16+
including one named `wasi:clocks`.
17+
Our HTTP proxy world could import the `wasi:clocks/wall-clock` interface
18+
(read as "the `wall-clock` interface from the `wasi:clocks` package"),
19+
rather than having to define a custom clock interface.
820

921
> 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).
22+
23+
[wp-idl]: https://en.wikipedia.org/wiki/Interface_description_language

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

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

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

0 commit comments

Comments
 (0)