idnits 2.17.1 draft-zhang-alto-multipart-06.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 325 has weird spacing: '...ceQuery reso...' -- The document date (12 July 2021) is 1013 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) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) == Outdated reference: A later version (-25) exists of draft-ietf-alto-path-vector-14 == Outdated reference: A later version (-24) exists of draft-ietf-alto-unified-props-new-17 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ALTO WG J. Zhang 3 Internet-Draft Tongji University 4 Intended status: Standards Track Y.R. Yang 5 Expires: 13 January 2022 Yale University 6 12 July 2021 8 Multiple ALTO Resources Query Using Multipart Message 9 draft-zhang-alto-multipart-06 11 Abstract 13 Many ALTO use cases involve multiple ALTO information resources like 14 different network maps, cost maps and property maps to achieve their 15 own specific goals. To make the ALTO client query them one by one is 16 not only inefficient but also error-prone. The inconsistent 17 responses can be performed because of the unstable communication 18 environment, and finally conduct the unexpected traffic optimization. 19 Further more, some ALTO information resources may have correlation, 20 which means one's input parameters may depends on another one's 21 response. To address those issues, some advanced query schema is 22 required. This document proposes an ALTO extension to support the 23 multiple ALTO resources query in the single request using the HTTP 24 multipart message and the existing JSON query languages. 26 Requirements Language 28 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 29 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 30 document are to be interpreted as described in [RFC2119]. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 13 January 2022. 49 Copyright Notice 51 Copyright (c) 2021 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Simplified BSD License text 60 as described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Terminologies . . . . . . . . . . . . . . . . . . . . . . . . 4 67 2.1. Resource Query Entry . . . . . . . . . . . . . . . . . . 4 68 2.2. Resource Response Entry . . . . . . . . . . . . . . . . . 4 69 2.3. Resource Response Entry Body . . . . . . . . . . . . . . 4 70 3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 3.1. Simple Batch Query . . . . . . . . . . . . . . . . . . . 4 72 3.2. Properties Constrained Query . . . . . . . . . . . . . . 5 73 3.3. Path Vector Query . . . . . . . . . . . . . . . . . . . . 5 74 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 5 75 5. Design Space of Multipart Resource in ALTO . . . . . . . . . 6 76 6. Multipart Query Resource . . . . . . . . . . . . . . . . . . 7 77 6.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 7 78 6.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 7 79 6.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 7 80 6.4. Accept Input Parameters . . . . . . . . . . . . . . . . . 7 81 6.5. Uses . . . . . . . . . . . . . . . . . . . . . . . . . . 8 82 6.6. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 83 7. Protocol Errors . . . . . . . . . . . . . . . . . . . . . . . 8 84 7.1. Partial Error . . . . . . . . . . . . . . . . . . . . . . 9 85 7.2. Entire Error . . . . . . . . . . . . . . . . . . . . . . 10 86 8. Incremental Update Integration . . . . . . . . . . . . . . . 10 87 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10 88 9.1. IRD Example . . . . . . . . . . . . . . . . . . . . . . . 10 89 9.2. Example 1: Simple Batch Query . . . . . . . . . . . . . . 12 90 9.3. Example 2: Properties Constrained Query . . . . . . . . . 14 91 9.4. Example 3: Path Vector Query . . . . . . . . . . . . . . 17 92 9.5. Example 4: Incremental Updates . . . . . . . . . . . . . 18 93 10. Compatibility . . . . . . . . . . . . . . . . . . . . . . . . 20 94 10.1. Compatibility with Legacy ALTO Clients/Servers . . . . . 20 95 10.2. Compatibility with Existing Protocol Extensions . . . . 20 96 11. Misc Considerations . . . . . . . . . . . . . . . . . . . . . 21 97 11.1. Return ALTO Information Resources over HTTP/2 . . . . . 21 98 11.2. Support Incremental Update . . . . . . . . . . . . . . . 21 99 11.3. Anonymous Resources . . . . . . . . . . . . . . . . . . 21 100 12. Security Considerations . . . . . . . . . . . . . . . . . . . 21 101 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 102 13.1. application/alto-* Media Types . . . . . . . . . . . . . 22 103 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 104 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 105 15.1. Normative References . . . . . . . . . . . . . . . . . . 23 106 15.2. Informative References . . . . . . . . . . . . . . . . . 24 107 Appendix A. Figures . . . . . . . . . . . . . . . . . . . . . . 25 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 110 1. Introduction 112 Application-Layer Traffic Optimization (ALTO) protocol [RFC7285] and 113 its extensions already define several types of information resources, 114 like Network Map, Cost Map and Property Map, to expose useful network 115 information to applications. However, many applications do not only 116 use a single information resource to perform their traffic 117 optimization. Retrieving multiple ALTO information resources is very 118 common in many ALTO use cases. 120 Using the current ALTO framework defined in [RFC7285], the ALTO 121 client can only query multiple ALTO information resources one by one. 122 It is not only inefficient but also error-prone. Because of the 123 network delay between different requests and the frequent change of 124 ALTO information resources, the responses received by the ALTO client 125 may be inconsistent. 127 Furthermore, some ALTO information resources have known dependencies, 128 which means the ALTO client may need one's response to decide another 129 one's query input parameters. 131 To be summarized, we need the multipart query service for three 132 reasons: 134 * Clients may want to query multiple ALTO information resources in a 135 single request to reduce the network latency. 137 * Clients may want to query multiple ALTO resources consistently, 138 which means the server should guarantee the responses of all 139 resources are generated at the same time. 141 * Some use cases need to query multiple ALTO resources with a joint 142 relationship. 144 This document defines a new ALTO service for: (1) querying multiple 145 ALTO resources in a single request/response, and (2) supporting 146 general-purpose JSON query languages to resolve the relational query. 148 2. Terminologies 150 Besides the terms defined in [RFC2045], [RFC2046], [RFC2387], and 151 [RFC7285], this document also uses the following additional terms: 153 2.1. Resource Query Entry 155 A Resource Query Entry indicates the ResoureQuery object (see 156 Section 6.4) for an individual resource in the accept input 157 parameters of the Multipart Query resource. 159 2.2. Resource Response Entry 161 A Resource Response Entry indicates the entry of an individual part 162 of the multipart response message, including the MIME headers and the 163 body content. 165 2.3. Resource Response Entry Body 167 A Resource Response Entry Body indicates the body content of a 168 Resource Response Entry. 170 3. Use Cases 172 The following use cases can benefit from the multipart query service. 174 3.1. Simple Batch Query 176 The simplest use case is to query a batch of ALTO resources in a 177 single request. 179 Although the ALTO client can perform ALTO requests for multiple 180 times, it is not only inefficient but also inconsistent. 182 For example, the ALTO server provides a network map resource A and a 183 dependent cost map resource B. Both resources may change frequently. 184 Assume the ALTO client queries the network map first, and it gets the 185 revision A1. When the client queries the cost map, the network map 186 may be already changed from A1 to A2, and the client receives cost 187 map B2 which depends on A2 not A1. So the responded cost map B2 is 188 not consistent with the previous network map A1. 190 This case requires the ALTO server to provide a way for the ALTO 191 client to query multiple ALTO resources in a single transaction. 193 3.2. Properties Constrained Query 195 Beyond the simple batch query, there are also some another use cases 196 requiring a new service for relational query. For example, Some 197 clients may need to query an endpoint property map first, and find 198 endpoints with some properties fitting some conditions. And then 199 they query the endpoint cost of these endpoints. 201 In this case, the endpoint cost query depends on the result of the 202 property map query. Although the ALTO client can cache the whole 203 property map in its local storage, it is still not efficient and may 204 conduct the consistency issue if the property map changes frequently. 205 So it requires a new service to provide multiple dependent resources 206 efficiently and consistently. 208 A general multipart query service benefits the ALTO client in two 209 aspects: 211 * It allows the ALTO client to specify the boolean test to reduce 212 the transmission of the useless data from the ALTO server. 214 * It compounds multiple ALTO information resources in a single 215 response to reduce the communication times. Thus, the 216 transmission latency can be reduced. 218 3.3. Path Vector Query 220 Another use case requiring the multiple resource query is the 221 relational query between the on-demand generated resources. A 222 straightforward example is the path vector query demonstrated in 223 [I-D.ietf-alto-path-vector]. 225 [I-D.ietf-alto-path-vector] introduces an extension of ALTO to 226 provide path vector information by cost map and unified property map 227 [I-D.ietf-alto-unified-props-new]. The client using path vector 228 extension will usually query cost map and a dynamically generated 229 property map sequentially. It is even hard to cache the full data of 230 resources, because both the cost map and the property map are on- 231 demand generated by the query input here. Thus, the only way to 232 reduce the time consumption is to compound the two resources. 234 4. Requirements 236 From the use cases described in Section 3, there are three additional 237 requirements for ALTO protocol: 239 MPQ-Req1: The ALTO protocol SHOULD allow the client to query 240 multiple ALTO resources in a single request, and return the result 241 in a single response. 243 It is the basic requirement to provide the query for the compound 244 resources. Even simple cases can benefit if this requirement is 245 realized. 247 MPQ-Req2: The ALTO protocol SHOULD provide general filter schema for 248 any ALTO resources. 250 Current filter schema in ALTO protocol only supports the simple 251 boolean test of numerical comparison. And the boolean filtered 252 query is only supported by the cost map and the endpoint cost 253 resource. It is not enough for the general cases. Even simple 254 property map may require more general filter schema. 256 MPQ-Req3: The ALTO protocol SHOULD support relational query for 257 mulitple joint resources. 259 Some ALTO resources are relational and cannot be used 260 individually. The path vector query is such an example. In these 261 use cases, the support of relational query for multiple joint 262 resources is very helpful. 264 5. Design Space of Multipart Resource in ALTO 266 This document discusses the solution of how to apply "multipart/*" 267 (see [RFC2045] and [RFC2046]) response to the ALTO protocol. 269 There are three cases applying Multipart response to ALTO: 271 Multipart Request and Multipart Response: In this case, an ALTO 272 client can start a single request using Multipart encoding to 273 query a batch of resources. 275 Single Request and Fixed-Layout Multipart Response: In this case, an 276 ALTO server receives a non-Multipart request, e.g., the filtered 277 costmap request or the endpoint cost request, but returns a 278 Multipart response. The ALTO server MUST export the layout of the 279 Multipart response in the IRD. A special example can be found in 280 [I-D.ietf-alto-path-vector]. 282 Single Request and Flexible-Layout Multipart Response: This case 283 extends the previous case to allows the Multipart response with 284 flexible layout. The ALTO server receives the unified query 285 request and generate the layout of the response based on the 286 request. The ALTO client can even use general-purpose query 287 language like XQuery [W3CXQUERY] and JSONiq [JSONIQ] for general 288 query process and relational joint query. 290 The application about Multipart request to the single object response 291 is out of the scope of this document. 293 6. Multipart Query Resource 295 6.1. Media Type 297 "multipart/related" [RFC2387]. 299 6.2. HTTP Method 301 An ALTO Multipart Query resource is requested using the HTTP POST 302 method. 304 6.3. Capabilities 306 The capabilities are defined by an object of type 307 MultipartQueryCapabilities: 309 object { 310 JSONString query-langs<0..*>; 311 } MultipartQueryCapabilities; 313 where "query-langs" is an array of JSONString to indicate which query 314 languages are supported by this resource. 316 6.4. Accept Input Parameters 318 The input parameters for a Multipart Query request are supplied in 319 the entity body of the POST request. This document specifies the 320 input parameters with a data format indicated by the media type 321 "application/alto-multipartquery+alto", which is a JSON object of 322 type ReqMultipartQuery: 324 object { 325 ResourceQuery resources<1..*>; 326 [JsonString query-lang;] 327 } ReqMultipartQuery; 329 object { 330 JsonString resource-id; 331 [JsonValue input;] 332 } ResourceQuery; 334 with fields: 336 resources: List of ResourceQuery objects for which resources are to 337 be queried and how to query them. Each ResourceQuery object MUST 338 include the "resource-id" field to indicate which resource is to 339 be queried. If the queried resource requires the POST method, the 340 "input" field MUST be specified. The value of the "input" field 341 MUST be either a JSONString or a JSONObject. When its value is a 342 JSONObject, its format MUST be as the accept input parameters of 343 its resource. When its value is a JSONString, it MUST be a 344 program written in the query language specified by the "query- 345 lang" field. 347 query-lang: Optional. The value of the "query-lang" field MUST be 348 one of values in the "query-langs" capability. If this field is 349 not specified in the request, the ALTO client SHOULD NOT use any 350 query language in the "input" field. 352 6.5. Uses 354 An array with the resource ID(s) of resource(s) which this multipart 355 query resource can compound. The used resource can be any available 356 ALTO resources except for the multipart query resource. If the 357 "uses" field is not specified, all the available ALTO resources can 358 be queried except for the multipart query resource. 360 6.6. Response 362 The response of multipart query resource is a multipart message. 363 Each part of this multipart message is the response of a queried 364 resource in the request. 366 7. Protocol Errors 368 At the top level, the request of ALTO Multipart Query resource may 369 conduct two types of errors: Partial Error and Entire Error. 371 7.1. Partial Error 373 The Partial Error only occurs when the value of the "resource-id" 374 field or the "input" field is invalid. 376 When the Partial Error occurs, the ALTO server MUST still return the 377 response in the media type "multipart/related". For the resource 378 query entry with an error, the ALTO server MUST specify the "Content- 379 Type" of its resource response entry as "application/alto- 380 error+json", and include the ALTO error message in its resource 381 response entry body. For the resource query entry without any error, 382 the ALTO server MUST perform its query request normally. 384 The value of the "resource-id" field is invalid when this resource id 385 is not defined by the Information Resource Directory. In this case, 386 the ALTO server MUST return the E_INVALID_FIELD_VALUE error. 388 The validation of each "input" field of the multipart query input 389 parameters depends on the queried resource: 391 * If the "input" field of the multipart query input parameters is 392 neither a JSONObject nor a JSONString, the ALTO server SHOULD 393 return the E_INVALID_FIELD_TYPE error, unless a future protocol 394 extension supports the non-JSONObject input parameters. 396 * If the "input" field of the multipart query input parameters is a 397 JSONObject, the ALTO server MUST validate the value using its 398 queried resource and return the corresponding error if it has. 400 * If the "input" field of the multipart query input parameters is a 401 JSONString: 403 - If the "query-lang" is not specified, the ALTO server MUST 404 return the E_INVALID_FIELD_TYPE error. 406 - If the "query-lang" is specified, the ALTO server MUST execute 407 this JSONString as a program written in the "query-lang". If 408 the execution failed, the ALTO server MUST return the 409 E_INVALID_FIELD_VALUE error. If the execution succeeds but the 410 result fails to pass the validation of the queried resource, 411 the ALTO server MUST return the E_INVALID_FIELD_VALUE error and 412 attach the error message returned by the queried resource into 413 the "message" field of the ALTO error message. 415 The syntax error is an Entire Error. 417 7.2. Entire Error 419 Any other invalid request will conduct the Entire Error. 421 When the Entire Error occurs, the ALTO server MUST return the error 422 response in the media type "application/alto-error+json" instead of 423 "multipart/related". The process of the Entire Error is as defined 424 in Section 8.5 of [RFC7285]. 426 8. Incremental Update Integration 428 This document defines a compatible incremental update process for 429 Multipart Query resource with [RFC8895]. 431 An ALTO server's IRD can export an Update Stream service defined in 432 [RFC8895] including the Resource ID of a Multipart Query resource in 433 the "uses" field. When an ALTO client subscribes the incremental 434 update for this Multipart Query resource, the ALTO server sends the 435 whole Multipart response message back at the first data update 436 message. Then the ALTO server subscribes all nodes in this multipart 437 resource tree automatically. Once data updated later, the ALTO 438 server publishes the update for each node individually. 440 9. Examples 442 9.1. IRD Example 444 Assume the root IRD is like the following: 446 { 447 "meta": { 448 "path-vector": { 449 "cost-mode": "array", 450 "cost-metric": "ane-path" 451 }, 452 "num-routingcost": { 453 "cost-mode": "numerical", 454 "cost-metric": "routingcost" 455 }, 456 "num-hopcount": { 457 "cost-mode": "numerical", 458 "cost-metric": "hopcount" 459 } 460 }, 461 "resources": { 462 "my-default-networkmap": { 463 "uri": "https://alto.example.com/networkmap", 464 "media-type": "application/alto-networkmap+json" 466 }, 467 "my-default-costmap": { 468 "uri": "https://alto.example.com/costmap", 469 "media-type": "application/alto-costmap+json", 470 "capabilities": { 471 "cost-type-names": [ "num-routingcost" ] 472 }, 473 "uses": [ "my-default-networkmap" ] 474 }, 475 "my-filtered-costmap": { 476 "uri": "https://alto.example.com/costmap/filtered", 477 "media-type": "application/alto-costmap+json", 478 "accepts": "application/alto-costmapfilter+json", 479 "capabilities": { 480 "cost-type-names": [ "num-hopcount" ] 481 }, 482 "uses": [ "my-default-networkmap" ] 483 }, 484 "endpoint-path-vector": { 485 "uri": "https://alto.exmaple.com/endpointcost", 486 "media-type": "application/alto-endpointcost+json", 487 "accepts": "application/alto-endpointcostparams+json", 488 "capabilities": { 489 "cost-constraints": true, 490 "cost-type-names": [ "path-vector" ], 491 }, 492 "property-map": "propmap-availbw" 493 }, 494 "propmap-availbw-delay": { 495 "uri": "https://alto.exmaple.com/propmap/availbw", 496 "media-type": "application/alto-propmap+json", 497 "accepts": "application/alto-propmapparams+json", 498 "uses": [ "endpoint-path-vector" ], 499 "capabilities": { 500 "mappings": { 501 "endpoint-path-vector.ane": [ "availbw" ] 502 } 503 } 504 }, 505 "propmap-location": { 506 "uri": "https://alto.exmaple.com/propmap/location", 507 "media-type": "application/alto-propmap+json", 508 "accepts": "application/alto-propmapparams+json", 509 "uses": [ "my-default-networkmap" ], 510 "capabilities": { 511 "mappings": { 512 "my-default-networkmap.pid": [ "country", "state" ] 513 } 515 } 516 }, 517 "multipart-query": { 518 "uri": "https://alto.example.com/multipart", 519 "media-type": "multipart/related", 520 "accepts": "application/alto-multipartquery+json", 521 "capabilities": { 522 "query-langs": [ "xquery", "jsoniq" ] 523 } 524 }, 525 "update-multipart-query": { 526 "uri": "https://alto.example.com/updates/multipart", 527 "media-type": "text/event-stream", 528 "uses": [ "multipart-query" ], 529 "accepts": "application/alto-updatestreamparams+json", 530 "capabilities": { 531 "incremental-change-media-types": { 532 "multipart-query": "application/merge-patch+json" 533 }, 534 "support-stream-control": true 535 } 536 } 537 } 538 } 540 9.2. Example 1: Simple Batch Query 542 POST /multipart HTTP/1.1 543 Host: alto.example.com 544 Accept: multipart/related, application/alto-error+json 545 Content-Lenght: TBD 546 Content-Type: application/alto-multipartquery+json 548 { 549 "resources": [ 550 { 551 "resource-id": "my-default-networkmap" 552 }, 553 { 554 "resource-id": "my-default-costmap" 555 } 556 ] 557 } 558 HTTP/1.1 200 OK 559 Content-Lenght: TBD 560 Content-Type: multipart/related; boundary=simple-batch-query 562 --simple-batch-query 563 Content-ID: my-default-networkmap 564 Content-Type: application/alto-networkmap+json 566 { 567 "meta": { 568 "vtag": { 569 "resource-id": "my-default-networkmap", 570 "tag": "75ed013b3cb58f896e839582504f622838ce670f" 571 } 572 }, 573 "network-map": { 574 "PID1" : { 575 "ipv4" : [ 576 "192.0.2.0/24", 577 "198.51.100.0/25" 578 ] 579 }, 580 "PID2" : { 581 "ipv4" : [ 582 "198.51.100.128/25" 583 ] 584 }, 585 "PID3" : { 586 "ipv4" : [ 587 "0.0.0.0/0" 588 ], 589 "ipv6" : [ 590 "::/0" 591 ] 592 } 593 } 594 } 596 --simple-batch-query 597 Content-ID: my-default-costmap 598 Content-Type: application/alto-costmap+json 600 { 601 "meta": { 602 "dependent-vtags": [ 603 { 604 "resource-id": "my-default-networkmap", 605 "tag": "75ed013b3cb58f896e839582504f622838ce670f" 607 } 608 ], 609 "cost-type": { 610 "cost-mode": "numerical", 611 "cost-metric": "routingcost" 612 } 613 }, 614 "cost-map": { 615 "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, 616 "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, 617 "PID3": { "PID1": 20, "PID2": 15 } 618 } 619 } 620 --simple-batch-query 622 9.3. Example 2: Properties Constrained Query 624 NOTE: In this example, we use the "`" block to express the raw string 625 with unescaped characters like "\n" and "\"". It is not a valid HTTP 626 body, but only used to better present. When the request is sent to 627 the ALTO server, the "`" block should be escaped. 629 POST /multipart HTTP/1.1 630 Host: alto.example.com 631 Accept: multipart/related, application/alto-error+json 632 Content-Lenght: TBD 633 Content-Type: application/alto-multipartquery+json 635 { 636 "query-lang": "jsoniq", 637 "resources": [ 638 { 639 "resource-id": "propmap-location" 640 }, 641 { 642 "resource-id": "my-default-costmap", 643 "input": ` 644 let $propmap := collection("propmap-location") 645 .("property-map") 646 return { 647 "cost-type": { 648 "cost-mode": "numerical", 649 "cost-metric": "hopcount" 650 }, 651 "pids": { 652 "srcs": [ 653 for $pid in keys($propmap) 654 where $propmap.$pid.country eq "US" 655 return substring-after($pid, "PID:") 656 ], 657 "dsts": [ 658 for $pid in keys($propmap) 659 where $propmap.$pid.country eq "CA" 660 return substring-after($pid, "PID:") 661 ] 662 } 663 } 664 ` 665 } 666 ] 667 } 669 HTTP/1.1 200 OK 670 Content-Lenght: TBD 671 Content-Type: multipart/related; boundary=prop-const-query 673 --prop-const-query 674 Content-ID: propmap-location 675 Content-Type: application/alto-propmap+json 676 { 677 "property-map": { 678 "pid:PID1": { 679 "country": "US", 680 "state": "CA" 681 }, 682 "pid:PID2": { 683 "country": "US", 684 "state": "CT" 685 }, 686 "pid:PID3": { 687 "country": "CA", 688 "state": "QC" 689 }, 690 "pid:PID4": { 691 "country": "CA", 692 "state": "NT" 693 }, 694 "pid:PID5": { 695 "country": "FR" 696 } 697 } 698 } 700 --prop-const-query 701 Content-ID: my-default-costmap 702 Content-Type: application/alto-costmap+json 704 { 705 "meta": { 706 "cost-type": { 707 "cost-mode": "numerical", 708 "cost-metric": "hopcount" 709 } 710 }, 711 "cost-map": { 712 "PID1": { 713 "PID3": 5, 714 "PID4": 7 715 }, 716 "PID2": { 717 "PID3": 8, 718 "PID4": 4 719 } 720 } 721 } 722 --prop-const-query 724 9.4. Example 3: Path Vector Query 726 POST /multipart HTTP/1.1 727 Host: alto.example.com 728 Accept: multipart/related, application/alto-error+json 729 Content-Lenght: TBD 730 Content-Type: application/alto-multipartquery+json 732 { 733 "query-lang": "jsoniq", 734 "resources": [ 735 { 736 "resource-id": "endpoint-path-vector", 737 "input": { 738 "cost-type": { 739 "cost-mode": "array", 740 "cost-metric": "ane-path" 741 }, 742 "endpoints": { 743 "srcs": [ "ipv4:192.0.2.2" ], 744 "dsts": [ "ipv4:192.0.2.89", 745 "ipv4:203.0.113.45" ] 746 } 747 } 748 }, 749 { 750 "resource-id": "propmap-availbw", 751 "input": ` 752 let $propmap := collection("endpiont-path-vector") 753 .("endpoint-cost-map") 754 return { 755 "entities": [ 756 distinct-values(flatten( 757 for $src in keys($propmap) 758 let $dsts := $propmap.$src 759 return flatten( 760 for $dst in keys($dsts) 761 return $dsts.$dst 762 ) 763 )) 764 ], 765 "properties": [ "availbw" ] 766 } 767 ` 768 } 769 ] 770 } 771 HTTP/1.1 200 OK 772 Content-Length: TBD 773 Content-Type: multipart/related; boundary=path-vector-query 775 --path-vector-query 776 Content-ID: endpoint-path-vector 777 Content-Type: application/alto-endpointcost+json 779 { 780 "meta": { 781 "cost-type": { 782 "cost-mode": "array", 783 "cost-metric": "ane-path" 784 } 785 }, 786 "endpoint-cost-map": { 787 "ipv4:192.0.2.2": { 788 "ipv4:192.0.2.89": [ "ane:L001", "ane:L003", "ane:L004" ], 789 "ipv4:203.0.113.45": [ "ane:L001", "ane:L004", "ane:L005" ], 790 "ipv6:2001:db8::10": [ "ane:L001", "ane:L005", "ane:L007" ] 791 } 792 } 793 } 795 --path-vector-query 796 Content-ID: propmap-availbw 797 Content-Type: application/alto-propmap+json 799 { 800 "property-map": { 801 "ane:L001": { "availbw": 50 }, 802 "ane:L003": { "availbw": 48 }, 803 "ane:L004": { "availbw": 55 }, 804 "ane:L005": { "availbw": 60 }, 805 "ane:L007": { "availbw": 35 } 806 } 807 } 808 --path-vector-query 810 9.5. Example 4: Incremental Updates 811 POST /updates/multipart 812 Host: alto.example.com 813 Accept: text/event-stream,application/alto-error+json 814 Content-Length: TBD 815 Content-Type: application/alto-updatestreamparams+json 817 { 818 "add": { 819 "multipart-query": { 820 "resource-id": "multipart-query", 821 "input": { 822 "resources": [ 823 { 824 "resource-id": "my-default-networkmap" 825 }, 826 { 827 "resource-id": "my-default-costmap" 828 } 829 ] 830 } 831 } 832 } 833 } 834 HTTP/1.1 200 OK 835 Connection: keep-alive 836 Content-Type: text/event-stream 838 event: application/alto-updatestreamcontrol+json 839 data: {"control-uri": 840 data: "https://alto.example.com/updates/streams/1414"} 842 event: multipart/related;boundary=example-update,multipart-query 843 data: --simple-batch-query 844 data: Content-ID: netmap 845 data: Content-Type: application/alto-networkmap+json 846 data: 847 data: { ... data (object) of network map ... } 848 data: 849 data: --simple-batch-query 850 data: Content-ID: costmap 851 data: Content-Type: application/alto-costmap+json 852 data: 853 data: { .. data (object) of cost map ... } 854 data: --simple-batch-query 856 (pause) 858 event: application/merge-patch+json,multipart-query.netmap 859 data: { ... merge patch for updates of network map ... } 861 event: application/merge-patch+json,multipart-query.costmap 862 data: { ... merge patch for updates of cost map ... } 864 10. Compatibility 866 10.1. Compatibility with Legacy ALTO Clients/Servers 868 The multipart query service is a new ALTO service using the new media 869 type. So the legacy ALTO client cannot identify this service from 870 the IRD of the ALTO server supporting it. And the legacy ALTO server 871 also cannot interpret the request of a multipart query service sent 872 by the ALTO client. 874 10.2. Compatibility with Existing Protocol Extensions 876 The multipart query service can use any ALTO resources exchanging 877 JSON data in request/response mechanism. So all the known ALTO 878 extensions like ALTO Calendar [RFC8896], Multi-Cost [RFC8189] and the 879 Path Vector [I-D.ietf-alto-path-vector] extension, which does not 880 change the request/response mechanism, are compatible with the 881 multipart query service. 883 11. Misc Considerations 885 11.1. Return ALTO Information Resources over HTTP/2 887 HTTP/2 [RFC7540] provides new features like streams and multiplexing 888 that can essentially reduce the web interface communication latency. 889 As the growth of deployment of HTTP/2, it is valuable to consider how 890 to transit the ALTO information resources over HTTP/2. 892 The multipart query service defined in this document includes two 893 parts: the multiple-resource query schema and the multipart response 894 schema. 896 By leveraging HTTP/2 multiplexing in the scope of this document, the 897 multipart response schema can be replaced with sending multiple 898 HTTP/2 streams using HTTP/2 server push. Each stream only needs to 899 include a single ALTO information resource. The benefit is that the 900 Server can include additional meta information in the HTTP HEADERS 901 frame of each stream. And the Client can parse each ALTO information 902 resource in parallel. However, the multiple-resource query schema is 903 required to be reused to keep the consistent request semantics. If 904 the Client wants to receive consistent query results, it should send 905 a single multiple-resource query request over the HTTP/2 stream to 906 enforce the Server to generate the response to different ALTO 907 information resources based on the same database snapshot. 909 11.2. Support Incremental Update 911 According to Section 5.2 of [RFC8895], the update stream service can 912 use concatenation of the substream-id, the '.' separator and a 913 Content-ID to identify the update to each part of a multipart 914 response. Thus, each part of a multiple-resource query response MUST 915 include a Content-ID, if the Server provides an update stream service 916 defined in [RFC8895] for this multiple-resource query service. 918 11.3. Anonymous Resources 920 Some use cases may need the server to generate "anonymous" ALTO 921 resources for the on-demand information. The "anonymous" ALTO 922 resources usually cannot appear alone but need to bind with some 923 "non-anonymous" ALTO resources. 925 12. Security Considerations 927 Allow the ALTO clients to upload the query language script may not be 928 safe. The code injection and many potential attacks can be 929 conducted. The security issue should be discussed and considered. 931 To avoid the attacks like the code injection, this document 932 recommends the following approaches: 934 Database Isolation: Some clients may attempt to access the secure 935 database inside the server. Isolate the data into the different 936 databases can reduce the risk of the information leak. 938 Application Container Isolation: Attackers may inject harmful code 939 into the input query programs to attempt to access the system 940 control. To avoid this, each query process is recommended to be 941 isolated using the application container. 943 Resource Limit: Even attackers cannot get the permission to crack 944 the data or the system, they can still inject some heavy-load 945 programs to consume the server resources. Thus, limiting the 946 memory usage and execution time of each query process is highly 947 recommended. 949 13. IANA Considerations 951 13.1. application/alto-* Media Types 953 This document registers an additional ALTO media type, listed in 954 Table 1. 956 +=============+==========================+===============+ 957 | Type | Subtype | Specification | 958 +=============+==========================+===============+ 959 | application | alto-multipartquery+json | Section 6.4 | 960 +-------------+--------------------------+---------------+ 962 Table 1: Additional ALTO Media Type. 964 Type name: application 966 Subtype name: This document registers multiple subtypes, as listed 967 in Table 1. 969 Required parameters: n/a 971 Optional parameters: n/a 973 Encoding considerations: Encoding considerations are identical to 974 those specified for the "application/json" media type. See 975 [RFC8259]. 977 Security considerations: Security considerations related to the 978 generation and consumption of ALTO Protocol messages are discussed 979 in Section 15 of [RFC7285]. 981 Interoperability considerations: This document specifies formats of 982 conforming messages and the interpretation thereof. 984 Published specification: This document is the specification for 985 these media types; see Table 1 for the section documenting each 986 media type. 988 Applications that use this media type: ALTO servers and ALTO clients 989 either stand alone or are embedded within other applications. 991 Additional information: Magic number(s): n/a 993 File extension(s): This document uses the 994 mime type to refer to protocol messages and thus does not 995 require a file extension. 997 Macintosh file type code(s): n/a 999 Person & email address to contact for further information: See 1000 Authors' Addresses section. 1002 Intended usage: COMMON 1004 Restrictions on usage: n/a 1006 Author: See Authors' Addresses section. 1008 Change controller: Internet Engineering Task Force 1009 (mailto:iesg@ietf.org). 1011 14. Acknowledgements 1013 15. References 1015 15.1. Normative References 1017 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1018 Extensions (MIME) Part One: Format of Internet Message 1019 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 1020 . 1022 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1023 Extensions (MIME) Part Two: Media Types", RFC 2046, 1024 DOI 10.17487/RFC2046, November 1996, 1025 . 1027 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1028 Requirement Levels", BCP 14, RFC 2119, 1029 DOI 10.17487/RFC2119, March 1997, 1030 . 1032 [RFC2387] Levinson, E., "The MIME Multipart/Related Content-type", 1033 RFC 2387, DOI 10.17487/RFC2387, August 1998, 1034 . 1036 [RFC7285] Alimi, R., Ed., Penno, R., Ed., Yang, Y., Ed., Kiesel, S., 1037 Previdi, S., Roome, W., Shalunov, S., and R. Woundy, 1038 "Application-Layer Traffic Optimization (ALTO) Protocol", 1039 RFC 7285, DOI 10.17487/RFC7285, September 2014, 1040 . 1042 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1043 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1044 DOI 10.17487/RFC7540, May 2015, 1045 . 1047 [RFC8895] Roome, W. and Y. Yang, "Application-Layer Traffic 1048 Optimization (ALTO) Incremental Updates Using Server-Sent 1049 Events (SSE)", RFC 8895, DOI 10.17487/RFC8895, November 1050 2020, . 1052 15.2. Informative References 1054 [I-D.ietf-alto-path-vector] 1055 Gao, K., Lee, Y., Randriamasy, S., Yang, Y. R., and J. J. 1056 Zhang, "ALTO Extension: Path Vector", Work in Progress, 1057 Internet-Draft, draft-ietf-alto-path-vector-14, 22 1058 February 2021, . 1061 [I-D.ietf-alto-unified-props-new] 1062 Roome, W., Randriamasy, S., Yang, Y. R., Zhang, J. J., and 1063 K. Gao, "ALTO Extension: Entity Property Maps", Work in 1064 Progress, Internet-Draft, draft-ietf-alto-unified-props- 1065 new-17, 16 April 2021, . 1068 [JSONIQ] Robie, J., Fourny, G., Brantner, M., Florescu, D., 1069 Westmann, T., and M. Zaharioudakis, "JSONiq - the SQL of 1070 NoSQL 1.0", JSONiq , 2015. 1072 [RFC8189] Randriamasy, S., Roome, W., and N. Schwan, "Multi-Cost 1073 Application-Layer Traffic Optimization (ALTO)", RFC 8189, 1074 DOI 10.17487/RFC8189, October 2017, 1075 . 1077 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1078 Interchange Format", STD 90, RFC 8259, 1079 DOI 10.17487/RFC8259, December 2017, 1080 . 1082 [RFC8896] Randriamasy, S., Yang, R., Wu, Q., Deng, L., and N. 1083 Schwan, "Application-Layer Traffic Optimization (ALTO) 1084 Cost Calendar", RFC 8896, DOI 10.17487/RFC8896, November 1085 2020, . 1087 [W3CXQUERY] 1088 Robie, J., Chamberlin, D., Dyck, M., and J. Snelson, 1089 "XQuery 3.0: An XML query language", W3C Recommendation, 1090 W3C, 2014. 1092 Appendix A. Figures 1094 TODO: Put additional figures here if we have. 1096 Authors' Addresses 1098 Jingxuan Jensen Zhang 1099 Tongji University 1100 4800 Cao'An Hwy 1101 Shanghai 1102 201804 1103 China 1105 Email: jingxuan.n.zhang@gmail.com 1107 Yang Richard Yang 1108 Yale University 1109 51 Prospect Street 1110 New Haven, CT 1111 United States of America 1113 Email: yry@cs.yale.edu