WAMP Advanced Profile

1.1. Feature Announcement

Support for advanced features must be announced by the peers which implement them. The following is a complete list of advanced features currently defined or proposed.¶

Advanced RPC Features¶

Advanced PubSub Features¶

Other Advanced Features¶

The status of the respective AP feature is marked as follows:¶

1.2. Additional Messages

The Advanced Profile defines additional WAMP-level messages which are explained in detail in separate sections. The following 4 additional message types MAY be used in the Advanced Profile and their direction between peer roles. Here, "Tx" ("Rx") means the message is sent (received) by a peer of the respective role.¶

    [CHALLENGE, AuthMethod|string, Extra|dict]

    [AUTHENTICATE, Signature|string, Extra|dict]

    [CANCEL, CALL.Request|id, Options|dict]

    [INTERRUPT, INVOCATION.Request|id, Options|dict]

2.1. Session Meta API

WAMP enables the monitoring of when sessions join a realm on the router or when they leave it via Session Meta Events. It also allows retrieving information about currently connected sessions via Session Meta Procedures.¶

Meta events are created by the router itself. This means that the events, as well as the data received when calling a meta procedure, can be accorded the same trust level as the router.¶

Note that an implementation that only supports a Broker or Dealer role, not both at the same time, essentially cannot offer the Session Meta API, as it requires both roles to support this feature.¶

The following sections contain an informal, easy to digest description of the WAMP procedures and topics available in (this part of) the WAMP Meta API. A formal definition of the WAMP Meta API in terms of available WAMP procedures and topics including precise and complete type definitions of the application payloads, that is procedure arguments and results or event payloads is contained in¶

• Compiled Binary Schema: <WAMP API Catalog>/schema/wamp-meta.bfbs¶
• FlatBuffers Schema Source: <WAMP API Catalog>/src/wamp-meta.fbs¶

which uses FlatBuffers IDL to describe the API. The method of using FlatBuffers IDL and type definitions to formally define WAMP procedures and topics is detailed in section WAMP IDL.¶

Feature Announcement¶

Support for this feature MUST be announced by both Dealers and Brokers via:¶

    HELLO.Details.roles.<role>.features.
        session_meta_api|bool := true

Here is a WELCOME message from a Router with support for both the Broker and Dealer role, and with support for Session Meta API:¶

    [
        2,
        4580268554656113,
        {
            "authid":"OL3AeppwDLXiAAPbqm9IVhnw",
            "authrole": "anonymous",
            "authmethod": "anonymous",
            "roles": {
                "broker": {
                    "features": {
                        "session_meta_api": true
                    }
                },
                "dealer": {
                    "features": {
                        "session_meta_api": true
                    }
                }
            }
        }
    ]

Note in particular that the feature is announced on both the Broker and the Dealer roles.¶

2.2. Registration Meta API

Registration Meta Events are fired when registrations are first created, when Callees are attached (removed) to (from) a registration, and when registrations are finally destroyed.¶

Furthermore, WAMP allows actively retrieving information about registrations via Registration Meta Procedures.¶

Meta-events are created by the router itself. This means that the events as well as the data received when calling a meta-procedure can be accorded the same trust level as the router.¶

Note that an implementation that only supports a Broker or Dealer role, not both at the same time, essentially cannot offer the Registration Meta API, as it requires both roles to support this feature.¶

The following sections contain an informal, easy to digest description of the WAMP procedures and topics available in (this part of) the WAMP Meta API. A formal definition of the WAMP Meta API in terms of available WAMP procedures and topics including precise and complete type definitions of the application payloads, that is procedure arguments and results or event payloads is contained in:¶

• Compiled Binary Schema: <WAMP API Catalog>/schema/wamp-meta.bfbs¶
• FlatBuffers Schema Source: <WAMP API Catalog>/src/wamp-meta.fbs¶

which uses FlatBuffers IDL to describe the API. The method of using FlatBuffers IDL and type definitions to formally define WAMP procedures and topics is detailed in section WAMP IDL.¶

Feature Announcement¶

Support for this feature MUST be announced by a Dealers (role := "dealer") via:¶

    HELLO.Details.roles.<role>.features.
        registration_meta_api|bool := true

Here is a WELCOME message from a Router with support for both the Broker and Dealer role, and with support for Registration Meta API:¶

    [
        2,
        4580268554656113,
        {
            "authid":"OL3AeppwDLXiAAPbqm9IVhnw",
            "authrole": "anonymous",
            "authmethod": "anonymous",
            "roles": {
                "broker": {
                    "features": {
                    }
                },
                "dealer": {
                    "features": {
                        "registration_meta_api": true
                    }
                }
            }
        }
    ]

    RegistrationDetails :=
    {
        "id": registration|id,
        "created": time_created|iso_8601_string,
        "uri": procedure|uri,
        "match": match_policy|string,
        "invoke": invocation_policy|string
    }

    RegistrationLists :=
    {
        "exact": registration_ids|list,
        "prefix": registration_ids|list,
        "wildcard": registration_ids|list
    }

    RegistrationDetails :=
    {
        "id": registration|id,
        "created": time_created|iso_8601_string,
        "uri": procedure|uri,
        "match": match_policy|string,
        "invoke": invocation_policy|string
    }

2.3. Subscriptions Meta API

Within an application, it may be desirable for a publisher to know whether a publication to a specific topic currently makes sense, i.e. whether there are any subscribers who would receive an event based on the publication. It may also be desirable to keep a current count of subscribers to a topic to then be able to filter out any subscribers who are not supposed to receive an event.¶

Subscription meta-events are fired when topics are first created, when clients subscribe/unsubscribe to them, and when topics are deleted. WAMP allows retrieving information about subscriptions via subscription meta-procedures.¶

Support for this feature MUST be announced by Brokers via¶

    HELLO.Details.roles.broker.features.subscription_meta_api|
        bool := true

Meta-events are created by the router itself. This means that the events as well as the data received when calling a meta-procedure can be accorded the same trust level as the router.¶

The following sections contain an informal, easy to digest description of the WAMP procedures and topics available in (this part of) the WAMP Meta API. A formal definition of the WAMP Meta API in terms of available WAMP procedures and topics including precise and complete type definitions of the application payloads, that is procedure arguments and results or event payloads is contained in¶

• Compiled Binary Schema: <WAMP API Catalog>/schema/wamp-meta.bfbs¶
• FlatBuffers Schema Source: <WAMP API Catalog>/src/wamp-meta.fbs¶

which uses FlatBuffers IDL to describe the API. The method of using FlatBuffers IDL and type definitions to formally define WAMP procedures and topics is detailed in section WAMP IDL.¶

Feature Announcement¶

Support for this feature MUST be announced by a Brokers (role := "nroker") via:¶

    HELLO.Details.roles.<role>.features.
        subscription_meta_api|bool := true

Here is a WELCOME message from a Router with support for both the Broker and Dealer role, and with support for Subscription Meta API:¶

    [
        2,
        4580268554656113,
        {
            "authid":"OL3AeppwDLXiAAPbqm9IVhnw",
            "authrole": "anonymous",
            "authmethod": "anonymous",
            "roles": {
                "broker": {
                    "features": {
                        "subscription_meta_api": true
                    }
                },
                "dealer": {
                    "features": {
                    }
                }
            }
        }
    ]

      SubscriptionDetails :=
      {
          "id": subscription|id,
          "created": time_created|iso_8601_string,
          "uri": topic|uri,
          "match": match_policy|string
      }

      SubscriptionLists :=
      {
          "exact": subscription_ids|list,
          "prefix": subscription_ids|list,
          "wildcard": subscription_ids|list
      }

      SubscriptionDetails :=
      {
          "id": subscription|id,
          "created": time_created|iso_8601_string,
          "uri": topic|uri,
          "match": match_policy|string
      }

3.1. Progressive Call Results

A procedure implemented by a Callee and registered at a Dealer may produce progressive results. Progressive results can e.g. be used to return partial results for long-running operations, or to chunk the transmission of larger results sets.¶

Feature Announcement¶

Support for this advanced feature MUST be announced by Callers (role := "caller"), Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.
         progressive_call_results|bool := true

Additionally, Callees and Dealers MUST support Call Canceling, which is required for canceling progressive results if the original Caller leaves the realm. If a Callee supports Progressive Call Results, but not Call Canceling, then the Dealer disregards the Callees Progressive Call Results feature.¶

Message Flow¶

The message flow for progressive results involves:¶

 ,------.           ,------.          ,------.
 |Caller|           |Dealer|          |Callee|
 `--+---'           `--+---'          `--+---'
    |       CALL       |                 |
    | ----------------->                 |
    |                  |                 |
    |                  |    INVOCATION   |
    |                  | ---------------->
    |                  |                 |
    |                  | YIELD (progress)|
    |                  | <----------------
    |                  |                 |
    | RESULT (progress)|                 |
    | <-----------------                 |
    |                  |                 |
    |                  | YIELD (progress)|
    |                  | <----------------
    |                  |                 |
    | RESULT (progress)|                 |
    | <-----------------                 |
    |                  |                 |
    |                  |                 |
    |       ...        |       ...       |
    |                  |                 |
    |                  |  YIELD or ERROR |
    |                  | <----------------
    |                  |                 |
    |  RESULT or ERROR |                 |
    | <-----------------                 |
 ,--+---.           ,--+---.          ,--+---.
 |Caller|           |Dealer|          |Callee|
 `------'           `------'          `------'

A Caller indicates its willingness to receive progressive results by setting¶

    CALL.Options.receive_progress|bool := true

Example. Caller-to-Dealer CALL¶

    [
        48,
        77133,
        {
            "receive_progress": true
        },
        "com.myapp.compute_revenue",
        [2010, 2011, 2012]
    ]

If the Callee supports Progressive Call Results, the Dealer will forward the Caller's willingness to receive progressive results by setting¶

    INVOCATION.Details.receive_progress|bool := true

Example. Dealer-to-Callee INVOCATION¶

    [
        68,
        87683,
        324,
        {
            "receive_progress": true
        },
        [2010, 2011, 2012]
    ]

An endpoint implementing the procedure produces progressive results by sending YIELD messages to the Dealer with¶

    YIELD.Options.progress|bool := true

Example. Callee-to-Dealer progressive YIELDs¶

    [
        70,
        87683,
        {
            "progress": true
        },
        ["Y2010", 120]
    ]

    [
        70,
        87683,
        {
            "progress": true
        },
        ["Y2011", 205]
    ]

Upon receiving an YIELD message from a Callee with YIELD.Options.progress == true (for a call that is still ongoing), the Dealer will immediately send a RESULT message to the original Caller with¶

    RESULT.Details.progress|bool := true

Example. Dealer-to-Caller progressive RESULTs¶

    [
        50,
        77133,
        {
            "progress": true
        },
        ["Y2010", 120]
    ]

    [
        50,
        77133,
        {
            "progress": true
        },
        ["Y2011", 205]
    ]

and so on...¶

An invocation MUST always end in either a normal RESULT or ERROR message being sent by the Callee and received by the Dealer.¶

Example. Callee-to-Dealer final YIELD¶

    [
        70,
        87683,
        {},
        ["Total", 490]
    ]

Example. Callee-to-Dealer final ERROR¶

    [
        8,
        68,
        87683,
        {},
        "com.myapp.invalid_revenue_year",
        [1830]
    ]

A call MUST always end in either a normal RESULT or ERROR message being sent by the Dealer and received by the Caller.¶

Example. Dealer-to-Caller final RESULT¶

    [
        50,
        77133,
        {},
        ["Total", 490]
    ]

Example. Dealer-to-Caller final ERROR¶

    [
        8,
        68,
        77133,
        {},
        "com.myapp.invalid_revenue_year",
        [1830]
    ]

In other words: YIELD with YIELD.Options.progress == true and RESULT with RESULT.Details.progress == true messages may only be sent during a call or invocation is still ongoing.¶

The final YIELD and final RESULT may also be empty, e.g. when all actual results have already been transmitted in progressive result messages.¶

Example. Callee-to-Dealer YIELDs¶

    [70, 87683, {"progress": true}, ["Y2010", 120]]
    [70, 87683, {"progress": true}, ["Y2011", 205]]
     ...
    [70, 87683, {"progress": true}, ["Total", 490]]
    [70, 87683, {}]

Example. Dealer-to-Caller RESULTs¶

    [50, 77133, {"progress": true}, ["Y2010", 120]]
    [50, 77133, {"progress": true}, ["Y2011", 205]]
     ...
    [50, 77133, {"progress": true}, ["Total", 490]]
    [50, 77133, {}]

The progressive YIELD and progressive RESULT may also be empty, e.g. when those messages are only used to signal that the procedure is still running and working, and the actual result is completely delivered in the final YIELD and RESULT:¶

Example. Callee-to-Dealer YIELDs¶

    [70, 87683, {"progress": true}]
    [70, 87683, {"progress": true}]
    ...
    [70, 87683, {}, [["Y2010", 120], ["Y2011", 205], ...,
        ["Total", 490]]]

Example. Dealer-to-Caller RESULTs¶

    [50, 77133, {"progress": true}]
    [50, 77133, {"progress": true}]
    ...
    [50, 77133, {}, [["Y2010", 120], ["Y2011", 205], ...,
        ["Total", 490]]]

Note that intermediate, progressive results and/or the final result MAY have different structure. The WAMP peer implementation is responsible for mapping everything into a form suitable for consumption in the host language.¶

Example. Callee-to-Dealer YIELDs¶

    [70, 87683, {"progress": true}, ["partial 1", 10]]
    [70, 87683, {"progress": true}, [], {"foo": 10,
        "bar": "partial 1"}]
     ...
    [70, 87683, {}, [1, 2, 3], {"moo": "hello"}]

Example. Dealer-to-Caller RESULTs¶

    [50, 77133, {"progress": true}, ["partial 1", 10]]
    [50, 77133, {"progress": true}, [], {"foo": 10,
        "bar": "partial 1"}]
     ...
    [50, 77133, {}, [1, 2, 3], {"moo": "hello"}]

Even if a Caller has indicated its expectation to receive progressive results by setting CALL.Options.receive_progress|bool := true, a Callee is not required to produce progressive results. CALL.Options.receive_progress and INVOCATION.Details.receive_progress are simply indications that the Caller is prepared to process progressive results, should there be any produced. In other words, Callees are free to ignore such receive_progress hints at any time.¶

Caller Leaving¶

The Dealer's behavior for when a Caller leaves or disconnects during a progressive results call shall be the same as in a basic, non-progressive call. That is, the Dealer sends an INTERRUPT to the Callee with mode="killnowait". See Caller Leaving During RPC Invocation under the Basic Profile.¶

 ,------.           ,------.          ,------.
 |Caller|           |Dealer|          |Callee|
 `--+---'           `--+---'          `--+---'
    |       CALL       |                 |
    | ----------------->                 |
    |                  |    INVOCATION   |
    |                  | ---------------->
    |                  |                 |
    |                  | YIELD (progress)|
    |                  | <----------------
    |                  |                 |
    | RESULT (progress)|                 |
    | <-----------------                 |
 ,--+---.              |                 |
 |Caller|              |                 |
 `------'              |    INTERRUPT    |
  (gone)               | ---------------->
                       |                 |
                    ,--+---.          ,--+---.
                    |Dealer|          |Callee|
                    `------'          `------'

Such cancellation when the caller leaves addresses a potential security vulnerability: In cases where progressive results are used to stream data to Callers, and network connectivity is unreliable, Callers may often get disconnected in the middle of receiving such progressive results. Without the mandated cancellation behavior, recurring connect-call-disconnect cycles by a Caller would result in a rapidly growing backlog of unprocessed streaming results, overloading the router and further degrading network connectivity.¶

Callee Leaving¶

The Dealer's behavior for when a Callee leaves or disconnects during a progressive results call shall be the same as in a basic, non-progressive call. That is, the Dealer sends an ERROR message to the Caller with the wamp.error.canceled URI. See Callee Leaving During an RPC Invocation under the Basic Profile.¶

 ,------.           ,------.          ,------.
 |Caller|           |Dealer|          |Callee|
 `--+---'           `--+---'          `--+---'
    |        CALL      |                 |
    | ----------------->                 |
    |                  |    INVOCATION   |
    |                  | ---------------->
    |                  |                 |
    |                  | YIELD (progress)|
    |                  | <----------------
    |                  |                 |
    | RESULT (progress)|                 |
    | <----------------|                 |
    |                  |              ,--+---.
    |                  |              |Callee|
    |                  |              `------'
    |      ERROR       |               (gone)
    | <--------------- |
    |                  |
 ,--+---.           ,--+---.
 |Caller|           |Dealer|
 `------'           `------'

Ignoring Requests for Progressive Call Results¶

A Callee that does not support progressive results SHOULD ignore any INVOCATION.Details.receive_progress flag.¶

A Callee that supports progressive results, but does not support call canceling is considered by the Dealer to not support progressive results.¶

Timeouts¶

When the Call Timeouts feature is used in combination with Progressive Call Results, the CALL.Options.timeout|integer option shall represent the time limit between the initial call and the first result, and between results thereafter.¶

For Dealer-initiated timeouts, this corresponds to - the time between receipt of the CALL message and receipt of the first YIELD message, and, - the time between received YIELD messages thereafter.¶

For Callee-initiated timeouts, this corresponds to - the time between receipt of the INVOCATION message and acquisition of the first result, and, - the time between acquisition of successive results thereafter.¶

Note that for progressive results, the timeout value does not correspond to the duration of the complete call from initiation to the final result. The rationale for this is that it would be unfeasible to compute a reasonable timeout value for a call having a non-deterministic number of progressive results.¶

3.2. Progressive Call Invocations

A Caller may issue a call having progressive invocations. This can be useful in a few cases:¶

• Payload is too big to send it whole in one request, e.g., uploading a file.¶
• Long-term data transfer that needs to be consumed early, such as a media stream.¶
• RPC is called too often and overall processing can be optimized: avoid the need to generate a new id for requests, initiate data structures for a new call, etc.¶

In such cases, a procedure implemented by a Callee and registered at a Dealer may be made to receive progressive call invocations, where the Callee may start processing the incoming data without awaiting the entire set of payload chunks.¶

Feature Announcement¶

Support for this advanced feature MUST be announced by Callers (role := "caller"), Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.progressive_call_invocations|bool := true

Progressive call invocations can work only if all three peers support and announce this feature. In addition, Callees MUST announce support of the Call Cancelling feature via¶

    HELLO.Details.roles.callee.features.call_cancelling|bool := true

As a consequence, Dealers MUST also announce support of the Call Cancelling feature via¶

    WELCOME.Details.roles.dealer.features.call_cancelling|bool := true

The following cases, where a Caller sends a CALL message with progress := true, MUST be treated as protocol errors with the underlying WAMP sessions being aborted:¶

• The Caller did not announce the progressive call invocations feature during the HELLO handshake.¶
• The Dealer did not announce the progressive call invocations feature during the HELLO handshake.¶

Otherwise, in cases where the Caller sends a CALL message with progress := true but the Callee does not support progressive call invocations or call cancelling, the call MUST be treated as an application error with the Dealer responding to the Caller with the wamp.error.feature_not_supported error message.¶

Message Flow¶

The message flow for a progressive call when a Callee waits for all chunks before processing and sending a single result:¶

 ,------.                  ,------.                 ,------.
 |Caller|                  |Dealer|                 |Callee|
 `--+---'                  `--+---'                 `--+---'
    |     CALL (progress)     |                        |
    | ----------------------> |                        |
    |                         | INVOCATION (progress)  |
    |                         | ---------------------->|
    |     CALL (progress)     |                        |
    | ----------------------->|                        |
    |                         | INVOCATION (progress)  |
    |                         | ---------------------->|
    |                         |                        |
    |           ...           |          ...           |
    |                         |                        |
    |     CALL (final)        |                        |
    | ----------------------->|                        |
    |                         |   INVOCATION (final)   |
    |                         | ---------------------->|
    |                         |                        |
    |                         | YIELD (final) or ERROR |
    |                         | <----------------------|
    |                         |                        |
    | RESULT (final) or ERROR |                        |
    | <-----------------------|                        |
 ,--+---.                  ,--+---.                 ,--+---.
 |Caller|                  |Dealer|                 |Callee|
 `------'                  `------'                 `------'

As a progressive call chunks are part of the same overall call, the Caller must send the same Request|id for every CALL and the Dealer must also use the same Request|id with every INVOCATION to the Callee.¶

A Caller indicates its willingness to issue a progressive call by setting¶

    CALL.Options.progress|bool := true

Example. Caller-to-Dealer CALL¶

    [
        48,
        77245,
        {
            "progress": true
        },
        "com.myapp.get_country_by_coords",
        [50.450001, 30.523333]
    ]

If the Callee supports progressive call invocations, the Dealer shall forward the Caller's willingness to send progressive call invocations by setting¶

    INVOCATION.Details.progress|bool := true

Example. Dealer-to-Callee INVOCATION¶

    [
        68,
        35224,
        379,
        {
            "progress": true
        },
        [50.450001, 30.523333]
    ]

A call invocation MUST always end in a normal CALL without the "progress": true option, or explicitly set "progress": false which is the default.¶

Progressive Call Invocations and Shared Registration¶

RPCs can have a multiple registrations (see Shared Registration feature) with different <invocation_policies>. However, allowing progressive CALL messages to be routed to different Callees would lead to unexpected results. To prevent this the Dealer MUST make a first INVOCATION based on <invocation_policy> and then route all subsequent progressive calls to the same Callee.¶

Caller Leaving¶

The Dealer's behavior for when a Caller leaves or disconnects during a call with progressive invocations shall be the same as in a basic, non-progressive call. That is, the Dealer sends an INTERRUPT to the Callee with mode="killnowait". See Caller Leaving During RPC Invocation under the Basic Profile.¶

 ,------.            ,------.                 ,------.
 |Caller|            |Dealer|                 |Callee|
 `--+---'            `--+---'                 `--+---'
    |  CALL (progress)  |                        |
    | ----------------->|                        |
    |                   | INVOCATION (progress)  |
    |                   | ---------------------->|
    |  CALL (progress)  |                        |
    | ----------------->|                        |
    |                   | INVOCATION (progress)  |
    |                   | ---------------------->|
 ,--+---.               |                        |
 |Caller|               |                        |
 `------'               |                        |
  (gone)                |                        |
                        |       INTERRUPT        |
                        | ---------------------->|
                        |                        |
                     ,--+---.                 ,--+---.
                     |Dealer|                 |Callee|
                     `------'                 `------'

