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

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

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

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).¶