diff --git a/docs/concepts/interface-driven-development.mdx b/docs/concepts/interface-driven-development.mdx index 528cf4b6..5208430b 100644 --- a/docs/concepts/interface-driven-development.mdx +++ b/docs/concepts/interface-driven-development.mdx @@ -27,10 +27,106 @@ wasmCloud embraces interface driven development and separation of concerns in it ### WebAssembly Interface Type (WIT) -wasmCloud uses [WIT](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) as its IDL for interfaces. WIT is designed to allow WebAssembly components to define the interfaces they support ("exports") and the capabilities they need ("imports"). wasmCloud also uses WIT to define the interface/contract provided by capability providers. +wasmCloud uses [WIT][wit-spec] as its [Interface Definition Language (IDL)][wiki-idl] for interfaces (similar to [gRPC][grpc], [Smithy][smithy]). + +WIT is designed to allow WebAssembly components to define the interfaces they support ("exports") and the capabilities they need ("imports"). wasmCloud also uses WIT to define the interface/contract provided by capability providers. :::info wasmCloud is in the process of migrating interfaces from Smithy to WIT. If you see references to Smithy in the wasmCloud ecosytem, they are referring to the [stable ABI](/docs/hosts/abis/wasmbus/) ::: + +### Example: A `greeter` interface defined in WIT + +WIT interfaces are developed in the open and are simple to understand and read: + +```wit +package local:greeter-demo; // : + +interface greet { // interface + greet: func(name: string) -> string; // a function named "greet" +} + +world greeter { + export greet; // make the `greet` function available to other components/the runtime +} +``` + +While reading the [spec][wit-spec] is the best way to learn about WIT, it is also reasonably simple to understand at a glance. + +How to *use* WIT in your WebAssembly components is beyond the scope of this document, but [`wit-bindgen`][wit-bindgen] is a great place to start if you are interested. + +[wit-bindgen]: https://github.com/bytecodealliance/wit-bindgen + +### Compare: WIT vs. gRPC + +For those familiar with [gRPC][grpc], the above WIT interface would look something like the following: + +```grpc +syntax = "proto3"; + +package greeter; + +service Greeter { + rpc SayHello (HelloRequest) returns (HelloReply) {} +} + +message HelloRequest { + string name = 1; +} + +message HelloReply { + string message = 1; +} +``` + +Similar to gRPC, WIT defines both a schema and a method for serialization/movement across abstraction boundaries (via the Component Model). + +:::warning + +A key difference: while gRPC is meant to perform over network boundaries, WIT is *in-process*, and performs at near-native speed. + +::: + +### Compare: WIT vs. Smithy + +For those familiar with [smithy][smithy], the above WIT interface would look something like the following: + +```smithy +namespace com.example.greeter + +service GreeterService { + version: "2022-01-01", + operations: [Greet] +} + +operation Greet { + input: GreetRequest, + output: GreetResponse +} + +structure GreetRequest { + @required + name: String +} + +structure GreetResponse { + // Required string field + @required + message: String +} +``` + +Similar to Smithy, WIT defines both a schema and a method for serialization/movement across abstraction boundaries (via the Component Model). + +:::warning + +A key difference: while Smithy is meant to perform over network boundaries, WIT is *in-process*, and performs at near-native speed. + +::: + +[wit-spec]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md +[wiki-idl]: https://en.wikipedia.org/wiki/Interface_description_language +[smithy]: https://smithy.io +[grpc]: https://grpc.io/ diff --git a/docs/concepts/webassembly-components.mdx b/docs/concepts/webassembly-components.mdx index bd84165a..256d102a 100644 --- a/docs/concepts/webassembly-components.mdx +++ b/docs/concepts/webassembly-components.mdx @@ -16,100 +16,3 @@ The Component Model is an emerging standard for WebAssembly, and wasmCloud contr The wasmCloud host remains up-to-date with the latest versions of [wasmtime](https://wasmtime.dev/) and [WASI Preview 2](https://github.com/WebAssembly/WASI/blob/main/preview2/README.md), a set of interfaces designed to allow WebAssembly components to access external resources in a safe and portable way. -## WebAssembly Interface Types (WIT) Interfaces - -Since one of the main benefits of WebAssembly components is *composition*, it's important to structure the composition and ensure that contracts on either side are fulfilled properly. - -The [WebAssembly Interface Types (WIT) specification][wit-spec] was developed to make component composition manageable in a principled way. - -WIT serves as a WebAssembly-native [Interface Definition Language (IDL)][wiki-idl] layer (think [gRPC][grpc], [Smithy][smithy]), that directs how components interact, which types are sent over the boundaries of WebAssembly components. - -### Example: A `greeter` interface defined in WIT - -WIT interfaces are developed in the open and are simple to understand and read: - -```wit -package local:greeter-demo; // : - -interface greet { // interface - greet: func(name: string) -> string; // a function named "greet" -} - -world greeter { - export greet; // make the `greet` function available to other components/the runtime -} -``` - -While reading the [spec][wit-spec] is the best way to learn about WIT, it is also reasonably simple to understand at a glance. - -How to *use* WIT in your WebAssembly components is beyond the scope of this document, but [`wit-bindgen`][wit-bindgen] is a great place to start if you are interested. - -[wit-bindgen]: https://github.com/bytecodealliance/wit-bindgen - -### Compare: WIT vs. gRPC - -For those familiar with [gRPC][grpc], the above WIT interface would look something like the following: - -```grpc -syntax = "proto3"; - -package greeter; - -service Greeter { - rpc SayHello (HelloRequest) returns (HelloReply) {} -} - -message HelloRequest { - string name = 1; -} - -message HelloReply { - string message = 1; -} -``` - -Similar to gRPC, WIT defines both a schema and a method for serialization/movement across abstraction boundaries (via the Component Model). - -:::warning -A key difference: while gRPC is meant to perform over network boundaries, WIT is *in-process*, and performs at near-native speed. -::: - -### Compare: WIT vs. Smithy - -For those familiar with [smithy][smithy], the above WIT interface would look something like the following: - -```smithy -namespace com.example.greeter - -service GreeterService { - version: "2022-01-01", - operations: [Greet] -} - -operation Greet { - input: GreetRequest, - output: GreetResponse -} - -structure GreetRequest { - @required - name: String -} - -structure GreetResponse { - // Required string field - @required - message: String -} -``` - -Similar to Smithy, WIT defines both a schema and a method for serialization/movement across abstraction boundaries (via the Component Model). - -:::warning -A key difference: while Smithy is meant to perform over network boundaries, WIT is *in-process*, and performs at near-native speed. -::: - -[wit-spec]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md -[wiki-idl]: https://en.wikipedia.org/wiki/Interface_description_language -[smithy]: https://smithy.io -[grpc]: https://grpc.io/