As in progressive call results, such cancellation when the caller leaves addresses a potential security vulnerability: In cases where progressive call invocations are used to stream data from a Caller, and network connectivity is unreliable, the Caller may often get disconnected in the middle of sending progressive data. This can lead to unneeded memory consumption for the Dealer and Callee, due to the need to store temporary metadata about ongoing calls.¶

Callee Leaving¶

The Dealer's behavior for when a Callee leaves or disconnects during a call with progressive invocations shall be the same as in a basic, non-progressive call. That is, the Dealer sends an ERROR message to the Caller with the wamp.error.canceled URI. See Callee Leaving During an RPC Invocation under the Basic Profile.¶

 ,------.           ,------.                ,------.
 |Caller|           |Dealer|                |Callee|
 `--+---'           `--+---'                `--+---'
    |  CALL (progress) |                       |
    | ----------------->                       |
    |                  | INVOCATION (progress) |
    |                  | ---------------------->
    |                  |                       |
    |                  |                       |
    |                  |                    ,--+---.
    |                  |                    |Callee|
    |      ERROR       |                    `------'
    | <--------------- |                     (gone)
    |                  |
 ,--+---.           ,--+---.
 |Caller|           |Dealer|
 `------'           `------'

Continuations on Completed Calls¶

A call with progressive invocations is considered completed by the Dealer when the latter receives a correlated final YIELD or ERROR message from the Callee, or when the Callee leaves the realm.¶

Due to network delays, the Caller may be unaware that the call is completed by time it sends another progressive CALL continuation.¶

When a Dealer receives a CALL under the following conditions:¶

• the Dealer supports Progressive Call Invocations,¶
• the CALL request ID does not correspond to a new call request, and,¶
• the CALL request ID does not match any RPC invocation in progress,¶

then it MUST ignore and discard that CALL message without any further correlated response to the Caller. The rationale for this is that the Caller will eventually receive a correlated RESULT or ERROR message from the previous call completion and will be able to handle the call completion accordingly.¶

The sequence diagram below illustrates this sitation, where the Network actor models network delay.¶

 ,------.     ,-------.      ,------.      ,------.
 |Caller|     |Network|      |Dealer|      |Callee|
 `--+---'     `---+---'      `--+---'      `--+---'
    |  CALL #123  |             |             |
    | (progress)  |             |             |
    | ------------>  CALL #123  |             |
    |             | (progress)  |             |
    |             | ------------>  INVOCATION |
    |             |             |  (progress) |
    |             |             | ------------>
    |  CALL #123  |             |             |
    | (progress)  |             |    ERROR    |
    | ------------>             | <-----------|
    |             |    ERROR    |             |
    |             | <-----------|             |
    |             | ,---------. |             |
    |             | |  Call   | |             |
    |             | |Completed| |             |
    |             | `---------' |             |
    |             |             |             |
    |             |  CALL #123  |             |
    |             | (progress)  |             |
    |             | ------------>             |
    |             | ,---------. |             |
    |             | | Ignored | |             |
    |             | `---------' |             |
    |    ERROR    |             |             |
    | <-----------|             |             |
    |             |             |             |
 ,--+---.     ,---+---.      ,--+---.    ,--+---.
 |Caller|     |Network|      |Dealer|    |Callee|
 `------'     `-------'      `------'    `------'

From the Callee's perspective, a call with progressive invocations is considered completed when the Callee sends a correlated final YIELD or ERROR message.¶

Due to network delays, the Dealer may be unaware that the call is completed by time it sends another progressive INVOCATION.¶

When a Callee receives an INVOCATION under the following conditions:¶

• the Callee supports Progressive Call Invocations,¶
• the INVOCATION request ID does not correspond to a new call request, and,¶
• the INVOCATION request ID does not match any RPC invocation in progress,¶

then it MUST ignore and discard that INVOCATION message without any further correlated response to the Dealer. The rationale for this is that the Dealer will eventually receive a correlated YIELD or ERROR message from the Callee and then send a correlated RESULT or ERROR message to the Caller, thus the Caller and the Dealer will both be able to handle the call completion accordingly.¶

