ALTO Transport Information Publication Service

2.1. TIPS Information

A key design of the ALTO TIPS is to distinguish between network information resource and the transport information (referred to as transport state).¶

• A transport state is always created for a network information resource.¶
• The basic component of a transport state is an updates queue, which contains a sequence of incremental updates about the network information resource. Each incremental update is assigned a sequence number, and a URI can be constructed using the sequence number.¶
• A static network information resource (e.g., Cost Map, Network Map) may need only a single updates queue, and a dynamic network information resource (e.g., Filtered Cost Map) may create an updates queue for each unique filter request.¶
• A transport state is a container that may include other transport information beyond the updates queue. This document also defines the push updates state, to support server push updates.¶

Figure 2 shows an example illustrating the aforementioned components. Each ALTO client (Client 1, Client 2, or Client 3) maintains a single HTTP connection with the ALTO server.¶

Network Information Resource:

a) Static resource (#1) such as NetworkMap
b) Filterable resource (#3) such as FilteredCostMap


                              +-------------+
                              |             |
         +--------------------| ALTO Server |-----------+
         |                  +-|             |-+         |
         |                  | +-------------+ |         |
         |                  |                 |         |
---------|------------------|-----------------|---------|------------
         |                  |                 |         | Network
         |                  |                 |         | Information
+-------------+   +-------------+   +-------------+   +-------------+
| Information |   | Information |   | Information |   | Information |
| Resource #1 |   | Resource #2 |   | Resource #3 |   | Resource #4 |
+-------------+   +-------------+   +-------------+   +-------------+
       |                              /    \
-------|-----------------------------/------\------------------------
       |                            /        \            Transport
       |                      +----/          \------+    Information
       |                      |                      |
  +--------+             +--------+             +--------+
  |   ts1  |-----+       |   ts2  |-----+       |   ts3  |-----+
  +----|---+     |       +----|---+     |       +----|---+     |
       |         |            |         |            |         |
  +----|---+ +---|----+  +----|---+ +---|----+  +----|---+ +---|----+
  | ts1/uq | | ts1/sp |  | ts2/uq | | ts2/sp |  | ts3/uq | | ts3/sp |
  +--------+ +--------+  +--------+ +--------+  +--------+ +--------+
       |\       /\              |         /           |          |
-------|-\-----/--\-------------|--------/------------|----------|---
       |  \   /    +-------+    |       /             |          |
       |   +-/-----------+  \   |      /              |          |
       |    /             \  \  |     /   A           +          +
       |   /            +--\--\-|----/--+ single       \        /
       |  /             +---\--\|---/---+ http2/3       \      /
   +----------+             +----------+  connection   +----------+
   | Client 1 |             | Client 2 |               | Client 3 |
   +----------+             +------- --+               +----------+

tsi    = transport information resource i
tsi/uq = incremental-updates queue of transport information resource tsi
tsi/sp = server push state associated with tsi

2.2. TIPS Work Flow

The intended use case of TIPS is to run it as a service inside an HTTP/2 or HTTP/3 connection. Specifically, an ALTO client opens an HTTP connection with an ALTO server, and uses TIPS to create a transport state at the server for each network information resource that the client wants to monitor. The transport state provides (1) the base URI that the server will host incremental updates for the information resource and (2) the start sequence number that the server will order the updates. The server will assign each additional update with a consecutive sequence number.¶

In the simplest use case, the transport state provides enough information for the client to continuously pull each additional update, resulting in the following work flow:¶

   Client                                  TIPS         URS
     o                                       .           .
     | Open HTTP connection                  .           .
     |-------------------------------------->|           .
     |                                       .           .
     | Create Transport state for resource 1 .           .
     | ------------------------------------> |           .
     | <updates-queue-uri1>, <start-seq>     .           .
     |<------------------------------------- |           .
     |                                       .           .
     | GET <updates-queue-uri1>/content/<start-seq>      .
     | ------------------------------------------------->|
     | update <start-seq> content            .           .
     |<------------------------------------------------->|
     |                                       .           .
     | GET <updates-queue-uri1>/content/<start-seq+1>    .
     | ------------------------------------------------->|
     | update <start-seq+1> content          .           .
     |<------------------------------------------------->|
     |
     | DELETE transport state for resource 1 .
     |-------------------------------------> |
     |
     | Close HTTP connection                 .
     |-------------------------------------->|
     o

     TIPS: Transport Information Publication Service
     URS : Update Read Service

A client that prefers server push can use the following work flow:¶

   Client                                  TIPS         UPS
     o                                       .           .
     | Open HTTP connection                  .           .
     |-------------------------------------->|           .
     |                                       .           .
     | Create Transport state for resource 1 .           .
     |   indicate receiving server push      .           .
     | ------------------------------------> |           .
     | <updates-queue-uri1>, <start-seq>     .           .
     |<------------------------------------- |           .
     |                                       .           .
     | PUSH <updates-queue-uri1>/content/<start-seq>     .
     | <------------------------------------------------ |
     |                                       .           .
     | PUSH <updates-queue-uri1>/content/<start-seq+1>   .
     | <------------------------------------------------ |
     |
     | DELETE transport state for resource 1 .
     |-------------------------------------> |
     |
     | Close HTTP connection                 .
     |-------------------------------------->|
     o

     TIPS: Transport Information Publication Service
     UPS : Update Push Service

3.1. Notations

This document uses the same syntax and notations as introduced in Section 8.2 of RFC 7285 [RFC7285] to specify the extensions to existing ALTO resources and services.¶

4.1. TIPS IRD

An ALTO server's IRD (Information Resource Directory) MAY define one or more transport information publication services, which ALTO clients use to request new TIPS instances. An IRD entry defining a TIPS MUST declare the "media-type", and specify "capabilities" and "uses" as follows.¶

     object {
       IncrementalUpdateMediaTypes incremental-change-media-types;
       Boolean                     support-server-push;
     } TIPSCapabilities;

     object-map {
        ResourceID -> String;
     } IncrementalUpdateMediaTypes;

4.2. Create Transport State using TIPS

     object {
        ResourceID   resource-id;
        [JSONString  tag;]
        [Object      input;]
     } TIPSReq;

          HTTP/1.1 400 Bad Request
          Content-Length: 131
          Content-Type: application/alto-error+json
          Connection: Closed

          {
              "meta":{
                  "code":  "E_INVALID_FIELD_VALUE",
                  "field": "resource-id",
                  "value": "my-networkmap/#"
              }
          }

      object {
        JSONString        transport-state-uri;
        TransportState    transport-state;
      } AddTIPSResponse;

      object {
        UpdatesQueueMeta  updates-queue-meta;
       [PushUpdatesMeta   push-updates-meta;]
      } TransportState;

      object {
        JSONString         uri;
        UpdatesQueueStateSummary state-summary;
      } UpdateQueueMeta;

      object {
        JSONNumber         start-seq;
      } UpdatesQueueStateSummary;

      object {
        JSONString       uri;
        PushUpdatesState state;
      } PushUpdatesMeta;

      object {
         Boolean          push-enabled;
        [JSONNumber       next-seq;]
      } PushUpdatesState;

4.3. Read Transport State using TIPS

An ALTO client can read the transport state using the returned absolute-transport-state-uri (See Section 4.2.2) using the HTTP GET method. For example, if it is on the same connection as that of the invoking TIPS, it is¶

    GET <transport-state-uri>

The response to a valid request MUST be a JSON object of type TransportState defined in Section 4.2, denoted as media type "application/alto-tips+json".¶

4.4. Delete Transport State using TIPS

An ALTO client can delete the transport state using the returned absolute-transport-state-uri using the HTTP DELETE method. If it is on the same connection as that of the invoking TIPS, it is¶

    DELETE <transport-state-uri>

The response to a valid request MUST be 200 if success, and the corresponding error code if there is any error.¶

4.5. Example

For simplicity, assume the ALTO server is using the Basic authentication. If a client with username "client1" and password "helloalto" wants to create a transport queue of an ALTO Cost Map resource with resource ID "my-routingcost-map", it can send the following request:¶

   POST /tips HTTP/1.1
   Host: alto.example.com
   Accept: application/alto-tips+json, application/alto-error+json
   Authorization: Basic Y2xpZW50MTpoZWxsb2FsdG8K
   Content-Type: application/alto-tipsparams+json
   Content-Length: [TBD]

   {
     "resource-id": "my-routingcost-map"
   }

If the operation is successful, the ALTO server returns the following message:¶

   HTTP/1.1 200 OK
   Content-Type: application/alto-tips+json
   Content-Length: [TBD]

   {
      "transport-state-uri": “/tips/2718281828459”,
      "transport-state": {
        "updates-queue-meta" : {
           "uri": "uq",
           "state-summary": {
             "start-seq": 101
           }
        },
        "push-updates-meta" : {
           "uri": "sp",
           "state": {
             "push-enabled" : false,
             "next-seq" : -1
           }
        },

      }
   }

5.1. Media Type

A QSS response uses "application/alto-tipsqueue+json" media type.¶

5.2. HTTP Method

An ALTO QSS resource is requested using the HTTP GET method.¶

5.3. IRD Capabilities and Uses

None (QSS does not appear in the IRD).¶

5.4. Request

An ALTO client reads the queue state using an HTTP GET method, with the path constructed as:¶

     <updates-queue-complete-uri> :=
           <transport-state-uri>/<updates-queue-meta.uri>
           specified in Section 4.

5.5. Response

If the transport state is closed, the ALTO server MUST return an error HTTP message with status code 404 (Not Found) and media type "application/alto-error+json".¶

The response from the server, if no error, is the UpdatesQueue object indicated as "application/alto-tipsqueue+json" media type:¶

    object-map {
        Seq -> UpdateItem;
    } UpdatesQueue;

    object-map {
        JSONString     media-type;
        JSONString     tag;
       [JSONString     link;]
    } UpdateItem;

with field:¶

Seq:

A required, positive JSON integer indicating the sequence number of the incremental update. As JSON allows a large integer space, when the server reaches the largest integer, the server SHOULD close the incremental update queue.¶

media-type:

A required JSON string giving the type of the incremental update (see ALTO/SSE).¶

tag:

A required JSON string which is defined the same way as the "tag" field of VersionTag (see Section 10.3 of [RFC7285]).¶

link:

An optional JSON string giving an optional link for a client to directly request a resource as a complete snapshot (not through incremental updates).¶

5.6. Example

   GET /tips/2718281828459/uq HTTP/1.1
   Host: alto.example.com
   Accept: application/alto-tipsqueue+json, application/alto-error+json
   Authorization: Basic Y2xpZW50MTpoZWxsb2FsdG8K


   HTTP/1.1 200 OK
   Content-Type: application/alto-tipsqueue+json
   Content-Length: [TBD]

   {

        101 : {
            "media-type": "application/alto-costmap+json",
            “tag”:        "a10ce8b059740b0b2e3f8eb1d4785acd42231bfe"
        },
        102 : {
            "media-type": "application/merge-patch+json",
            “tag”:        "cdf0222x59740b0b2e3f8eb1d4785acd42231bfe"
        },
        103 : {
            "media-type": "application/merge-patch+json",
            “tag”:        "8eb1d4785acd42231bfecdf0222x59740b0b2e3f",
            "link":       "/tips/2718281828459/snapshot/2e3f"
        }
   }

An ALTO client can also read the (meta data) of an individual element in the updates queue. The HTTP method MUST also be GET, and the URI is constructed by appending the seq at the end of the preceding URI.¶

6.1. Path

The path to the content of an update item resource has the following format:¶

        <uq-elem-seq> := <updates-queue-complete-uri>/content/<seq>

where updates-queue-complete-uri is specified in Section 5.4.¶

For example, if the client wants to query the content of the first update item (with sequence number 101), it can send a request to "/tips/2718281828459/uq/101".¶

6.2. Media Type

The media type of an Update Item resource MUST be the same as the "media-type" field of the update item with sequence number seq in the updates queue.¶

For example, if the client wants to query the content of the first update item (with sequence number 101) whose media type is "application/alto-costmap+json", it must set the "Accept" header to "application/alto-costmap+json, application/alto-error+json" in the request.¶

6.3. HTTP Method

The Update Read Service resource must be requested using the HTTP GET method.¶

6.4. Capabilities and Uses

None¶

6.5. Response

If the transport state is closed, the ALTO server MUST return an error HTTP message with status code 404 (Not Found) and media type "application/alto-error+json".¶

Otherwise, let LOW_SEQ and HIGH_SEQ represent the smallest and largest sequence number in the updates queue of the transport state respectively. If seq is smaller than LOW_SEQ, the ALTO server MUST return an error HTTP message with status code 410 (Gone) and media type "application/alto-error+json". If seq is greater than HIGH_SEQ, the ALTO server MAY either treat the request as a long polling request and save it as a pending request; if the server wants to conduct resource control, the server can return an error code and indicate the "Re-Try After" headers.¶

If the request is valid, the response is encoded as a JSON object whose data format is indicated by the media type.¶

6.6. Example

Assume the client wants to get the contents of updates 101, the request is:¶

      GET /tips/2718281828459/uq/content/101 HTTP/1.1
      Host: alto.example.com
      Accept: application/alto-costmap+json, application/alto-error+json

And the response will be¶

   HTTP/1.1 200 OK
   Content-Type: application/alto-costmap+json
   Content-Length: [TBD]

   { ... full replacement of my-routingcost-map ... }

9.1. Considerations for Choosing Updates

TIPS should be cognizant of the effects of its update schedule, which includes both the choice of timing (i.e., when/what to trigger an update on the updates queue) and the choice of message format (i.e., given an update, send a full replacement or an incremental change). In particular, the update schedule can have effects on both the overhead and the freshness of information. To minimize overhead, TIPS may choose to batch a sequence of updates for resources that frequently change by cumulative updates or a full replacement after a while. TIPS should be cognizant that batching reduces the freshness of information. The server should also consider the effect of such delays on client behaviors (see below on client timeout on waiting for updates of dependent resources).¶

For incremental updates, this design allows both JSON patch and JSON merge patch for incremental changes. JSON merge patch is clearly superior to JSON patch for describing incremental changes to cost maps, endpoint costs, and endpoint properties. For these data structures, JSON merge patch is more space efficient, as well as simpler to apply. There is no advantage allowing a server to use JSON patch for those resources.¶

The case is not as clear for incremental changes to network maps.¶

First, consider small changes, such as moving a prefix from one PID to another. JSON patch could encode that as a simple insertion and deletion, while JSON merge patch would have to replace the entire array of prefixes for both PIDs. On the other hand, to process a JSON patch update, the ALTO client would have to retain the indexes of the prefixes for each PID. Logically, the prefixes in a PID are an unordered set, not an array; aside from handling updates, a client has no need to retain the array indexes of the prefixes. Hence, to take advantage of JSON patch for network maps, ALTO clients would have to retain additional, otherwise unnecessary, data.¶

Second, consider more involved changes, such as removing half of the prefixes from a PID. JSON merge patch would send a new array for that PID, while JSON patch would have to send a list of remove operations and delete the prefix one by one.¶

Therefore, each TIPS may decide on its own whether to use JSON merge patch or JSON patch according to the changes in network maps.¶

9.2. Considerations for Client Processing Updates

In general, when an ALTO client receives a full replacement for a resource, the ALTO client should replace the current version with the new version. When an ALTO client receives an incremental change for a resource, the ALTO client should apply those patches to the current version of the resource.¶

However, because resources can depend on other resources (e.g., cost maps depend on network maps), an ALTO client MUST NOT use a dependent resource if the resource on which it depends has changed. There are at least two ways an ALTO client can do that. The following paragraphs illustrate these techniques by referring to network and cost map messages, although these techniques apply to any dependent resources.¶

Note that when a network map changes, the update stream server MUST send the network map update message before sending the updates for the dependent cost maps (see Section 6.7.1).¶

One approach is for the ALTO client to save the network map update message in a buffer and continue to use the previous network map and the associated cost maps until the ALTO client receives the update messages for all dependent cost maps. The ALTO client then applies all network and cost map updates atomically.¶

Alternatively, the ALTO client MAY update the network map immediately. In this case, the cost maps using the network map become invalid because they are inconsistent with the current network map; hence, the ALTO client MUST mark each such dependent cost map as temporarily invalid and MUST NOT use each such cost map until the ALTO client receives a cost map update indicating that it is based on the new network map version tag.¶

When implementing server push, the server SHOULD send updates for dependent resource (i.e., the cost maps in the preceding example) in a timely fashion. However, if the ALTO client does not receive the expected updates, a simple recovery method is that the ALTO client uses client pull to request the missing update. The ALTO client MAY retain the version tag of the last version of any tagged resources and search those version tags when identifying the new updates to pull. Although not as efficient as possible, this recovery method is simple and reliable.¶

9.3. Considerations for Updates to Filtered Cost Maps

If TIPS provides updates to a Filtered Cost Map that allows constraint tests, then an ALTO client MAY request updates to a Filtered Cost Map request with a constraint test. In this case, when a cost changes, the updates queue MUST have an update if the new value satisfies the test. If the new value does not, whether there is an update depends on whether the previous value satisfied the test. If it did not, the updates queue SHOULD NOT have an update. But if the previous value did, then the updates queue MUST add an update with a "null" value to inform the ALTO client that this cost no longer satisfies the criteria.¶

TIPS can avoid having to handle such a complicated behavior by offering TIPS only for Filtered Cost Maps that do not allow constraint tests.¶

9.4. Considerations for Updates to Ordinal Mode Costs

For an ordinal mode cost map, a change to a single cost point may require updating many other costs. As an extreme example, suppose the lowest cost changes to the highest cost. For a numerical mode cost map, only that one cost changes. But for an ordinal mode cost map, every cost might change. While this document allows TIPS to offer incremental updates for ordinal mode cost maps, TIPS implementors should be aware that incremental updates for ordinal costs are more complicated than for numerical costs, and ALTO clients should be aware that small changes may result in large updates.¶

A TIPS can avoid this complication by only offering full replacements as updates in the updates queue for ordinal cost maps.¶

10.1. TIPS: Denial-of-Service Attacks

Allowing persistent TIPS states enables a new class of Denial-of-Service attacks. In particular, For the TIPS server, an ALTO client might create an unreasonable number of transport states.¶

To avoid these attacks on the TIPS server, the server SHOULD choose to limit the number of active states and reject new requests when that threshold is reached. The Update Read Service allows predicative fetching and the server SHOULD also choose to limit the number of pending requests. In these cases, the update stream server SHOULD return the HTTP status "503 Service Unavailable".¶

It is important to note that the preceding approaches are not the only possibilities. For example, it may be possible for TIPS to use somewhat more clever logic involving IP reputation, rate-limiting, and compartmentalization of the overall threshold into smaller thresholds that apply to subsets of potential clients.¶

10.2. ALTO Client: Update Overloading or Instability

The availability of continuous updates, when the client indicates receiving server push, can also cause overload for an ALTO client, in particular, an ALTO client with limited processing capabilities. The current design does not include any flow control mechanisms for the client to reduce the update rates from the server. Under overloading, the client MAY choose to remove the information resources with high update rates.¶

Also, under overloading, the client may no longer be able to detect whether information is still fresh or has become stale. In such a case, the client should be careful in how it uses the information to avoid stability or efficiency issues.¶

10.3. Spoofed URI

An outside party that can read the TIPS response or that can observe TIPS requests can obtain the transport state URI and use that to send a fraudulent "DELETE" requests, thus disabling the service for the valid ALTO client. This can be avoided by encrypting the requests and responses (see Section 15 of [RFC7285]).¶

In general, as the architecture allows the possibility for TIPS, URS and UPS to be different entities, the additional risks should be evaluated and remedied. For example, the private communication path between the servers may be attacked, resulting in a risk of communications breakdown between them, as well as invalid or spoofed messages claiming to be on that private communications path. Proper security mechanisms, including confidentiality, authenticity, and integrity mechanisms, should be considered.¶