path: root/doc/rfc/rfc8895.txt

Internet Engineering Task Force (IETF)                          W. Roome
Request for Comments: 8895                               Nokia Bell Labs
Category: Standards Track                                        Y. Yang
ISSN: 2070-1721                                          Yale University
                                                           November 2020


Application-Layer Traffic Optimization (ALTO) Incremental Updates Using
                        Server-Sent Events (SSE)

Abstract

   The Application-Layer Traffic Optimization (ALTO) protocol (RFC 7285)
   provides network-related information, called network information
   resources, to client applications so that clients can make informed
   decisions in utilizing network resources.  This document presents a
   mechanism to allow an ALTO server to push updates to ALTO clients to
   achieve two benefits: (1) updates can be incremental, in that if only
   a small section of an information resource changes, the ALTO server
   can send just the changes and (2) updates can be immediate, in that
   the ALTO server can send updates as soon as they are available.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc8895.

Copyright Notice

   Copyright (c) 2020 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
   (https://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
   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
   2.  Terms
     2.1.  Requirements Language
   3.  Background
     3.1.  Incremental Encoding: JSON Merge Patch
       3.1.1.  JSON Merge Patch Encoding
       3.1.2.  JSON Merge Patch ALTO Messages
     3.2.  Incremental Encoding: JSON Patch
       3.2.1.  JSON Patch Encoding
       3.2.2.  JSON Patch ALTO Messages
     3.3.  Multiplexing and Server Push: HTTP/2
     3.4.  Server Push: Server-Sent Event
   4.  Overview of Approach and High-Level Protocol Message Flow
     4.1.  Update Stream Service Message Flow
     4.2.  Stream Control Service Message Flow
     4.3.  Service Announcement and Management Message Flow
   5.  Update Messages: Data Update and Control Update Messages
     5.1.  Generic ALTO Update Message Structure
     5.2.  ALTO Data Update Message
     5.3.  ALTO Control Update Message
   6.  Update Stream Service
     6.1.  Media Type
     6.2.  HTTP Method
     6.3.  Capabilities
     6.4.  Uses
     6.5.  Request: Accept Input Parameters
     6.6.  Response
     6.7.  Additional Requirements on Update Stream Service
       6.7.1.  Event Sequence Requirements
       6.7.2.  Cross-Stream Consistency Requirements
       6.7.3.  Multipart Update Requirements
     6.8.  Keep-Alive Messages
   7.  Stream Control Service
     7.1.  URI
     7.2.  Media Type
     7.3.  HTTP Method
     7.4.  IRD Capabilities & Uses
     7.5.  Request: Accept Input Parameters
     7.6.  Response
   8.  Examples
     8.1.  Example: IRD Announcing Update Stream Services
     8.2.  Example: Simple Network and Cost Map Updates
     8.3.  Example: Advanced Network and Cost Map Updates
     8.4.  Example: Endpoint Property Updates
     8.5.  Example: Multipart Message Updates
   9.  Operation and Processing Considerations
     9.1.  Considerations for Choosing Data Update Messages
     9.2.  Considerations for Client Processing Data Update Messages
     9.3.  Considerations for Updates to Filtered Cost Maps
     9.4.  Considerations for Updates to Ordinal Mode Costs
     9.5.  Considerations for SSE Text Formatting and Processing
   10. Security Considerations
     10.1.  Update Stream Server: Denial-of-Service Attacks
     10.2.  ALTO Client: Update Overloading or Instability
     10.3.  Stream Control: Spoofed Control Requests and Information
            Breakdown
   11. Requirements on Future ALTO Services to Use This Design
   12. IANA Considerations
     12.1.  application/alto-updatestreamparams+json Media Type
     12.2.  application/alto-updatestreamcontrol+json Media Type
   13. Appendix: Design Decision: Not Allowing Stream Restart
   14. References
     14.1.  Normative References
     14.2.  Informative References
   Acknowledgments
   Contributors
   Authors' Addresses

1.  Introduction

   The Application-Layer Traffic Optimization (ALTO) protocol [RFC7285]
   provides network-related information, called network information
   resources, to client applications so that clients may make informed
   decisions in utilizing network resources.  For example, an ALTO
   server provides network and cost maps, where a network map partitions
   the set of endpoints into a manageable number of sets each defined by
   a Provider-Defined Identifier (PID) and a cost map provides directed
   costs between PIDs.  Given network and cost maps, an ALTO client can
   obtain costs between endpoints by first using the network map to get
   the PID for each endpoint and then using the cost map to get the
   costs between those PIDs.  Such costs can be used by the client to
   choose communicating endpoints with low network costs.

   The ALTO protocol defines only an ALTO client pull model without
   defining a mechanism to allow an ALTO client to obtain updates to
   network information resources, other than by periodically re-fetching
   them.  In settings where an information resource may be large but
   only parts of it may change frequently (e.g., some entries of a cost
   map), complete re-fetching can be inefficient.

   This document presents a mechanism to allow an ALTO server to push
   incremental updates to ALTO clients.  Integrating server push and
   incremental updates provides two benefits: (1) updates can be small,
   in that if only a small section of an information resource changes,
   the ALTO server can send just the changes and (2) updates can be
   immediate, in that the ALTO server can send updates as soon as they
   are available.

   While primarily intended to provide updates to GET-mode network and
   cost maps, the mechanism defined in this document can also provide
   updates to POST-mode ALTO services, such as the ALTO endpoint
   property and endpoint cost services.  The mechanism can also support
   new ALTO services to be defined by future extensions, but a future
   service needs to satisfy requirements specified in Section 11.

   The rest of this document is organized as follows.  Section 3 gives
   background on the basic techniques used in this design: (1) JSON
   merge patch and JSON patch to allow incremental updates and (2)
   Server-Sent Events (SSE) [SSE] to allow server push.  With the
   background, Section 4 gives a non-normative overview of the design.
   Section 5 defines individual messages in an update stream.  Section 6
   defines the update stream service.  Section 7 defines the stream
   control service.  Section 8 gives several examples to illustrate the
   two types of services.  Section 9 describes operation and processing
   considerations by both ALTO servers and clients.  Section 13
   discusses a design feature that is not supported.  Section 10
   discusses security issues.  Sections 11 and 12 review the
   requirements for future ALTO services to use SSE and IANA
   considerations, respectively.

2.  Terms

   Besides the terminologies as defined in [RFC7285], this document also
   uses additional terminologies defined as follows:

   Update Stream:
      A reliable, in-order connection compatible with HTTP/1.x between
      an ALTO client and an ALTO server so that the server can push a
      sequence of update messages using [SSE] to the client.

   Update Stream Server:
      This document refers to an ALTO server providing an update stream
      as an ALTO update stream server, or update stream server for
      short.  Note that the ALTO server mentioned in this document
      refers to a general server that provides various kinds of
      services; it can be an update stream server or stream control
      server (see below).  It can also be a server providing ALTO
      Information Resource Directory (IRD).

   Update Message:
      A message that is either a data update message or a control update
      message.

   Data Update Message:
      An update message that is for a single ALTO information resource
      and sent from the update stream server to the ALTO client when the
      resource changes.  A data update message can be either a full-
      replacement message or an incremental-change message.  Full
      replacement is a shorthand for a full-replacement message, and
      incremental change is a shorthand for an incremental-change
      message.

   Full Replacement:
      A data update message for a resource that encodes the content of
      the resource in its original ALTO encoding.

   Incremental Change:
      A data update message that specifies only the difference between
      the new content and the previous version.  An incremental change
      can be encoded using either JSON merge patch or JSON patch in this
      document.

   Stream Control Service:
      A service that provides an HTTP URI so that the ALTO client of an
      update stream can use it to send stream control requests to the
      ALTO server on the addition or removal of resources receiving
      update messages from the update stream.  The ALTO server creates a
      new stream control resource for each update stream instance,
      assigns a unique URI to it, and sends the URI to the client as the
      first event in the stream.  (Note that the stream control service
      in ALTO has no association with the similarly named Stream Control
      Transmission Protocol [RFC4960].)

   Stream Control:
      A shorthand for stream control service.

   Stream Control Server:
      An ALTO server providing the stream control service.

   Substream-ID:
      An ALTO client can assign a unique substream-id when requesting
      the addition of a resource receiving update messages from an
      update stream.  The server puts the substream-id in each update
      event for that resource.  The substream-id allows a client to use
      one update stream to receive updates to multiple requests for the
      same resource (i.e., with the same resource-id in an ALTO IRD),
      for example, for a POST-mode resource with different input
      parameters.

   Data-ID:
      A subfield of the "event" field of [SSE] to identify the ALTO data
      (object) to be updated.  For an ALTO resource returning a
      multipart response, the data-id to identify the data (object) is
      the substream-id, in addition to the Content-ID of the object in
      the multipart response.  The data-id of a single-part response is
      just the substream-id.

   Control Update Message:
      An update message for the update stream server to notify the ALTO
      client of related control information of the update stream.  A
      control update message may be triggered by an internal event at
      the server, such as server overloading and hence the update stream
      server will no longer send updates for an information resource, or
      as a result of a client sending a request through the stream
      control service.  The first message of an update stream is a
      control update message that provides a control URI to the ALTO
      client.  The ALTO client can use the URI to send stream control
      requests to the stream control server.

2.1.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Background

   The design requires two basic techniques: encoding of incremental
   changes and server push.  For incremental changes, existing
   techniques include JSON merge patch and JSON patch; this design uses
   both.  For server push, existing techniques include HTTP/2 and [SSE];
   this design adopts some design features of HTTP/2 but uses [SSE] as
   the basic server-push design.  The rest of this section gives a non-
   normative summary of JSON merge patch, JSON patch, HTTP/2, and [SSE].

3.1.  Incremental Encoding: JSON Merge Patch

   To avoid always sending complete data, a server needs mechanisms to
   encode incremental changes, and JSON merge patch is one mechanism.
   [RFC7396] defines the encoding of incremental changes (called JSON
   merge patch objects) to be used by the HTTP PATCH method [RFC5789].
   From [RFC7396], this document adopts only the JSON merge patch object
   encoding and does not use the HTTP PATCH method, as the updates are
   sent as events instead of HTTP methods; also, the updates are server
   to client, and PATCH semantics are more for client to server.  Below
   is a non-normative summary of JSON merge patch objects; see [RFC7396]
   for the normative definition.

3.1.1.  JSON Merge Patch Encoding

   Informally, a JSON merge patch message consists of a JSON merge patch
   object (referred to as a patch in [RFC7396]), which defines how to
   transform one JSON value into another using a recursive merge patch
   algorithm.  Specifically, the patch is computed by treating two JSON
   values (first one being the original and the second being the
   updated) as trees of nested JSON objects (dictionaries of name/value
   pairs), where the leaves are values (e.g., JSON arrays, strings, and
   numbers), other than JSON objects, and the path for each leaf is the
   sequence of keys leading to that leaf.  When the second tree has a
   different value for a leaf at a path or adds a new leaf, the patch
   has a leaf, at that path, with the new value.  When a leaf in the
   first tree does not exist in the second tree, the JSON merge patch
   tree has a leaf with a JSON "null" value.  Hence, in the patch, null
   as the value of a name/value pair will delete the element with "name"
   in the original JSON value.  The patch does not have an entry for any
   leaf that has the same value in both versions.  See the MergePatch
   pseudocode at the beginning of Section 2 of [RFC7396] for the formal
   specification of how to apply a given patch.  As a result, if all
   leaf values are simple scalars, JSON merge patch is a quite efficient
   representation of incremental changes.  It is less efficient when
   leaf values are arrays, because JSON merge patch replaces arrays in
   their entirety, even if only one entry changes.

3.1.2.  JSON Merge Patch ALTO Messages

   To provide both examples of JSON merge patch and a demonstration of
   the feasibility of applying JSON merge patch to ALTO, the sections
   below show the application of JSON merge patch to two key ALTO
   messages.

3.1.2.1.  JSON Merge Patch Network Map Messages

   Section 11.2.1.6 of [RFC7285] defines the format of an ALTO network
   map message.  Assume a simple example ALTO message sending an initial
   network map:

     {
       "meta" : {
         "vtag": {
           "resource-id" : "my-network-map",
           "tag" : "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785"
         }
       },
       "network-map" : {
         "PID1" : {
           "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25" ]
         },
         "PID2" : {
           "ipv4" : [ "198.51.100.128/25" ]
         },
         "PID3" : {
           "ipv4" : [ "0.0.0.0/0" ],
           "ipv6" : [ "::/0" ]
         }
       }
     }

   Consider the following JSON merge patch update message, which (1)
   adds an ipv4 prefix "203.0.113.0/25" and an ipv6 prefix
   "2001:db8:8000::/33" to "PID1", (2) deletes "PID2", and (3) assigns a
   new "tag" to the network map:

     {
       "meta" : {
         "vtag" : {
           "tag" : "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
         }
       },
       "network-map": {
         "PID1" : {
           "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25",
                      "203.0.113.0/25" ],
           "ipv6" : [ "2001:db8:8000::/33" ]
         },
         "PID2" : null
       }
     }

   Applying the JSON merge patch update to the initial network map is
   equivalent to the following ALTO network map:

     {
       "meta" : {
         "vtag": {
           "resource-id" : "my-network-map",
           "tag" : "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
         }
       },
       "network-map" : {
         "PID1" : {
           "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25",
                      "203.0.113.0/25" ],
           "ipv6" : [ "2001:db8:8000::/33" ]
         },
         "PID3" : {
           "ipv4" : [ "0.0.0.0/0" ],
           "ipv6" : [ "::/0" ]
         }
       }
     }