The sequence diagram below illustrates this sitation, where the Network actor models network delay.¶

 ,------.     ,------.        ,-------.         ,------.
 |Caller|     |Dealer|        |Network|         |Callee|
 `--+---'     `--+---'        `---+---'         `--+---'
    | CALL #123  |                |                |
    | (progres)  |                |                |
    | ----------->                |                |
    |            | INVOCATION #42 |                |
    |            | (progress)     |                |
    |            | --------------->                |
    |            |                | INVOCATION #42 |
    |            |                | (progress)     |
    |            |                | --------------->
    | CALL #123  |                |                |
    | (progress) |                |     ERROR      |
    | ----------->                | <--------------|
    |            | INVOCATION #42 |                |
    |            | (progress)     |                |
    |            | --------------->                |
    |            |                | INVOCATION #42 |
    |            |                | (progress)     |
    |            |     ERROR      | --------------->
    |            | <--------------|   ,-------.    |
    |    ERROR   |                |   |Ignored|    |
    | <----------|                |   `---+---'    |
    |            |                |                |
 ,--+---.     ,--+---.        ,---+---.       ,--+---.
 |Caller|     |Dealer|        |Network|       |Callee|
 `------'     `------'        `-------'       `------'

Verification of CALL Request IDs¶

When sending a CALL that continues a progressive call, its request ID is the same as the CALL that initiated the progressive call invocation. Therefore, when progressive call invocations are enabled, request IDs from CALL messages may not appear sequential. For example:¶

1. [CALL, 1, {"progress":true}, "foo"]¶
2. [CALL, 2, {}, "bar"]¶
3. [CALL, 1, {}, "foo"] (OK, continues CALL request #1)¶

The requirement for CALL request IDs to be sequential session scope (see Protocol Violations) must therefore only apply to new RPC transactions:¶

1. [CALL, 1, {"progress":true}, "foo"]¶
2. [CALL, 2, {}, "bar"]¶
3. [CALL, 4, {}, "baz"] (protocol violation, request ID 3 expected)¶

Let us define watermark as the maximum valid request ID of all received CALL messages during a Dealer's run time.¶

Let us also define continuation candiate as a CALL with a request ID that is equal to or less than the watermark.¶

When a Dealer receives a CALL with a request ID that is exactly one above the watermark, then it shall be considered a new RPC transaction, and the requirement for sequential session scope IDs is verified.¶

When a Dealer receives a CALL with a request ID that is greater than one above the watermark, then this corresponds to a gap in the session scope ID sequence and MUST always be treated as a protocol violation.¶

When a Dealer receives a CALL with a request ID that is equal to or less than the watermark, then it is considered as a continuation candidate for a progressive invocation transfer.¶

As discussed in the previous section, a Caller may be unaware that a progressive invocation transfer is completed while sending a CALL continuation for that progressive invocation. Therefore, the Dealer cannot simply just check against progressive transfers in progress when verifying the validity of continuation candidates. It must also consider past progressive transfers that have been completed.¶

In order to validate the request ID of continuation candidates, it is suggested that a Dealer maintain a table of request IDs of completed progressive invocation transfers, where each entry is kept for a limited grace period. When a Dealer receives a continuation candidate with a request ID that is not in that table, nor in the list of active progressive invocations, then it is considered a protocol violation. Care must be taken in choosing the grace period: too short and data races can occur with slow networks, too long and memory usage of the table may become excessive when frequent progressive calls are made.¶

Due to resource constraints, it may not be desireable to implement such a grace period table, so Dealers MAY instead discard continuation candidates with request IDs that cannot be found in the list of active progressive invocation transfers.¶

The following pseudocode summarizes the algorithm for verifying CALL request IDs when progressive call invocations are enabled:¶

if (request_id == watermark + 1)
    watermark = watermak + 1
    initiate_new_call()
else if (request_id > watermark + 1)
    // Gap in request IDs
    abort_session("wamp.error.protocol_violation")
else
    // Continuation candidate
    if (active_call_records.contains(request_id, procedure_uri))
        record = active_call_records.at(request_id)
        if (record.is_progressive_invocation_call())
            continue_call()
        else
            abort_session("wamp.error.protocol_violation")
        endif
    else if (strict_request_id_verification_enabled)
        if (grace_period_table.contains(request_id, procedure_uri))
            discard_call()
        else
            abort_session("wamp.error.protocol_violation")
        endif
    else
        discard_call()
    endif
endif

Ignoring Progressive Call Invocations¶

Unlike some other advanced features, a Callee cannot be unaware of progressive call invocations. Therefore, if a Callee doesn't support this feature, the Dealer MUST respond to the Caller with an wamp.error.feature_not_supported error message.¶

A Callee that supports progressive call invocations, but does not support call canceling, shall be considered by the Dealer as not supporting progressive call invocations.¶

Progressive Call Invocations with Progressive Call Results¶

Progressive Call Invocations may be used in conjunction with Progressive Call Results if the Caller, Dealer, and Callee all support both features. This allows the Callee to start sending partial results back to the Caller after receiving one or more initial payload chunks. Efficient two-way streams between a Caller and Callee can be implemented this way.¶

The following message flow illustrates a call using progressive call invocations when a Callee starts sending progressive call results immediately. Note that YIELD messages don't need to be matched with CALL/INVOCATION messages. For example, the caller can send a few CALL messages before starting to receive RESULT messages; they do not need to be matched pairs.¶

 ,------.                  ,------.                 ,------.
 |Caller|                  |Dealer|                 |Callee|
 `--+---'                  `--+---'                 `--+---'
    |     CALL (progress)     |                        |
    |------------------------>|                        |
    |                         | INVOCATION (progress)  |
    |                         |----------------------->|
    |                         |                        |
    |                         |   YIELD (progress)     |
    |                         |<-----------------------|
    |                         |                        |
    |   RESULT (progress)     |                        |
    |<------------------------|                        |
    |                         |                        |
    |    CALL (progress)      |                        |
    |------------------------>|                        |
    |                         | INVOCATION (progress)  |
    |                         |----------------------->|
    |                         |                        |
    |    CALL (progress)      |                        |
    |------------------------>|                        |
    |                         | INVOCATION (progress)  |
    |                         |----------------------->|
    |                         |    YIELD (progress)    |
    |                         |<-----------------------|
    |                         |                        |
    |   RESULT (progress)     |                        |
    |<------------------------|                        |
    |                         |                        |
    |                         |    YIELD (progress)    |
    |                         |<-----------------------|
    |                         |                        |
    |   RESULT (progress)     |                        |
    |<------------------------|                        |
    |                         |                        |
    |          ...            |          ...           |
    |                         |                        |
    |      CALL (final)       |                        |
    |------------------------>|                        |
    |                         |   INVOCATION (final)   |
    |                         |----------------------->|
    |                         |                        |
    |                         | YIELD (final) or ERROR |
    |                         |<-----------------------|
    |                         |                        |
    | RESULT (final) or ERROR |                        |
    |<------------------------|                        |
 ,--+---.                  ,--+---.                 ,--+---.
 |Caller|                  |Dealer|                 |Callee|
 `------'                  `------'                 `------'

Because they are part of the same call operation, the request ID is the same in all CALL, INVOCATION, YIELD, and ERROR messages in the above exchange.¶

Freezing of Options in Progressive Call Invocations¶

Except for progress, items in the Options dictionary of the initiating progressive CALL shall be effective for the entirety of the progressive call request. Only the progress option shall be considered by the Dealer in subsequent progressive call invocations (within the same overall request). Except for progress, items in the Details dictionary of corresponding INVOCATION messages shall be based on the initiating progressive CALL only.¶

For example, if disclose_me=true was specified in the initiating progressive call, all subsequent progressive call invocations (within the same call) shall be considered by the Dealer to implictly have disclose_me=true as well. That is, all INVOCATION messages associated with the overall request shall contain caller identify information.¶

Any option besides progress SHOULD be omitted altogether by the Caller in subsequent progressive call invocations. Not having to repeat (and not being able to change) options is more in tune with the concept of a media stream where options are set up initially, and the source (Caller) only needs to keep uploading more data thereafter.¶

In subsequent call invocations:¶

• Dealers and Callees MUST ignore any option except for progress¶
• Dealers SHOULD NOT propagate any option passed by the Caller, except for progress¶

Dealers and Callees are responsible for remembering the options of the initiating progressive CALL.¶

For reference, here is a list of options that are frozen upon the initial progressive call invocations:¶

• CALL.Options.disclose_me|bool¶
• CALL.Options.ppt_cipher|string¶
• CALL.Options.ppt_keyid|string¶
• CALL.Options.ppt_scheme|string¶
• CALL.Options.ppt_serializer|string¶
• CALL.Options.receive_progress|bool¶
• CALL.Options.rkey¶
• CALL.Options.runmode|string¶
• CALL.Options.timeout|integer¶

These rules concerning progressive call invocation options also apply to custom options that are not part of this specification.¶

3.3. Call Timeouts

The Call Timeouts feature allows for automatic cancellation of a remote procedure call by the Dealer or Callee after a specified time duration.¶

A Caller specifies a timeout by providing¶

    CALL.Options.timeout|integer

in milliseconds. Automatic call timeouts are deactivated if there is no timeout option, or if its value is 0.¶

Dealer-Initiated Timeouts¶

If the Callee does not support Call Timeouts, a Dealer supporting this feature MUST start a timeout timer upon receiving a CALL message with a timeout option. The message flow for call timeouts is identical to Call Canceling, except that there is no CANCEL message that originates from the Caller. The cancellation mode is implicitly killnowait if the Callee supports call cancellation, otherwise the cancellation mode is skip.¶

The error message that is returned to the Caller MUST use wamp.error.timeout as the reason URI.¶

Callee-Initiated Timeouts¶

If the Callee supports Call Timeouts, the Dealer MAY propagate the CALL.Options.timeout|integer option via the INVOCATION message and allow the Callee to handle the timeout logic. If the operation times out, the Callee MUST return an ERROR message with wamp.error.timeout as the reason URI.¶

Callees wanting to handle the timeout logic MAY specify this intention via the REGISTER.Options.forward_timeout|boolean option. The Dealer, upon receiving a CALL with the timeout option set, checks if the matching RPC registration had the forward_timeout option set, then accordingly either forwards the timeout value or handles the timeout logic locally without forwarding the timeout value.¶

Dealers MAY choose to override the REGISTER.Options.forward_timeout|boolean option based on router configuration. For example, if a Dealer is resource-constrained and does not wish to maintain a queue of pending call timeouts, it may decide to always forward the CALL timeout option to Callees.¶

Caller-Initiated Timeouts¶

Callers may run their own timeout timer and send a CANCEL message upon timeout. This is permitted if the Dealer supports Call Canceling and is not considered to be a usage of the Call Timeouts feature.¶

Feature Announcement¶

Support for this feature MUST be announced by Dealers (role := "dealer") and MAY be announced by Callees (role := "callee") via¶

    HELLO.Details.roles.<role>.features.call_timeout|bool := true

If a Callee does not support Call Timeouts, it may optionally announce support for Call Cancellation via¶

    HELLO.Details.roles.<role>.features.call_canceling|bool := true

3.4. Call Canceling

A Caller might want to actively cancel a call that was issued, but not has yet returned. An example where this is useful could be a user triggering a long running operation and later changing his mind or no longer willing to wait.¶

Feature Announcement¶

Support for this feature MUST be announced by Callers (role := "caller"), Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.call_canceling|bool := true

Message Flow¶

The message flow between Callers, a Dealer and Callees for canceling remote procedure calls involves the following messages:¶

• CANCEL¶
• INTERRUPT¶
• ERROR¶

A call may be canceled at the Callee or at the Dealer side. Cancellation behaves differently depending on the mode:¶

• skip: The pending call is canceled and ERROR is sent immediately back to the caller. No INTERRUPT is sent to the callee and the result is discarded when received.¶
• kill: INTERRUPT is sent to the callee, but ERROR is not returned to the caller until after the callee has responded to the canceled call. In this case the caller may receive RESULT or ERROR depending whether the callee finishes processing the invocation or the interrupt first.¶
• killnowait: The pending call is canceled and ERROR is sent immediately back to the caller. INTERRUPT is sent to the callee and any response to the invocation or interrupt from the callee is discarded when received.¶

If the callee does not support call canceling, then behavior is skip.¶

Message flow during call canceling when Callee supports this feature and mode is kill¶

    ,------.          ,------.          ,------.
    |Caller|          |Dealer|          |Callee|
    `--+---'          `--+---'          `--+---'
       |       CALL      |                 |
       | ---------------->                 |
       |                 |                 |
       |                 |    INVOCATION   |
       |                 | ---------------->
       |                 |                 |
       |      CANCEL     |                 |
       | ---------------->                 |
       |                 |                 |
       |                 |    INTERRUPT    |
       |                 | ---------------->
       |                 |                 |
       |                 |      ERROR      |
       |                 | <----------------
       |                 |                 |
       |      ERROR      |                 |
       | <----------------                 |
    ,--+---.          ,--+---.          ,--+---.
    |Caller|          |Dealer|          |Callee|
    `------'          `------'          `------'

Message flow during call canceling when Callee does not support this feature or mode is skip¶

    ,------.          ,------.            ,------.
    |Caller|          |Dealer|            |Callee|
    `--+---'          `--+---'            `--+---'
       |       CALL      |                   |
       | ---------------->                   |
       |                 |                   |
       |                 |    INVOCATION     |
       |                 | ----------------> |
       |                 |                   |
       |      CANCEL     |                   |
       | ---------------->                   |
       |                 |                   |
       |      ERROR      |                   |
       | <----------------                   |
       |                 |                   |
       |                 | RESULT (skipped)  |
       |                 | <---------------- |
       |                 |                   |
       |                 | or ERROR (skipped)|
       |                 | <-----------------
    ,--+---.          ,--+---.            ,--+---.
    |Caller|          |Dealer|            |Callee|
    `------'          `------'            `------'

Message flow during call canceling when Callee supports this feature and mode is killnowait¶

    ,------.          ,------.          ,------.
    |Caller|          |Dealer|          |Callee|
    `--+---'          `--+---'          `--+---'
       |       CALL      |                 |
       | ---------------->                 |
       |                 |                 |
       |                 |    INVOCATION   |
       |                 | ---------------->
       |                 |                 |
       |      CANCEL     |                 |
       | ---------------->                 |
       |                 |                 |
       |      ERROR      |                 |
       | <----------------                 |
       |                 |    INTERRUPT    |
       |                 | ---------------->
       |                 |                 |
    ,--+---.          ,--+---.          ,--+---.
    |Caller|          |Dealer|          |Callee|
    `------'          `------'          `------'

A Caller cancels a remote procedure call initiated (but not yet finished) by sending a CANCEL message to the Dealer:¶

    [CANCEL, CALL.Request|id, Options|dict]

A Dealer cancels an invocation of an endpoint initiated (but not yet finished) by sending a INTERRUPT message to the Callee:¶

    [INTERRUPT, INVOCATION.Request|id, Options|dict]

Options:¶

    CANCEL.Options.mode|string == "skip" | "kill" | "killnowait"

Ignoring Results after Cancel¶

After the Dealer sends an INTERRUPT when mode="killnowait", any responses from the Callee are ignored. This means that it is not necessary for the Callee to respond with an ERROR message, when mode="killnowait", since the Dealer ignores it.¶

3.5. Call Re-Routing

A CALLEE might not be able to attend to a call. This may be due to a multitude of reasons including, but not limited to:¶

• CALLEE is busy handling other requests and is not able to attend¶
• CALLEE has dependency issues which prevent it from being able to fulfil the request¶
• In a HA environment, the Callee knows that it is scheduled to be taken off the HA cluster and as such should not handle the request.¶

A unavailable response allows for automatic reroute of a call by the Dealer without the CALLER ever having to know about it.¶

When such a situation occurs, the Callee responds to a INVOCATION message with the error uri:¶

wamp.error.unavailable¶

When the Dealer receives the wamp.error.unavailable message in response to an INVOCATION, it will reroute the CALL to another registration according to the rerouting rules of the invocation_policy of the procedure, as given below.¶

Feature Announcement¶

Support for this feature MUST be announced by Callees (role := "callee") and Dealers (role := "dealer") via¶

HELLO.Details.roles.<role>.features.call_reroute|bool := true¶

Rerouting Rules¶

The Dealer MUST adhere to the invocation policy of the procedure when rerouting the CALL, while assuming that the unavailable registration virtually does not exist.¶

For different invocation policy the Dealer MUST follow:¶

Failure Scenario¶

In case all available registrations of a Procedure responds with a wamp.error.unavailable for a CALL, the Dealer MUST respond with a wamp.error.no_available_callee to the CALLER¶

3.6. Caller Identification

A Caller MAY request the disclosure of its identity (its WAMP session ID) to endpoints of a routed call via¶

    CALL.Options.disclose_me|bool := true

Example¶

    [48, 7814135, {"disclose_me": true}, "com.myapp.echo",
        ["Hello, world!"]]

If above call is issued by a Caller with WAMP session ID 3335656, the Dealer sends an INVOCATION message to Callee with the Caller's WAMP session ID in INVOCATION.Details.caller:¶

Example¶

    [68, 6131533, 9823526, {"caller": 3335656}, ["Hello, world!"]]

Note that a Dealer MAY disclose the identity of a Caller even without the Caller having explicitly requested to do so when the Dealer configuration (for the called procedure) is setup to do so.¶

Identity Information¶

When Caller disclosure is allowed for a particular CALL message, the corresponding INVOCATION message MUST contain an INVOCATION.Details.caller|integer property set to the Caller's session ID.¶

The following additional properties MAY also be included::¶

• INVOCATION.Details.caller_authid|string¶
• INVOCATION.Details.caller_authrole|string¶

Feature Announcement¶

Support for this feature MUST be announced by Callers (role := "caller"), Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.
         caller_identification|bool := true

Request Identification¶

A Dealer MAY deny a Caller's request to disclose its identity:¶

Example¶

    [8, 48, 7814135, "wamp.error.disclose_me.not_allowed"]

A Callee MAY request the disclosure of caller identity via¶

    REGISTER.Options.disclose_caller|bool := true

Example¶

    [64, 927639114088448, {"disclose_caller":true},
        "com.maypp.add2"]

With the above registration, the registered procedure is called with the caller's sessionID as part of the call details object.¶

3.7. Call Trust Levels

A Dealer may be configured to automatically assign trust levels to calls issued by Callers according to the Dealer configuration on a per-procedure basis and/or depending on the application defined role of the (authenticated) Caller.¶

A Dealer supporting trust level will provide¶

    INVOCATION.Details.trustlevel|integer

in an INVOCATION message sent to a Callee. The trustlevel 0 means lowest trust, and higher integers represent (application-defined) higher levels of trust.¶

Example¶

    [68, 6131533, 9823526, {"trustlevel": 2}, ["Hello, world!"]]

In above event, the Dealer has (by configuration and/or other information) deemed the call (and hence the invocation) to be of trustlevel 2.¶

Feature Announcement¶

Support for this feature MUST be announced by Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.call_trustlevels|bool := true

3.8. Pattern-based Registrations

By default, Callees register procedures with exact matching policy. That is a call will only be routed to a Callee by the Dealer if the procedure called (CALL.Procedure) exactly matches the endpoint registered (REGISTER.Procedure).¶

A Callee might want to register procedures based on a pattern. This can be useful to reduce the number of individual registrations to be set up or to subscribe to a open set of topics, not known beforehand by the Subscriber.¶

If the Dealer and the Callee support pattern-based registrations, this matching can happen by¶

• prefix-matching policy¶
• wildcard-matching policy¶

Feature Announcement¶

Support for this feature MUST be announced by Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.
        pattern_based_registration|bool := true

    REGISTER.Options.match|string := "prefix"

    [
        64,
        612352435,
        {
            "match": "prefix"
        },
        "com.myapp.myobject1"
    ]

    REGISTER.Options.match|string := "wildcard"

    [
        64,
        612352435,
        {
            "match": "wildcard"
        },
        "com.myapp..myprocedure1"
    ]

Registered RPCs:
    1. 'a1.b2.c3.d4.e55' (exact),
    2. 'a1.b2.c3' (prefix),
    3. 'a1.b2.c3.d4' (prefix),
    4. 'a1.b2..d4.e5',
    5. 'a1.b2.c33..e5',
    6. 'a1.b2..d4.e5..g7',
    7. 'a1.b2..d4..f6.g7'

Call request RPC URI: 'a1.b2.c3.d4.e55' →
    exact match. Use RPC 1
Call request RPC URI: 'a1.b2.c3.d98.e74' →
    no exact match, single prefix match. Use RPC 2
Call request RPC URI: 'a1.b2.c3.d4.e325' →
    no exact match, 2 prefix matches (2,3), select longest one.
    Use RPC 3
Call request RPC URI: 'a1.b2.c55.d4.e5' →
    no exact match, no prefix match, single wildcard match.
    Use RPC 4
Call request RPC URI: 'a1.b2.c33.d4.e5' →
    no exact match, no prefix match, 2 wildcard matches (4,5),
    select longest one. Use RPC 5
Call request RPC URI: 'a1.b2.c88.d4.e5.f6.g7' →
    no exact match, no prefix match, 2 wildcard matches (6,7),
    both having equal first portions (a1.b2), but RPC 6 has longer
    second portion (d4.e5). Use RPC 6
Call request RPC URI: 'a2.b2.c2.d2.e2' →
    no exact match, no prefix match, no wildcard match.
    Return wamp.error.no_such_procedure

    INVOCATION.Details.procedure

    [
        68,
        6131533,
        9823527,
        {
            "procedure": "com.myapp.procedure.proc1"
        },
        ["Hello, world!"]
    ]

3.9. Shared Registration

Feature status: alpha¶

As a default, only a single Callee may register a procedure for a URI.¶

There are use cases where more flexibility is required. As an example, for an application component with a high computing load, several instances may run, and load balancing of calls across these may be desired. As another example, in an application a second or third component providing a procedure may run, which are only to be called in case the primary component is no longer reachable (hot standby).¶

When shared registrations are supported, then the first Callee to register a procedure for a particular URI MAY determine that additional registrations for this URI are allowed, and what Invocation Rules to apply in case such additional registrations are made.¶

This is done through setting¶

    REGISTER.Options.invoke|string := <invocation_policy>

where <invocation_policy> is one of¶

• 'single'¶
• 'roundrobin'¶
• 'random'¶
• 'first'¶
• 'last'¶

If the option is not set, 'single' is applied as a default.¶

With 'single', the Dealer MUST fail all subsequent attempts to register a procedure for the URI while the registration remains in existence.¶

With the other values, the Dealer MUST fail all subsequent attempts to register a procedure for the URI where the value for this option does not match that of the initial registration.¶

Feature Announcement¶

Support for this feature MUST be announced by Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.
        shared_registration|bool := true

3.10. Sharded Registration

Feature status: sketch¶

Sharded Registrations are intended to allow calling a procedure which is offered by a sharded database, by routing the call to a single shard.¶

Feature Announcement¶

Support for this feature MUST be announced by Callers (role := "caller"), Callees (role := "callee") and Dealers (role := "dealer") via¶

HELLO.Details.roles.<role>.features.sharded_registration|bool := true

3.11. Registration Revocation

Feature status: alpha¶

This feature allows a Dealer to actively revoke a previously granted registration. To achieve this, the existing UNREGISTERED message is extended as described below.¶

Feature Announcement¶

Support for this feature MUST be announced by Callees (role := "callee") and Dealers (role := "dealer") via¶

    HELLO.Details.roles.<role>.features.
         registration_revocation|bool := true

If the Callee does not support registration_revocation, the Dealer may still revoke a registration to support administrative functionality. In this case, the Dealer MUST NOT send an UNREGISTERED message to the Callee. The Callee MAY use the registration meta event wamp.registration.on_unregister to determine whether a session is removed from a registration.¶

Extending UNREGISTERED¶

When revoking a registration, the router has no request ID to reply to. So it's set to zero and another argument is appended to indicate which registration to revoke. Optionally, a reason why the registration was revoked is also appended.¶

    [UNREGISTERED, 0, Details|dict]

where¶

• Details.registration|bool MUST be a previously issued registration ID.¶
• Details.reason|string MAY provide a reason as to why the registration was revoked.¶

Example¶

    [67, 0, {"registration": 1293722, "reason": "moving endpoint to other callee"}]

4.1. Subscriber Black- and Whitelisting

Subscriber Black- and Whitelisting is an advanced Broker feature where a Publisher is able to restrict the set of receivers of a published event.¶

Under normal Publish & Subscriber event dispatching, a Broker will dispatch a published event to all (authorized) Subscribers other than the Publisher itself. This set of receivers can be further reduced on a per-publication basis by the Publisher using Subscriber Black- and Whitelisting.¶

The Publisher can explicitly exclude Subscribers based on WAMP sessionid, authid or authrole. This is referred to as Blacklisting.¶

A Publisher may also explicitly define a eligible list of Subscribers based on WAMP sessionid, authid or authrole. This is referred to as Whitelisting.¶

Use Cases include the following.¶

Avoiding Callers from being self-notified¶

Consider an application that exposes a procedure to update a product price. The procedure might not only actually update the product price (e.g. in a backend database), but additionally publish an event with the updated product price, so that all application components get notified actively of the new price.¶

However, the application might want to exclude the originator of the product price update (the Caller of the price update procedure) from receiving the update event - as the originator naturally already knows the new price, and might get confused when it receives an update the Caller has triggered himself.¶

The product price update procedure can use PUBLISH.Options.exclude|list[int] to exclude the Caller of the procedure.¶

Note that the product price update procedure needs to know the session ID of the Caller to be able to exclude him. For this, please see Caller Identification.¶

A similar approach can be used for other CRUD-like procedures.¶

Restricting receivers of sensitive information¶

Consider an application with users that have different authroles, such as "manager" and "staff" that publishes events with updates to "customers". The topics being published to could be structured like¶

    com.example.myapp.customer.<customer ID>

The application might want to restrict the receivers of customer updates depending on the authrole of the user. E.g. a user authenticated under authrole "manager" might be allowed to receive any kind of customer update, including personal and business sensitive information. A user under authrole "staff" might only be allowed to receive a subset of events.¶

The application can publish all customer updates to the same topic com.example.myapp.customer.<customer ID> and use PUBLISH.Options.eligible_authrole|list[string] to safely restrict the set of actual receivers as desired.¶

Feature Definition¶

A Publisher may restrict the actual receivers of an event from the set of Subscribers through the use of¶

• Blacklisting Options¶

  • PUBLISH.Options.exclude|list[int]¶
  • PUBLISH.Options.exclude_authid|list[string]¶
  • PUBLISH.Options.exclude_authrole|list[string]¶

• Whitelisting Options¶

  • PUBLISH.Options.eligible|list[int]¶
  • PUBLISH.Options.eligible_authid|list[string]¶
  • PUBLISH.Options.eligible_authrole|list[string]¶

PUBLISH.Options.exclude is a list of integers with WAMP sessionids providing an explicit list of (potential) Subscribers that won't receive a published event, even though they may be subscribed. In other words, PUBLISH.Options.exclude is a blacklist of (potential) Subscribers.¶

PUBLISH.Options.eligible is a list of integers with WAMP WAMP sessionids providing an explicit list of (potential) Subscribers that are allowed to receive a published event. In other words, PUBLISH.Options.eligible is a whitelist of (potential) Subscribers.¶

The exclude_authid, exclude_authrole, eligible_authid and eligible_authrole options work similar, but not on the basis of WAMP sessionid, but authid and authrole.¶

An (authorized) Subscriber to topic T will receive an event published to T if and only if all of the following statements hold true:¶

1. if there is an eligible attribute present, the Subscriber's sessionid is in this list¶
2. if there is an eligible_authid attribute present, the Subscriber's authid is in this list¶
3. if there is an eligible_authrole attribute present, the Subscriber's authrole is in this list¶
4. if there is an exclude attribute present, the Subscriber's sessionid is NOT in this list¶
5. if there is an exclude_authid attribute present, the Subscriber's authid is NOT in this list¶
6. if there is an exclude_authrole attribute present, the Subscriber's authrole is NOT in this list¶

For example, if both PUBLISH.Options.exclude and PUBLISH.Options.eligible are present, the Broker will dispatch events published only to Subscribers that are not explicitly excluded in PUBLISH.Options.exclude and which are explicitly eligible via PUBLISH.Options.eligible.¶

Example¶

    [
       16,
       239714735,
       {
          "exclude": [
             7891255,
             1245751
          ]
       },
       "com.myapp.mytopic1",
       [
          "Hello, world!"
       ]
    ]

The above event will get dispatched to all Subscribers of com.myapp.mytopic1, but not WAMP sessions with IDs 7891255 or 1245751 (and also not the publishing session).¶

Example¶

    [
       16,
       239714735,
       {
          "eligible": [
             7891255,
             1245751
          ]
       },
       "com.myapp.mytopic1",
       [
          "Hello, world!"
       ]
    ]

The above event will get dispatched to WAMP sessions with IDs 7891255 or 1245751 only - but only if those are actually subscribed to the topic com.myapp.mytopic1.¶

Example¶

    [
       16,
       239714735,
       {
          "eligible": [
             7891255,
             1245751,
             9912315
          ],
          "exclude": [
             7891255
          ]
       },
       "com.myapp.mytopic1",
       [
          "Hello, world!"
       ]
    ]

The above event will get dispatched to WAMP sessions with IDs 1245751 or 9912315 only, since 7891255 is excluded - but only if those are actually subscribed to the topic com.myapp.mytopic1.¶

Feature Announcement¶

Support for this feature MUST be announced by Publishers (role := "publisher") and Brokers (role := "broker") via¶

    HELLO.Details.roles.<role>.features.
        subscriber_blackwhite_listing|bool := true

4.2. Publisher Exclusion

By default, a Publisher of an event will not itself receive an event published, even when subscribed to the Topic the Publisher is publishing to. This behavior can be overridden using this feature.¶

To override the exclusion of a publisher from its own publication, the PUBLISH message must include the following option:¶

    PUBLISH.Options.exclude_me|bool

When publishing with PUBLISH.Options.exclude_me := false, the Publisher of the event will receive that event, if it is subscribed to the Topic published to.¶

Example¶

    [
        16,
        239714735,
        {
            "exclude_me": false
        },
        "com.myapp.mytopic1",
        ["Hello, world!"]
    ]

In this example, the Publisher will receive the published event, if it is subscribed to com.myapp.mytopic1.¶

Feature Announcement¶

Support for this feature MUST be announced by Publishers (role := "publisher") and Brokers (role := "broker") via¶

    HELLO.Details.roles.<role>.features.
        publisher_exclusion|bool := true

4.3. Publisher Identification

A Publisher may request the disclosure of its identity (its WAMP session ID) to receivers of a published event by setting¶

    PUBLISH.Options.disclose_me|bool := true

Example¶

    [16, 239714735, {"disclose_me": true}, "com.myapp.mytopic1",
        ["Hello, world!"]]

If above event is published by a Publisher with WAMP session ID 3335656, the Broker would send an EVENT message to Subscribers with the Publisher's WAMP session ID in EVENT.Details.publisher:¶

Example¶

    [36, 5512315355, 4429313566, {"publisher": 3335656},
        ["Hello, world!"]]

Note that a Broker may deny a Publisher's request to disclose its identity:¶

Example¶

    [8, 16, 239714735, {}, "wamp.error.option_disallowed.disclose_me"]

A Broker may also (automatically) disclose the identity of a Publisher even without the Publisher having explicitly requested to do so when the Broker configuration (for the publication topic) is set up to do so.¶

Additional Identity Information¶

When publisher disclosure is allowed for a particular PUBLISH message, the corresponding EVENT message MAY also contain the following additional properties in its Details dictionary:¶

• EVENT.Details.publisher_authid|string¶
• EVENT.Details.publisher_authrole|string¶

Feature Announcement¶

Support for this feature MUST be announced by Publishers (role := "publisher"), Brokers (role := "broker") and Subscribers (role := "subscriber") via¶

    HELLO.Details.roles.<role>.features.
        publisher_identification|bool := true

4.4. Publication Trust Levels

A Broker may be configured to automatically assign trust levels to events published by Publishers according to the Broker configuration on a per-topic basis and/or depending on the application defined role of the (authenticated) Publisher.¶

A Broker supporting trust level will provide¶

    EVENT.Details.trustlevel|integer

in an EVENT message sent to a Subscriber. The trustlevel 0 means lowest trust, and higher integers represent (application-defined) higher levels of trust.¶

Example¶

    [36, 5512315355, 4429313566, {"trustlevel": 2},
        ["Hello, world!"]]

In above event, the Broker has (by configuration and/or other information) deemed the event publication to be of trustlevel 2.¶

Feature Announcement¶

Support for this feature MUST be announced by Subscribers (role := "subscriber") and Brokers (role := "broker") via¶

    HELLO.Details.roles.<role>.features.
        publication_trustlevels|bool := true

4.5. Pattern-based Subscription

By default, Subscribers subscribe to topics with exact matching policy. That is an event will only be dispatched to a Subscriber by the Broker if the topic published to (PUBLISH.Topic) exactly matches the topic subscribed to (SUBSCRIBE.Topic).¶

A Subscriber might want to subscribe to topics based on a pattern. This can be useful to reduce the number of individual subscriptions to be set up and to subscribe to topics the Subscriber is not aware of at the time of subscription, or which do not yet exist at this time.¶

Let's review the event publication flow. When one peer decides to publish a message to a topic, it results in a PUBLISH WAMP message with fields for the Publication id, Details dictionary, and, optionally, the payload arguments.¶

A given event received by the router from a publisher via a PUBLISH message will match one or more subscriptions:¶

• zero or one exact subscription¶
• zero or more prefix subscriptions¶
• zero or more wildcard subscriptions¶

The same published event is then forwarded to subscribers for every matching subscription. Thus, a given event might be sent multiple times to the same client under different subscriptions. Every subscription instance, based on a topic URI and some options, has a unique ID. All subscribers of the same subscription are given the same subscription ID.¶

                             +----------+          +------------+        +----------+
                             |          |          |   Exact    |        |Subscriber|
                             |          |--Event-->|Subscription|---+--->|   peer   |
                             |          |          +------------+   |    +----------+
 +----------+                |          |          +------------+   |    +----------+
 |Publisher |                |  Broker  |          |  Wildcard  |   +--->|Subscriber|
 |   peer   |--Publication-->|          |--Event-->|Subscription|---+--->|   peer   |
 +----------+                |          |          +------------+   |    +----------+
                             |          |          +------------+   |    +----------+
                             |          |          |   Prefix   |   +--->|Subscriber|
                             |          |--Event-->|Subscription|------->|   peer   |
                             +----------+          +------------+        +----------+

If the Broker and the Subscriber support pattern-based subscriptions, this matching can happen by¶

• prefix-matching policy¶
• wildcard-matching policy¶

Feature Announcement¶

Support for this feature MUST be announced by Subscribers (role := "subscriber") and Brokers (role := "broker") via¶

    HELLO.Details.roles.<role>.features.
        pattern_based_subscription|bool := true

    SUBSCRIBE.Options.match|string := "prefix"

    [
        32,
        912873614,
        {
            "match": "prefix"
        },
        "com.myapp.topic.emergency"
    ]

    SUBSCRIBE.Options.match|string := "wildcard"

    [
        32,
        912873614,
        {
            "match": "wildcard"
        },
        "com.myapp..userevent"
    ]

    EVENT.Details.topic|uri

    [
        36,
        5512315355,
        4429313566,
        {
            "topic": "com.myapp.topic.emergency.category.severe"
        },
        ["Hello, world!"]
    ]

4.6. Sharded Subscription

Feature status: alpha¶

Support for this feature MUST be announced by Publishers (role := "publisher"), Subscribers (role := "subscriber") and Brokers (role := "broker") via¶

    HELLO.Details.roles.<role>.features.shareded_subscriptions|
        bool := true

Resource keys: PUBLISH.Options.rkey|string is a stable, technical resource key.¶

E.g. if your sensor has a unique serial identifier, you can use that.¶

Example¶

    [16, 239714735, {"rkey": "sn239019"}, "com.myapp.sensor.sn239019.
        temperature", [33.9]]

Node keys: SUBSCRIBE.Options.nkey|string is a stable, technical node key.¶

E.g. if your backend process runs on a dedicated host, you can use its hostname.¶

Example¶

    [32, 912873614, {"match": "wildcard", "nkey": "node23"},
        "com.myapp.sensor..temperature"]

4.7. Event History

Instead of complex QoS for message delivery, a Broker may provide Event History. With event history, a Subscriber is responsible for handling overlaps (duplicates) when it wants "exactly-once" message processing across restarts.¶

The event history may be transient, or it may be persistent where it survives Broker restarts.¶

The Broker implementation may allow for configuration of event history on a per-topic or per-topic-pattern basis. Such configuration could enable/disable the feature, set the event history storage location, set parameters for sub-features such as compression, or set the event history data retention policy.¶

Event History saves events published to discrete subscriptions, in the chronological order received by the broker. Let us examine an example.¶

Subscriptions:¶

1. Subscription to exact match 'com.mycompany.log.auth' topic¶
2. Subscription to exact match 'com.mycompany.log.basket' topic¶
3. Subscription to prefix-based 'com.mycompany.log' topic¶

Publication messages:¶

1. Publication to topic 'com.mycompany.log.auth'. Forwarded as events to subscriptions 1 and 3.¶
2. Publication to topic 'com.mycompany.log.basket'. Delivered as event to subscriptions 2 and 3.¶
3. Publication to topic 'com.mycompany.log.basket'. Delivered as events to subscriptions 2 and 3.¶
4. Publication to topic 'com.mycompany.log.basket'. Delivered as events subscriptions 2 and 3.¶
5. Publication to topic 'com.mycompany.log.checkout'. Delivered as an event to subscription 3 only.¶

Event History:¶

• Event history for subscription 1 contains publication 1 only.¶
• Event history for subscription 2 contains publications 2, 3, and 4.¶
• Event history for subscription 3 contains all publications.¶

Feature Announcement¶

A Broker that implements event history must indicate HELLO.roles.broker.features.event_history = true, must announce the role HELLO.roles.callee, and must provide the meta procedures described below.¶

Receiving Event History¶

A Caller can request message history by calling the Broker meta procedure¶

    wamp.subscription.get_events

With payload:¶

• Arguments = [subscription|id]. The subscription id for which to retrieve event history¶

• ArgumentsKw:¶

  • reverse. Boolean. Optional. Traverses events in reverse order of occurrence. The default is to traverse events in order of occurrence.¶
  • limit. Positive integer. Optional. Indicates the maximum number of events to retrieve. Can be used for pagination.¶
  • from_time. RFC3339-formatted timestamp string. Optional. Only include publications occurring at the given timestamp or after (using >= comparison).¶
  • after_time. RFC3339-formatted timestamp string. Optional. Only include publications occurring after the given timestamp (using > comparison).¶
  • before_time. RFC3339-formatted timestamp string. Optional. Only include publications occurring before the given timestamp (using < comparison).¶
  • until_time. RFC3339-formatted timestamp string. Optional. Only include publications occurring before the given timestamp including date itself (using <= comparison).¶
  • topic. WAMP URI. Optional. For pattern-based subscriptions, only include publications to the specified topic.¶
  • from_publication. Positive integer. Optional. Events in the results must have occurred at or following the event with the given publication|id (includes the event with the given publication|id in the results).¶
  • after_publication. Positive integer. Optional. Events in the results must have occurred following the event with the given publication_id (excludes the event with the given publication|id in the results). Useful for pagination: pass the publication|id attribute of the last event returned in the previous page of results when navigating in order of occurrence (reverse argument absent or false).¶
  • before_publication. Positive integer. Optional. Events in the results must have occurred previously to the event with the given publication|id (excludes the event with the given publication|id in the results). Useful for pagination: pass the publication|id attribute of the last event returned in the previous page of results when navigating in reverse order of occurrence (reverse=true).¶
  • until_publication. Positive integer. Optional. Events in the results must have occurred at or previously to the event with the given publication|id (includes the event with the given publication|id in the results).¶

It is possible to pass multiple options at the same time. In this case they will be treated as conditions with logical AND. Note that the publication|id event attribute is not ordered as it belongs to the Global scope. But since events are stored in the order they are received by the broker, it is possible to find an event with the specified publication|id and then return events including or excluding the matched one depending on the *_publication filter attributes.¶

The arguments payload field returned by the above RPC uses the same schema: an array of Event objects containing an additional timestamp string attribute in RFC3339 format. It can also be an empty array in the case where there were no publications to the specified subscription, or all events were filtered out by the specified criteria. Additional general information about the query may be returned via the argumentsKw payload field.¶

  [
    {
        "timestamp": "yyyy-MM-ddThh:mm:ss.SSSZ", // string with event date/time in RFC3339 format
        "subscription": 2342423, // The subscription ID of the event
        "publication": 32445235, // The original publication ID of the event
        "details": {},           // The original details of the event
        "args": [],              // The original list arguments payload of the event. May be ommited
        "kwargs": {}             // The original key-value arguments payload of the event. May be ommited
    }
  ]

Clients should not rely on timestamps being unique and monotonic. When events occur in quick succession, it's possible for some of them to have the same timestamp. When a router in an IoT system is deployed off-grid and is not synchronized to an NTP server, it's possible for the timestamps to jump backwards when the router's wall clock time or time zone is manually adjusted.¶

In cases where the events list is too large to send as a single RPC result, router implementations may provide additional options, such as pagination or returning progressive results.¶

As the Event History feature operates on subscription|id, there can be situations when there are not yet any subscribers to a topic of interest, but publications to the topic occur. In this situation, the Broker cannot predict that events under that topic should be stored. If the Broker implementation allows configuration on a per-topic basis, it may overcome this situations by preinitializing history-enabled topics with "dummy" subscriptions even if there are not yet any real subscribers to those topics.¶

Sometimes, a client may not be willing to subscribe to a topic just for the purpose of obtaining a subscription id. In that case a client may use other Subscriptions Meta API RPC for retrieving subscription IDs by topic URIs if the router supports it.¶

Security Aspects¶

TODO/FIXME: This part of Event History needs more discussion and clarification. But at least provides some basic information to take into account.¶

In order to request event history, a peer must be allowed to subscribe to a desired subscription first. Thus, if a peer cannot subscribe to a topic resulting in a subscription, it means that it cannot receive events history for that topic either. To sidestep this problem, a peer must be allowed to call related meta procedures for obtaining the event history as described above. Prohibited Event History meta procedure calls must fail with the wamp.error.not_authorized error URI.¶

Original publications may include additional options, such as black-white-listing that triggers special event processing. These same rules must also apply to event history requests. For example, if the original publication contains eligible_authrole = 'admin', but the request for history came from a peer with authrole = 'user', then even if user is authorized to subscribe to the topic (and thus is authorized to ask for event history), this publication must be filtered out from the results of this specific request, by the router side.¶

The black-white-listing feature also allows the filtering of event delivery on a session ID basis. In the context of event history, this can result in unexpected behaviour: session ids are generated randomly at runtime for every session establishment, so newly connected sessions asking for event history may receive events that were originally excluded, or, vice versa, may not receive expected events due to session ID mismatch. To prevent this unexpected behaviour, all events published with Options.exclude|list[int] or Options.eligible|list[int] should be ignored by the Event History mechanism and not be saved at all.¶

Finally, Event History should only filter according to attributes that do not change during the run time of the router, which are currently authrole and authid. Filtering based on ephemeral attributes like session ID – (U+2013) and perhaps other future custom attributes – (U+2013) should result in the event not being stored in the history at all, to avoid unintentional leaking of event information.¶

4.8. Event Retention

Event Retention is where a particular topic has an event associated with it which is delivered upon an opting-in client subscribing to the topic.¶

It can be used for topics that generally have single or very few Publishers notifying Subscribers of a single updating piece of data -- for example, a topic where a sensor publishes changes of temperature & humidity in a data center. It may do this every time the data changes (making the time between updates potentially very far apart), which causes an issue for new Subscribers who may need the last-known value upon connection, rather than waiting an unknown period of time until it is updated. Event Retention covers this use case by allowing the Publisher to mark a event as 'retained', bound to the topic it was sent to, which can be delivered upon a new client subscription that asks for it. It is similar to Event History, but allows the publisher to decide what the most important recent event is on the topic, even if other events are being delivered.¶

A Broker that advertises support MAY provide event retention on topics it provides. This event retention SHOULD be provided on a best-effort basis, and MUST NOT be interpreted as permanent or reliable storage by clients. This event retention is limited to one event that all subscribers would receive, and MAY include other supplemental events that have limited distribution (for example, a event published with subscriber black/whitelisting).¶

A Publisher can request storage of a new Retained Event by setting Publish.Options.retain|bool to true. Lack of the key in Publish.Options MUST be interpreted as a false value. A Broker MAY decline to provide event retention on certain topics by ignoring the Publish.Options.retain value. Brokers that allow event retention on the given topic MUST set the topic Retained Event to this if it were eligible to be published on the topic.¶

Subscribers may request access to the Retained Event by setting Subscribe.Options.get_retained|bool to true. Lack of the key in Subscribe.Options MUST be interpreted as a false value. When they opt-in to receiving the Retained Event, the Broker MUST send the Subscriber the most recent Retained Event that they would have received if they were subscribing when it was published. The Broker MUST NOT send the Subscriber a Retained Event that they would not be eligible to receive if they were subscribing when it was published. The Retained Event, as sent to the subscribing client, MUST have Event.Details.retained|bool set to true, to inform subscribers that it is not an immediately new message.¶

Feature Announcement¶

Support for this feature MUST be announced by Brokers (role := "broker") via¶

    Welcome.Details.roles.broker.features.event_retention|bool := true

4.9. Subscription Revocation

Feature status: alpha¶

This feature allows a Broker to actively revoke a previously granted subscription. To achieve this, the existing UNSUBSCRIBED message is extended as described below.¶

Feature Announcement¶

Support for this feature MUST be announced by Subscribers (role := "subscriber") and Brokers (role := "broker") via¶

    HELLO.Details.roles.<role>.features.
         subscription_revocation|bool := true

If the Subscriber does not support subscription_revocation, the Broker MAY still revoke a subscription to support administrative functionality. In this case, the Broker MUST NOT send an UNSUBSCRIBED message to the Subscriber. The Subscriber MAY use the subscription meta event wamp.subscription.on_unsubscribe to determine whether a session is removed from a subscription.¶

Extending UNSUBSCRIBED¶

When revoking a subscription, the router has no request ID to reply to. So it's set to zero and another argument is appended to indicate which subscription to revoke. Optionally, a reason why the subscription was revoked is also appended.¶

    [UNSUBSCRIBED, 0, Details|dict]

where¶

• Details.subscription|bool MUST be a previously issued subscription ID.¶
• Details.reason|string MAY provide a reason as to why the subscription was revoked.¶

Example¶

    [35, 0, {"subscription": 1293722, "reason": "no longer authorized"}]

4.10. Session Testament

When a WAMP client disconnects, or the WAMP session is destroyed, it may want to notify other subscribers or publish some fixed data. Since a client may disconnect uncleanly, this can't be done reliably by them. A Testament, however, set on the server, can be reliably sent by the Broker once either the WAMP session has detached or the client connection has been lost, and allows this functionality. It can be triggered when a Session is either detached (the client has disconnected from it, or frozen it, in the case of Session Resumption) or destroyed (when the WAMP session no longer exists on the server).¶

This allows clients that otherwise would not be able to know when other clients disconnect get a notification (for example, by using the WAMP Session Meta API) with a format the disconnected client chose.¶

Feature Announcement¶

Support for this feature MUST be announced by Dealers (role := "dealer") via¶

    HELLO.Details.roles.dealer.features.
        testament_meta_api|bool := true

Testament Meta Procedures¶

A Client can call the following procedures to set/flush Testaments:¶

• wamp.session.add_testament to add a Testament which will be published on a particular topic when the Session is detached or destroyed.¶
• wamp.session.flush_testaments to remove the Testaments for that Session, either for when it is detached or destroyed.¶

wamp.session.add_testament¶

Adds a new testament:¶

Positional arguments¶

1. topic|uri - the topic to publish the event on¶
2. args|list - positional arguments for the event¶
3. kwargs|dict - keyword arguments for the event¶

Keyword arguments¶

1. publish_options|dict - options for the event when it is published -- see Publish.Options. Not all options may be honoured (for example, acknowledge). By default, there are no options.¶
2. scope|string - When the testament should be published. Valid values are detached (when the WAMP session is detached, for example, when using Event Retention) or destroyed (when the WAMP session is finalized and destroyed on the Broker). Default MUST be destroyed.¶

wamp.session.add_testament does not return a value.¶

wamp.session.flush_testaments¶

Removes testaments for the given scope:¶

Keyword arguments¶

1. scope|string - Which set of testaments to be removed. Valid values are the same as wamp.session.add_testament, and the default MUST be destroyed.¶

wamp.session.flush_testaments does not return a value.¶

Testaments in Use¶

A Client that wishes to send some form of data when their Session ends unexpectedly or their Transport becomes lost can set a testament using the WAMP Testament Meta API, when a Router supports it. For example, a client may call add_testament (this example uses the implicit scope option of destroyed):¶

yield self.call('wamp.session.add_testament',
                'com.myapp.mytopic', ['Seeya!'], {'my_name': 'app1'})

The Router will then store this information on the WAMP Session, either in a detached or destroyed bucket, in the order they were added. A client MUST be able to set multiple testaments per-scope. If the Router does not support Session Resumption (therefore removing the distinction between a detached and destroyed session), it MUST still use these two separate buckets to allow wamp.session.flush_testaments to work.¶

When a Session is detached, the Router will inspect it for any Testaments in the detached scope, and publish them in the order that the Router received them, on the specified topic, with the specified arguments, keyword arguments, and publish options. The Router MAY ignore publish options that do not make sense for a Testament (for example, acknowledged publishes).¶

When a Session is going to be destroyed, the Router will inspect it for any Testaments in the destroyed scope, and publish them in the same way as it would for the detached scope, in the order that they were received.¶

A Router that does not allow Session Resumption MUST send detached-scope Testaments before destroyed-scope Testaments.¶

A Client can also clear testaments if the information is no longer relevant (for example, it is shutting down completely cleanly). For example, a client may call wamp.session.flush_testaments:¶

yield self.call('wamp.session.flush_testaments', scope='detached')
yield self.call('wamp.session.flush_testaments', scope='destroyed')

The Router will then flush all Testaments stored for the given scope.¶

5.1. Ticket-based Authentication

With Ticket-based authentication, the client needs to present the server an authentication "ticket" - some magic value to authenticate itself to the server.¶

This "ticket" could be a long-lived, pre-agreed secret (e.g. a user password) or a short-lived authentication token (like a Kerberos token). WAMP does not care or interpret the ticket presented by the client.¶

Caution: This scheme is extremely simple and flexible, but the resulting security may be limited. E.g., the ticket value will be sent over the wire. If the transport WAMP is running over is not encrypted, a man-in-the-middle can sniff and possibly hijack the ticket. If the ticket value is reused, that might enable replay attacks.¶

A typical authentication begins with the client sending a HELLO message specifying the ticket method as (one of) the authentication methods:¶

    [1, "realm1",
      {
        "roles": ...,
        "authmethods": ["ticket"],
        "authid": "joe"
      }
    ]

The HELLO.Details.authmethods|list is used by the client to announce the authentication methods it is prepared to perform. For Ticket-based, this MUST include "ticket".¶

The HELLO.Details.authid|string is the authentication ID (e.g. username) the client wishes to authenticate as. For Ticket-based authentication, this MUST be provided.¶

If the server is unwilling or unable to perform Ticket-based authentication, it'll either skip forward trying other authentication methods (if the client announced any) or send an ABORT message.¶

If the server is willing to let the client authenticate using a ticket and the server recognizes the provided authid, it'll send a CHALLENGE message:¶

    [4, "ticket", {}]

The client will send an AUTHENTICATE message containing a ticket:¶

    [5, "secret!!!", {}]

The server will then check if the ticket provided is permissible (for the authid given).¶

If the authentication succeeds, the server will finally respond with a WELCOME message:¶

    [2, 3251278072152162,
      {
        "authid": "joe",
        "authrole": "user",
        "authmethod": "ticket",
        "authprovider": "static",
        "roles": ...
      }
    ]

where¶

1. authid|string: The authentication ID the client was (actually) authenticated as.¶
2. authrole|string: The authentication role the client was authenticated for.¶
3. authmethod|string: The authentication method, here "ticket"¶
4. authprovider|string: The actual provider of authentication. For Ticket-based authentication, this can be freely chosen by the app, e.g. static or dynamic.¶

The WELCOME.Details again contain the actual authentication information active. If the authentication fails, the server will response with an ABORT message.¶

5.2. Challenge Response Authentication

WAMP Challenge-Response ("WAMP-CRA") authentication is a simple, secure authentication mechanism using a shared secret. The client and the server share a secret. The secret never travels the wire, hence WAMP-CRA can be used via non-TLS connections. The actual pre-sharing of the secret is outside the scope of the authentication mechanism.¶

A typical authentication begins with the client sending a HELLO message specifying the wampcra method as (one of) the authentication methods:¶

    [1, "realm1",
        {
            "roles": ...,
            "authmethods": ["wampcra"],
            "authid": "peter"
        }
    ]

The HELLO.Details.authmethods|list is used by the client to announce the authentication methods it is prepared to perform. For WAMP-CRA, this MUST include "wampcra".¶

The HELLO.Details.authid|string is the authentication ID (e.g. username) the client wishes to authenticate as. For WAMP-CRA, this MUST be provided.¶

If the server is unwilling or unable to perform WAMP-CRA authentication, it MAY either skip forward trying other authentication methods (if the client announced any) or send an ABORT message.¶

If the server is willing to let the client authenticate using WAMP-CRA, and the server recognizes the provided authid, it MUST send a CHALLENGE message:¶

    [4, "wampcra",
        {
            "challenge": "{ \"nonce\": \"LHRTC9zeOIrt_9U3\",
                \"authprovider\": \"userdb\", \"authid\": \"peter\",
                \"timestamp\": \"2014-06-22T16:36:25.448Z\",
                \"authrole\": \"user\", \"authmethod\": \"wampcra\",
                \"session\": 3251278072152162}"
        }
    ]

The CHALLENGE.Details.challenge|string is a string the client needs to create a signature for. The string MUST BE a JSON serialized object which MUST contain:¶

1. authid|string: The authentication ID the client will be authenticated as when the authentication succeeds.¶
2. authrole|string: The authentication role the client will be authenticated as when the authentication succeeds.¶
3. authmethod|string: The authentication methods, here "wampcra"¶
4. authprovider|string: The actual provider of authentication. For WAMP-CRA, this can be freely chosen by the app, e.g. userdb.¶
5. nonce|string: A random value.¶
6. timestamp|string: The UTC timestamp (ISO8601 format) the authentication was started, e.g. 2014-06-22T16:51:41.643Z.¶
7. session|int: The WAMP session ID that will be assigned to the session once it is authenticated successfully.¶

The client needs to compute the signature as follows:¶

    signature := HMAC[SHA256]_{secret} (challenge)

That is, compute the HMAC-SHA256 using the shared secret over the challenge.¶

After computing the signature, the client will send an AUTHENTICATE message containing the signature, as a base64-encoded string:¶

    [5, "gir1mSx+deCDUV7wRM5SGIn/+R/ClqLZuH4m7FJeBVI=", {}]

The server will then check if¶

• the signature matches the one expected¶
• the AUTHENTICATE message was sent in due time¶

If the authentication succeeds, the server will finally respond with a WELCOME message:¶

    [2, 3251278072152162,
        {
            "authid": "peter",
            "authrole": "user",
            "authmethod": "wampcra",
            "authprovider": "userdb",
            "roles": ...
        }
    ]

The WELCOME.Details again contain the actual authentication information active.¶

If the authentication fails, the server will response with an ABORT message.¶

Server-side Verification¶

The challenge sent during WAMP-CRA contains¶

1. random information (the nonce) to make WAMP-CRA robust against replay attacks¶
2. timestamp information (the timestamp) to allow WAMP-CRA timeout on authentication requests that took too long¶
3. session information (the session) to bind the authentication to a WAMP session ID¶
4. all the authentication information that relates to authorization like authid and authrole¶

Three-legged Authentication¶

The signing of the challenge sent by the server usually is done directly on the client. However, this is no strict requirement.¶

E.g. a client might forward the challenge to another party (hence the "three-legged") for creating the signature. This can be used when the client was previously already authenticated to that third party, and WAMP-CRA should run piggy packed on that authentication.¶

The third party would, upon receiving a signing request, simply check if the client is already authenticated, and if so, create a signature for WAMP-CRA.¶

In this case, the secret is actually shared between the WAMP server who wants to authenticate clients using WAMP-CRA and the third party server, who shares a secret with the WAMP server.¶

This scenario is also the reason the challenge sent with WAMP-CRA is not simply a random value, but a JSON serialized object containing sufficient authentication information for the third party to check.¶

Password Salting¶

WAMP-CRA operates using a shared secret. While the secret is never sent over the wire, a shared secret often requires storage of that secret on the client and the server - and storing a password verbatim (unencrypted) is not recommended in general.¶

WAMP-CRA allows the use of salted passwords following the PBKDF2 key derivation scheme. With salted passwords, the password itself is never stored, but only a key derived from the password and a password salt. This derived key is then practically working as the new shared secret.¶

When the password is salted, the server will during WAMP-CRA send a CHALLENGE message containing additional information:¶

    [4, "wampcra",
        {
            "challenge": "{ \"nonce\": \"LHRTC9zeOIrt_9U3\",
                \"authprovider\": \"userdb\", \"authid\": \"peter\",
                \"timestamp\": \"2014-06-22T16:36:25.448Z\",
                \"authrole\": \"user\", \"authmethod\": \"wampcra\",
                \"session\": 3251278072152162}",
            "salt": "salt123",
            "keylen": 32,
            "iterations": 1000
        }
    ]

The CHALLENGE.Details.salt|string is the password salt in use. The CHALLENGE.Details.keylen|int and CHALLENGE.Details.iterations|int are parameters for the PBKDF2 algorithm.¶

5.3. Salted Challenge Response Authentication

The WAMP Salted Challenge Response Authentication Mechanism ("WAMP-SCRAM"), is a password-based authentication method where the shared secret is neither transmitted nor stored as cleartext. WAMP-SCRAM is based on RFC5802 (Salted Challenge Response Authentication Mechanism) and RFC7677 (SCRAM-SHA-256 and SCRAM-SHA-256-PLUS).¶

WAMP-SCRAM supports the Argon2 (draft-irtf-cfrg-argon2) password-based key derivation function, a memory-hard algorithm intended to resist cracking on GPU hardware. PBKDF2 (RFC2898) is also supported for applications that are required to use primitives currently approved by cryptographic standards.¶

Security Considerations¶

With WAMP-SCRAM, if the authentication database is stolen, an attacker cannot impersonate a user unless they guess the password offline by brute force.¶

In the event that the server's authentication database is stolen, and the attacker either eavesdrops on one authentication exchange or impersonates a server, the attacker gains the ability to impersonate that particular user on that server. If the same salt is used on other servers, the attacker would gain the ability to impersonate that user on all servers using the same salt. That's why it's important to use a per-user random salt.¶

An eavesdropper that captures a user authentication exchange has enough information to mount an offline, brute-force dictionary attack for that particular user. If passwords are sufficiently strong, the cost/time needed to crack a password becomes prohibitive.¶

Note that when HTML/JavaScript assets are served to a web browser, WAMP-SCRAM does not safeguard against a man-in-the-middle tampering with those assets. Those assets could be tampered with in a way that captures the user's password and sends it to the attacker.¶

In light of the above security concerns, a secure TLS transport is therefore advised to prevent such attacks. The channel binding feature of SCRAM can be used to ensure that the TLS endpoints are the same between client and router.¶

Deviations from RFC5802¶

1. To simplify parsing, SCRAM attributes in the authentication exchange messages are encoded as members of the Options/Details objects without escaping the , and = characters. However, the AuthMessage used to compute the client and server signatures DOES use the exact syntax specified in RFC5802, section 7. This makes it possible to use existing test vectors to verify WAMP-SCRAM implementations.¶

2. Hashing based on the weaker SHA-1 specified in RFC5802 is intentionally not supported by WAMP-SCRAM, in favor of the stronger SHA-256 specified in RFC7677.¶

3. The Argon2 key derivation function MAY be used instead of PBKDF2.¶

4. Nonces are required to be base64-encoded, which is stricter than the printable syntax specification of RFC5802.¶

5. The "y" channel binding flag is not used as there is currently no standard way for WAMP routers to announce channel binding capabilities.¶

6. The use of authzid for user impersonation is not supported.¶

authmethod Type String¶

"wamp-scram" SHALL be used as the authmethod type string for WAMP-SCRAM authentication. Announcement by routers of WAMP-SCRAM support is outside the scope of this document.¶

Base64 encoding¶

Base64 encoding of octet strings is restricted to canonical form with no whitespace, as defined in RFC4648 (The Base16, Base32, and Base64 Data Encodings).¶

Nonces¶

In WAMP-SCRAM, a nonce (number used once) is a base64-encoded sequence of random octets. It SHOULD be of sufficient length to make a replay attack unfeasible. A length of 16 octets (128 bits) is recommended for each of the client and server-generated nonces.¶

See RFC4086 (Randomness Requirements for Security) for best practices concerning randomness.¶

Salts¶

A salt is a base64-encoded sequence of random octets.¶

To prevent rainbow table attacks in the event of database theft, the salt MUST be generated randomly by the server for each user. The random salt is stored with each user record in the authentication database.¶

Username/Password String Normalization¶

Username and password strings SHALL be normalized according to the SASLprep profile described in RFC4013, using the stringprep algorithm described in RFC3454.¶

While SASLprep preserves the case of usernames, the server MAY choose to perform case insensitive comparisons when searching for a username in the authentication database.¶

Channel Binding¶

Channel binding is a feature that allows a higher layer to establish that the other end of an underlying secure channel is bound to its higher layer counterpart. See RFC5056 (On the Use of Channel Bindings) for an in-depth discussion.¶

RFC5929 defines binding types for use with TLS transports, of which tls-unique and tls-server-end-point are applicable for WAMP-SCRAM. For each channel binding type, there is a corresponding definition of the channel binding data that must be sent in response to the authentication challenge.¶

Negotiation and announcement of channel binding is outside the scope of this document. RFC5929 section 6 recommends that application protocols use tls-unique exclusively, except perhaps where server-side proxies are commonly deployed.¶

Note that WAMP-SCRAM channel binding is not generally possible with web browser clients due to the lack of a suitable API for this purpose.¶

The tls-unique Channel Binding Type¶

The tls-unique channel binding type allows the WAMP layer to establish that the other peer is authenticating over the same, unique TLS connection. The channel binding data for this type corresponds to the bytes of the first TLS Finished message, as described in RFC5929, section 3. RFC5929 section 10.2 addresses the concern of disclosing this data over the TLS channel (in short, the TLS Finished message would already be visible to eavesdroppers).¶

To safeguard against the triple handshake attack described in RFC7627, this channel binding type MUST be used over a TLS channel that uses the extended master secret extension, or over a TLS channel where session resumption is not permitted.¶

The tls-server-end-point Channel Binding Type¶

The tls-server-end-point channel binding type allows the WAMP layer to establish that the other peer is authenticating over a TLS connection to a server having been issued a Public Key Infrastructure Certificate. The channel binding data for this type is a hash of the TLS server's certificate, computed as described in RFC5929, section 4.1. The certificate is hashed to accommodate memory-constrained implementations.¶

Authentication Exchange¶

WAMP-SCRAM uses a single round of challenge/response pairs after the client authentication request and before the authentication outcome.¶

The mapping of RFC5802 messages to WAMP messages is as follows:¶

Initial Client Authentication Message¶

WAMP-SCRAM authentication begins with the client sending a HELLO message specifying the wamp-scram method as (one of) the authentication methods:¶

    [1, "realm1",
        {
            "roles": ...,
            "authmethods": ["wamp-scram"],
            "authid": "user",
            "authextra":
                {
                    "nonce": "egVDf3DMJh0=",
                    "channel_binding": null
                }

        }
    ]

where:¶

1. authid|string: The identity of the user performing authentication. This corresponds to the username parameter in RFC5802.¶
2. authextra.nonce|string: A base64-encoded sequence of random octets, generated by the client. See Nonces.¶
3. authextra.channel_binding|string: Optional string containing the desired channel binding type. See Channel Bindings.¶

Upon receiving the HELLO message, the server MUST terminate the authentication process by sending an ABORT message under any of the following circumstances:¶

• The server does not support the WAMP-SCRAM authmethods, and there are no other methods left that the server supports for this authid.¶
• The the server does not support the requested channel_binding type.¶
• (Optional) The server does not recognize the given authid. In this case, the server MAY proceed with a mock CHALLENGE message to avoid leaking information on the existence of usernames. This mock CHALLENGE SHOULD contain a generated salt value that is always the same for a given authid, otherwise an attacker may discover that the user doesn't actually exist.¶

Initial Server Authentication Message¶

If none of the above failure conditions apply, and the server is ready to let the client authenticate using WAMP-SCRAM, then it SHALL send a CHALLENGE message:¶

    [4, "wamp-scram",
        {
            "nonce": "egVDf3DMJh0=SBmkFIh7sSo=",
            "salt": "aBc+fx0NAVA=",
            "kdf": "pbkdf2",
            "iterations": 4096,
            "memory": null
        }
    ]

where:¶

1. nonce|string: A server-generated nonce that is appended to the client-generated nonce sent in the previous HELLO message. See Nonces.¶
2. salt|string: The base64-encoded salt for this user, to be passed to the key derivation function. This value is stored with each user record in the authentication database. See Salts.¶
3. kdf: The key derivation function (KDF) used to hash the password. This value is stored with each user record in the authentication database. See Key Derivation Functions.¶
4. iterations|integer: The execution time cost factor to use for generating the SaltedPassword hash. This value is stored with each user record in the authentication database.¶
5. memory|integer: The memory cost factor to use for generating the SaltedPassword hash. This is only used by the Argon2 key derivation function, where it is stored with each user record in the authentication database.¶

The client MUST respond with an ABORT message if CHALLENGE.Details.nonce does not begin with the client nonce sent in HELLO.Details.nonce.¶

The client SHOULD respond with an ABORT message if it detects that the cost parameters are unusually low. Such low-cost parameters could be the result of a rogue server attempting to obtain a weak password hash that can be easily cracked. What constitutes unusually low parameters is implementation-specific and is not covered by this document.¶

Final Client Authentication Message¶

Upon receiving a valid CHALLENGE message, the client SHALL respond with an AUTHENTICATE message:¶

    [5, "dHzbZapWIk4jUhN+Ute9ytag9zjfMHgsqmmiz7AndVQ=",
        {
            "nonce": "egVDf3DMJh0=SBmkFIh7sSo=",
            "channel_binding": null,
            "cbind_data": null
        }
    ]

where:¶

1. Signature|string argument: The base64-encoded ClientProof, computed as described in the SCRAM-Algorithms section.¶
2. nonce|string: The concatenated client-server nonce from the previous CHALLENGE message.¶
3. channel_binding|string: Optional string containing the channel binding type that was sent in the original HELLO message.¶
4. cbind_data|string: Optional base64-encoded channel binding data. MUST be present if and only if channel_binding is not null. The format of the binding data is dependent on the binding type. See Channel Binding.¶

Upon receiving the AUTHENTICATE message, the server SHALL then check that:¶

• The AUTHENTICATE message was received in due time.¶
• The ClientProof passed via the Signature|string argument is validated against the StoredKey and ServerKey stored in the authentication database. See SCRAM Algorithms.¶
• nonce matches the one previously sent via CHALLENGE.¶
• The channel_binding matches the one sent in the HELLO message.¶
• The cbind_data sent by the client matches the channel binding data that the server sees on its side of the channel.¶

Final Server Authentication Message - Success¶

If the authentication succeeds, the server SHALL finally respond with a WELCOME message:¶

    [2, 3251278072152162,
        {
            "authid": "user",
            "authrole": "frontend",
            "authmethod": "wamp-scram",
            "authprovider": "static",
            "roles": ...,
            "authextra":
                {
                    "verifier":
                      "v=6rriTRBi23WpRR/wtup+mMhUZUn/dB5nLTJRsjl95G4="
                }
        }
    ]

where:¶

1. authid|string: The authentication ID the client was actually authenticated as.¶
2. authrole|string: The authentication role the client was authenticated for.¶
3. authmethod|string: The authentication method, here "wamp-scram".¶
4. authprovider|string: The actual provider of authentication. For WAMP-SCRAM authentication, this can be freely chosen by the app, e.g. static or dynamic.¶
5. authextra.verifier|string: The base64-encoded ServerSignature, computed as described in the SCRAM Algorithms section.¶

The client SHOULD check the verifier for mutual authentication, terminating the session if invalid.¶

Final Server Authentication Message - Failure¶

If the authentication fails, the server SHALL respond with an ABORT message.¶

The server MAY include a SCRAM-specific error string in the ABORT message as a Details.scram attribute. SCRAM error strings are listed in RFC5802, section 7, under server-error-value.¶

SCRAM Algorithms¶

This section is non-normative.¶

RFC5802 specifies the algorithms used to compute the ClientProof, ServerSignature, ServerKey, and StoredKey values referenced by this document. Those algorithms are summarized here in pseudocode for reference.¶

Notation¶

• "=": The variable on the left-hand side is the result of the expression on the right-hand side.¶
• "+": String concatenation.¶
• IfNull(attribute, value, else): If the given attribute is absent or null, evaluates to the given value, otherwise evaluates to the given else value.¶
• Decimal(integer): The decimal string representation of the given integer.¶
• Base64(octets): Base64 encoding of the given octet sequence, restricted to canonical form with no whitespace, as defined in RFC4648.¶
• UnBase64(str): Decode the given Base64 string into an octet sequence.¶
• Normalize(str): Normalize the given string using the SASLprep profile RFC4013 of the "stringprep" algorithm RFC3454.¶
• XOR: The exclusive-or operation applied to each octet of the left and right-hand-side octet sequences.¶
• SHA256(str): The SHA-256 cryptographic hash function.¶
• HMAC(key, str): Keyed-hash message authentication code, as defined in RFC2104, with SHA-256 as the underlying hash function.¶
• KDF(str, salt, params...): One of the supported key derivations function, with the output key length the same as the SHA-256 output length (32 octets). params... are the additional parameters that are applicable for the function: iterations and memory.¶
• Escape(str): Replace every occurrence of "," and "=" in the given string with "=2C" and "=3D" respectively.¶

Data Stored on the Server¶

For each user, the server needs to store:¶

1. A random, per-user salt.¶
2. The type string corresponding to the key derivation function (KDF) used to hash the password (e.g. "argon2id13"). This is needed to handle future revisions of the KDF, as well as allowing migration to stronger KDFs that may be added to WAMP-SCRAM in the future. This may also be needed if the KDF used during user registration is configurable or selectable on a per-user basis.¶
3. Parameters that are applicable to the key derivation function : iterations and possibly memory.¶
4. The StoredKey.¶
5. The ServerKey.¶

where StoredKey and ServerKey are computed as follows:¶

SaltedPassword  = KDF(Normalize(password), salt, params...)
ClientKey       = HMAC(SaltedPassword, "Client Key")
StoredKey       = SHA256(ClientKey)
ServerKey       = HMAC(SaltedPassword, "Server Key")

Note that "Client Key" and "Server Key" are string literals.¶

The manner in which the StoredKey and ServerKey are shared with the server during user registration is outside the scope of SCRAM and this document.¶

AuthMessage¶

In SCRAM, AuthMessage is used for computing ClientProof and ServerSignature. AuthMessage is computed using attributes that were sent in the first three messages of the authentication exchange.¶

ClientFirstBare = "n=" + Escape(HELLO.Details.authid) + "," +
                  "r=" + HELLO.Details.authextra.nonce

ServerFirst = "r=" + CHALLENGE.Details.nonce + "," +
              "s=" + CHALLENGE.Details.salt + "," +
              "i=" + Decimal(CHALLENGE.Details.iterations)

CBindName = AUTHENTICATE.Extra.channel_binding

CBindData = AUTHENTICATE.Extra.cbind_data

CBindFlag = IfNull(CBindName, "n", "p=" + CBindName)

CBindInput = CBindFlag + ",," +
             IfNull(CBindData, "", UnBase64(CBindData))

ClientFinalNoProof = "c=" + Base64(CBindInput) + "," +
                     "r=" + AUTHENTICATE.Extra.nonce

AuthMessage = ClientFirstBare + "," + ServerFirst + "," +
              ClientFinalNoProof

ClientProof¶

ClientProof is computed by the client during the authentication exchange as follows:¶

SaltedPassword  = KDF(Normalize(password), salt, params...)
ClientKey       = HMAC(SaltedPassword, "Client Key")
StoredKey       = SHA256(ClientKey)
ClientSignature = HMAC(StoredKey, AuthMessage)
ClientProof     = ClientKey XOR ClientSignature

The ClientProof is then sent to the server, base64-encoded, via the AUTHENTICATE.Signature argument.¶

The server verifies the ClientProof by computing the RecoveredStoredKey and comparing it to the actual StoredKey:¶

ClientSignature    = HMAC(StoredKey, AuthMessage)
RecoveredClientKey = ClientSignature XOR ReceivedClientProof
RecoveredStoredKey = SHA256(RecoveredClientKey)

Note that the client MAY cache the ClientKey and StoredKey (or just SaltedPassword) to avoid having to perform the expensive KDF computation for every authentication exchange. Storing these values securely on the client is outside the scope of this document.¶

ServerSignature¶

ServerSignature is computed by the server during the authentication exchange as follows:¶

ServerSignature = HMAC(ServerKey, AuthMessage)

The ServerSignature is then sent to the client, base64-encoded, via the WELCOME.Details.authextra.verifier attribute.¶

The client verifies the ServerSignature by computing it and comparing it with the ServerSignature sent by the server:¶

ServerKey       = HMAC(SaltedPassword, "Server Key")
ServerSignature = HMAC(ServerKey, AuthMessage)

Key Derivation Functions¶

SCRAM uses a password-based key derivation function (KDF) to hash user passwords. WAMP-SCRAM supports both Argon2 and PBKDF2 as the KDF. Argon2 is recommended because of its memory hardness and resistance against GPU hardware. PBKDF2, which does not feature memory hardness, is also supported for applications that are required to use primitives currently approved by cryptographic standards.¶

The following table maps the CHALLENGE.Details.kdf type string to the corresponding KDF.¶

To promote interoperability, WAMP-SCRAM client/server implementations SHOULD support both of the above KDFs. During authentication, there is no "negotiation" of the KDF, and the client MUST use the same KDF than the one used to create the keys stored in the authentication database.¶

Which KDF is used to hash the password during user registration is up to the application and/or server implementation, and is not covered by this document. Possibilities include:¶

• making the KDF selectable at runtime during registration,¶
• making the KDF statically configurable on the server, or,¶
• hard-coding the KDF selection on the server.¶

Argon2¶

The Argon2 key derivation function, proposed in draft-irtf-cfrg-argon2, is computed using the following parameters:¶

• CHALLENGE.Details.salt as the cryptographic salt,¶
• CHALLENGE.Details.iterations as the number of iterations,¶
• CHALLENGE.Details.memory as the memory size (in kibibytes),¶
• 1 as the parallelism parameter,¶
• Argon2id as the algorithm variant, and,¶
• 32 octets as the output key length.¶

For WAMP-SCRAM, the parallelism parameter is fixed to 1 due to the password being hashed on the client side, where it is not generally known how many cores/threads are available on the client's device.¶

Section 4 of the Argon2 internet draft recommends the general procedure for selecting parameters, of which the following guidelines are applicable to WAMP-SCRAM:¶

• A 128-bit salt is recommended, which can be reduced to 64-bit if space is limited.¶
• The memory parameter is to be configured to the maximum amount of memory usage that can be tolerated on client devices for computing the hash.¶
• The iterations parameter is to be determined experimentally so that execution time on the client reaches the maximum that can be tolerated by users during authentication. If the execution time is intolerable with iterations = 1, then reduce the memory parameter as needed.¶

PBKDF2¶

The PBKDF2 key derivation function, defined in RFC2898, is used with SHA-256 as the pseudorandom function (PRF).¶

The PDBKDF2 hash is computed using the following parameters:¶

• CHALLENGE.Details.salt as the cryptographic salt,¶
• CHALLENGE.Details.iterations as the iteration count, and,¶
• 32 octets as the output key length (dkLen), which matches the SHA-256 output length.¶

RFC2898 section 4.1 recommends at least 64 bits for the salt.¶

The iterations parameter SHOULD be determined experimentally so that execution time on the client reaches the maximum that can be tolerated by users during authentication. RFC7677 section 4 recommends an iteration count of at least 4096, with a significantly higher value on non-mobile clients.¶

5.4. Cryptosign-based Authentication

WAMP-Cryptosign is a WAMP authentication method based on public-private key cryptography. Specifically, it is based on Ed25519 digital signatures as described in [RFC8032].¶

Ed25519 is an elliptic curve signature scheme that instantiates the Edwards-curve Digital Signature Algorithm (EdDSA) with elliptic curve parameters which are equivalent to Curve25519. Curve25519 is a SafeCurve, which means it is easy to implement and avoid security issues resulting from common implementation challenges and bugs. Ed25519 is intended to operate at around the 128-bit security level, and there are robust native implementations available as open-source, e.g. libsodium, which can be used from script languages, e.g. PyNaCl.¶

An implementation of WAMP-Cryptosign MUST provide¶

• Client Authentication¶

and MAY implement one or more of¶

• TLS Channel Binding¶
• Router Authentication¶
• Trustroots and Certificates¶
• Remote Attestation¶

The following sections describe each of above features of WAMP-Cryptosign.¶

Examples of complete authentication message exchanges can be found at the end of this chapter in Example Message Exchanges.¶

In WAMP, the following cryptographic primitives are used with WAMP-Cryptosign authentication:¶

Elliptic Curves:¶

• RFC4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)¶
• RFC7748: Elliptic Curves for Security¶

Hash Functions:¶

Note that sha256 refers to the SHA-2 algorithm, while sha3-256 is a different algorithm refering to SHA-3.¶

Signature Schemes:¶

[1, "realm1", {
    "roles": {/* see below */},
    "authmethods": ["cryptosign"],
    "authid": "client01@example.com",
    "authextra": {
        "pubkey": "545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122"
    }
}]

{"callee": {"features": {"call_canceling": True,
                         "caller_identification": True,
                         "pattern_based_registration": True,
                         "progressive_call_results": True,
                         "registration_revocation": True,
                         "shared_registration": True}},
"caller": {"features": {"call_canceling": True,
                        "caller_identification": True,
                        "progressive_call_results": True}},
"publisher": {"features": {"publisher_exclusion": True,
                           "publisher_identification": True,
                           "subscriber_blackwhite_listing": True}},
"subscriber": {"features": {"pattern_based_subscription": True,
                            "publisher_identification": True,
                            "subscription_revocation": True}}}}

[4, "cryptosign", {
    "challenge": "fa034062ad76352b53a25358854577730db82f367aa439709c91296d04a5716c",
    "channel_binding": null
}]

[5 'e2f0297a193b63b7a4a92028e9e2e6107f82730560d54a657bd982cb4b3151490399debbbde998e494d3c3b2a5e2e91271291e10dee85a6cfaa127885ddd8b0afa034062ad76352b53a25358854577730db82f367aa439709c91296d04a5716c', {}]

[2, 7562122397119786, {
    "authextra": {
        "x_cb_node": "intel-nuci7-27532",
        "x_cb_peer": "tcp4:127.0.0.1:49032",
        "x_cb_pid": 27637,
        "x_cb_worker": "worker001"
    },
    "authid": "client01@example.com",
    "authmethod": "cryptosign",
    "authprovider": "static",
    "authrole": "user",
    "realm": "realm1",
    "roles": {/* see below */}
}]

{"broker": {"features": {"event_retention": True,
                                    "pattern_based_subscription": True,
                                    "publisher_exclusion": True,
                                    "publisher_identification": True,
                                    "session_meta_api": True,
                                    "subscriber_blackwhite_listing": True,
                                    "subscription_meta_api": True,
                                    "subscription_revocation": True}},
            "dealer": {"features": {"call_canceling": True,
                                    "caller_identification": True,
                                    "pattern_based_registration": True,
                                    "progressive_call_results": True,
                                    "registration_meta_api": True,
                                    "registration_revocation": True,
                                    "session_meta_api": True,
                                    "shared_registration": True,
                                    "testament_meta_api": True}}
    }

test_vectors_1 = [
    {
        'channel_id': None,
        'private_key': '4d57d97a68f555696620a6d849c0ce582568518d729eb753dc7c732de2804510',
        'challenge': 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
        'signature': 'b32675b221f08593213737bef8240e7c15228b07028e19595294678c90d11c0cae80a357331bfc5cc9fb71081464e6e75013517c2cf067ad566a6b7b728e5d03ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'
    },
    {
        'channel_id': None,
        'private_key': 'd511fe78e23934b3dadb52fcd022974b80bd92bccc7c5cf404e46cc0a8a2f5cd',
        'challenge': 'b26c1f87c13fc1da14997f1b5a71995dff8fbe0a62fae8473c7bdbd05bfb607d',
        'signature': 'd4209ad10d5aff6bfbc009d7e924795de138a63515efc7afc6b01b7fe5201372190374886a70207b042294af5bd64ce725cd8dceb344e6d11c09d1aaaf4d660fb26c1f87c13fc1da14997f1b5a71995dff8fbe0a62fae8473c7bdbd05bfb607d'
    },
    {
        'channel_id': None,
        'private_key': '6e1fde9cf9e2359a87420b65a87dc0c66136e66945196ba2475990d8a0c3a25b',
        'challenge': 'b05e6b8ad4d69abf74aa3be3c0ee40ae07d66e1895b9ab09285a2f1192d562d2',
        'signature': '7beb282184baadd08f166f16dd683b39cab53816ed81e6955def951cb2ddad1ec184e206746fd82bda075af03711d3d5658fc84a76196b0fa8d1ebc92ef9f30bb05e6b8ad4d69abf74aa3be3c0ee40ae07d66e1895b9ab09285a2f1192d562d2'
    },
    {
        'channel_id': '62e935ae755f3d48f80d4d59f6121358c435722a67e859cc0caa8b539027f2ff',
        'private_key': '4d57d97a68f555696620a6d849c0ce582568518d729eb753dc7c732de2804510',
        'challenge': 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
        'signature': '9b6f41540c9b95b4b7b281c3042fa9c54cef43c842d62ea3fd6030fcb66e70b3e80d49d44c29d1635da9348d02ec93f3ed1ef227dfb59a07b580095c2b82f80f9d16ca518aa0c2b707f2b2a609edeca73bca8dd59817a633f35574ac6fd80d00'
    },
    {
        'channel_id': '62e935ae755f3d48f80d4d59f6121358c435722a67e859cc0caa8b539027f2ff',
        'private_key': 'd511fe78e23934b3dadb52fcd022974b80bd92bccc7c5cf404e46cc0a8a2f5cd',
        'challenge': 'b26c1f87c13fc1da14997f1b5a71995dff8fbe0a62fae8473c7bdbd05bfb607d',
        'signature': '305aaa3ac25e98f651427688b3fc43fe7d8a68a7ec1d7d61c61517c519bd4a427c3015599d83ca28b4c652333920223844ef0725eb5dc2febfd6af7677b73f01d0852a29b460fc92ec943242ac638a053bbacc200512b18b30d15083cbdc9282'
    },
    {
        'channel_id': '62e935ae755f3d48f80d4d59f6121358c435722a67e859cc0caa8b539027f2ff',
        'private_key': '6e1fde9cf9e2359a87420b65a87dc0c66136e66945196ba2475990d8a0c3a25b',
        'challenge': 'b05e6b8ad4d69abf74aa3be3c0ee40ae07d66e1895b9ab09285a2f1192d562d2',
        'signature': 'ee3c7644fd8070532bc1fde3d70d742267da545d8c8f03e63bda63f1ad4214f4d2c4bfdb4eb9526def42deeb7e31602a6ff99eba893e0a4ad4d45892ca75e608d2b75e24a189a7f78ca776ba36fc53f6c3e31c32f251f2c524f0a44202f2902d'
    },
]

[1, 'realm1', {
  'authextra': {
    'channel_binding': 'tls-unique',
    'pubkey': '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'
  },
  'authmethods': ['cryptosign']
  }]

[4, 'cryptosign', {
  'challenge': '0e9192bc08512c8198da159c1ae600ba91729215f35d56102ee318558e773537',
  'channel_binding': 'tls-unique'}]

[1, 'realm1', {
  'authextra': {
    'challenge': 'bbae60ea44cdd7b20dc7010a618b0f0803fab25a817520b4b7f057299b524deb',
    'pubkey': '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'
    }}]

[4, 'cryptosign', {
  'challenge': '0e9192bc08512c8198da159c1ae600ba91729215f35d56102ee318558e773537',
  'pubkey': '4a3838f6fe75251e613329d53fc69b262d5eac97fb1d73bebbaed4015b53c862',
  'signature': 'fd5128d2d207ba58a9d1d6f41b72c747964ad9d1294077b3b1eee6130b05843ab12c53c7f2519f73d4feb82db19d8ca0fc26b62bde6518e79a882f5795bc9f00bbae60ea44cdd7b20dc7010a618b0f0803fab25a817520b4b7f057299b524deb'}]

           EIP712AuthorityCertificate
        +------------------------------+
        |   chainId                    |       Root Certificate
        |   verifyingContract          |
        |   validFrom                  |         * trust anchor, stored on-chain
   +----+-- issuer (== realm owner)    |         * tied to a realm
   +----+-> subject (== issuer) -------+----+    * self-signed by realm owner
        |   realm                      |    |
        |   capabilities               |    |
        |   meta                       |    |
        +------------------------------+    |   +------------------------------+
        |   issuerSignature            +----+---> Public Blockchain (L1 or L2) |
        +------------------------------+    |   +------------------------------+
                                            |
                                            |
                                            |
                                            |
                                            |
           EIP712AuthorityCertificate       |
        +------------------------------+    |
        |   chainId                    |    |   Intermediate Certificate
        |   verifyingContract          |    |
        |   validFrom                  |    |    * stored off-chain
        |   issuer  <------------------+----+    * same realm as issueing cert
  +-----+-- subject                    |         * subset of capabilities
  |     |   realm                      |             of issueing cert
  |     |   capabilities               |
  |     |   meta                       |
  |     +------------------------------+
  |     |   issuerSignature            |
  |     +------------------------------+
  |


optional hierarchical chain of intermediate certificates


  |
  |        EIP712AuthorityCertificate
  |     +------------------------------+
  |     |   chainId                    |        Intermediate Certificate
  |     |   verifyingContract          |
  |     |   validFrom                  |         * stored off-chain
  +-----+-> issuer                     |         * same realm as issueing cert
        |   subject--------------------+----+    * subset of capabilities
        |   realm                      |    |        of issueing cert
        |   capabilities               |    |
        |   meta                       |    |
        +------------------------------+    |
        |   issuerSignature            |    |
        +------------------------------+    |
                                            |
                                            |
                                            |
                                            |
                                            |
           EIP712DelegateCertificate        |
        +------------------------------+    |
        |   chainId                    |    |   End-point Certificate
        |   verifyingContract          |    |
        |   validFrom                  |    |     * ephemeral, generate per-boot
        |   delegate <-----------------+----+     * subject is WAMP-Cryptosign pubkey
        |   csPubKey                   |          * Boot time (UTC in Posix ns)
        |   bootedAt                   |
        |   meta                       |
        |                              |
        |                              |
        +------------------------------+         +--------------------------+
        |   delegateSignature          +---------> Hardware Security Module |
        +------------------------------+         +--------------------------+

[
    {
        "name": "chainId",
        "type": "uint256"
    },
    {
        "name": "verifyingContract",
        "type": "address"
    },
    {
        "name": "validFrom",
        "type": "uint256"
    },
    {
        "name": "issuer",
        "type": "address"
    },
    {
        "name": "subject",
        "type": "address"
    },
    {
        "name": "realm",
        "type": "address"
    },
    {
        "name": "capabilities",
        "type": "uint64"
    },
    {
        "name": "meta",
        "type": "string"
    }
]

[
    {
        "name": "chainId",
        "type": "uint256"
    },
    {
        "name": "verifyingContract",
        "type": "address"
    },
    {
        "name": "validFrom",
        "type": "uint256"
    },
    {
        "name": "delegate",
        "type": "address"
    },
    {
        "name": "csPubKey",
        "type": "bytes32"
    },
    {
        "name": "bootedAt",
        "type": "uint64"
    },
    {
        "name": "meta",
        "type": "string"
    }
]

[
    (EIP712DelegateCertificate, Signature),       // delegate certificate
    (EIP712AuthorityCertificate, Signature),      // intermediate CA certificate
    ...
    (EIP712AuthorityCertificate, Signature),      // intermediate CA certificate
    (EIP712AuthorityCertificate, Signature)       // root CA certificate
]

{'authextra': {'certificates': [/* certificate, see below */],
              'challenge': '2763e7fdb1c34a74e8497daf6c913744d11161a94cec3b16aeec60a788612e17',
              'channel_binding': 'tls-unique',
              'pubkey': '12ae0184b180e9a9c5e45be4a1afbce3c6491320063701cd9c4011a777d04089',
              'trustroot': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57'},

trustroot == 0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57
          == certificates[-1].issuer
          == certificates[-1].subject

{'authextra': {'certificates': [/* certificate, see below */],
              'challenge': '2763e7fdb1c34a74e8497daf6c913744d11161a94cec3b16aeec60a788612e17',
              'channel_binding': 'tls-unique',
              'pubkey': '12ae0184b180e9a9c5e45be4a1afbce3c6491320063701cd9c4011a777d04089',
              'trustroot': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57'},

    +------------------------------+
    | CHALLENGE sent by router     |
    +------------------------------+

      Selected PCRs (bitmap) == CHALLENGE.Extra.attest

      Nonce == CHALLENGE.Extra.challenge

        |
        |
        |
        |       Quote (signed with AK)
        |      +------------------------------+
        |      |                              |
        +----> | Selected PCRs (bitmap)       |
        |      |                              |
        |      | PCR values (digest)          |
        |      |                              |
        +----> | Nonce                        |
               |                              |
               +------------------------------+
               | Signature (Attestation Key)  |
               |                              |
               +------------------------------+

                             +

               +------------------------------+
               |                              |
               | Measurement Log              |
               |                              |
               |                              |
               |                              |
               +------------------------------+

                    |
                    |
                    |
                    |
                    |
                    |    +------------------------------+
                    +--> | AUTHENTICATE sent by client  |
                         +------------------------------+

                            AUTHENTICATE.Extra.quote

                            AUTHENTICATE.Extra.measurement

WAMP-Transmit(-, -) >>
  HELLO::
    [1,
     'devices',
     {'authextra': {'challenge': 'bbae60ea44cdd7b20dc7010a618b0f0803fab25a817520b4b7f057299b524deb',
                    'channel_binding': None,
                    'pubkey': '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'},
      'authmethods': ['cryptosign'],
      'roles': {'callee': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'pattern_based_registration': True,
                                        'progressive_call_results': True,
                                        'registration_revocation': True,
                                        'shared_registration': True}},
                'caller': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'progressive_call_results': True}},
                'publisher': {'features': {'publisher_exclusion': True,
                                           'publisher_identification': True,
                                           'subscriber_blackwhite_listing': True}},
                'subscriber': {'features': {'pattern_based_subscription': True,
                                            'publisher_identification': True,
                                            'subscription_revocation': True}}}}]
>>

WAMP-Receive(-, -) <<
  CHALLENGE::
    [4,
     'cryptosign',
     {'challenge': '0e9192bc08512c8198da159c1ae600ba91729215f35d56102ee318558e773537',
      'channel_binding': None,
      'pubkey': '4a3838f6fe75251e613329d53fc69b262d5eac97fb1d73bebbaed4015b53c862',
      'signature': 'fd5128d2d207ba58a9d1d6f41b72c747964ad9d1294077b3b1eee6130b05843ab12c53c7f2519f73d4feb82db19d8ca0fc26b62bde6518e79a882f5795bc9f00bbae60ea44cdd7b20dc7010a618b0f0803fab25a817520b4b7f057299b524deb'}]
<<

WAMP-Transmit(-, -) >>
  AUTHENTICATE::
    [5,
     'a3a178fe792ed772a8fc092f8341e455de96670c8901264a7c312dbf940d5743626fe9fbc29b23dcd2169b308eca309de85a89ccd296b24835de3d95b16b77030e9192bc08512c8198da159c1ae600ba91729215f35d56102ee318558e773537',
     {}]
>>

WAMP-Receive(-, -) <<
  WELCOME::
    [2,
     3735119691078036,
     {'authextra': {'x_cb_node': 'intel-nuci7-49879',
                    'x_cb_peer': 'tcp4:127.0.0.1:53976',
                    'x_cb_pid': 49987,
                    'x_cb_worker': 'worker001'},
      'authid': 'client01@example.com',
      'authmethod': 'cryptosign',
      'authprovider': 'static',
      'authrole': 'device',
      'realm': 'devices',
      'roles': {'broker': {'features': {'event_retention': True,
                                        'pattern_based_subscription': True,
                                        'publisher_exclusion': True,
                                        'publisher_identification': True,
                                        'session_meta_api': True,
                                        'subscriber_blackwhite_listing': True,
                                        'subscription_meta_api': True,
                                        'subscription_revocation': True}},
                'dealer': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'pattern_based_registration': True,
                                        'progressive_call_results': True,
                                        'registration_meta_api': True,
                                        'registration_revocation': True,
                                        'session_meta_api': True,
                                        'shared_registration': True,
                                        'testament_meta_api': True}}},
      'x_cb_node': 'intel-nuci7-49879',
      'x_cb_peer': 'tcp4:127.0.0.1:53976',
      'x_cb_pid': 49987,
      'x_cb_worker': 'worker001'}]
<<

WAMP-Transmit(3735119691078036, client01@example.com) >>
  GOODBYE::
    [6, {}, 'wamp.close.normal']
>>

WAMP-Receive(3735119691078036, client01@example.com) <<
  GOODBYE::
    [6, {}, 'wamp.close.normal']
<<

WAMP-Transmit(-, -) >>
  HELLO::
    [1,
     'devices',
     {'authextra': {'challenge': '4f861f12796c2972b7b0026522a687aa851d90355122a61d4f1fdce4d06b564f',
                    'channel_binding': 'tls-unique',
                    'pubkey': '545efb0a2192db8d43f118e9bf9aee081466e1ef36c708b96ee6f62dddad9122'},
      'authmethods': ['cryptosign'],
      'roles': {'callee': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'pattern_based_registration': True,
                                        'progressive_call_results': True,
                                        'registration_revocation': True,
                                        'shared_registration': True}},
                'caller': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'progressive_call_results': True}},
                'publisher': {'features': {'publisher_exclusion': True,
                                           'publisher_identification': True,
                                           'subscriber_blackwhite_listing': True}},
                'subscriber': {'features': {'pattern_based_subscription': True,
                                            'publisher_identification': True,
                                            'subscription_revocation': True}}}}]
>>

WAMP-Receive(-, -) <<
  CHALLENGE::
    [4,
     'cryptosign',
     {'challenge': '358625312c6c3bf64ed51d17d210ce21af1639c774cabf5735a9651d7d91fc6a',
      'channel_binding': 'tls-unique',
      'pubkey': '4a3838f6fe75251e613329d53fc69b262d5eac97fb1d73bebbaed4015b53c862',
      'signature': 'aa05f4cd7747d36b79443f1d4703a681e107edc085d876b508714e2a3a8135bacaae1c018452c4acb3ad2818aa97a6d23e5ac7e3734c7b1f40e6232a70938205a6f5a1f034a28090b195fb2ce2454a82532f5c8baf6ba1dfb5ddae63c09ce72f'}]
<<

WAMP-Transmit(-, -) >>
  AUTHENTICATE::
    [5,
     '25114474580d6e99a6126b091b4565c23db567d686c5b8c3a94e3f2f09dc80300c5b40a124236733fa56396df721eb12ac092362379bd5b27b4db9e2beaa1408dcf59bd361a2921448f0e45e12f303097924f5798a83b895cf6b179a6d664d0a',
     {}]
>>

WAMP-Receive(-, -) <<
  WELCOME::
    [2,
     7325966140445461,
     {'authextra': {'x_cb_node': 'intel-nuci7-49879',
                    'x_cb_peer': 'tcp4:127.0.0.1:54046',
                    'x_cb_pid': 49987,
                    'x_cb_worker': 'worker001'},
      'authid': 'client01@example.com',
      'authmethod': 'cryptosign',
      'authprovider': 'static',
      'authrole': 'device',
      'realm': 'devices',
      'roles': {'broker': {'features': {'event_retention': True,
                                        'pattern_based_subscription': True,
                                        'publisher_exclusion': True,
                                        'publisher_identification': True,
                                        'session_meta_api': True,
                                        'subscriber_blackwhite_listing': True,
                                        'subscription_meta_api': True,
                                        'subscription_revocation': True}},
                'dealer': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'pattern_based_registration': True,
                                        'progressive_call_results': True,
                                        'registration_meta_api': True,
                                        'registration_revocation': True,
                                        'session_meta_api': True,
                                        'shared_registration': True,
                                        'testament_meta_api': True}}},
      'x_cb_node': 'intel-nuci7-49879',
      'x_cb_peer': 'tcp4:127.0.0.1:54046',
      'x_cb_pid': 49987,
      'x_cb_worker': 'worker001'}]
<<
2022-07-13T17:38:29+0200 session joined: {'authextra': {'x_cb_node': 'intel-nuci7-49879',
               'x_cb_peer': 'tcp4:127.0.0.1:54046',
               'x_cb_pid': 49987,
               'x_cb_worker': 'worker001'},
 'authid': 'client01@example.com',
 'authmethod': 'cryptosign',
 'authprovider': 'static',
 'authrole': 'device',
 'realm': 'devices',
 'resumable': False,
 'resume_token': None,
 'resumed': False,
 'serializer': 'cbor.batched',
 'session': 7325966140445461,
 'transport': {'channel_framing': 'websocket',
               'channel_id': {'tls-unique': b'\xe9s\xbe\xe2M\xce\xa9\xe2'
                                            b'\x06%\xf9I\xc0\xe3\xcd('
                                            b'\xd62\xcc\xbe\xfeI\x07\xc2'
                                            b'\xfa\xc2r\x87\x10\xf7\xb1`'},
               'channel_serializer': None,
               'channel_type': 'tls',
               'http_cbtid': None,
               'http_headers_received': None,
               'http_headers_sent': None,
               'is_secure': True,
               'is_server': False,
               'own': None,
               'own_fd': -1,
               'own_pid': 50690,
               'own_tid': 50690,
               'peer': 'tcp4:127.0.0.1:8080',
               'peer_cert': None,
               'websocket_extensions_in_use': None,
               'websocket_protocol': None}}

