Configuring destinations

Destination configuration

A destination configuration can specify:

name

A resource name, URL or wild card pattern. The connection infrastructure uses the name to select the appropriate destination configuration for a individual request.

handlers

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

connection

An optional set of static protocol configuration that is applied to requests sent to the destination.

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

/config/connection/destinations += {
    "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 shown in the following example:

• 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

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 is used.

Destination processing

The following list contains the destination processing rules used by the connection infrastructure:

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