[Search] [txt|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00 01 02                                                      
BiDirectional or Server-Initiated HTTP                      T. Oberstein
Internet-Draft                                              Tavendo GmbH
Intended status: Standards Track                      September 27, 2015
Expires: March 30, 2016


           Web Application Messaging Protocol - Basic Profile
                  draft-oberstet-hybi-tavendo-wamp-00

Abstract

   This document defines the basic profile for 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-based
   communication.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on March 30, 2016.

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must



Oberstein                Expires March 30, 2016                 [Page 1]


Internet-Draft                  WAMP - BP                 September 2015


   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Background  . . . . . . . . . . . . . . . . . . . . . . .   4
     1.2.  Protocol Overview . . . . . . . . . . . . . . . . . . . .   5
     1.3.  Design Philosophy . . . . . . . . . . . . . . . . . . . .   5
       1.3.1.  Basic and Advanced Profile  . . . . . . . . . . . . .   6
       1.3.2.  Application Code  . . . . . . . . . . . . . . . . . .   6
       1.3.3.  Router Implementation Specifics . . . . . . . . . . .   7
     1.4.  Relationship to WebSocket . . . . . . . . . . . . . . . .   7
   2.  Conformance Requirements  . . . . . . . . . . . . . . . . . .   7
     2.1.  Terminology and Other Conventions . . . . . . . . . . . .   7
   3.  Realms, Sessions and Transports . . . . . . . . . . . . . . .   8
   4.  Peers and Roles . . . . . . . . . . . . . . . . . . . . . . .   8
     4.1.  Symmetric Messaging . . . . . . . . . . . . . . . . . . .   8
     4.2.  Remote Procedure Call Roles . . . . . . . . . . . . . . .   9
     4.3.  Publish & Subscribe Roles . . . . . . . . . . . . . . . .   9
     4.4.  Peers with multiple Roles . . . . . . . . . . . . . . . .  10
   5.  Building Blocks . . . . . . . . . . . . . . . . . . . . . . .  10
     5.1.  Identifiers . . . . . . . . . . . . . . . . . . . . . . .  10
       5.1.1.  URIs  . . . . . . . . . . . . . . . . . . . . . . . .  10
       5.1.2.  IDs . . . . . . . . . . . . . . . . . . . . . . . . .  13
     5.2.  Serializations  . . . . . . . . . . . . . . . . . . . . .  15
       5.2.1.  JSON  . . . . . . . . . . . . . . . . . . . . . . . .  15
       5.2.2.  MsgPack . . . . . . . . . . . . . . . . . . . . . . .  16
     5.3.  Transports  . . . . . . . . . . . . . . . . . . . . . . .  16
       5.3.1.  WebSocket Transport . . . . . . . . . . . . . . . . .  16
       5.3.2.  Transport and Session Lifetime  . . . . . . . . . . .  17
   6.  Messages  . . . . . . . . . . . . . . . . . . . . . . . . . .  18
     6.1.  Extensibility . . . . . . . . . . . . . . . . . . . . . .  19
     6.2.  No Polymorphism . . . . . . . . . . . . . . . . . . . . .  19
     6.3.  Structure . . . . . . . . . . . . . . . . . . . . . . . .  20
     6.4.  Message Definitions . . . . . . . . . . . . . . . . . . .  20
       6.4.1.  Session Lifecycle . . . . . . . . . . . . . . . . . .  20
       6.4.2.  Publish & Subscribe . . . . . . . . . . . . . . . . .  21
       6.4.3.  Routed Remote Procedure Calls . . . . . . . . . . . .  23
     6.5.  Message Codes and Direction . . . . . . . . . . . . . . .  24
     6.6.  Extension Messages  . . . . . . . . . . . . . . . . . . .  25
     6.7.  Empty Arguments and Keyword Arguments . . . . . . . . . .  25
   7.  Sessions  . . . . . . . . . . . . . . . . . . . . . . . . . .  26
     7.1.  Session Establishment . . . . . . . . . . . . . . . . . .  26
       7.1.1.  HELLO . . . . . . . . . . . . . . . . . . . . . . . .  26
       7.1.2.  WELCOME . . . . . . . . . . . . . . . . . . . . . . .  28
       7.1.3.  ABORT . . . . . . . . . . . . . . . . . . . . . . . .  29



Oberstein                Expires March 30, 2016                 [Page 2]


Internet-Draft                  WAMP - BP                 September 2015


     7.2.  Session Closing . . . . . . . . . . . . . . . . . . . . .  30
       7.2.1.  Difference between ABORT and GOODBYE  . . . . . . . .  31
     7.3.  Agent Identification  . . . . . . . . . . . . . . . . . .  32
   8.  Publish and Subscribe . . . . . . . . . . . . . . . . . . . .  32
     8.1.  Subscribing and Unsubscribing . . . . . . . . . . . . . .  32
       8.1.1.  SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . .  34
       8.1.2.  SUBSCRIBED  . . . . . . . . . . . . . . . . . . . . .  34
       8.1.3.  Subscribe ERROR . . . . . . . . . . . . . . . . . . .  35
       8.1.4.  UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . .  35
       8.1.5.  UNSUBSCRIBED  . . . . . . . . . . . . . . . . . . . .  36
       8.1.6.  Unsubscribe ERROR . . . . . . . . . . . . . . . . . .  36
     8.2.  Publishing and Events . . . . . . . . . . . . . . . . . .  37
       8.2.1.  PUBLISH . . . . . . . . . . . . . . . . . . . . . . .  37
       8.2.2.  PUBLISHED . . . . . . . . . . . . . . . . . . . . . .  38
       8.2.3.  Publish ERROR . . . . . . . . . . . . . . . . . . . .  39
       8.2.4.  EVENT . . . . . . . . . . . . . . . . . . . . . . . .  39
   9.  Remote Procedure Calls  . . . . . . . . . . . . . . . . . . .  40
     9.1.  Registering and Unregistering . . . . . . . . . . . . . .  41
       9.1.1.  REGISTER  . . . . . . . . . . . . . . . . . . . . . .  41
       9.1.2.  REGISTERED  . . . . . . . . . . . . . . . . . . . . .  42
       9.1.3.  Register ERROR  . . . . . . . . . . . . . . . . . . .  42
       9.1.4.  UNREGISTER  . . . . . . . . . . . . . . . . . . . . .  43
       9.1.5.  UNREGISTERED  . . . . . . . . . . . . . . . . . . . .  43
       9.1.6.  Unregister ERROR  . . . . . . . . . . . . . . . . . .  43
     9.2.  Calling and Invocations . . . . . . . . . . . . . . . . .  44
       9.2.1.  CALL  . . . . . . . . . . . . . . . . . . . . . . . .  45
       9.2.2.  INVOCATION  . . . . . . . . . . . . . . . . . . . . .  46
       9.2.3.  YIELD . . . . . . . . . . . . . . . . . . . . . . . .  47
       9.2.4.  RESULT  . . . . . . . . . . . . . . . . . . . . . . .  48
       9.2.5.  Invocation ERROR  . . . . . . . . . . . . . . . . . .  49
       9.2.6.  Call ERROR  . . . . . . . . . . . . . . . . . . . . .  50
     9.3.  Predefined URIs . . . . . . . . . . . . . . . . . . . . .  51
     9.4.  Interaction . . . . . . . . . . . . . . . . . . . . . . .  51
       9.4.1.  Session Close . . . . . . . . . . . . . . . . . . . .  52
     9.5.  Authorization . . . . . . . . . . . . . . . . . . . . . .  52
     9.6.  Ordering Guarantees . . . . . . . . . . . . . . . . . . .  53
       9.6.1.  Publish & Subscribe Ordering  . . . . . . . . . . . .  53
       9.6.2.  Remote Procedure Call Ordering  . . . . . . . . . . .  53
     9.7.  Security Model  . . . . . . . . . . . . . . . . . . . . .  54
       9.7.1.  Transport Encryption and Integrity  . . . . . . . . .  54
       9.7.2.  Router Authentication . . . . . . . . . . . . . . . .  54
       9.7.3.  Client Authentication . . . . . . . . . . . . . . . .  55
     9.8.  Binary conversion of JSON Strings . . . . . . . . . . . .  56
       9.8.1.  Python  . . . . . . . . . . . . . . . . . . . . . . .  57
       9.8.2.  JavaScript  . . . . . . . . . . . . . . . . . . . . .  57
   10. Security Considerations . . . . . . . . . . . . . . . . . . .  58
   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  59
   12. Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  59



Oberstein                Expires March 30, 2016                 [Page 3]


Internet-Draft                  WAMP - BP                 September 2015


   13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  59
   14. References  . . . . . . . . . . . . . . . . . . . . . . . . .  59
     14.1.  Normative References . . . . . . . . . . . . . . . . . .  59
     14.2.  Informative References . . . . . . . . . . . . . . . . .  59
     14.3.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  59
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  59

1.  Introduction

1.1.  Background

   _This section is non-normative._

   The WebSocket protocol brought bi-directional real-time connections
   to the browser.  This defines an API at the message level, requiring
   users who want to use WebSocket connections in their applications to
   define any semantics on top of it.

   The Web Application Messaging Protocl (WAMP) was initially defined as
   WebSocket protocol at the technical level, and is intended to provide
   application developers with the semantics they need to handle
   messaging between components in distributed applications.

   WAMP is a routed protocol, with all components connecting to a WAMP
   router.

   WAMP provides two messaging patterns: Publish & Subscribe and routed
   Remote Procedure calls.

   Publish & Subscribe is an established messaging pattern where
   components inform the router that they want to receive information on
   a topic (they suscribe to the topic).  A component can then publish
   to this topic, and the router distributes events to all subscribers.

   With routed Remote Procedure calls, the decoupling of the Publish &
   Subscribe pattern is applied to Remote Procedure Calls: a component
   announces to the router that it provides a certain procedure,
   identified by a procedure name.  Other components can then call the
   procedure, with the router invoking the procedure on the registering
   component, receiving the result for this, and forwarding this to the
   caller.

   Routed Remote Procedure Calls transfer the decoupling of the Publish
   & Subscribe pattern to Remote Procedure Calls.  A caller is no longer
   required to have knowledge of the Callee, it merely needs to know the
   identifier for the procedure it wants to call.  There is also no
   longer a need for a direct connection between the caller and the
   callee, since all traffic is routed.  This enables calling procedures



Oberstein                Expires March 30, 2016                 [Page 4]


Internet-Draft                  WAMP - BP                 September 2015


   in components which are not reachable externally, e.g. on a NATted
   connection, but which can establish an outgoing connection to the
   WAMP router.

   Combining these two patterns into a single protocol allows a single
   protocol to be used for the entire messaging requirements of an
   application, reducing complexity in the technology stack and
   networking overheads.

   While WAMP was originally specified to run over WebSocket, it can run
   over any transport which is message-based, ordered, reliable and bi-
   directional.

1.2.  Protocol Overview

   _This section is non-normative._

   For each of the two messaging patterns, three roles are defined:

   For PubSub, there are Subscribers and Publishers, which are connected
   through a Broker.

   For routed Remote Procedure Calls there are Callers and Callees,
   which are connected through a Dealer.

   WAMP Connections are established by Clients to a Router.  Connections
   can use any transport which is message-based, ordered, reliable and
   bi-directional, with WebSocket as the default transport.

   WAMP Sessions are established using a WAMP Connection.  A WAMP
   Session connects to a Realm on a Router.  Routing occurs only between
   WAMP Sessions connected to the same realm.

   o  extend me -

1.3.  Design Philosophy

   _This section is non-normative._

   WAMP was designed to be performant, safe and easy to implement.  Its
   entire design was drive by a implement, get feedback, adjust cycle.

   A first version of the protocol was publicly released in March 2012.
   The intention was to gain insight through implementation and use, and
   integrate these into a second version of the protocol, where there
   would be no regard for compatibility between the two versions.
   Several interoperable, independent implementations were released, and
   feedback from the implementers and users was collected.



Oberstein                Expires March 30, 2016                 [Page 5]


Internet-Draft                  WAMP - BP                 September 2015


   The second version of the protocol, which this RFC covers, integrates
   this feedback.  Routed Remote Procedure Calls are one outcome of
   this, where the first version of the protocol only allowed to call
   functionality implemented in the router.  A connected outcome was the
   strict separation of routing and application functionality (see
   below).

   While WAMP was originally developed to use WebSocket as a transport,
   and JSON for serialization, experience in the field showed that other
   transports and serialization formats were better suited to some use
   cases.  As an example, with the use of WAMP in the Internet of Things
   sphere, resource constraints play a much larger role than in the
   browser, so any reduction in resource use of WAMP implementations
   counts.  This lead to the decoupling of WAMP from any particular
   transport or serialization, and the establishment of minimum
   requirements for each.

1.3.1.  Basic and Advanced Profile

   This specification is for a necessary basic set of features which
   allow WAMP to function, and which is referred to as the WAMP Basic
   Profile.

   The specification of additional features is still ongoing.  The
   standardization of such features will be through a separate, future
   document.

1.3.2.  Application Code

   WAMP is designed for application code to run inside _Clients_, i.e.
   _Peers_ of the roles _Callee_, _Caller_, _Publisher_, and
   _Subscriber_.

   _Routers_, i.e. _Peers_ of the roles _Brokers_ and _Dealers_ are
   responsible for *generic call and event routing* and do not run
   application code.

   This allows to transparently exchange _Broker_ and _Dealer_
   implementations without affecting the application and to distribute
   and deploy application components flexibly.

      Note that a *program* that implements e.g. the _Dealer_ role might
      at the same time implement e.g. a built-in _Callee_. It is the
      _Dealer_ and _Broker_ that are generic, not the program.







Oberstein                Expires March 30, 2016                 [Page 6]


Internet-Draft                  WAMP - BP                 September 2015


1.3.3.  Router Implementation Specifics

   This specification only deals with the protocol level for a basic
   profile.  Specific WAMP _Broker_ and _Dealer_ implementations might
   differ in aspects such as:

   o  support for WAMP Advanced Profile

   o  router networks (clustering and federation)

   o  authentication and authorization schemes

   o  message persistence

   o  management and monitoring

   The definition and documentation of implementation specific _Router_
   features like the above is outside the scope of this document.

1.4.  Relationship to WebSocket

   WAMP uses WebSocket as its default transport binding, and is a
   registered WebSocket subprotocol.

2.  Conformance Requirements

   All diagrams, examples, and notes in this specification are non-
   normative, as are all sections explicitly marked non-normative.
   Everything else in this specification is normative.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

   Requirements phrased in the imperative as part of algorithms (such as
   "strip any leading space characters" or "return false and abort these
   steps") are to be interpreted with the meaning of the key word
   ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm.

   Conformance requirements phrased as algorithms or specific steps MAY
   be implemented in any manner, so long as the end result is
   equivalent.

2.1.  Terminology and Other Conventions

   Key terms such as named algorithms or definitions are indicated like
   _this_.




Oberstein                Expires March 30, 2016                 [Page 7]


Internet-Draft                  WAMP - BP                 September 2015


3.  Realms, Sessions and Transports

   A _Realm_ is a WAMP routing and administrative domain, optionally
   protected by authentication and authorization.  -- extend --

   A _Session_ is a transient conversation between two _Peers_ attached
   to a _Realm_ and running over a _Transport_.

   A _Transport_ connects two WAMP _Peers_ and provides a channel over
   which WAMP messages for a WAMP _Session_ can flow in both directions.

   WAMP can run over any _transport_ which is message-based,
   bidirectional, reliable and ordered.

   The default transport for WAMP is WebSocket [RFC6455], where WAMP is
   an officially registered [1] subprotocol.

4.  Peers and Roles

   A WAMP _Session_ connects two _Peers_, a _Client_ and a _Router_.
   Each WAMP _Peer_ can implement one or more roles.

   A _Client_ can implement any combination of the _Roles_:

   o  _Callee_

   o  _Caller_

   o  _Publisher_

   o  _Subscriber_

   and a _Router_ can implement either or both of the _Roles_:

   o  _Dealer_

   o  _Broker_

      This document describes WAMP as in client-to-router communication.
      Direct client-to-client communication is not supported by WAMP.
      Router-to-router communication MAY be defined by a specific router
      implementation.

4.1.  Symmetric Messaging

   It is important to note that though the establishment of a
   _Transport_ might have a inherent asymmetry (like a TCP client
   establishing a WebSocket connection to a server), and _Clients_



Oberstein                Expires March 30, 2016                 [Page 8]


Internet-Draft                  WAMP - BP                 September 2015


   establish WAMP sessions by attaching to _Realms_ on _Routers_, WAMP
   itself is designed to be fully symmetric for application components.

   After the transport and a session have been established, any
   application component may act as _Caller_, _Callee_, _Publisher_ and
   _Subscriber_ at the same time.  And _Routers_ provide the fabric on
   top of which WAMP runs a symmetric application messaging service.

4.2.  Remote Procedure Call Roles

   The Remote Procedure Call messaging pattern involves peers of three
   different roles:

   o  _Callee (Client)_

   o  _Caller (Client)_

   o  _Dealer (Router)_

   A _Caller_ issues calls to remote procedures by providing the
   procedure URI and any arguments for the call.  The _Callee_ will
   execute the procedure using the supplied arguments to the call and
   return the result of the call to the _Caller_.

   _Callees_ register procedures they provide with _Dealers_. _Callers_
   initiate procedure calls first to _Dealers_. _Dealers_ route calls
   incoming from _Callers_ to _Callees_ implementing the procedure
   called, and route call results back from _Callees_ to _Callers_.

   The _Caller_ and _Callee_ will usually run application code, while
   the _Dealer_ works as a generic router for remote procedure calls
   decoupling _Callers_ and _Callees_.

4.3.  Publish & Subscribe Roles

   The Publish & Subscribe messaging pattern involves peers of three
   different roles:

   o  _Subscriber (Client)_

   o  _Publisher (Client)_

   o  _Broker (Router)_

   A _Publishers_ publishes events to topics by providing the topic URI
   and any payload for the event. _Subscribers_ of the topic will
   receive the event together with the event payload.




Oberstein                Expires March 30, 2016                 [Page 9]


Internet-Draft                  WAMP - BP                 September 2015


   _Subscribers_ subscribe to topics they are interested in with
   _Brokers_. _Publishers_ initiate publication first at _Brokers_.
   _Brokers_ route events incoming from _Publishers_ to _Subscribers_
   that are subscribed to respective topics.

   The _Publisher_ and _Subscriber_ will usually run application code,
   while the _Broker_ works as a generic router for events decoupling
   _Publishers_ from _Subscribers_.

4.4.  Peers with multiple Roles

   Note that _Peers_ might implement more than one role: e.g. a _Peer_
   might act as _Caller_, _Publisher_ and _Subscriber_ at the same time.
   Another _Peer_ might act as both a _Broker_ and a _Dealer_.

5.  Building Blocks

   WAMP is defined with respect to the following building blocks

   1.  Identifiers

   2.  Serializations

   3.  Transports

   For each building block, WAMP only assumes a defined set of
   requirements, which allows to run WAMP variants with different
   concrete bindings.

5.1.  Identifiers

5.1.1.  URIs

   WAMP needs to identify the following _persistent_ resources:

   1.  Topics

   2.  Procedures

   3.  Errors

   These are identified in WAMP using _Uniform Resource Identifiers_
   (URIs) [RFC3986] that MUST be Unicode strings.

      When using JSON as WAMP serialization format, URIs (as other
      strings) are transmitted in UTF-8 [RFC3629] encoding.

   _Examples_



Oberstein                Expires March 30, 2016                [Page 10]


Internet-Draft                  WAMP - BP                 September 2015


   o  "com.myapp.mytopic1"

   o  "com.myapp.myprocedure1"

   o  "com.myapp.myerror1"

   The URIs are understood to form a single, global, hierarchical
   namespace for WAMP.

      The namespace is unified for topics, procedures and errors - these
      different resource types do NOT have separate namespaces.

   To avoid resource naming conflicts, the package naming convention
   from Java is used, where URIs SHOULD begin with (reversed) domain
   names owned by the organization defining the URI.

5.1.1.1.  Relaxed/Loose URIs

   URI components (the parts between two "."s, the head part up to the
   first ".", the tail part after the last ".") MUST NOT contain a ".",
   "#" or whitespace characters and MUST NOT be empty (zero-length
   strings).

      The restriction not to allow "." in component strings is due to
      the fact that "." is used to separate components, and WAMP
      associates semantics with resource hierarchies, such as in
      pattern-based subscriptions that may be part of an Advanced
      Profile.  The restriction not to allow empty (zero-length) strings
      as components is due to the fact that this may be used to denote
      wildcard components with pattern-based subscriptions and
      registrations in an Advanced Profile.  The character "#" is not
      allowed since this is reserved for internal use by _Dealers_ and
      _Brokers_.

   As an example, the following regular expression could be used in
   Python to check URIs according to above rules:

       <CODE BEGINS>
           ## loose URI check disallowing empty URI components
           pattern = re.compile(r"^([^\s\.#]+\.)*([^\s\.#]+)$")
       <CODE ENDS>

   When empty URI components are allowed (this may the case for specific
   messages that are part of an Advanced Profile), this following
   regular expression can be used (shown used in Python):






Oberstein                Expires March 30, 2016                [Page 11]


Internet-Draft                  WAMP - BP                 September 2015


       <CODE BEGINS>
           ## loose URI check allowing empty URI components
           pattern = re.compile(r"^(([^\s\.#]+\.)|\.)*([^\s\.#]+)?$")
       <CODE ENDS>

5.1.1.2.  Strict URIs

   While the above rules MUST be followed, following a stricter URI rule
   is recommended: URI components SHOULD only contain letters, digits
   and "_".

   As an example, the following regular expression could be used in
   Python to check URIs according to the above rules:

       <CODE BEGINS>
           ## strict URI check disallowing empty URI components
           pattern = re.compile(r"^([0-9a-z_]+\.)*([0-9a-z_]+)$")
       <CODE ENDS>

   When empty URI components are allowed (this may the case for specific
   messages that are part of an Advanced Profile), the following regular
   expression can be used (shown in Python):

       <CODE BEGINS>
           ## strict URI check allowing empty URI components
           pattern = re.compile(r"^(([0-9a-z_]+\.)|\.)*([0-9a-z_]+)?$")
       <CODE ENDS>

      Following the suggested regular expression will make URI
      components valid identifiers in most languages (modulo URIs
      starting with a digit and language keywords) and the use of lower-
      case only will make those identifiers unique in languages that
      have case-insensitive identifiers.  Following this suggestion can
      allow implementations to map topics, procedures and errors to the
      language environment in a completely transparent way.

5.1.1.3.  Reserved URIs

   Further, application URIs MUST NOT use "wamp" as a first URI
   component, since this is reserved for URIs predefined with the WAMP
   protocol itself.

   _Examples_

   o  "wamp.error.not_authorized"

   o  "wamp.error.procedure_already_exists"




Oberstein                Expires March 30, 2016                [Page 12]


Internet-Draft                  WAMP - BP                 September 2015


5.1.2.  IDs

   WAMP needs to identify the following ephemeral entities each in the
   scope noted:

   1.  Sessions (_global scope_)

   2.  Publications (_global scope_)

   3.  Subscriptions (_router scope_)

   4.  Registrations (_router scope_)

   5.  Requests (_session scope_)

   These are identified in WAMP using IDs that are integers between
   (inclusive) *0* and *2^53* (9007199254740992):

   o  IDs in the _global scope_ MUST be drawn _randomly_ from a _uniform
      distribution_ over the complete range [0, 2^53]

   o  IDs in the _router scope_ can be chosen freely by the specific
      router implementation

   o  IDs in the _session scope_ SHOULD be incremented by 1 beginning
      with 1 (for each direction - _Client-to-Router_ and _Router-to-
      Client_)

      The reason to choose the specific upper bound is that 2^53 is the
      largest integer such that this integer and _all_ (positive)
      smaller integers can be represented exactly in IEEE-754 doubles.
      Some languages (e.g.  JavaScript) use doubles as their sole number
      type.  Most languages do have signed and unsigned 64-bit integer
      types that both can hold any value from the specified range.

   The following is a complete list of usage of IDs in the three
   categories for all WAMP messages.  For a full definition of these see
   Section 6.

5.1.2.1.  Global Scope IDs

   o  "WELCOME.Session"

   o  "PUBLISHED.Publication"

   o  "EVENT.Publication"





Oberstein                Expires March 30, 2016                [Page 13]


Internet-Draft                  WAMP - BP                 September 2015


5.1.2.2.  Router Scope IDs

   o  "EVENT.Subscription"

   o  "SUBSCRIBED.Subscription"

   o  "REGISTERED.Registration"

   o  "UNSUBSCRIBE.Subscription"

   o  "UNREGISTER.Registration"

   o  "INVOCATION.Registration"

5.1.2.3.  Session Scope IDs

   o  "ERROR.Request"

   o  "PUBLISH.Request"

   o  "PUBLISHED.Request"

   o  "SUBSCRIBE.Request"

   o  "SUBSCRIBED.Request"

   o  "UNSUBSCRIBE.Request"

   o  "UNSUBSCRIBED.Request"

   o  "CALL.Request"

   o  "CANCEL.Request"

   o  "RESULT.Request"

   o  "REGISTER.Request"

   o  "REGISTERED.Request"

   o  "UNREGISTER.Request"

   o  "UNREGISTERED.Request"

   o  "INVOCATION.Request"

   o  "INTERRUPT.Request"




Oberstein                Expires March 30, 2016                [Page 14]


Internet-Draft                  WAMP - BP                 September 2015


   o  "YIELD.Request"

5.2.  Serializations

   WAMP is a message based protocol that requires serialization of
   messages to octet sequences to be sent out on the wire.

   A message _serialization_ format is assumed that (at least) provides
   the following types:

   o  "integer" (non-negative)

   o  "string" (UTF-8 encoded Unicode)

   o  "bool"

   o  "list"

   o  "dict" (with string keys)

      WAMP _itself_ only uses the above types, e.g. it does not use the
      JSON data types "number" (non-integer) and "null".  The
      _application payloads_ transmitted by WAMP (e.g. in call arguments
      or event payloads) may use other types a concrete serialization
      format supports.

   There is no required serialization or set of serializations for WAMP
   implementations (but each implementation MUST, of course, implement
   at least one serialization format).  Routers SHOULD implement more
   than one serialization format, enabling components using different
   kinds of serializations to connect to each other.

   WAMP defines two bindings for message _serialization_:

   1.  JSON

   2.  MsgPack

   Other bindings for _serialization_ may be defined in future WAMP
   versions.

5.2.1.  JSON

   With JSON serialization, each WAMP message is serialized according to
   the JSON specification as described in RFC4627.

   Further, binary data follows a convention for conversion to JSON
   strings.  For details see the Appendix.



Oberstein                Expires March 30, 2016                [Page 15]


Internet-Draft                  WAMP - BP                 September 2015


5.2.2.  MsgPack

   With MsgPack serialization, each WAMP message is serialized according
   to the MsgPack specification.

      Version 5 or later of MsgPack MUST BE used, since this version is
      able to differentiate between strings and binary values.

5.3.  Transports

   WAMP assumes a _transport_ with the following characteristics:

   1.  message-based

   2.  reliable

   3.  ordered

   4.  bidirectional (full-duplex)

   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.

5.3.1.  WebSocket Transport

   The default transport binding for WAMP is WebSocket.

   As a default, WAMP messages are transmitted as WebSocket messages:
   each WAMP message is transmitted as a separate WebSocket message (not
   WebSocket frame).  A *batched mode* where multiple WAMP messages are
   transmitted via single WebSocket message may be defined as part of an
   Advanced Profile.

   The WAMP protocol MUST BE negotiated during the WebSocket opening
   handshake between _Peers_ using the WebSocket subprotocol negotiation
   mechanism.

   WAMP uses the following WebSocket subprotocol identifiers for
   unbatched modes:

   o  "wamp.2.json"

   o  "wamp.2.msgpack"





Oberstein                Expires March 30, 2016                [Page 16]


Internet-Draft                  WAMP - BP                 September 2015


   With "wamp.2.json", _all_ WebSocket messages MUST BE of type *text*
   (UTF8 encoded payload) and use the JSON message serialization.

   With "wamp.2.msgpack", _all_ WebSocket messages MUST BE of type
   *binary* and use the MsgPack message serialization.

      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.

5.3.2.  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.

   The diagram below illustrates the full transport connection and
   session lifecycle for an implementation which uses WebSocket over TCP
   as the transport and allows the re-use of a transport connection.




























Oberstein                Expires March 30, 2016                [Page 17]


Internet-Draft                  WAMP - BP                 September 2015


       ,------.                                    ,------.
       | Peer |                                    | Peer |
       `--+---'                                    `--+---'

                         TCP established
          |<----------------------------------------->|
          |                                           |
          |               TLS established             |
          |+<--------------------------------------->+|
          |+                                         +|
          |+           WebSocket established         +|
          |+|<------------------------------------->|+|
          |+|                                       |+|
          |+|            WAMP established           |+|
          |+|+<----------------------------------->+|+|
          |+|+                                     +|+|
          |+|+                                     +|+|
          |+|+            WAMP closed              +|+|
          |+|+<----------------------------------->+|+|
          |+|                                       |+|
          |+|                                       |+|
          |+|            WAMP established           |+|
          |+|+<----------------------------------->+|+|
          |+|+                                     +|+|
          |+|+                                     +|+|
          |+|+            WAMP closed              +|+|
          |+|+<----------------------------------->+|+|
          |+|                                       |+|
          |+|           WebSocket closed            |+|
          |+|<------------------------------------->|+|
          |+                                         +|
          |+              TLS closed                 +|
          |+<--------------------------------------->+|
          |                                           |
          |               TCP closed                  |
          |<----------------------------------------->|

       ,--+---.                                    ,--+---.
       | Peer |                                    | Peer |
       `------'                                    `------'

6.  Messages

   All WAMP messages are a "list" with a first element "MessageType"
   followed by one or more message type specific elements:

       [MessageType|integer, ... one or more message type specific
           elements ...]



Oberstein                Expires March 30, 2016                [Page 18]


Internet-Draft                  WAMP - BP                 September 2015


   The notation "Element|type" denotes a message element named "Element"
   of type "type", where "type" is one of

   o  "uri": a string URI as defined in Section 5.1.1

   o  "id": an integer ID as defined in Section 5.1.2

   o  "integer": a non-negative integer

   o  "string": a Unicode string, including the empty string

   o  "bool": a boolean value ("true" or "false") - integers MUST NOT be
      used instead of boolean value

   o  "dict": a dictionary (map) where keys MUST be strings, keys MUST
      be unique and serialization order is undefined (left to the
      serializer being used)

   o  "list": a list (array) where items can be again any of this
      enumeration

   _Example_

   A "SUBSCRIBE" message has the following format

       [SUBSCRIBE, Request|id, Options|dict, Topic|uri]

   Here is an example message conforming to the above format

       [32, 713845233, {}, "com.myapp.mytopic1"]

6.1.  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.

6.2.  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




Oberstein                Expires March 30, 2016                [Page 19]


Internet-Draft                  WAMP - BP                 September 2015


   control flow that is efficient, simple to implement and simple to
   code for rigorous message format checking.

6.3.  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.

6.4.  Message Definitions

   WAMP defines the following messages that are explained in detail in
   the following sections.

   The messages concerning the WAMP session itself are mandatory for all
   _Peers_, i.e. a _Client_ MUST implement "HELLO", "ABORT" and
   "GOODBYE", while a _Router_ MUST implement "WELCOME", "ABORT" and
   "GOODBYE".

   All other messages are mandatory _per role_, i.e. in an
   implementation that only provides a _Client_ with the role of
   _Publisher_ MUST additionally implement sending "PUBLISH" and
   receiving "PUBLISHED" and "ERROR" messages.

6.4.1.  Session Lifecycle

6.4.1.1.  HELLO

   Sent by a _Client_ to initiate opening of a WAMP session to a
   _Router_ attaching to a _Realm_.

       [HELLO, Realm|uri, Details|dict]

6.4.1.2.  WELCOME

   Sent by a _Router_ to accept a _Client_. The WAMP session is now
   open.

       [WELCOME, Session|id, Details|dict]








Oberstein                Expires March 30, 2016                [Page 20]


Internet-Draft                  WAMP - BP                 September 2015


6.4.1.3.  ABORT

   Sent by a _Peer_ to abort the opening of a WAMP session.  No response
   is expected.

     [ABORT, Details|dict, Reason|uri]

6.4.1.4.  GOODBYE

   Sent by a _Peer_ to close a previously opened WAMP session.  Must be
   echo'ed by the receiving _Peer_.

       [GOODBYE, Details|dict, Reason|uri]

6.4.1.5.  ERROR

   Error reply sent by a _Peer_ as an error response to different kinds
   of requests.

       [ERROR, REQUEST.Type|int, REQUEST.Request|id, Details|dict,
           Error|uri]

       [ERROR, REQUEST.Type|int, REQUEST.Request|id, Details|dict,
           Error|uri, Arguments|list]

       [ERROR, REQUEST.Type|int, REQUEST.Request|id, Details|dict,
           Error|uri, Arguments|list, ArgumentsKw|dict]

6.4.2.  Publish & Subscribe

6.4.2.1.  PUBLISH

   Sent by a _Publisher_ to a _Broker_ to publish an event.

       [PUBLISH, Request|id, Options|dict, Topic|uri]

       [PUBLISH, Request|id, Options|dict, Topic|uri,
           Arguments|list]

       [PUBLISH, Request|id, Options|dict, Topic|uri,
           Arguments|list, ArgumentsKw|dict]

6.4.2.2.  PUBLISHED

   Acknowledge sent by a _Broker_ to a _Publisher_ for acknowledged
   publications.

       [PUBLISHED, PUBLISH.Request|id, Publication|id]



Oberstein                Expires March 30, 2016                [Page 21]


Internet-Draft                  WAMP - BP                 September 2015


6.4.2.3.  SUBSCRIBE

   Subscribe request sent by a _Subscriber_ to a _Broker_ to subscribe
   to a topic.

       [SUBSCRIBE, Request|id, Options|dict, Topic|uri]

6.4.2.4.  SUBSCRIBED

   Acknowledge sent by a _Broker_ to a _Subscriber_ to acknowledge a
   subscription.

       [SUBSCRIBED, SUBSCRIBE.Request|id, Subscription|id]

6.4.2.5.  UNSUBSCRIBE

   Unsubscribe request sent by a _Subscriber_ to a _Broker_ to
   unsubscribe a subscription.

       [UNSUBSCRIBE, Request|id, SUBSCRIBED.Subscription|id]

6.4.2.6.  UNSUBSCRIBED

   Acknowledge sent by a _Broker_ to a _Subscriber_ to acknowledge
   unsubscription.

       [UNSUBSCRIBED, UNSUBSCRIBE.Request|id]

6.4.2.7.  EVENT

   Event dispatched by _Broker_ to _Subscribers_ for subscriptions the
   event was matching.

       [EVENT, SUBSCRIBED.Subscription|id, PUBLISHED.Publication|id,
           Details|dict]

       [EVENT, SUBSCRIBED.Subscription|id, PUBLISHED.Publication|id,
           Details|dict, PUBLISH.Arguments|list]

       [EVENT, SUBSCRIBED.Subscription|id, PUBLISHED.Publication|id,
           Details|dict, PUBLISH.Arguments|list,
           PUBLISH.ArgumentsKw|dict]

      An event is dispatched to a _Subscriber_ for a given
      "Subscription|id" _only once_. On the other hand, a _Subscriber_
      that holds subscriptions with different "Subscription|id"s that
      all match a given event will receive the event on each matching
      subscription.



Oberstein                Expires March 30, 2016                [Page 22]


Internet-Draft                  WAMP - BP                 September 2015


6.4.3.  Routed Remote Procedure Calls

6.4.3.1.  CALL

   Call as originally issued by the _Caller_ to the _Dealer_.

     [CALL, Request|id, Options|dict, Procedure|uri]

     [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list]

     [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list,
         ArgumentsKw|dict]

6.4.3.2.  RESULT

   Result of a call as returned by _Dealer_ to _Caller_.

       [RESULT, CALL.Request|id, Details|dict]

       [RESULT, CALL.Request|id, Details|dict, YIELD.Arguments|list]

       [RESULT, CALL.Request|id, Details|dict, YIELD.Arguments|list,
           YIELD.ArgumentsKw|dict]

6.4.3.3.  REGISTER

   A _Callees_ request to register an endpoint at a _Dealer_.

       [REGISTER, Request|id, Options|dict, Procedure|uri]

6.4.3.4.  REGISTERED

   Acknowledge sent by a _Dealer_ to a _Callee_ for successful
   registration.

       [REGISTERED, REGISTER.Request|id, Registration|id]

6.4.3.5.  UNREGISTER

   A _Callees_ request to unregister a previously established
   registration.

       [UNREGISTER, Request|id, REGISTERED.Registration|id]








Oberstein                Expires March 30, 2016                [Page 23]


Internet-Draft                  WAMP - BP                 September 2015


6.4.3.6.  UNREGISTERED

   Acknowledge sent by a _Dealer_ to a _Callee_ for successful
   unregistration.

       [UNREGISTERED, UNREGISTER.Request|id]

6.4.3.7.  INVOCATION

   Actual invocation of an endpoint sent by _Dealer_ to a _Callee_.

       [INVOCATION, Request|id, REGISTERED.Registration|id,
           Details|dict]

       [INVOCATION, Request|id, REGISTERED.Registration|id,
           Details|dict, C* Arguments|list]

       [INVOCATION, Request|id, REGISTERED.Registration|id,
           Details|dict, CALL.Arguments|list, CALL.ArgumentsKw|dict]

6.4.3.8.  YIELD

   Actual yield from an endpoint sent by a _Callee_ to _Dealer_.

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

       [YIELD, INVOCATION.Request|id, Options|dict, Arguments|list]

       [YIELD, INVOCATION.Request|id, Options|dict, Arguments|list,
           ArgumentsKw|dict]

6.5.  Message Codes and Direction

   The following table lists the message type code for *all 25 messages
   defined in the WAMP basic profile* and their direction between peer
   roles.

   Reserved codes may be used to identify additional message types in
   future standards documents.

      "Tx" indicates the message is sent by the respective role, and
      "Rx" indicates the message is received by the respective role.









Oberstein                Expires March 30, 2016                [Page 24]


Internet-Draft                  WAMP - BP                 September 2015


   +-----+----------------+------+------+------+------+-------+--------+
   | Cod |    Message     | Pub  | Brk  | Subs | Calr | Dealr | Callee |
   +-----+----------------+------+------+------+------+-------+--------+
   |  1  |    "HELLO"     |  Tx  |  Rx  |  Tx  |  Tx  |   Rx  |   Tx   |
   |  2  |   "WELCOME"    |  Rx  |  Tx  |  Rx  |  Rx  |   Tx  |   Rx   |
   |  3  |    "ABORT"     |  Rx  | TxRx |  Rx  |  Rx  |  TxRx |   Rx   |
   |  6  |   "GOODBYE"    | TxRx | TxRx | TxRx | TxRx |  TxRx |  TxRx  |
   |     |                |      |      |      |      |       |        |
   |  8  |    "ERROR"     |  Rx  |  Tx  |  Rx  |  Rx  |  TxRx |  TxRx  |
   |     |                |      |      |      |      |       |        |
   |  16 |   "PUBLISH"    |  Tx  |  Rx  |      |      |       |        |
   |  17 |  "PUBLISHED"   |  Rx  |  Tx  |      |      |       |        |
   |     |                |      |      |      |      |       |        |
   |  32 |  "SUBSCRIBE"   |      |  Rx  |  Tx  |      |       |        |
   |  33 |  "SUBSCRIBED"  |      |  Tx  |  Rx  |      |       |        |
   |  34 | "UNSUBSCRIBE"  |      |  Rx  |  Tx  |      |       |        |
   |  35 | "UNSUBSCRIBED" |      |  Tx  |  Rx  |      |       |        |
   |  36 |    "EVENT"     |      |  Tx  |  Rx  |      |       |        |
   |     |                |      |      |      |      |       |        |
   |  48 |     "CALL"     |      |      |      |  Tx  |   Rx  |        |
   |  50 |    "RESULT"    |      |      |      |  Rx  |   Tx  |        |
   |     |                |      |      |      |      |       |        |
   |  64 |   "REGISTER"   |      |      |      |      |   Rx  |   Tx   |
   |  65 |  "REGISTERED"  |      |      |      |      |   Tx  |   Rx   |
   |  66 |  "UNREGISTER"  |      |      |      |      |   Rx  |   Tx   |
   |  67 | "UNREGISTERED" |      |      |      |      |   Tx  |   Rx   |
   |  68 |  "INVOCATION"  |      |      |      |      |   Tx  |   Rx   |
   |  70 |    "YIELD"     |      |      |      |      |   Rx  |   Tx   |
   +-----+----------------+------+------+------+------+-------+--------+

6.6.  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.

6.7.  Empty Arguments and Keyword Arguments

   Implementations SHOULD avoid sending empty "Arguments" lists.

   E.g. a "CALL" message

       [CALL, Request|id, Options|dict, Procedure|uri,
           Arguments|list]

   where "Arguments == []" SHOULD be avoided, and instead



Oberstein                Expires March 30, 2016                [Page 25]


Internet-Draft                  WAMP - BP                 September 2015


       [CALL, Request|id, Options|dict, Procedure|uri]

   SHOULD be sent.

   Implementations SHOULD avoid sending empty "ArgumentsKw"
   dictionaries.

   E.g. a "CALL" message

       [CALL, Request|id, Options|dict, Procedure|uri,
           Arguments|list, ArgumentsKw|dict]

   where "ArgumentsKw == {}" SHOULD be avoided, and instead

       [CALL, Request|id, Options|dict, Procedure|uri,
           Arguments|list]

   SHOULD be sent when "Arguments" is non-empty.

7.  Sessions

   The message flow between _Clients_ and _Routers_ for opening and
   closing WAMP sessions involves the following messages:

   1.  "HELLO"

   2.  "WELCOME"

   3.  "ABORT"

   4.  "GOODBYE"

7.1.  Session Establishment

7.1.1.  HELLO

   After the underlying transport has been established, the opening of a
   WAMP session is initiated by the _Client_ sending a "HELLO" message
   to the _Router_

       [HELLO, Realm|uri, Details|dict]

   where

   o  "Realm" is a string identifying the realm this session should
      attach to





Oberstein                Expires March 30, 2016                [Page 26]


Internet-Draft                  WAMP - BP                 September 2015


   o  "Details" is a dictionary that allows to provide additional
      opening information (see below).

   The "HELLO" message MUST be the very first message sent by the
   _Client_ after the transport has been established.

   In the WAMP Basic Profile without session authentication the _Router_
   will reply with a "WELCOME" or "ABORT" message.

       ,------.          ,------.
       |Client|          |Router|
       `--+---'          `--+---'
          |      HELLO      |
          | ---------------->
          |                 |
          |     WELCOME     |
          | <----------------
       ,--+---.          ,--+---.
       |Client|          |Router|
       `------'          `------'

   A WAMP session starts its lifetime when the _Router_ has sent a
   "WELCOME" message to the _Client_, and ends when the underlying
   transport closes or when the session is closed explicitly by either
   peer sending the "GOODBYE" message (see below).

   It is a protocol error to receive a second "HELLO" message during the
   lifetime of the session and the _Peer_ must fail the session if that
   happens.

7.1.1.1.  Client: Role and Feature Announcement

   WAMP uses _Role & Feature announcement_ instead of _protocol
   versioning_ to allow

   o  implementations only supporting subsets of functionality

   o  future extensibility

   A _Client_ must announce the *roles* it supports via
   "Hello.Details.roles|dict", with a key mapping to a
   "Hello.Details.roles.<role>|dict" where "<role>" can be:

   o  "publisher"

   o  "subscriber"

   o  "caller"



Oberstein                Expires March 30, 2016                [Page 27]


Internet-Draft                  WAMP - BP                 September 2015


   o  "callee"

   A _Client_ can support any combination of the above roles but must
   support at least one role.

   The "<role>|dict" is a dictionary describing *features* supported by
   the peer for that role.

   This is empty for WAMP Basic Profile implementations, but may be used
   by implementations implementing parts of a future WAMP Advanced
   Profile to list the specific set of features they support.

   _Example: A Client that implements the Publisher and Subscriber roles
   of the WAMP Basic Profile._

       [1, "somerealm", {
         "roles": {
             "publisher": {},
             "subscriber": {}
         }
       }]

7.1.2.  WELCOME

   A _Router_ completes the opening of a WAMP session by sending a
   "WELCOME" reply message to the _Client_.

       [WELCOME, Session|id, Details|dict]

   where

   o  "Session" MUST be a randomly generated ID specific to the WAMP
      session.  This applies for the lifetime of the session.

   o  "Details" is a dictionary that allows to provide additional
      information regarding the open session (see below).

   In the WAMP Basic Profile without session authentication, a "WELCOME"
   message is the first message sent by the _Router_, directly in
   response to a "HELLO" message received from the _Client_. Extensions
   in an Advanced Profile may include intermediate steps and messages
   for authentication.

      Note.  The behavior if a requested "Realm" does not presently
      exist is router-specific.  A router may e.g. automatically create
      the realm, or deny the establishment of the session with a "ABORT"
      reply message.




Oberstein                Expires March 30, 2016                [Page 28]


Internet-Draft                  WAMP - BP                 September 2015


7.1.2.1.  Router: Role and Feature Announcement

   Similar to a _Client_ announcing _Roles_ and _Features_ supported in
   the `"HELLO" message, a _Router_ announces its supported _Roles_ and
   _Features_ in the "WELCOME" message.

   A _Router_ MUST announce the *roles* it supports via
   "Welcome.Details.roles|dict", with a key mapping to a
   "Welcome.Details.roles.<role>|dict" where "<role>" can be:

   o  "broker"

   o  "dealer"

   A _Router_ must support at least one role, and MAY support both
   roles.

   The "<role>|dict" is a dictionary describing *features* supported by
   the peer for that role.  With WAMP Basic Profile implementations,
   this will be empty, but may be used by implementations implementing
   parts of a future WAMP Advanced Profile to list the specific set of
   features they support

   _Example: A Router implementing the Broker role of the WAMP Basic
   Profile._

       [2, 9129137332, {
          "roles": {
             "broker": {}
          }
       }]

7.1.3.  ABORT

   Both the _Router_ and the _Client_ may abort the opening of a WAMP
   session by sending an "ABORT" message.

       [ABORT, Details|dict, Reason|uri]

   where

   o  "Reason" MUST be an URI.

   o  "Details" MUST be a dictionary that allows to provide additional,
      optional closing information (see below).

   No response to an "ABORT" message is expected.




Oberstein                Expires March 30, 2016                [Page 29]


Internet-Draft                  WAMP - BP                 September 2015


       ,------.          ,------.
       |Client|          |Router|
       `--+---'          `--+---'
          |      HELLO      |
          | ---------------->
          |                 |
          |      ABORT      |
          | <----------------
       ,--+---.          ,--+---.
       |Client|          |Router|
       `------'          `------'

   _Example_

       [3, {"message": "The realm does not exist."},
           "wamp.error.no_such_realm"]

7.2.  Session Closing

   A WAMP session starts its lifetime with the _Router_ sending a
   "WELCOME" message to the _Client_ and ends when the underlying
   transport disappears or when the WAMP session is closed explicitly by
   a "GOODBYE" message sent by one _Peer_ and a "GOODBYE" message sent
   from the other _Peer_ in response.

       [GOODBYE, Details|dict, Reason|uri]

   where

   o  "Reason" MUST be an URI.

   o  "Details" MUST be a dictionary that allows to provide additional,
      optional closing information (see below).

       ,------.          ,------.
       |Client|          |Router|
       `--+---'          `--+---'
          |     GOODBYE     |
          | ---------------->
          |                 |
          |     GOODBYE     |
          | <----------------
       ,--+---.          ,--+---.
       |Client|          |Router|
       `------'          `------'






Oberstein                Expires March 30, 2016                [Page 30]


Internet-Draft                  WAMP - BP                 September 2015


       ,------.          ,------.
       |Client|          |Router|
       `--+---'          `--+---'
          |     GOODBYE     |
          | <----------------
          |                 |
          |     GOODBYE     |
          | ---------------->
       ,--+---.          ,--+---.
       |Client|          |Router|
       `------'          `------'

   _Example_. One _Peer_ initiates closing

       [6, {"message": "The host is shutting down now."},
           "wamp.error.system_shutdown"]

   and the other peer replies

       [6, {}, "wamp.error.goodbye_and_out"]

   _Example_. One _Peer_ initiates closing

       [6, {}, "wamp.error.close_realm"]

   and the other peer replies

       [6, {}, "wamp.error.goodbye_and_out"]

7.2.1.  Difference between ABORT and GOODBYE

   The differences between "ABORT" and "GOODBYE" messages are:

   1.  "ABORT" gets sent only _before_ a _Session_ is established, while
       "GOODBYE" is sent only _after_ a _Session_ is already
       established.

   2.  "ABORT" is never replied to by a _Peer_, whereas "GOODBYE" must
       be replied to by the receiving _Peer_

      Though "ABORT" and "GOODBYE" are structurally identical, using
      different message types serves to reduce overloaded meaning of
      messages and simplify message handling code.








Oberstein                Expires March 30, 2016                [Page 31]


Internet-Draft                  WAMP - BP                 September 2015


7.3.  Agent Identification

   When a software agent operates in a network protocol, it often
   identifies itself, its application type, operating system, software
   vendor, or software revision, by submitting a characteristic
   identification string to its operating peer.

   Similar to what browsers do with the "User-Agent" HTTP header, both
   the "HELLO" and the "WELCOME" message MAY disclose the WAMP
   implementation in use to its peer:

       HELLO.Details.agent|string

   and

       WELCOME.Details.agent|string

   _Example: A Client "HELLO" message._

       [1, "somerealm", {
            "agent": "AutobahnJS-0.9.14",
            "roles": {
               "subscriber": {},
               "publisher": {}
            }
       }]

   _Example: A Router "WELCOME" message._

       [2, 9129137332, {
           "agent": "Crossbar.io-0.10.11",
           "roles": {
             "broker": {}
           }
       }]

8.  Publish and Subscribe

   All of the following features for Publish & Subscribe are mandatory
   for WAMP Basic Profile implementations supporting the respective
   roles, i.e. _Publisher_, _Subscriber_ and _Dealer_.

8.1.  Subscribing and Unsubscribing

   The message flow between _Clients_ implementing the role of
   _Subscriber_ and _Routers_ implementing the role of _Broker_ for
   subscribing and unsubscribing involves the following messages:




Oberstein                Expires March 30, 2016                [Page 32]


Internet-Draft                  WAMP - BP                 September 2015


   1.  "SUBSCRIBE"

   2.  "SUBSCRIBED"

   3.  "UNSUBSCRIBE"

   4.  "UNSUBSCRIBED"

   5.  "ERROR"

       ,---------.          ,------.             ,----------.
       |Publisher|          |Broker|             |Subscriber|
       `----+----'          `--+---'             `----+-----'
            |                  |                      |
            |                  |                      |
            |                  |       SUBSCRIBE      |
            |                  | <---------------------
            |                  |                      |
            |                  |  SUBSCRIBED or ERROR |
            |                  | --------------------->
            |                  |                      |
            |                  |                      |
            |                  |                      |
            |                  |                      |
            |                  |      UNSUBSCRIBE     |
            |                  | <---------------------
            |                  |                      |
            |                  | UNSUBSCRIBED or ERROR|
            |                  | --------------------->
       ,----+----.          ,--+---.             ,----+-----.
       |Publisher|          |Broker|             |Subscriber|
       `---------'          `------'             `----------'

   A _Subscriber_ may subscribe to zero, one or more topics, and a
   _Publisher_ publishes to topics without knowledge of subscribers.

   Upon subscribing to a topic via the "SUBSCRIBE" message, a
   _Subscriber_ will receive any future events published to the
   respective topic by _Publishers_, and will receive those events
   asynchronously.

   A subscription lasts for the duration of a session, unless a
   _Subscriber_ opts out from a previously established subscription via
   the "UNSUBSCRIBE" message.

      A _Subscriber_ may have more than one event handler attached to
      the same subscription.  This can be implemented in different ways:
      a) a _Subscriber_ can recognize itself that it is already



Oberstein                Expires March 30, 2016                [Page 33]


Internet-Draft                  WAMP - BP                 September 2015


      subscribed and just attach another handler to the subscription
      for incoming events, b) or it can send a new "SUBSCRIBE" message
      to broker (as it would be first) and upon receiving a
      "SUBSCRIBED.Subscription|id" it already knows about, attach the
      handler to the existing subscription

