One document matched: draft-roome-alto-incr-update-sse-01.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-roome-alto-incr-update-sse-01"
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="Alcatel-Lucent">Alcatel-Lucent/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>w.roome@alcatel-lucent.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>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="January" day="30" year="2015"/>
<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 a client to obtain updates to those maps,
other than by periodically re-fetching them.
Because the maps may be very 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 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. Network Maps partition the set
of endpoints into a manageable number of Provider-Defined Identifiers (PIDs),
and Cost Maps provide 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 very 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 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,
an ALTO Server can use the mechanisms defined in this document
to 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>
Section 2 gives an overview of the incremental update approach,
which is based on Server-Sent Events (SSEs).
Section 3 defines the update events,
and Section 4 defines the format of the incremental update messages.
Sections 5 and 6 define two new Update Stream Services.
Section 7 describes how a client should handle incoming updates,
and Section 8 gives an example of the Information Resource Directory (IRD)
for an ALTO Server that offers a comprehensive set of Update Services.
Section 9 discusses the design decisions behind this update mechanism.
The remaining sections review the security and IANA considerations.
</t>
</section>
<section title="Overview of Approach">
<t>
This section presents a non-normative overview of the update mechanism.
</t>
<t>
An ALTO Server can offer one or more Update Stream resources.
Each stream presents a continuous sequence of update messages
for a set of ALTO resources selected by the server.
Each message updates one resource.
The messages are Server-Sent Events (SSEs), as defined by <xref target="SSE"/>.
An update message is either a complete replacement
or else an incremental change.
Complete 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 a full replacement or an incremental update.
These decisions can vary from resource to resource
and from update to update.
</t>
<t>
There are two types of Update Stream resources:
Full Update Streams and Filtered Update Streams.
A Full Update Stream is a GET-mode resource
that provides updates to a set of GET-mode resources
selected by the server.
</t>
<t>
A Filtered Update Stream is a POST-mode resource,
and allows the client to select a subset of the update events
offered by the server for that stream.
In particular, a client may ask a server
to send full updates events instead of incremental updates.
A Filtered Update Stream can also provide updates
to POST-mode resources such as the Endpoint Property Service.
</t>
<t>
An ALTO Server may offer any number of Update Stream resources,
for any collection of the server's resources.
A server may offer updates to the same resource
via several different Update Stream resources,
provided that the different update messages yield the same net result.
</t>
<t>
An ALTO Server's Information Resource Directory (IRD)
defines its Update Stream resources.
</t>
<t>
When an ALTO Client requests an Update Stream resource,
the client establishes a new persistent connection to the server.
The connection remains open, and the server continues to send updates,
until either the client or server closes it.
A client may connect to any number of Update Stream resources.
Because each connection 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="Update Events">
<section title="Overview of SSEs">
<t>
The following is a non-normative summary of Server-Sent Events.
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).
Messages may contain three fields:
an event type, an id, and data. All fields are strings.
The data field may contain new-lines; the other fields cannot.
The event type and id fields are optional.
</t>
<t>
Here is a sample SSE stream, starting with the client request.
The server sends three events and then closes the stream.
Note that the server may "chunk" the returned data (see <xref target="RFC2616"/>);
for simplicity, we have omitted those details.
</t>
<figure>
<artwork><![CDATA[
GET /stream HTTP/1.1
Host: example.com
Accept: text/event-stream
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="ALTO Update Events" anchor="ALTO.SSE.Events">
<t>
In the events defined in this document,
the data field is a JSON object.
That object is either a complete specificiation of an ALTO resource,
or else a JSON Merge Patch object
describing changes to apply to an ALTO resource.
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.
The data objects in Merge Patch messages
are defined by <xref target="RFC7386"/>.
</t>
<t>
The event type field has two sub-fields:
the resource-id of an ALTO resource,
and the media-type of the JSON message in the data field.
The media-types for full-replacement messages are defined by <xref target="RFC7285"/>,
and include "application/alto-networkmap+json" for Network Map messages
and "application/alto-costmap+json" for Cost Map messages.
The media-type for a JSON Merge Patch message is "application/merge-patch+json",
and is defined by <xref target="RFC7386"/>.
</t>
<t>
We do not use the SSE id field.
</t>
<t>
We encode the event type sub-fields as:
</t>
<figure>
<artwork><![CDATA[
resource-id , media-type
]]></artwork>
</figure>
<t>
Note that commas (character code 0x2c) are allowed in ALTO resource-ids,
but not in media-type names.
Hence when parsing the SSE event type into sub-types,
a client MUST split the string on the last comma.
</t>
<t>
Here examples of ALTO update events:
</t>
<figure>
<artwork><![CDATA[
event: my-network-map,application/alto-networkmap+json
data: { ... full Network Map message ... }
event: my-routingcost-map,application/alto-costmap+json
data: { ... full Cost Map message ... }
event: my-routingcost-map,application/merge-patch+json
data: { ... Merge Patch update for previous Cost Map ... }
]]></artwork>
</figure>
</section>
<section title="Keep-Alive Messages">
<t>
An SSE event with an empty event type is a keep-alive message.
An ALTO Server MAY send keep-alive messages as needed.
An ALTO Client MUST ignore any keep-alive messages.
</t>
</section>
</section>
<section title="Incremental Update Message Format">
<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 incremental updates,
but uses a different transport mechanism.
</t>
<t>
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 document.
</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 that 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:
</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="Update Stream Service" anchor="UpdateStreamService">
<t>
An Update Stream Service returns a stream of SSE messages,
as defined in <xref target="ALTO.SSE.Events"/>.
</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 GET method.
</t>
</section>
<section title="Accept Input Parameters">
<t>
None.
</t>
</section>
<section title="Capabilities" anchor="UpdateStreamService.Capabilities">
<t>
The capabilities are defined by an object of type UpdateStreamCapabilities:
</t>
<figure>
<artwork><![CDATA[
object {
JSONString update-events<1..*>;
} UpdateEventStreamCapabilities;
]]></artwork>
</figure>
<t>
The strings in the array are the event types (see <xref target="ALTO.SSE.Events"/>)
sent by this Update Stream.
</t>
<t>
If an Update Event Service's "update-events" capability list
has an event with a media-type of "application/merge-patch+json"
for a resource-id,
then the event capability list MUST also have a full-replacement event
for that resource-id.
For example, suppose "my-costmap" is the resource-id of a Cost Map.
Then if the event list has "my-costmap,application/merge-patch+json",
it MUST also have the event "my-costmap,application/alto-costmap+json".
</t>
</section>
<section title="Uses" anchor="UpdateStreamService.Uses">
<t>
An array with the resource-ids of the resources for which this stream sends updates.
This array MUST contain the resource-ids of every event type
in the "update-events" capability.
</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>
There are additional requirements between events
in the stream, as described below.
</t>
<section title="Event Sequence Requirements">
<t>
<list style="symbols">
<t>
The ALTO Server MUST send a full-replacement update event
for each resource-id covered by this Update Stream resource
as soon as possible after the client initiates the connection.
</t>
<t>
The ALTO Server MUST send a full-replacement update event
for a resource-id before sending the first
Merge Patch event for that resource-id.
</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>
</list>
</t>
</section>
<section title="Cross-Stream Consistency Requirements">
<t>
If several distinct Update Stream resources
offer updates for the same resource-id,
the ALTO Server MUST send the same update data
on all of those Update Streams.
Similarly, the server MUST send the same updates
to all clients connected to the that stream.
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 open the same Cost Map Update Stream,
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>
</section>
</section>
<section title="Example">
<t>
Here is an example of a client's request and the server's immediate response,
using the Update Stream resource "my-routingcost-update-stream"
defined in the IRD in <xref target="IRD.example"/>.
This assumes the Update Stream service sends updates
for a Network Map with resource-id "my-network-map"
and an associated Cost Map with resource-id "my-routingcost-map".
Note that the server may "chunk" the returned data (see <xref target="RFC2616"/>);
for simplicity, we have omitted those details.
</t>
<figure>
<artwork><![CDATA[
GET /updates/routingcost HTTP/1.1
Host: alto.example.com
Accept: text/event-stream
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/event-stream
event: my-network-map,application/alto-networkmap+json
data: { ... full Network Map message ... }
event: my-routingcost-map,application/alto-costmap+json
data: { ... full Cost Map message ... }
]]></artwork>
</figure>
<t>
After sending those two 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: my-routingcost-map,application/merge-patch+json
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: my-network-map,application/alto-networkmap+json
data: { ... full Network Map message ... }
event: my-routingcost-map,application/alto-costmap+json
data: { ... full Cost Map message ... }
]]></artwork>
</figure>
</section>
</section>
<section title="Filtered Update Stream Service">
<t>
The Filtered Update Stream service is similar to
the Update Stream service (<xref target="UpdateStreamService"/>),
except that the client
can select the types of update events.
</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>
A Filtered ALTO Update Stream resource
is requested using the HTTP POST method.
</t>
</section>
<section title="Accept Input Parameters" anchor="FilteredUpdate.media-type">
<t>
An ALTO Client supplies filtering parameters by specifying media type
"application/alto-updatestreamfilter+json" with HTTP POST body
containing a JSON object of type ReqFilteredUpdateStream, where:
</t>
<figure>
<artwork><![CDATA[
object {
[UpdateEventType update-events<1..*>;]
[VersionTag vtags<1..*>;]
[ResourceInputs inputs<1..*>;]
} ReqFilteredUpdateStream;
object-map {
ResourceID -> JSONObject;
} ResourceInputs;
]]></artwork>
</figure>
<t>
The "update-events" field gives the types of the events the ALTO
Client wishes to receive. These events MUST be a subset of the
"update-events" capability of this resource; the ALTO Server
MUST ignore any events not in the resource's capability list. If
the "update-events" list is omitted, the ALTO Server MUST send
all event types in the "update-events" capability of this
resource.
</t>
<t>
The "vtags" field is an array of version tags,
as defined in Section 10.3 of <xref target="RFC7285"/>,
for any resources which the client already has.
At startup, the server SHOULD NOT send the full version
of any resource for which the client has the current version.
</t>
<t>
The "inputs" field gives the client input needed for any POST-mode resources
requested by the client.
The value is a JSON object.
The keys are the resource-ids of the POST-mode resources,
and the value for each resource-id is the JSON object
that resource requires as its input.
</t>
<t>
If the "update-events" field includes events for a POST-mode resource,
but the "inputs" field for that resource is missing or invalid,
then ALTO Server MUST return the same error response
that that resource would return if given that input
(see <xref target="RFC7285"/>).
In this case, the server MUST close the Update Stream
without sending any update 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>
If a client requests Merge Patch update events for a resource-id,
the client MUST also request the corresponding full map update events
for that resource-id.
</t>
<t>
If a client requests the full-replacement update event for a resource-id,
but does not request the Merge Patch update event for that resource-id,
when that resource changes,
the ALTO 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 Merge Patch events
will not get updates as quickly as a client which does.
</t>
</section>
<section title="Capabilities and Uses">
<t>
The "capabilities" and "uses" fields
are the same as for the Full Update Stream Service,
as described in <xref target="UpdateStreamService.Capabilities"/>
and <xref target="UpdateStreamService.Uses"/>, respectively.
</t>
</section>
<section title="Response">
<t>
The format of the response, and the associated rules,
are the same as for the Full Update Stream Service
(<xref target="UpdateStreamService.Response"/>),
except that the ALTO Server SHOULD NOT
send an initial full-replacement message
for any resource for which the version
in the "vtags" field of the client's input
matches the resource's current version.
</t>
</section>
<section title="Example: Network and Cost Map Updates">
<t>
Here is an example of a client's request and the server's immediate response,
using the Filtered Update Stream resource "my-allresources-update-stream"
defined in the IRD in <xref target="IRD.example"/>.
The client requests updates for the Network Map
and the "routingcost" Cost Map,
but does not want updates for the "hopcount" Cost Map.
The "vtags" field gives the client's version of the Network Map.
Because that version is still current,
the server does not send the full Network Map update event
at the beginning of the stream.
After that, the ALTO Server sends updates for the Network Map
and "routingcost" Cost Map as they become available:
</t>
<figure>
<artwork><![CDATA[
POST /updates/allresources HTTP/1.1
Host: alto.example.com
Accept: text/event-stream
Content-Type: application/alto-updatestreamfilter+json
Content-Length: ###
{ "update-events": [
"my-network-map,application/alto-networkmap+json",
"my-routingcost-map,application/alto-costmap+json",
"my-routingcost-map,application/merge-patch+json"
],
"vtags": [
{"resource-id": "my-network-map",
"tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
}
],
}
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/event-stream
event: my-routingcost-map,application/alto-costmap+json
data: { ... full Cost Map message ... }
(pause)
event: my-routingcost-map,application/merge-patch+json
data: {"cost-map": {"PID2" : {"PID3" : 31}}}
]]></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 a set of endpoints.
The ALTO Server immediately sends a full-replacement message 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/allresources HTTP/1.1
Host: alto.example.com
Accept: text/event-stream
Content-Type: application/alto-updatestreamfilter+json
Content-Length: ###
{ "update-events": [
"my-properties,application/alto-endpointprops+json",
"my-properties,application/merge-patch+json"
],
"inputs": {
"my-properties": {
"properties" : [ "priv:ietf-bandwidth" ],
"endpoints" : [
"ipv4:1.0.0.1",
"ipv4:1.0.0.2",
"ipv4:1.0.0.3"
]
}
}
}
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: text/event-stream
event: my-properties,application/alto-endpointprops+json
data: { "endpoint-properties": {
data: "ipv4:1.0.0.1" : { "priv:ietf-bandwidth": "13" },
data: "ipv4:1.0.0.2" : { "priv:ietf-bandwidth": "42" },
data: "ipv4:1.0.0.3" : { "priv:ietf-bandwidth": "27" }
data: } }
(pause)
event: my-properties,application/merge-patch+json
data: { "endpoint-properties":
data: {"ipv4:1.0.0.1" : {"priv:ietf-bandwidth": "3"}}
data: }
(pause)
event: my-properties,application/merge-patch+json
data: { "endpoint-properties":
data: {"ipv4:1.0.0.3" : {"priv:ietf-bandwidth": "38"}}
data: }
]]></artwork>
</figure>
</section>
</section>
<section title="Client Actions When Receiving Update Messages">
<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>
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.
If the client uses the Filtered Update Stream service,
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="IRD Example" anchor="IRD.example">
<t>
Here is an example of an IRD that offers both regular and Filtered
Update Stream services.
The unfiltered Update Stream
provides updates for the Network Map
and "routingcost" Cost Map.
The Filtered Update Stream
provides update to both those maps,
plus the "hopcount" Cost Map
and the Endpoint Properties service.
</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",
"media-type": "application/alto-costmap+json",
"uses": ["my-networkmap+json"],
"capabilities": {
"cost-type-names": ["num-routingcost"]
}
},
"my-hopcount-map": {
"uri": "http://alto.example.com/costmap",
"media-type": "application/alto-costmap+json",
"uses": ["my-networkmap+json"],
"capabilities": {
"cost-type-names": ["num-hopcount"]
}
},
"my-properties": {
"uri": "http://alto.example.com/properties",
"media-type": "application/alto-endpointprops+json",
"accepts": "application/alto-endpointpropparams+json",
"capabilities": {
"prop-types": ["priv:ietf-bandwidth"]
}
},
"my-routingcost-update-stream": {
"uri": "http://alto.example.com/updates/routingcost",
"media-type": "text/event-stream",
"uses": ["my-network-map", "my-routingcost-map"],
"capabilities": {
"update-events": [
"my-network-map,application/alto-networkmap+json",
"my-routingcost-map,application/alto-costmap+json",
"my-routingcost-map,application/merge-patch+json"
]
}
},
"my-allresources-update-stream": {
"uri": "http://alto.example.com/updates/allresources",
"media-type": "text/event-stream",
"uses": [
"my-network-map",
"my-routingcost-map",
"my-hopcount-map",
"my-properties"
],
"accepts": "application/alto-updatestreamfilter+json",
"capabilities": {
"update-events": [
"my-network-map,application/alto-networkmap+json",
"my-routingcost-map,application/alto-costmap+json",
"my-routingcost-map,application/merge-patch+json"
"my-hopcount-map,application/alto-costmap+json",
"my-hopcount-map,application/merge-patch+json"
"my-properties,application/alto-endpointprops+json",
"my-properties,application/merge-patch+json"
]
}
}
]]></artwork>
</figure>
</section>
<section title="Design Decisions and Discussions">
<section title="HTTP2 Server-Push">
<t>
An alternative would be to use HTTP 2 Server-Push
<xref target="I-D-ietf-http2"/>,
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>
Also, although this is a theoretical inefficiency,
in practice it is unlikely to be a problem.
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 is
hopefully very rare. We believe that complexity
is not worth the benefit.
</t>
<t>
The Filtered Update Stream service does allow the client
to specify the vtag 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 vtags 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 occurance.
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.
</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="Security Considerations" anchor="Security">
<t>
Allowing persistent update stream connections
enables a new class of Denial-of-Service attacks.
An ALTO Server MAY choose to limit the number of active streams,
and reject new requests when that threshold is reached.
In this case the server should return
the HTTP status "503 Service Unavailable".
</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>
<t>
This extension does not introduce any privacy issues
not already present in the ALTO protocol.
</t>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>
This document defines a new media-type, "application/alto-updatestreamfilter+json",
as described in <xref target="FilteredUpdate.media-type"/>.
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-updatestreamfilter+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="FilteredUpdate.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>
</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="I-D-ietf-http2">
<front>
<title>Hypertext Transfer Protocol version 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="November" day="29" year="2014"/>
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-httpbis-http2-16' />
</reference>
<reference anchor="SSE">
<front>
<title>Server-Sent Events (W3C)</title>
<author initials="I." surname="Hickson" fullname="Ian Hickson"/>
<date month="December" year="2012"/>
</front>
<!-- http://www.w3.org/TR/eventsource/ -->
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 07:19:06 |