From 7b2f2bb1c56de6fb2a810aaf13e6f06df0d454fe Mon Sep 17 00:00:00 2001 From: Andrzej Ressel Date: Mon, 11 Mar 2024 02:18:18 +0100 Subject: [PATCH 1/2] More docs --- docs/Internal/Data passing.md | 4 +-- docs/Internal/Output.md | 58 +++++++++++++++++++++++++++++++++++ docs/Internal/WIT.md | 2 ++ docs/crates.md | 38 +++++++++++++++++++++++ 4 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 docs/Internal/WIT.md create mode 100644 docs/crates.md diff --git a/docs/Internal/Data passing.md b/docs/Internal/Data passing.md index 7c9590f00..26d17a871 100644 --- a/docs/Internal/Data passing.md +++ b/docs/Internal/Data passing.md @@ -1,9 +1,9 @@ ```mermaid stateDiagram-v2 - UserInput --> Pulumi_provider_wasm: WIT + User --> Pulumi_provider_wasm: WIT Pulumi_provider_wasm --> Pulumi_wasm: MessagePack - Pulumi_wasm --> PulumiProper: Protobuf + Pulumi_wasm --> Pulumi: Protobuf ``` diff --git a/docs/Internal/Output.md b/docs/Internal/Output.md index e69de29bb..4210f74ef 100644 --- a/docs/Internal/Output.md +++ b/docs/Internal/Output.md @@ -0,0 +1,58 @@ +# Outputs + +## Types of Output + +Pulumi WASM has 4 types of outputs: +1. Done +2. Mapped +3. Func +4. Unknown + +### Done + +This is output for which value is known. Internally it's represented as MessagePack's `Value`. + +### Mapped + +This is output which wait to be mapped by host. More details are in [Mapping](#Mapping) section. Internally it's represented as tuple of function name and output which will values will be it's argument. + +### Func + +This is output that is a function. As opposed to `Mapped` this function in executed internally in Pulumi WASM. Currently these are +functions that creates resources. Internally it's tuple of list of outputs and function that handles their values. + +### Unknown + +This is output for which value will never be known. This is used in Pulumi's preview stage. + +## Mapping + +One of Pulumi features is allowing transforming values in programming languages as opposed to +configuration language like in Terraform. While it's obvious how to do that when everything is written in one language +in Pulumi WASM it's not the case - internals are written in Rust compiled to WASM, while user code +can be written in any language that can be compiled to WASM. + +To handle it mapping value has 2 stages: + +1. Save function in global map (in functional languages it may be monad) +2. Iterating over all values that be mapped and invoking function on it. + +Simplified sequence diagram of this process: + +```mermaid +sequenceDiagram + User --> User: Create function + User --> User: Assign ID to function + User -> Pulumi_WASM: Map given output with function "ID" + Note left of User: Other computations + + loop While there are still outputs to map (1) + User -> Pulumi_WASM: Get output values with function ids + User --> User: Compute results + User -> Pulumi_WASM: Return values + end +``` + +(1) Outputs ready to be mapped are of type `Func` for which input is type `Done` + +Currently due to single threaded nature of WASM this operation is done at the end of the program. \ No newline at end of file diff --git a/docs/Internal/WIT.md b/docs/Internal/WIT.md new file mode 100644 index 000000000..2f1b3afe3 --- /dev/null +++ b/docs/Internal/WIT.md @@ -0,0 +1,2 @@ +# WIT + diff --git a/docs/crates.md b/docs/crates.md new file mode 100644 index 000000000..e6b66562b --- /dev/null +++ b/docs/crates.md @@ -0,0 +1,38 @@ +# Crates + +### Pulumi WASM + +Main WASM component. Currently implements Output handling, send and handles requests to Pulumi. + +### Pulumi WASM runner + +x64 application that runs the WASM component. +Implements `component:pulumi-wasm@0.1.0/external-world` and `component:pulumi-wasm@0.1.0/log` interfaces. + +### Pulumi WASM Rust + +Rust library that provides a high-level and typesafe API for Pulumi WASM. It's a wrapper around `pulumi-wasm` interfaces. +Also provides `pulumi_main` macro via `pub use` from `Pulumi WASM Rust Macro`. + +### Pulumi WASM Rust Macro + +Rust library with `pulumi_main` macro. Addon to `Pulumi WASM Rust` + +### WASM Common + +Library used in WASM components of Pulumi providers. Currently provides logging facilities. + +### Pulumi WASM Provider Random + +WASM component for Pulumi's Random provider. Currently handwritten - +after [#5](https://github.com/andrzejressel/pulumi-wasm/issues/5) generated. + +### Pulumi WASM Provider Random Rust + +Rust library that provides a high-level and typesafe API for `Pulumi WASM Provider Random` WASM component. +Currently handwritten - after [#5](https://github.com/andrzejressel/pulumi-wasm/issues/5) generated. + +### examples/simple + +Currently the only example. It's a simple Pulumi program that uses `Pulumi WASM Provider Random Rust` to generate random numbers. +In future will be one of integration tests. \ No newline at end of file From e7373f1d53bf4df857b811bdb89c2adae3169642 Mon Sep 17 00:00:00 2001 From: Andrzej Ressel Date: Mon, 11 Mar 2024 02:20:14 +0100 Subject: [PATCH 2/2] More docs --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 38f9b02a9..f1f26b4ad 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,7 +4,7 @@ name: Docs on: # Runs on pushes targeting the default branch push: - branches: ["main", "docs"] + branches: ["main"] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: