One document matched: draft-ietf-alto-incr-update-sse-02.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "http://http://tools.ietf.org/tools/templates/rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc iprnotified="no" ?>
<?rfc symrefs="yes"?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std"
docName="draft-ietf-alto-incr-update-sse-02"
ipr="trust200902">
<front>
<title abbrev="ALTO Incremental Updates">ALTO Incremental Updates Using Server-Sent Events (SSE)</title>
<author initials="W." surname="Roome" fullname="Wendy Roome">
<organization abbrev="Nokia">Nokia/Bell Labs</organization>
<address>
<postal>
<street>600 Mountain Ave, Rm 3B-324</street>
<city>Murray Hill</city>
<region>NJ</region>
<code>07974</code>
<country>USA</country>
</postal>
<phone>+1-908-582-7974</phone>
<email>wendy.roome@nokia.com</email>
</address>
</author>
<!--
<author initials="X." surname="Shi" fullname="Xiao Shi">
<organization abbrev="Yale University">Yale University</organization>
<address>
<postal>
<street>51 Prospect Street</street>
<city>New Haven</city>
<region>CT</region>
<code>06511</code>
<country>USA</country>
</postal>
<email>xiao.shi@yale.edu</email>
</address>
</author>
-->
<author fullname="Y. Richard Yang" initials="Y." surname="Yang">
<organization>Tongji/Yale University</organization>
<address>
<postal>
<street>51 Prospect St</street>
<city>New Haven</city>
<code>CT</code>
<country>USA</country>
</postal>
<email>yang.r.yang@gmail.com</email>
</address>
</author>
<date month="April" day="4" year="2016"/>
<area>Networks</area>
<workgroup>ALTO WG</workgroup>
<keyword>ALTO</keyword>
<abstract>
<t>
The Application-Layer Traffic Optimization (ALTO)
<xref target="RFC7285"/> protocol
provides network related information to client
applications so that clients may make informed
decisions. To that end, an ALTO Server provides
Network and Cost Maps. Using those maps, an ALTO Client
can determine the costs between endpoints.
</t>
<t>
However, the ALTO protocol does not define a mechanism
to allow an ALTO client to obtain updates to those maps,
other than by periodically re-fetching them.
Because the maps may be large (potentially tens of megabytes),
and because only parts of the maps may change frequently (especially Cost Maps),
that can be extremely inefficient.
</t>
<t>
Therefore this document presents a mechanism to allow an ALTO Server
to provide updates to ALTO Clients.
Updates can be both immediate, in that the server can send updates
as soon as they are available,
and incremental, in that if only a small section of a map changes,
the server can send just the changes.
</t>
</abstract>
<note title="Requirements Language">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref target="RFC2119">RFC 2119</xref>.</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>
The Application-Layer Traffic Optimization (ALTO)
<xref target="RFC7285"/> protocol
provides network related information to client
applications so that clients may make informed
decisions. To that end, an ALTO Server provides
Network and Cost Maps, where a Network Map partitions the set
of endpoints into a manageable number of Provider-Defined Identifiers (PIDs),
and a Cost Map provides directed costs between PIDs.
Given Network and Cost Maps, an ALTO Client
can obtain costs between endpoints by using the Network Map
to get the PID for each endpoint, and then using the Cost Map
to get the costs between those PIDs.
</t>
<t>
However, the ALTO protocol does not define a mechanism
to allow a client to obtain updates to those maps,
other than by periodically re-fetching them.
Because the maps may be large (potentially tens of megabytes),
and because parts of the maps may change frequently (especially Cost Maps),
that can be extremely inefficient.
</t>
<t>
Therefore this document presents a mechanism to allow an ALTO Server
to provide incremental updates to ALTO Clients.
Updates can be both immediate, in that the server can send updates
as soon as they are available,
and incremental, in that if only a small section of a map changes,
the server can send just the changes.
</t>
<t>
While primarily intended to provide updates to Network and Cost Maps,
the mechanism defined in this document can
provide updates to any ALTO resource, including POST-mode services
such as Endpoint Property and Endpoint Cost Services,
as well as new ALTO services to be defined by future extensions.
</t>
<t>
The rest of this document is organized as follows.
<xref target="Overview"/> gives an overview of the incremental update approach,
which is based on Server-Sent Events (SSEs).
<xref target="SSEOverview"/> and <xref target="MergePatchOverview"/>
give SSEs and JSON Merge Patch,
the technologies on which ALTO updates are based.
<xref target="ALTO.SSE.Events"/> defines the update events,
<xref target="UpdateStreamService"/>
and <xref target="UpdateStreamControlService"/>
define the update services themselves,
and <xref target="Examples"/> gives several examples.
<xref target="ClientActions"/> describes
how a client should handle incoming updates.
<xref target="DesignDecisions"/>
and
<xref target="MiscConsiderations"/>
discuss the design decisions behind this update mechanism
and other considerations.
The remaining sections review the security and IANA considerations.
</t>
</section>
<section title="Overview of Approach" anchor="Overview">
<t>
This section presents a non-normative overview of the update mechanism
to be defined in this document.
</t>
<t>
An ALTO Server can offer one or more Update Stream resources, where
each Update Stream resource (or Update Stream for short) is a POST-mode
service that returns a continuous sequence of update messages
for one or more ALTO resources.
An Update Stream can provide updates to both GET-mode resources,
such as Network and Cost Maps,
and POST-mode resources, such as Endpoint Property Services.
</t>
<t>
Each update message updates one resource, and is sent as a
Server-Sent Event (SSE), as defined by <xref target="SSE"/>.
An update message is either a full replacement
or else an incremental change.
Full replacement updates use the JSON message formats
defined by the ALTO protocol.
Incremental updates use JSON Merge Patch (<xref target="RFC7386"/>)
to describe the changes to the resource.
The ALTO Server decides when to send update messages,
and whether to send full replacements or incremental updates.
These decisions can vary from resource to resource
and from update to update.
</t>
<t>
An ALTO Server may offer any number of Update Stream resources,
for any subset of the server's resources.
An ALTO Server's Information Resource Directory (IRD)
defines the Update Stream resources,
and declares the set of resources for which each Update Stream
provides updates.
The server selects the resource set for each stream,
although it is recommended that the set
be closed under the ALTO resource dependency relationship
(i.e., the "uses" relationship).
Thus the Update Stream for a Cost Map will also
provide updates for the Network Map on which that Cost Map depends.
</t>
<t>
When an ALTO Client requests an Update Stream resource,
the client establishes a new persistent connection
to the server. The server responds by sending an event
with the URI of a stream-control resource for
this update stream. The client uses the control URI
to select the resources for which it wants updates.
The client can also use the control URI to tell
the server to stop sending updates for some resources,
or to shut the update stream down completely.
</t>
<t>
A client may request any number of Update Streams simultaneously.
Because each stream consumes resources on the server,
a server may limit the number of open Update Streams,
may close inactive streams,
may provide Update Streams via other processors,
or may require client authorization/authentication.
</t>
</section>
<section title="Changes Since Version -01" anchor="Changes">
<t>
<list style="symbols">
<t>
Defined a new "Stream Control" resource
(<xref target="UpdateStreamControlService"/>)
to allow clients to add or remove resources
from a previously created 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.
</t>
<t>
The client now assigns a unique client-id
to each resource in an update stream.
The server puts the client-id in each update
event for that resource (before, the server
used the server's resource-id).
This allows a client to use one stream to get
updates to two different Endpoint Cost requests
(before, that required two separate streams).
</t>
</list>
</t>
</section>
<section title="Overview of Server-Sent Events (SSEs)" anchor="SSEOverview">
<t>
The following is a non-normative summary of Server-Sent Events (SSEs).
See <xref target="SSE"/> for the normative definition.
</t>
<t>
Server-Sent Events enable a server
to send new data to a client by "server-push".
The client establishes
an HTTP (<xref target="RFC2616"/>) connection to the server,
and keeps the connection open.
The server continually sends messages.
Messages are delimited by two new-lines
(this is a slight simplification; see <xref target="SSE"/> for details).
Each line is of the form "field-name: string value".
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" or "id" line per message.
The "data" field is required; the others are optional.
</t>
<t>
<xref target="sse-example"/> is a sample SSE stream, starting with the client request.
The server sends three events and then closes the stream.
</t>
<figure anchor="sse-example" title="A Sample SSE stream.">
<artwork><![CDATA[
(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: good bye
]]></artwork>
</figure>
</section>
<section title="Incremental Update Message Format" anchor="MergePatchOverview">
<section title="Overview of JSON Merge Patch">
<t>
The following is a non-normative summary of JSON Merge Patch.
See <xref target="RFC7386"/> for the normative definition.
</t>
<t>
JSON Merge Patch is intended to allow applications to update
server resources via the HTTP PATCH method <xref target="RFC5789"/>.
This document adopts the JSON Merge Patch message format
to encode the changes,
but uses a different transport mechanism.
</t>
<t>
Informally, a Merge Patch object is a JSON data structure
that defines how to transform one JSON value
into another.
Merge Patch treats the two JSON values as trees
of nested JSON Objects (dictionaries of name-value pairs),
where the leaves are values other than JSON Objects (e.g.,
JSON Arrays, Strings, Numbers, etc.),
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 Merge Patch tree 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 Merge Patch tree has
a leaf with a JSON "null" value.
The Merge Patch tree does not have an entry for any leaf
that has the same value in both versions.
</t>
<t>
As a result, if all leaf values are simple scalars,
JSON Merge Patch is a very efficient representation
of the change. It is less efficient when leaf values
are arrays, because JSON Merge Patch replaces arrays
in their entirety, even if only one entry changes.
</t>
<t>
Formally, the process of applying a Merge Patch is defined by the
following recursive algorithm, as specified in <xref target="RFC7386"/>:
</t>
<figure>
<artwork><![CDATA[
define MergePatch(Target, Patch) {
if Patch is an Object {
if Target is not an Object {
Target = {} # Ignore the contents and
# set it to an empty Object
}
for each Name/Value pair in Patch {
if Value is null {
if Name exists in Target {
remove the Name/Value pair from Target
}
} else {
Target[Name] = MergePatch(Target[Name], Value)
}
}
return Target
} else {
return Patch
}
}
]]></artwork>
</figure>
<t>
Note that null as the value of a name/value pair will
delete the element with "name" in the original JSON value.
</t>
</section>
<section title="JSON Merge Patch Applied to Network Map Messages">
<t>
Section 11.2.1.6 of <xref target="RFC7285"/> defines the format
of a Network Map message.
Here is a simple example:
</t>
<figure>
<artwork><![CDATA[
{
"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" ]
}
}
}
]]></artwork>
</figure>
<t>
When applied to that message, the following Merge Patch update message
adds the ipv6 prefix "2000::/3" to "PID1",
deletes "PID2",
and assigns a new "tag" to the Network Map:
</t>
<figure>
<artwork><![CDATA[
{
"meta" : {
"vtag" : {
"tag" : "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
}
},
"network-map": {
"PID1" : {
"ipv6" : [ "2000::/3" ]
},
"PID2" : null
}
}
]]></artwork>
</figure>
<t>
Here is the updated Network Map:
</t>
<figure>
<artwork><![CDATA[
{
"meta" : {
"vtag": {
"resource-id" : "my-network-map",
"tag" : "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
}
},
"network-map" : {
"PID1" : {
"ipv4" : [ "192.0.2.0/24", "198.51.100.0/25" ],
"ipv6" : [ "2000::/3" ]
},
"PID3" : {
"ipv4" : [ "0.0.0.0/0" ],
"ipv6" : [ "::/0" ]
}
}
}
]]></artwork>
</figure>
</section>
<section title="JSON Merge Patch Applied to Cost Map Messages">
<t>
Section 11.2.3.6 of <xref target="RFC7285"/> defines the format
of a Cost Map message. Here is a simple example:
</t>
<figure>
<artwork><![CDATA[
{
"meta" : {
"dependent-vtags" : [
{"resource-id": "my-network-map",
"tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
}
],
"cost-type" : {
"cost-mode" : "numerical",
"cost-metric": "routingcost"
}
},
"cost-map" : {
"PID1": { "PID1": 1, "PID2": 5, "PID3": 10 },
"PID2": { "PID1": 5, "PID2": 1, "PID3": 15 },
"PID3": { "PID1": 20, "PID2": 15 }
}
}
]]></artwork>
</figure>
<t>
The following Merge Patch message updates the example cost map
so that PID1->PID2 is 9 instead of 5,
PID3->PID1 is no longer available,
and PID3->PID3 is now defined as 1:
<!-- yry again, the tag issue -->
</t>
<figure>
<artwork><![CDATA[
{
"cost-map" : {
"PID1" : { "PID2" : 9 },
"PID3" : { "PID1" : null, "PID3" : 1 }
}
}
]]></artwork>
</figure>
<t>
Here is the updated cost map:
</t>
<figure>
<artwork><![CDATA[
{
"meta" : {
"dependent-vtags" : [
{"resource-id": "my-network-map",
"tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
}
],
"cost-type" : {
"cost-mode" : "numerical",
"cost-metric": "routingcost"
}
},
"cost-map" : {
"PID1": { "PID1": 1, "PID2": 9, "PID3": 10 },
"PID2": { "PID1": 5, "PID2": 1, "PID3": 15 },
"PID3": { "PID2": 15, "PID3": 1 }
}
}
]]></artwork>
</figure>
</section>
</section>
<section title="ALTO Event Stream" anchor="ALTO.SSE.Events">
<t>
The Update Stream service (<xref target="UpdateStreamService"/>)
returns a stream of Update Events (<xref target="ALTO.SSE.UpdateEvents"/>)
and Control Events (<xref target="ALTO.SSE.ControlEvents"/>).
</t>
<section title="ALTO Event Format" anchor="ALTO.SSE.EventFormat">
<t>
Update and Control Events have the same basic stucture.
The data field is a JSON object,
and the event field contains the media type
of the data field, and an optional client id.
Update Events use the client id to identify
the ALTO resource to which the update message applies.
Client ids MUST follow the rules for ALTO ResourceIds
(see {10.2} of <xref target="RFC7285"/>.
Client ids MUST be unique within an Update Stream,
but need not be globally unique.
For example, if a client requests updates
for both a Cost Map and its Network Map,
the client might assign id "1" to the Network Map
and "2" to the Cost Map.
Alternatively, the client could use the ALTO resource ids
for those two maps.
</t>
<t>
JSON specifications use the type ClientId for a client-id.
</t>
<t>
The two sub-fields of the event field are encoded as
comma-separated strings:
</t>
<figure>
<artwork><![CDATA[
media-type [ ',' client-id ]
]]></artwork>
</figure>
<t>
Note that media type names may not contain a comma (character code 0x2c).
</t>
<t>
The Update Stream Service does not use the SSE "id" field.
</t>
</section>
<section title="ALTO Update Events" anchor="ALTO.SSE.UpdateEvents">
<t>
The Update Stream Service sends an update event
when a monitored resource changes.
The data is either a complete specification of the resource,
or else a JSON Merge Patch object
describing the changes from the last version.
We will refer to these as full-replacement and Merge Patch messages, respectively.
The data objects in full-replacement messages
are defined by <xref target="RFC7285"/>;
examples are Network and Cost Map messages.
They have the media types defined in that document.
The data objects in Merge Patch messages
are defined by <xref target="RFC7386"/>,
and they have the media type "application/merge-patch+json",
as defined by <xref target="RFC7386"/>.
</t>
<t>
<xref target="alto-sse-example"/> shows some examples of ALTO update events:
<!-- yry give an example of having , in resource id? -->
</t>
<figure anchor="alto-sse-example" title="Examples of ALTO update events.">
<artwork><![CDATA[
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: { ... Merge Patch update for the Cost Map ... }
]]></artwork>
</figure>
</section>
<section title="ALTO Control Events" anchor="ALTO.SSE.ControlEvents">
<t>
Control events have the media type
"application/alto-updatestreamcontrol+json",
and the data is of type UpdateStreamControlEvent:
</t>
<figure>
<artwork><![CDATA[
object {
[String control-uri;]
[String remove<1..*>;]
} UpdateStreamControlEvent;
]]></artwork>
</figure>
<t>
The "control-uri" field is the URI of the Stream Control
resource for this Update Stream
(<xref target="UpdateStreamControlService"/>).
The ALTO server MUST send a control event with that
URI as the first event in an Update Stream.
</t>
<t>
The "remove" field is a list of client-ids of resources
for which the server will no longer send updates.
The server sends this event after processing
the client's Stream Control request to remove
those resources (<xref target="UpdateStreamService.Response.Sequence"/>).
</t>
</section>
</section>
<section title="Update Stream Service" anchor="UpdateStreamService">
<t>
An Update Stream Service returns a stream of SSE messages,
as defined in <xref target="ALTO.SSE.Events"/>.
An Update Stream resource is used to request a new Update Stream.
</t>
<t>
A server creates an Update Stream Control resource
for each active Update Stream. A client uses
the control resource to remove resources
from the Update Stream instance,
or to request updates for additional resources.
Update Stream resources are listed in the server's IRD,
but Stream Control resources are not. Instead, the
first event that the server sends to the client
has the URI for the Update Stream Control resource
for that stream (see <xref target="ALTO.SSE.ControlEvents"/>.
</t>
<t>
<xref target="UpdateStreamControlService"/> describes
the Update Stream Control Service.
</t>
<section title="Media Type">
<t>
The media type of an ALTO Update Stream resource is "text/event-stream".
</t>
</section>
<section title="HTTP Method">
<t>
An ALTO Update Stream resource is
requested using the HTTP POST method.
</t>
</section>
<section title="Accept Input Parameters" anchor="UpdateInput.media-type">
<t>
An ALTO Client supplies the Update Stream resource
parameters by specifying media type
"application/alto-updatestreamparams+json" with an HTTP POST body
containing a JSON Object of type UpdateStreamReq, where:
</t>
<figure>
<artwork><![CDATA[
object {
[AddUpdatesReq add;]
[ClientId remove<0..*>;]
} UpdateStreamReq;
object-map {
ClientId -> AddUpdateReq;
} AddUpdatesReq;
object {
String resource-id;
[String tag;]
[Boolean incremental-updates;]
[Object input;]
} AddUpdateReq;
]]></artwork>
</figure>
<t>
The "add" field specifies the resources for which
the client wants updates, and has one entry
for each resource. The client creates a unique client-id
(<xref target="ALTO.SSE.EventFormat"/>)
for each such resource, and uses those client-ids
as the keys in the "add" field.
</t>
<t>
An Update Stream request
MUST have an "add" field specifying one or more resources.
If it does not, the server MUST return an E_INVALID_FIELD_VALUE
error response (see Section 8.5.2 of <xref target="RFC7285"/>),
and MUST close the stream without sending any events.
</t>
<t>
The "resource-id" field is the resource-id of an ALTO resource,
and MUST be in the Update Streams's "uses" list
(see <xref target="UpdateStreamService.Uses"/>).
If any resource-id is invalid, or is not associated with this Update Stream,
the server MUST return an E_INVALID_FIELD_VALUE
error response (see Section 8.5.2 of <xref target="RFC7285"/>),
and MUST close the stream without sending any events.
</t>
<t>
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 <xref target="RFC7285"/>,
and if the client has previously retrieved
a version of that resource from the server,
the client MAY set the "tag" field to "tag" part
of the resource's version tag.
If that version is still current, the ALTO Server SHOULD omit sending
a full replacement update at the start of the stream
(see <xref target="UpdateStreamService.Response.Sequence"/>).
If that version is not current, the server MUST ignore the "tag" field.
</t>
<t>
If the "incremental-updates" field for a resource-id is "true",
the server MAY send incremental update events for this resource-id
(assuming the server supports incremental updates for that resource;
see <xref target="UpdateStreamService.Capabilities"/>).
If the "incremental-updates" field is "false",
the ALTO Server MUST NOT send incremental update events for that resource.
In this case, whenever a change occurs,
the server MUST send a full-replacement
update instead of an incremental update.
The ALTO Server SHOULD send the full-replacement message
soon after the change,
although the server MAY wait until more changes are available.
Thus an ALTO Client which declines to accept incremental updates
may not get updates as quickly as a client which does.
</t>
<t>
The default for "incremental-updates" is "true",
so to suppress incremental updates,
the client MUST explicitly set "incremental-updates" to "false".
Note that the client cannot suppress full-replacement update events.
</t>
<t>
If the resource is a POST-mode service which requires input,
the client MUST set the "input" field to a JSON Object
with the parameters that resource expects.
If the "input" field is missing or invalid,
the ALTO Server MUST return the same error response
that that resource would return for missing or invalid input
(see <xref target="RFC7285"/>).
In this case, the server MUST close the Update Stream
without sending any events.
If the inputs for several POST-mode resources are missing or invalid,
the server MUST pick one error response and return it.
</t>
<t>
The "remove" field is used by the Update Stream Control Service
<xref target="UpdateStreamControlService"/>,
and is not allowed in the Update Stream request.
If the "remove" field exists,
the server MUST return an E_INVALID_FIELD_VALUE
error response (see Section 8.5.2 of <xref target="RFC7285"/>),
and MUST close the stream without sending any events.
</t>
</section>
<section title="Capabilities" anchor="UpdateStreamService.Capabilities">
<t>
The capabilities are defined by an object of type UpdateStreamCapabilities:
</t>
<figure>
<artwork><![CDATA[
object {
IncrementalUpdateMediaTypes incremental-update-media-types;
} UpdateStreamCapabilities;
object-map {
ResourceID -> String;
} IncrementalUpdateMediaTypes;
]]></artwork>
</figure>
<t>
If this Update Stream can provide incremental update events
for a resource, the "incremental-update-media-types" field
has an entry for that resource-id, and the value is the
media-type of the incremental update message.
Normally this will be "application/merge-patch+json",
because, as described in <xref target="ALTO.SSE.Events"/>,
JSON Merge Patch is the only incremental update event type defined by this document.
However future extensions may define other types of incremental updates.
</t>
</section>
<section title="Uses" anchor="UpdateStreamService.Uses">
<t>
The "uses" attribute MUST be an array with the resource-ids of every resource
for which this stream can provide updates.
</t>
<t>
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 select 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.
</t>
</section>
<section title="Response" anchor="UpdateStreamService.Response">
<t>
The response is a stream of SSE update events.
<xref target="ALTO.SSE.Events"/> defines the events,
and <xref target="SSE"/> defines how they are encoded into a stream.
</t>
<t>
An ALTO server SHOULD send updates only when the underlying values change.
However, it may be difficult for a server to guarantee that
in all circumstances. Therefore a client MUST NOT assume
that an SSE update event represents an actual change.
</t>
<t>
There are additional requirements on the server's response, as described below.
</t>
<section title="Keep-Alive Messages" anchor="UpdateStreamService.keep-alive">
<t>
In an SSE stream, any line which starts with a colon (U+003A) character
is a comment, and an ALTO Client MUST ignore that line (<xref target="SSE"/>).
As recommended in <xref target="SSE"/>,
an ALTO Server SHOULD send a comment line (or an event) every 15 seconds
to prevent clients and proxy servers from dropping the HTTP connection.
</t>
</section>
<section title="Event Sequence Requirements" anchor="UpdateStreamService.Response.Sequence">
<t>
<list style="symbols">
<t>
The first event MUST be a control event with
the URI of the Stream Control resource
(<xref target="UpdateStreamControlService"/>)
for this Update Stream (<xref target="ALTO.SSE.ControlEvents"/>).
</t>
<t>
As soon as possible after the client initiates the connection,
the ALTO Server MUST send a full-replacement update event
for each resource-id requested by the client.
The only exception is for a GET-mode resource with a version tag:
the server MAY omit the initial full-replacement event for that resource
if the "tag" field the client provided for that resource-id
matches the tag of the server's current version.
</t>
<t>
If this stream provides updates for resource-ids R0 and R1,
and if R1 depends on R0,
then the ALTO Server MUST send the update for R0
before sending the related update for R1.
For example, suppose a stream provides updates
to a Network Map and its dependent Cost Maps.
When the Network Map changes, the ALTO Server MUST
send the Network Map update
before sending the Cost Map updates.
</t>
<t>
If this stream provides updates for resource-ids R0 and R1,
and if R1 depends on R0,
then the ALTO Server SHOULD send an update for R1
as soon as possible after sending the update for R0.
For example, when a Network Map changes, the ALTO Server SHOULD
send update events for the dependent Cost Maps
as soon as possible after the update event for the Network Map.
</t>
<t>
When the client uses the Control Stream resource
to stop updates for one or more resources
<xref target="UpdateStreamControlService"/>,
the ALTO Server MUST send a control event
(<xref target="ALTO.SSE.ControlEvents"/>)
whose "remove" field has the client-ids of those resources.
If the client uses the Control Stream resource
to terminate all active resources and close the stream,
the server MUST send a control event
whose "remove" field has the client-ids of all active resources.
</t>
</list>
</t>
</section>
<section title="Cross-Stream Consistency Requirements">
<t>
If several clients create Update Streams
for updates to the same resource,
the server MUST send the same updates to all of them.
However, the server MAY pack data items into different Merge Patch events,
as long as the net result of applying those updates is the same.
</t>
<t>
For example, suppose two different clients
create Update Streams for the same Cost Map,
and suppose the ALTO 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 server MAY send a single Merge Patch event
(with all three cost points) to one client,
while sending three separate Merge Patch events
(with one cost point per event) to the other client.
</t>
<t>
A 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 data.
</t>
</section>
</section>
</section>
<section title="Update Stream Control Service" anchor="UpdateStreamControlService">
<t>
The Update Stream Control Service allows a client
to remove resources from the set of resources that
are monitored by an Update Stream, or add additional resources
to that set. The Control Service also allows a client
to gracefully shutdown an Update Stream.
</t>
<t>
The Update Stream Control Service is not listed in
the ALTO Server's IRD. Instead, when a client requests
a new Update Stream, the server creates a new Update Stream
Control resource for that stream, and sends
its URI to the client as the first event in the Update Stream
(<xref target="UpdateStreamService.Response.Sequence"/>).
</t>
<t>
As described below, each control request adds resources
to the set of monitored resources,
or removes previously added resources, or does both.
Each control request is a separate HTTP request;
the client MAY NOT stream multiple control requests
in one HTTP request. However, if the client and server
support HTTP Keep-Alive (<xref target="RFC2616"/>),
the client MAY send multiple HTTP requests
on the same TCP/IP connection.
</t>
<section title="URI">
<t>
The URI for a Stream Control resource, by itself,
MUST uniquely specify the
Update Stream instance which it controls.
The 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, a server MUST NOT re-use a Control Stream URI
once the associated Update Stream has been closed.
</t>
<t>
The client MUST evaluate a non-absolute Stream Control URI
(for example, a URI without a host, or with a relative path)
in the context of the URI used to create the Update Stream.
If a Stream Control URI has an explicit host,
it may be different from the Update Stream's host.
</t>
<t>
It is expected that the server will assign
a unique stream id to each Update Stream instance,
and will embed that id in the associated Control Stream URI.
However, the exact mechanism is left to the server.
Clients MUST NOT attempt to deduce a stream id
from the Control Stream URI.
</t>
</section>
<section title="Media Type">
<t>
An ALTO Update Stream Control resource does not have
a specific media type. If a request is successful,
the server returns an HTTP "200 OK" response
with Content-Type "text/plain" and no data.
If a request is unsuccessful, the server returns
an ALTO error response (Section 8.5.2 of <xref target="RFC7285"/>)
</t>
</section>
<section title="HTTP Method">
<t>
An ALTO Update Stream Control resource is
requested using the HTTP POST method.
</t>
</section>
<section title="Accept Input Parameters" anchor="ControlStream.media-type">
<t>
A Stream Control resource accepts the same input media
type and input parameters as the Update Stream Service
(<xref target="UpdateInput.media-type"/>).
The only difference is that a Stream Control resource
also accepts the "remove" field.
</t>
<t>
If specified, the "remove" field is an array of client-ids
the client previously added to this Update Stream.
An empty "remove" array is equivalent to a list
of all currently active resources; the server responds
by removing all resources and closing the stream.
</t>
<t>
A client MAY use the "add" field to add additional resources.
However, the client MUST assign a unique client-id to each
resource. Client-ids MUST be unique over the lifetime
of this Update Stream: a client MUST NOT re-use
a previously removed client-id.
</t>
<t>
If a request has any error,
the server MUST NOT add or remove any resources
from the associated Update Stream.
In particular,
<list style="symbols">
<t>
Each "add" request must satisfy the requirements
in <xref target="UpdateInput.media-type"/>.
If not, the server MUST return the error response
defined in <xref target="UpdateInput.media-type"/>.
</t>
<t>
The server MUST return an E_INVALID_FIELD_VALUE error
if a client-id in the "remove" field
was not added in a prior request.
Thus it is illegal to "add" and "remove"
the same client-id in the same request.
However, it is legal to remove a client-id twice.
</t>
<t>
The server MUST return an E_INVALID_FIELD_VALUE error
if a client-id in the "add" field has
been used before in this stream.
</t>
<t>
The server MUST return an E_INVALID_FIELD_VALUE error
if the request has a non-empty "add" field
and a "remove" field with an empty list of client-ids
(to replace all active resources with a new set,
the client MUST explicitly enumerate the
client-ids to be removed).
</t>
<t>
If the associated Update Stream has been closed,
the server MUST return either an ALTO E_INVALID_FIELD_VALUE
error, or else an HTTP error, such as "404 Not Found".
</t>
</list>
</t>
</section>
<section title="Capabilities & Uses">
<t>
None (Control Stream Services do not appear in the IRD).
</t>
</section>
<section title="Response" anchor="ControlStream.Response">
<t>
If a request is successful,
the server returns an HTTP "200 OK" response
with Content-Type "text/plain" and no data.
If there are any errors,
the server MUST return the appropriate error code,
and MUST NOT add or remove any resources from the Update Stream.
Thus control requests are atomic: they cannot partially succeed.
</t>
<t>
The server MUST process the "add" field before the "remove" field.
If the request removes all active resources
without adding any additional resources,
the server MUST close the Update Stream.
Thus an Update Stream cannot have zero resources.
</t>
<t>
Whenever a server removes resources as a result
of a Stream Control request, the server MUST
send the corresponding "remove" Control Events
(<xref target="ALTO.SSE.ControlEvents"/>)
on the Update Stream.
If one control request removes several resources,
the server MAY send one Control Event for all those resources,
or a separate event for each removed resource,
or any combination thereof.
</t>
</section>
</section>
<section title="Examples" anchor="Examples">
<section title="Example: Simple Network and Cost Map Updates">
<t>
Here is an example of a client's request and the server's immediate response,
using the Update Stream resource "update-my-costs"
defined in the IRD in <xref target="IRD.example"/>.
The client requests updates for the Network Map and
"routingcost" Cost Map, but not for the "hopcount" Cost Map.
The client uses the server's resource-ids as the client-ids.
Because the client does not provide a "tag" for the Network Map,
the server must send a full update for the Network Map
as well as for the Cost Map.
The client does not set "incremental-updates" to "false",
so it defaults to "true".
Thus server will send Merge Patch updates for the Cost Map,
but not for the Network Map, because this Update Stream resource
does not provide incremental updates for the Network Map.
</t>
<figure>
<artwork><![CDATA[
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: ###
{ "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: "http://alto.example.com/updates/streams/3141592653589"}
event: application/alto-networkmap+json,my-network-map
data: { ... full Network Map message ... }
event: application/alto-costmap+json,my-routingcost-map
data: { ... full routinccost Cost Map message ... }
]]></artwork>
</figure>
<t>
After sending those events immediately,
the ALTO Server will send additional events
as the maps change. For example, the following
represents a small change to the Cost Map:
</t>
<figure>
<artwork><![CDATA[
event: application/merge-patch+json,my-routingcost-map
data: {"cost-map": {"PID1" : {"PID2" : 9}}}
]]></artwork>
</figure>
<t>
If a major change to the Network Map occurs,
the ALTO Server MAY choose to send
full Network and Cost Map messages
rather than Merge Patch messages:
</t>
<figure>
<artwork><![CDATA[
event: application/alto-networkmap+json,my-network-map
data: { ... full Network Map message ... }
event: application/alto-costmap+json,my-routingcost-map
data: { ... full Cost Map message ... }
]]></artwork>
</figure>
</section>
<section title="Example: Advanced Network and Cost Map Updates">
<t>
This example is similar to the previous one,
except that the 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 server is not required to send
the full Network Map update event
at the beginning of the stream.
In this example, the client uses the client-ids "net",
"routing" and "hops" for those resources.
The ALTO Server sends the stream id and the full Cost Maps,
followed by updates for the Network Map
and Cost Maps as they become available:
</t>
<figure>
<artwork><![CDATA[
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: ###
{ "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: "http://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}}}
]]></artwork>
</figure>
<t>
If the client wishes to stop receiving updates for the "hopcount"
Cost Map, the client can send a "remove" request
on the Stream Control URI:
</t>
<figure>
<artwork><![CDATA[
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: ###
{
"remove": [ "hops" ]
}
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/plain
Content-Length: 0
(stream closed without sending data content)
]]></artwork>
</figure>
<t>
The ALTO Server sends a "remove" control event on the
original request stream to inform the client
that updates are stopped for that resource:
</t>
<figure>
<artwork><![CDATA[
event: application/alto-updatestreamcontrol+json
data: { "remove": ["hops"] }
]]></artwork>
</figure>
<t>
If the 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:
</t>
<figure>
<artwork><![CDATA[
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: ###
{
"remove": [ ]
}
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/plain
Content-Length: 0
(stream closed without sending data content)
]]></artwork>
</figure>
<t>
The ALTO Server sends a final "remove" control event on the
original request stream to inform the client
that all updates are stopped, and then closes the stream:
</t>
<figure>
<artwork><![CDATA[
event: application/alto-updatestreamcontrol+json
data: { "remove": ["net", "routing"] }
(server closes stream)
]]></artwork>
</figure>
</section>
<section title="Example: Endpoint Property Updates">
<t>
As another example, here is how a client can request updates
for the property "priv:ietf-bandwidth" for one set of endpoints,
and "priv:ietf-load" for another.
The ALTO Server immediately sends full-replacement messages
with the property values for all endpoints.
After that, the server sends update events
for the individual endpoints as their property values change.
</t>
<figure>
<artwork><![CDATA[
POST /updates/properties HTTP/1.1
Host: alto.example.com
Accept: text/event-stream
Content-Type: application/alto-updatestreamparams+json
Content-Length: ###
{ "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" : [
"ipv4:198.51.100.31",
"ipv4:198.51.100.32",
"ipv4:198.51.100.33"
]
}
},
}
}
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/event-stream
event: application/alto-updatestreamcontrol+json
data: {"control-uri":
data: "http://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: "ipv4:198.51.100.31" : { "priv:ietf-load": "8" },
data: "ipv4:198.51.100.32" : { "priv:ietf-load": "2" },
data: "ipv4:198.51.100.33" : { "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: {"ipv4:198.51.100.33" : {"priv:ietf-load": "7"}}
data: }
]]></artwork>
</figure>
</section>
<section title="IRD Example" anchor="IRD.example">
<t>
Here is an example of an IRD that offers two
Update Stream services.
The first provides updates for the Network Map,
the "routingcost" and "hopcount" Cost Maps,
and a Filtered Cost Map resource.
The second Update Stream provides updates to the Endpoint Properties service.
</t>
<t>
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 <xref target="UpdateStreamService.FCMConsiderations"/>,
the Update Stream provides updates for the second,
but not the first.
</t>
<figure>
<artwork><![CDATA[
"my-network-map": {
"uri": "http://alto.example.com/networkmap",
"media-type": "application/alto-networkmap+json",
},
"my-routingcost-map": {
"uri": "http://alto.example.com/costmap/routingcost",
"media-type": "application/alto-costmap+json",
"uses": ["my-networkmap"],
"capabilities": {
"cost-type-names": ["num-routingcost"]
}
},
"my-hopcount-map": {
"uri": "http://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": "http://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": "http://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": "http://alto.example.com/properties",
"media-type": "application/alto-endpointprops+json",
"accepts": "application/alto-endpointpropparams+json",
"capabilities": {
"prop-types": ["priv:ietf-bandwidth"]
}
},
"update-my-costs": {
"uri": "http://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-update-media-types": {
"my-routingcost-map": application/merge-patch+json",
"my-hopcount-map": "application/merge-patch+json"
}
}
},
"update-my-props": {
"uri": "http://alto.example.com/updates/properties",
"media-type": "text/event-stream",
"uses": [ "my-props" ],
"accepts": "application/alto-updatestreamparams+json",
"capabilities": {
"incremental-update-media-types": {
"my-props": "application/merge-patch+json"
}
}
}
]]></artwork>
</figure>
</section>
</section>
<section title="Client Actions When Receiving Update Messages" anchor="ClientActions">
<t>
In general, when a client receives a full-replacement update message
for a resource, the client should replace the current version
with the new version.
When a client receives a Merge Patch update message
for a resource, the client should apply those patches
to the current version of the resource.
</t>
<t>
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 a client can do that.
We will illustrate these techniques by referring to Network and Cost Map messages,
although these techniques apply to any dependent resources.
</t>
<t>
Note that when a Network Map changes,
the ALTO Server MUST send the Network Map update message
before sending the updates for the dependent Cost Maps
(see <xref target="UpdateStreamService.Response.Sequence"/>).
</t>
<t>
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 client receives the update messages
for all dependent Cost Maps.
The client then applies all Network and Cost Map updates atomically.
</t>
<t>
Alternatively, the client MAY update the Network Map immediately.
In this case, the client MUST mark each dependent Cost Map as
temporarily invalid, and MUST NOT use that map
until the client receives a Cost Map update message
with the new Network Map version tag.
Note that the client MUST NOT delete the Cost Maps,
because the server may send Merge Patch update messages.
</t>
<t>
The ALTO Server SHOULD send updates for dependent resources in a timely fashion.
However, if the client does not receive the expected updates,
the client MUST close the Update Stream connection,
discard the dependent resources,
and reestablish the Update Stream.
The 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 ALTO Server
will not re-send that resource.
</t>
<t>
Although not as efficient as possible, this recovery method is simple and reliable.
</t>
</section>
<section title="Design Decisions and Discussions" anchor="DesignDecisions">
<section title="HTTP2 Server-Push">
<t>
An alternative would be to use HTTP 2 Server-Push
<xref target="RFC7540"/>,
instead of SSE over HTTP 1.1,
as the transport mechanism for update messages.
That would have several advantages:
HTTP 2 Server-Push is designed to allow a server
to send asynchronous messages to the client,
and HTTP library packages should make it simple
for servers to send those asynchronous messages,
and for clients to receive them.
</t>
<t>
The disadvantage is HTTP 2 is a new protocol,
and it is considerably more complicated than HTTP 1.1.
While there is every reason to expect that HTTP library packages
will eventually support HTTP 2, we do not want to delay
deployment of an ALTO incremental update mechanism
until that time.
</t>
<t>
Hence we have chosen to base ALTO updates on HTTP 1.1 and SSE.
When HTTP 2 support becomes ubiquitous,
a future extension of this document may define updates via HTTP 2 Server-Push.
</t>
</section>
<section title="Not Allowing Stream Restart">
<t>
If an update stream is closed accidentally,
when the client reconnects, the server must
resend the full maps.
This is clearly inefficient.
To avoid that inefficiency,
the SSE specification allows a server to assign an id
to each event. When a client reconnects,
the client can present the id of the last successfully
received event, and the server restarts with the
next event.
</t>
<t>
However, that mechanism adds additional complexity.
The server must save SSE messages in a buffer,
in case clients reconnect.
But that mechanism will never be perfect:
if the client waits too long to reconnect,
or if the client sends an invalid id,
then the server will have to resend the complete maps anyway.
</t>
<t>
Furthermore, this is unlikely to be a problem in practice.
Clients who want continuous updates for large resources,
such as full Network and Cost Maps,
are likely to be things like P2P trackers.
These clients will be well connected to the network;
they will rarely drop connections.
</t>
<t>
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 ALTO Server will have to retransmit only a small amount
of redundant data.
</t>
<t>
In short, using event ids to avoid resending the full map
adds a considerable amount of complexity to avoid a situation which
we expect is very rare. We believe that complexity
is not worth the benefit.
</t>
<t>
The Update Stream service does allow the client
to specify the tag of the last received version of any tagged
resource, and if that is still current, the server need not
retransmit the full resource.
Hence 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.
</t>
</section>
<section title="Is Incremental Update Useful for Network Maps?" anchor="IncrUpdForNetworkMaps">
<t>
It is not clear whether incremental updates (that is, Merge Patch updates)
are useful for Network Maps. For minor changes, such as moving a prefix
from one PID to another, they can be useful. But more involved changes
to the Network Map are likely to be "flag days": they represent a completely
new Network Map, rather than a simple, well-defined change.
</t>
<t>
At this point we do not have sufficient experience with ALTO deployments
to know how frequently Network Maps will change,
or how extensive those changes will be.
For example, suppose a link goes down and the network uses an alternative route.
This is a frequent occurrence.
If an ALTO Server models that by moving prefixes from one PID to another,
then Network Maps will change frequently.
However, an ALTO Server might model that
as a change in costs between PIDs,
rather than a change in the PID definitions.
If a server takes that approach,
simple routing changes will affect Cost Maps,
but not Network Maps.
</t>
<t>
So while we allow a server to use Merge Patch on Network Maps,
we do not require the server to do so.
Each server may decide on its own whether to use Merge Patch for Network Maps.
</t>
<t>
This is not to say that Network Map updates are not useful.
Clearly Network Maps will change, and update events are necessary
to inform clients of the new map. Further, there maybe another incremental
update encoding that is better suited for updating Networks Maps;
see the discussions in the next section.
</t>
</section>
<section title="Other Incremental Update Message Types">
<t>
Other JSON-based incremental update formats have been defined,
in particular JSON Patch (<xref target="RFC6902"/>).
The update events defined in this document
have the media-type of the update data.
JSON Patch has its own media type ("application/json-patch+json"),
so this update mechanism could easily be extended to allow
servers to use JSON Patch for incremental updates.
</t>
<t>
However, we think that JSON Merge Patch is clearly superior
to JSON Patch for describing incremental updates 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; we see no advantage to allowing
a server to use JSON Patch for those resources.
</t>
<t>
The case is not as clear for incremental updates to Network Maps.
For example, suppose a prefix moves from one PID to another.
JSON Patch could encode that as a simple insertion and deletion,
while 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 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,
clients would have to retain additional, otherwise unnecessary, data.
</t>
<t>
However, it is entirely possible that JSON Patch will be appropriate for
describing incremental updates to new, as yet undefined ALTO resources.
In this case, the extensions defining those new resources
can use the update framework defined in this document,
but recommend using JSON Patch, or some other method,
to describe the incremental changes.
</t>
</section>
</section>
<section title="Miscellaneous Considerations" anchor="MiscConsiderations">
<section title="Considerations For Updates To Filtered Cost Maps"
anchor="UpdateStreamService.FCMConsiderations">
<t>
If an Update Stream provides updates to a Filtered Cost Map
which allows constraint tests, then a client MAY request updates
to a Filtered Cost Map request with a constraint test.
In this case, when a cost changes,
the server MUST send an update if the new value satisfies the test.
If the new value does not,
whether the server sends an update depends
on whether the previous value satisfied the test.
If it did not, the server SHOULD NOT send an update to the client.
But if the previous value did, then the server MUST send
an update with a "null" value,
to inform the client that this cost no longer satisfies the criteria.
</t>
<t>
An ALTO Server can avoid such issues
by offering Update Streams only for Filtered Cost Maps
which do not allow constraint tests.
</t>
</section>
<section title="Considerations For Incremental Updates To Ordinal Mode Costs"
anchor="UpdateStreamService.OrdinalConsiderations">
<t>
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 a server to offer incremental updates
for ordinal mode cost maps, server implementors should be aware
that incremental updates for ordinal costs are more complicated
than for numerical costs, and clients should be aware that
small changes may result in large updates.
</t>
<t>
An ALTO Server can avoid this complication
by only offering full replacement updates for ordinal cost maps.
</t>
</section>
<section title="Considerations Related to SSE Line Lengths"
anchor="UpdateStreamService.SSELineLengthConsiderations">
<t>
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 full cost maps as single events,
and a cost map may involve megabytes, if not tens of megabytes, of text.
This has implications for both the ALTO Server and Client.
</t>
<t>
First, SSE clients might not be able to handle a multi-megabyte data "line".
Hence when sending a full network map or cost map,
an ALTO server SHOULD insert a new-line character periodically.
Approximately every 2,000 characters should be sufficient
for most SSE clients.
</t>
<t>
Second, some SSE client packages read all the data for an event
into memory, and then present it to the client as a single character array.
However, a client computer 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
which presents the event data in manageable chunks,
so the client can parse the cost map incrementally
and store the underlying data in a more compact format.
</t>
</section>
</section>
<section title="Security Considerations" anchor="Security">
<section title="Denial-of-Service Attacks">
<t>
Allowing persistent update stream connections
enables a new class of Denial-of-Service attacks.
A client might create an unreasonable number
of update stream connections,
or add an unreasonable number of client-ids
to one update stream.
To avoid those attacks, an ALTO Server MAY choose
to limit the number of active streams,
and reject new requests when that threshold is reached.
A server MAY also chose to limit the number of active
client-ids on any given stream, or limit the total
number of client-ids used over the lifetime of a stream,
and reject any stream control request
which would exceed those limits.
In these cases, the server SHOULD return
the HTTP status "503 Service Unavailable".
</t>
<t>
While this technique prevents Update Stream DoS attacks from disrupting
an ALTO Server's other services, it does make it easier
for a DoS attack to disrupt the Update Stream service.
Therefore a server may prefer to restrict Update Stream
services to authorized clients, as discussed in Section 15
of <xref target="RFC7285"/>.
</t>
<t>
Alternatively an ALTO Server MAY return
the HTTP status "307 Temporary Redirect"
to redirect the client to another ALTO Server
which can better handle a large number of update streams.
</t>
</section>
<section title="Spoofed Control Requests">
<t>
An outside party which can read the update stream response
can obtain the control URI and use that
to send a fraudulent "remove" requests,
thus disabling updates for the valid client.
This can be avoided by encrypting the stream
(see Section 15 of <xref target="RFC7285"/>).
Also, the ALTO Server echoes the "remove" requests
on the update stream, so the valid client can detect
unauthorized requests.
</t>
</section>
<section title="Privacy">
<t>
This extension does not introduce any privacy issues
not already present in the ALTO protocol.
</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>
This document defines two new media-types,
"application/alto-updatestreamparams+json",
as described in <xref target="UpdateInput.media-type"/>,
and "application/alto-updatestreamcontrol+json",
as described in <xref target="ALTO.SSE.ControlEvents"/>.
All other media-types used in this document have already been registered,
either for ALTO or JSON Merge Patch.
</t>
<t>
<list style="hanging" hangIndent="3">
<t hangText="Type name:">application</t>
<t hangText="Subtype name:">alto-updatestreamparams+json</t>
<t hangText="Required parameters:">n/a</t>
<t hangText="Optional parameters:">n/a</t>
<t hangText="Encoding considerations:">Encoding considerations are
identical to those specified for the "application/json" media type. See
<xref target="RFC7159" />.</t>
<t hangText="Security considerations:">Security considerations relating
to the generation and consumption of ALTO Protocol messages are
discussed in <xref target="Security"/> of this document
and Section 15 of <xref target="RFC7285"/>.</t>
<t hangText="Interoperability considerations:">This document specifies
format of conforming messages and the interpretation thereof.</t>
<t hangText="Published specification:"><xref target="UpdateInput.media-type"/>
of this document.</t>
<t hangText="Applications that use this media type:">ALTO servers and
ALTO clients either stand alone or are embedded within other
applications.</t>
<t hangText="Additional information:">
<list style="hanging" hangIndent="3">
<t hangText="Magic number(s):">n/a</t>
<t hangText="File extension(s):">This document uses the mime type
to refer to protocol messages and thus does not require a file
extension.</t>
<t hangText="Macintosh file type code(s):">n/a</t>
</list>
</t>
<t hangText="Person & email address to contact for further information:">
See Authors' Addresses section.</t>
<t hangText="Intended usage:">COMMON</t>
<t hangText="Restrictions on usage:">n/a</t>
<t hangText="Author:">See Authors' Addresses section.</t>
<t hangText="Change controller:">Internet Engineering Task Force (mailto:iesg@ietf.org).</t>
</list>
</t>
<t>
<list style="hanging" hangIndent="3">
<t hangText="Type name:">application</t>
<t hangText="Subtype name:">alto-updatestreamcontrol+json</t>
<t hangText="Required parameters:">n/a</t>
<t hangText="Optional parameters:">n/a</t>
<t hangText="Encoding considerations:">Encoding considerations are
identical to those specified for the "application/json" media type. See
<xref target="RFC7159" />.</t>
<t hangText="Security considerations:">Security considerations relating
to the generation and consumption of ALTO Protocol messages are
discussed in <xref target="Security"/> of this document
and Section 15 of <xref target="RFC7285"/>.</t>
<t hangText="Interoperability considerations:">This document specifies
format of conforming messages and the interpretation thereof.</t>
<t hangText="Published specification:"><xref target="ALTO.SSE.ControlEvents"/>
of this document.</t>
<t hangText="Applications that use this media type:">ALTO servers and
ALTO clients either stand alone or are embedded within other
applications.</t>
<t hangText="Additional information:">
<list style="hanging" hangIndent="3">
<t hangText="Magic number(s):">n/a</t>
<t hangText="File extension(s):">This document uses the mime type
to refer to protocol messages and thus does not require a file
extension.</t>
<t hangText="Macintosh file type code(s):">n/a</t>
</list>
</t>
<t hangText="Person & email address to contact for further information:">
See Authors' Addresses section.</t>
<t hangText="Intended usage:">COMMON</t>
<t hangText="Restrictions on usage:">n/a</t>
<t hangText="Author:">See Authors' Addresses section.</t>
<t hangText="Change controller:">Internet Engineering Task Force (mailto:iesg@ietf.org).</t>
</list>
</t>
</section>
</middle>
<back>
<references>
<!--
<reference anchor="RFC5226">
<front>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author initials="T." surname="Narten" fullname="T. Narten"/>
<author initials="H." surname="Alvestrand" fullname="H. Alvestrand"/>
<date month="May" year="2008"/>
</front>
<seriesInfo name="RFC" value="5226" />
<seriesInfo name="BCP" value="26" />
</reference>
-->
<reference anchor='RFC2119'>
<front>
<title abbrev='HTTP'>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner' />
<date year='1997' month='March' />
</front>
<seriesInfo name='RFC' value='2119' />
<seriesInfo name='BCP' value='14' />
<format type='TXT' target='http://www.rfc-editor.org/rfc/rfc2119.txt' />
</reference>
<reference anchor='RFC2616'>
<front>
<title abbrev='HTTP'>Hypertext Transfer Protocol -- HTTP/1.1</title>
<author initials='R.' surname='Fielding' fullname='N. Freed' />
<author initials='J.' surname='Gettys' fullname='J. Gettys' />
<author initials='J.' surname='Mogul' fullname='J. Mogul' />
<author initials='H.' surname='Frystyk' fullname='H. Frystyk' />
<author initials='L.' surname='Masinter' fullname='L. Masinter' />
<author initials='P.' surname='Leach' fullname='P. Leach' />
<author initials='T.' surname='Burners-Lee' fullname='T. Burners-Lee' />
<date year='1999' month='June' />
</front>
<seriesInfo name='RFC' value='2616' />
<format type='TXT' target='http://www.rfc-editor.org/rfc/rfc2616.txt' />
</reference>
<reference anchor="RFC5789">
<front>
<title>PATCH Method for HTTP</title>
<author initials="L." surname="Dusseault" fullname="L. Dusseault"/>
<author initials="J." surname="Snell" fullname="J. Snell"/>
<date month="March" year="2010"/>
</front>
<seriesInfo name="RFC" value="5789" />
</reference>
<reference anchor="RFC6902">
<front>
<title abbrev='JSON-Patch'>JavaScript Object Notation (JSON) Patch</title>
<author initials='P.' surname='Bryan' fullname='P. Bryan' />
<author initials='M.' surname='Nottingham' fullname='M. Nottingham' />
<date year='2013' month='April' />
</front>
<seriesInfo name='RFC' value='6902' />
<format type='TXT' target='http://www.rfc-editor.org/rfc/rfc6902.txt' />
</reference>
<reference anchor="RFC7159">
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials="T." surname="Bray" fullname="T. Bray"/>
<date month="March" year="2014"/>
</front>
<seriesInfo name="RFC" value="7159" />
</reference>
<reference anchor="RFC7285">
<front>
<title>Application-Layer Traffic Optimization (ALTO) Protocol</title>
<author initials="R." surname="Almi" fullname="R. Alimi"/>
<author initials="R." surname="Penno" fullname="R. Penno"/>
<author initials="Y." surname="Yang" fullname="Y. Yang"/>
<author initials="S." surname="Kiesel" fullname="S. Kiesel"/>
<author initials="S." surname="Previdi" fullname="S. Previdi"/>
<author initials="W." surname="Roome" fullname="W. Roome"/>
<author initials="S." surname="Shalunov" fullname="S. Shalunov"/>
<author initials="R." surname="Woundy" fullname="R. Woundy"/>
<date month="September" year="2014"/>
</front>
<seriesInfo name="RFC" value="7285" />
</reference>
<reference anchor="RFC7386">
<front>
<title>JSON Merge Patch</title>
<author initials="P." surname="Hoffman" fullname="P. Hoffman"/>
<author initials="J." surname="Snell" fullname="J. Snell"/>
<date month="October" year="2014"/>
</front>
<seriesInfo name="RFC" value="7386" />
</reference>
<reference anchor="RFC7540">
<front>
<title>Hypertext Transfer Protocol Version 2 (HTTP/2)</title>
<author initials="M." surname="Belshe" fullname="M. Belshe"/>
<author initials="R." surname="Peon" fullname="R. Peon"/>
<author initials="M." surname="Thomson" fullname="M. Thomson"/>
<date month="May" year="2015"/>
</front>
<seriesInfo name="RFC" value="7540" />
</reference>
<reference anchor="SSE">
<front>
<title>Server-Sent Events (W3C)</title>
<author initials="I." surname="Hickson" fullname="Ian Hickson"/>
<date day="03" month="February" year="2015"/>
</front>
<seriesInfo name="W3C Recommendation" value="03 February 2015"/>
<!-- http://www.w3.org/TR/eventsource/ -->
</reference>
</references>
<section anchor="Acknowledgments" title="Acknowledgments">
<t>Thank you to Xiao Shi (Yale University) for his contributions to an earlier version of this document.</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 06:04:12 |