3.1.2.2.  JSON Merge Patch Cost Map Messages

   Section 11.2.3.6 of [RFC7285] defines the format of an ALTO cost map
   message.  Assume a simple example ALTO message for an initial cost
   map:

     {
       "meta" : {
         "dependent-vtags" : [
           {"resource-id": "my-network-map",
            "tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
           }
         ],
         "cost-type" : {
           "cost-mode"  : "numerical",
           "cost-metric": "routingcost"
         },
         "vtag": {
           "resource-id" : "my-cost-map",
           "tag" : "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"
         }
       },
       "cost-map" : {
         "PID1": { "PID1": 1,  "PID2": 5,  "PID3": 10 },
         "PID2": { "PID1": 5,  "PID2": 1,  "PID3": 15 },
         "PID3": { "PID1": 20, "PID2": 15  }
       }
     }

   The following JSON merge patch message updates the example cost map
   so that (1) the "tag" field of the cost map is updated, (2) the cost
   of PID1->PID2 is 9 instead of 5, (3) the cost of PID3->PID1 is no
   longer available, and (4) the cost of PID3->PID3 is defined as 1.

     {
       "meta" : {
         "vtag": {
           "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"
         }
       }
       "cost-map" : {
         "PID1" : { "PID2" : 9 },
         "PID3" : { "PID1" : null, "PID3" : 1 }
       }
     }

   Hence, applying the JSON merge patch to the initial cost map is
   equivalent to the following ALTO cost map:

     {
       "meta" : {
         "dependent-vtags" : [
           {"resource-id": "my-network-map",
            "tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
           }
         ],
         "cost-type" : {
           "cost-mode"  : "numerical",
           "cost-metric": "routingcost"
         },
         "vtag": {
           "resource-id": "my-cost-map",
           "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"
         }
       },
       "cost-map" : {
         "PID1": { "PID1": 1,  "PID2": 9,  "PID3": 10 },
         "PID2": { "PID1": 5,  "PID2": 1,  "PID3": 15 },
         "PID3": {             "PID2": 15, "PID3": 1  }
       }
     }

3.2.  Incremental Encoding: JSON Patch

3.2.1.  JSON Patch Encoding

   One issue of JSON merge patch is that it does not handle array
   changes well.  In particular, JSON merge patch considers an array as
   a single object and hence can only replace an array in its entirety.
   When the change is to make a small change to an array, such as the
   deletion of an element from a large array, whole-array replacement is
   inefficient.  Consider the example in Section 3.1.2.1.  To add a new
   entry to the ipv4 array for PID1, the server needs to send a whole
   new array.  Another issue is that JSON merge patch cannot change a
   value to be null, as the JSON merge patch processing algorithm
   (MergePatch in Section 3.1.1) interprets a null as a removal
   instruction.  On the other hand, some ALTO resources can have null
   values, and it is possible that the update will want to change the
   new value to be null.

   JSON patch [RFC6902] can address the preceding issues.  It defines a
   set of operators to modify a JSON object.  See [RFC6902] for the
   normative definition.

3.2.2.  JSON Patch ALTO Messages

   To provide both examples of JSON patch and a demonstration of the
   difference between JSON patch and JSON merge patch, the sections
   below show the application of JSON patch to the same updates shown in
   Section 3.1.2.

3.2.2.1.  JSON Patch Network Map Messages

   First, consider the same update as in Section 3.1.2.1 for the network
   map.  Below is the encoding using JSON patch:

     [
       {
         "op": "replace",
         "path": "/meta/vtag/tag",
         "value": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
       },
       {
         "op": "add",
         "path": "/network-map/PID1/ipv4/2",
         "value": "203.0.113.0/25"
       }
       {
         "op": "add",
         "path": "/network-map/PID1/ipv6",
         "value": ["2001:db8:8000::/33"]
       },
       {
         "op": "remove",
         "path": "/network-map/PID2"
       }
     ]

3.2.2.2.  JSON Patch Cost Map Messages

   Compared with JSON merge patch, JSON patch does not encode cost map
   updates efficiently.  Consider the cost map update shown in
   Section 3.1.2.2, the encoding using JSON patch is:

     [
       {
         "op": "replace",
         "path": "/meta/vtag/tag",
         "value": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"
       },
       {
         "op": "replace",
         "path": "/cost-map/PID1/PID2",
         "value": 9
       },
       {
         "op": "remove",
         "path": "/cost-map/PID3/PID1"
       },
       {
         "op": "replace",
         "path": "/cost-map/PID3/PID3",
         "value": 1
       }
     ]

3.3.  Multiplexing and Server Push: HTTP/2

   HTTP/2 [RFC7540] provides two related features: multiplexing and
   server push.  In particular, HTTP/2 allows a client and a server to
   multiplex multiple HTTP requests and responses over a single TCP
   connection.  The requests and responses can be interleaved on a block
   (frame) by block (frame) basis, by indicating the requests and
   responses in HTTP/2 messages, avoiding the head-of-line blocking
   problem encountered with HTTP/1.1.  To achieve the same goal, this
   design introduces substream-id to allow a client to receive updates
   to multiple resources.  HTTP/2 also provides a server-push facility
   to allow a server to send asynchronous updates.

   Despite the two features of HTTP/2, this design chooses a design
   compatible with HTTP/1.x for the simplicity of HTTP/1.x.  A design
   based on HTTP/2 may more likely need to be implemented using a more
   complex HTTP/2 client library.  In such a case, one approach for
   using server push for updates is for the update stream server to send
   each data update message as a separate server-push item and let the
   client apply those updates as they arrive.  An HTTP/2 client library
   may not necessarily inform a client application when the server
   pushes a resource.  Instead, the library might cache the pushed
   resource and only deliver it to the client when the client explicitly
   requests that URI.  Further, it is more likely that a design based on
   HTTP/2 may encounter issues with a proxy between the client and the
   server, in that server push is optional and can be disabled by any
   proxy between the client and the server.  This is not a problem for
   the intended use of server push; eventually, the client will request
   those resources, so disabling server push just adds a delay.  But
   this means that Server Push is not suitable for resources that the
   client does not know to request.

   Thus, this design leaves a design based on HTTP/2 as a future work
   and focuses on ALTO updates on HTTP/1.x and [SSE].

3.4.  Server Push: Server-Sent Event

   Server-Sent Events (SSE) are techniques that can work with HTTP/1.1.
   The following is a non-normative summary of SSE; see [SSE] for its
   normative definition.

   SSE enable a server to send new data to a client by "server push".
   The client establishes an HTTP [RFC7230] [RFC7231] connection to the
   server and keeps the connection open.  The server continually sends
   messages.  Each message has one or more lines, where a line is
   terminated by a carriage return immediately followed by a new line, a
   carriage return not immediately followed by a new line, or a new line
   not immediately preceded by a carriage return.  A message is
   terminated by a blank line (two line terminators in a row).

   Each line in a message is of the form "field-name: string value".
   Lines with a blank field name (that is, lines that start with a
   colon) are ignored, as are lines that do not have a colon.  The
   protocol defines three field names: event, id, and data.  If a
   message has more than one "data" line, the value of the data field is
   the concatenation of the values on those lines.  There can be only
   one "event" and "id" line per message.  The "data" field is required;
   the others are optional.

   Figure 1 is a sample SSE stream, starting with the client request.
   The server sends three events and then closes the stream.

     (Client request)
     GET /stream HTTP/1.1
     Host: example.com
     Accept: text/event-stream

     (Server response)
     HTTP/1.1 200 OK
     Connection: keep-alive
     Content-Type: text/event-stream

     event: start
     id: 1
     data: hello there

     event: middle
     id: 2
     data: let's chat some more ...
     data: and more and more and ...

     event: end
     id: 3
     data: goodbye

                       Figure 1: A Sample SSE Stream

4.  Overview of Approach and High-Level Protocol Message Flow

   With the preceding background, this section now gives a non-normative
   overview of the update mechanisms and message flow to be defined in
   later sections of this document.  Figure 2 gives the main components
   and overall message flow.

    -------------------------------------------------------------------
   |                                                                   |
   |          +-------+         +-------+ 1. init request   +------+   |
   |          |       |         |       | <--------------   |      |   |
   |          |       |         |       | -------------->   |      |   |
   | 3.add/   |       |         |       | 1'. control URI   |      |   |
   | remove   |       |         |       |                   |      |   |
   | resource |Stream |         |Update |                   |      |   |
     -------->|Control| private |Stream | 2a. data update   |Client| --
              |Server |<------->|Server | messages          |      |
     -------- |       |         |       | --------------->  |      | <-
   | response |       |         |       | --------------->  |      |   |
   |          |       |         |       | 2b. control update|      |   |
   |          +-------+         +-------+ messages          +------+   |
   |                                                                   |
    -------------------------------------------------------------------

              Figure 2: ALTO SSE Architecture and Message Flow

