From 2df50fcd7a550ccb1ae3165d7bd89d282e04b12a Mon Sep 17 00:00:00 2001 From: Roman Volosatovs Date: Thu, 5 Dec 2024 12:08:58 +0100 Subject: [PATCH] refactor: make message property setters fallible Support for `content-type` and metadata/headers across different message queues and services is not uniform. For example, RabbitMQ has built-in support for `content-type`, but NATS.io does not. Make setters of these properties on the message resource fallible to account for this difference. Note, that this is only a partial solution to the bigger issue: What's the correct behavior on the host's part when content-type and/or metadata is set in the guest message, but not supported by the underlying implementation? Signed-off-by: Roman Volosatovs --- imports-request-reply.md | 34 +++++++++++++++++++++++++++++++--- imports.md | 34 +++++++++++++++++++++++++++++++--- messaging-core.md | 34 +++++++++++++++++++++++++++++++--- messaging-request-reply.md | 34 +++++++++++++++++++++++++++++++--- wit/types.wit | 24 ++++++++++++++++++------ 5 files changed, 142 insertions(+), 18 deletions(-) diff --git a/imports-request-reply.md b/imports-request-reply.md index 84063a7..c494380 100644 --- a/imports-request-reply.md +++ b/imports-request-reply.md @@ -42,6 +42,19 @@ This allows the component to perform request/reply messaging patterns.

A catch all for other types of errors +

variant metadata-error

+

Errors that can occur when adding metadata to a message

+
Variant Cases
+

resource message

A message with a binary payload and additional information

Functions

@@ -95,12 +108,17 @@ sometimes described as the "format" type

[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

+sometimes described as the "format" type. +Error is returned if content-type is not supported by the message type.

Params
+
Return values
+

[method]message.data: func

An opaque blob of data

Params
@@ -131,20 +149,30 @@ to ensure portability across different implementors (e.g., Kafka -> NATS, etc
  • option<metadata>

    • [method]message.add-metadata: func

    -

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

    +

    Add a new key-value pair to the metadata, overwriting any existing value for the same key. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.set-metadata: func

    -

    Set the metadata

    +

    Set the metadata. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.remove-metadata: func

    Remove a key-value pair from the metadata

    Params
    diff --git a/imports.md b/imports.md index 3f09021..b734d1b 100644 --- a/imports.md +++ b/imports.md @@ -41,6 +41,19 @@ It includes the producer interface for sending messages.

    A catch all for other types of errors +

    variant metadata-error

    +

    Errors that can occur when adding metadata to a message

    +
    Variant Cases
    +

    resource message

    A message with a binary payload and additional information

    Functions

    @@ -94,12 +107,17 @@ sometimes described as the "format" type

    [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

    +sometimes described as the "format" type. +Error is returned if content-type is not supported by the message type.

    Params
    +
    Return values
    +

    [method]message.data: func

    An opaque blob of data

    Params
    @@ -130,20 +148,30 @@ to ensure portability across different implementors (e.g., Kafka -> NATS, etc
  • option<metadata>

    • [method]message.add-metadata: func

    -

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

    +

    Add a new key-value pair to the metadata, overwriting any existing value for the same key. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.set-metadata: func

    -

    Set the metadata

    +

    Set the metadata. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.remove-metadata: func

    Remove a key-value pair from the metadata

    Params
    diff --git a/messaging-core.md b/messaging-core.md index dd6d715..f8168cd 100644 --- a/messaging-core.md +++ b/messaging-core.md @@ -46,6 +46,19 @@ enabling the component to handle incoming messages without request/reply capabil

    A catch all for other types of errors +

    variant metadata-error

    +

    Errors that can occur when adding metadata to a message

    +
    Variant Cases
    +

    resource message

    A message with a binary payload and additional information

    Functions

    @@ -99,12 +112,17 @@ sometimes described as the "format" type

    [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

    +sometimes described as the "format" type. +Error is returned if content-type is not supported by the message type.

    Params
    +
    Return values
    +

    [method]message.data: func

    An opaque blob of data

    Params
    @@ -135,20 +153,30 @@ to ensure portability across different implementors (e.g., Kafka -> NATS, etc
  • option<metadata>

    • [method]message.add-metadata: func

    -

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

    +

    Add a new key-value pair to the metadata, overwriting any existing value for the same key. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.set-metadata: func

    -

    Set the metadata

    +

    Set the metadata. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.remove-metadata: func

    Remove a key-value pair from the metadata

    Params
    diff --git a/messaging-request-reply.md b/messaging-request-reply.md index e9b9abd..72bc144 100644 --- a/messaging-request-reply.md +++ b/messaging-request-reply.md @@ -48,6 +48,19 @@ handling incoming messages with request/reply capabilities.

    A catch all for other types of errors +

    variant metadata-error

    +

    Errors that can occur when adding metadata to a message

    +
    Variant Cases
    +

    resource message

    A message with a binary payload and additional information

    Functions

    @@ -101,12 +114,17 @@ sometimes described as the "format" type

    [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

    +sometimes described as the "format" type. +Error is returned if content-type is not supported by the message type.

    Params
    +
    Return values
    +

    [method]message.data: func

    An opaque blob of data

    Params
    @@ -137,20 +155,30 @@ to ensure portability across different implementors (e.g., Kafka -> NATS, etc
  • option<metadata>

    • [method]message.add-metadata: func

    -

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

    +

    Add a new key-value pair to the metadata, overwriting any existing value for the same key. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.set-metadata: func

    -

    Set the metadata

    +

    Set the metadata. +Error is returned if metadata is either not supported by the concrete message type or value is not valid.

    Params
    +
    Return values
    +

    [method]message.remove-metadata: func

    Remove a key-value pair from the metadata

    Params
    diff --git a/wit/types.wit b/wit/types.wit index 62f02f7..d3dd5c8 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -22,6 +22,15 @@ interface types { /// A catch all for other types of errors other(string), } + + /// Errors that can occur when adding metadata to a message + variant metadata-error { + /// Metadata is not supported by the message type + not-supported, + + /// Metadata is not valid for message type with optional reason + invalid(option) + } /// A message with a binary payload and additional information resource message { @@ -32,8 +41,9 @@ interface types { /// sometimes described as the "format" type content-type: func() -> option; /// Set the content-type describing the format of the data in the message. This is - /// sometimes described as the "format" type - set-content-type: func(content-type: string); + /// sometimes described as the "format" type. + /// Error is returned if content-type is not supported by the message type. + set-content-type: func(content-type: string) -> result; /// An opaque blob of data data: func() -> list; /// Set the opaque blob of data for this message, discarding the old value @@ -42,10 +52,12 @@ interface types { /// 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.). metadata: func() -> option; - /// Add a new key-value pair to the metadata, overwriting any existing value for the same key - add-metadata: func(key: string, value: string); - /// Set the metadata - set-metadata: func(meta: metadata); + /// Add a new key-value pair to the metadata, overwriting any existing value for the same key. + /// Error is returned if metadata is either not supported by the concrete message type or value is not valid. + add-metadata: func(key: string, value: string) -> result<_, metadata-error>; + /// Set the metadata. + /// Error is returned if metadata is either not supported by the concrete message type or value is not valid. + set-metadata: func(meta: metadata) -> result<_, metadata-error>; /// Remove a key-value pair from the metadata remove-metadata: func(key: string); }