idnits 2.17.1 draft-ietf-alto-incr-update-sse-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC7285]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 572 has weird spacing: '...atesReq add;...' -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: 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 ([RFC7230]), the client MAY send multiple HTTP requests on the same TCP/IP connection. -- The document date (March 12, 2017) is 2602 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Name' is mentioned on line 328, but not defined == Unused Reference: 'RFC7232' is defined on line 1725, but no explicit reference was found in the text == Unused Reference: 'RFC7233' is defined on line 1728, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 1731, but no explicit reference was found in the text == Unused Reference: 'RFC7235' is defined on line 1735, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Possible downref: Non-RFC (?) normative reference: ref. 'SSE' Summary: 10 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ALTO WG W. Roome 3 Internet-Draft Nokia Bell Labs 4 Intended status: Standards Track Y. Yang 5 Expires: September 13, 2017 Tongji/Yale University 6 March 12, 2017 8 ALTO Incremental Updates Using Server-Sent Events (SSE) 9 draft-ietf-alto-incr-update-sse-04 11 Abstract 13 The Application-Layer Traffic Optimization (ALTO) [RFC7285] protocol 14 provides network related information to client applications so that 15 clients may make informed decisions. To that end, an ALTO Server 16 provides Network and Cost Maps. Using those maps, an ALTO Client can 17 determine the costs between endpoints. 19 However, the ALTO protocol does not define a mechanism to allow an 20 ALTO client to obtain updates to those maps, other than by 21 periodically re-fetching them. Because the maps may be large 22 (potentially tens of megabytes), and because only parts of the maps 23 may change frequently (especially Cost Maps), that can be extremely 24 inefficient. 26 Therefore this document presents a mechanism to allow an ALTO Server 27 to provide updates to ALTO Clients. Updates can be both immediate, 28 in that the server can send updates as soon as they are available, 29 and incremental, in that if only a small section of a map changes, 30 the server can send just the changes. 32 Requirements Language 34 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 35 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 36 document are to be interpreted as described in RFC 2119 [RFC2119]. 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on September 13, 2017. 55 Copyright Notice 57 Copyright (c) 2017 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 2. Overview of Approach . . . . . . . . . . . . . . . . . . . . 4 74 3. Changes Since Version -01 . . . . . . . . . . . . . . . . . . 5 75 4. Overview of Server-Sent Events (SSEs) . . . . . . . . . . . . 5 76 5. Incremental Update Message Format . . . . . . . . . . . . . . 6 77 5.1. Overview of JSON Merge Patch . . . . . . . . . . . . . . 7 78 5.2. JSON Merge Patch Applied to Network Map Messages . . . . 8 79 5.3. JSON Merge Patch Applied to Cost Map Messages . . . . . . 10 80 6. ALTO Event Stream . . . . . . . . . . . . . . . . . . . . . . 11 81 6.1. ALTO Event Format . . . . . . . . . . . . . . . . . . . . 11 82 6.2. ALTO Update Events . . . . . . . . . . . . . . . . . . . 12 83 6.3. ALTO Control Events . . . . . . . . . . . . . . . . . . . 12 84 7. Update Stream Service . . . . . . . . . . . . . . . . . . . . 13 85 7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 13 86 7.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 13 87 7.3. Accept Input Parameters . . . . . . . . . . . . . . . . . 13 88 7.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . 15 89 7.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 16 90 7.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 16 91 7.6.1. Keep-Alive Messages . . . . . . . . . . . . . . . . . 16 92 7.6.2. Event Sequence Requirements . . . . . . . . . . . . . 16 93 7.6.3. Cross-Stream Consistency Requirements . . . . . . . . 17 94 8. Update Stream Controller . . . . . . . . . . . . . . . . . . 18 95 8.1. URI . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 96 8.2. Media Type . . . . . . . . . . . . . . . . . . . . . . . 19 97 8.3. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 19 98 8.4. Accept Input Parameters . . . . . . . . . . . . . . . . . 19 99 8.5. Capabilities & Uses . . . . . . . . . . . . . . . . . . . 20 100 8.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 20 101 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 20 102 9.1. Example: Simple Network and Cost Map Updates . . . . . . 20 103 9.2. Example: Advanced Network and Cost Map Updates . . . . . 22 104 9.3. Example: Endpoint Property Updates . . . . . . . . . . . 24 105 9.4. IRD Example . . . . . . . . . . . . . . . . . . . . . . . 28 106 10. Client Actions When Receiving Update Messages . . . . . . . . 30 107 11. Design Decisions and Discussions . . . . . . . . . . . . . . 31 108 11.1. HTTP/2 Server-Push . . . . . . . . . . . . . . . . . . . 31 109 11.2. Not Allowing Stream Restart . . . . . . . . . . . . . . 32 110 11.3. Is Incremental Update Useful for Network Maps? . . . . . 33 111 11.4. Other Incremental Update Message Types . . . . . . . . . 34 112 12. Miscellaneous Considerations . . . . . . . . . . . . . . . . 34 113 12.1. Considerations For Updates To Filtered Cost Maps . . . . 34 114 12.2. Considerations For Incremental Updates To Ordinal Mode 115 Costs . . . . . . . . . . . . . . . . . . . . . . . . . 35 116 12.3. Considerations Related to SSE Line Lengths . . . . . . . 35 117 13. Security Considerations . . . . . . . . . . . . . . . . . . . 36 118 13.1. Denial-of-Service Attacks . . . . . . . . . . . . . . . 36 119 13.2. Spoofed Control Requests . . . . . . . . . . . . . . . . 36 120 13.3. Privacy . . . . . . . . . . . . . . . . . . . . . . . . 36 121 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 122 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 123 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 40 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 126 1. Introduction 128 The Application-Layer Traffic Optimization (ALTO) [RFC7285] protocol 129 provides network related information to client applications so that 130 clients may make informed decisions. To that end, an ALTO Server 131 provides Network and Cost Maps, where a Network Map partitions the 132 set of endpoints into a manageable number of Provider-Defined 133 Identifiers (PIDs), and a Cost Map provides directed costs between 134 PIDs. Given Network and Cost Maps, an ALTO Client can obtain costs 135 between endpoints by using the Network Map to get the PID for each 136 endpoint, and then using the Cost Map to get the costs between those 137 PIDs. 139 However, the ALTO protocol does not define a mechanism to allow a 140 client to obtain updates to those maps, other than by periodically 141 re-fetching them. Because the maps may be large (potentially tens of 142 megabytes), and because parts of the maps may change frequently 143 (especially Cost Maps), that can be extremely inefficient. 145 Therefore this document presents a mechanism to allow an ALTO Server 146 to provide incremental updates to ALTO Clients. Updates can be both 147 immediate, in that the server can send updates as soon as they are 148 available, and incremental, in that if only a small section of a map 149 changes, the server can send just the changes. 151 While primarily intended to provide updates to GET-mode Network and 152 Cost Maps, the mechanism defined in this document can also provide 153 updates to other ALTO resource, including POST-mode services such as 154 Endpoint Property and Endpoint Cost Services, as well as potentially 155 new ALTO services to be defined by future extensions. 157 The rest of this document is organized as follows. Section 2 gives 158 an overview of the incremental update approach, which is based on 159 Server-Sent Events (SSEs). Section 4 and Section 5 give SSEs and 160 JSON Merge Patch, the technologies on which ALTO updates are based. 161 Section 6 defines the update events, Section 7 and Section 8 define 162 the update services themselves, and Section 9 gives several examples. 163 Section 10 describes how a client should handle incoming updates. 164 Section 11 and Section 12 discuss the design decisions behind this 165 update mechanism and other considerations. The remaining sections 166 review the security and IANA considerations. 168 2. Overview of Approach 170 This section presents a non-normative overview of the update 171 mechanism to be defined in this document. 173 An ALTO Server can offer one or more Update Stream resources, where 174 each Update Stream resource (or Update Stream for short) is a POST- 175 mode service that returns a continuous sequence of update messages 176 for one or more ALTO resources. An Update Stream can provide updates 177 to both GET-mode resources, such as Network and Cost Maps, and POST- 178 mode resources, such as Endpoint Property Services. 180 Each update message updates one resource, and is sent as a Server- 181 Sent Event (SSE), as defined by [SSE]. An update message is either a 182 full replacement or an incremental change. A full-replacement update 183 uses the JSON message format defined by the ALTO protocol; an 184 incremental-update uses JSON Merge Patch ([RFC7396]) to describe the 185 changes to the resource. The ALTO Server decides when to send update 186 messages, and whether to send full replacements or incremental 187 updates. These decisions can vary from resource to resource and from 188 update to update. 190 An ALTO Server may offer any number of Update Stream resources, for 191 any subset of the server's resources. An ALTO Server's Information 192 Resource Directory (IRD) defines the Update Stream resources, and 193 declares the set of resources for which each Update Stream provides 194 updates. The server selects the resource set for each stream. It is 195 recommended that if a resource depends on one or more other 196 resource(s) (indicated with the "uses" attribute defined in 197 [RFC7285]), these other resource(s) should also be part of that 198 stream. Thus the Update Stream for a Cost Map should also provide 199 updates for the Network Map on which that Cost Map depends. 201 When an ALTO Client requests an Update Stream resource, the client 202 establishes a new persistent connection to the server. The server 203 responds by sending an event with the URI of a stream-control 204 resource for this update stream. The control URI allows a client to 205 modify the newly-created update stream. For example, the client can 206 ask the server to send update events for additional resources, to 207 stop sending update events for previously requested resources, or to 208 gracefully stop and close the update stream altogether. 210 A client may request any number of Update Streams simultaneously. 211 Because each stream consumes resources on the server, a server may 212 limit the number of open Update Streams, may close inactive streams, 213 may provide Update Streams via other processors, or may require 214 client authorization/authentication. 216 3. Changes Since Version -01 218 o Defined a new "Stream Control" resource (Section 8) to allow 219 clients to add or remove resources from a previously created 220 Update Stream. The ALTO Server creates a new Stream Control 221 resource for each Update Stream instance, assigns a unique URI to 222 it, and sends the URI to the client as the first event in the 223 stream. 225 o The client now assigns a unique client-id to each resource in an 226 update stream. The server puts the client-id in each update event 227 for that resource (before, the server used the server's resource- 228 id). This allows a client to use one stream to get updates to two 229 different Endpoint Cost requests (before, that required two 230 separate streams). 232 4. Overview of Server-Sent Events (SSEs) 234 The following is a non-normative summary of Server-Sent Events 235 (SSEs); see [SSE] for its normative definition. 237 Server-Sent Events enable a server to send new data to a client by 238 "server-push". The client establishes an HTTP ([RFC7230], [RFC7231]) 239 connection to the server, and keeps the connection open. The server 240 continually sends messages. Each message has one or more lines, 241 where a line is terminated by a carriage-return immediately followed 242 by a new-line, a carriage-return not immediately followed by a new- 243 line, or a new-line not immediately preceded by a carriage-return. A 244 message is terminated by a blank line (two line terminators in a 245 row). 247 Each line in a message is of the form "field-name: string value". 248 Lines with a blank field-name (that is, lines which start with a 249 colon) are ignored, as are lines which do not have a colon. The 250 protocol defines three field names: event, id, and data. If a 251 message has more than one "data" line, the value of the data field is 252 the concatenation of the values on those lines. There can be only 253 one "event" or "id" line per message. The "data" field is required; 254 the others are optional. 256 Figure 1 is a sample SSE stream, starting with the client request. 257 The server sends three events and then closes the stream. 259 (Client request) 260 GET /stream HTTP/1.1 261 Host: example.com 262 Accept: text/event-stream 264 (Server response) 265 HTTP/1.1 200 OK 266 Connection: keep-alive 267 Content-Type: text/event-stream 269 event: start 270 id: 1 271 data: hello there 273 event: middle 274 id: 2 275 data: let's chat some more ... 276 data: and more and more and ... 278 event: end 279 id: 3 280 data: good bye 282 Figure 1: A Sample SSE stream. 284 5. Incremental Update Message Format 285 5.1. Overview of JSON Merge Patch 287 The following is a non-normative summary of JSON Merge Patch. See 288 [RFC7396] for the normative definition. 290 JSON Merge Patch is intended to allow applications to update server 291 resources via the HTTP PATCH method [RFC5789]. This document adopts 292 the JSON Merge Patch message format to encode the changes, but uses a 293 different transport mechanism. 295 Informally, a Merge Patch object is a JSON data structure that 296 defines how to transform one JSON value into another. Merge Patch 297 treats the two JSON values as trees of nested JSON Objects 298 (dictionaries of name-value pairs), where the leaves are values other 299 than JSON Objects (e.g., JSON Arrays, Strings, Numbers, etc.), and 300 the path for each leaf is the sequence of keys leading to that leaf. 301 When the second tree has a different value for a leaf at a path, or 302 adds a new leaf, the Merge Patch tree has a leaf, at that path, with 303 the new value. When a leaf in the first tree does not exist in the 304 second tree, the Merge Patch tree has a leaf with a JSON "null" 305 value. The Merge Patch tree does not have an entry for any leaf that 306 has the same value in both versions. 308 As a result, if all leaf values are simple scalars, JSON Merge Patch 309 is a very efficient representation of the change. It is less 310 efficient when leaf values are arrays, because JSON Merge Patch 311 replaces arrays in their entirety, even if only one entry changes. 313 Formally, the process of applying a Merge Patch is defined by the 314 following recursive algorithm, as specified in [RFC7396]: 316 define MergePatch(Target, Patch) { 317 if Patch is an Object { 318 if Target is not an Object { 319 Target = {} # Ignore the contents and 320 # set it to an empty Object 321 } 322 for each Name/Value pair in Patch { 323 if Value is null { 324 if Name exists in Target { 325 remove the Name/Value pair from Target 326 } 327 } else { 328 Target[Name] = MergePatch(Target[Name], Value) 329 } 330 } 331 return Target 332 } else { 333 return Patch 334 } 335 } 337 Note that null as the value of a name/value pair will delete the 338 element with "name" in the original JSON value. 340 5.2. JSON Merge Patch Applied to Network Map Messages 342 Section 11.2.1.6 of [RFC7285] defines the format of a Network Map 343 message. Here is a simple example: 345 { 346 "meta" : { 347 "vtag": { 348 "resource-id" : "my-network-map", 349 "tag" : "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785" 350 } 351 }, 352 "network-map" : { 353 "PID1" : { 354 "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25" ] 355 }, 356 "PID2" : { 357 "ipv4" : [ "198.51.100.128/25" ] 358 }, 359 "PID3" : { 360 "ipv4" : [ "0.0.0.0/0" ], 361 "ipv6" : [ "::/0" ] 362 } 363 } 364 } 366 When applied to that message, the following Merge Patch update 367 message adds the ipv6 prefix "2001:db8:8000::/33" to "PID1", deletes 368 "PID2", and assigns a new "tag" to the Network Map: 370 { 371 "meta" : { 372 "vtag" : { 373 "tag" : "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe" 374 } 375 }, 376 "network-map": { 377 "PID1" : { 378 "ipv6" : [ "2001:db8:8000::/33" ] 379 }, 380 "PID2" : null 381 } 382 } 384 Here is the updated Network Map: 386 { 387 "meta" : { 388 "vtag": { 389 "resource-id" : "my-network-map", 390 "tag" : "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe" 391 } 392 }, 393 "network-map" : { 394 "PID1" : { 395 "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25" ], 396 "ipv6" : [ "2001:db8:8000::/33" ] 397 }, 398 "PID3" : { 399 "ipv4" : [ "0.0.0.0/0" ], 400 "ipv6" : [ "::/0" ] 401 } 402 } 403 } 405 5.3. JSON Merge Patch Applied to Cost Map Messages 407 Section 11.2.3.6 of [RFC7285] defines the format of a Cost Map 408 message. Here is a simple example: 410 { 411 "meta" : { 412 "dependent-vtags" : [ 413 {"resource-id": "my-network-map", 414 "tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe" 415 } 416 ], 417 "cost-type" : { 418 "cost-mode" : "numerical", 419 "cost-metric": "routingcost" 420 } 421 }, 422 "cost-map" : { 423 "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, 424 "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, 425 "PID3": { "PID1": 20, "PID2": 15 } 426 } 427 } 429 The following Merge Patch message updates the example cost map so 430 that PID1->PID2 is 9 instead of 5, PID3->PID1 is no longer available, 431 and PID3->PID3 is now defined as 1: 433 { 434 "cost-map" : { 435 "PID1" : { "PID2" : 9 }, 436 "PID3" : { "PID1" : null, "PID3" : 1 } 437 } 438 } 440 Here is the updated cost map: 442 { 443 "meta" : { 444 "dependent-vtags" : [ 445 {"resource-id": "my-network-map", 446 "tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe" 447 } 448 ], 449 "cost-type" : { 450 "cost-mode" : "numerical", 451 "cost-metric": "routingcost" 452 } 453 }, 454 "cost-map" : { 455 "PID1": { "PID1": 1, "PID2": 9, "PID3": 10 }, 456 "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, 457 "PID3": { "PID2": 15, "PID3": 1 } 458 } 459 } 461 6. ALTO Event Stream 463 The Update Stream service (Section 7) returns a stream of Update 464 Events (Section 6.2) and Control Events (Section 6.3). 466 6.1. ALTO Event Format 468 Update and Control Events have the same basic structure. The data 469 field is a JSON object, and the event field contains the media type 470 of the data field, and an optional client id. Update Events use the 471 client id to identify the ALTO resource to which the update message 472 applies. Client ids MUST follow the rules for ALTO ResourceIds (see 473 {10.2} of [RFC7285]. Client ids MUST be unique within an Update 474 Stream, but need not be globally unique. For example, if a client 475 requests updates for both a Cost Map and its Network Map, the client 476 might assign id "1" to the Network Map and "2" to the Cost Map. 477 Alternatively, the client could use the ALTO resource ids for those 478 two maps. 480 JSON specifications use the type ClientId for a client-id. 482 The two sub-fields of the event field are encoded as comma-separated 483 strings: 485 media-type [ ',' client-id ] 487 Note that media type names may not contain a comma (character code 488 0x2c). 490 The Update Stream Service does not use the SSE "id" field. 492 6.2. ALTO Update Events 494 The Update Stream Service sends an update event when a monitored 495 resource changes. The data is either a complete specification of the 496 resource, or else a JSON Merge Patch object describing the changes 497 from the last version. We will refer to these as full-replacement 498 and Merge Patch messages, respectively. The data objects in full- 499 replacement messages are defined by [RFC7285]; examples are Network 500 and Cost Map messages. They have the media types defined in that 501 document. The data objects in Merge Patch messages are defined by 502 [RFC7396], and they have the media type "application/merge- 503 patch+json", as defined by [RFC7396]. 505 Figure 2 shows some examples of ALTO update events: 507 event: application/alto-networkmap+json,1 508 data: { ... full Network Map message ... } 510 event: application/alto-costmap+json,2 511 data: { ... full Cost Map message ... } 513 event: application/merge-patch+json,2 514 data: { ... Merge Patch update for the Cost Map ... } 516 Figure 2: Examples of ALTO update events. 518 6.3. ALTO Control Events 520 Control events have the media type "application/alto- 521 updatestreamcontrol+json", and the data is of type 522 UpdateStreamControlEvent: 524 object { 525 [String control-uri;] 526 [String remove<1..*>;] 527 } UpdateStreamControlEvent; 529 The "control-uri" field is the URI of the Stream Control resource for 530 this Update Stream (Section 8). The ALTO server MUST send a control 531 event with that URI as the first event in an Update Stream. 533 The "remove" field is a list of client-ids of resources for which the 534 server will no longer send updates. The server sends this event 535 after processing a Stream Controller request to remove those 536 resources (Section 7.6.2). 538 7. Update Stream Service 540 An Update Stream returns a stream of SSE messages, as defined in 541 Section 6. An ALTO Server's IRD (Information Resource Directory) MAY 542 define one or more Update Stream resources, which clients use to 543 request new Update Stream instances. 545 When a server creates a new Update Stream, it also create a new 546 Stream Controller for that Update Stream. A client uses that Stream 547 Controller to remove resources from the Update Stream instance, or to 548 request updates for additional resources. A client cannot obtain the 549 Stream Controller through the IRD. Instead, the first event that the 550 server sends to the client has the URI for the associated controller 551 (see Section 6.3. 553 Section 8 describes the Stream Controller. 555 7.1. Media Type 557 The media type of an ALTO Update Stream resource is "text/event- 558 stream", as defined by [SSE]. 560 7.2. HTTP Method 562 An ALTO Update Stream is requested using the HTTP POST method. 564 7.3. Accept Input Parameters 566 An ALTO Client specifies the parameters for the new Update Stream by 567 sending an HTTP POST body with the media type "application/alto- 568 updatestreamparams+json". That body contains a JSON Object of type 569 UpdateStreamReq, where: 571 object { 572 [AddUpdatesReq add;] 573 [ClientId remove<0..*>;] 574 } UpdateStreamReq; 576 object-map { 577 ClientId -> AddUpdateReq; 578 } AddUpdatesReq; 580 object { 581 String resource-id; 582 [String tag;] 583 [Boolean incremental-updates;] 584 [Object input;] 585 } AddUpdateReq; 587 The "add" field specifies the resources for which the client wants 588 updates, and has one entry for each resource. The client creates a 589 unique client-id (Section 6.1) for each such resource, and uses those 590 client-ids as the keys in the "add" field. 592 An Update Stream request MUST have an "add" field specifying one or 593 more resources. If it does not, the server MUST return an 594 E_INVALID_FIELD_VALUE error response (see Section 8.5.2 of 595 [RFC7285]), and MUST close the stream without sending any events. 597 The "resource-id" field is the resource-id of an ALTO resource, and 598 MUST be in the Update Streams's "uses" list (see Section 7.5). If 599 any resource-id is invalid, or is not associated with this Update 600 Stream, the server MUST return an E_INVALID_FIELD_VALUE error 601 response (see Section 8.5.2 of [RFC7285]), and MUST close the stream 602 without sending any events. 604 If the resource-id is a GET-mode resource with a version tag (or 605 "vtag"), as defined in Sections 6.3 and 10.3 of [RFC7285], and if the 606 client has previously retrieved a version of that resource from the 607 server, the client MAY set the "tag" field to the tag part of the 608 client's version of that resource. If that version is not current, 609 the server MUST send a full-replacement update before sending any 610 incremental updates, as described in Section 7.6.2. If that version 611 is still current, the ALTO Server MAY omit the initial full- 612 replacement update. 614 If the "incremental-updates" field for a resource-id is "true", the 615 server MAY send incremental update events for this resource-id 616 (assuming the server supports incremental updates for that resource; 617 see Section 7.4). If the "incremental-updates" field is "false", the 618 ALTO Server MUST NOT send incremental update events for that 619 resource. In this case, whenever a change occurs, the server MUST 620 send a full-replacement update instead of an incremental update. The 621 server MAY wait until more changes are available, and send a single 622 full-replacement update with those changes. Thus an ALTO Client 623 which declines to accept incremental updates may not get updates as 624 quickly as a client which does. 626 The default for "incremental-updates" is "true", so to suppress 627 incremental updates, the client MUST explicitly set "incremental- 628 updates" to "false". Note that the client cannot suppress full- 629 replacement update events. 631 If the resource is a POST-mode service which requires input, the 632 client MUST set the "input" field to a JSON Object with the 633 parameters that resource expects. If the "input" field is missing or 634 invalid, the ALTO Server MUST return the same error response that 635 that resource would return for missing or invalid input (see 636 [RFC7285]). In this case, the server MUST close the Update Stream 637 without sending any events. If the inputs for several POST-mode 638 resources are missing or invalid, the server MUST pick one error 639 response and return it. 641 The "remove" field is used in Stream Controller requests (see 642 Section 8), and is not allowed in the Update Stream request. If the 643 "remove" field exists, the server MUST return an 644 E_INVALID_FIELD_VALUE error response (see Section 8.5.2 of 645 [RFC7285]), and MUST close the stream without sending any events. 647 7.4. Capabilities 649 The capabilities are defined by an object of type 650 UpdateStreamCapabilities: 652 object { 653 IncrementalUpdateMediaTypes incremental-update-media-types; 654 } UpdateStreamCapabilities; 656 object-map { 657 ResourceID -> String; 658 } IncrementalUpdateMediaTypes; 660 If this Update Stream can provide incremental update events for a 661 resource, the "incremental-update-media-types" field has an entry for 662 that resource-id, and the value is the media-type of the incremental 663 update message. Normally this will be "application/merge- 664 patch+json", because, as described in Section 6, JSON Merge Patch is 665 the only incremental update event type defined by this document. 667 However future extensions may define other types of incremental 668 updates. 670 7.5. Uses 672 The "uses" attribute MUST be an array with the resource-ids of every 673 resource for which this stream can provide updates. 675 This set may be any subset of the ALTO Server's resources, and may 676 include resources defined in linked IRDs. However, it is RECOMMENDED 677 that the ALTO Server select a set that is closed under the resource 678 dependency relationship. That is, if an Update Stream's "uses" set 679 includes resource R1, and resource R1 depends on ("uses") resource 680 R0, then the Update Stream's "uses" set should include R0 as well as 681 R1. For example, an Update Stream for a Cost Map SHOULD also provide 682 updates for the Network Map upon which that Cost Map depends. 684 7.6. Response 686 The response is a stream of SSE update events. Section 6 defines the 687 events, and [SSE] defines how they are encoded into a stream. 689 An ALTO server SHOULD send updates only when the underlying values 690 change. However, it may be difficult for a server to guarantee that 691 in all circumstances. Therefore a client MUST NOT assume that an SSE 692 update event represents an actual change. 694 There are additional requirements on the server's response, as 695 described below. 697 7.6.1. Keep-Alive Messages 699 In an SSE stream, any line which starts with a colon (U+003A) 700 character is a comment, and an ALTO Client MUST ignore that line 701 ([SSE]). As recommended in [SSE], an ALTO Server SHOULD send a 702 comment line (or an event) every 15 seconds to prevent clients and 703 proxy servers from dropping the HTTP connection. 705 7.6.2. Event Sequence Requirements 707 o The first event MUST be a control event with the URI of the Stream 708 Controller (Section 8) for this Update Stream (Section 6.3). 710 o As soon as possible after the client initiates the connection, the 711 ALTO Server MUST send a full-replacement update event for each 712 resource-id requested by the client. The only exception is for a 713 GET-mode resource with a version tag. In this case the server MAY 714 omit the initial full-replacement event for that resource if the 715 "tag" field the client provided for that resource-id matches the 716 tag of the server's current version. 718 o If this stream provides updates for resource-ids R0 and R1, and if 719 R1 depends on R0, then the ALTO Server MUST send the update for R0 720 before sending the related update for R1. For example, suppose a 721 stream provides updates to a Network Map and its dependent Cost 722 Maps. When the Network Map changes, the ALTO Server MUST send the 723 Network Map update before sending the Cost Map updates. 725 o If this stream provides updates for resource-ids R0 and R1, and if 726 R1 depends on R0, then the ALTO Server SHOULD send an update for 727 R1 as soon as possible after sending the update for R0. For 728 example, when a Network Map changes, the ALTO Server SHOULD send 729 update events for the dependent Cost Maps as soon as possible 730 after the update event for the Network Map. 732 o When the client uses the Stream Controller to stop updates for one 733 or more resources (Section 8), the ALTO Server MUST send a control 734 event (Section 6.3) whose "remove" field has the client-ids of 735 those resources. If the client uses the Stream Controller to 736 terminate all active resources and close the stream, the server 737 MUST send a control event whose "remove" field has the client-ids 738 of all active resources. 740 7.6.3. Cross-Stream Consistency Requirements 742 If several clients create Update Streams for updates to the same 743 resource, the server MUST send the same updates to all of them. 744 However, the server MAY pack data items into different Merge Patch 745 events, as long as the net result of applying those updates is the 746 same. 748 For example, suppose two different clients create Update Streams for 749 the same Cost Map, and suppose the ALTO Server processes three 750 separate cost point updates with a brief pause between each update. 751 The server MUST send all three new cost points to both clients. But 752 the server MAY send a single Merge Patch event (with all three cost 753 points) to one client, while sending three separate Merge Patch 754 events (with one cost point per event) to the other client. 756 A server MAY offer several different Update Stream resources that 757 provide updates to the same underlying resource (that is, a resource- 758 id may appear in the "uses" field of more than one Update Stream 759 resource). In this case, those Update Stream resources MUST return 760 the same update data. 762 8. Update Stream Controller 764 An Update Stream Controller allows a client to remove resources from 765 the set of resources that are monitored by an Update Stream, or add 766 additional resources to that set. The controller also allows a 767 client to gracefully shutdown an Update Stream. 769 The Stream Controller is not obtained from the ALTO Server's IRD. 770 Instead, when a client requests a new Update Stream, the server 771 creates a new controller for that stream, and sends its URI to the 772 client as the first event in the Update Stream (Section 7.6.2). 774 As described below, each control request adds resources to the set of 775 monitored resources, or removes previously added resources, or does 776 both. Each control request is a separate HTTP request; the client 777 MAY NOT stream multiple control requests in one HTTP request. 778 However, if the client and server support HTTP Keep-Alive 779 ([RFC7230]), the client MAY send multiple HTTP requests on the same 780 TCP/IP connection. 782 8.1. URI 784 The URI for a Stream Controller, by itself, MUST uniquely specify the 785 Update Stream instance which it controls. The server MUST NOT use 786 other properties of an HTTP request, such as cookies or the client's 787 IP address, to determine the Update Stream. Furthermore, a server 788 MUST NOT re-use a controller URI once the associated Update Stream 789 has been closed. 791 The client MUST evaluate a non-absolute controller URI (for example, 792 a URI without a host, or with a relative path) in the context of the 793 URI used to create the Update Stream. The controller's host MAY be 794 different from the Update Stream's host. 796 It is expected that the server will assign a unique stream id to each 797 Update Stream instance, and will embed that id in the associated 798 Stream Controller URI. However, the exact mechanism is left to the 799 server. Clients MUST NOT attempt to deduce a stream id from the 800 controller URI. 802 To prevent an attacker from forging a Stream Controller URI and 803 sending bogus requests to disrupt other Update Streams, Stream 804 Controller URIs SHOULD contain sufficient random redundency to make 805 it difficult to guess valid URIs. 807 8.2. Media Type 809 An ALTO Stream Controller response does not have a specific media 810 type. If a request is successful, the server returns an HTTP "204 No 811 Content" response. If a request is unsuccessful, the server returns 812 an ALTO error response (Section 8.5.2 of [RFC7285]) 814 8.3. HTTP Method 816 An ALTO Update Stream Controller request uses the POST method. 818 8.4. Accept Input Parameters 820 A Stream Controller accepts the same input media type and input 821 parameters as the Update Stream Service (Section 7.3). The only 822 difference is that a Stream Controller also accepts the "remove" 823 field. 825 If specified, the "remove" field is an array of client-ids the client 826 previously added to this Update Stream. An empty "remove" array is 827 equivalent to a list of all currently active resources; the server 828 responds by removing all resources and closing the stream. 830 A client MAY use the "add" field to add additional resources. 831 However, the client MUST assign a unique client-id to each resource. 832 Client-ids MUST be unique over the lifetime of this Update Stream: a 833 client MUST NOT re-use a previously removed client-id. 835 If a request has any error, the server MUST NOT add or remove any 836 resources from the associated Update Stream. In particular, 838 o Each "add" request must satisfy the requirements in Section 7.3. 839 If not, the server MUST return the error response defined in 840 Section 7.3. 842 o As described in Section 7.6.2, for each "add" request, the ALTO 843 Server MUST send a full-replacement update event for that resource 844 before sending any incremental updates. The only exception is for 845 a GET-mode resource with a version tag. In this case the server 846 MAY omit the full-replacement event for that resource if the "tag" 847 field the client provided matches the server's current version. 849 o The server MUST return an E_INVALID_FIELD_VALUE error if a client- 850 id in the "remove" field was not added in a prior request. Thus 851 it is illegal to "add" and "remove" the same client-id in the same 852 request. However, it is legal to remove a client-id twice. 854 o The server MUST return an E_INVALID_FIELD_VALUE error if a client- 855 id in the "add" field has been used before in this stream. 857 o The server MUST return an E_INVALID_FIELD_VALUE error if the 858 request has a non-empty "add" field and a "remove" field with an 859 empty list of client-ids (to replace all active resources with a 860 new set, the client MUST explicitly enumerate the client-ids to be 861 removed). 863 o If the associated Update Stream has been closed, the server MUST 864 return either an ALTO E_INVALID_FIELD_VALUE error, or else an HTTP 865 error, such as "404 Not Found". 867 8.5. Capabilities & Uses 869 None (Stream Controllers do not appear in the IRD). 871 8.6. Response 873 If a request is successful, the server returns an HTTP "204 No 874 Content" response with no data. If there are any errors, the server 875 MUST return the appropriate error code, and MUST NOT add or remove 876 any resources from the Update Stream. Thus control requests are 877 atomic: they cannot partially succeed. 879 The server MUST process the "add" field before the "remove" field. 880 If the request removes all active resources without adding any 881 additional resources, the server MUST close the Update Stream. Thus 882 an Update Stream cannot have zero resources. 884 Whenever a server removes resources as a result of a Stream 885 Controller request, the server MUST send the corresponding "remove" 886 Control Events (Section 6.3) on the Update Stream. If one control 887 request removes several resources, the server MAY send one Control 888 Event for all those resources, or a separate event for each removed 889 resource, or any combination thereof. 891 9. Examples 893 9.1. Example: Simple Network and Cost Map Updates 895 Here is an example of a client's request and the server's immediate 896 response, using the Update Stream resource "update-my-costs" defined 897 in the IRD in Section 9.4. The client requests updates for the 898 Network Map and "routingcost" Cost Map, but not for the "hopcount" 899 Cost Map. The client uses the server's resource-ids as the client- 900 ids. Because the client does not provide a "tag" for the Network 901 Map, the server must send a full update for the Network Map as well 902 as for the Cost Map. The client does not set "incremental-updates" 903 to "false", so it defaults to "true". Thus server will send Merge 904 Patch updates for the Cost Map, but not for the Network Map, because 905 this Update Stream resource does not provide incremental updates for 906 the Network Map. 908 POST /updates/costs HTTP/1.1 909 Host: alto.example.com 910 Accept: text/event-stream,application/alto-error+json 911 Content-Type: application/alto-updatestreamparams+json 912 Content-Length: ### 914 { "add": { 915 "my-network-map": { 916 "resource-id": "my-network-map" 917 }, 918 "my-routingcost-map": { 919 "resource-id": "my-routingcost-map" 920 } 921 } 922 } 924 HTTP/1.1 200 OK 925 Connection: keep-alive 926 Content-Type: text/event-stream 928 event: application/alto-updatestreamcontrol+json 929 data: {"control-uri": 930 data: "http://alto.example.com/updates/streams/3141592653589"} 932 event: application/alto-networkmap+json,my-network-map 933 data: { ... full Network Map message ... } 935 event: application/alto-costmap+json,my-routingcost-map 936 data: { ... full routingcost Cost Map message ... } 938 After sending those events immediately, the ALTO Server will send 939 additional events as the maps change. For example, the following 940 represents a small change to the Cost Map: 942 event: application/merge-patch+json,my-routingcost-map 943 data: {"cost-map": {"PID1" : {"PID2" : 9}}} 945 If a major change to the Network Map occurs, the ALTO Server MAY 946 choose to send full Network and Cost Map messages rather than Merge 947 Patch messages: 949 event: application/alto-networkmap+json,my-network-map 950 data: { ... full Network Map message ... } 952 event: application/alto-costmap+json,my-routingcost-map 953 data: { ... full Cost Map message ... } 955 9.2. Example: Advanced Network and Cost Map Updates 957 This example is similar to the previous one, except that the client 958 requests updates for the "hopcount" Cost Map as well as the 959 "routingcost" Cost Map, and provides the current version tag of the 960 Network Map, so the server is not required to send the full Network 961 Map update event at the beginning of the stream. In this example, 962 the client uses the client-ids "net", "routing" and "hops" for those 963 resources. The ALTO Server sends the stream id and the full Cost 964 Maps, followed by updates for the Network Map and Cost Maps as they 965 become available: 967 POST /updates/costs HTTP/1.1 968 Host: alto.example.com 969 Accept: text/event-stream,application/alto-error+json 970 Content-Type: application/alto-updatestreamparams+json 971 Content-Length: ### 973 { "add": { 974 "net": { 975 "resource-id": "my-network-map". 976 "tag": "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe" 977 }, 978 "routing": { 979 "resource-id": "my-routingcost-map" 980 }, 981 "hops": { 982 "resource-id": "my-hopcount-map" 983 } 984 } 985 } 986 HTTP/1.1 200 OK 987 Connection: keep-alive 988 Content-Type: text/event-stream 990 event: application/alto-updatestreamcontrol+json 991 data: {"control-uri": 992 data: "http://alto.example.com/updates/streams/2718281828459"} 994 event: application/alto-costmap+json,routing 995 data: { ... full routingcost Cost Map message ... } 997 event: application/alto-costmap+json,hops 998 data: { ... full hopcount Cost Map message ... } 1000 (pause) 1002 event: application/merge-patch+json,routing 1003 data: {"cost-map": {"PID2" : {"PID3" : 31}}} 1005 event: application/merge-patch+json,hops 1006 data: {"cost-map": {"PID2" : {"PID3" : 4}}} 1008 If the client wishes to stop receiving updates for the "hopcount" 1009 Cost Map, the client can send a "remove" request on the Stream 1010 Controller URI: 1012 POST /updates/streams/2718281828459" HTTP/1.1 1013 Host: alto.example.com 1014 Accept: text/plain,application/alto-error+json 1015 Content-Type: application/alto-updatestreamparams+json 1016 Content-Length: ### 1018 { 1019 "remove": [ "hops" ] 1020 } 1022 HTTP/1.1 204 No Content 1023 Content-Length: 0 1025 (stream closed without sending data content) 1027 The ALTO Server sends a "remove" control event on the original 1028 request stream to inform the client that updates are stopped for that 1029 resource: 1031 event: application/alto-updatestreamcontrol+json 1032 data: { "remove": ["hops"] } 1034 If the client no longer needs any updates, and wishes to shut the 1035 Update Stream down gracefully, the client can send a "remove" request 1036 with an empty array: 1038 POST /updates/streams/2718281828459" HTTP/1.1 1039 Host: alto.example.com 1040 Accept: text/plain,application/alto-error+json 1041 Content-Type: application/alto-updatestreamparams+json 1042 Content-Length: ### 1044 { 1045 "remove": [ ] 1046 } 1048 HTTP/1.1 204 No Content 1049 Content-Length: 0 1051 (stream closed without sending data content) 1053 The ALTO Server sends a final "remove" control event on the original 1054 request stream to inform the client that all updates are stopped, and 1055 then closes the stream: 1057 event: application/alto-updatestreamcontrol+json 1058 data: { "remove": ["net", "routing"] } 1060 (server closes stream) 1062 9.3. Example: Endpoint Property Updates 1064 As another example, here is how a client can request updates for the 1065 property "priv:ietf-bandwidth" for one set of endpoints, and 1066 "priv:ietf-load" for another. The ALTO Server immediately sends 1067 full-replacement messages with the property values for all endpoints. 1068 After that, the server sends update events for the individual 1069 endpoints as their property values change. 1071 POST /updates/properties HTTP/1.1 1072 Host: alto.example.com 1073 Accept: text/event-stream 1074 Content-Type: application/alto-updatestreamparams+json 1075 Content-Length: ### 1077 { "add": { 1078 "props-1": { 1079 "resource-id": "my-props", 1080 "input": { 1081 "properties" : [ "priv:ietf-bandwidth" ], 1082 "endpoints" : [ 1083 "ipv4:198.51.100.1", 1084 "ipv4:198.51.100.2", 1085 "ipv4:198.51.100.3" 1086 ] 1087 } 1088 }, 1089 "props-2": { 1090 "resource-id": "my-props", 1091 "input": { 1092 "properties" : [ "priv:ietf-load" ], 1093 "endpoints" : [ 1094 "ipv6:2001:db8:100::1", 1095 "ipv6:2001:db8:100::2", 1096 "ipv6:2001:db8:100::3", 1097 ] 1098 } 1099 }, 1100 } 1101 } 1102 HTTP/1.1 200 OK 1103 Connection: keep-alive 1104 Content-Type: text/event-stream 1106 event: application/alto-updatestreamcontrol+json 1107 data: {"control-uri": 1108 data: "http://alto.example.com/updates/streams/1414213562373"} 1110 event: application/alto-endpointprops+json,props-1 1111 data: { "endpoint-properties": { 1112 data: "ipv4:198.51.100.1" : { "priv:ietf-bandwidth": "13" }, 1113 data: "ipv4:198.51.100.2" : { "priv:ietf-bandwidth": "42" }, 1114 data: "ipv4:198.51.100.3" : { "priv:ietf-bandwidth": "27" } 1115 data: } } 1117 event: application/alto-endpointprops+json,props-2 1118 data: { "endpoint-properties": { 1119 data: "ipv6:2001:db8:100::1" : { "priv:ietf-load": "8" }, 1120 data: "ipv6:2001:db8:100::2" : { "priv:ietf-load": "2" }, 1121 data: "ipv6:2001:db8:100::3" : { "priv:ietf-load": "9" } 1122 data: } } 1124 (pause) 1126 event: application/merge-patch+json,props-1 1127 data: { "endpoint-properties": 1128 data: {"ipv4:198.51.100.1" : {"priv:ietf-bandwidth": "3"}} 1129 data: } 1131 (pause) 1133 event: application/merge-patch+json,props-2 1134 data: { "endpoint-properties": 1135 data: {"ipv6:2001:db8:100::3" : {"priv:ietf-load": "7"}} 1136 data: } 1138 If the client needs the "bandwidth" property for additional 1139 endpoints, the client can send a "add" request on the Stream 1140 Controller URI: 1142 POST /updates/streams/1414213562373" HTTP/1.1 1143 Host: alto.example.com 1144 Accept: text/plain,application/alto-error+json 1145 Content-Type: application/alto-updatestreamparams+json 1146 Content-Length: ### 1148 { "add": { 1149 "props-3": { 1150 "resource-id": "my-props", 1151 "input": { 1152 "properties" : [ "priv:ietf-bandwidth" ], 1153 "endpoints" : [ 1154 "ipv4:198.51.100.4", 1155 "ipv4:198.51.100.5", 1156 ] 1157 } 1158 }, 1159 "props-4": { 1160 "resource-id": "my-props", 1161 "input": { 1162 "properties" : [ "priv:ietf-load" ], 1163 "endpoints" : [ 1164 "ipv6:2001:db8:100::4", 1165 "ipv6:2001:db8:100::5", 1166 ] 1167 } 1168 }, 1169 } 1170 } 1172 HTTP/1.1 204 No Content 1173 Content-Length: 0 1175 (stream closed without sending data content) 1177 The ALTO Server sends full replacement events for the two new 1178 resources, followed by incremental updates for all four requests as 1179 they arrive: 1181 event: application/alto-endpointprops+json,props-3 1182 data: { "endpoint-properties": { 1183 data: "ipv4:198.51.100.4" : { "priv:ietf-bandwidth": "25" }, 1184 data: "ipv4:198.51.100.5" : { "priv:ietf-bandwidth": "31" }, 1185 data: } } 1187 event: application/alto-endpointprops+json,props-4 1188 data: { "endpoint-properties": { 1189 data: "ipv6:2001:db8:100::4" : { "priv:ietf-load": "6" }, 1190 data: "ipv6:2001:db8:100::5" : { "priv:ietf-load": "4" }, 1191 data: } } 1193 (pause) 1195 event: application/merge-patch+json,props-3 1196 data: { "endpoint-properties": 1197 data: {"ipv4:198.51.100.5" : {"priv:ietf-bandwidth": "15"}} 1198 data: } 1200 (pause) 1202 event: application/merge-patch+json,props-2 1203 data: { "endpoint-properties": 1204 data: {"ipv6:2001:db8:100::2" : {"priv:ietf-load": "9"}} 1205 data: } 1207 (pause) 1209 event: application/merge-patch+json,props-4 1210 data: { "endpoint-properties": 1211 data: {"ipv6:2001:db8:100::4" : {"priv:ietf-load": "3"}} 1212 data: } 1214 9.4. IRD Example 1216 Here is an example of an IRD that offers two Update Stream services. 1217 The first provides updates for the Network Map, the "routingcost" and 1218 "hopcount" Cost Maps, and a Filtered Cost Map resource. The second 1219 Update Stream provides updates to the Endpoint Properties service. 1221 Note that this IRD defines two Filtered Cost Map resources. They use 1222 the same cost types, but "my-filtered-cost-map" accepts cost 1223 constraint tests, while "my-simple-filtered-cost-map" does not. To 1224 avoid the issues discussed in Section 12.1, the Update Stream 1225 provides updates for the second, but not the first. 1227 "my-network-map": { 1228 "uri": "http://alto.example.com/networkmap", 1229 "media-type": "application/alto-networkmap+json", 1230 }, 1231 "my-routingcost-map": { 1232 "uri": "http://alto.example.com/costmap/routingcost", 1233 "media-type": "application/alto-costmap+json", 1234 "uses": ["my-networkmap"], 1235 "capabilities": { 1236 "cost-type-names": ["num-routingcost"] 1237 } 1238 }, 1239 "my-hopcount-map": { 1240 "uri": "http://alto.example.com/costmap/hopcount", 1241 "media-type": "application/alto-costmap+json", 1242 "uses": ["my-networkmap"], 1243 "capabilities": { 1244 "cost-type-names": ["num-hopcount"] 1245 } 1246 }, 1247 "my-filtered-cost-map": { 1248 "uri": "http://alto.example.com/costmap/filtered/constraints", 1249 "media-type": "application/alto-costmap+json", 1250 "accepts": "application/alto-costmapfilter+json", 1251 "uses": ["my-networkmap"], 1252 "capabilities": { 1253 "cost-type-names": ["num-routingcost", "num-hopcount"], 1254 "cost-constraints": true 1255 } 1256 }, 1257 "my-simple-filtered-cost-map": { 1258 "uri": "http://alto.example.com/costmap/filtered/simple", 1259 "media-type": "application/alto-costmap+json", 1260 "accepts": "application/alto-costmapfilter+json", 1261 "uses": ["my-networkmap"], 1262 "capabilities": { 1263 "cost-type-names": ["num-routingcost", "num-hopcount"], 1264 "cost-constraints": false 1265 } 1266 }, 1267 "my-props": { 1268 "uri": "http://alto.example.com/properties", 1269 "media-type": "application/alto-endpointprops+json", 1270 "accepts": "application/alto-endpointpropparams+json", 1271 "capabilities": { 1272 "prop-types": ["priv:ietf-bandwidth"] 1273 } 1274 }, 1275 "update-my-costs": { 1276 "uri": "http://alto.example.com/updates/costs", 1277 "media-type": "text/event-stream", 1278 "accepts": "application/alto-updatestreamparams+json", 1279 "uses": [ 1280 "my-network-map", 1281 "my-routingcost-map", 1282 "my-hopcount-map", 1283 "my-simple-filtered-cost-map" 1284 ], 1285 "capabilities": { 1286 "incremental-update-media-types": { 1287 "my-routingcost-map": application/merge-patch+json", 1288 "my-hopcount-map": "application/merge-patch+json" 1289 } 1290 } 1291 }, 1292 "update-my-props": { 1293 "uri": "http://alto.example.com/updates/properties", 1294 "media-type": "text/event-stream", 1295 "uses": [ "my-props" ], 1296 "accepts": "application/alto-updatestreamparams+json", 1297 "capabilities": { 1298 "incremental-update-media-types": { 1299 "my-props": "application/merge-patch+json" 1300 } 1301 } 1302 } 1304 10. Client Actions When Receiving Update Messages 1306 In general, when a client receives a full-replacement update message 1307 for a resource, the client should replace the current version with 1308 the new version. When a client receives a Merge Patch update message 1309 for a resource, the client should apply those patches to the current 1310 version of the resource. 1312 However, because resources can depend on other resources (e.g., Cost 1313 Maps depend on Network Maps), an ALTO Client MUST NOT use a dependent 1314 resource if the resource on which it depends has changed. There are 1315 at least two ways a client can do that. We will illustrate these 1316 techniques by referring to Network and Cost Map messages, although 1317 these techniques apply to any dependent resources. 1319 Note that when a Network Map changes, the ALTO Server MUST send the 1320 Network Map update message before sending the updates for the 1321 dependent Cost Maps (see Section 7.6.2). 1323 One approach is for the ALTO Client to save the Network Map update 1324 message in a buffer, and continue to use the previous Network Map, 1325 and the associated Cost Maps, until the client receives the update 1326 messages for all dependent Cost Maps. The client then applies all 1327 Network and Cost Map updates atomically. 1329 Alternatively, the client MAY update the Network Map immediately. In 1330 this case, the client MUST mark each dependent Cost Map as 1331 temporarily invalid, and MUST NOT use that map until the client 1332 receives a Cost Map update message with the new Network Map version 1333 tag. Note that the client MUST NOT delete the Cost Maps, because the 1334 server may send Merge Patch update messages. 1336 The ALTO Server SHOULD send updates for dependent resources in a 1337 timely fashion. However, if the client does not receive the expected 1338 updates, the client MUST close the Update Stream connection, discard 1339 the dependent resources, and reestablish the Update Stream. The 1340 client MAY retain the version tag of the last version of any tagged 1341 resources, and give those version tags when requesting the new Update 1342 Stream. In this case, if a version is still current, the ALTO Server 1343 will not re-send that resource. 1345 Although not as efficient as possible, this recovery method is simple 1346 and reliable. 1348 11. Design Decisions and Discussions 1350 11.1. HTTP/2 Server-Push 1352 HTTP/2 ([RFC7540]) provides a Server Push facility. Although the 1353 name implies that it might be useful for sending asynchronous updates 1354 from the server to the client, in reality Server Push is not well 1355 suited for that task. To see why it is not, here is a quick summary 1356 of HTTP/2. 1358 HTTP/2 allows a client and server to multiplex many HTTP requests and 1359 responses over a single TCP connection. The requests and responses 1360 can be interleaved on a block by block basis, avoiding the head-of- 1361 line blocking problem encountered with the Keep-Alive mechanism in 1362 HTTP/1.1. Server Push allows the server to send a resource (an 1363 image, a CSS file, a javascript file, etc.) to the client before the 1364 client explicitly requests it. A server can only push cacheable GET- 1365 mode resources. By pushing a resource, the server implicitly tells 1366 the client, "Add this resource to your cache, because a resource you 1367 have requested needs it." 1369 One approach for using Server Push for ALTO updates is for the server 1370 to send each update event as a separate Server Push item, and let the 1371 client apply those updates as they arrive. Unfortunately there are 1372 several problems with that approach. 1374 First, HTTP/2 does not guarantee that pushed resources are delivered 1375 to the client in the order they were sent by the client, so each 1376 update event would need a sequence number, and the client would have 1377 to re-sequence them. 1379 Second, an HTTP/2-aware client library will not necessarily inform a 1380 client application when the server pushes a resource. Instead, the 1381 library might cache the pushed resource, and only deliver it to the 1382 client when the client explicitly requests that URI. 1384 But the third problem is the most significant: Server Push is 1385 optional, and can be disabled by any proxy between the client and the 1386 server. This is not a problem for the intended use of Server Push: 1387 eventually the client will request those resources, so disabling 1388 Server Push just adds a delay. But this means that Server Push is 1389 not suitable for resources which the client does not know to request. 1391 Thus we do not believe HTTP/2 Server Push is suitable for delivering 1392 asynchronous updates. Hence we have chosen to base ALTO updates on 1393 HTTP/1.1 and SSE. 1395 11.2. Not Allowing Stream Restart 1397 If an update stream is closed accidentally, when the client 1398 reconnects, the server must resend the full maps. This is clearly 1399 inefficient. To avoid that inefficiency, the SSE specification 1400 allows a server to assign an id to each event. When a client 1401 reconnects, the client can present the id of the last successfully 1402 received event, and the server restarts with the next event. 1404 However, that mechanism adds additional complexity. The server must 1405 save SSE messages in a buffer, in case clients reconnect. But that 1406 mechanism will never be perfect: if the client waits too long to 1407 reconnect, or if the client sends an invalid id, then the server will 1408 have to resend the complete maps anyway. 1410 Furthermore, this is unlikely to be a problem in practice. Clients 1411 who want continuous updates for large resources, such as full Network 1412 and Cost Maps, are likely to be things like P2P trackers. These 1413 clients will be well connected to the network; they will rarely drop 1414 connections. 1416 Mobile devices certainly can and do drop connections, and will have 1417 to reconnect. But mobile devices will not need continuous updates 1418 for multi-megabyte Cost Maps. If mobile devices need continuous 1419 updates at all, they will need them for small queries, such as the 1420 costs from a small set of media servers from which the device can 1421 stream the currently playing movie. If the mobile device drops the 1422 connection and reestablishes the Update Stream, the ALTO Server will 1423 have to retransmit only a small amount of redundant data. 1425 In short, using event ids to avoid resending the full map adds a 1426 considerable amount of complexity to avoid a situation which we 1427 expect is very rare. We believe that complexity is not worth the 1428 benefit. 1430 The Update Stream service does allow the client to specify the tag of 1431 the last received version of any tagged resource, and if that is 1432 still current, the server need not retransmit the full resource. 1433 Hence clients can use this to avoid retransmitting full Network Maps. 1434 Cost Maps are not tagged, so this will not work for them. Of course, 1435 the ALTO protocol could be extended by adding version tags to Cost 1436 Maps, which would solve the retransmission-on-reconnect problem. 1437 However, adding tags to Cost Maps might add a new set of 1438 complications. 1440 11.3. Is Incremental Update Useful for Network Maps? 1442 It is not clear whether incremental updates (that is, Merge Patch 1443 updates) are useful for Network Maps. For minor changes, such as 1444 moving a prefix from one PID to another, they can be useful. But 1445 more involved changes to the Network Map are likely to be "flag 1446 days": they represent a completely new Network Map, rather than a 1447 simple, well-defined change. 1449 At this point we do not have sufficient experience with ALTO 1450 deployments to know how frequently Network Maps will change, or how 1451 extensive those changes will be. For example, suppose a link goes 1452 down and the network uses an alternative route. This is a frequent 1453 occurrence. If an ALTO Server models that by moving prefixes from 1454 one PID to another, then Network Maps will change frequently. 1455 However, an ALTO Server might model that as a change in costs between 1456 PIDs, rather than a change in the PID definitions. If a server takes 1457 that approach, simple routing changes will affect Cost Maps, but not 1458 Network Maps. 1460 So while we allow a server to use Merge Patch on Network Maps, we do 1461 not require the server to do so. Each server may decide on its own 1462 whether to use Merge Patch for Network Maps. 1464 This is not to say that Network Map updates are not useful. Clearly 1465 Network Maps will change, and update events are necessary to inform 1466 clients of the new map. Further, there maybe another incremental 1467 update encoding that is better suited for updating Networks Maps; see 1468 the discussions in the next section. 1470 11.4. Other Incremental Update Message Types 1472 Other JSON-based incremental update formats have been defined, in 1473 particular JSON Patch ([RFC6902]). The update events defined in this 1474 document have the media-type of the update data. JSON Patch has its 1475 own media type ("application/json-patch+json"), so this update 1476 mechanism could easily be extended to allow servers to use JSON Patch 1477 for incremental updates. 1479 However, we think that JSON Merge Patch is clearly superior to JSON 1480 Patch for describing incremental updates to Cost Maps, Endpoint 1481 Costs, and Endpoint Properties. For these data structures, JSON 1482 Merge Patch is more space-efficient, as well as simpler to apply; we 1483 see no advantage to allowing a server to use JSON Patch for those 1484 resources. 1486 The case is not as clear for incremental updates to Network Maps. 1487 For example, suppose a prefix moves from one PID to another. JSON 1488 Patch could encode that as a simple insertion and deletion, while 1489 Merge Patch would have to replace the entire array of prefixes for 1490 both PIDs. On the other hand, to process a JSON Patch update, the 1491 client would have to retain the indexes of the prefixes for each PID. 1492 Logically, the prefixes in a PID are an unordered set, not an array; 1493 aside from handling updates, a client has no need to retain the array 1494 indexes of the prefixes. Hence to take advantage of JSON Patch for 1495 Network Maps, clients would have to retain additional, otherwise 1496 unnecessary, data. 1498 However, it is entirely possible that JSON Patch will be appropriate 1499 for describing incremental updates to new, as yet undefined ALTO 1500 resources. In this case, the extensions defining those new resources 1501 can use the update framework defined in this document, but recommend 1502 using JSON Patch, or some other method, to describe the incremental 1503 changes. 1505 12. Miscellaneous Considerations 1507 12.1. Considerations For Updates To Filtered Cost Maps 1509 If an Update Stream provides updates to a Filtered Cost Map which 1510 allows constraint tests, then a client MAY request updates to a 1511 Filtered Cost Map request with a constraint test. In this case, when 1512 a cost changes, the server MUST send an update if the new value 1513 satisfies the test. If the new value does not, whether the server 1514 sends an update depends on whether the previous value satisfied the 1515 test. If it did not, the server SHOULD NOT send an update to the 1516 client. But if the previous value did, then the server MUST send an 1517 update with a "null" value, to inform the client that this cost no 1518 longer satisfies the criteria. 1520 An ALTO Server can avoid such issues by offering Update Streams only 1521 for Filtered Cost Maps which do not allow constraint tests. 1523 12.2. Considerations For Incremental Updates To Ordinal Mode Costs 1525 For an ordinal mode cost map, a change to a single cost point may 1526 require updating many other costs. As an extreme example, suppose 1527 the lowest cost changes to the highest cost. For a numerical mode 1528 cost map, only that one cost changes. But for an ordinal mode cost 1529 map, every cost might change. While this document allows a server to 1530 offer incremental updates for ordinal mode cost maps, server 1531 implementors should be aware that incremental updates for ordinal 1532 costs are more complicated than for numerical costs, and clients 1533 should be aware that small changes may result in large updates. 1535 An ALTO Server can avoid this complication by only offering full 1536 replacement updates for ordinal cost maps. 1538 12.3. Considerations Related to SSE Line Lengths 1540 SSE was designed for events that consist of relatively small amounts 1541 of line-oriented text data, and SSE clients frequently read input one 1542 line-at-a-time. However, an Update Stream sends full cost maps as 1543 single events, and a cost map may involve megabytes, if not tens of 1544 megabytes, of text. This has implications for both the ALTO Server 1545 and Client. 1547 First, SSE clients might not be able to handle a multi-megabyte data 1548 "line". Hence it is RECOMMENDED that an ALTO server limit data lines 1549 to at most 2,000 characters. 1551 Second, some SSE client packages read all the data for an event into 1552 memory, and then present it to the client as a single character 1553 array. However, a client computer may not have enough memory to hold 1554 the entire JSON text for a large cost map. Hence an ALTO client 1555 SHOULD consider using an SSE library which presents the event data in 1556 manageable chunks, so the client can parse the cost map incrementally 1557 and store the underlying data in a more compact format. 1559 13. Security Considerations 1561 13.1. Denial-of-Service Attacks 1563 Allowing persistent update stream connections enables a new class of 1564 Denial-of-Service attacks. A client might create an unreasonable 1565 number of update stream connections, or add an unreasonable number of 1566 client-ids to one update stream. To avoid those attacks, an ALTO 1567 Server MAY choose to limit the number of active streams, and reject 1568 new requests when that threshold is reached. A server MAY also chose 1569 to limit the number of active client-ids on any given stream, or 1570 limit the total number of client-ids used over the lifetime of a 1571 stream, and reject any stream control request which would exceed 1572 those limits. In these cases, the server SHOULD return the HTTP 1573 status "503 Service Unavailable". 1575 While this technique prevents Update Stream DoS attacks from 1576 disrupting an ALTO Server's other services, it does make it easier 1577 for a DoS attack to disrupt the Update Stream service. Therefore a 1578 server may prefer to restrict Update Stream services to authorized 1579 clients, as discussed in Section 15 of [RFC7285]. 1581 Alternatively an ALTO Server MAY return the HTTP status "307 1582 Temporary Redirect" to redirect the client to another ALTO Server 1583 which can better handle a large number of update streams. 1585 13.2. Spoofed Control Requests 1587 An outside party which can read the update stream response, or which 1588 can observe stream control requests, can obtain the controller URI 1589 and use that to send a fraudulent "remove" requests, thus disabling 1590 updates for the valid client. This can be avoided by encrypting the 1591 Update Stream and Stream Controller requests (see Section 15 of 1592 [RFC7285]). Also, the ALTO Server echoes the "remove" requests on 1593 the update stream, so the valid client can detect unauthorized 1594 requests. 1596 13.3. Privacy 1598 This extension does not introduce any privacy issues not already 1599 present in the ALTO protocol. 1601 14. IANA Considerations 1603 This document defines two new media-types, "application/alto- 1604 updatestreamparams+json", as described in Section 7.3, and 1605 "application/alto-updatestreamcontrol+json", as described in 1606 Section 6.3. All other media-types used in this document have 1607 already been registered, either for ALTO or JSON Merge Patch. 1609 Type name: application 1611 Subtype name: alto-updatestreamparams+json 1613 Required parameters: n/a 1615 Optional parameters: n/a 1617 Encoding considerations: Encoding considerations are identical to 1618 those specified for the "application/json" media type. See 1619 [RFC7159]. 1621 Security considerations: Security considerations relating to the 1622 generation and consumption of ALTO Protocol messages are discussed 1623 in Section 13 of this document and Section 15 of [RFC7285]. 1625 Interoperability considerations: This document specifies format of 1626 conforming messages and the interpretation thereof. 1628 Published specification: Section 7.3 of this document. 1630 Applications that use this media type: ALTO servers and ALTO clients 1631 either stand alone or are embedded within other applications. 1633 Additional information: 1635 Magic number(s): n/a 1637 File extension(s): This document uses the mime type to refer to 1638 protocol messages and thus does not require a file extension. 1640 Macintosh file type code(s): n/a 1642 Person & email address to contact for further information: See 1643 Authors' Addresses section. 1645 Intended usage: COMMON 1647 Restrictions on usage: n/a 1649 Author: See Authors' Addresses section. 1651 Change controller: Internet Engineering Task Force 1652 (mailto:iesg@ietf.org). 1654 Type name: application 1656 Subtype name: alto-updatestreamcontrol+json 1658 Required parameters: n/a 1660 Optional parameters: n/a 1662 Encoding considerations: Encoding considerations are identical to 1663 those specified for the "application/json" media type. See 1664 [RFC7159]. 1666 Security considerations: Security considerations relating to the 1667 generation and consumption of ALTO Protocol messages are discussed 1668 in Section 13 of this document and Section 15 of [RFC7285]. 1670 Interoperability considerations: This document specifies format of 1671 conforming messages and the interpretation thereof. 1673 Published specification: Section 6.3 of this document. 1675 Applications that use this media type: ALTO servers and ALTO clients 1676 either stand alone or are embedded within other applications. 1678 Additional information: 1680 Magic number(s): n/a 1682 File extension(s): This document uses the mime type to refer to 1683 protocol messages and thus does not require a file extension. 1685 Macintosh file type code(s): n/a 1687 Person & email address to contact for further information: See 1688 Authors' Addresses section. 1690 Intended usage: COMMON 1692 Restrictions on usage: n/a 1694 Author: See Authors' Addresses section. 1696 Change controller: Internet Engineering Task Force 1697 (mailto:iesg@ietf.org). 1699 15. References 1701 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1702 Requirement Levels", RFC 2119, BCP 14, March 1997. 1704 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1705 RFC 5789, March 2010. 1707 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 1708 (JSON) Patch", RFC 6902, April 2013. 1710 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1711 Interchange Format", RFC 7159, March 2014. 1713 [RFC7285] Almi, R., Penno, R., Yang, Y., Kiesel, S., Previdi, S., 1714 Roome, W., Shalunov, S., and R. Woundy, "Application-Layer 1715 Traffic Optimization (ALTO) Protocol", RFC 7285, September 1716 2014. 1718 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1719 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 1720 2014. 1722 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1723 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1725 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1726 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 1728 [RFC7233] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1729 (HTTP/1.1): Range Requests", RFC 7233, June 2014. 1731 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 1732 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 1733 2014. 1735 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1736 (HTTP/1.1): Authentication", RFC 7235, June 2014. 1738 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1739 October 2014. 1741 [RFC7540] Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 1742 Protocol Version 2 (HTTP/2)", RFC 7540, May 2015. 1744 [SSE] Hickson, I., "Server-Sent Events (W3C)", W3C 1745 Recommendation 03 February 2015, February 2015. 1747 Appendix A. Acknowledgments 1749 Thank you to Xiao Shi (Yale University) for his contributions to an 1750 earlier version of this document. 1752 Authors' Addresses 1754 Wendy Roome 1755 Nokia Bell Labs 1756 600 Mountain Ave, Rm 3B-324 1757 Murray Hill, NJ 07974 1758 USA 1760 Phone: +1-908-582-7974 1761 Email: wendy@wdroome.com 1763 Y. Richard Yang 1764 Tongji/Yale University 1765 51 Prospect St 1766 New Haven CT 1767 USA 1769 Email: yang.r.yang@gmail.com