8.1.1.  SUBSCRIBE

   A _Subscriber_ communicates its interest in a topic to a _Broker_ by
   sending a "SUBSCRIBE" message:

       [SUBSCRIBE, Request|id, Options|dict, Topic|uri]

   where

   o  "Request" MUST be a random, ephemeral ID chosen by the
      _Subscriber_ and used to correlate the _Broker's_ response with
      the request.

   o  "Options" MUST be a dictionary that allows to provide additional
      subscription request details in a extensible way.  This is
      described further below.

   o  "Topic" is the topic the _Subscriber_ wants to subscribe to and
      MUST be an URI.

   _Example_

       [32, 713845233, {}, "com.myapp.mytopic1"]

   A _Broker_, receiving a "SUBSCRIBE" message, can fullfill or reject
   the subscription, so it answers with "SUBSCRIBED" or "ERROR"
   messages.

8.1.2.  SUBSCRIBED

   If the _Broker_ is able to fulfill and allow the subscription, it
   answers by sending a "SUBSCRIBED" message to the _Subscriber_

       [SUBSCRIBED, SUBSCRIBE.Request|id, Subscription|id]

   where

   o  "SUBSCRIBE.Request" MUST be the ID from the original request.

   o  "Subscription" MUST be an ID chosen by the _Broker_ for the
      subscription.