WAMP-Transmit(7325966140445461, client01@example.com) >>
  GOODBYE::
    [6, {}, 'wamp.close.normal']
>>

WAMP-Receive(7325966140445461, client01@example.com) <<
  GOODBYE::
    [6, {}, 'wamp.close.normal']
<<

WAMP-Transmit(-, -) >>
  HELLO::
    [1,
     'devices',
     {'authextra': {'certificates': [({'domain': {'name': 'WMP', 'version': '1'},
                                       'message': {'bootedAt': 1658765756680628959,
                                                   'chainId': 1,
                                                   'csPubKey': '12ae0184b180e9a9c5e45be4a1afbce3c6491320063701cd9c4011a777d04089',
                                                   'delegate': '0xf5173a6111B2A6B3C20fceD53B2A8405EC142bF6',
                                                   'meta': '',
                                                   'validFrom': 15212703,
                                                   'verifyingContract': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57'},
                                       'primaryType': 'EIP712DelegateCertificate',
                                       'types': {'EIP712DelegateCertificate': [{'name': 'chainId',
                                                                                'type': 'uint256'},
                                                                               {'name': 'verifyingContract',
                                                                                'type': 'address'},
                                                                               {'name': 'validFrom',
                                                                                'type': 'uint256'},
                                                                               {'name': 'delegate',
                                                                                'type': 'address'},
                                                                               {'name': 'csPubKey',
                                                                                'type': 'bytes32'},
                                                                               {'name': 'bootedAt',
                                                                                'type': 'uint64'},
                                                                               {'name': 'meta',
                                                                                'type': 'string'}],
                                                 'EIP712Domain': [{'name': 'name',
                                                                   'type': 'string'},
                                                                  {'name': 'version',
                                                                   'type': 'string'}]}},
                                      '8fe06bb269110c6bc0e011ea2b7da07091c674f7fe67458c1805157157da702b70b56cdf662666dc386820ded0116b6b84151df1ed65210eeecd7e477cdb765b1b'),
                                     ({'domain': {'name': 'WMP', 'version': '1'},
                                       'message': {'capabilities': 12,
                                                   'chainId': 1,
                                                   'issuer': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57',
                                                   'meta': '',
                                                   'realm': '0xA6e693CC4A2b4F1400391a728D26369D9b82ef96',
                                                   'subject': '0xf5173a6111B2A6B3C20fceD53B2A8405EC142bF6',
                                                   'validFrom': 15212703,
                                                   'verifyingContract': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57'},
                                       'primaryType': 'EIP712AuthorityCertificate',
                                       'types': {'EIP712AuthorityCertificate': [{'name': 'chainId',
                                                                                 'type': 'uint256'},
                                                                                {'name': 'verifyingContract',
                                                                                 'type': 'address'},
                                                                                {'name': 'validFrom',
                                                                                 'type': 'uint256'},
                                                                                {'name': 'issuer',
                                                                                 'type': 'address'},
                                                                                {'name': 'subject',
                                                                                 'type': 'address'},
                                                                                {'name': 'realm',
                                                                                 'type': 'address'},
                                                                                {'name': 'capabilities',
                                                                                 'type': 'uint64'},
                                                                                {'name': 'meta',
                                                                                 'type': 'string'}],
                                                 'EIP712Domain': [{'name': 'name',
                                                                   'type': 'string'},
                                                                  {'name': 'version',
                                                                   'type': 'string'}]}},
                                      '0c0eb60a108dbd72a204b41c1d18505358e4e7886b0c9787192a33ac9e0f94c92ce158f8de576fa9cccf28a8c9404ed66c2d355ea4ae7ee65cff0b73215b91bb1c'),
                                     ({'domain': {'name': 'WMP', 'version': '1'},
                                       'message': {'capabilities': 63,
                                                   'chainId': 1,
                                                   'issuer': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57',
                                                   'meta': '',
                                                   'realm': '0xA6e693CC4A2b4F1400391a728D26369D9b82ef96',
                                                   'subject': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57',
                                                   'validFrom': 15212703,
                                                   'verifyingContract': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57'},
                                       'primaryType': 'EIP712AuthorityCertificate',
                                       'types': {'EIP712AuthorityCertificate': [{'name': 'chainId',
                                                                                 'type': 'uint256'},
                                                                                {'name': 'verifyingContract',
                                                                                 'type': 'address'},
                                                                                {'name': 'validFrom',
                                                                                 'type': 'uint256'},
                                                                                {'name': 'issuer',
                                                                                 'type': 'address'},
                                                                                {'name': 'subject',
                                                                                 'type': 'address'},
                                                                                {'name': 'realm',
                                                                                 'type': 'address'},
                                                                                {'name': 'capabilities',
                                                                                 'type': 'uint64'},
                                                                                {'name': 'meta',
                                                                                 'type': 'string'}],
                                                 'EIP712Domain': [{'name': 'name',
                                                                   'type': 'string'},
                                                                  {'name': 'version',
                                                                   'type': 'string'}]}},
                                      'be35c8d6ae735d3bd8b5e27b1e1a067eba53e6a1cb4ef0f607c4717435e8ffa676246e7d08dfb4e83c78ad26f423b727b5d2c90627bdf6c94c1dbdf01979c34b1c')],
                    'challenge': '2763e7fdb1c34a74e8497daf6c913744d11161a94cec3b16aeec60a788612e17',
                    'channel_binding': 'tls-unique',
                    'pubkey': '12ae0184b180e9a9c5e45be4a1afbce3c6491320063701cd9c4011a777d04089',
                    'trustroot': '0xf766Dc789CF04CD18aE75af2c5fAf2DA6650Ff57'},
      'authmethods': ['cryptosign'],
      'roles': {'callee': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'pattern_based_registration': True,
                                        'progressive_call_results': True,
                                        'registration_revocation': True,
                                        'shared_registration': True}},
                'caller': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'progressive_call_results': True}},
                'publisher': {'features': {'publisher_exclusion': True,
                                           'publisher_identification': True,
                                           'subscriber_blackwhite_listing': True}},
                'subscriber': {'features': {'pattern_based_subscription': True,
                                            'publisher_identification': True,
                                            'subscription_revocation': True}}}}]
