Crate wasmrs_guest

Expand description

§wasmrs-guest

This crate provides the WebAssembly-side logic for wasmRS modules using the wasmRS RSocket protocol.

§Usage

This is a basic implementation of a WebAssembly module that exports three operations:

greeting::sayHello(input: string) -> string - returns a greeting, e.g. `Hello World!’
echo::chars(input: string) -> stream string - returns a stream of string representing each character in the input string
echo::reverse(input: stream string) -> stream string - reverses each string from the input stream and outputs it on a stream.

use guest::*;
use wasmrs_guest as guest;

#[no_mangle]
extern "C" fn __wasmrs_init(guest_buffer_size: u32, host_buffer_size: u32, max_host_frame_len: u32) {
  guest::init(guest_buffer_size, host_buffer_size, max_host_frame_len);

  guest::register_request_response("greeting", "sayHello", request_response);
  guest::register_request_stream("echo", "chars", request_stream);
  guest::register_request_channel("echo", "reverse", request_channel);
}

fn request_response(input: Mono<ParsedPayload, PayloadError>) -> Result<Mono<Payload, PayloadError>, GenericError> {
  Ok(async move {
    let input = deserialize::<String>(&input.await.unwrap().data).unwrap();
    let output = format!("Hello, {}!", input);
    Ok(Payload::new_data(None, Some(serialize(&output).unwrap().into())))
  }.boxed())
}

fn request_stream(
  input: Mono<ParsedPayload, PayloadError>,
) -> Result<FluxReceiver<Payload, PayloadError>, GenericError> {
  let channel = FluxChannel::<Payload, PayloadError>::new();
  let rx = channel.take_rx().unwrap();
  spawn(async move {
    let input = deserialize::<String>(&input.await.unwrap().data).unwrap();
    for char in input.chars() {
      channel
        .send(Payload::new_data(None, Some(serialize(&char).unwrap().into())))
        .unwrap();
    }
  });

  Ok(rx)
}
fn request_channel(
  mut input: FluxReceiver<ParsedPayload, PayloadError>,
) -> Result<FluxReceiver<Payload, PayloadError>, GenericError> {
  let channel = FluxChannel::<Payload, PayloadError>::new();
  let rx = channel.take_rx().unwrap();
  spawn(async move {
    while let Some(payload) = input.next().await {
      if let Err(e) = payload {
        println!("{}", e);
        continue;
      }
      let payload = payload.unwrap();
      let input = deserialize::<String>(&payload.data).unwrap();
      let output: String = input.chars().rev().collect();
      if let Err(e) = channel.send(Payload::new_data(None, Some(serialize(&output).unwrap().into()))) {
        println!("{}", e);
      }
    }
  });

  Ok(rx)
}

§Apex Code generators

NanoBus iota code generators use the wasmRS protocol. You can build wasmRS modules from those templates using the https://github.com/apexlang/apex CLI.

Run the following command to get started:

$ apex new git@github.com:nanobus/iota.git -p templates/rust [your-project]

From there, edit the apex.axdl interface definition to match your needs and run apex build to generate the wasmRS module.

§More Information

WasmRS makes heavy use of generated code from apex specs and generators to automate all of the boilerplate. See the getting-started for usage.

For more information on wasmRS, see the core wasmrs crate.

§Contributing

See CONTRIBUTING.md

§License

See the root LICENSE.txt

Re-exports§

pub use error::Error;
pub use wasmrs_runtime as runtime;

Modules§

error: The wasmRS-guest error module.
select_all: An unbounded set of streams

Structs§

Bytes: A cheaply cloneable and sliceable chunk of contiguous memory.
FluxChannel: An implementation of the Flux as seen in RSocket and reactive streams. It is similar to a [Stream<Item = Result<Item, Err>>] or an unbounded channel.
FluxPipe: A FluxPipe is the result of piping one [Flux] into another.
FluxReceiver: The receving end-only of a crate::Flux
Host: The Host inside a WebAssembly module that implements RSocket
Metadata: Metadata associated with the frame.
Mono: An implementation of Mono as seen in RSocket and reactive streams. It is similar to a [Future<Output = Result<Item, Err>>] that can be pushed to after instantiation.
OperationList: A list of imports/exports for a wasmRS module.
Payload: A Payload with pre-parsed Metadata.
PayloadError: The error type used for all [wasmrs_rx::Mono]/[wasmrs_rx::Flux] payloads.
RawPayload: A complete [Payload] object that includes metadata and data bytes.

Enums§

Frame: An enum that can hold any time of wasmrs frame.
OperationType: The types of RSocket operations supported by wasmRS.
Signal: The Signal is the wrapper payload that wasmrx types pass around.
Value: Represents any valid JSON value.

Traits§

Flux: A generic trait to wrap over Flux, Mono, and supporting types.
FutureExt: An extension trait for Futures that provides a variety of convenient adapters.
MonoFuture: A Future that wraps a Result and can be used as a Mono.
Observable: The wasmrs-rx implementation of an Rx Observable trait
Observer: The wasmrs-rx implementation of an Rx Observer trait
RSocket: A trait for an RSocket client/server (host/guest).
RequestChannel
RequestFnF
RequestResponse
RequestStream
Stream: A stream of values produced asynchronously.
StreamExt: An extension trait for Streams that provides a variety of convenient combinator functions.
TryStreamExt: Adapters specific to Result-returning streams

Functions§

add_import: Add an imported wasmRS method for the module.
deserialize: The standard function for de-serializing codec structs from a format suitable. for message exchange between actor and host. Use of any other function to. deserialize could result in breaking incompatibilities.
deserialize_generic: Deserialize a generic Value from CBOR bytes.
init: This is called as part of the module initialization for wasmRS.
init_logging: Turn on logging for the guest (WASI only).
register_fire_and_forget: Register a fire & forget handler under the specified namespace and operation.
register_request_channel: Register a request/channel handler under the specified namespace and operation.
register_request_response: Register a request/response handler under the specified namespace and operation.
register_request_stream: Register a request/stream handler under the specified namespace and operation.
select_all: Convert a list of streams into a Stream of results from the streams.
serialize: The standard function for serializing codec structs into a format that can be. used for message exchange between actor and host. Use of any other function to. serialize could result in breaking incompatibilities.
set_max_n: Set the MAX_N value for the guest.
spawn

Type Aliases§

BoxFlux: A utility type for a boxed stream.
BoxMono: A utility type for a boxed future.
FluxBox: A pinned, boxed [Flux].
GenericError: An alias to [Box<dyn std::error::Error + Send + Sync + ’static>]
IncomingMono: An alias for [Mono<ParsedPayload, PayloadError>]
IncomingStream: An alias for [FluxReceiver<ParsedPayload, PayloadError>]
OutgoingMono: An alias for [Mono<Payload, PayloadError>]
OutgoingStream: An alias for [FluxReceiver<Payload, PayloadError>]
ProcessReturnValue