Oberstein                Expires March 30, 2016                [Page 34]


Internet-Draft                  WAMP - BP                 September 2015


   _Example_

       [33, 713845233, 5512315355]

      Note.  The "Subscription" ID chosen by the broker need not be
      unique to the subscription of a single _Subscriber_, but may be
      assigned to the "Topic", or the combination of the "Topic" and
      some or all "Options", such as the topic pattern matching method
      to be used.  Then this ID may be sent to all _Subscribers_ for the
      "Topic" or "Topic" / "Options" combination.  This allows the
      _Broker_ to serialize an event to be delivered only once for all
      actual receivers of the event.

      In case of receiving a "SUBSCRIBE" message from the same
      _Subscriber_ and to already subscribed topic, _Broker_ should
      answer with "SUBSCRIBED" message, containing the existing
      "Subscription|id".

8.1.3.  Subscribe ERROR

   When the request for subscription cannot be fulfilled by the
   _Broker_, the _Broker_ sends back an "ERROR" message to the
   _Subscriber_

       [ERROR, SUBSCRIBE, SUBSCRIBE.Request|id, Details|dict,
           Error|uri]

   where

   o  "SUBSCRIBE.Request" MUST be the ID from the original request.

   o  "Error" MUST be an URI that gives the error of why the request
      could not be fulfilled.

   _Example_

       [8, 32, 713845233, {}, "wamp.error.not_authorized"]