4.1.  Update Stream Service Message Flow

   The building block of the update mechanism defined in this document
   is the update stream service (defined in Section 6), where each
   update stream service is a POST-mode service that provides update
   streams.

   Note that the lines of the format "** ... **" are used to describe
   message flows in this section and the following sections.

   ** Initial request: client -> update server **:
      When an ALTO client requests an update stream service, the ALTO
      client establishes a persistent connection to the update stream
      server and submits an initial update-stream request (defined in
      Section 6.5), creating an update stream.  This initial request
      creating the update stream is labeled "1. init request" in
      Figure 2.

      An update stream can provide updates to both GET-mode resources,
      such as ALTO network and cost maps, and POST-mode resources, such
      as ALTO endpoint property service.  Also, to avoid creating too
      many update streams, this design allows an ALTO client to use one
      update stream to receive updates to multiple requests.  In
      particular, the client may request to receive updates for the same
      resource but with different parameters for a POST-mode resource,
      in addition to being able to consolidate updates for multiple
      resources into a single stream.  The updates for each request is
      called a substream and hence the update server needs an identifier
      to indicate the substream when sending an update.  To achieve this
      goal, the client assigns a unique substream-id when requesting
      updates to a resource in an update stream, and the server puts the
      substream-id in each update.

   ** Data updates: update server -> client **:
      The objective of an update stream is to continuously push (to an
      ALTO client) the data value changes for a set of resources, where
      the set of resources is specified by the ALTO client's requests.
      This document refers to messages sending such data-value changes
      as data update messages (defined in Section 5.2).  Although an
      update stream may update one or more requests, each data update
      message updates only one request and is sent as a Server-Sent
      Event (SSE), as defined by [SSE].  A data update message is
      encoded either as a full replacement or as an incremental change.
      A full replacement uses the JSON message format defined by the
      ALTO protocol.  There can be multiple encodings for incremental
      changes.  The current design supports incremental changes using
      JSON merge patch [RFC7396] or JSON patch [RFC6902] to describe the
      changes of the resource.  Future documents may define additional
      mechanisms for incremental changes.  The update stream server
      decides when to send data update messages and whether to send full
      replacements or incremental changes.  These decisions can vary
      from resource to resource and from update to update.  Since the
      transport is a design compatible with HTTP/1.x, data update
      messages are delivered reliably and in order, and the lossless,
      sequential delivery of its messages allows the server to know the
      exact state of the client to compute the correct incremental
      updates.  Figure 2 shows examples of data update messages (labeled
      "2a. data update messages") in the overall message flow.

   ** Control updates: update server -> client **:
      An update stream can run for a long time and hence there can be
      status changes at the update stream server side during the
      lifetime of an update stream; for example, the update stream
      server may encounter an error or need to shut down for
      maintenance.  To support a robust, flexible protocol design, this
      document allows the update stream server to send control update
      messages (defined in Section 5.3) in addition to data update
      messages to the ALTO client.  Figure 2 shows that both data
      updates and control updates can be sent by the server to the
      client (labeled "2b. control update messages").

4.2.  Stream Control Service Message Flow

   ** Stream control: client -> stream control server **:
      In addition to control changes triggered from the update stream
      server side, in a flexible design, an ALTO client may initiate
      control changes as well, in particular, by adding or removing ALTO
      resources receiving updates.  An ALTO client initiates such
      changes using the stream control service (defined in Section 7).
      Although one may use a design that the client uses as the same
      HTTP connection to send the control requests, it requires stronger
      server support, such as HTTP pipeline.  For more flexibility, this
      document introduces stream control service.  In particular, the
      update stream server of an update stream uses the first message to
      provide the URI of the stream control service (labeled "1':
      control URI" in Figure 2).

      The ALTO client can then use the URI to ask the stream control
      server specified in the URI to request the update stream server to
      (1) send data update messages for additional resources, (2) stop
      sending data update messages for previously requested resources,
      or (3) gracefully stop and close the update stream altogether.

4.3.  Service Announcement and Management Message Flow

   ** Service announcements: IRD server -> client **:
      An update server may provide any number of update stream services,
      where each update stream may provide updates for a given subset of
      the ALTO server's resources.  An ALTO server's Information
      Resource Directory (IRD) defines the update stream services and
      declares the set of resources for which each update stream service
      provides updates.  The ALTO server selects the resource set for
      each update stream service.  It is recommended that if a resource
      depends on one or more other resource(s) (indicated with the
      "uses" attribute defined in [RFC7285]), these other resource(s)
      should also be part of that update stream.  Thus, the update
      stream for a cost map should also provide updates for the network
      map on which that cost map depends.

   ** Service management (server) **:
      An ALTO client may request any number of update streams
      simultaneously.  Because each update stream consumes resources on
      the update stream server, an update stream server may require
      client authorization and/or authentication, limit the number of
      open update streams, close inactive streams, or redirect an ALTO
      client to another update stream server.

5.  Update Messages: Data Update and Control Update Messages

   This section defines the format of update messages sent from the
   server to the client.  It first defines the generic structure of
   update messages (Section 5.1).  It then defines the details of the
   data update messages (Section 5.2) and the control update messages
   (Section 5.3).  These messages will be used in the next two sections
   to define the update stream service (Section 6) and the stream
   control service (Section 7).

5.1.  Generic ALTO Update Message Structure

   Both data update and control update messages from the server to the
   client have the same basic structure.  Each message includes a data
   field to provide data information, which is typically a JSON object,
   and an event field preceding the data field, to specify the media
   type indicating the encoding of the data field.

   A data update message needs additional information to identify the
   ALTO data (object) to which the update message applies.  To be
   generic, this document uses a data-id to identify the ALTO data
   (object) to be updated; see below.

   Hence, the event field of ALTO update message can include two
   subfields (media-type and data-id), where the two subfields are
   separated by a comma (',', U+002C):

         media-type [ ',' data-id ]

   According to Section 4.2 of [RFC6838], the comma character is not
   allowed in a media-type name so there is no ambiguity when decoding
   of the two subfields.

   Note that an update message does not use the SSE "id" field.

5.2.  ALTO Data Update Message

   A data update message is sent when a monitored resource changes.  As
   discussed in the preceding section, the event field of a data update
   message includes two subfields: 'media-type' and 'data-id'.

   The 'media-type' subfield depends on whether the data update is a
   complete specification of the identified data or an incremental patch
   (e.g., a JSON merge patch or JSON patch), if possible, describing the
   changes from the last version of the data.  This document refers to
   these as full replacement and incremental change, respectively.  The
   encoding of a full replacement is defined by its defining document
   (e.g., network and cost map messages by [RFC7285]) and uses the media
   type defined in that document.  The encoding of JSON merge patch is
   defined by [RFC7396], with the media type "application/merge-
   patch+json"; the encoding of JSON patch is defined by [RFC6902], with
   media type "application/json-patch+json".

   The 'data-id' subfield identifies the ALTO data to which the data
   update message applies.

   First, consider the case that the resource contains only a single
   JSON object.  For example, since an ALTO client can request data
   updates for both a cost map resource (object) and its dependent
   network map resource (object) in the same update stream, to
   distinguish the updates, the client assigns a substream-id for each
   resource receiving data updates.  Substream-ids MUST be unique within
   an update stream but need not be globally unique.  A substream-id is
   encoded as a JSON string with the same format as that of the type
   ResourceID (Section 10.2 of [RFC7285]).  The type SubstreamID is used
   in this document to indicate a string of this format.  The substream-
   id of a single JSON object is the 'data-id'.

   As an example, assume that the ALTO client assigns substream-id "1"
   in its request to receive updates to the network map and substream-id
   "2" to the cost map.  Then, the substream-ids are the data-ids
   indicating which objects will be updated.  Figure 3 shows some
   examples of ALTO data update messages:

     event: application/alto-networkmap+json,1
     data: { ... full network map message ... }

     event: application/alto-costmap+json,2
     data: { ... full cost map message ... }

     event: application/merge-patch+json,2
     data: { ... JSON merge patch update for the cost map ... }

              Figure 3: Examples of ALTO Data Update Messages

   Next, consider the case that a resource may include multiple JSON
   objects.  This document considers the case that a resource may
   contain multiple components (parts), and they are encoded using the
   media type "multipart/related" [RFC2387].  Each part of this
   multipart response MUST be an HTTP message including a Content-ID
   header and a JSON object body.  Each component requiring the update
   stream service (defined in Section 6) MUST be identified by a unique
   Content-ID to be defined in its defining document.

   For a resource using the media type "multipart/related", the 'data-
   id' subfield MUST be the concatenation of the substream-id, the '.'
   separator (U+002E), and the unique Content-ID, in order.

5.3.  ALTO Control Update Message

   Control update messages have the media type "application/alto-
   updatestreamcontrol+json", and the data is of type
   UpdateStreamControlEvent:

     object {
        [String          control-uri;]
        [SubstreamID     started<1..*>;]
        [SubstreamID     stopped<1..*>;]
        [String          description;]
     } UpdateStreamControlEvent;

   control-uri:
      the URI providing stream control for this update stream (see
      Section 7).  The server sends a control update message notifying
      the client of the control-uri.  This control update message
      notifying the control-uri will be sent once and MUST be the first
      event in an update stream.  If the URI value is NULL, the update
      stream server does not support stream control for this update
      stream; otherwise, the update stream server provides stream
      control through the given URI.

   started:
      a list of substream-ids of resources.  It notifies the ALTO client
      that the update stream server will start sending data update
      messages for each resource listed.

   stopped:
      a list of substream-ids of resources.  It notifies the ALTO client
      that the update stream server will no longer send data update
      messages for the listed resources.  There can be multiple reasons
      for an update stream server to stop sending data update messages
      for a resource, including a request from the ALTO client using
      stream control (Section 6.7.1) or an internal server event.

   description:
      a non-normative, human-readable text providing an explanation for
      the control event.  When an update stream server stops sending
      data update messages for a resource, it is RECOMMENDED that the
      update stream server use the description field to provide details.
      There can be multiple reasons that trigger a "stopped" event; see
      above.  The intention of this field is to provide a human-readable
      text for the developer and/or the administrator to diagnose
      potential problems.

6.  Update Stream Service

   An update stream service returns a stream of update messages, as
   defined in Section 5.  An ALTO server's IRD (Information Resource
   Directory) MAY define one or more update stream services, which ALTO
   clients use to request new update stream instances.  An IRD entry
   defining an update stream service MUST define the media type, HTTP
   method, and capabilities and uses as follows.

6.1.  Media Type

   The media type of an ALTO update stream service is "text/event-
   stream", as defined by [SSE].

6.2.  HTTP Method

   An ALTO update stream service is requested using the HTTP POST
   method.