>>

WAMP-Receive(-, -) <<
  CHALLENGE::
    [4,
     'cryptosign',
     {'challenge': 'e4b40f72f9604754789d472225483bace926b9668d72c9122545e540d8d98f23',
      'channel_binding': 'tls-unique',
      'pubkey': '4a3838f6fe75251e613329d53fc69b262d5eac97fb1d73bebbaed4015b53c862',
      'signature': 'ce456092998d796533d7ef2bab543300409d161066c9520c9284df6bbfb82947b37fb78d69fd56e5118afec62e35e015c60569af2e18ed92fedc738552242d039a38790e9c94064d89335393d39973c14074cd1008d7266de74c641103e30609'}]
<<

WAMP-Transmit(-, -) >>
  AUTHENTICATE::
    [5,
     '16c89629e72aff3f44661e701341b2221a2fa9d93205826fad85e70d3a8dab70a8f54314c14d470ebeb77a0dd16c833928c01134a52b2e73862b7d3f258b600059ef9181d4370b6d19e7691e9a407f29784315dfc949d4696ce5e1f6535ba73d',
     {}]
>>

WAMP-Receive(-, -) <<
  WELCOME::
    [2,
     869996509191260,
     {'authextra': {'x_cb_node': 'intel-nuci7-30969',
                    'x_cb_peer': 'tcp4:127.0.0.1:59172',
                    'x_cb_pid': 31090,
                    'x_cb_worker': 'worker001'},
      'authid': '0xf5173a6111B2A6B3C20fceD53B2A8405EC142bF6',
      'authmethod': 'cryptosign',
      'authprovider': 'static',
      'authrole': 'user',
      'realm': 'realm1',
      'roles': {'broker': {'features': {'event_retention': True,
                                        'pattern_based_subscription': True,
                                        'publisher_exclusion': True,
                                        'publisher_identification': True,
                                        'session_meta_api': True,
                                        'subscriber_blackwhite_listing': True,
                                        'subscription_meta_api': True,
                                        'subscription_revocation': True}},
                'dealer': {'features': {'call_canceling': True,
                                        'caller_identification': True,
                                        'pattern_based_registration': True,
                                        'progressive_call_results': True,
                                        'registration_meta_api': True,
                                        'registration_revocation': True,
                                        'session_meta_api': True,
                                        'shared_registration': True,
                                        'testament_meta_api': True}}},
      'x_cb_node': 'intel-nuci7-30969',
      'x_cb_peer': 'tcp4:127.0.0.1:59172',
      'x_cb_pid': 31090,
      'x_cb_worker': 'worker001'}]
