Configuring destinations

A destination configuration can be used to specify how interactions with a resource made using the Connection API should be handled. A destination configuration can specify:

name

A resource name, URL or wild card pattern. This is used by the connection infrastructure to select the appropriate destination configuration for a individual request.

handlers

An optional list of connection handlers that will be executed during request and response processing.

connection

An optional set of static protocol configuration which will be applied to requests sent to the destination.

For more information on the connection configuration, see Configuring protocols. For more information on the handlers configuration, see Configuring connection handlers.

Destination configurations are made under /config/connection/destinations in zero.config. The following is simple example which specifies the HTTPS configuration which should be used when sending requests to URLs matching the wild card name value.

/config/connection/destinations += [{
        "name" : "https://www.projectzero.org/*",
        "connection" : {
                "protocol" : "https",
                "config" : { "httpsConfig" : "myHttpsConfig" }
        }
}]

Destination name matching

Destination configuration name values ending with a * character are interpreted as wild card names. The wild card must be the last character in the name value.

Configured destination name and target resource names conforming to recognized URL schemata are normalized before matching as follows:

• Default port numbers implicitly added as necessary. For example, specifying http://www.projectzero.org/ is equivalent to specifying http://www.projectzero.org:80/
• Any leading zeros on explicit port numbers are removed. For example, specifying http://www.projectzero.org:080/ is equivalent to specifying http://www.projectzero.org:80/
• Only the protocol, host, port and file name are used for destination matching. Other items such as query parameters or local anchor references are discounted. For example, specifying http://www.projectzero.org/service?q=value is equivalent to specifying http://www.projectzero.org:80/service

Note that the URL matching algorithm requires the host address strings to be identical. For example, localhost and 127.0.0.1 are treated as separate destinations by the connection infrastructure.

Destination configurations are not required in order to use the Connection API. If no matching destination configuration is found for a request then a default configuration with empty connection handler and protocol configuration will be used.

Destination processing

The destination processing rules used by the connection infrastructure are as follows:

1. Target resource (/connection/request/target) is compared with the list of configured destinations:
   • If a destination name is an exact match for the target resource then it will be selected.
   • If no exact match is found, then the destination with the longest wild card name which matches the target resource will be selected.
   • If no matching destination is found then the default destination configuration is used (no handlers or connection configuration).
2. If the destination configuration contains a handlers list then the configured connection handlers are executed in the order specified.
   • If the target resource (/connection/request/target) value has been changed during connection handler processing, the request is logically routed to the next destination (Step 1).
3. If the destination configuration contains a connection configuration, it is applied to the request and the request is sent to the resource.
4. When the response is received from the resource, any configured connection handlers are executed in the reverse of the order they were specified.
   • If the request was logically routed through more than one destination, then the connection handlers of each destination are executed in reverse order.

It is important to note that under the above processing rules, a connection configuration is only applied if the handlers configured for a destination have not modified the target resource (/connection/request/target) value.