8.1.4.  UNSUBSCRIBE

   When a _Subscriber_ is no longer interested in receiving events for a
   subscription it sends an "UNSUBSCRIBE" message

       [UNSUBSCRIBE, Request|id, SUBSCRIBED.Subscription|id]

   where





Oberstein                Expires March 30, 2016                [Page 35]


Internet-Draft                  WAMP - BP                 September 2015


   o  "Request" MUST be a random, ephemeral ID chosen by the
      _Subscriber_ and used to correlate the _Broker's_ response with
      the request.

   o  "SUBSCRIBED.Subscription" MUST be the ID for the subscription to
      unsubscribe from, originally handed out by the _Broker_ to the
      _Subscriber_.

   _Example_

       [34, 85346237, 5512315355]

8.1.5.  UNSUBSCRIBED

   Upon successful unsubscription, the _Broker_ sends an "UNSUBSCRIBED"
   message to the _Subscriber_

       [UNSUBSCRIBED, UNSUBSCRIBE.Request|id]

   where

   o  "UNSUBSCRIBE.Request" MUST be the ID from the original request.

   _Example_

       [35, 85346237]

8.1.6.  Unsubscribe ERROR

   When the request fails, the _Broker_ sends an "ERROR"

       [ERROR, UNSUBSCRIBE, UNSUBSCRIBE.Request|id, Details|dict,
           Error|uri]

   where

   o  "UNSUBSCRIBE.Request" MUST be the ID from the original request.

   o  "Error" MUST be an URI that gives the error of why the request
      could not be fulfilled.

   _Example_

       [8, 34, 85346237, {}, "wamp.error.no_such_subscription"]







