Skip to content

Latest commit

 

History

History
303 lines (303 loc) · 15.8 KB

messaging-request-reply.md

File metadata and controls

303 lines (303 loc) · 15.8 KB
Raw

World messaging-request-reply

The messaging-request-reply world combines imports-request-reply with the incoming-handler export. This setup allows the host to interact with the component for both sending messages and handling incoming messages with request/reply capabilities.

Import interface wasi:messaging/[email protected]

Types

type metadata

metadata

A type alias for list> to represent metadata attached to a message

type topic

string

A type alias for string to represent a message topic

resource client

A connection to a message-exchange service (e.g., buffer, broker, etc.).

variant error

Errors that can occur when using the messaging interface.

Variant Cases

  • timeout

    The request or operation timed out.

  • connection: string

    An error occurred with the connection. Includes a message for additional context

  • permission-denied: string

    A permission error occurred. Includes a message for additional context

  • other: string

    A catch all for other types of errors

resource message

A message with a binary payload and additional information

Functions

[static]client.connect: func

Params
  • name: string
Return values

[method]client.disconnect: func

Params
Return values

[constructor]message: func

Params
  • data: list<u8>
Return values

[method]message.topic: func

The topic/subject/channel this message was received on, if any

Params
Return values

[method]message.content-type: func

An optional content-type describing the format of the data in the message. This is sometimes described as the "format" type

Params
Return values
  • option<string>

[method]message.set-content-type: func

Set the content-type describing the format of the data in the message. This is sometimes described as the "format" type

Params
  • self: borrow<message>
  • content-type: string

[method]message.data: func

An opaque blob of data

Params
Return values
  • list<u8>

[method]message.set-data: func

Set the opaque blob of data for this message, discarding the old value

Params
  • self: borrow<message>
  • data: list<u8>

[method]message.metadata: func

Optional metadata (also called headers or attributes in some systems) attached to the message. This metadata is simply decoration and should not be interpreted by a host to ensure portability across different implementors (e.g., Kafka -> NATS, etc.).

Params
Return values

[method]message.add-metadata: func

Add a new key-value pair to the metadata, overwriting any existing value for the same key

Params
  • self: borrow<message>
  • key: string
  • value: string

[method]message.set-metadata: func

Set the metadata

Params

[method]message.remove-metadata: func

Remove a key-value pair from the metadata

Params
  • self: borrow<message>
  • key: string

Import interface wasi:messaging/[email protected]

The request-reply interface allows a guest to send a message and await a response. This interface is considered optional as not all message services support the concept of request/reply. However, request/reply is a very common pattern in messaging and as such, we have included it as a core interface.

Types

type client

client

#### `type message` [`message`](#message)

#### `type error` [`error`](#error)

#### `type topic` [`topic`](#topic)

#### `resource request-options`

Options for a request/reply operation. This is a resource to allow for future expansion of options.

Functions

[constructor]request-options: func

Creates a new request options resource with no options set.

Return values

[method]request-options.set-timeout-ms: func

The maximum amount of time to wait for a response. If the timeout value is not set, then the request/reply operation will block until a message is received in response.

Params

[method]request-options.set-expected-replies: func

The maximum number of replies to expect before returning.

Params

request: func

Performs a blocking request/reply operation with an optional set of request options.

The behavior of this function is largely dependent on the options given to the function. If no options are provided, then the request/reply operation will block until a single message is received in response. If a timeout is provided, then the request/reply operation will block for the specified amount of time before returning an error if no messages were received (or the list of messages that were received). If both a timeout and an expected number of replies are provided, the function should return when either condition is met (whichever comes first)—e.g., (1) if no replies were received within the timeout return an error, (2) if the maximum expected number of replies were received before timeout, return the list of messages, or (3) if the timeout is reached before the expected number of replies, return the list of messages received up to that point.

Params
Return values

reply: func

Replies to the given message with the given response message. The details of which topic the message is sent to is up to the implementation. This allows for reply-to details to be handled in the best way possible for the underlying messaging system.

Please note that this reply functionality is different than something like HTTP because there are several use cases in which a reply might not be required for every message (so this would be a noop). There are also cases when you might want to reply and then continue processing. Additionally, you might want to reply to a message several times (such as providing an update). So this function is allowed to be called multiple times, unlike something like HTTP where the reply is sent and the connection is closed.

Params
Return values

Import interface wasi:messaging/[email protected]

The producer interface is used to send messages to a channel/topic.

Types

type client

client

#### `type message` [`message`](#message)

#### `type error` [`error`](#error)

#### `type topic` [`topic`](#topic)

----

Functions

send: func

Sends the message using the given client.

Params
Return values

Export interface wasi:messaging/[email protected]

Types

type message

message

#### `type error` [`error`](#error)

#### `type topic` [`topic`](#topic)

----

Functions

handle: func

Whenever this guest receives a message in one of the subscribed topics, the message is sent to this handler. The guest is responsible for matching on the topic and handling the message accordingly. Implementors (such as hosts) calling this interface should make their own decisions on how to handle errors returned from this function.

Params
Return values