6.3.  Capabilities

   The capabilities are defined as an object of type
   UpdateStreamCapabilities:

     object {
       IncrementalUpdateMediaTypes incremental-change-media-types;
       Boolean                     support-stream-control;
     } UpdateStreamCapabilities;

     object-map {
        ResourceID -> String;
     } IncrementalUpdateMediaTypes;

   If this update stream can provide data update messages with
   incremental changes for a resource, the "incremental-change-media-
   types" field has an entry for that resource-id, and the value is the
   supported media types of the incremental change separated by commas.
   Normally, this will be "application/merge-patch+json", "application/
   json-patch+json", or "application/merge-patch+json,application/json-
   patch+json", because, as described in Section 5, they are the only
   incremental change types defined by this document.  However, future
   extensions may define other types of incremental changes.

   When choosing the media types to encode incremental changes for a
   resource, the update stream server MUST consider the limitations of
   the encoding.  For example, when a JSON merge patch specifies that
   the value of a field is null, its semantics are that the field is
   removed from the target and hence the field is no longer defined
   (i.e., undefined); see the MergePatch algorithm in Section 3.1.1 on
   how null value is processed.  This, however, may not be the intended
   result for the resource, when null and undefined have different
   semantics for the resource.  In such a case, the update stream server
   MUST choose JSON patch over JSON merge patch if JSON patch is
   indicated as a capability of the update stream server.  If the server
   does not support JSON patch to handle such a case, the server then
   need to send a full replacement.

   The "support-stream-control" field specifies whether the given update
   stream supports stream control.  If the "support-stream-control"
   field is "true", the update stream server will use the stream control
   specified in this document; otherwise, the update stream server may
   use other mechanisms to provide the same functionality as stream
   control.

6.4.  Uses

   The "uses" attribute MUST be an array with the resource-ids of every
   resource for which this update stream can provide updates.  Each
   resource specified in the "uses" MUST support full replacement; the
   update stream server can always send full replacement, and the ALTO
   client MUST accept full replacement.

   This set may be any subset of the ALTO server's resources and may
   include resources defined in linked IRDs.  However, it is RECOMMENDED
   that the ALTO server selects a set that is closed under the resource
   dependency relationship.  That is, if an update stream's "uses" set
   includes resource R1 and resource R1 depends on ("uses") resource R0,
   then the update stream's "uses" set SHOULD include R0 as well as R1.
   For example, an update stream for a cost map SHOULD also provide
   updates for the network map upon which that cost map depends.

6.5.  Request: Accept Input Parameters

   An ALTO client specifies the parameters for the new update stream by
   sending an HTTP POST body with the media type "application/alto-
   updatestreamparams+json".  That body contains a JSON object of type
   UpdateStreamReq, where:

     object {
        [AddUpdatesReq   add;]
        [SubstreamID     remove<0..*>;]
     } UpdateStreamReq;

     object-map {
        SubstreamID -> AddUpdateReq;
     } AddUpdatesReq;

     object {
        ResourceID   resource-id;
        [JSONString  tag;]
        [Boolean     incremental-changes;]
        [Object      input;]
     } AddUpdateReq;

   add:
      Specifies the resources (and the parameters for the resources) for
      which the ALTO client wants updates.  In the scope of the same
      update stream, the ALTO client MUST assign a substream-id that is
      unique in the scope of the update stream (Section 5.2) for each
      entry and use those substream-ids as the keys in the "add" field.

   resource-id:
      The resource-id of an ALTO resource and MUST be in the update
      stream's "uses" list (Section 6.4).  If the resource-id is a GET-
      mode resource with a version tag (or "vtag"), as defined in
      Sections 6.3 and 10.3 of [RFC7285], and the ALTO client has
      previously retrieved a version of that resource from the update
      stream server, the ALTO client MAY set the "tag" field to the tag
      part of the client's version of that resource.  If that version is
      not current, the update stream server MUST send a full replacement
      before sending any incremental changes, as described in
      Section 6.7.1.  If that version is still current, the update
      stream server MAY omit the initial full replacement.

   incremental-changes:
      The ALTO client specifies whether it is willing to receive
      incremental changes from the update stream server for this
      substream.  If the "incremental-changes" field is "true", the
      update stream server MAY send incremental changes for this
      substream.  In this case, the client MUST support all incremental
      methods from the set announced in the server's capabilities for
      this resource; see Section 6.3 for the server's announcement of
      potential incremental methods.  If a client does not support all
      incremental methods from the set announced in the server's
      capabilities, the client can set "incremental-changes" to "false",
      and the update stream server then MUST NOT send incremental
      changes for that substream.  The default value for "incremental-
      changes" is "true", so to suppress incremental changes, the ALTO
      client MUST explicitly set "incremental-changes" to "false".  An
      alternative design of incremental-changes control is a more fine-
      grained control, by allowing a client to select a subset of
      incremental methods from the set announced in the server's
      capabilities.  But this alternative design is not adopted in this
      document, because it adds complexity to the server, which is more
      likely to be the bottleneck.  Note that the ALTO client cannot
      suppress full replacement.  When the ALTO client sets
      "incremental-changes" to "false", the update stream server MUST
      send a full replacement instead of an incremental change to the
      ALTO client.  The update stream server MAY wait until more changes
      are available and send a single full replacement with those
      changes.  Thus, an ALTO client that declines to accept incremental
      changes may not get updates as quickly as an ALTO client that
      does.

   input:
      If the resource is a POST-mode service that requires input, the
      ALTO client MUST set the "input" field to a JSON object with the
      parameters that the resource expects.

   remove:
      It is used in update stream control requests (Section 7) and is
      not allowed in the update stream request.  The update stream
      server SHOULD ignore this field if it is included in the request.

   If a request has any errors, the update stream server MUST NOT create
   an update stream.  Also, the update stream server will send an error
   response to the ALTO client, as specified in Section 6.6.

6.6.  Response

   If the update stream request has any errors, the update stream server
   MUST return an HTTP "400 Bad Request" to the ALTO client; the body of
   the response follows the generic ALTO error response format specified
   in Section 8.5.2 of [RFC7285].  Hence, an example ALTO error response
   has the format:

          HTTP/1.1 400 Bad Request
          Content-Length: 131
          Content-Type: application/alto-error+json
          Connection: Closed

          {
              "meta":{
                  "code":  "E_INVALID_FIELD_VALUE",
                  "field": "add/my-network-map/resource-id",
                  "value": "my-networkmap/#"
              }
          }

   Note that "field" and "value" are optional fields.  If the "value"
   field exists, the "field" field MUST exist.

   *  If an update stream request does not have an "add" field
      specifying one or more resources, the error code of the error
      message MUST be E_MISSING_FIELD and the "field" field SHOULD be
      "add".  The update stream server MUST close the stream without
      sending any events.

   *  If the "resource-id" field is invalid or is not associated with
      the update stream, the error code of the error message MUST be
      E_INVALID_FIELD_VALUE.  The "field" field SHOULD be the full path
      of the "resource-id" field, and the "value" field SHOULD be the
      invalid resource-id.  If there are more than one invalid resource-
      ids, the update stream server SHOULD pick one and return it.  The
      update stream server MUST close the stream (i.e., TCP connection)
      without sending any events.

   *  If the resource is a POST-mode service that requires input, the
      client MUST set the "input" field to a JSON object with the
      parameters that that resource expects.  If the "input" field is
      missing or invalid, the update stream server MUST return the same
      error response that that resource would return for missing or
      invalid input (see [RFC7285]).  In this case, the update stream
      server MUST close the update stream without sending any events.
      If the input for several POST-mode resources is missing or
      invalid, the update stream server MUST pick one and return it.

   The response to a valid request is a stream of update messages.
   Section 5 defines the update messages, and [SSE] defines how they are
   encoded into a stream.

   An update stream server SHOULD send updates only when the underlying
   values change.  However, it may be difficult for an update stream
   server to guarantee that in all circumstances.  Therefore, a client
   MUST NOT assume that an update message represents an actual change.

6.7.  Additional Requirements on Update Stream Service

6.7.1.  Event Sequence Requirements

   *  The first event MUST be a control update message with the URI of
      the update stream control service (see Section 7) for this update
      stream.  Note that the value of the control-uri can be "null",
      indicating that there is no control stream service.

   *  As soon as possible, after the ALTO client initiates the
      connection, the update stream server checks the "tag" field for
      each added update request.  If the "tag" field is not specified in
      an added update request, the update stream server MUST first send
      a full replacement for the request.  If the "tag" field is
      specified, the client can accept incremental changes, and the
      server can compute an incremental update based on the "tag" (the
      server needs to ensure that for a POST resource with input, the
      "tag" should indicate the correct result for different inputs);
      the update stream server MAY omit the initial full replacement.

   *  If this update stream provides updates for resource-ids R0 and R1
      and if R1 depends on R0, then the update stream server MUST send
      the update for R0 before sending the related updates for R1.  For
      example, suppose an update stream provides updates to a network
      map and its dependent cost maps.  When the network map changes,
      the update stream server MUST send the network map update before
      sending the cost map updates.

   *  When the ALTO client uses the stream control service to stop
      updates for one or more resources (Section 7), the ALTO client
      MUST send a stream control request.  The update stream server MUST
      send a control update message whose "stopped" field has the
      substream-ids of all stopped resources.

6.7.2.  Cross-Stream Consistency Requirements

   If multiple ALTO clients create multiple update streams from the same
   update stream resource and with the same update request parameters
   (i.e., same resource and same input), the update stream server MUST
   send the same updates to all of them.  However, the update stream
   server MAY pack data items into different patch events, as long as
   the net result of applying those updates is the same.

   For example, suppose two different ALTO clients create two different
   update streams for the same cost map, and suppose the update stream
   server processes three separate cost point updates with a brief pause
   between each update.  The server MUST send all three new cost points
   to both clients.  But the update stream server MAY send a single
   patch event (with all three cost points) to one ALTO client while
   sending three separate patch events (with one cost point per event)
   to the other ALTO client.

   An update stream server MAY offer several different update stream
   resources that provide updates to the same underlying resource (that
   is, a resource-id may appear in the "uses" field of more than one
   update stream resource).  In this case, those update stream resources
   MUST return the same update.

6.7.3.  Multipart Update Requirements

   This design allows any valid media type for full replacement.  Hence,
   it supports ALTO resources using multipart to contain multiple JSON
   objects.  This realizes the push benefit but not the incremental
   encoding benefit of SSE.

   JSON patch and merge patch provide the incremental encoding benefit
   but can be applied to only a single JSON object.  If an update stream
   service supports a resource providing a multipart media type, which
   we refer to as a multipart resource, then the update stream service
   needs to handle the issue that the message of a full multipart
   resource can include multiple JSON objects.  To address the issue,
   when an update stream service specifies that it supports JSON patch
   or merge patch incremental updates for a multipart resource, the
   service MUST ensure that (1) each part of a multipart message is a
   single JSON object, (2) each part is specified by a static Content-ID
   in the initial full message, (3) each data update event applies to
   only one part, and (4) each data update specifies substream-
   id.content-id as the "event" field of the event, to identify the part
   to be updated.