Oberstein                Expires March 30, 2016                [Page 36]


Internet-Draft                  WAMP - BP                 September 2015


8.2.  Publishing and Events

   The message flow between _Publishers_, a _Broker_ and _Subscribers_
   for publishing to topics and dispatching events involves the
   following messages:

   1.  "PUBLISH"

   2.  "PUBLISHED"

   3.  "EVENT"

   4.  "ERROR"

       ,---------.          ,------.          ,----------.
       |Publisher|          |Broker|          |Subscriber|
       `----+----'          `--+---'          `----+-----'
            |     PUBLISH      |                   |
            |------------------>                   |
            |                  |                   |
            |PUBLISHED or ERROR|                   |
            |<------------------                   |
            |                  |                   |
            |                  |       EVENT       |
            |                  | ------------------>
       ,----+----.          ,--+---.          ,----+-----.
       |Publisher|          |Broker|          |Subscriber|
       `---------'          `------'          `----------'

8.2.1.  PUBLISH

   When a _Publisher_ requests to publish an event to some topic, it
   sends a "PUBLISH" message to a _Broker_:

       [PUBLISH, Request|id, Options|dict, Topic|uri]

   or

       [PUBLISH, Request|id, Options|dict, Topic|uri, Arguments|list]

   or

       [PUBLISH, Request|id, Options|dict, Topic|uri, Arguments|list,
           ArgumentsKw|dict]

   where





