Skip to main content

Road network concepts

This page describes some Global Dcc core concepts related to the road network of a native Dcc, which we denote by RoadNet or simply RN. For the purpose of this page (or the Global Dcc) , a RoadNet is the collection of configuration and data loaded into a native Dcc: its DccMulti.xml together with any data files referenced therein.

The content presented here may change substantially in the future: the CR - RoadNet Update Framework is not fully implemented yet (cache recalculation missing).

RoadNet id and version​

Each Global Dcc backend may have several native Dcc instances. The RoadNet data loaded into such a native instance is characterized by two identifiers:

  • The road network id is a 'public' identifier of the RN for consumers of the api:
    • The Api exposes an endpoint which lists its available RN ids together with a description of the road network.
    • Api consumers must specify a RN id to use for their request.
    • One use case of a RN id is to delimit the geographical area on which customers can expect the Dcc to perform the calculation request.
    • Each backend instance is assigned to exactly one RN id which does not change (until restarted).
  • The road network version identifies the configuration and data currently used by a native backend of a given RN id:
    • It is the name of the subfolder where a native backend instance expects to find its configuration file (DccMulti.xml).
    • It is a sub-identifier for a given RN id (only version strings for the same RN id must be unique).
    • It is an internal identifier in the sense that api consumers can only choose the RN (id) but not the specific version of the RN that the backend uses. But it is not hidden from consumers: Replies from the Api both include its RN version and the one used by the backend that handled the request.

This allows us to push versioned data updates to deployed backends, without requiring consumers to update their RN id. And without downtime (see details on the backends update process below).

RoadNet manager​

Each road network (id) has only one single active version, defined as the current entry in the RN version source: a shared key-value store (key: id, value: version) that both api and backend can read from. They do so for example on startup to determine the current version for the RN ids. If no entry exists, they use the value 'default', defined in the file RoadNet.cs from the project GlobalDcc.RoadNetwork.

The RoadNet manager is a simple .Net web app with REST endpoints for internal use (no access for regular consumers) to manage the entries of the version source and notify other services (apis and backends) of changes. For example, using the RN managers POST endpoint for RN (id_x) with payload new_version, results in:

  1. RN manager updates the value for key id_x in the 'version source' to new_version.
  2. RN manager publishes a message that the version for id_x changed.
  3. The subscribed apps update their version:
    • Apis query the 'version source' and update their RN version to new_version.
    • Backends whose RN id matches id_x query the 'version source'. And if new_version differs from their currently loaded version, they start to load the new data from a subfolder named new_version into a separate native instance. Once this has completed, it is swapped with the native instance that handles requests.

As a consequence, backends for the same RN id may have sometimes different versions loaded:

  • When some of the backends are in the process of updating, while others have finished. This is expected to be temporary.
  • When some backend failed to perform the update. This will persist until the backend server itself is restarted or receives a new notification from the RN manager.

Consequences for the Dcc Cache​

Both the used id and version used to compute a Dcc result are part of the cache key.

One single api request should return a consistent result, being computed with the same RN version. This complicates the flow for 1xN requests, where an api might find a partial cache match of k entries for its currently active RN version. It will forward both the original request and a 1x(N-k) request together with k cached results to the backend. If the backends RN version differs from the apis, the backend has to discard the k cached results and process the full original request.