Fixes, README, rpc-error type (#2)

* Fixes, README, rpc-error type

* Export RpcError

README.md

@@ -2,6 +2,19 @@
 
 ## golem-wasm-rpc
 
+Defines data types for [Golem](https://golem.cloud)'s remote function invocation and conversions between them.
+
+- `WitValue` is the WIT-defined generic data type capable of representing an arbitrary value, generated by `wit-bindgen`
+- A builder and an extractor API for `WitValue`
+- `Value` is a recursive Rust type which is more convenient to work with than `WitValue`. Conversion between `WitValue` and `Value` is implemented in both directions.
+- Protobuf message types for describing values and types, and a protobuf version of `WitValue` itself and conversion from and to `Value` and `WitValue`
+- JSON representation of WIT values, as defined in [the Golem docs](https://learn.golem.cloud/docs/template-interface).
+- Conversion of `Value` to and from `wasmtime` values
+
+The JSON representation requires additional type information which can be extracted using the [golem-wasm-ast](https://crates.io/crates/golem-wasm-ast) crate.
+
+## Host and stub mode
+
 The `golem-wasm-rpc` crate can be both used in host and guest environments:
 
 To compile the host version:
@@ -16,6 +29,15 @@ To compile the guest version, has minimal dependencies and feature set to be use
 cargo component build -p wasm-rpc --no-default-features --features stub
 ```
 
+## Feature flags
+- `arbitrary` adds an `Arbitrary` instance for `Value`
+- `json` adds conversion functions for mapping of a WIT value and type definition to/from JSON
+- `protobuf` adds the protobuf message types
+- `wasmtime` adds conversion to `wasmtime` `Val` values
+- `host` enables all features: `arbitrary`, `json`, `protobuf`, `typeinfo`, and `wasmtime`
+- `stub` is to be used in generated WASM stubs and disables all features, and generates guest bindings instead of host bindings
+
+
 ## golem-wasm-rpc-stubgen
 
 The `golem-wasm-rpc-stubgen` is a CLI tool to generate the RPC stubs from a component's WIT definition.

wasm-rpc-stubgen/README.md

@@ -0,0 +1,35 @@
+# golem-wasm-rpc-stubgen
+
+The `golem-wasm-rpc-stubgen` is a CLI tool to generate the RPC stubs from a component's WIT definition.
+
+```shell
+Usage: wasm-rpc-stubgen generate [OPTIONS] --source-wit-root <SOURCE_WIT_ROOT> --dest-crate-root <DEST_CRATE_ROOT>
+
+Options:
+ -s, --source-wit-root <SOURCE_WIT_ROOT> 
+ -d, --dest-crate-root <DEST_CRATE_ROOT> 
+ -w, --world <WORLD> 
+ --stub-crate-version <STUB_CRATE_VERSION> [default: 0.0.1]
+ --wasm-rpc-path-override <WASM_RPC_PATH_OVERRIDE> 
+ -h, --help Print help
+ -V, --version Print version
+```
+
+- `source-wit-root`: The root directory of the component's WIT definition to be called via RPC
+- `dest-crate-root`: The target path to generate a new stub crate to
+- `world`: The world name to be used in the generated stub crate. If there is only a single world in the source root
+ package, no need to specify.
+- `stub-crate-version`: The crate version of the generated stub crate
+- `wasm-rpc-path-override`: The path to the `wasm-rpc` crate to be used in the generated stub crate. If not specified,
+ the latest version of `wasm-rpc` will be used.
+
+The command creates a new Rust crate that is ready to be compiled with
+
+```shell
+cargo component build --release
+```
+
+The resulting WASM component implements the **stub interface** corresponding to the source interface, found in the
+target directory's
+`wit/_stub.wit` file. This WASM component is to be composed together with another component that calls the original
+interface via WASM RPC.

wasm-rpc-stubgen/src/cargo.rs

@@ -103,7 +103,7 @@ pub fn generate_cargo_toml(def: &StubDefinition) -> anyhow::Result<()> {
  }),
  };
 
- let mut package = cargo_toml::Package::new(def.source_world_name()?, &def.stub_crate_version);
+ let mut package = cargo_toml::Package::new(def.target_crate_name()?, &def.stub_crate_version);
  package.edition = Inheritable::Set(Edition::E2021);
  package.metadata = Some(metadata);
  manifest.package = Some(package);

wasm-rpc-stubgen/src/rust.rs

@@ -14,7 +14,7 @@
 
 use crate::stub::{FunctionResultStub, FunctionStub, StubDefinition};
 use anyhow::anyhow;
-use heck::{ToShoutySnakeCase, ToUpperCamelCase};
+use heck::{ToShoutySnakeCase, ToSnakeCase, ToUpperCamelCase};
 use proc_macro2::{Ident, Span, TokenStream};
 use quote::quote;
 use std::fs;
@@ -51,20 +51,24 @@ pub fn generate_stub_source(def: &StubDefinition) -> anyhow::Result<()> {
  let mut fn_impls = Vec::new();
  for function in &interface.functions {
  fn_impls.push(generate_function_stub_source(
+ def,
  function,
- &root_ns,
- &root_name,
  if interface.global {
  None
  } else {
  Some(&interface.name)
  },
- &def.resolve,
  )?);
  }
 
+ let stub_interface_name = format!("stub-{}", def.source_world_name()?);
+ let stub_interface_name = Ident::new(
+ &to_rust_ident(&stub_interface_name).to_snake_case(),
+ Span::call_site(),
+ );
+
  interface_impls.push(quote! {
- impl crate::bindings::exports::#root_ns::#root_name::stub_api::#guest_interface_name for #interface_name {
+ impl crate::bindings::exports::#root_ns::#root_name::#stub_interface_name::#guest_interface_name for #interface_name {
  fn new(location: crate::bindings::golem::rpc::types::Uri) -> Self {
  let location = Uri { value: location.value };
  Self {
@@ -101,11 +105,9 @@ pub fn generate_stub_source(def: &StubDefinition) -> anyhow::Result<()> {
 }
 
 fn generate_function_stub_source(
+ def: &StubDefinition,
  function: &FunctionStub,
- root_ns: &Ident,
- root_name: &Ident,
  interface_name: Option<&String>,
- resolve: &Resolve,
 ) -> anyhow::Result<TokenStream> {
  let function_name = Ident::new(&to_rust_ident(&function.name), Span::call_site());
  let mut params = Vec::new();
@@ -114,7 +116,7 @@ fn generate_function_stub_source(
 
  for param in &function.params {
  let param_name = Ident::new(&to_rust_ident(&param.name), Span::call_site());
- let param_typ = type_to_rust_ident(&param.typ, resolve)?;
+ let param_typ = type_to_rust_ident(&param.typ, &def.resolve)?;
  params.push(quote! {
  #param_name: #param_typ
  });
@@ -123,14 +125,14 @@ fn generate_function_stub_source(
  input_values.push(wit_value_builder(
  &param.typ,
  &param_name_access,
- resolve,
+ &def.resolve,
  quote! { WitValue::builder() },
  )?);
  }
 
  let result_type = match &function.results {
  FunctionResultStub::Single(typ) => {
- let typ = type_to_rust_ident(typ, resolve)?;
+ let typ = type_to_rust_ident(typ, &def.resolve)?;
  quote! {
  #typ
  }
@@ -139,7 +141,7 @@ fn generate_function_stub_source(
  let mut results = Vec::new();
  for param in params {
  let param_name = Ident::new(&to_rust_ident(&param.name), Span::call_site());
- let param_typ = type_to_rust_ident(&param.typ, resolve)?;
+ let param_typ = type_to_rust_ident(&param.typ, &def.resolve)?;
  results.push(quote! {
  #param_name: #param_typ
  });
@@ -158,13 +160,17 @@ fn generate_function_stub_source(
 
  match &function.results {
  FunctionResultStub::Single(typ) => {
- output_values.push(extract_from_wit_value(typ, resolve, quote! { result })?);
+ output_values.push(extract_from_wit_value(
+ typ,
+ &def.resolve,
+ quote! { result },
+ )?);
  }
  FunctionResultStub::Multi(params) => {
  for (n, param) in params.iter().enumerate() {
  output_values.push(extract_from_wit_value(
  &param.typ,
- resolve,
+ &def.resolve,
  quote! { result.tuple_element(#n).expect("tuple not found") },
  )?);
  }
@@ -174,9 +180,15 @@ fn generate_function_stub_source(
  let remote_function_name = match interface_name {
  Some(remote_interface) => format!(
  "{}:{}/{}/{}",
- root_ns, root_name, remote_interface, function.name
+ def.root_package_name.namespace,
+ def.root_package_name.name,
+ remote_interface,
+ function.name
+ ),
+ None => format!(
+ "{}:{}/{}",
+ def.root_package_name.namespace, def.root_package_name.name, function.name
  ),
- None => format!("{}:{}/{}", root_ns, root_name, function.name),
  };
 
  Ok(quote! {

wasm-rpc-stubgen/src/stub.rs

@@ -89,6 +89,10 @@ impl StubDefinition {
  self.target_root.join("Cargo.toml")
  }
 
+ pub fn target_crate_name(&self) -> anyhow::Result<String> {
+ Ok(format!("{}-stub", self.source_world_name()?))
+ }
+
  pub fn target_rust_path(&self) -> PathBuf {
  self.target_root.join("src/lib.rs")
  }
@@ -315,10 +319,12 @@ fn get_unresolved_packages(
 
  let mut deps = BTreeMap::new();
  let deps_path = root_path.join(Path::new("deps"));
- for dep_entry in fs::read_dir(deps_path)? {
- let dep_entry = dep_entry?;
- let dep = UnresolvedPackage::parse_path(&dep_entry.path())?;
- deps.insert(dep.name.clone(), dep);
+ if deps_path.exists() {
+ for dep_entry in fs::read_dir(deps_path)? {
+ let dep_entry = dep_entry?;
+ let dep = UnresolvedPackage::parse_path(&dep_entry.path())?;
+ deps.insert(dep.name.clone(), dep);
+ }
  }
 
  // Perform a simple topological sort which will bail out on cycles

wasm-rpc/README.md

@@ -0,0 +1,36 @@
+# golem-wasm-rpc
+
+Defines data types for [Golem](https://golem.cloud)'s remote function invocation and conversions between them.
+
+- `WitValue` is the WIT-defined generic data type capable of representing an arbitrary value, generated by `wit-bindgen`
+- A builder and an extractor API for `WitValue`
+- `Value` is a recursive Rust type which is more convenient to work with than `WitValue`. Conversion between `WitValue` and `Value` is implemented in both directions.
+- Protobuf message types for describing values and types, and a protobuf version of `WitValue` itself and conversion from and to `Value` and `WitValue`
+- JSON representation of WIT values, as defined in [the Golem docs](https://learn.golem.cloud/docs/template-interface).
+- Conversion of `Value` to and from `wasmtime` values
+
+The JSON representation requires additional type information which can be extracted using the [golem-wasm-ast](https://crates.io/crates/golem-wasm-ast) crate.
+
+## Host and stub mode
+
+The `golem-wasm-rpc` crate can be both used in host and guest environments:
+
+To compile the host version:
+
+```shell
+cargo build -p wasm-rpc --no-default-features --features host
+```
+
+To compile the guest version, has minimal dependencies and feature set to be used in generated stubs:
+
+```shell
+cargo component build -p wasm-rpc --no-default-features --features stub
+```
+
+## Feature flags
+- `arbitrary` adds an `Arbitrary` instance for `Value`
+- `json` adds conversion functions for mapping of a WIT value and type definition to/from JSON
+- `protobuf` adds the protobuf message types
+- `wasmtime` adds conversion to `wasmtime` `Val` values
+- `host` enables all features: `arbitrary`, `json`, `protobuf`, `typeinfo`, and `wasmtime`
+- `stub` is to be used in generated WASM stubs and disables all features, and generates guest bindings instead of host bindings