Oberstein                Expires March 30, 2016                [Page 37]


Internet-Draft                  WAMP - BP                 September 2015


   o  "Request" is a random, ephemeral ID chosen by the _Publisher_ and
      used to correlate the _Broker's_ response with the request.

   o  "Options" is a dictionary that allows to provide additional
      publication request details in an extensible way.  This is
      described further below.

   o  "Topic" is the topic published to.

   o  "Arguments" is a list of application-level event payload elements.
      The list may be of zero length.

   o  "ArgumentsKw" is an optional dictionary containing application-
      level event payload, provided as keyword arguments.  The
      dictionary may be empty.

   If the _Broker_ is able to fulfill and allowing the publication, the
   _Broker_ will send the event to all current _Subscribers_ of the
   topic of the published event.

   By default, publications are unacknowledged, and the _Broker_ will
   not respond, whether the publication was successful indeed or not.
   This behavior can be changed with the option
   "PUBLISH.Options.acknowledge|bool" (see below).

   _Example_

       [16, 239714735, {}, "com.myapp.mytopic1"]

   _Example_

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

   _Example_

       [16, 239714735, {}, "com.myapp.mytopic1", [], {"color": "orange",
           "sizes": [23, 42, 7]}]

8.2.2.  PUBLISHED

   If the _Broker_ is able to fulfill and allowing the publication, and
   "PUBLISH.Options.acknowledge == true", the _Broker_ replies by
   sending a "PUBLISHED" message to the _Publisher_:

       [PUBLISHED, PUBLISH.Request|id, Publication|id]

   where




Oberstein                Expires March 30, 2016                [Page 38]


Internet-Draft                  WAMP - BP                 September 2015


   o  "PUBLISH.Request" is the ID from the original publication request.

   o  "Publication" is a ID chosen by the Broker for the publication.

   _Example_

       [17, 239714735, 4429313566]

8.2.3.  Publish ERROR

   When the request for publication cannot be fulfilled by the _Broker_,
   and "PUBLISH.Options.acknowledge == true", the _Broker_ sends back an
   "ERROR" message to the _Publisher_

       [ERROR, PUBLISH, PUBLISH.Request|id, Details|dict, Error|uri]

   where

   o  "PUBLISH.Request" is the ID from the original publication request.

   o  "Error" is an URI that gives the error of why the request could
      not be fulfilled.

   _Example_

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

8.2.4.  EVENT

   When a publication is successful and a _Broker_ dispatches the event,
   it determines a list of receivers for the event based on
   _Subscribers_ for the topic published to and, possibly, other
   information in the event.

   Note that the _Publisher_ of an event will never receive the
   published event even if the _Publisher_ is also a _Subscriber_ of the
   topic published to.

      WAMP Advanced Profile provides options for more detailed control
      over publication.

   When a _Subscriber_ is deemed to be a receiver, the _Broker_ sends
   the _Subscriber_ an "EVENT" message:

       [EVENT, SUBSCRIBED.Subscription|id, PUBLISHED.Publication|id,
           Details|dict]

   or



Oberstein                Expires March 30, 2016                [Page 39]


Internet-Draft                  WAMP - BP                 September 2015


       [EVENT, SUBSCRIBED.Subscription|id, PUBLISHED.Publication|id,
           Details|dict, PUBLISH.Arguments|list]

   or

       [EVENT, SUBSCRIBED.Subscription|id, PUBLISHED.Publication|id,
       Details|dict, PUBLISH.Arguments|list, PUBLISH.ArgumentKw|dict]

   where

   o  "SUBSCRIBED.Subscription" is the ID for the subscription under
      which the _Subscriber_ receives the event - the ID for the
      subscription originally handed out by the _Broker_ to the
      _Subscriber_.

   o  "PUBLISHED.Publication" is the ID of the publication of the
      published event.

   o  "Details" is a dictionary that allows the _Broker_ to provide
      additional event details in a extensible way.  This is described
      further below.

   o  "PUBLISH.Arguments" is the application-level event payload that
      was provided with the original publication request.

   o  "PUBLISH.ArgumentKw" is the application-level event payload that
      was provided with the original publication request.

   _Example_

       [36, 5512315355, 4429313566, {}]

   _Example_

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

   _Example_

       [36, 5512315355, 4429313566, {}, [], {"color": "orange",
           "sizes": [23, 42, 7]}]

9.  Remote Procedure Calls

   All of the following features for Remote Procedure Calls are
   mandatory for WAMP Basic Profile implementations supporting the
   respective roles.





Oberstein                Expires March 30, 2016                [Page 40]


Internet-Draft                  WAMP - BP                 September 2015


9.1.  Registering and Unregistering

   The message flow between _Callees_ and a _Dealer_ for registering and
   unregistering endpoints to be called over RPC involves the following
   messages:

   1.  "REGISTER"

   2.  "REGISTERED"

   3.  "UNREGISTER"

   4.  "UNREGISTERED"

   5.  "ERROR"

       ,------.          ,------.               ,------.
       |Caller|          |Dealer|               |Callee|
       `--+---'          `--+---'               `--+---'
          |                 |                      |
          |                 |                      |
          |                 |       REGISTER       |
          |                 | <---------------------
          |                 |                      |
          |                 |  REGISTERED or ERROR |
          |                 | --------------------->
          |                 |                      |
          |                 |                      |
          |                 |                      |
          |                 |                      |
          |                 |                      |
          |                 |      UNREGISTER      |
          |                 | <---------------------
          |                 |                      |
          |                 | UNREGISTERED or ERROR|
          |                 | --------------------->
       ,--+---.          ,--+---.               ,--+---.
       |Caller|          |Dealer|               |Callee|
       `------'          `------'               `------'

9.1.1.  REGISTER

   A _Callee_ announces the availability of an endpoint implementing a
   procedure with a _Dealer_ by sending a "REGISTER" message:

       [REGISTER, Request|id, Options|dict, Procedure|uri]

   where



Oberstein                Expires March 30, 2016                [Page 41]


Internet-Draft                  WAMP - BP                 September 2015


   o  "Request" is a random, ephemeral ID chosen by the _Callee_ and
      used to correlate the _Dealer's_ response with the request.

   o  "Options" is a dictionary that allows to provide additional
      registration request details in a extensible way.  This is
      described further below.

   o  "Procedure"is the procedure the _Callee_ wants to register

   _Example_

       [64, 25349185, {}, "com.myapp.myprocedure1"]

