Internet-Draft | ALTO TIPS | March 2023 |
Schott, et al. | Expires 13 September 2023 | [Page] |
The ALTO Protocol (RFC 7285) leverages HTTP/1.x and is designed for the simple, sequential request-reply use case, in which an ALTO client requests a sequence of information resources, and the server responds with the complete content of each resource one at a time.¶
ALTO incremental updates using Server-Sent Events (SSE) (RFC 8895) defines a multiplexing protocol on top of HTTP/1.x, so that an ALTO server can incrementally push resource updates to clients whenever monitored network information resources change, allowing the clients to monitor multiple resources at the same time. However, HTTP/2 and later versions already support concurrent, non-blocking transport of multiple streams in the same HTTP connection.¶
To take advantage of newer HTTP features, this document introduces the ALTO Transport Information Publication Service (TIPS). TIPS uses an incremental RESTful design to give an ALTO client the new capability to explicitly, concurrently (non-blocking) request (pull) specific incremental updates using native HTTP/2 or HTTP/3, while still functioning for HTTP/1.x. TIPS also provides an ALTO server to concurrently push specific incremental updates using native HTTP/2 or HTTP/3 server push.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 13 September 2023.¶
Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Application-Layer Traffic Optimization (ALTO) provides means for network applications to obtain network status information. So far, two transport protocols have been designed: (1) The ALTO base protocol [RFC7285], which is designed for the simple use case in which an ALTO client requests a network information resource, and the server sends the complete content of the requested information (if any) resource to the client; and (2) ALTO incremental updates using Server-Sent Events (ALTO/SSE) [RFC8895], which is designed for an ALTO client to indicate to the server that it wants to receive updates for a set of resources, and the server can then concurrently, and incrementally push updates to that client whenever monitored resources change.¶
Both protocols are designed for HTTP/1.x [RFC9112] and, ideally, they should be able to automatically take advantage of newer HTTP versions such as HTTP/2 [RFC9113] and HTTP/3 [RFC9114]. However, there are issues with both protocols when higher HTTP versions are used. First, consider the ALTO base protocol, which is designed to transfer only complete information resources. Hence, a client can run the base protocol on top of HTTP/2 or HTTP/3 to request multiple information resources concurrently, in concurrent streams, but each request must be for a complete information resource; there is no capability of transferring incremental updates. Hence, there can be large overhead when the client already has an information resource and then there are small changes to the resource. Next, consider ALTO/SSE. Although ALTO/SSE can transfer incremental updates, it introduces a customized multiplexing protocol on top of HTTP, assuming a total-order message channel from the server to the client. The multiplexing design does not provide naming (i.e., providing resource identifier) to individual incremental updates. Hence, the design cannot use concurrent per-stream server push or non-blocking per-stream client pull, available in HTTP/2 and HTTP/3, because both cases require the resource identifier. Additionally, ALTO/SSE is a push-only protocol, which denies the client flexibility in choosing how and when it receives updates.¶
This document introduces a new ALTO service called the Transport Information Publication Service (TIPS). TIPS uses an incremental RESTful design to provide an ALTO client with a new capability to explicitly, concurrently (non-blocking) request (pull) specific incremental updates using native HTTP/2 or HTTP/3, while still functioning for HTTP/1.x. TIPS also provides an ALTO server to concurrently push specific incremental updates using native HTTP/2 or HTTP/3 server push. Specifically, this document specifies the following:¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.¶
For each resource (e.g., a cost map, network map), the incremental updates and snapshots can be represented using the following directed acyclic graph model, where the server maps base resource IDs to incremental update IDs that are assigned sequentially:¶
A concrete example is as shown in Figure 1. Thick lines represent incremental updates and thin lines represent snapshots. Note that node content is path independent: the content can be obtained by applying the updates from different paths. For example, assume the client already has version at 103: the version at 105 can either be directly fetched as a snapshot or computed incrementally by applying the incremental updates between 103 and 104, then 104 and 105.¶
To access each individual update, consider the model represented as a "virtual" file system (adjacency list).¶
Due to the sequential nature of the update patch IDs, a client can long pull a future update that does not yet exist (e.g., the patch from 106 to 107) by constructing the URI:¶
GET /<tips-view-uri>/ug/<end-seq>/<end-seq + 1>¶
Conceptually, the TIPS system consists of 3 types of resources:¶
Design Point: Component Resource Location¶
This document specifies Design 1 (keeping R1, R2, and R3 on the same server) in order to simplify session management, though at the expense of maximum load balancing flexibility (see Section 8.1 for a discussion on load balancing considerations). A future companion document may extend the protocol to support Design 2 or Design 3.¶
This document uses the following components:¶
Figure 1 shows an example illustrating the TIPS abstraction. Each ALTO client (Client 1, Client 2, or Client 3) maintains a single HTTP connection with the ALTO server.¶
The intended use case of TIPS is to run it as a service inside an HTTP/2 or HTTP/3 connection (though it can run inside an HTTP/1.x connection, without server push functionality). Specifically, an ALTO client opens an HTTP connection with an ALTO server and uses TIPS to retrieve a JSON object that contains a URI to a TIPS view of each network information resource that the client wants to monitor, along with a summary of each TIPS view (which provides, at minimum, the start and end sequence number of the updates graph and a server-recommended edge to consume first).¶
In the simplest use case, the TIPS view summary provides enough information for the client to continuously pull each additional update, resulting in the following workflow:¶
A client that prefers server push can use the following workflow:¶
While TIPS is designed to take advantage of newer HTTP features, TIPS still functions with HTTP/1.x for client pull functionality only, with the limitation that it cannot cancel any outstanding requests or fetch resources concurrently over the same connection.¶
An ALTO server's IRD (Information Resource Directory) MAY define one or more transport information publication services, which ALTO clients use to request new TIPS instances. An IRD entry defining a TIPS MUST declare the "media-type", and specify "capabilities" and "uses" as follows.¶
The media type of the Transport Information Publication Service resource is "application/alto-tips+json".¶
The capabilities declaration of TIPS is modelled on that defined in Section 6.3 of [RFC8895].¶
Specifically, the capabilities are defined as an object of type TIPSCapabilities:¶
object { IncrementalUpdateMediaTypes incremental-change-media-types; Boolean support-server-push; } TIPSCapabilities; object-map { ResourceID -> String; } IncrementalUpdateMediaTypes;¶
with field:¶
If a TIPS can provide updates with incremental changes for a resource, the "incremental-change-media-types" field has an entry for that resource-id, and the value is the supported media types of the incremental change separated by commas. For the implementation of this specification, this will be "application/merge-patch+json", "application/json-patch+json", or "application/merge-patch+json,application/json-patch+json". Future extensions may define other types of incremental changes.¶
When choosing the media types to encode incremental updates for a resource, the server MUST consider the limitations of the encoding. For example, when a JSON merge patch specifies that the value of a field is null, its semantics are that the field is removed from the target and hence the field is no longer defined (i.e., undefined). This, however, may not be the intended result for the resource, when null and undefined have different semantics for the resource. In such a case, the server MUST choose JSON patch over JSON merge patch if JSON patch is indicated as a capability of the TIPS. If the server does not support JSON patch to handle such a case, the server then needs to send a full replacement.¶
The "support-server-push" field specifies whether the given TIPS supports server push. If the "support-server-push" field is TRUE, this TIPS will allow a client to start or stop server push. If the field is FALSE or not present, this TIPS does not provide server push.¶
The "uses" attribute MUST be an array with the resource-ids of every network information resource for which this TIPS can provide service.¶
This set may be any subset of the ALTO server's network information resources and may include resources defined in linked IRDs. However, it is RECOMMENDED that the ALTO server selects a set that is closed under the resource dependency relationship. That is, if a TIPS' "uses" set includes resource R1 and resource R1 depends on ("uses") resource R0, then the TIPS' "uses" set SHOULD include R0 as well as R1. For example, a TIPS for a cost map SHOULD also provide a TIPS view for the network map upon which that cost map depends.¶
Extending the IRD example in Section 8.1 of [RFC8895], below is the IRD of an ALTO server supporting ALTO base protocol, ALTO/SSE, and ALTO TIPS.¶
"my-network-map": { "uri": "https://alto.example.com/networkmap", "media-type": "application/alto-networkmap+json", }, "my-routingcost-map": { "uri": "https://alto.example.com/costmap/routingcost", "media-type": "application/alto-costmap+json", "uses": ["my-networkmap"], "capabilities": { "cost-type-names": ["num-routingcost"] } }, "my-hopcount-map": { "uri": "https://alto.example.com/costmap/hopcount", "media-type": "application/alto-costmap+json", "uses": ["my-networkmap"], "capabilities": { "cost-type-names": ["num-hopcount"] } }, "my-filtered-cost-map": { "uri": "https://alto.example.com/costmap/filtered/constraints", "media-type": "application/alto-costmap+json", "accepts": "application/alto-costmapfilter+json", "uses": ["my-networkmap"], "capabilities": { "cost-type-names": ["num-routingcost", "num-hopcount"], "cost-constraints": true } }, "my-simple-filtered-cost-map": { "uri": "https://alto.example.com/costmap/filtered/simple", "media-type": "application/alto-costmap+json", "accepts": "application/alto-costmapfilter+json", "uses": ["my-networkmap"], "capabilities": { "cost-type-names": ["num-routingcost", "num-hopcount"], "cost-constraints": false } }, "my-props": { "uri": "https://alto.example.com/properties", "media-type": "application/alto-endpointprops+json", "accepts": "application/alto-endpointpropparams+json", "capabilities": { "prop-types": ["priv:ietf-bandwidth"] } }, "my-pv": { "uri": "https://alto.example.com/endpointcost/pv", "media-type": "multipart/related; type=application/alto-endpointcost+json", "accepts": "application/alto-endpointcostparams+json", "capabilities": { "cost-type-names": [ "path-vector" ], "ane-properties": [ "maxresbw", "persistent-entities" ] } }, "update-my-costs": { "uri": "https://alto.example.com/updates/costs", "media-type": "text/event-stream", "accepts": "application/alto-updatestreamparams+json", "uses": [ "my-network-map", "my-routingcost-map", "my-hopcount-map", "my-simple-filtered-cost-map" ], "capabilities": { "incremental-change-media-types": { "my-network-map": "application/json-patch+json", "my-routingcost-map": "application/merge-patch+json", "my-hopcount-map": "application/merge-patch+json" }, "support-stream-control": true } }, "update-my-costs-tips": { "uri": "https://alto.example.com/updates-new/costs", "media-type": "application/alto-tips+json", "accepts": "application/alto-tipsparams+json", "uses": [ "my-network-map", "my-routingcost-map", "my-hopcount-map", "my-simple-filtered-cost-map" ], "capabilities": { "incremental-change-media-types": { "my-network-map": "application/json-patch+json", "my-routingcost-map": "application/merge-patch+json", "my-hopcount-map": "application/merge-patch+json", "my-simple-filtered-cost-map": "application/merge-patch+json" }, "support-server-push": true } }, "update-my-props": { "uri": "https://alto.example.com/updates/properties", "media-type": "text/event-stream", "uses": [ "my-props" ], "accepts": "application/alto-updatestreamparams+json", "capabilities": { "incremental-change-media-types": { "my-props": "application/merge-patch+json" }, "support-stream-control": true } }, "update-my-pv": { "uri": "https://alto.example.com/updates/pv", "media-type": "text/event-stream", "uses": [ "my-pv" ], "accepts": "application/alto-updatestreamparams+json", "capabilities": { "incremental-change-media-types": { "my-pv": "application/merge-patch+json" }, "support-stream-control": true } }¶
Note that it is straightforward for an ALTO sever to run HTTP/2 and support concurrent retrieval of multiple resources such as "my- network-map" and "my-routingcost-map" using multiple HTTP/2 streams.¶
The resource "update-my-costs-tips" provides an ALTO TIPS based connection, and this is indicated by the media-type "application/alto-tips+json".¶
Upon request, a server sends a TIPS view to a client. This TIPS view may be created at the time of the request or may already exist (either because another client has an active connection to a TIPS view for the same requested network resource or because the server perpetually maintains a TIPS view for an often requested resource). The server MAY keep track of which clients have an active connection to each TIPS view to determine whether or not it should delete a TIPS view and its corresponding updates graph and associated data.¶
An ALTO client requests that the server provide a TIPS view for a given resource by sending an HTTP POST body with the media type "application/alto-tipsparams+json". That body contains a JSON object of type TIPSReq, where:¶
object { ResourceID resource-id; [JSONString tag;] [Object input;] [Boolean server-push;] } TIPSReq;¶
with the following fields:¶
The resource-id of an ALTO resource and MUST be in the TIPS' "uses" list (Section 3). If a client does not support all incremental methods from the set announced in the server's capabilities, the client MUST NOT use the TIPS service.¶
If the resource-id is a GET-mode resource with a version tag (or "vtag"), as defined in Sections 6.3 and 10.3 of [RFC7285], and the ALTO client has previously retrieved a version of that resource from ALTO, the ALTO client MAY set the "tag" field to the tag part of the client's version of that resource. The server MAY use the tag when calculating a recommended starting edge for the client to consume. Note that the client MUST support all incremental methods from the set announced in the server's capabilities for this resource.¶
If the resource is a POST-mode service that requires input, the ALTO client MUST set the "input" field to a JSON object with the parameters that the resource expects.¶
Set to TRUE if a client desires to receive updates via server push. If the value is FALSE or not present, the client does not accept server push updates.¶
The response to a valid request MUST be a JSON object of type AddTIPSResponse, denoted as media type "application/alto-tips+json":¶
object { JSONString tips-view-uri; TIPSViewSummary tips-view-summary; } AddTIPSResponse; object { UpdatesGraphSummary updates-graph-summary; [Boolean server-push;] } TIPSViewSummary; object { JSONNumber start-seq; JSONNumber end-seq; StartEdgeRec start-edge-rec; } UpdatesGraphSummary; object { JSONNumber seq-i; JSONNumber seq-j; } StartEdgeRec;¶
with the following fields:¶
Relative URI to the TIPS view of a network resource.¶
When creating the URI for the TIPS view, TIPS MUST NOT use other properties of an HTTP request, such as cookies or the client's IP address, to determine the TIPS view. Furthermore, TIPS MUST NOT reuse a URI for a different object in the same connection.¶
It is expected that there is an internal mechanism to map a tips-view-uri to the TIPS view to be accessed. For example, TIPS may assign a unique, internal state id to each TIPS view instance. However, the exact mechanism is left to the TIPS provider.¶
Contains both an updates-graph-summary and an optional server-push boolean value which is set to TRUE if and only if the client indicates server push.¶
The updates-graph-summary field contains the starting sequence number (start-seq) of the updates graph and the last sequence number (end-seq) that is currently available, along with a recommended edge to consume (start-edge-rec). How the server calculates the recommended edge depends on the implementation. Ideally, if the client does not provide a version tag, the server should recommend the edge of the latest snapshot available. If the client does provide a version tag, the server should calculate the cumulative size of the patch updates availabe from that version onward and compare it to the size of the complete resource snapshot. If the snapshot is bigger, the server should recommend the first patch update edge starting from client's tagged version. Else, the server should recommend the latest snapshot edge. If the client indicates server push, the recommended edge will be the first content pushed.¶
If the request has any errors, the TIPS service MUST return an HTTP "400 Bad Request" to the ALTO client; the body of the response follows the generic ALTO error response format specified in Section 8.5.2 of [RFC7285]. Hence, an example ALTO error response has the format:¶
HTTP/1.1 400 Bad Request Content-Length: 131 Content-Type: application/alto-error+json Connection: Closed { "meta":{ "code": "E_INVALID_FIELD_VALUE", "field": "resource-id", "value": "my-network-map/#" } }¶
Note that "field" and "value" are optional fields. If the "value" field exists, the "field" field MUST exist.¶
For simplicity, assume that the ALTO server is using the Basic authentication. If a client with username "client1" and password "helloalto" wants to create a TIPS view of an ALTO Cost Map resource with resource ID "my-routingcost-map", it can send the following request:¶
POST /tips HTTP/1.1 Host: alto.example.com Accept: application/alto-tips+json, application/alto-error+json Authorization: Basic Y2xpZW50MTpoZWxsb2FsdG8K Content-Type: application/alto-tipsparams+json Content-Length: 41 { "resource-id": "my-routingcost-map" }¶
If the operation is successful, the ALTO server returns the following message:¶
HTTP/1.1 200 OK Content-Type: application/alto-tips+json Content-Length: 291 { "tips-view-uri": "/tips/2718281828459", "tips-view-summary": { "updates-graph-summary": { "start-seq": 101, "end-seq": 106, "start-edge-rec" : { "seq-i": 0, "seq-j": 105 } }, "server-push": false } }¶
An ALTO client can indicate it no longer desires to pull/receive updates for a specific network resource by "deleting" the TIPS view using the returned tips-view-uri and the HTTP DELETE method. Whether or not the server actually deletes the TIPS view is implementation dependent. Likely, a server will remove the client from a dependency set associated with the TIPS view. A server will not want to delete a TIPS view if another client is using it. The DELETE request looks like:¶
DELETE /<tips-view-uri>¶
The response to a valid request MUST be 200 if success, and the corresponding error code if there is any error.¶
If the connection between the client and TIPS provider is severed without a DELETE request having been sent, the server MUST treat it as if the client had sent a DELETE request because the TIPS view is, at least from the client view, per-session based.¶
An ALTO client can read the metadata directory of the TIPS view to understand its full contents beyond the intial summary provided.¶
An ALTO client requests the updates graph's metadata directory by sending an HTTP GET request with the media type "application/alto-tipsview+json". The GET request looks like:¶
GET /<tips-view-uri>¶
An ALTO client can also read the metadata directory of just the the updates graph (perhaps to calculate a new shortest path to the end of the graph after not having fetched for a period of time). The HTTP method is a GET, and looks like:¶
GET /<tips-view-uri>/ug¶
An ALTO client can also read the metadata of an individual edge in the updates graph. The HTTP method is a GET, and looks like:¶
GET /<tips-view-uri>/ug/meta/<i>/<j>¶
If the TIPS view is closed, the ALTO server MUST return an error HTTP message with status code 404 (Not Found) and media type "application/alto-error+json".¶
The response from the server, if no error, for the entire metadata directory of the TIPS view is the UpdatesDirectory object indicated as "application/alto-tipsview+json" media type:¶
object { GraphDirMeta meta; UpdatesGraph updates-graph; PushState push-state; } UpdatesDirectory : ResponseEntityBase; object { ResourceID resource-id; Tag tag; } GraphDirMeta; object-map { JSONString -> EndSeqUpdates; } UpdatesGraph; object-map { JSONString -> UpdateItemMeta; } EndSeqUpdates; object { JSONString media-type; JSONString tag; JSONNumber size; } UpdateItemMeta; object { Boolean server-push; NextEdge next-edge; } PushState; object { JSONNumber seq-i; JSONNumber seq-j; } NextEdge;¶
with the following fields:¶
Specifies the network resource-id TIPS view to which the directory corresponds and the version tag of the directory itself.¶
Contains a map of edges in the updates graph (start-seq to end-seq). Each edge has a corresponding update-item-meta which includes the edge's media type, resource version tag, and size of the content in kilobytes. Note that two different edges will share the same resource version tag if they connect to the same end-seq node in the graph.¶
Contains server-push boolean which is set to TRUE if the client has indicated server push. Otherwise, it is set to FALSE. push-state also contains next-edge which indicates the next edge that will be pushed to the client. If server-push is FALSE, next-edge is NULL.¶
GET /tips/2718281828459 HTTP/1.1 Host: alto.example.com Accept: application/alto-tipsview+json, application/alto-error+json Authorization: Basic Y2xpZW50MTpoZWxsb2FsdG8K HTTP/1.1 200 OK Content-Type: application/alto-tipsview+json Content-Length: 1239 { "meta": { "resource-id": "2718281828459", "tag": "125351264356" }, "updates-graph": { "0": { "101": { "media-type": "alto-costmap+json", "tag": "109783421097", "size": 1000000 }, "103": { "media-type": "alto-costmap+json", "tag": "123400881080", "size": 1004000 }, "105": { "media-type": "alto-costmap+json", "tag": "123567838392", "size": 1008033 } }, "101": { "102": { "media-type": "application/merge-patch+json", "tag": "123566431234", "size": 4040} }, "102": { "103": { "media-type": "application/merge-patch+json", "tag": "123400881080", "size": 3000} }, "103": { "104": { "media-type": "application/merge-patch+json", "tag": "123566452654", "size": 8000} }, "104": { "105": { "media-type": "application/merge-patch+json", "tag": "123567838392", "size": 10000} }, "105": { "106": { "media-type": "application/merge-patch+json", "tag": "123566470983", "size": 4040} } }, "push-state": { "server-push": false, "next-edge": null } }¶
An ALTO client can refresh the updates graph directory without re-fetching the whole updates graph object.¶
An ALTO client requests the TIPS view metadata directory by sending an HTTP GET request with the media type "application/alto-tipsview+json" and the version tag of the TIPS view directory it has currently. The GET request looks like:¶
POST /tips/2718281828459 HTTP/1.1 Host: alto.example.com Accept: application/alto-tipsview+json, application/merge-patch+json, application/alto-error+json Authorization: Basic Y2xpZW50MTpoZWxsb2FsdG8K Content-Type: application/alto-tipsparams+json Content-Length: 43 { "tag": "125351264356" }¶
The server may return the whole directory or the incremental changes, using merge-patch. A patch response looks like:¶
HTTP/1.1 200 OK Content-Type: application/merge-patch+json Content-Length: 212 { "meta": { "tag": "543353364839" }, "updates-map": { "0": { "101": null, "107": {...} }, "101": null, "102": null } }¶
A server may change its updates graph (to compact, etc.), but it must satisfy the following invariants:¶
For example, using the example model in Section 2.1, assume at time 0, the server provides the valid set [101, 102, 103, 104, 105, 106]. At time 1, both [103, 104, 105, 106] and [105, 106] are valid sets. However, [102, 103, 104, 105, 106] is not a valid set as there is no snapshot of the version at 102 and [104, 105, 106] is not a valid set as there is no snapshot of the version at 104. Thus, there is a risk that the right content of the version at 102, in the first example, and 104, in the second example, cannot be obtained by a client that does not have the previous version at 101 or 103, respectively.¶
TIPS allows an ALTO client to retrieve the content of an update item from the updates graph, with an update item defined as the content (patch or snapshot) on an edge in the updates graph.¶
The client sends an HTTP GET request, where the media type of an update item resource MUST be the same as the "media-type" field of the update item on the specified edge in the updates graph.¶
For example, if the client wants to query the content of the first update item (0 -> 101) whose media type is "application/alto-costmap+json", it must set the "Accept" header to "application/alto-costmap+json, application/alto-error+json" in the request.¶
The GET request looks like¶
GET /<tips-view-uri>/ug/<i>/<j>¶
For example, if the client wants to query the content of the first update item (0 -> 101), it can send a request to "/tips/2718281828459/ug/0/101".¶
If the request is valid (ug/<i>/<j> exists), the response is encoded as a JSON object whose data format is indicated by the media type.¶
It is possible that a client conducts proactive fetching of future updates, by long pulling updates that have not been listed in the directory yet. For long-pull prefetch, the client must have indicated the media type which may appear. It is RECOMMENDED that the server allows for at least the prefetch of <end-seq> -> <end-seq + 1>¶
Hence, the server processing logic SHOULD be:¶
It is RECOMMENDED that the server uses the following HTTP codes to indicate errors, with the media type "application/alto-error+json", regarding update item requests.¶
Assume the client wants to get the contents of the update item on edge 0 to 101. The request is:¶
GET /tips/2718281828459/ug/0/101 HTTP/1.1 Host: alto.example.com Accept: application/alto-costmap+json, application/alto-error+json¶
And the response will be¶
HTTP/1.1 200 OK Content-Type: application/alto-costmap+json Content-Length: 50 { ... full replacement of my-routingcost-map ... }¶
TIPS allows an ALTO client to receive an update item pushed by the ALTO server.¶
If a client registers for server push, it should not request updates via pull to avoid receiving the same information twice, unless the client does not receive the expected updates (see Section 8.4).¶
A client starts to receive server push when it is added to the receiver set. A client can read the status of the push state and remove itself from the receiver set to stop server push.¶
A client can add itself explicitly to the receiver set or add itself to the receiver set when requesting the TIPS view.¶
Explicit add: A client can explicitly add itself in the receiver set by using the HTTP PUT method with media type "application/alto-tipsview+json", where the client may optionally specify a starting edge (next-edge) from which it would like to receive updates:¶
PUT /<tips-view-uri>/push object { Boolean server-push; [NextEdge next-edge;] } PushState; object { JSONNumber seq-i; JSONNumber seq-j; } NextEdge;¶
with the following fields:¶
Set to true if the client desires to receive server push updates.¶
Optional field to request a starting edge to be pushed if the client has pulled the updates graph directory and has calculated the path it desires to take. The server is MAY push this edge first if available.¶
Short cut add: When requesting a TIPS view, an ALTO client can start server push by setting the option "server-push" field to be true using the HTTP POST method defined in Section 4.1.¶
Example of a client requesting a TIPS view and starting server push:¶
Client -> server request HEADERS - END_STREAM + END_HEADERS :method = POST :scheme = https :path = /tips host = alto.example.com accept = application/alto-error+json, application/alto-tips+json content-type = application/alto-tips+json content-length = 69 DATA - END_STREAM { "resource-id": "my-routingcost-map", ["server-push": true] } Server -> client response: HEADERS - END_STREAM + END_HEADERS :status = 200 content-type = application/alto-tips+json content-length = 196 DATA - END_STREAM { "tips-view-uri": "/tips/2718281828459", "tips-view-summary": { "updates-graph-summary": { "start-seq": 101, "end-seq": 106, "start-edge-rec" : { "seq-i": 0, "seq-j": 105 } }, "server-push": true } }¶
A client can use the HTTP GET method, with accept header set to "application/alto-tipsview+json" (defined in Section 7.1.1) to check the status of server push.¶
GET /<tips-view-uri>/push¶
Example:¶
Client -> server request HEADERS - END_STREAM + END_HEADERS :method = GET :scheme = https :path = /tips/2718281828459/push host = alto.example.com accept = application/alto-error+json, application/alto-tipsview+json Server -> client response: HEADERS - END_STREAM + END_HEADERS :status = 200 content-type = application/alto-tipsview+json content-length = 519 DATA - END_STREAM { "server-push": true; "next-edge": { "seq-i": 0, "seq-j": 105 } }¶
A client can stop receiving server push updates either explicitly or implicitly.¶
Explicit stop: A client stops push by using the HTTP PUT method to /<tips-view-uri>/push, with content type "application/alto-tipsview+json" and setting server-push to FALSE:¶
Implicit stop: (1) TIPS view is connection ephemeral: the close of connection or stream for the TIPS view deletes the TIPS view from the view of the client. (2) The client sends a DELETE /<tips-view-uri> request, indicating it no longer is interested in the resource, which also deletes the client from the push receiver set if present.¶
Note that a client may choose to explicitly stop server push for a resource, but may not delete the TIPS view so that it can switch seemlessly from server push to client pull in the case that the server push frequency is undesirable, without having to request a new TIPS view.¶
Example of explicit stop:¶
Client -> server request HEADERS - END_STREAM + END_HEADERS :method = PUT :scheme = https :path = /tips/2718281828459/push host = alto.example.com accept = application/alto-error+json content-type = application/alto-tipsview+json content-length = 69 DATA - END_STREAM { "server-push": false } Server-> client response HEADERS - END_STREAM + END_HEADERS :status = 200¶
The objective of the server is to push the latest version to the client using the lowest cost (sum of size) of the updates. Hence, it is RECOMMENDED that the server computes the push path using the following algorithm, upon each event computing a push:¶
Note¶
Using the example updates graph in Section 2.1, a client can wait on the server for incremental push, where the server first sends PUSH_PROMISE:¶
Server -> client PUSH_PROMISE in current stream: PUSH_PROMISE - END_STREAM Promised Stream 4 HEADER BLOCK :method = GET :scheme = https :path = /tips/2718281828459/ug/0/101 host = alto.example.com accept = application/alto-error+json, application/alto-costmap+json Server -> client content Stream 4: HEADERS + END_STREAM + END_HEADERS :status = 200 content-type = application/alto-costmap+json content-length = 539 DATA + END_STREAM { "meta" : { "dependent-vtags" : [{ "resource-id": "my-network-map", "tag": "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785" }], "cost-type" : { "cost-mode" : "numerical", "cost-metric": "routingcost" }, "vtag": { "resource-id" : "my-routingcost-map", "tag" : "3ee2cb7e8d63d9fab71b9b34cbf764436315542e" } }, "cost-map" : { "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, "PID3": { "PID1": 20, "PID2": 15 } } } Server -> client PUSH_PROMISE in current stream: PUSH_PROMISE - END_STREAM Promised Stream 6 HEADER BLOCK :method = GET :scheme = https :path = /tips/2718281828459/ug/101/102 host = alto.example.com accept = application/alto-error+json, application/merge-patch+json Server -> client content Stream 6 HEADERS + END_STREAM + END_HEADERS :status = 200 content-type = application/merge-patch+json content-length = 7 DATA + END_STREAM { "meta": { "vtag": { "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d" } }, "cost-map": { "PID1": { "PID2": 9 }, "PID3": { "PID1": null, "PID3": 1 } } }¶
The server push MUST satisfy the following requirements:¶
TIPS allow clients to make concurrent pulls of the incremental updates potentianlly through different HTTP connections. As a consequence, it introduces additional complexties when the ALTO server is being load balanced -- a feature widely used to build scalable and fault-tolerant web services. For example, a request may be incorrectly processed if¶
Thus, additional considerations are required to enable correct load balancing for TIPS, including:¶
TIPS should be cognizant of the effects of its update schedule, which includes both the choice of timing (i.e., when/what to trigger an update on the updates graph) and the choice of message format (i.e., given an update, send a full replacement or an incremental change). In particular, the update schedule can have effects on both the overhead and the freshness of information. To minimize overhead, TIPS may choose to batch a sequence of updates for resources that frequently change by cumulative updates or a full replacement after a while. TIPS should be cognizant that batching reduces the freshness of information. The server should also consider the effect of such delays on client behaviors.¶
For incremental updates, this design allows both JSON patch and JSON merge patch for incremental changes. JSON merge patch is clearly superior to JSON patch for describing incremental changes to cost maps, endpoint costs, and endpoint properties. For these data structures, JSON merge patch is more space efficient, as well as simpler to apply. There is no advantage allowing a server to use JSON patch for those resources.¶
The case is not as clear for incremental changes to network maps.¶
First, consider small changes, such as moving a prefix from one PID to another. JSON patch could encode that as a simple insertion and deletion, while JSON merge patch would have to replace the entire array of prefixes for both PIDs. On the other hand, to process a JSON patch update, the ALTO client would have to retain the indexes of the prefixes for each PID. Logically, the prefixes in a PID are an unordered set, not an array; aside from handling updates, a client has no need to retain the array indexes of the prefixes. Hence, to take advantage of JSON patch for network maps, ALTO clients would have to retain additional, otherwise unnecessary, data.¶
Second, consider more involved changes, such as removing half of the prefixes from a PID. JSON merge patch would send a new array for that PID, while JSON patch would have to send a list of remove operations and delete the prefix one by one.¶
Therefore, each TIPS may decide on its own whether to use JSON merge patch or JSON patch according to the changes in network maps.¶
Dependent ALTO resources result in cross-resource dependenies in TIPS. Consider the following pair of resources, where my-cost-map is dependent on my-network-map:¶
In pull-mode, a client can decide the order in which to receive the updates.¶
In push-mode, the server must decide. Pushing order may affect how fast the client can build a consistent view and how long the client needs to buffer the update.¶
Therefore, the server is RECOMMENDED to push updates in the ascending order of the smallest dependent tag, e.g., {C1, C2, N1} before {C3, N2}¶
In general, when an ALTO client receives a full replacement for a resource, the ALTO client should replace the current version with the new version. When an ALTO client receives an incremental change for a resource, the ALTO client should apply those patches to the current version of the resource.¶
However, because resources can depend on other resources (e.g., cost maps depend on network maps), an ALTO client MUST NOT use a dependent resource if the resource on which it depends has changed. There are at least two ways an ALTO client can do that. The following paragraphs illustrate these techniques by referring to network and cost map messages, although these techniques apply to any dependent resources.¶
Note that when a network map changes, the server SHOULD send the network map update message before sending the updates for the dependent cost maps.¶
One approach is for the ALTO client to save the network map update message in a buffer and continue to use the previous network map and the associated cost maps until the ALTO client receives the update messages for all dependent cost maps. The ALTO client then applies all network and cost map updates atomically.¶
Alternatively, the ALTO client MAY update the network map immediately. In this case, the cost maps using the network map become invalid because they are inconsistent with the current network map; hence, the ALTO client MUST mark each such dependent cost map as temporarily invalid and MUST NOT use each such cost map until the ALTO client receives a cost map update indicating that it is based on the new network map version tag.¶
When implementing server push, the server SHOULD send updates for dependent resource (i.e., the cost maps in the preceding example) in a timely fashion. However, if the ALTO client does not receive the expected updates, a simple recovery method is that the ALTO client uses client pull to request the missing update. The ALTO client MAY retain the version tag of the last version of any tagged resources and search those version tags when identifying the new updates to pull. Although not as efficient as possible, this recovery method is simple and reliable.¶
If TIPS provides updates to a Filtered Cost Map that allows constraint tests, then an ALTO client MAY request updates to a Filtered Cost Map request with a constraint test. In this case, when a cost changes, the updates graph MUST have an update if the new value satisfies the test. If the new value does not, whether there is an update depends on whether the previous value satisfied the test. If it did not, the updates graph SHOULD NOT have an update. But if the previous value did, then the updates graph MUST add an update with a "null" value to inform the ALTO client that this cost no longer satisfies the criteria.¶
TIPS can avoid having to handle such a complicated behavior by offering TIPS only for Filtered Cost Maps that do not allow constraint tests.¶
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 TIPS to offer incremental updates for ordinal mode cost maps, TIPS implementors should be aware that incremental updates for ordinal costs are more complicated than for numerical costs, and ALTO clients should be aware that small changes may result in large updates.¶
A TIPS can avoid this complication by only offering full replacements as updates in the updates graph for ordinal cost maps.¶
The security considerations (Section 15 of [RFC7285]) of the base protocol fully apply to this extension. For example, the same authenticity and integrity considerations (Section 15.1 of [RFC7285]) still fully apply; the same considerations for the privacy of ALTO users (Section 15.4 of [RFC7285]) also still fully apply.¶
The additional services (addition of update read service and update push service) provided by this extension extend the attack surface described in Section 15.1.1 of [RFC7285]. Below, we discuss the additional risks and their remedies.¶
Allowing TIPS views enables a new class of Denial-of-Service attacks. In particular, For the TIPS server, an ALTO client might create an unreasonable number of TIPS views.¶
To avoid these attacks on the TIPS server, the server SHOULD choose to limit the number of active views and reject new requests when that threshold is reached. TIPS allows predictive fetching and the server SHOULD also choose to limit the number of pending requests. In these cases, the server SHOULD return the HTTP status "429 Too many requests".¶
It is important to note that the preceding approaches are not the only possibilities. For example, it may be possible for TIPS to use somewhat more clever logic involving IP reputation, rate-limiting, and compartmentalization of the overall threshold into smaller thresholds that apply to subsets of potential clients.¶
The availability of continuous updates, when the client indicates receiving server push, can also cause overload for an ALTO client, in particular, an ALTO client with limited processing capabilities. The current design does not include any flow control mechanisms for the client to reduce the update rates from the server. Under overloading, the client MAY choose to remove the information resources with high update rates.¶
Also, under overloading, the client may no longer be able to detect whether information is still fresh or has become stale. In such a case, the client should be careful in how it uses the information to avoid stability or efficiency issues.¶
An outside party that can read the TIPS response or that can observe TIPS requests can obtain the TIPS view URI and use that to send fraudulent "DELETE" requests, thus disabling the service for the valid ALTO client. This can be avoided by encrypting the requests and responses (see Section 15 of [RFC7285]).¶
IANA is requested to register the following media type under ALTO registry as defined in [RFC7285]:¶
The authors of this document would also like to thank Adrian Farrel, Qin Wu, Jordi Ros Giralt, and the many others who reviewed and commented on previous drafts of this document.¶