<<

WAMP-Transmit(869996509191260, 0xf5173a6111B2A6B3C20fceD53B2A8405EC142bF6) >>
  GOODBYE::
    [6, {}, 'wamp.close.normal']
>>

WAMP-Receive(869996509191260, 0xf5173a6111B2A6B3C20fceD53B2A8405EC142bF6) <<
  GOODBYE::
    [6, {}, 'wamp.close.normal']
<<

5.5. Dynamic Authentication API

Write me.¶

5.6. Authorization

WAMP allows user services to integrate seamlessly while enabling Clients to perform Actions, namely, to¶

• register procedures using fully qualified URIs or URI patterns in order to receive invocations¶
• call procedures at (fully qualified) URIs¶
• subscribe to topics using fully qualified URIs or URI patterns in order to receive events¶
• publish events to (fully qualified) URIs¶

Performing these actions requires Clients to have an open Session to the same shared Realm.¶

A Session is established between a Client to a Router, and is initiated by a Client.¶

*Session*s MAY be required to Authenticate access to a Realm hosted by a Router.¶

Authentication is the sequence of operations that allow a Router to verify the identity of a Session, often as a prerequisite to allowing access to resources within a Realm.¶

When the Session authenticates to a Router successfully, the Router will have established the¶

• realm|string,¶
• authrole|string, and¶
• authid|string¶