9.1.2.  REGISTERED

   If the _Dealer_ is able to fulfill and allowing the registration, it
   answers by sending a "REGISTERED" message to the "Callee":

       [REGISTERED, REGISTER.Request|id, Registration|id]

   where

   o  "REGISTER.Request" is the ID from the original request.

   o  "Registration" is an ID chosen by the _Dealer_ for the
      registration.

   _Example_

       [65, 25349185, 2103333224]

9.1.3.  Register ERROR

   When the request for registration cannot be fulfilled by the
   _Dealer_, the _Dealer_ sends back an "ERROR" message to the _Callee_:

       [ERROR, REGISTER, REGISTER.Request|id, Details|dict, Error|uri]

   where

   o  "REGISTER.Request" is the ID from the original request.

   o  "Error" is an URI that gives the error of why the request could
      not be fulfilled.

   _Example_

       [8, 64, 25349185, {}, "wamp.error.procedure_already_exists"]



Oberstein                Expires March 30, 2016                [Page 42]


Internet-Draft                  WAMP - BP                 September 2015


9.1.4.  UNREGISTER

   When a _Callee_ is no longer willing to provide an implementation of
   the registered procedure, it sends an "UNREGISTER" message to the
   _Dealer_:

       [UNREGISTER, Request|id, REGISTERED.Registration|id]

   where

   o  "Request" is a random, ephemeral ID chosen by the _Callee_ and
      used to correlate the _Dealer's_ response with the request.

   o  "REGISTERED.Registration" is the ID for the registration to
      revoke, originally handed out by the _Dealer_ to the _Callee_.

   _Example_

       [66, 788923562, 2103333224]

9.1.5.  UNREGISTERED

   Upon successful unregistration, the _Dealer_ sends an "UNREGISTERED"
   message to the _Callee_:

       [UNREGISTERED, UNREGISTER.Request|id]

   where

   o  "UNREGISTER.Request" is the ID from the original request.

   _Example_

       [67, 788923562]

9.1.6.  Unregister ERROR

   When the unregistration request fails, the _Dealer_ sends an "ERROR"
   message:

       [ERROR, UNREGISTER, UNREGISTER.Request|id, Details|dict,
           Error|uri]

   where

   o  "UNREGISTER.Request" is the ID from the original request.





Oberstein                Expires March 30, 2016                [Page 43]


Internet-Draft                  WAMP - BP                 September 2015


   o  "Error" is an URI that gives the error of why the request could
      not be fulfilled.

   _Example_

       [8, 66, 788923562, {}, "wamp.error.no_such_registration"]

9.2.  Calling and Invocations

   The message flow between _Callers_, a _Dealer_ and _Callees_ for
   calling procedures and invoking endpoints involves the following
   messages:

   1.  "CALL"

   2.  "RESULT"

   3.  "INVOCATION"

   4.  "YIELD"

   5.  "ERROR"

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

   The execution of remote procedure calls is asynchronous, and there
   may be more than one call outstanding.  A call is called outstanding
   (from the point of view of the _Caller_), when a (final) result or
   error has not yet been received by the _Caller_.






Oberstein                Expires March 30, 2016                [Page 44]


Internet-Draft                  WAMP - BP                 September 2015


9.2.1.  CALL

   When a _Caller_ wishes to call a remote procedure, it sends a "CALL"
   message to a _Dealer_:

       [CALL, Request|id, Options|dict, Procedure|uri]

   or

       [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list]

   or

       [CALL, Request|id, Options|dict, Procedure|uri, Arguments|list,
           ArgumentsKw|dict]

   where

   o  "Request" is a random, ephemeral ID chosen by the _Caller_ and
      used to correlate the _Dealer's_ response with the request.

   o  "Options" is a dictionary that allows to provide additional call
      request details in an extensible way.  This is described further
      below.

   o  "Procedure" is the URI of the procedure to be called.

   o  "Arguments" is a list of positional call arguments (each of
      arbitrary type).  The list may be of zero length.

   o  "ArgumentsKw" is a dictionary of keyword call arguments (each of
      arbitrary type).  The dictionary may be empty.

   _Example_

       [48, 7814135, {}, "com.myapp.ping"]

   _Example_

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

   _Example_

       [48, 7814135, {}, "com.myapp.add2", [23, 7]]

   _Example_





Oberstein                Expires March 30, 2016                [Page 45]


Internet-Draft                  WAMP - BP                 September 2015


       [48, 7814135, {}, "com.myapp.user.new", ["johnny"],
           {"firstname": "John", "surname": "Doe"}]

9.2.2.  INVOCATION

   If the _Dealer_ is able to fulfill (mediate) the call and it allows
   the call, it sends a "INVOCATION" message to the respective _Callee_
   implementing the procedure:

       [INVOCATION, Request|id, REGISTERED.Registration|id,
           Details|dict]

   or

       [INVOCATION, Request|id, REGISTERED.Registration|id,
           Details|dict, CALL.Arguments|list]

   or

       [INVOCATION, Request|id, REGISTERED.Registration|id,
           Details|dict, CALL.Arguments|list, CALL.ArgumentsKw|dict]

   where

   o  "Request" is a random, ephemeral ID chosen by the _Dealer_ and
      used to correlate the _Callee's_ response with the request.

   o  "REGISTERED.Registration" is the registration ID under which the
      procedure was registered at the _Dealer_.

   o  "Details" is a dictionary that allows to provide additional
      invocation request details in an extensible way.  This is
      described further below.

   o  "CALL.Arguments" is the original list of positional call arguments
      as provided by the _Caller_.

   o  "CALL.ArgumentsKw" is the original dictionary of keyword call
      arguments as provided by the _Caller_.

   _Example_

       [68, 6131533, 9823526, {}]

   _Example_

       [68, 6131533, 9823527, {}, ["Hello, world!"]]




Oberstein                Expires March 30, 2016                [Page 46]


Internet-Draft                  WAMP - BP                 September 2015


   _Example_

       [68, 6131533, 9823528, {}, [23, 7]]

   _Example_

       [68, 6131533, 9823529, {}, ["johnny"], {"firstname": "John",
           "surname": "Doe"}]

9.2.3.  YIELD

   If the _Callee_ is able to successfully process and finish the
   execution of the call, it answers by sending a "YIELD" message to the
   _Dealer_:

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

   or

       [YIELD, INVOCATION.Request|id, Options|dict, Arguments|list]

   or

       [YIELD, INVOCATION.Request|id, Options|dict, Arguments|list,
           ArgumentsKw|dict]

   where

   o  "INVOCATION.Request" is the ID from the original invocation
      request.

   o  "Options"is a dictionary that allows to provide additional
      options.

   o  "Arguments" is a list of positional result elements (each of
      arbitrary type).  The list may be of zero length.

   o  "ArgumentsKw" is a dictionary of keyword result elements (each of
      arbitrary type).  The dictionary may be empty.

   _Example_

       [70, 6131533, {}]

   _Example_

       [70, 6131533, {}, ["Hello, world!"]]




Oberstein                Expires March 30, 2016                [Page 47]


Internet-Draft                  WAMP - BP                 September 2015


   _Example_

       [70, 6131533, {}, [30]]

   _Example_

       [70, 6131533, {}, [], {"userid": 123, "karma": 10}]

9.2.4.  RESULT

   The _Dealer_ will then send a "RESULT" message to the original
   _Caller_:

       [RESULT, CALL.Request|id, Details|dict]

   or

       [RESULT, CALL.Request|id, Details|dict, YIELD.Arguments|list]

   or

       [RESULT, CALL.Request|id, Details|dict, YIELD.Arguments|list,
           YIELD.ArgumentsKw|dict]

   where

   o  "CALL.Request" is the ID from the original call request.

   o  "Details" is a dictionary of additional details.

   o  "YIELD.Arguments" is the original list of positional result
      elements as returned by the _Callee_.

   o  "YIELD.ArgumentsKw" is the original dictionary of keyword result
      elements as returned by the _Callee_.

   _Example_

       [50, 7814135, {}]

   _Example_

       [50, 7814135, {}, ["Hello, world!"]]

   _Example_

       [50, 7814135, {}, [30]]




Oberstein                Expires March 30, 2016                [Page 48]


Internet-Draft                  WAMP - BP                 September 2015


   _Example_

       [50, 7814135, {}, [], {"userid": 123, "karma": 10}]

9.2.5.  Invocation ERROR

   If the _Callee_ is unable to process or finish the execution of the
   call, or the application code implementing the procedure raises an
   exception or otherwise runs into an error, the _Callee_ sends an
   "ERROR" message to the _Dealer_:

       [ERROR, INVOCATION, INVOCATION.Request|id, Details|dict,
           Error|uri]

   or

       [ERROR, INVOCATION, INVOCATION.Request|id, Details|dict,
       Error|uri, Arguments|list]

   or

       [ERROR, INVOCATION, INVOCATION.Request|id, Details|dict,
           Error|uri, Arguments|list, ArgumentsKw|dict]

   where

   o  "INVOCATION.Request" is the ID from the original "INVOCATION"
      request previously sent by the _Dealer_ to the _Callee_.

   o  "Details" is a dictionary with additional error details.

   o  "Error" is an URI that identifies the error of why the request
      could not be fulfilled.

   o  "Arguments" is a list containing arbitrary, application defined,
      positional error information.  This will be forwarded by the
      _Dealer_ to the _Caller_ that initiated the call.

   o  "ArgumentsKw" is a dictionary containing arbitrary, application
      defined, keyword-based error information.  This will be forwarded
      by the _Dealer_ to the _Caller_ that initiated the call.

   _Example_

       [8, 68, 6131533, {}, "com.myapp.error.object_write_protected",
           ["Object is write protected."], {"severity": 3}]





Oberstein                Expires March 30, 2016                [Page 49]


Internet-Draft                  WAMP - BP                 September 2015


9.2.6.  Call ERROR

   The _Dealer_ will then send a "ERROR" message to the original
   _Caller_:

       [ERROR, CALL, CALL.Request|id, Details|dict, Error|uri]

   or

       [ERROR, CALL, CALL.Request|id, Details|dict, Error|uri,
           Arguments|list]

   or

       [ERROR, CALL, CALL.Request|id, Details|dict, Error|uri,
           Arguments|list, ArgumentsKw|dict]

   where

   o  "CALL.Request" is the ID from the original "CALL" request sent by
      the _Caller_ to the _Dealer_.

   o  "Details" is a dictionary with additional error details.

   o  "Error" is an URI identifying the type of error as returned by the
      _Callee_ to the _Dealer_.

   o  "Arguments" is a list containing the original error payload list
      as returned by the _Callee_ to the _Dealer_.

   o  "ArgumentsKw" is a dictionary containing the original error
      payload dictionary as returned by the _Callee_ to the _Dealer_

   _Example_

       [8, 48, 7814135, {}, "com.myapp.error.object_write_protected",
           ["Object is write protected."], {"severity": 3}]

   If the original call already failed at the _Dealer_ *before* the call
   would have been forwarded to any _Callee_, the _Dealer_ will send an
   "ERROR" message to the _Caller_:

       [ERROR, CALL, CALL.Request|id, Details|dict, Error|uri]

   _Example_

       [8, 48, 7814135, {}, "wamp.error.no_such_procedure"]