6.8.  Keep-Alive Messages

   In an SSE stream, any line that starts with a colon (U+003A)
   character is a comment, and an ALTO client MUST ignore that line
   [SSE].  As recommended in [SSE], an update stream server SHOULD send
   a comment line (or an event) every 15 seconds to prevent ALTO clients
   and proxy servers from dropping the HTTP connection.  Note that
   although TCP also provides a Keep-Alive function, the interval
   between TCP Keep-Alive messages can depend on the OS configuration
   and varies.  The preceding recommended SSE Keep-Alive allows the SSE
   client to detect the status of the update stream server with more
   certainty.

7.  Stream Control Service

   A stream control service allows an ALTO client to remove resources
   from the set of resources that are monitored by an update stream or
   add additional resources to that set.  The service also allows an
   ALTO client to gracefully shut down an update stream.

   When an update stream server creates a new update stream and if the
   update stream server supports stream control for the update stream,
   the update stream server creates a stream control service for that
   update stream.  An ALTO client uses the stream control service to
   remove resources from the update stream instance or to request
   updates for additional resources.  An ALTO client cannot obtain the
   stream control service through the IRD.  Instead, the first event
   that the update stream server sends to the ALTO client has the URI
   for the associated stream control service (see Section 5.3).

   Each stream control request is an individual HTTP request.  The ALTO
   client MAY send multiple stream control requests to the stream
   control server using the same HTTP connection.

7.1.  URI

   The URI for a stream control service, by itself, MUST uniquely
   specify the update stream instance that it controls.  The stream
   control server MUST NOT use other properties of an HTTP request, such
   as cookies or the client's IP address, to determine the update
   stream.  Furthermore, an update stream server MUST NOT reuse a
   control service URI once the associated update stream has been
   closed.

   The ALTO client MUST evaluate a relative control URI reference
   [RFC3986] (for example, a URI reference without a host or with a
   relative path) in the context of the URI used to create the update
   stream.  The stream control service's host MAY be different from the
   update stream's host.

   It is expected that there is an internal mechanism to map a stream
   control URI to the unique update stream instance to be controlled.
   For example, the update stream service may assign a unique, internal
   stream id to each update stream instance.  However, the exact
   mechanism is left to the update stream service provider.

   To prevent an attacker from forging a stream control URI and sending
   bogus requests to disrupt other update streams, the service should
   consider two security issues.  First, if http, not https, is used,
   the stream control URI can be exposed to an on-path attacker.  To
   address this issue, in a setting where the path from the server to
   the client can traverse such an attacker, the server SHOULD use
   https.  Second, even without direct exposure, an off-path attacker
   may guess valid stream control URIs.  To address this issue, the
   server SHOULD choose stream control URIs with enough randomness to
   make guessing difficult; the server SHOULD introduce mechanisms that
   detect repeated guesses indicating an attack (e.g., keeping track of
   the number of failed stream control attempts).  Please see the W3C's
   "Good Practices for Capability URLs" <https://www.w3.org/TR/
   capability-urls/>.

7.2.  Media Type

   An ALTO stream control response does not have a specific media type.

7.3.  HTTP Method

   An ALTO update stream control resource is requested using the HTTP
   POST method.

7.4.  IRD Capabilities & Uses

   None (Stream control services do not appear in the IRD).

7.5.  Request: Accept Input Parameters

   A stream control service accepts the same input media type and input
   parameters as the update stream service (Section 6.5).  The only
   difference is that a stream control service also accepts the "remove"
   field.

   If specified, the "remove" field is an array of substream-ids the
   ALTO client previously added to this update stream.  An empty
   "remove" array is equivalent to a list of all currently active
   resources; the update stream server responds by removing all
   resources and closing the stream.

   An ALTO client MAY use the "add" field to add additional resources.
   The ALTO client MUST assign a unique substream-id to each additional
   resource.  Substream-ids MUST be unique over the lifetime of this
   update stream; an ALTO client MUST NOT reuse a previously removed
   substream-id.  The processing of an "add" resource is the same as
   discussed in Sections 6.5 and 6.6.

   If a request has any errors, the update stream server MUST NOT add or
   remove any resources from the associated update stream.  Also, the
   stream control server will return an error response to the client, as
   specified in Section 7.6.

7.6.  Response

   The stream control server MUST process the "add" field before the
   "remove" field.  If the request removes all active resources without
   adding any additional resources, the update stream server MUST close
   the update stream.  Thus, an update stream cannot have zero
   resources.

   If the request has any errors, the stream control server MUST return
   an HTTP "400 Bad Request" to the ALTO client.  The body part of the
   response follows the generic ALTO error response format specified in
   Section 8.5.2 of [RFC7285].  An error response has the same format as
   specified in Section 6.6.  Detailed error code and error information
   are specified as below.

   *  If the "add" request does not satisfy the requirements in
      Section 6.5, the stream control server MUST return the ALTO error
      message defined in Section 6.6.

   *  If any substream-id in the "remove" field was not added in a prior
      request, the error code of the error message MUST be
      E_INVALID_FIELD_VALUE, the "field" field SHOULD be "remove", and
      the "value" field SHOULD be an array of the invalid substream-ids.
      Thus, it is illegal to "add" and "remove" the same substream-id in
      the same request.  However, it is legal to remove a substream-id
      twice.  To support the preceding checking, the update stream
      server MUST keep track of previously used but now closed
      substream-ids.

   *  If any substream-id in the "add" field has been used before in
      this stream, the error code of the error message MUST be
      E_INVALID_FIELD_VALUE, the "field" field SHOULD be "add", and the
      "value" field SHOULD be an array of invalid substream-ids.

   *  If the request has a non-empty "add" field and a "remove" field
      with an empty list of substream-ids (to replace all active
      resources with a new set, the client MUST explicitly enumerate the
      substream-ids to be removed), the error code of the error message
      MUST be E_INVALID_FIELD_VALUE, the "field" field SHOULD be
      "remove", and the "value" field SHOULD be an empty array.

   If the request is valid but the associated update stream has been
   closed, then the stream control server MUST return an HTTP "404 Not
   Found".

   If the request is valid and the stream control server successfully
   processes the request without error, the stream control server should
   return either an HTTP "202 Accepted" response or an HTTP "204 No
   Content" response.  The difference is that for the latter case, the
   stream control server is sure that the update stream server has also
   processed the request.  Regardless of a 202 or 204 HTTP response, the
   final updates of related resources will be notified by the update
   stream server using its control update message(s), due to the modular
   design.

8.  Examples

8.1.  Example: IRD Announcing Update Stream Services

   Below is an example IRD announcing three update stream services.  The
   first, which is named "update-my-costs", provides updates for the
   network map, the "routingcost" and "hopcount" cost maps, and a
   Filtered Cost Map resource.  The second, which is named "update-my-
   prop", provides updates to the endpoint properties service.  The
   third, which is named "update-my-pv", provides updates to a
   nonstandard ALTO service returning a multipart response.

   Note that in the "update-my-costs" update stream shown in the example
   IRD, the update stream server uses JSON patch for network map, and it
   uses JSON merge patch to update the other resources.  Also, the
   update stream will only provide full replacements for "my-simple-
   filtered-cost-map".

   Also, note that this IRD defines two Filtered Cost Map resources.
   They use the same cost types, but "my-filtered-cost-map" accepts cost
   constraint tests, while "my-simple-filtered-cost-map" does not.  To
   avoid the issues discussed in Section 9.3, the update stream provides
   updates for the second but not the first.

   This IRD also announces a nonstandard ALTO service, which is named
   "my-pv".  This service accepts an extended endpoint cost request as
   an input and returns a multipart response, including an endpoint cost
   resource and a property map resource.  This document does not rely on
   any other design details of this new service.  In this document, the
   "my-pv" service is only used to illustrate how the update stream
   service provides updates to an ALTO resource returning a multipart
   response.

     "my-network-map": {
       "uri": "https://alto.example.com/networkmap",
       "media-type": "application/alto-networkmap+json",
     },
     "my-routingcost-map": {
       "uri": "https://alto.example.com/costmap/routingcost",
       "media-type": "application/alto-costmap+json",
       "uses": ["my-networkmap"],
       "capabilities": {
         "cost-type-names": ["num-routingcost"]
       }
     },
     "my-hopcount-map": {
       "uri": "https://alto.example.com/costmap/hopcount",
       "media-type": "application/alto-costmap+json",
       "uses": ["my-networkmap"],
       "capabilities": {
         "cost-type-names": ["num-hopcount"]
       }
     },
     "my-filtered-cost-map": {
       "uri": "https://alto.example.com/costmap/filtered/constraints",
       "media-type": "application/alto-costmap+json",
       "accepts": "application/alto-costmapfilter+json",
       "uses": ["my-networkmap"],
       "capabilities": {
         "cost-type-names": ["num-routingcost", "num-hopcount"],
         "cost-constraints": true
       }
     },
     "my-simple-filtered-cost-map": {
       "uri": "https://alto.example.com/costmap/filtered/simple",
       "media-type": "application/alto-costmap+json",
       "accepts": "application/alto-costmapfilter+json",
       "uses": ["my-networkmap"],
       "capabilities": {
         "cost-type-names": ["num-routingcost", "num-hopcount"],
         "cost-constraints": false
       }
     },
     "my-props": {
       "uri": "https://alto.example.com/properties",
       "media-type": "application/alto-endpointprops+json",
       "accepts": "application/alto-endpointpropparams+json",
       "capabilities": {
         "prop-types": ["priv:ietf-bandwidth"]
       }
     },
     "my-pv": {
       "uri": "https://alto.example.com/endpointcost/pv",
       "media-type": "multipart/related;
                      type=application/alto-endpointcost+json",
       "accepts": "application/alto-endpointcostparams+json",
       "capabilities": {
         "cost-type-names": [ "path-vector" ],
         "ane-properties": [ "maxresbw", "persistent-entities" ]
       }
     },
     "update-my-costs": {
       "uri": "https://alto.example.com/updates/costs",
       "media-type": "text/event-stream",
       "accepts": "application/alto-updatestreamparams+json",
       "uses": [
          "my-network-map",
          "my-routingcost-map",
          "my-hopcount-map",
          "my-simple-filtered-cost-map"
       ],
       "capabilities": {
         "incremental-change-media-types": {
           "my-network-map": "application/json-patch+json",
           "my-routingcost-map": "application/merge-patch+json",
           "my-hopcount-map": "application/merge-patch+json"
         },
         "support-stream-control": true
       }
     },
     "update-my-props": {
       "uri": "https://alto.example.com/updates/properties",
       "media-type": "text/event-stream",
       "uses": [ "my-props" ],
       "accepts": "application/alto-updatestreamparams+json",
       "capabilities": {
         "incremental-change-media-types": {
           "my-props": "application/merge-patch+json"
         },
         "support-stream-control": true
       }
     },
     "update-my-pv": {
       "uri": "https://alto.example.com/updates/pv",
       "media-type": "text/event-stream",
       "uses": [ "my-pv" ],
       "accepts": "application/alto-updatestreamparams+json",
       "capabilities": {
         "incremental-change-media-types": {
           "my-pv": "application/merge-patch+json"
         },
         "support-stream-control": true
       }
     }