for that Session running in the Client.¶

The triple (realm, authrole, authid) is called Principal, and a Session is authenticated under that Principal.¶

At any moment, there can be zero, one, or many *Session*s with different session ids authenticated under the same Principal.¶

*Session*s MAY be required to Authorize in order to perform a specific Action on an URI — (U+2014) or an URI pattern — (U+2014) within a Realm.¶

This distinction between Authentication and Authorization follows the established practice called "AAA":¶

• Authentication: Establishes who it is ("subject")¶
• Authorization: Decides within a Realm whether an Action ("operation") on an URI or URI pattern ("object") is allowed for the requesting Principal ("subject")¶
• Accounting: Records, for a Realm, what Action ("operation") on what URI or URI pattern ("object") was requested by which Principal ("subject"), and whether it was allowed or denied¶

6.1. Payload Passthru Mode

In some situations, you may want to reduce the access the router has to the information users transmit, or payload data is presented in some specific format that can not be simply recognized by WAMP router serializer.¶

Here are some use cases:¶

• Using WAMP via gateways to other technologies like MQTT Brokers or AMQP Queues. So the actual payload is, for example, MQTT message that should be delivered to a WAMP topic as is.¶
• Sensitive user data that should be delivered to a target Callee without any possibility of unveiling it in transit.¶

The above use cases can be fulfilled with the Payload Passthru Mode feature. This feature allows:¶

• Specifying additional attributes within CALL, PUBLISH, EVENT, YIELD, RESULT messages to signal the Router to skip payload inspection/conversion.¶
• The forwarding of these additional attributes via INVOCATION and ERROR messages¶
• Encrypting and decrypting payload using cryptographic algorithms.¶
• Providing additional information about payload format and type.¶

Feature Announcement¶

Support for this advanced feature MUST be announced by Callers (role := "caller"), Callees (role := "callee"), Dealers (role := "dealer"), Publishers (role := "publisher"), Subscribers (role := "subscriber") and Brokers (role := "broker") via¶

HELLO.Details.roles.<role>.features.payload_passthru_mode|bool := true¶

Payload Passthru Mode can work only if all three nodes (Caller, Dealer, Callee or Publisher, Broker, Subscriber) support and announced this feature.¶

Cases where a Caller sends a CALL message with payload passthru without announcing it during the HELLO handshake MUST be treated as PROTOCOL ERRORS and underlying WAMP connections must be aborted with the wamp.error.protocol_violation error reason.¶

Cases where a Caller sends a CALL message with payload passthru to a Dealer, the latter not announcing payload passthru support during WELCOME handshake MUST be treated as PROTOCOL ERRORS and the underlying WAMP connections must be aborted with the wamp.error.protocol_violation error reason.¶

Cases where a Caller sends a CALL message with payload passthru to a Dealer that supports this feature, which then must be routed to a Callee which doesn't support payload passthru, MUST be treated as APPLICATION ERRORS and the Dealer MUST respond to the Caller with a wamp.error.feature_not_supported error message.¶

Cases where a Publisher sends a PUBLISH message with payload passthru, without announcing it during HELLO handshake, MUST be treated as PROTOCOL ERRORS and the underlying WAMP connections must be aborted with the wamp.error.protocol_violation error reason.¶

Cases where a Publisher sends a PUBLISH message with payload passthru to a Broker, with the latter not announcing payload passthru support during the WELCOME handshake, MUST be treated as PROTOCOL ERRORS and the underlying WAMP connections must be aborted with the wamp.error.protocol_violation error reason.¶

Cases where a Publisher sends a PUBLISH message with payload passthru to a Broker that supports this feature, which then must be routed to a Subscriber which doesn't support payload passthru, cannot be recognized at the protocol level due to asynchronous message processing and must be covered at the Subscriber side.¶

Cases where a Callee sends a YIELD message with payload passthru without announcing it during the HELLO handshake MUST be treated as PROTOCOL ERRORS and the underlying WAMP connections must be aborted with the wamp.error.protocol_violation error reason.¶

Cases where a Callee sends a YIELD message with payload passthru to a Dealer, with the latter not announcing payload passthru support during the WELCOME handshake, MUST be treated as PROTOCOL ERRORS and the underlying WAMP connections must be aborted with the wamp.error.protocol_violation error reason.¶

Cases where a Callee sends a YIELD message with payload passthru to a Dealer that supports this feature, which then must be routed to the Caller which doesn't support payload passthru, MUST be treated as APPLICATION ERRORS and the Dealer MUST respond to the Callee with a wamp.error.feature_not_supported error message.¶

Message Attributes¶

To use payload passthru mode, the options for CALL, PUBLISH and YIELD messages MUST be extended with additional attributes. These additional attributes must be forwarded via INVOCATION, EVENT and RESULT messages, respectively, as well as ERROR messages in the case of failures.¶

    CALL.Options.ppt_scheme|string
    CALL.Options.ppt_serializer|string
    CALL.Options.ppt_cipher|string
    CALL.Options.ppt_keyid|string
    ---
    INVOCATION.Details.ppt_scheme|string
    INVOCATION.Details.ppt_serializer|string
    INVOCATION.Details.ppt_cipher|string
    INVOCATION.Details.ppt_keyid|string
    ---
    YIELD.Options.ppt_scheme|string
    YIELD.Options.ppt_serializer|string
    YIELD.Options.ppt_cipher|string
    YIELD.Options.ppt_keyid|string
    ---
    RESULT.Details.ppt_scheme|string
    RESULT.Details.ppt_serializer|string
    RESULT.Details.ppt_cipher|string
    RESULT.Details.ppt_keyid|string
    ---
    ERROR.Details.ppt_scheme|string
    ERROR.Details.ppt_serializer|string
    ERROR.Details.ppt_cipher|string
    ERROR.Details.ppt_keyid|string

    PUBLISH.Options.ppt_scheme|string
    PUBLISH.Options.ppt_serializer|string
    PUBLISH.Options.ppt_cipher|string
    PUBLISH.Options.ppt_keyid|string
    ---
    EVENT.Details.ppt_scheme|string
    EVENT.Details.ppt_serializer|string
    EVENT.Details.ppt_cipher|string
    EVENT.Details.ppt_keyid|string
    ---
    ERROR.Options.ppt_scheme|string
    ERROR.Options.ppt_serializer|string
    ERROR.Options.ppt_cipher|string
    ERROR.Options.ppt_keyid|string

ppt_scheme Attribute¶

The ppt_scheme identifies the Payload Schema. It is a required string attribute. For End-2-End Encryption flow this attribute can contain the name or identifier of a key management provider that is known to the target peer, so it can be used with help of additional ppt_* attributes to obtain information about encryption keys. For gateways and external schemas this can contain the name of related technology. The one predefined is mqtt. Others may be introduced later. A Router can recognize that Payload Passthru Mode is in use by checking the existence and non-empty value of this attribute within the options of CALL, PUBLISH and YIELD messages.¶

ppt_serializer Attribute¶

The ppt_serializer attribute is optional. It specifies what serializer was used to encode the payload. It can be a native value to indicate that the incoming data is tunneling through other technologies specified by the ppt_scheme, or it can be ordinary json, msgpack, cbor, flatbuffers data serializers. For some predefined ppt_scheme schemas this option may be omitted as schema defines the concrete serializer. See predefined schemas below.¶

ppt_cipher Attribute¶

The ppt_cipher attribute is optional. It is required if the payload is encrypted. This attribute specifies the cryptographic algorithm that was used to encrypt the payload. It can be xsalsa20poly1305, aes256gcm for now.¶

ppt_keyid Attribute¶

The ppt_keyid attribute is optional. This attribute can contain the encryption key id that was used to encrypt the payload. The ppt_keyid attribute is a string type. The value can be a hex-encoded string, URI, DNS name, Ethereum address, UUID identifier - any meaningful value which allows the target peer to choose a private key without guessing. The format of the value may depend on the ppt_scheme attribute.¶

ppt_ Predefined Schemes¶

MQTT Predefined Scheme¶

*: If ppt_serializer is not provided then it is assuming as native. So no additional serialization will be applied to payload and payload will be serialized within WAMP message with session serializer.¶

End-to-End Encryption Predefined Scheme¶

For End-to-End Encryption flow both peers must support chosen ppt_serializer regardless of their own session serializer.¶

*: The least significant 20 bytes (160 bits) of the SHA256 of the public key (32 bytes) of the data encryption key, as a hex-encoded string with prefix 0x and either uppercase/lowercase alphabetic characters, encoding a checksum according to EIP55.¶

Custom Scheme Example¶

When Payload Passthru Mode is used for gateways to other technologies, such as MQTT Brokers, then the ppt_serializer attribute may be set to the native value. This means that the payload is not to be modified by WAMP peers, nor serialized in any manner, and is delivered as-is from the originating peer. Another possible case is when the ppt_serializer attribute is set to any valid serializer, for example msgpack. In this case the originating WAMP client peer first applies ppt_serializer to serialize the payload (without encryption), then the resulting binary payload is embedded in the WAMP message, the latter having possibly a different serializer depending on the one chosen during WAMP Session establishment.¶

Important Note Regarding JSON Serialization¶

With Payload Passthru Mode, payloads are treated as binary. To send these binary payloads, the WAMP session serializer MUST support byte arrays. Most serialization formats known to WAMP support byte arrays, but JSON does not support them natively. To use Payload Passthru Mode with a JSON serializer, WAMP peers MUST perform the special Binary serialization in JSON. This conversion may have unacceptable overhead, so it is generally advised to use WAMP session serializers with native byte array support, for example, MessagePack, CBOR, or FlatBuffers.¶

Message Structure¶

When Payload Passthru Mode is in use, the message payload MUST be sent as one binary item within Arguments|list, while ArgumentsKw|dict MUST be absent or empty.¶

Since many WAMP messages assume the possibility of simultaneous use of Arguments|list and ArgumentsKw|dict, WAMP client implementations must package arguments into the following hash table and then serialize it and transmit as a single element within Arguments|list.¶

{
    "args": Arguments|list,
    "kwargs": ArgumentsKw|dict
}

This will allow maintaining a single interface for client applications, regardless of whether the Payload Passthru Mode mode, or especially Payload End-to-End Encryption which is built on top of Payload End-to-End Encryption is used or not.¶

Example. Caller-to-Dealer CALL with encryption and key ID¶

    [
        48,
        25471,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "cbor",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evIWpKGQAPdOh0="
        },
        "com.myapp.secret_rpc_for_sensitive_data",
        [Payload|binary]
    ]

Example. Caller-to-Dealer progressive CALL with encryption and key ID.¶

Note that nothing prevents the use of Payload Passthru Mode with other features such as, for example, Progressive Call Results or Progressive Call Invocations.¶

    [
        48,
        25471,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "flatbuffers",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evIWpKGQAPdOh0=",
            "progress": true
        },
        "com.myapp.progressive_rpc_for_sensitive_data",
        [Payload|binary]
    ]

Example. Caller-to-Dealer CALL with MQTT payload. Specifying "ppt_serializer": "native" means that the original MQTT message payload is passed as WAMP payload message as is, without any transcoding.¶

    [
        48,
        25471,
        {
            "ppt_scheme": "mqtt",
            "ppt_serializer": "native"
        },
        "com.myapp.mqtt_processing",
        [Payload|binary]
    ]

Example. Caller-to-Dealer CALL with MQTT payload. Specifying "ppt_scheme": "mqtt" simply indicates that the original source of payload data is received from a related system. Specifying "ppt_serializer": "json" means that the original MQTT message payload was parsed and encoded with the json serializer before embedding it into WAMP message.¶

    [
        48,
        25471,
        {
            "ppt_scheme": "mqtt",
            "ppt_serializer": "json"
        },
        "com.myapp.mqtt_processing",
        [Payload|binary]
    ]

Example. Dealer-to-Callee INVOCATION with encryption and key ID¶

    [
        68,
        35477,
        1147,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "cbor",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evIWpKGQAPdOh0="
        },
        [Payload|binary]
    ]

Example. Dealer-to-Callee INVOCATION with MQTT payload¶

    [
        68,
        35479,
        3344,
        {
            "ppt_scheme": "mqtt",
            "ppt_serializer": "native"
        },
        [Payload|binary]
    ]

Example. Callee-to-Dealer YIELD with encryption and key ID¶

    [
        70,
        87683,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "flatbuffers",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1="
        },
        [Payload|binary]
    ]

Example. Callee-to-Dealer progressive YIELD with encryption and key ID¶

Nothing prevents the use of Payload Passthru Mode with other features such as, for example, Progressive Call Results.¶

    [
        70,
        87683,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "flatbuffers",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1=",
            "progress": true
        },
        [Payload|binary]
    ]

Example. Dealer-to-Caller RESULT with encryption and key ID¶

    [
        50,
        77133,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "flatbuffers",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1="
        },
        [Payload|binary]
    ]

Example. Dealer-to-Caller progressive RESULT with encryption and key ID¶

Nothing prevents the use of Payload Passthru Mode with other features such as, for example, Progressive Call Results.¶

    [
        50,
        77133,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "flatbuffers",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1=",
            "progress": true
        },
        [Payload|binary]
    ]

Example. Callee-to-Dealer ERROR with encryption and key ID¶

    [
        8,
        68,
        87683,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "cbor",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1="
        },
        "com.myapp.invalid_revenue_year",
        [Payload|binary]
    ]

Example. Publishing event to a topic with encryption and key ID¶

    [
        16,
        45677,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "cbor",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1="
        },
        "com.myapp.mytopic1",
        [Payload|binary]
    ]

Example. Receiving event for a topic with encryption and key ID¶

    [
        36,
        5512315355,
        4429313566,
        {
            "ppt_scheme": "wamp",
            "ppt_serializer": "flatbuffers",
            "ppt_cipher": "xsalsa20poly1305",
            "ppt_keyid": "GTtQ37XGJO2O4R8Dvx4AUo8pe61D9evNSpGMDQWdOh1="
        },
        [Payload|binary]
    ]

About Supported Serializers and Cryptographic Ciphers¶

WAMP serves as infrastructure for delivering messages between peers. Regardless of what encryption algorithm and serializer were chosen for Payload Passthru Mode, a Router shall not inspect and analyze the ppt_ options and payload of encrypted messages. The application is responsible for choosing serializers and ciphers known to every peer involved in message processing.¶

6.2. Payload End-to-End Encryption

TBD¶

7.1. RawSocket Transport

WAMP-over-RawSocket is an (alternative) transport for WAMP that uses length-prefixed, binary messages - a message framing different from WebSocket.¶

Compared to WAMP-over-WebSocket, WAMP-over-RawSocket is simple to implement, since there is no need to implement the WebSocket protocol which has some features that make it non-trivial (like a full HTTP-based opening handshake, message fragmentation, masking and variable length integers).¶

WAMP-over-RawSocket has even lower overhead than WebSocket, which can be desirable in particular when running on local connections like loopback TCP or Unix domain sockets. It is also expected to allow implementations in microcontrollers in under 2KB RAM.¶

WAMP-over-RawSocket can run over TCP, TLS, Unix domain sockets or any reliable streaming underlying transport. When run over TLS on the standard port for secure HTTPS (443), it is also able to traverse most locked down networking environments such as enterprise or mobile networks (unless man-in-the-middle TLS intercepting proxies are in use).¶

However, WAMP-over-RawSocket cannot be used with Web browser clients, since browsers do not allow raw TCP connections. Browser extensions would do, but those need to be installed in a browser. WAMP-over-RawSocket also (currently) does not support transport-level compression as WebSocket does provide (permessage-deflate WebSocket extension).¶

Endianess¶

WAMP-over-RawSocket uses network byte order ("big-endian"). That means, given a unsigned 32 bit integer¶

    0x 11 22 33 44

the first octet sent out to (or received from) the wire is 0x11 and the last octet sent out (or received) is 0x44.¶

Here is how you would convert octets received from the wire into an integer in Python:¶

import struct

octets_received = b"\x11\x22\x33\x44"
i = struct.unpack(">L", octets_received)[0]

The integer received has the value 287454020.¶

And here is how you would send out an integer to the wire in Python:¶

octets_to_be_send = struct.pack(">L", i)

The octets to be sent are b"\x11\x22\x33\x44".¶

Handshake: Client-to-Router Request¶

WAMP-over-RawSocket starts with a handshake where the client connecting to a router sends 4 octets:¶

    MSB                                 LSB
    31                                    0
    0111 1111 LLLL SSSS RRRR RRRR RRRR RRRR

The first octet is a magic octet with value 0x7F. This value is chosen to avoid any possible collision with the first octet of a valid HTTP request (see here and here). No valid HTTP request can have 0x7F as its first octet.¶

By using a magic first octet that cannot appear in a regular HTTP request, WAMP-over-RawSocket can be run e.g. on the same TCP listening port as WAMP-over-WebSocket or WAMP-over-LongPoll.¶

The second octet consists of a 4 bit LENGTH field and a 4 bit SERIALIZER field.¶

The LENGTH value is used by the Client to signal the maximum message length of messages it is willing to receive. When the handshake completes successfully, a Router MUST NOT send messages larger than this size.¶

The possible values for LENGTH are:¶

     0: 2**9 octets
     1: 2**10 octets
    ...
    14: 2**23 octets
    15: 2**24 octets

This means a Client can choose the maximum message length between 512 and 16M octets.¶

The SERIALIZER value is used by the Client to request a specific serializer to be used. When the handshake completes successfully, the Client and Router will use the serializer requested by the Client.¶

The possible values for SERIALIZER are:¶

    0: illegal
    1: JSON
    2: MessagePack
    3: CBOR
    4: UBJSON
    5: FlatBuffers
    6 - 15: reserved for future serializers

Here is a Python program that prints all (currently) permissible values for the second octet:¶

SERMAP = {
    1: 'json',
    2: 'msgpack',
    3: 'cbor',
    4: 'ubjson',
    5: 'flatbuffers',
}

