Set BPvsAP, BP, AP as TOP-TOP level title.

rfc/text/advanced/ap_02_features.md

@@ -1,16 +1,29 @@
-## Feature Announcement
+# 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 Session Features**
+
+The status of the respective AP feature is marked as follows:
+
+| Status | Description                                                                                                                                                                                              |
+|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| sketch | There is a rough description of an itch to scratch, but the feature use case isn't clear, and there is no protocol proposal at all.                                                                      |
+| alpha  | The feature use case is still fuzzy and/or the feature definition is unclear, but there is at least a protocol level proposal.                                                                           |
+| beta   | The feature use case is clearly defined and the feature definition in the spec is sufficient to write a prototype implementation. The feature definition and details may still be incomplete and change. |
+| stable | The feature definition in the spec is complete and stable and the feature use case is field proven in real applications. There are multiple, interoperable implementations.                              |
+
+
+## Advanced Session Lifecycle
+
+{align="left"}
 | Feature                                       | Status |
 |-----------------------------------------------|--------|
 | [Challenge-response Authentication](#wampcra) | stable |
 | [Ticket authentication](#ticketauth)          | beta   |
 | [Cryptosign authentication](#cryptosignauth)  | beta   |
 
 
-**Advanced PubSub Features**
+## Advanced PubSub Features
 
 {align="left"}
 | Feature                                                   | Status | Publisher | Broker | Subscriber |
@@ -26,7 +39,7 @@ Support for advanced features must be announced by the peers which implement the
 | [(Interface) Topic Reflection](#interface-reflection)     | sketch |           | X      |            |
 
 
-**Advanced RPC Features**
+## Advanced RPC Features
 
 {align="left"}
 | Feature                                                           | Status | Caller | Dealer | Callee |
@@ -45,7 +58,7 @@ Support for advanced features must be announced by the peers which implement the
 | [(Interface) Procedure Reflection](#interface-reflection)         | sketch |        | X      |        |
 
 
-**Other Advanced Features**
+## Other Advanced Features
 
 {align="left"}
 | Feature                                          | Status |
@@ -56,13 +69,3 @@ Support for advanced features must be announced by the peers which implement the
 | [Session Meta API](#session-metapi)              | beta   |
 | [Call Rerouting](#rpc-call-rerouting)            | sketch |
 | [Payload Passthru Mode](#payload-passthru-mode)  | sketch |
-
-
-The status of the respective AP feature is marked as follows:
-
-| Status | Description                                                                                                                                                                                              |
-|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| sketch | There is a rough description of an itch to scratch, but the feature use case isn't clear, and there is no protocol proposal at all.                                                                      |
-| alpha  | The feature use case is still fuzzy and/or the feature definition is unclear, but there is at least a protocol level proposal.                                                                           |
-| beta   | The feature use case is clearly defined and the feature definition in the spec is sufficient to write a prototype implementation. The feature definition and details may still be incomplete and change. |
-| stable | The feature definition in the spec is complete and stable and the feature use case is field proven in real applications. There are multiple, interoperable implementations.                              |

rfc/text/advanced/ap_03_messages.md

@@ -1,33 +1,34 @@
-## Message Definitions
+# Message Definitions
 
 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.
 
-### Session Lifecycle
 
-#### CHALLENGE
+## Advanced Sessions
+
+### CHALLENGE
 
 The `CHALLENGE` message is used with certain Authentication Methods. During authenticated session establishment, a **Router** sends a challenge message.
 
 {align="left"}
         [CHALLENGE, AuthMethod|string, Extra|dict]
 
-#### AUTHENTICATE
+### AUTHENTICATE
 
 The `AUTHENTICATE` message is used with certain Authentication Methods. A **Client** having received a challenge is expected to respond by sending a signature or token.
 
 {align="left"}
         [AUTHENTICATE, Signature|string, Extra|dict]
 
-### Routed Remote Procedure Calls
+## Advanced Remote Procedure Calls
 
-#### CANCEL
+### CANCEL
 
 The `CANCEL` message is used with the Call Canceling advanced feature. A *Caller* can cancel and issued call actively by sending a cancel message to the *Dealer*.
 
 {align="left"}
         [CANCEL, CALL.Request|id, Options|dict]
 
-#### INTERRUPT
+### INTERRUPT
 
 The `INTERRUPT` message is used with the Call Canceling advanced feature. Upon receiving a cancel for a pending call, a *Dealer* will issue an interrupt to the *Callee*.
 

rfc/text/base/base_01_bp_vs_ap.md

@@ -0,0 +1,7 @@
+# Basic vs Advanced Profile
+
+This document first describes a Basic Profile for WAMP in its entirety, before describing an Advanced Profile which extends the basic functionality of WAMP.
+
+The separation into Basic and Advanced Profiles is intended to extend the reach of the protocol. It allows implementations to start out with a minimal, yet operable and useful set of features, and to expand that set from there. It also allows implementations that are tailored for resource-constrained environments, where larger feature sets would not be possible. Here implementers can weigh between resource constraints and functionality requirements, then implement an optimal feature set for the circumstances.
+
+Advanced Profile features are announced during session establishment, so that different implementations can adjust their interactions to fit the commonly supported feature set.

rfc/text/basic.md

@@ -1,19 +1,19 @@
-{{base/base_01_abstract.md}}
+{{base/base_01_bp_vs_ap.md}}
 
-{{base/base_02_introduction.md}}
+{{basic/bp_00_title.md}}
 
-{{base/base_03_building_blocks.md}}
+{{basic/bp_01_introduction.md}}
 
-{{base/base_04_messages.md}}
+{{basic/bp_02_building_blocks.md}}
 
-{{basic/bp_01_messages.md}}
+{{basic/bp_03_messages.md}}
 
-{{basic/bp_02_sessions.md}}
+{{basic/bp_04_sessions.md}}
 
-{{basic/bp_03_publish_subscribe.md}}
+{{basic/bp_05_publish_subscribe.md}}
 
-{{basic/bp_04_remote_procedure_call.md}}
+{{basic/bp_06_remote_procedure_call.md}}
 
-{{basic/bp_05_security_model.md}}
+{{basic/bp_07_security_model.md}}
 
-{{basic/bp_06_uri_reference.md}}
+{{basic/bp_08_uri_reference.md}}

rfc/text/base/base_01_abstract.md → rfc/text/basic/bp_00_title.md

@@ -1,3 +1,3 @@
-# Abstract
+# WAMP Basic Profile
 
 This document defines the Web Application Messaging Protocol (WAMP). WAMP is a routed protocol that provides two messaging patterns: Publish & Subscribe and routed Remote Procedure Calls. It is intended to connect application components in distributed applications. WAMP uses WebSocket as its default transport, but can be transmitted via any other protocol that allows for ordered, reliable, bi-directional, and message-oriented communications.

rfc/text/base/base_02_introduction.md → rfc/text/basic/bp_01_introduction.md

@@ -221,12 +221,3 @@ Note that Peers might implement more than one role: e.g. a Peer might act as Cal
 ### Relationship to WebSocket
 
 WAMP uses WebSocket as its default transport binding, and is a registered WebSocket subprotocol.
-
-
-## Basic vs Advanced Profile
-
-This document first describes a Basic Profile for WAMP in its entirety, before describing an Advanced Profile which extends the basic functionality of WAMP.
-
-The separation into Basic and Advanced Profiles is intended to extend the reach of the protocol. It allows implementations to start out with a minimal, yet operable and useful set of features, and to expand that set from there. It also allows implementations that are tailored for resource-constrained environments, where larger feature sets would not be possible. Here implementers can weigh between resource constraints and functionality requirements, then implement an optimal feature set for the circumstances.
-
-Advanced Profile features are announced during session establishment, so that different implementations can adjust their interactions to fit the commonly supported feature set.

rfc/text/base/base_03_building_blocks.md → rfc/text/basic/bp_02_building_blocks.md

@@ -1,4 +1,4 @@
-# Building Blocks
+## Building Blocks
 
 WAMP is defined with respect to the following building blocks
 
@@ -8,9 +8,9 @@ WAMP is defined with respect to the following building blocks
 
 For each building block, WAMP only assumes a defined set of requirements, which allows to run WAMP variants with different concrete bindings.
 
-## Identifiers
+### Identifiers
 
-### URIs {#uris}
+#### URIs {#uris}
 
 WAMP needs to identify the following persistent resources:
 
@@ -83,7 +83,7 @@ Further, application URIs MUST NOT use `wamp` as a first URI component, since th
 * `wamp.error.procedure_already_exists`
 
 
-### IDs {#ids}
+#### IDs {#ids}
 
 WAMP needs to identify the following ephemeral entities each in the scope noted:
 
@@ -142,7 +142,7 @@ The following is a complete list of usage of IDs in the three categories for all
 * `ERROR.Request` (mirrored original request ID)
 
 
-## Serializers
+### Serializers
 
 WAMP is a message based protocol that requires serialization of messages to octet sequences to be sent out on the wire.
 
@@ -178,7 +178,7 @@ Version 5 or later of MessagePack MUST BE used, since this version is able to di
 With CBOR serialization, each WAMP message is serialized according to the CBOR specification as described in [@!RFC8949].
 
 
-## Transports
+### Transports
 
 WAMP assumes a transport with the following characteristics:
 
@@ -190,7 +190,7 @@ WAMP assumes a transport with the following characteristics:
 There is no required transport or set of transports for WAMP implementations (but each implementation MUST, of course, implement at least one transport). Routers SHOULD implement more than one transport, enabling components using different kinds of transports to connect in an application.
 
 
-### WebSocket Transport
+#### WebSocket Transport
 
 The default transport binding for WAMP is WebSocket ([@!RFC6455]).
 
@@ -213,7 +213,7 @@ With `wamp.2.cbor`, *all* WebSocket messages MUST BE of type **binary** and use
 > To avoid incompatibilities merely due to naming conflicts with WebSocket subprotocol identifiers, implementers SHOULD register identifiers for additional serialization formats with the official WebSocket subprotocol registry.
 
 
-### Transport and Session Lifetime
+#### Transport and Session Lifetime
 
 WAMP implementations MAY choose to tie the lifetime of the underlying transport connection for a WAMP connection to that of a WAMP session, i.e. establish a new transport-layer connection as part of each new session establishment. They MAY equally choose to allow re-use of a transport connection, allowing subsequent WAMP sessions to be established using the same transport connection.
 
@@ -259,7 +259,7 @@ The diagram below illustrates the full transport connection and session lifecycl
         `------'                                    `------'
 
 
-### Protocol Errors {#protocol_errors}
+#### Protocol Errors {#protocol_errors}
 
 WAMP implementations MUST abort sessions (disposing all of their resources such as subscriptions and registrations) on protocol errors caused by offending peers.
 
@@ -288,3 +288,85 @@ In all such cases WAMP implementations:
 1. MUST send an `ABORT` message to the offending peer, having reason `wamp.error.protocol_violation` and optional attributes in ABORT.Details such as a human readable error message.
 2. MUST abort the WAMP session by disposing any allocated subscriptions/registrations for that particular client and without waiting for or processing any messages subsequently received from the peer,
 3. SHOULD also drop the WAMP connection at transport level (recommended to prevent denial of service attacks)
+
+
+### Messages {#messages}
+
+All WAMP messages are a `list` with a first element `MessageType` followed by one or more message type specific elements:
+
+{align="left"}
+        [MessageType|integer, ... one or more message type specific
+            elements ...]
+
+The notation `Element|type` denotes a message element named `Element` of type `type`, where `type` is one of
+
+* `uri`: a string URI as defined in [URIs](#uris)
+* `id`: an integer ID as defined in [IDs](#ids)
+* `integer`: a non-negative integer
+* `string`: a Unicode string, including the empty string
+* `bool`: a boolean value (`true` or `false`) - integers MUST NOT be used instead of boolean value
+* `dict`: a dictionary (map) where keys MUST be strings, keys MUST be unique and serialization order is undefined (left to the serializer being used)
+* `list`: a list (array) where items can be again any of this enumeration
+
+*Example*
+
+A `SUBSCRIBE` message has the following format
+
+{align="left"}
+        [SUBSCRIBE, Request|id, Options|dict, Topic|uri]
+
+Here is an example message conforming to the above format
+
+{align="left"}
+        [32, 713845233, {}, "com.myapp.mytopic1"]
+
+
+#### Extensibility
+
+Some WAMP messages contain `Options|dict` or `Details|dict` elements. This allows for future extensibility and implementations that only provide subsets of functionality by ignoring unimplemented attributes. Keys in `Options` and `Details` MUST be of type `string` and MUST match the regular expression `[a-z][a-z0-9_]{2,}` for WAMP predefined keys. Implementations MAY use implementation-specific keys that MUST match the regular expression `_[a-z0-9_]{3,}`. Attributes unknown to an implementation MUST be ignored.
+
+
+#### No Polymorphism
+
+For a given `MessageType` and number of message elements the expected types are uniquely defined. Hence there are no polymorphic messages in WAMP. This leads to a message parsing and validation control flow that is efficient, simple to implement and simple to code for rigorous message format checking.
+
+
+#### Structure
+
+The application payload (that is call arguments, call results, event payload etc) is always at the end of the message element list. The rationale is: Brokers and Dealers have no need to inspect (parse) the application payload. Their business is call/event routing. Having the application payload at the end of the list allows Brokers and Dealers to skip parsing it altogether. This can improve efficiency and performance.
+
+
+#### Extension Messages
+
+WAMP uses type codes from the core range [0, 255]. Implementations MAY define and use implementation specific messages with message type codes from the extension message range [256, 1023]. For example, a router MAY implement router-to-router communication by using extension messages.
+
+
+#### Empty Arguments and Keyword Arguments
+
+Implementations SHOULD avoid sending empty `Arguments` lists.
+
+E.g. a `CALL` message
+
+{align="left"}
+        [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list]
+
+where `Arguments == []` SHOULD be avoided, and instead
+
+{align="left"}
+        [CALL, Request|id, Options|dict, Procedure|uri]
+
+SHOULD be sent.
+
+Implementations SHOULD avoid sending empty `ArgumentsKw` dictionaries.
+
+E.g. a `CALL` message
+
+{align="left"}
+        [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list, ArgumentsKw|dict]
+
+where `ArgumentsKw == {}` SHOULD be avoided, and instead
+
+{align="left"}
+        [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list]
+
+SHOULD be sent when `Arguments` is non-empty.