8.2.  Example: Simple Network and Cost Map Updates

   Given the update streams announced in the preceding example IRD, the
   section below shows an example of an ALTO client's request and the
   update stream server's immediate response, using the update stream
   resource "update-my-costs".  In the example, the ALTO client requests
   updates for the network map and "routingcost" cost map but not for
   the "hopcount" cost map.  The ALTO client uses the ALTO server's
   resource-ids as the substream-ids.  Because the client does not
   provide a "tag" for the network map, the update stream server must
   send a full replacement for the network map as well as for the cost
   map.  The ALTO client does not set "incremental-changes" to "false",
   so it defaults to "true".  Thus, the update stream server will send
   patch updates for the cost map and the network map.

     POST /updates/costs HTTP/1.1
     Host: alto.example.com
     Accept: text/event-stream,application/alto-error+json
     Content-Type: application/alto-updatestreamparams+json
     Content-Length: 155

     { "add": {
         "my-network-map": {
           "resource-id": "my-network-map"
           },
         "my-routingcost-map": {
           "resource-id": "my-routingcost-map"
         }
       }
     }

     HTTP/1.1 200 OK
     Connection: keep-alive
     Content-Type: text/event-stream

     event: application/alto-updatestreamcontrol+json
     data: {"control-uri":
     data: "https://alto.example.com/updates/streams/3141592653589"}

     event: application/alto-networkmap+json,my-network-map
     data: {
     data:   "meta" : {
     data:     "vtag": {
     data:       "resource-id" : "my-network-map",
     data:         "tag" : "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785"
     data:       }
     data:     },
     data:     "network-map" : {
     data:       "PID1" : {
     data:         "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25" ]
     data:       },
     data:       "PID2" : {
     data:         "ipv4" : [ "198.51.100.128/25" ]
     data:       },
     data:       "PID3" : {
     data:         "ipv4" : [ "0.0.0.0/0" ],
     data:         "ipv6" : [ "::/0" ]
     data:       }
     data:     }
     data:   }
     data: }

     event: application/alto-costmap+json,my-routingcost-map
     data: {
     data:   "meta" : {
     data:     "dependent-vtags" : [{
     data:       "resource-id": "my-network-map",
     data:       "tag": "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785"
     data:     }],
     data:     "cost-type" : {
     data:       "cost-mode"  : "numerical",
     data:       "cost-metric": "routingcost"
     data:     },
     data:     "vtag": {
     data:       "resource-id" : "my-routingcost-map",
     data:       "tag" : "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"
     data:     }
     data:   },
     data:   "cost-map" : {
     data:     "PID1": { "PID1": 1,  "PID2": 5,  "PID3": 10 },
     data:     "PID2": { "PID1": 5,  "PID2": 1,  "PID3": 15 },
     data:     "PID3": { "PID1": 20, "PID2": 15  }
     data:   }
     data: }

   After sending those events immediately, the update stream server will
   send additional events as the maps change.  For example, the
   following represents a small change to the cost map.  PID1->PID2 is
   changed to 9 from 5, PID3->PID1 is no longer available, and
   PID3->PID3 is now defined as 1:

     event: application/merge-patch+json,my-routingcost-map
     data: {
     data:   "meta" : {
     data:     "vtag": {
     data:       "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"
     data:     }
     data:   },
     data:   "cost-map": {
     data:     "PID1" : { "PID2" : 9 },
     data:     "PID3" : { "PID1" : null, "PID3" : 1 }
     data:   }
     data: }

   As another example, the following represents a change to the network
   map: an ipv4 prefix "203.0.113.0/25" is added to PID1.  It triggers
   changes to the cost map.  The update stream server chooses to send an
   incremental change for the network map and send a full replacement
   instead of an incremental change for the cost map:

         event: application/json-patch+json,my-network-map
         data: {
         data:   {
         data:     "op": "replace",
         data:     "path": "/meta/vtag/tag",
         data:     "value" :"a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
         data:   },
         data:   {
         data:     "op": "add",
         data:     "path": "/network-map/PID1/ipv4/2",
         data:     "value": "203.0.113.0/25"
         data:   }
         data: }

         event: application/alto-costmap+json,my-routingcost-map
         data: {
         data:   "meta" : {
         data:     "vtag": {
         data:       "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"
         data:     }
         data:   },
         data:   "cost-map" : {
         data:     "PID1": { "PID1": 1,  "PID2": 3,  "PID3": 7 },
         data:     "PID2": { "PID1": 12, "PID2": 1,  "PID3": 9 },
         data:     "PID3": { "PID1": 14, "PID2": 8  }
         data:   }
         data: }

