backplane.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="./lib/xslt/rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "./lib/xslt/rfc2629.dtd" [
  <!ENTITY RFC2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
  <!ENTITY RFC2616 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
  <!ENTITY RFC2617 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml">
  <!ENTITY RFC4086 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4086.xml">
  <!ENTITY RFC4627 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
]>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Echo"?>
<rfc>
  <front><!-- [[[ -->
    <title abbrev="Backplane">Backplane 2.0 - draft 04</title>

    <author fullname="Chris Saad" initials="C." surname="Saad"> 
      <organization>Echo</organization>
      <address>
        <email>chris@aboutecho.com</email>
        <uri>http://aboutecho.com</uri>
      </address>
    </author>

    <author fullname="Vlad Skvortsov" initials="V." surname="Skvortsov">
      <organization>Echo</organization>
      <address>
        <email>vss@aboutecho.com</email>
        <uri>http://aboutecho.com</uri>
      </address>
    </author>

    <author fullname="Yuri Lukyanov" initials="Y." surname="Lukyanov">
      <organization>Echo</organization>
      <address>
        <email>snaky@aboutecho.com</email>
        <uri>http://aboutecho.com</uri>
      </address>
    </author>

    <author fullname="Alexander Zhuravlev" initials="A." surname="Zhuravlev">
      <organization>Echo</organization>
      <address>
        <email>zaa@aboutecho.com</email>
        <uri>http://aboutecho.com</uri>
      </address>
    </author>

    <author fullname="Ivan Glushkov" initials="I." surname="Glushkov">
      <organization>Echo</organization>
      <address>
        <email>gli@aboutecho.com</email>
        <uri>http://aboutecho.com</uri>
      </address>
    </author>

    <author fullname="Carl Howells" initials="C." surname="Howells">
      <organization>Janrain</organization>
      <address>
        <email>chowells@janrain.com</email>
        <uri>http://www.janrain.com/</uri>
      </address>
    </author>

    <author fullname="Johnny Bufu" initials="J." surname="Bufu">
      <organization>Janrain</organization>
      <address>
        <email>jbufu@janrain.com</email>
        <uri>http://www.janrain.com/</uri>
      </address>
    </author>

    <date day="3" month="May" year="2011" />

    <keyword>Internet-Draft</keyword>

    <abstract>
      <t>Backplane is a framework that facilitates message exchanges
          and event notifications between third-party JavaScript
          components within a web page.</t>
    </abstract>

  </front><!-- ]]] -->

  <middle><!-- [[[ -->
    <section anchor="introduction" title="Introduction"><!-- [[[ -->
      <t>Web pages have evolved from being loaded from a single resource
          to being able to reference third-party, external components
          that get loaded, run and rendered by the web browser within
          the same web page.</t>

      <t>These components can be active and continue to run after the
          web page completed loading and are generally decoupled
          &mdash; not under the control of a single entity.</t>

      <t>Interactions between the end user, the web page, and its
          features provided through such components can greatly benefit
          when all parties involved can exchange information with each
          other, and can do it in a standardized way.</t>

      <t>The Backplane framework facilitates such interactions by
          providing an open standard API that is secure in the context
          of the assumed trust relationships between the parties
          involved. Messages are delivered reliably and in order. The
          framework may be used in different scenarios which build on
          top of the transport-level semantics described in this
          document.</t>
    </section><!-- ]]] -->


    <section anchor="definitions" title="Definitions">

      <t>
        <list style="hanging">

          <t hangText="Web Page">
            Document obtained from a web resource and loaded by the end
            user's web browser.
          </t>

          <t hangText="Widget">
            Third-party JavaScript component referenced from the Web
            Page that is loaded and run in the end user's browser.
          </t>

          <t hangText="Backplane Client">
            Entity that uses the Backplane framework to exchange
            information.
          </t>

          <t hangText="Backplane Message">
            A JSON object representing the unit of communication between
            Backplane Clients.
          </t>

          <t hangText="Backplane Header">
            A Backplane Message without the payload field.
          </t>

          <t hangText="Backplane JavaScript API">
            JavaScript API used by Widgets to initialize and subscribe
            to Backplane Messages.
          </t>

          <t hangText="Backplane JavaScript Library">
            Backplane JavaScript API implementation.
          </t>

          <t hangText="Backplane Server API">
            Server API through which Backplane Clients send and retrieve
            Backplane Messages.
          </t>

          <t hangText="Backplane Server">
            Backplane Server API implementation.
          </t>

          <t hangText="Bus">
            Logical grouping of Backplane Clients that need to interact
            with each other, typically belonging to one organization.
          </t>

          <t hangText="Channel">
            Subset of Backplane Messages that belong to a Bus and are
            addressed to the Backplane Clients interacting with the end
            user through a single session and Web Page.
          </t>

          <t hangText="Message Sequence">
            A set of Backplane Messages that meet a certain filter criteria,
            in the same order as they have been received by a Backplane
            server.
          </t>

          <t hangText="Message Age">
            The length of time since the Message was received by the
            Backplane server.
          </t>

        </list>
      </t>

      <section title="Requirements Language">
        <t>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 <xref target="RFC2119">RFC 2119</xref>.</t>
      </section>

    </section>

    <section anchor="overview" title="Overview"><!-- [[[ -->
      <t>
        An operational Backplane framework consists of the following
        components:
        <list style="symbols">
          <t>A Backplane Server</t>
          <t>A Backplane JavaScript Library</t>
          <t>Widgets that act as Backplane Clients</t>
          <t>Widgets' server-side counterparts that act as Backplane Clients.</t>
        </list>
      </t>

      <t>A Backplane Server is an independent orchestrator of the
        message interchange between Backplane Clients and may serve
        multiple independent Buses.</t>

      <t>A Backplane framework instance needs to be configured prior to use:
        all Backplane Clients and the Server have to share the same Bus. 
        Backplane Clients operating at the
        <xref target="access.level.privileged">Privileged Access Level</xref>
        need a password to authenticate themselves to the Server. It is
        outside the scope of this document how such configuration is
        performed.</t>

    </section> <!-- ]]] -->

    <section anchor="trust" title="Trust">
      <t>
        The Backplane framework is intended to be used and operate under
        the following trust relationships. Any number of security issues
        can arise if any of these assumptions do not hold.</t>
      <t>
        <list>
          <t>
            The end user trusts the Web Page owner (and indirectly all
            Widget owners) that the Web Page will not attack or exploit
            their web browser.
          </t>
          <t>
            The Web Page owner (and indirectly the end user) trusts all
            Widget owners that the Widgets will not abuse the Backplane
            framework by trying to impersonate other Widgets' behavior
            in order to obtain and access information that is not
            directed to them, such as end user account information
            addressed to other Widgets.
          </t>
          <t>
            The Web Page owner (and indirectly the end user), and
            Widget owners trust the Backplane Server API and Backplane
            JavaScript API implementations that they will comply with
            this specification.
          </t>
          <t>
            The Web Page owner (and indirectly the end user) trusts
            all content on the Web Page to not attack the widgets or
            the Backplane framework. This must explicitly include all
            JavaScript loaded for any purpose, including JavaScript
            that is not part of any of the Widgets on the Web Page.
          </t>
          <t>
            Backplane Clients trust the Bus owner and the authenticity
            of Backplane Messages received through a Bus, i.e all
            Backplane Clients that were granted permission to post on
            the Bus by its owner.
          </t>
        </list>
      </t>
    </section>

    <section anchor="access.levels" title="Access Levels">

      <t>
        Considering the significantly different security enforcement
        capabilities of applications running in a web browser versus the
        ones running on a web server, two access levels are defined for
        Backplane Clients: Regular and Privileged.
      </t>

      <section anchor="access.level.regular" title="Regular Access">
        <t>
          Regular access level is given to Backplane Clients running in
          the web browser (Widgets and the Backplane JavaScript Library).
        </t>
        <t>
          Regular access level is exercised without presenting any
          authorization credentials aside from the Message Sequence
          identifier.
          Bus owners and Backplane Servers acting on their behalf MUST
          NOT give authorization credentials for Privileged access level
          to Backplane Clients running in the web browser.
        </t>
        <t>
          Backplane Server MUST only make Backplane Message Headers (not
          full Backplane Messages) available to Clients having Regular
          access level.
        </t>
      </section>

      <section anchor="access.level.privileged" title="Privileged Access">
        <t>
          Privileged access level is given to Backplane Clients that
          are not running in a web browser, typically the Widgets'
          server-side components.
        </t>
        <t>
          Privileged access level is exercised by presenting
          authorization credentials obtained from the Bus owner for such
          operations. The authorization credentials MUST be sent using
          HTTP Basic Authentication with the corresponding Backplane
          Server API requests. Backplane Servers MUST validate the
          authorization credentials for all Backplane Server API
          operations that require Privileged access level, summarized
          below (see <xref target="backplane.server.api">Backplane Server
          API</xref>).
          The provisioning of Privileged access level credentials is
          outside of the scope of this specification.
        </t>
        <t>
          Backplane Clients having Privileged access level can perform
          the following operations on a Bus for which they have obtained
          authorization credentials from the Bus owner:
          <list style="symbols">
            <t>
              retrieve all Backplane Messages sent to the Bus (XXX: xref)
            </t>
            <t>
              post Backplane Messages to a Channel (XXX: xref)
            </t>
          </list>
        </t>
      </section>

    </section>

    <section anchor="padded.response" title="Padded Responses">
      <t>
        For API requests made by the Javascript Library, the response
        is formatted specially.
      </t>
      <t>
        The response body begins with the value of
        the <spanx type="emph">callback</spanx> parameter from the
        request.  That value is followed by a &quot;(&quot; (opening
        parenthesis), then the JSON-encoded result value, then a
        &quot;)&quot; (closing parenthesis).
      </t>
    </section>

    <section anchor="buses" title="Buses">
      <t>
        A Bus is a logical grouping of Backplane Clients that need to
        interact with each other, typically belonging to one
        organization. Buses allow a Backplane Server to service
        multiple customers. Bus names are short strings
        referencing the Bus owner's name (e.g. "customer.com",
        "organization.org").
        Backplane Clients must know the identifiers for the Buses through
        which they wish to exchange Backplane Messages.
      </t>
      <t>
        It is assumed that a relationship of trust exists between all
        clients granted permission to post messages to a specific
        Bus (see <xref target="trust">Trust</xref>).
      </t>
    </section>

    <section anchor="channels" title="Channels">
      <t>
        A Channel is a subset of Backplane Messages that belong to a Bus
        and are addressed to the Backplane Clients interacting with the
        end user through a single session and Web Page. A Channel is
        similar to a session identifier for the user but is shared by
        multiple Backplane Clients.
      </t>

      <t>Channels are:
        <list style="symbols">
          <t>allocated within Buses</t>
          <t>referenced by unique, unguessable identifiers</t>
          <t>created implicitly once a Backplane Message gets
            posted to a channel that doesn't yet exist</t>
          <t>non-persistent and expire after being inactive (no
            messages posted) for specific amount of time (e.g. 30
            minutes)</t>
          <t>sensitive (i.e. content that cannot be trusted to keep the
            Channel identifier secret MUST NOT be loaded)</t>
        </list>
      </t>

      <t>
        Channel identifiers are used by Backplane Clients for message
        retrieval. All Backplane Clients that know a given Channel identifier
        can receive Backplane Messages posted to that Channel.
      </t>

      <t>Channel identifiers MUST only contain characters from the
        <xref target="RFC4648.section5">base64url</xref> character set
        and be at least 32 characters long.
      </t>
    </section>

    <section anchor="backplane.messages" title="Backplane Messages">
      <t>A Backplane message is a JSON object with the following fields:
        <list style="hanging">
          <t hangText="bus (string)">
            the name of the Bus the message was posted to
          </t>
          <t hangText="channel (string)">
            the identifier of Channel the message was posted to
          </t>
          <t hangText="messageURL (string)">
            a URL that a client can use to retrieve the message
          </t>
          <t hangText="source (string)">
            an arbitrary URL identifying the client which posted the message
          </t>
          <t hangText="payload (object)">
            arbitrary data specific to the particular message type
          </t>
          <t hangText="type (string)">
            message type
          </t>
        </list>
      </t>

      <t>
        The presence of certain fields in a Backplane message depends on the
        context it appears in.
      </t>

      <t>
        A downstream (server-to-client) Backplane message MUST contain all
        the fields listed above. If the client receiving the message has
        regular access, the server MUST omit the "payload" field.
      </t>

      <t>
        An upstream (client-to-server) Backplane message MUST only contain
        the following fields: "bus", "channel", "payload", "type".
      </t>

      <figure>
        <preamble>
          Example downstream Backplane Message:
        </preamble>
        <artwork type="code">
{
        "bus": "customer.com",
        "channel": "67dc880cc265b0dbc755ea959b257118",
        "messageURL": "https://bp.example.com/v2/message/097a5cc401001f95b45d37aca32a3bd2",
        "source": "http://aboutecho.com",
        "payload": {
                "role": "administrator"
        },
        "type": "identity/ack"
}
        </artwork>
      </figure>

    </section>

    <section anchor="backplane.server.api" title="Backplane Server API"><!-- [[[ -->

      <section anchor="backplane.server.conventions" title="Message Retrieval Conventions">
        <t>
          Backplane Servers MUST maintain a buffer of messages received from
          all their clients until messages become older than a certain
          threshold. Such threshold MUST be no less than 1 minute. It is
          RECOMMENDED that Backplane Servers set the threshold to at least 5
          minutes. A message is considered obsolete once its age reaches the
          threshold.
        </t>

        <t>
          It is RECOMMENDED that Backplane Servers make messages available
          for retrieval as soon as possible after they are posted.
        </t>

        <t>
          Backplane Clients that require reliable message delivery
          MUST poll their Backplane Servers with an interval of 30
          seconds or less in order to avoid omissions.
        </t>

        <t>
          Backplane Clients retrieve messages from a Backplane Server by
          presenting a Message Sequence identifier (see XXX). The server's
          response to such request includes a set of messages matching
          certain criteria and a new Sequence identifier which can be
          presented by the Client in a later call to the Server.
        </t>

        <t>
          A Backplane Server keeps record of provisioned Sequence
          identifiers and maps each of them to a set of filters along with a
          reference to the Backplane Message in the Server's message buffer.
          A Sequence identifier is considered obsolete if it references an
          obsolete message.
        </t>

        <t>
          If a Backplane Server receives a request to retrieve Messages with
          an obsolete Sequence identifier, it serves the request as if the
          Sequence identifier refered to the oldest Message still in the
          buffer.
        </t>

      </section>

      <section anchor="backplane.server.api.get.bus"
          title="Get All Messages From Buses">
        <t><list style="hanging">
            <t hangText="HTTP Method">GET</t>
            <t hangText="Endpoint">
              <spanx style="verb">/v2/bus</spanx></t>
            <t hangText="Security">HTTPS with
              <xref target="access.level.privileged">Privileged Access Level</xref></t>
            <t hangText="Parameters">
              <list style="symbols">
                <t>
                  callback (string, optional) &mdash; the
                  <xref target="padded.response">callback name</xref> to
                  pad the response with
                </t>
                <t>
                  busName (string, one or many) &mdash; names of the buses
                  to retrieve messages from
                </t>
              </list>
            </t>
            <t hangText="Returns">
              <list style="symbols">
                <t>
                  On success &mdash; status code 200 ("OK"). The response
                  body is then a JSON object of the following structure:
                  <list style="symbols">
                    <t>
                      nextSequenceURL (string) &mdash; a URL that the Client
                      can use to retrieve the first sequence of messages from
                      the requested buses.
                    </t>
                  </list>
                </t>
                <t>
                  If the Client is not authorized to retrieve messages from
                  the requested Bus, status code 401 ("Not Authorized") is
                  returned.
                </t>
                <t>
                  If the requested Bus name is not known to the server,
                  status code 404 ("Not Found") is returned.
                </t>
              </list>
            </t>
          </list>
        </t>
        <t>
          This method is used by Backplane Clients to receive all
          messages distributed on specific Buses. A Client is only able to
          retrieve messages from buses it has been granted access to (per
          the Server configuration).
        </t>

      <figure>
        <preamble>
          Example response:
        </preamble>
        <artwork type="code">
{
  "nextSequenceURL": "https://bp.example.com/v2/sequence/958bfa2dd8aed82c86afbd54b4a314a5"
}
        </artwork>
      </figure>
      </section>

      <section anchor="backplane.server.api.new_channel"
        title="Get Messages From A New Channel">
        <t>
          <list style="hanging">
            <t hangText="HTTP Method">GET</t>
            <t hangText="Endpoint">
              <spanx style="verb">/v2/channel</spanx></t>
            <t hangText="Security">optional HTTPS,
              <xref target="access.level.regular">Regular Access Level</xref></t>
            <t hangText="Parameters">
              <list style="symbols">
                <t>
                  callback (string, optional) &mdash; the
                  <xref target="padded.response">callback name</xref> to
                  pad the response with
                </t>
              </list>
            </t>
            <t hangText="Returns">
              <list style="symbols">
                <t>
                  Status code 200 ("OK"). The response body is a JSON object
                  of the following structure:
                  <list style="symbols">
                    <t>
                      channel (string) &mdash; unguessable channel name
                    </t>
                    <t>
                      nextSequenceURL (string) &mdash; a URL that the Client
                      can use to retrieve the first sequence of messages from
                      the newly allocated Channel
                    </t>
                  </list>
                </t>
              </list>
            </t>
          </list>
        </t>
        <t>
          This method allocates a new Backplane Channel and returns its name
          to the Client. The channel name MUST be at least 32 characters
          indepedently chosen with uniform distribution from the
          set <spanx style="emph">0123456789abcdef</spanx>. The
          channel name MUST NOT be guessable given knowledge of the
          algorithms in use or any details of the request being made
          (<xref target="RFC4086">RFC 4086</xref> discusses the
          requirements and pitfalls of generating unguessable values in great
          detail).
        </t>

        <t>As an operational note, this API call SHOULD NOT be
          implemented in a way that makes it capable of blocking and
          use of one of the mechanisms in section 7 of
          <xref target="RFC4086">RFC 4086</xref> is RECOMMENDED.
        </t>

        <t>
          The Sequence identifier returned by this method can be used by the
          Client to retrieve messages posted to the newly created Channel.
        </t>

        <figure>
          <preamble>
            Example response:
          </preamble>
          <artwork type="code">
{
	"channel": "67dc880cc265b0dbc755ea959b257118"
	"nextSequenceURL": "https://bp.example.com/v2/sequence/958bfa2dd8aed82c86afbd54b4a314a5"
}
          </artwork>
        </figure>
      </section>

      <section anchor="backplane.server.api.post.message"
        title="Post Messages To A Channel">
        <t><list style="hanging">
            <t hangText="HTTP Method">POST</t>
            <t hangText="Endpoint">
              <spanx style="verb">/v2/message</spanx></t>
            <t hangText="Security">HTTPS,
              <xref target="access.level.privileged">Privileged Access Level</xref></t>
            <t hangText="HTTP Request Body">an array of
              <xref target="backplane.messages">upstream Backplane
                messages</xref>
            </t>
            <t hangText="Returns">
              <list style="symbols">
                <t>
                  Status code 201 ("Created") on success.
                </t>
                <t>
                  Status code 401 ("Not Authorized") if the Client is not
                  authorized to post messages to a bus or channel.
                </t>
                <t>
                  Status code 404 ("Not Found") if the requested Bus or
                  channel name is not known to the server.
                </t>
              </list>
            </t>
          </list>
        </t>
        <t>
          This method injects one or more Backplane Messages to the
          Channels and Buses. Channels that do not exist are created and
          associated with corresponding buses.
        </t>
        <t>
          The server MUST ensure the client posts messages to buses it has
          been granted access to.
        </t>
        <t>
          The server MUST process the request as a whole. If any of the
          messages in the request body cannot be processed successfully, the
          entire request MUST be discarded.
        </t>
        <figure>
          <preamble>
            Example request:
          </preamble>
          <artwork type="code">
[
        {
                "bus": "customer.com",
                "channel": "67dc880cc265b0dbc755ea959b257118",
                "payload": {
                        "role": "administrator"
                },
                "type": "identity/ack"
        },
        {
                "bus": "organization.org",
                "channel": "96a6370f9dfc61ae12070b284acc8603",
                "payload": {
                        "role": "moderator"
                },
                "type": "identity/ack"
        }
]
          </artwork>
        </figure>
      </section>

      <section anchor="backplane.server.api.get.message" title="Get Message">
        <t>
          <list style="hanging">
            <t hangText="HTTP Method">GET</t>
            <t hangText="Endpoint">
              <spanx style="verb">/v2/message/&lt;MSG&gt;</spanx></t>
            <t hangText="Security">optional HTTPS</t>
            <t hangText="Parameters">
              <list style="symbols">
                <t>
                  callback (string, optional) &mdash; the
                  <xref target="padded.response">callback name</xref> to
                  pad the response with
                </t>
              </list>
            </t>
            <t hangText="Returns">
              <list style="symbols">
                <t>
                  Status code 200 ("OK") if the message is available in the
                  server's buffer. The response body is the requested
                  downstream Backplane message.
                </t>
                <t>
                  Status code 404 ("Not Found") if the message is not
                  present in the server's buffer.
                </t>
              </list>
            </t>
          </list>
        </t>

        <t>
          Note that the availability of the message depends on its age and
          the size of the server's buffer (see <xref
          target="backplane.server.conventions">Message Retrieval
          Conventions</xref>).
        </t>

        <t>
          Since the message returned by this method is a downstream one,
          the "payload" field is only available to clients with Privileged
          access (see <xref target="backplane.messages">Backplane
          messages</xref>).
        </t>

        <figure>
          <preamble>
            Example response to a privileged access client:
          </preamble>
          <artwork type="code">
{
        "bus": "customer.com",
        "channel": "67dc880cc265b0dbc755ea959b257118",
        "messageURL": "https://bp.example.com/v2/message/097a5cc401001f95b45d37aca32a3bd2",
        "source": "http://aboutecho.com",
        "payload": {
                "role": "administrator"
        },
        "type": "identity/ack"
}
          </artwork>
        </figure>
      </section>

      <section anchor="backplane.server.api.get.sequence"
        title="Get Message Sequence">
        <t><list style="hanging">
            <t hangText="HTTP Method">GET</t>
            <t hangText="Endpoint">
              <spanx style="verb">/v2/sequence/&lt;SEQ&gt;</spanx>
            </t>
            <t hangText="Security">
              <xref target="access.level.privileged">Privileged Access Level</xref>
              with HTTPS, or
              <xref target="access.level.regular">Regular Access Level</xref>
              with either HTTP or HTTPS.
            </t>
            <t hangText="Parameters">
              <list style="symbols">
                <t>block (integer, default 0) &mdash; if no messages are
                  available for immediate retrieval, this parameter
                  communicates how long (in seconds) the server should wait
                  before returning an empty response
                </t>
                <t>
                  callback (string, optional) &mdash; the
                  <xref target="padded.response">callback name</xref> to
                  pad the response with
                </t>
              </list>
            </t>
            <t hangText="Returns">
              <list style="symbols">
                <t>
                  Status code 200 ("OK") if the sequence identifier is known
                  to the server. The response body is a JSON object of the
                  following structure:
                  <list style="symbols">
                    <t>
                      nextSequenceURL (string) &mdash; a URL that the Client
                      can use to retrieve the next sequence of messages 
                      meeting the original selection criteria
                    </t>
                    <t>
                      messages (array) &mdash; an array of
                      <xref target="backplane.messages">downstream Backplane
                      messages</xref>
                    </t>
                  </list>
                </t>
                <t>
                  Status code 404 ("Not Found") if the sequence identifier
                  is unknown to the server.
                </t>
              </list>
            </t>
          </list>
        </t>

        <t>
          This API method retrieves a sequence of Backplane messages meeting
          criteria set with either
          <xref target="backplane.server.api.get.bus">"Get All Messages From
          Buses"</xref> (messages posted to specific buses)
          or <xref target="backplane.server.api.new_channel">"Get Messages
          From A New Channel"</xref> (messages posted to a specific channel).
        </t>

        <t>
          Since messages returned by this method are downstream ones,
          the "payload" fields are only available to clients with Privileged
          access (see <xref target="backplane.messages">Backplane
          messages</xref>).
        </t>

        <figure>
          <preamble>
            Example response to a privileged access client:
          </preamble>
          <artwork type="code">
{
	"nextSequenceURL": "https://bp.example.com/v2/chain/958bfa2dd8aed82c86afbd54b4a314a5",
	"messages": [
		{
			"bus": "customer.com",
			"channel": "67dc880cc265b0dbc755ea959b257118",
			"messageURL": "https://bp.example.com/v2/message/097a5cc401001f95b45d37aca32a3bd2",
                        "source": "http://aboutecho.com",
			"payload": {
				"role": "administrator"
			},
			"type": "identity/ack"
		}
	]
}
          </artwork>
        </figure>
      </section>

    </section><!-- ]]] -->

    <section anchor="backplane.javascript.api" title="Backplane JavaScript API"><!-- [[[ -->

      <t>A Backplane JavaScript Library runs in an end user's browser
        and mediates communication between Backplane-enabled Widgets on
        the page and the Backplane Server.</t>

      <t>Only one instance of the Backplane JavaScript Library on a
        given page is possible. The library has to be the first to load
        on the page to make it possible for other scripts to use its
        subscription functionality.</t>

      <figure>
        <preamble>The Backplane JavaScript Library provides the following
          API (all methods are static): </preamble>
        <artwork type="code">
/**
 * Initializes the backplane library
 *
 * @param {Object} Params - hash with configuration parameters.
 *   Possible hash keys:
 *     serverBaseURL (required) - Base URL of Backplane Server
 *     busName (required) - Customer's backplane bus name
 */
Backplane.init(Params);

/**
 * Subscribes to messages from Backplane server
 *
 * @param {Function} Callback - Callback function which accepts backplane messages.
 * @returns Subscription ID which can be used later for unsubscribing.
 */
Backplane.subscribe(Callback);

/**
 * Removes specified subscription
 *
 * @param {Integer} Subscription ID
 */
Backplane.unsubscribe(SubscriptionID);

/**
 * Returns channel ID (like http://backplane.customer.com/v2/bus/customer.com/channel/8ec92f459fa70b0da1a40e8fe70a0bc8)
 *
 * @returns Backplane channel ID
 */
Backplane.getChannelID();

/**
 * Notifies backplane library about the fact that subscribers are going
 * to receive backplane messages within specified time interval.
 *
 * @param {Integer} TimeInterval - Time interval in seconds
 * @param {Array} MessageTypes (optional) - a list of expected message types
 */
Backplane.expectMessagesWithin(TimeInterval, MessageTypes);
        </artwork>
      </figure>

      <section anchor="client.side.library.init"
        title="Initialization">
        <t>Backplane is initialized using the
          <spanx style="verb">Backplane.init</spanx> method.</t>

        <t>During initialization the library generates a random
          Channel Name unless information about one for the specified
          <spanx style="emph">bus name</spanx> already exists in the
          <spanx style="verb">backplane-channel</spanx> cookie. Since
          client-side generation of the channel name is non-secure,
          the library performs a request to obtain a channel name
          from the Backplane Server.</t>

        <t>After initialization the library stores the current Channel
          Name in the <spanx style="verb">backplane-channel</spanx>
          cookie set against the complete domain name of currently
          opened page. The cookie is set for 5 years in advance and
          keeps information about association of Bus names to Channel
          Names (to support possibility to use the library with several
          different Bus names on the same domain). The information
          about the association is stored in a serialized form.</t>

        <figure>
          <preamble>Here is an example of cookie that stores association
            of Bus names <spanx style="verb">example.com</spanx> and
            <spanx style="verb">example.org</spanx> to the corresponding
            channel names <spanx style="verb">123</spanx> and
            <spanx style="verb">456</spanx>:</preamble>
          <artwork type="example">backplane-channel=example.com:123|example.org:456</artwork>
        </figure>

        <t>After the channel ID has been determined, the library
          performs a first reading of messages from a channel, discards
          all of them (remembering only the identifier of the very
          last one) and starts polling the Backplane Server for new
          messages since the latest Backplane Message. This way the
          library is guaranteed to push to subscribers only those
          Backplane Messages which arrived after the library had been
          fully initialized.</t>

      </section>

      <section anchor="client.side.library.subscription"
          title="Subscription Management">
        <t>The library provides a method for Widgets to set up
          notification callbacks: <spanx style="verb">Backplane.subscribe</spanx>.
          The method returns a subscription id which can be later used
          for unsubscribing using the <spanx style="verb">Backplane.unsubscribe</spanx>
          method.</t>

        <t>After the initialization the library starts polling the
          Backplane Server for new events. All incoming events are
          delivered to the Widgets that have registered callbacks with
          the library. </t>

      </section>
      <section anchor="client.side.library.hints"
          title="Hints">
        <t>For performance reasons the Backplane JavaScript Library
          polls the Backplane Server with a low frequency (e.g once a
          minute). Since Backplane events usually are initiated on the
          client side (e.g. the user clicking a button), Widgets on the
          page are in a position to hint the library that a Backplane
          message may be soon delivered. Upon the receipt of such hint
          (via <spanx style="verb">expectMessagesWithin</spanx> method),
          the library temporarily increases the polling frequency (e.g.
          to once a second) and then gradually decreases it to the
          default low value one.</t>

        <t>The <spanx style="verb">expectMessagesWithin</spanx> method
          can accept an optional list of expected message types.
          <list>
            <t>If the library accepts <spanx style="emph">any</spanx>
              message from the passed message types list, it gradually
              returns to the lower polling frequency mode;</t>
            <t>If messages with only one type are expected, the second
              argument may be specified as a string;</t>
            <t>Each call of the method adds passed message types to the
              list of expected message types. In other words, if
              a user calls the method with a message type "type1" and
              then performs one more call with a message type "type2",
              the library will run in the fast polling mode until it
              received messages of <spanx style="emph">all</spanx>
              the types or until the libray reached the maximum allotted
              waiting time interval.</t>
          </list>
        </t>
      </section>

      <section anchor="client.side.library.example"
          title="Usage Example">
        <figure><artwork type="code">
Backplane.init({
    serverBaseURL: "http://backplane.customer.com/v2",
    busName: "customer.com"
});

var escSubscription = Backplane.subscribe(function(backplaneMessage) {
    alert(backplaneMessage.payload);
});

// We can ask the library to perform more frequent polling
// if a widget, for example, expects a message from Backplane pretty soon
// using the expectMessagesWithin method which accepts
// time interval of possible message arrival in seconds
Backplane.expectMessagesWithin(10);

// The method can accept an option list with expected message types.
// The library stops fast polling when it receives a message of
// either type.
Backplane.expectMessagesWithin(10, ["type1", "type2"]);

// Subsequent calls extend the list of expected message types.
// The library stops fast polling only after it has received
// a message of type1 or type2 AND a message of type3 or type4.
Backplane.expectMessagesWithin(10, ["type3", "type4"]);

Backplane.unsubscribe(escSubscription);

// If a widget needs Backplane channel ID it can get it using the
// getChannelID method
Backplane.getChannelID();
        </artwork></figure>
      </section>
    </section><!-- ]]] -->
    <section title="Security Considerations">
      <t>
        See <xref target="trust">Trust</xref>.
      </t>
      <section title="Channel Name Sensitivity">
        <t>
          The Channel Name acts as a session identifier shared among a
          group of trusted parties. Knowledge of a Channel Name offers
          Regular Access level to Backplane Server API.
        </t>
        <t>
          It is therefore important that the Channel Name is not
          compromised, by either:
          <list style="symbols">
            <t>
              Trusting any third-party JavaScript source included in the
              Web Page without due verification, or
            </t>
            <t>
              Disclosing Channel Names to untrusted parties.
            </t>
          </list>
        </t>
      </section>
      <section title="Message Payloads">
        <t>
          Message payloads are only sent to Backplane Clients at
          <xref target="access.level.privileged">Privileged Access Level</xref>.
          This is in order to allow sensitive data to be exchanged
          among server-side Backplane Clients, while not allowing it to
          reach the less secure context of web browser.
        </t>
        <t>
          It is therefore important that
          <xref target="access.level.privileged">Privileged Access Level</xref>
          credentials are not provisioned to Backplane Clients that run
          in a web browser.
        </t>
      </section>
    </section>
  </middle><!-- ]]] -->

  <back><!-- [[[ -->
    <references title="Normative References"><!-- [[[ -->

      &RFC2616;

      &RFC2617;

      &RFC4627;

      &RFC4086;

      &RFC2119;

      <reference
        anchor="RFC4648.section5"
        target="http://tools.ietf.org/html/rfc4648#section-5">
        <front>
          <title>The Base16, Base32, and Base64 Data Encodings</title>
          <author initials="S." surname="Josefsson"
            fullname="S. Josefsson">
            <organization>SJD</organization>
          </author>
          <date year="2006" month="October" />
        </front>
      </reference>
    </references><!-- ]]] -->
  </back><!-- ]]] -->
</rfc>
<!-- vim: set ts=2 sts=2 sw=2 tw=72 et fdm=marker fmr=[[[,]]]: -->