Oberstein                Expires March 30, 2016                [Page 50]


Internet-Draft                  WAMP - BP                 September 2015


9.3.  Predefined URIs

   WAMP pre-defines the following error URIs as part of this Basic
   Profile, which cover the full set of error states.  Additional error
   URIs may be defined as part of a future Advanced Profile to cover
   error states which may occur based on extensions of the protocol.

   o  below has to be changed to state that for the given error state a
      party MUST send the specific error uri, e.g

   When a _Peer_ provides an incorrect URI for any URI-based attribute
   of a WAMP message (e.g. realm, topic), then the other _Peer_ has to
   respond with an "ERROR" message and give the following _Error URI_:

       wamp.error.invalid_uri

9.4.  Interaction

   _Peer_ provided an incorrect URI for any URI-based attribute of WAMP
   message, such as realm, topic or procedure

       wamp.error.invalid_uri

   A _Dealer_ could not perform a call, since no procedure is currently
   registered under the given URI.

       wamp.error.no_such_procedure

   A procedure could not be registered, since a procedure with the given
   URI is already registered.

       wamp.error.procedure_already_exists

   A _Dealer_ could not perform an unregister, since the given
   registration is not active.

       wamp.error.no_such_registration

   A _Broker_ could not perform an unsubscribe, since the given
   subscription is not active.

       wamp.error.no_such_subscription

   A call failed since the given argument types or values are not
   acceptable to the called procedure.  In this case the _Callee_ may
   throw this error.  Alternatively a _Router_ may throw this error if
   it performed _payload validation_ of a call, call result, call error
   or publish, and the payload did not conform to the requirements.



Oberstein                Expires March 30, 2016                [Page 51]


Internet-Draft                  WAMP - BP                 September 2015


       wamp.error.invalid_argument

9.4.1.  Session Close

   The _Peer_ is shutting down completely - used as a "GOODBYE" (or
   "ABORT") reason.

       wamp.error.system_shutdown

   The _Peer_ want to leave the realm - used as a "GOODBYE" reason.

       wamp.error.close_realm

   A _Peer_ acknowledges ending of a session - used as a "GOODBYE" reply
   reason.

       wamp.error.goodbye_and_out

9.5.  Authorization

   A join, call, register, publish or subscribe failed, since the _Peer_
   is not authorized to perform the operation.

       wamp.error.not_authorized

   A _Dealer_ or _Broker_ could not determine if the _Peer_ is
   authorized to perform a join, call, register, publish or subscribe,
   since the authorization operation _itself_ failed.  E.g. a custom
   authorizer did run into an error.

       wamp.error.authorization_failed

   _Peer_ wanted to join a non-existing realm (and the _Router_ did not
   allow to auto-create the realm).

       wamp.error.no_such_realm

   A _Peer_ was to be authenticated under a Role that does not (or no
   longer) exists on the Router.  For example, the _Peer_ was
   successfully authenticated, but the Role configured does not exists -
   hence there is some misconfiguration in the Router.

       wamp.error.no_such_role








Oberstein                Expires March 30, 2016                [Page 52]


Internet-Draft                  WAMP - BP                 September 2015


9.6.  Ordering Guarantees

   All WAMP implementations, in particular _Routers_ MUST support the
   following ordering guarantees.

      A WAMP Advanced Profile may provide applications options to relax
      ordering guarantees, in particular with distributed calls.

9.6.1.  Publish & Subscribe Ordering

   Regarding *Publish & Subscribe*, the ordering guarantees are as
   follows:

   If _Subscriber A_ is subscribed to both *Topic 1* and *Topic 2*, and
   _Publisher B_ first publishes an *Event 1* to *Topic 1* and then an
   *Event 2* to *Topic 2*, then _Subscriber A_ will first receive *Event
   1* and then *Event 2*. This also holds if *Topic 1* and *Topic 2* are
   identical.

   In other words, WAMP guarantees ordering of events between any given
   _pair_ of _Publisher_ and _Subscriber_.

   Further, if _Subscriber A_ subscribes to *Topic 1*, the "SUBSCRIBED"
   message will be sent by the _Broker_ to _Subscriber A_ before any
   "EVENT" message for *Topic 1*.

   There is no guarantee regarding the order of return for multiple
   subsequent subscribe requests.  A subscribe request might require the
   _Broker_ to do a time-consuming lookup in some database, whereas
   another subscribe request second might be permissible immediately.

9.6.2.  Remote Procedure Call Ordering

   Regarding *Remote Procedure Calls*, the ordering guarantees are as
   follows:

   If _Callee A_ has registered endpoints for both *Procedure 1* and
   *Procedure 2*, and _Caller B_ first issues a *Call 1* to *Procedure
   1* and then a *Call 2* to *Procedure 2*, and both calls are routed to
   _Callee A_, then _Callee A_ will first receive an invocation
   corresponding to *Call 1* and then *Call 2*. This also holds if
   *Procedure 1* and *Procedure 2* are identical.

   In other words, WAMP guarantees ordering of invocations between any
   given _pair_ of _Caller_ and _Callee_.

   There are no guarantees on the order of call results and errors in
   relation to _different_ calls, since the execution of calls upon



Oberstein                Expires March 30, 2016                [Page 53]


Internet-Draft                  WAMP - BP                 September 2015


   different invocations of endpoints in _Callees_ are running
   independently.  A first call might require an expensive, long-running
   computation, whereas a second, subsequent call might finish
   immediately.

   Further, if _Callee A_ registers for *Procedure 1*, the "REGISTERED"
   message will be sent by _Dealer_ to _Callee A_ before any
   "INVOCATION" message for *Procedure 1*.

   There is no guarantee regarding the order of return for multiple
   subsequent register requests.  A register request might require the
   _Broker_ to do a time-consuming lookup in some database, whereas
   another register request second might be permissible immediately.

9.7.  Security Model

   The following discusses the security model for the WAMP basic
   profile.  A WAMP Advanced Profile may extend this.

9.7.1.  Transport Encryption and Integrity

   WAMP transports may provide (optional) transport-level encryption and
   integrity verification.  If so, encryption and integrity is point-to-
   point: between a _Client_ and the _Router_ it is connected to.

   Transport-level encryption and integrity is solely at the transport-
   level and transparent to WAMP.  WAMP itself deliberately does not
   specify any kind of transport-level encryption.

   Implementations that offer TCP based transport such as WAMP-over-
   WebSocket or WAMP-over-RawSocket SHOULD implement Transport Layer
   Security (TLS).

   WAMP deployments are encouraged to stick to a TLS-only policy with
   the TLS code and setup being hardened.

   Further, when a _Client_ connects to a _Router_ over a local-only
   transport such as Unix domain sockets, the integrity of the data
   transmitted is implicit (the OS kernel is trusted), and the privacy
   of the data transmitted can be assured using file system permissions
   (no one can tap a Unix domain socket without appropriate permissions
   or being root).

9.7.2.  Router Authentication

   To authenticate _Routers_ to _Clients_, deployments MUST run TLS and
   _Clients_ MUST verify the _Router_ server certificate presented.




Oberstein                Expires March 30, 2016                [Page 54]


Internet-Draft                  WAMP - BP                 September 2015


   WAMP itself does not provide mechanisms to authenticate a _Router_
   (only a _Client_).

   The verification of the _Router_ server certificate can happen

   1.  against a certificate trust database that comes with the
       _Clients_ operating system

   2.  against an issuing certificate/key hard-wired into the _Client_

   3.  by using new mechanisms like DNS-based Authentication of Named
       Enitities (DNSSEC)/TLSA

   Further, when a _Client_ connects to a _Router_ over a local-only
   transport such as Unix domain sockets, the file system permissions
   can be used to create implicit trust.  E.g. if only the OS user under
   which the _Router_ runs has the permission to create a Unix domain
   socket under a specific path, _Clients_ connecting to that path can
   trust in the router authenticity.

9.7.3.  Client Authentication

   Authentication of a _Client_ to a _Router_ at the WAMP level is not
   part of this basic profile.  A WAMP Advanced Profile may specify such
   mechanisms.

   When running over TLS, a _Router_ may authenticate a _Client_ at the
   transport level by doing a _client certificate based authentication_.

9.7.3.1.  Routers are trusted

   _Routers_ are _trusted_ by _Clients_.

   In particular, _Routers_ can read (and modify) any application
   payload transmitted in events, calls, call results and call errors
   (the "Arguments" or "ArgumentsKw" message fields).

   Hence, _Routers_ do not provide confidentiality with respect to
   application payload, and also do not provide authenticity or
   integrity of application payloads that could be verified by a
   receiving _Client_.

   _Routers_ need to read the application payloads in cases of automatic
   conversion between different serialization formats.

   Further, _Routers_ are trusted to *actually perform* routing as
   specified.  E.g. a _Client_ that publishes an event has to trust a




Oberstein                Expires March 30, 2016                [Page 55]


Internet-Draft                  WAMP - BP                 September 2015


   _Router_ that the event is actually dispatched to all (eligible)
   _Subscribers_ by the _Router_.

   A rogue _Router_ might deny normal routing operation without a
   _Client_ taking notice.

9.8.  Binary conversion of JSON Strings

   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

   _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.



Oberstein                Expires March 30, 2016                [Page 56]


Internet-Draft                  WAMP - BP                 September 2015


9.8.1.  Python

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

       ```python
       <CODE BEGINS>

       import os, base64, json, sys, binascii
       PY3 = sys.version_info >= (3,)
       if PY3:
          unicode = str

       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)

       <CODE ENDS>
       ```

9.8.2.  JavaScript

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










Oberstein                Expires March 30, 2016                [Page 57]


Internet-Draft                  WAMP - BP                 September 2015


      ```javascript
      <CODE BEGINS>

      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);

      <CODE ENDS>
      ```

10.  Security Considerations

   -- write me --





Oberstein                Expires March 30, 2016                [Page 58]


Internet-Draft                  WAMP - BP                 September 2015


11.  IANA Considerations

   TBD

12.  Contributors

13.  Acknowledgements

14.  References

14.1.  Normative References

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
              2003, <http://www.rfc-editor.org/info/rfc3629>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, DOI 10.17487/RFC3986, January 2005,
              <http://www.rfc-editor.org/info/rfc3986>.

   [RFC6455]  Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC
              6455, DOI 10.17487/RFC6455, December 2011,
              <http://www.rfc-editor.org/info/rfc6455>.

14.2.  Informative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

14.3.  URIs

   [1] http://www.iana.org/assignments/websocket/websocket.xml

Author's Address

   Tobias G. Oberstein
   Tavendo GmbH

   Email: tobias.oberstein@tavendo.de









Oberstein                Expires March 30, 2016                [Page 59]