# map serializer / max. msg length to RawSocket handshake
# request or success reply (2nd octet)
for ser in SERMAP:
    for l in range(16):
        octet_2 = (l << 4) | ser
        print("serializer: {}, maxlen: {} => 0x{:02x}".format(SERMAP[ser], 2 ** (l + 9), octet_2))

The third and forth octet are reserved and MUST be all zeros for now.¶

Handshake: Router-to-Client Reply¶

After a Client has connected to a Router, the Router will first receive the 4 octets handshake request from the Client.¶

If the first octet differs from 0x7F, it is not a WAMP-over-RawSocket request. Unless the Router also supports other transports on the connecting port (such as WebSocket or LongPoll), the Router MUST fail the connection.¶

Here is an example of how a Router could parse the second octet in a Clients handshake request:¶

# map RawSocket handshake request (2nd octet) to
# serializer / max. msg length
for i in range(256):
    ser_id = i & 0x0f
    if ser_id != 0:
        ser = SERMAP.get(ser_id, 'currently undefined')
        maxlen = 2 ** ((i >> 4) + 9)
        print("{:02x} => serializer: {}, maxlen: {}".format(i, ser, maxlen))
    else:
        print("fail the connection: illegal serializer value")

When the Router is willing to speak the serializer requested by the Client, it will answer with a 4 octets response of identical structure as the Client request:¶

    MSB                                 LSB
    31                                    0
    0111 1111 LLLL SSSS RRRR RRRR RRRR RRRR

Again, the first octet MUST be the value 0x7F. The third and forth octets are reserved and MUST be all zeros for now.¶

In the second octet, the Router MUST echo the serializer value in SERIALIZER as requested by the Client.¶

Similar to the Client, the Router sets the LENGTH field to request a limit on the length of messages sent by the Client.¶

During the connection, Router MUST NOT send messages to the Client longer than the LENGTH requested by the Client, and the Client MUST NOT send messages larger than the maximum requested by the Router in its handshake reply.¶

If a message received during a connection exceeds the limit requested, a Peer MUST fail the connection.¶

When the Router is unable to speak the serializer requested by the Client, or it is denying the Client for other reasons, the Router replies with an error:¶

    MSB                                 LSB
    31                                    0
    0111 1111 EEEE 0000 RRRR RRRR RRRR RRRR

An error reply has 4 octets: the first octet is again the magic 0x7F, and the third and forth octet are reserved and MUST all be zeros for now.¶

The second octet has its lower 4 bits zero'ed (which distinguishes the reply from an success/accepting reply) and the upper 4 bits encode the error:¶

    0: illegal (must not be used)
    1: serializer unsupported
    2: maximum message length unacceptable
    3: use of reserved bits (unsupported feature)
    4: maximum connection count reached
    5 - 15: reserved for future errors

Note that the error code 0 MUST NOT be used. This is to allow storage of error state in a host language variable, while allowing 0 to signal the current state "no error"¶

Here is an example of how a Router might create the second octet in an error response:¶

ERRMAP = {
    0: "illegal (must not be used)",
    1: "serializer unsupported",
    2: "maximum message length unacceptable",
    3: "use of reserved bits (unsupported feature)",
    4: "maximum connection count reached"
}

# map error to RawSocket handshake error reply (2nd octet)
for err in ERRMAP:
    octet_2 = err << 4
    print("error: {} => 0x{:02x}").format(ERRMAP[err], err)

The Client - after having sent its handshake request - will wait for the 4 octets from Router handshake reply.¶

Here is an example of how a Client might parse the second octet in a Router handshake reply:¶

# map RawSocket handshake reply (2nd octet)
for i in range(256):
    ser_id = i & 0x0f
    if ser_id:
        # verify the serializer is the one we requested!
        # if not, fail the connection!
        ser = SERMAP.get(ser_id, 'currently undefined')
        maxlen = 2 ** ((i >> 4) + 9)
        print("{:02x} => serializer: {}, maxlen: {}".format(i, ser, maxlen))
    else:
        err = i >> 4
        print("error: {}".format(ERRMAP.get(err, 'currently undefined')))

Serialization¶

To send a WAMP message, the message is serialized according to the WAMP serializer agreed in the handshake (e.g. JSON, MessagePack, CBOR, UBJSON or FlatBuffers).¶

The length of the serialized messages in octets MUST NOT exceed the maximum requested by the Peer.¶

If the serialized length exceed the maximum requested, the WAMP message can not be sent to the Peer. Handling situations like the latter is left to the implementation.¶

E.g. a Router that is to forward a WAMP EVENT to a Client which exceeds the maximum length requested by the Client when serialized might:¶

• drop the event (not forwarding to that specific client) and track dropped events¶
• prohibit publishing to the topic already¶
• remove the event payload, and send an event with extra information (payload_limit_exceeded = true)¶

Framing¶

The serialized octets for a message to be sent are prefixed with exactly 4 octets.¶

    MSB                                 LSB
    31                                    0
    RRRR XTTT LLLL LLLL LLLL LLLL LLLL LLLL

The three least significant octets constitute an unsigned 24 bit integer that provides the length of transport message payload following, excluding the 4 octets that constitute the prefix.¶

The most significant octet has the following structure¶

    MSB   LSB
    7       0
    RRRR XTTT

The four bits RRRR are reserved for future use and MUST be all zeros for now.¶

X is an extra (25th) bit used to encode the message payload length. This bit is only set when the payload length is exactly 16M octets, with the 24 remaining L bits cleared:¶

    MSB                                 LSB
    31                                    0
    RRRR 1TTT 0000 0000 0000 0000 0000 0000

When the payload length is 16M-1 octets, for example, the prefix would be:¶

    MSB                                 LSB
    31                                    0
    RRRR 0TTT 1111 1111 1111 1111 1111 1111

The three bits TTT encode the type of the transport message:¶

    0: regular WAMP message
    1: PING
    2: PONG
    3-7: reserved

For a regular WAMP message (TTT == 0), the length is the length of the serialized WAMP message: the number of octets after serialization (excluding the 4 octets of the prefix).¶

For a PING message (TTT == 1), the length is the length of the arbitrary payload that follows. A Peer MUST reply to each PING by sending exactly one PONG immediately, and the PONG MUST echo back the payload of the PING exactly.¶

For receiving messages with WAMP-over-RawSocket, a Peer will usually read exactly 4 octets from the incoming stream, decode the transport level message type and payload length, and then receive as many octets as the length was giving.¶

When the transport level message type indicates a regular WAMP message, the transport level message payload is unserialized according to the serializer agreed in the handshake and the processed at the WAMP level.¶

7.2. Message Batching

WAMP-over-Batched-WebSocket is a variant of WAMP-over-WebSocket where multiple WAMP messages are sent in one WebSocket message.¶

Using WAMP message batching can increase wire level efficiency further. In particular when using TLS and the WebSocket implementation is forcing every WebSocket message into a new TLS segment.¶

WAMP-over-Batched-WebSocket is negotiated between Peers in the WebSocket opening handshake by agreeing on one of the following WebSocket subprotocols:¶

• wamp.2.json.batched¶
• wamp.2.msgpack.batched¶
• wamp.2.cbor.batched¶

Batching with JSON works by serializing each WAMP message to JSON as normally, appending the single ASCII control character \30 (record separator) octet 0x1e to each serialized messages, and packing a sequence of such serialized messages into a single WebSocket message:¶

    Serialized JSON WAMP Msg 1 | 0x1e |
        Serialized JSON WAMP Msg 2 | 0x1e | ...

Batching with MessagePack works by serializing each WAMP message to MessagePack as normally, prepending a 32 bit unsigned integer (4 octets in big-endian byte order) with the length of the serialized MessagePack message (excluding the 4 octets for the length prefix), and packing a sequence of such serialized (length-prefixed) messages into a single WebSocket message:¶

    Length of Msg 1 serialization (uint32) |
        serialized MessagePack WAMP Msg 1 | ...

With batched transport, even if only a single WAMP message is to be sent in a WebSocket message, the (single) WAMP message needs to be framed as described above. In other words, a single WAMP message is sent as a batch of length 1. Sending a batch of length 0 (no WAMP message) is illegal and a Peer MUST fail the transport upon receiving such a transport message.¶

7.3. HTTP Longpoll Transport

The Long-Poll Transport is able to transmit a WAMP session over plain old HTTP 1.0/1.1. This is realized by the Client issuing HTTP/POSTs requests, one for sending, and one for receiving. Those latter requests are kept open at the server when there are no messages currently pending to be received.¶

Opening a Session¶

With the Long-Poll Transport, a Client opens a new WAMP session by sending a HTTP/POST request to a well-known URL, e.g.¶

    http://mypp.com/longpoll/open

Here, http://mypp.com/longpoll is the base URL for the Long-Poll Transport and /open is a path dedicated for opening new sessions.¶

The HTTP/POST request SHOULD have a Content-Type header set to application/json and MUST have a request body with a JSON document that is a dictionary:¶

    {
       "protocols": ["wamp.2.json"]
    }

The (mandatory) protocols attribute specifies the protocols the client is willing to speak. The server will chose one from this list when establishing the session or fail the request when no protocol overlap was found.¶

The valid protocols are:¶

• wamp.2.json.batched¶
• wamp.2.json¶
• wamp.2.msgpack.batched¶
• wamp.2.msgpack¶
• wamp.2.cbor.batched¶
• wamp.2.cbor¶

The request path with this and subsequently described HTTP/POST requests MAY contain a query parameter x with some random or sequentially incremented value:¶

http://mypp.com/longpoll/open?x=382913¶

The value is ignored, but may help in certain situations to prevent intermediaries from caching the request.¶

Returned is a JSON document containing a transport ID and the protocol to speak:¶

    {
       "protocol": "wamp.2.json",
       "transport": "kjmd3sBLOUnb3Fyr"
    }

As an implied side-effect, two HTTP endpoints are created¶

    http://mypp.com/longpoll/<transport_id>/receive
    http://mypp.com/longpoll/<transport_id>/send

where transport_id is the transport ID returned from open, e.g.¶

    http://mypp.com/longpoll/kjmd3sBLOUnb3Fyr/receive
    http://mypp.com/longpoll/kjmd3sBLOUnb3Fyr/send

Receiving WAMP Messages¶

The Client will then issue HTTP/POST requests (with empty request body) to¶

    http://mypp.com/longpoll/kjmd3sBLOUnb3Fyr/receive

When there are WAMP messages pending downstream, a request will return with a single WAMP message (unbatched modes) or a batch of serialized WAMP messages (batched mode).¶

The serialization format used is the one agreed during opening the session.¶

The batching uses the same scheme as with wamp.2.json.batched and wamp.2.msgpack.batched transport over WebSocket.¶

Note: In unbatched mode, when there is more than one message pending, there will be at most one message returned for each request. The other pending messages must be retrieved by new requests. With batched mode, all messages pending at request time will be returned in one batch of messages.¶

Sending WAMP Messages¶

For sending WAMP messages, the Client will issue HTTP/POST requests to¶

    http://mypp.com/longpoll/kjmd3sBLOUnb3Fyr/send

with request body being a single WAMP message (unbatched modes) or a batch of serialized WAMP messages (batched mode).¶

The serialization format used is the one agreed during opening the session.¶

The batching uses the same scheme as with wamp.2.json.batched and wamp.2.msgpack.batched transport over WebSocket.¶

Upon success, the request will return with HTTP status code 202 ("no content"). Upon error, the request will return with HTTP status code 400 ("bad request").¶

Closing a Session¶

To orderly close a session, a Client will issue a HTTP/POST to¶

    http://mypp.com/longpoll/kjmd3sBLOUnb3Fyr/close

with an empty request body. Upon success, the request will return with HTTP status code 202 ("no content").¶

7.4. Binary support in JSON

Binary data follows a convention for conversion to JSON strings.¶

A byte array is converted to a JSON string as follows:¶

1. convert the byte array to a Base64 encoded (host language) string¶
2. prepend the string with a \0 character¶
3. serialize the string to a JSON string¶

where Base64 encoding follows Section 4 of [RFC4648].¶

Example¶

Consider the byte array (hex representation):¶

    10e3ff9053075c526f5fc06d4fe37cdb

This will get converted to Base64¶

    EOP/kFMHXFJvX8BtT+N82w==

prepended with \0¶

    \x00EOP/kFMHXFJvX8BtT+N82w==

and serialized to a JSON string¶

    "\\u0000EOP/kFMHXFJvX8BtT+N82w=="

A JSON string is unserialized to either a string or a byte array using the following procedure:¶

1. Unserialize a JSON string to a host language (Unicode) string¶
2. If the string starts with a \0 character, interpret the rest (after the first character) as Base64 and decode to a byte array¶
3. Otherwise, return the Unicode string¶

Below are complete Python and JavaScript code examples for conversion between byte arrays and JSON strings.¶

Python¶

Here is a complete example in Python showing how byte arrays are converted to and from JSON:¶

import os, base64, json, sys, binascii

data_in = os.urandom(16)
print("In:   {}".format(binascii.hexlify(data_in)))

# encoding
encoded = json.dumps('\0' + base64.b64encode(data_in).
                                    decode('ascii'))

print("JSON: {}".format(encoded))

# decoding
decoded = json.loads(encoded)
if type(decoded) == unicode:
   if decoded[0] == '\0':
      data_out = base64.b64decode(decoded[1:])
   else:
      data_out = decoded

print("Out:  {}".format(binascii.hexlify(data_out)))

assert(data_out == data_in)

JavaScript¶

Here is a complete example in JavaScript showing how byte arrays are converted to and from JSON:¶

var data_in = new Uint8Array(new ArrayBuffer(16));

// initialize test data
for (var i = 0; i < data_in.length; ++i) {
   data_in[i] = i;
}
console.log(data_in);

// convert byte array to raw string
var raw_out = '';
for (var i = 0; i < data_in.length; ++i) {
   raw_out += String.fromCharCode(data_in[i]);
}

// base64 encode raw string, prepend with \0
// and serialize to JSON
var encoded = JSON.stringify("\0" + window.btoa(raw_out));
console.log(encoded); // "\u0000AAECAwQFBgcICQoLDA0ODw=="

// unserialize from JSON
var decoded = JSON.parse(encoded);

var data_out;
if (decoded.charCodeAt(0) === 0) {
   // strip first character and decode base64 to raw string
   var raw = window.atob(decoded.substring(1));

   // convert raw string to byte array
   var data_out = new Uint8Array(new ArrayBuffer(raw.length));
   for (var i = 0; i < raw.length; ++i) {
      data_out[i] = raw.charCodeAt(i);
   }
} else {
   data_out = decoded;
}

console.log(data_out);

7.5. Multiplexed Transport

A Transport may support the multiplexing of multiple logical transports over a single "physical" transport.¶

By using such a Transport, multiple WAMP sessions can be transported over a single underlying transport at the same time.¶

As an example, the proposed WebSocket extension "permessage-priority" would allow creating multiple logical Transports for WAMP over a single underlying WebSocket connection.¶

Sessions running over a multiplexed Transport are completely independent: they get assigned different session IDs, may join different realms and each session needs to authenticate itself.¶

Because of above, Multiplexed Transports for WAMP are actually not detailed in the WAMP spec, but a feature of the transport being used.¶

Note: Currently no WAMP transport supports multiplexing. The work on the MUX extension with WebSocket has stalled, and the permessage-priority proposal above is still just a proposal. However, with RawSocket, we should be able to add multiplexing in the the future (with downward compatibility).¶

8.1. WAMP IDL

/// Call args/kwargs for "wamp.session.kill_by_authid"
table SessionKillByAuthid
{
    /// The WAMP authid of the sessions to kill.
    authid: string (wampuri);

    /// A reason URI provided to the killed session(s).
    reason: string (kwarg, wampuri);

    /// A message provided to the killed session(s).
    message: string (kwarg);
}

table WampIds
{
    /// List of WAMP IDs.
    value: [uint64] (wampid);
}

/// UUID (canonical textual representation).
my_field1: string (uuid);

/// UUID (128 bit binary).
my_field2: uint128_t (uuid);

/// An unsigned integer with 128 bits.
struct uint128_t {
    /// Least significand 32 bits.
    w0: uint32;

    /// 2nd significand 32 bits.
    w1: uint32;

    /// 3rd significand 32 bits.
    w2: uint32;

    /// Most significand 32 bits.
    w3: uint32;
}

/// Ethereum address (checksummed HEX encoded address).
my_field1: string (ethadr);

/// Ethereum address (160 bit binary).
my_field2: uint160_t (ethadr);

/// An unsigned integer with 160 bits.
struct uint160_t {
    /// Least significand 32 bits.
    w0: uint32;

    /// 2nd significand 32 bits.
    w1: uint32;

    /// 3rd significand 32 bits.
    w2: uint32;

    /// 4th significand 32 bits.
    w3: uint32;

    /// Most significand 32 bits.
    w4: uint32;
}

rpc_service IWampMeta(type: "interface",
                      uuid: "88711231-3d95-44bc-9464-58d871dd7fd7",
                      wampuri: "wamp")
{
    session_kill_by_authid (SessionKillByAuthid): WampIds (
        type: "procedure",
        wampuri: "wamp.session.kill_by_authid"
    );
}

rpc_service IWampMeta(type: "interface",
                      uuid: "88711231-3d95-44bc-9464-58d871dd7fd7",
                      wampuri: "wamp")
{
    session_kill_by_authid (SessionKillByAuthid): WampIds (
        type: "procedure",
        wampuri: "wamp.session.kill_by_authid"
    );

    session_on_leave (SessionInfo): Void (
        type: "topic",
        wampuri: "wamp.session.on_leave"
    );
}

<TOPIC-METHOD> (<TOPIC-PAYLOAD-TABLE>): Void (
    type: "topic",
    wampuri: <TOPIC-URI>
);

<PROCEDURE-METHOD> (<CALL-PAYLOAD-TABLE>): <CALLRESULT-PAYLOAD-TABLE> (
    type: "procedure",
    wampuri: <PROCEDURE-URI>
);

rpc_service <INTERFACE> (
    type: "interface",
    uuid: <INTERFACE-UUID>,
    wampuri: <INTERFACE-URI-PREFIX>
) {
    /// Method declarations of WAMP Procedures and Topics
}

8.2. Interface Catalogs

Collections of types defined in FlatBuffers IDL are bundled in Interface Catalogs which are just ZIP files with¶

• one catalog.yaml file with catalog metadata¶
• one or more *.bfbs compiled FlatBuffer IDL schemas¶

and optionally¶

• schema source files¶
• image and documentation files¶

unzip -l build/example.zip
Archive:  build/example.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  1980-00-00 00:00   schema/
    14992  1980-00-00 00:00   schema/example2.bfbs
    15088  1980-00-00 00:00   schema/example4.bfbs
    13360  1980-00-00 00:00   schema/example3.bfbs
     8932  1980-00-00 00:00   schema/example1.bfbs
     6520  1980-00-00 00:00   schema/wamp.bfbs
     1564  1980-00-00 00:00   README.md
        0  1980-00-00 00:00   img/
    13895  1980-00-00 00:00   img/logo.png
     1070  1980-00-00 00:00   LICENSE.txt
     1288  1980-00-00 00:00   catalog.yaml
---------                     -------
    76709                     11 files

flatc -o ./schema --binary --schema --bfbs-comments --bfbs-builtins ./src

rpc_service IExample1 (
    type: "interface", uuid: "bf469db0-efea-425b-8de4-24b5770e6241"
) {
    my_procedure1 (TestRequest1): TestResponse1 (
        type: "procedure", wampuri: "com.example.my_procedure1"
    );

    on_something1 (TestEvent1): Void (
        type: "topic", wampuri: "com.example.on_something1"
    );
}

name: example

version: 22.6.1

title: WAMP Example API Catalog

description: An example of a WAMP API catalog.

schemas:
  - schema/example1.bfbs
  - schema/example2.bfbs
  - schema/example3.bfbs
  - schema/example4.bfbs

author: typedef int GmbH

publisher: "0x60CC48BFC44b48A53e793FE4cB50e2d625BABB27"

license: MIT

keywords:
  - wamp
  - sample

homepage: https://wamp-proto.org/

git: https://github.com/wamp-proto/wamp-proto.git

theme:
  background: "#333333"
  text: "#e0e0e0"
  highlight: "#00ccff"
  logo: img/logo.png

stripzip example.zip

openssl sha256 example.zip

8.3. Interface Reflection

Feature status: sketch¶

Reflection denotes the ability of WAMP peers to examine the procedures, topics and errors provided or used by other peers.¶

I.e. a WAMP Caller, Callee, Subscriber or Publisher may be interested in retrieving a machine readable list and description of WAMP procedures and topics it is authorized to access or provide in the context of a WAMP session with a Dealer or Broker.¶

Reflection may be useful in the following cases:¶

• documentation¶
• discoverability¶
• generating stubs and proxies¶

WAMP predefines the following procedures for performing run-time reflection on WAMP peers which act as Brokers and/or Dealers.¶

Predefined WAMP reflection procedures to list resources by type:¶

    wamp.reflection.topic.list
    wamp.reflection.procedure.list
    wamp.reflection.error.list

Predefined WAMP reflection procedures to describe resources by type:¶

    wamp.reflection.topic.describe
    wamp.reflection.procedure.describe
    wamp.reflection.error.describe

A peer that acts as a Broker SHOULD announce support for the reflection API by sending¶

    HELLO.Details.roles.broker.reflection|bool := true

A peer that acts as a Dealer SHOULD announce support for the reflection API by sending¶

    HELLO.Details.roles.dealer.reflection|bool := true

Since Brokers might provide (broker) procedures and Dealers might provide (dealer) topics, both SHOULD implement the complete API above (even if the peer only implements one of Broker or Dealer roles).¶

Reflection Events and Procedures¶

A topic or procedure is defined for reflection:¶

    wamp.reflect.define

A topic or procedure is asked to be described (reflected upon):¶

    wamp.reflect.describe

A topic or procedure has been defined for reflection:¶

    wamp.reflect.on_define

A topic or procedure has been undefined from reflection:¶

    wamp.reflect.on_undefine