8.3.  Example: Advanced Network and Cost Map Updates

   This example is similar to the previous one, except that the ALTO
   client requests updates for the "hopcount" cost map as well as the
   "routingcost" cost map and provides the current version tag of the
   network map, so the update stream server is not required to send the
   full network map data update message at the beginning of the stream.
   In this example, the client uses the substream-ids "net", "routing",
   and "hops" for those resources.  The update stream server sends the
   stream control URI and the full cost maps, followed by updates for
   the network map and cost maps as they become available:

     POST /updates/costs HTTP/1.1
     Host: alto.example.com
     Accept: text/event-stream,application/alto-error+json
     Content-Type: application/alto-updatestreamparams+json
     Content-Length: 244

     { "add": {
         "net": {
           "resource-id": "my-network-map",
           "tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
         },
         "routing": {
           "resource-id": "my-routingcost-map"
         },
         "hops": {
           "resource-id": "my-hopcount-map"
         }
       }
     }

     HTTP/1.1 200 OK
     Connection: keep-alive
     Content-Type: text/event-stream

     event: application/alto-updatestreamcontrol+json
     data: {"control-uri":
     data: "https://alto.example.com/updates/streams/2718281828459"}

     event: application/alto-costmap+json,routing
     data: { ... full routingcost cost map message ... }

     event: application/alto-costmap+json,hops
     data: { ... full hopcount cost map message ... }

        (pause)

     event: application/merge-patch+json,routing
     data: {"cost-map": {"PID2" : {"PID3" : 31}}}

     event: application/merge-patch+json,hops
     data: {"cost-map": {"PID2" : {"PID3" : 4}}}

   If the ALTO client wishes to stop receiving updates for the
   "hopcount" cost map, the ALTO client can send a "remove" request on
   the stream control URI:

     POST /updates/streams/2718281828459 HTTP/1.1
     Host: alto.example.com
     Accept: text/plain,application/alto-error+json
     Content-Type: application/alto-updatestreamparams+json
     Content-Length: 24

     {
       "remove": [ "hops" ]
     }


     HTTP/1.1 204 No Content
     Content-Length: 0

         (stream closed without sending data content)

   The update stream server sends a "stopped" control update message on
   the original request stream to inform the ALTO client that updates
   are stopped for that resource:

     event: application/alto-updatestreamcontrol+json
     data: {
     data:   "stopped": ["hops"]
     data: }

   Below is an example of an invalid stream control request.  The
   "remove" field of the request includes an undefined substream-id, and
   the stream control server will return an error response to the ALTO
   client.

         POST /updates/streams/2718281828459 HTTP/1.1
         Host: alto.example.com
         Accept: text/plain,application/alto-error+json
         Content-Type: application/alto-updatestreamparams+json
         Content-Length: 31
         {
           "remove": [ "properties" ]
         }

         HTTP/1.1 400 Bad Request
         Content-Length: 89
         Content-Type: application/alto-error+json

         {
           "meta":{
           "code": "E_INVALID_FIELD_VALUE",
           "field": "remove",
           "value": "properties"
         }

   If the ALTO client no longer needs any updates and wishes to shut the
   update stream down gracefully, the client can send a "remove" request
   with an empty array:

     POST /updates/streams/2718281828459 HTTP/1.1
     Host: alto.example.com
     Accept: text/plain,application/alto-error+json
     Content-Type: application/alto-updatestreamparams+json
     Content-Length: 17

     {
       "remove": [ ]
     }


     HTTP/1.1 204 No Content
     Content-Length: 0

         (stream closed without sending data content)

   The update stream server sends a final control update message on the
   original request stream to inform the ALTO client that all updates
   are stopped and then closes the stream:

     event: application/alto-updatestreamcontrol+json
     data: {
     data:   "stopped": ["net", "routing"]
     data: }

         (server closes stream)

8.4.  Example: Endpoint Property Updates

   As another example, here is how an ALTO client can request updates
   for the property "priv:ietf-bandwidth" for one set of endpoints and
   "priv:ietf-load" for another.  The update stream server immediately
   sends full replacements with the property values for all endpoints.
   After that, the update stream server sends data update messages for
   the individual endpoints as their property values change.

     POST /updates/properties HTTP/1.1
     Host: alto.example.com
     Accept: text/event-stream
     Content-Type: application/alto-updatestreamparams+json
     Content-Length: 511

     { "add": {
         "props-1": {
           "resource-id": "my-props",
           "input": {
             "properties" : [ "priv:ietf-bandwidth" ],
             "endpoints" : [
               "ipv4:198.51.100.1",
               "ipv4:198.51.100.2",
               "ipv4:198.51.100.3"
             ]
           }
         },
         "props-2": {
           "resource-id": "my-props",
           "input": {
             "properties" : [ "priv:ietf-load" ],
             "endpoints" : [
               "ipv6:2001:db8:100::1",
               "ipv6:2001:db8:100::2",
               "ipv6:2001:db8:100::3"
             ]
           }
         }
       }
     }

     HTTP/1.1 200 OK
     Connection: keep-alive
     Content-Type: text/event-stream

     event: application/alto-updatestreamcontrol+json
     data: {"control-uri":
     data: "https://alto.example.com/updates/streams/1414213562373"}

     event: application/alto-endpointprops+json,props-1
     data: { "endpoint-properties": {
     data:     "ipv4:198.51.100.1" : { "priv:ietf-bandwidth": "13" },
     data:     "ipv4:198.51.100.2" : { "priv:ietf-bandwidth": "42" },
     data:     "ipv4:198.51.100.3" : { "priv:ietf-bandwidth": "27" }
     data:  } }

     event: application/alto-endpointprops+json,props-2
     data: { "endpoint-properties": {
     data:     "ipv6:2001:db8:100::1" : { "priv:ietf-load": "8" },
     data:     "ipv6:2001:db8:100::2" : { "priv:ietf-load": "2" },
     data:     "ipv6:2001:db8:100::3" : { "priv:ietf-load": "9" }
     data:  } }

        (pause)

     event: application/merge-patch+json,props-1
     data: { "endpoint-properties":
     data:   {"ipv4:198.51.100.1" : {"priv:ietf-bandwidth": "3"}}
     data: }

        (pause)

     event: application/merge-patch+json,props-2
     data: { "endpoint-properties":
     data:   {"ipv6:2001:db8:100::3" : {"priv:ietf-load": "7"}}
     data: }

   If the ALTO client needs the "priv:ietf-bandwidth" property and the
   "priv:ietf-load" property for additional endpoints, the ALTO client
   can send an "add" request on the stream control URI:

     POST /updates/streams/1414213562373" HTTP/1.1
     Host: alto.example.com
     Accept: text/plain,application/alto-error+json
     Content-Type: application/alto-updatestreamparams+json
     Content-Length: 448

     { "add": {
         "props-3": {
           "resource-id": "my-props",
           "input": {
             "properties" : [ "priv:ietf-bandwidth" ],
             "endpoints" : [
               "ipv4:198.51.100.4",
               "ipv4:198.51.100.5"
             ]
           }
         },
         "props-4": {
           "resource-id": "my-props",
           "input": {
             "properties" : [ "priv:ietf-load" ],
             "endpoints" : [
               "ipv6:2001:db8:100::4",
               "ipv6:2001:db8:100::5"
             ]
           }
         }
       }
     }


     HTTP/1.1 204 No Content
     Content-Length: 0

         (stream closed without sending data content)

   The update stream server sends full replacements for the two new
   resources, followed by incremental changes for all four requests as
   they arrive:

     event: application/alto-endpointprops+json,props-3
     data: { "endpoint-properties": {
     data:     "ipv4:198.51.100.4" : { "priv:ietf-bandwidth": "25" },
     data:     "ipv4:198.51.100.5" : { "priv:ietf-bandwidth": "31" },
     data:  } }

     event: application/alto-endpointprops+json,props-4
     data: { "endpoint-properties": {
     data:     "ipv6:2001:db8:100::4" : { "priv:ietf-load": "6" },
     data:     "ipv6:2001:db8:100::5" : { "priv:ietf-load": "4" },
     data:  } }

        (pause)

     event: application/merge-patch+json,props-3
     data: { "endpoint-properties":
     data:   {"ipv4:198.51.100.5" : {"priv:ietf-bandwidth": "15"}}
     data: }

        (pause)

     event: application/merge-patch+json,props-2
     data: { "endpoint-properties":
     data:   {"ipv6:2001:db8:100::2" : {"priv:ietf-load": "9"}}
     data: }

        (pause)

     event: application/merge-patch+json,props-4
     data: { "endpoint-properties":
     data:   {"ipv6:2001:db8:100::4" : {"priv:ietf-load": "3"}}
     data: }

8.5.  Example: Multipart Message Updates

   This example shows how an ALTO client can request a nonstandard ALTO
   service returning a multipart response.  The update stream server
   immediately sends full replacements of the multipart response.  After
   that, the update stream server sends data update messages for the
   individual parts of the response as the ALTO data (object) in each
   part changes.

      POST /updates/pv HTTP/1.1
      Host: alto.example.com
      Accept: text/event-stream
      Content-Type: application/alto-updatestreamparams+json
      Content-Length: 382

      {
        "add": {
          "ecspvsub1": {
            "resource-id": "my-pv",
            "input": {
              "cost-type": {
                "cost-mode": "array",
                "cost-metric": "ane-path"
              },
              "endpoints": {
                "srcs": [ "ipv4:192.0.2.2" ],
                "dsts": [ "ipv4:192.0.2.89", "ipv4:203.0.113.45" ]
              },
              "ane-properties": [ "maxresbw", "persistent-entities" ]
            }
          }
        }
      }

      HTTP/1.1 200 OK
      Connection: keep-alive
      Content-Type: text/event-stream

      event: application/alto-updatestreamcontrol+json
      data: {"control-uri":
      data:    "https://alto.example.com/updates/streams/1414"}

      event: multipart/related;boundary=example-pv;
             type=application/alto-endpointcost+json,ecspvsub1
      data: --example-pv
      data: Content-ID: ecsmap
      data: Content-Type: application/alto-endpointcost+json
      data:
      data: { ... data (object) of an endpoint cost map ... }
      data: --example-pv
      data: Content-ID: propmap
      data: Content-Type: application/alto-propmap+json
      data:
      data: { ... data (object) of a property map ... }
      data: --example-pv--

         (pause)

      event: application/merge-patch+json,ecspvsub1.ecsmap
      data: { ... merge patch for updates of ecspvsub1.ecsmap ... }

      event: application/merge-patch+json,ecspvsub1.propmap
      data: { ... merge patch for updates of ecspvsub1.propmap ... }

9.  Operation and Processing Considerations

9.1.  Considerations for Choosing Data Update Messages

   The update stream server should be cognizant of the effects of its
   update schedule, which includes both the choice of timing (i.e.,
   when/what to trigger an update) and the choice of message format
   (i.e., given an update, send a full replacement or an incremental
   change).  In particular, the update schedule can have effects on both
   the overhead and the freshness of information.  To minimize overhead,
   the server may choose to batch a sequence of updates for resources
   that frequently change by sending cumulative updates or a full
   replacement after a while.  The update stream server should be
   cognizant that batching reduces the freshness of information.  The
   server should also consider the effect of such delays on client
   behaviors (see below on client timeout on waiting for updates of
   dependent resources).

   For incremental updates, this design allows both JSON patch and JSON
   merge patch for incremental changes.  JSON merge patch is clearly
   superior to JSON patch for describing incremental changes to cost
   maps, endpoint costs, and endpoint properties.  For these data
   structures, JSON merge patch is more space efficient, as well as
   simpler to apply.  There is no advantage allowing a server to use
   JSON patch for those resources.

   The case is not as clear for incremental changes to network maps.

   First, consider small changes, such as moving a prefix from one PID
   to another.  JSON patch could encode that as a simple insertion and
   deletion, while JSON merge patch would have to replace the entire
   array of prefixes for both PIDs.  On the other hand, to process a
   JSON patch update, the ALTO client would have to retain the indexes
   of the prefixes for each PID.  Logically, the prefixes in a PID are
   an unordered set, not an array; aside from handling updates, a client
   has no need to retain the array indexes of the prefixes.  Hence, to
   take advantage of JSON patch for network maps, ALTO clients would
   have to retain additional, otherwise unnecessary, data.

   Second, consider more involved changes, such as removing half of the
   prefixes from a PID.  JSON merge patch would send a new array for
   that PID, while JSON patch would have to send a list of remove
   operations and delete the prefix one by one.

   Therefore, each update stream server may decide on its own whether to
   use JSON merge patch or JSON patch according to the changes in
   network maps.

9.2.  Considerations for Client Processing Data Update Messages

   In general, when an ALTO client receives a full replacement for a
   resource, the ALTO client should replace the current version with the
   new version.  When an ALTO client receives an incremental change for
   a resource, the ALTO client should apply those patches to the current
   version of the resource.

   However, because resources can depend on other resources (e.g., cost
   maps depend on network maps), an ALTO client MUST NOT use a dependent
   resource if the resource on which it depends has changed.  There are
   at least two ways an ALTO client can do that.  The following
   paragraphs illustrate these techniques by referring to network and
   cost map messages, although these techniques apply to any dependent
   resources.

   Note that when a network map changes, the update stream server MUST
   send the network map update message before sending the updates for
   the dependent cost maps (see Section 6.7.1).

   One approach is for the ALTO client to save the network map update
   message in a buffer and continue to use the previous network map and
   the associated cost maps until the ALTO client receives the update
   messages for all dependent cost maps.  The ALTO client then applies
   all network and cost map updates atomically.

   Alternatively, the ALTO client MAY update the network map
   immediately.  In this case, the cost maps using the network map
   become invalid because they are inconsistent with the current network
   map; hence, the ALTO client MUST mark each such dependent cost map as
   temporarily invalid and MUST NOT use each such cost map until the
   ALTO client receives a cost map update message indicating that it is
   based on the new network map version tag.

   The update stream server SHOULD send updates for dependent resources
   (i.e., the cost maps in the preceding example) in a timely fashion.
   However, if the ALTO client does not receive the expected updates, a
   simple recovery method is that the ALTO client closes the update
   stream connection, discards the dependent resources, and
   reestablishes the update stream.  The ALTO client MAY retain the
   version tag of the last version of any tagged resources and give
   those version tags when requesting the new update stream.  In this
   case, if a version is still current, the update stream server will
   not resend that resource.

   Although not as efficient as possible, this recovery method is simple
   and reliable.

9.3.  Considerations for Updates to Filtered Cost Maps

   If an update stream provides updates to a Filtered Cost Map that
   allows constraint tests, then an ALTO client MAY request updates to a
   Filtered Cost Map request with a constraint test.  In this case, when
   a cost changes, the update stream server MUST send an update if the
   new value satisfies the test.  If the new value does not, whether the
   update stream server sends an update depends on whether the previous
   value satisfied the test.  If it did not, the update stream server
   SHOULD NOT send an update to the ALTO client.  But if the previous
   value did, then the update stream server MUST send an update with a
   "null" value to inform the ALTO client that this cost no longer
   satisfies the criteria.

   An update stream server can avoid having to handle such a complicated
   behavior by offering update streams only for Filtered Cost Maps that
   do not allow constraint tests.

9.4.  Considerations for Updates to Ordinal Mode Costs

   For an ordinal mode cost map, a change to a single cost point may
   require updating many other costs.  As an extreme example, suppose
   the lowest cost changes to the highest cost.  For a numerical mode
   cost map, only that one cost changes.  But for an ordinal mode cost
   map, every cost might change.  While this document allows an update
   stream server to offer incremental updates for ordinal mode cost
   maps, update stream server implementors should be aware that
   incremental updates for ordinal costs are more complicated than for
   numerical costs, and ALTO clients should be aware that small changes
   may result in large updates.

   An update stream server can avoid this complication by only offering
   full replacements for ordinal cost maps.

9.5.  Considerations for SSE Text Formatting and Processing

   SSE was designed for events that consist of relatively small amounts
   of line-oriented text data, and SSE clients frequently read input one
   line at a time.  However, an update stream sends a full cost map as a
   single events, and a cost map may involve megabytes, if not tens of
   megabytes, of text.  This has implications that the ALTO client and
   the update stream server may consider.

   First, some SSE client libraries read all data for an event into
   memory and then present it to the client as a character array.
   However, a client may not have enough memory to hold the entire JSON
   text for a large cost map.  Hence, an ALTO client SHOULD consider
   using an SSE library that presents the event data in manageable
   chunks, so the ALTO client can parse the cost map incrementally and
   store the underlying data in a more compact format.

   Second, an SSE client library may use a low-level, generic socket
   read library that stores each line of an event data, just in case the
   higher-level parser may need the line delimiters as part of the
   protocol formatting.  A server sending a complete cost map as a
   single line may then generate a multi-megabyte data "line", and such
   a long line may then require complex memory management at the client.
   It is RECOMMENDED that an update stream server limit the lengths of
   data lines.

   Third, an SSE server may use a library, which may put line breaks in
   places that would have semantic consequences for the ALTO updates;
   see Section 11.  The update stream server implementation MUST ensure
   that no line breaks are introduced to change the semantics.

10.  Security Considerations

   The security considerations (Section 15 of [RFC7285]) of the base
   protocol fully apply to this extension.  For example, the same
   authenticity and integrity considerations (Section 15.1 of [RFC7285])
   still fully apply; the same considerations for the privacy of ALTO
   users (Section 15.4 of [RFC7285]) also still fully apply.

   The additional services (addition of update streams and stream
   control URIs) provided by this extension extend the attack surface
   described in Section 15.1.1 of [RFC7285].  Below, we discuss the
   additional risks and their remedies.

10.1.  Update Stream Server: Denial-of-Service Attacks

   Allowing persistent update stream connections enables a new class of
   Denial-of-Service attacks.

   For the update stream server, an ALTO client might create an
   unreasonable number of update stream connections or add an
   unreasonable number of substream-ids to one update stream.

   To avoid these attacks on the update stream server, the server SHOULD
   choose to limit the number of active streams and reject new requests
   when that threshold is reached.  An update stream server SHOULD also
   choose to limit the number of active substream-ids on any given
   stream or limit the total number of substream-ids used over the
   lifetime of a stream and reject any stream control request that would
   exceed those limits.  In these cases, the update stream server SHOULD
   return the HTTP status "503 Service Unavailable".

   It is important to note that the preceding approaches are not the
   only possibilities.  For example, it may be possible for the update
   stream server to use somewhat more clever logic involving IP
   reputation, rate-limiting, and compartmentalization of the overall
   threshold into smaller thresholds that apply to subsets of potential
   clients.

   While the preceding techniques prevent update stream DoS attacks from
   disrupting an update stream server's other services, it does make it
   easier for a DoS attack to disrupt the update stream service.
   Therefore, an update stream server MAY prefer to restrict update
   stream services to authorized clients, as discussed in Section 15 of
   [RFC7285].

   Alternatively, an update stream server MAY return the HTTP status
   "307 Temporary Redirect" to redirect the client to another ALTO
   server that can better handle a large number of update streams.

10.2.  ALTO Client: Update Overloading or Instability

   The availability of continuous updates can also cause overload for an
   ALTO client, in particular, an ALTO client with limited processing
   capabilities.  The current design does not include any flow control
   mechanisms for the client to reduce the update rates from the server.
   Under overloading, the client MAY choose to remove the information
   resources with high update rates.

   Also, under overloading, the client may no longer be able to detect
   whether information is still fresh or has become stale.  In such a
   case, the client should be careful in how it uses the information to
   avoid stability or efficiency issues.

10.3.  Stream Control: Spoofed Control Requests and Information
       Breakdown

   An outside party that can read the update stream response or that can
   observe stream control requests can obtain the control URI and use
   that to send a fraudulent "remove" requests, thus disabling updates
   for the valid ALTO client.  This can be avoided by encrypting the
   update stream and stream control requests (see Section 15 of
   [RFC7285]).  Also, the update stream server echoes the "remove"
   requests on the update stream, so the valid ALTO client can detect
   unauthorized requests.

   In general, as the architecture allows the possibility for the update
   stream server and the stream control server to be different entities,
   the additional risks should be evaluated and remedied.  For example,
   the private communication path between the servers may be attacked,
   resulting in a risk of communications breakdown between them, as well
   as invalid or spoofed messages claiming to be on that private
   communications path.  Proper security mechanisms, including
   confidentiality, authenticity, and integrity mechanisms, should be
   considered.

11.  Requirements on Future ALTO Services to Use This Design

   Although this design is quite flexible, it has underlying
   requirements.

   The key requirements are that (1) each data update message is for a
   single resource and (2) an incremental change can be applied only to
   a resource that is a single JSON object, as both JSON merge patch and
   JSON patch can apply only to a single JSON object.  Hence, if a
   future ALTO resource can contain multiple objects, then either each
   individual object also has a resource-id or an extension to this
   design is made.

   At the low-level encoding level, new line in SSE has its own
   semantics.  Hence, this design requires that resource encoding does
   not include new lines that can be confused with SSE encoding.  In
   particular, the data update message MUST NOT include "event: " or
   "data: " at a new line as part of data message.

   If an update stream provides updates to a Filtered Cost Map that
   allows constraint tests, the requirements for such services are
   stated in Section 9.3.

12.  IANA Considerations

   This document defines two new media types: "application/alto-
   updatestreamparams+json", as described in Section 6.5, and
   "application/alto-updatestreamcontrol+json", as described in
   Section 5.3.  All other media types used in this document have
   already been registered, either for ALTO, JSON merge patch, or JSON
   patch.

12.1.  application/alto-updatestreamparams+json Media Type

   Type name:  application

   Subtype name:  alto-updatestreamparams+json

   Required parameters:  N/A

   Optional parameters:  N/A

   Encoding considerations:  Encoding considerations are identical to
      those specified for the "application/json" media type.  See
      [RFC8259].

   Security considerations:  Security considerations relating to the
      generation and consumption of ALTO Protocol messages are discussed
      in Section 10 of RFC 8895 and Section 15 of [RFC7285].

   Interoperability considerations:  RFC 8895 specifies format of
      conforming messages and the interpretation thereof.

   Published specification:  Section 6.5 of RFC 8895.

   Applications that use this media type:  ALTO servers and ALTO clients
      either stand alone or are embedded within other applications.

   Fragment identifier considerations:  N/A

   Additional information:

      Deprecated alias names for this type:  N/A

      Magic number(s):  N/A

      File extension(s):  RFC 8895 uses the media type to refer to
         protocol messages and thus does not require a file extension.

      Macintosh file type code(s):  N/A

   Person & email address to contact for further information:  See
      Authors' Addresses section.

   Intended usage:  COMMON

   Restrictions on usage:  N/A

   Author:  See Authors' Addresses section.

   Change controller:  Internet Engineering Task Force
      (mailto:iesg@ietf.org).

12.2.  application/alto-updatestreamcontrol+json Media Type

   Type name:  application

   Subtype name:  alto-updatestreamcontrol+json

   Required parameters:  N/A

   Optional parameters:  N/A

   Encoding considerations:  Encoding considerations are identical to
      those specified for the "application/json" media type.  See
      [RFC8259].

   Security considerations:  Security considerations relating to the
      generation and consumption of ALTO Protocol messages are discussed
      in Section 10 of RFC 8895 and Section 15 of [RFC7285].

   Interoperability considerations:  RFC 8895 specifies format of
      conforming messages and the interpretation thereof.

   Published specification:  Section 5.3 of RFC 8895.

   Applications that use this media type:  ALTO servers and ALTO clients
      either stand alone or are embedded within other applications.

   Fragment identifier considerations:  N/A

   Additional information:

      Deprecated alias names for this type:  N/A

      Magic number(s):  N/A

      File extension(s):  RFC 8895 uses the media type to refer to
         protocol messages and thus does not require a file extension.

      Macintosh file type code(s):  N/A

   Person & email address to contact for further information:  See
      Authors' Addresses section.

   Intended usage:  COMMON

   Restrictions on usage:  N/A

   Author:  See Authors' Addresses section.

   Change controller:  Internet Engineering Task Force
      (mailto:iesg@ietf.org).

13.  Appendix: Design Decision: Not Allowing Stream Restart

   If an update stream is closed accidentally, when the ALTO client
   reconnects, the update stream server must resend the full maps.  This
   is clearly inefficient.  To avoid that inefficiency, the SSE
   specification allows an update stream server to assign an id to each
   event.  When an ALTO client reconnects, the ALTO client can present
   the id of the last successfully received event, and the update stream
   server restarts with the next event.

   However, that mechanism adds additional complexity.  The update
   stream server must save SSE messages in a buffer in case ALTO clients
   reconnect.  But that mechanism will never be perfect: If the ALTO
   client waits too long to reconnect or if the ALTO client sends an
   invalid ID, then the update stream server will have to resend the
   complete maps anyway.

   Furthermore, this is unlikely to be a problem in practice.  ALTO
   clients who want continuous updates for large resources, such as full
   network and cost maps, are likely to be things like P2P trackers.
   These ALTO clients will be well connected to the network; they will
   rarely drop connections.

   Mobile devices certainly can and do drop connections and will have to
   reconnect.  But mobile devices will not need continuous updates for
   multi-megabyte cost maps.  If mobile devices need continuous updates
   at all, they will need them for small queries, such as the costs from
   a small set of media servers from which the device can stream the
   currently playing movie.  If the mobile device drops the connection
   and reestablishes the update stream, the update stream server will
   have to retransmit only a small amount of redundant data.

   In short, using event ids to avoid resending the full map adds a
   considerable amount of complexity to avoid a situation that is very
   rare.  The complexity is not worth the benefit.

   The update stream service does allow the ALTO client to specify the
   tag of the last received version of any tagged resource, and if that
   is still current, the update stream server need not retransmit the
   full resource.  Hence, ALTO clients can use this to avoid
   retransmitting full network maps.  Cost maps are not tagged, so this
   will not work for them.  Of course, the ALTO protocol could be
   extended by adding version tags to cost maps, which would solve the
   retransmission-on-reconnect problem.  However, adding tags to cost
   maps might add a new set of complications.

14.  References

14.1.  Normative References

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

   [RFC2387]  Levinson, E., "The MIME Multipart/Related Content-type",
              RFC 2387, DOI 10.17487/RFC2387, August 1998,
              <https://www.rfc-editor.org/info/rfc2387>.

   [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,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,
              <https://www.rfc-editor.org/info/rfc6838>.

   [RFC6902]  Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object
              Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902,
              April 2013, <https://www.rfc-editor.org/info/rfc6902>.

   [RFC7285]  Alimi, R., Ed., Penno, R., Ed., Yang, Y., Ed., Kiesel, S.,
              Previdi, S., Roome, W., Shalunov, S., and R. Woundy,
              "Application-Layer Traffic Optimization (ALTO) Protocol",
              RFC 7285, DOI 10.17487/RFC7285, September 2014,
              <https://www.rfc-editor.org/info/rfc7285>.

   [RFC7396]  Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
              DOI 10.17487/RFC7396, October 2014,
              <https://www.rfc-editor.org/info/rfc7396>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [SSE]      Hickson, I., "Server-Sent Events", W3C Recommendation,
              February 2015, <https://www.w3.org/TR/eventsource/>.

14.2.  Informative References

   [RFC4960]  Stewart, R., Ed., "Stream Control Transmission Protocol",
              RFC 4960, DOI 10.17487/RFC4960, September 2007,
              <https://www.rfc-editor.org/info/rfc4960>.

   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP",
              RFC 5789, DOI 10.17487/RFC5789, March 2010,
              <https://www.rfc-editor.org/info/rfc5789>.

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,
              <https://www.rfc-editor.org/info/rfc7230>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <https://www.rfc-editor.org/info/rfc7231>.

   [RFC7540]  Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
              Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
              DOI 10.17487/RFC7540, May 2015,
              <https://www.rfc-editor.org/info/rfc7540>.

Acknowledgments

   Thank you to Dawn Chen (Tongji University), Shawn Lin (Tongji
   University), and Xiao Shi (Yale University) for their contributions
   to an earlier version of this document.

Contributors

   Sections 2, 5.1, 5.2, and 8.5 of this document are based on
   contributions from Jingxuan Jensen Zhang, and he is considered an
   author.

Authors' Addresses

   Wendy Roome
   Nokia Bell Labs (Retired)
   124 Burlington Rd
   Murray Hill, NJ 07974
   United States of America

   Phone: +1-908-464-6975
   Email: wendy@wdroome.com


   Y. Richard Yang
   Yale University
   51 Prospect St
   New Haven, CT
   United States of America

   Email: yry@cs.yale.edu