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 a recognized URL protocol are normalized before matching, using the following rules:

• 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 user information, query parameters and fragment references are discounted. For example, specifying http://www.projectzero.org/service?q=value is equivalent to specifying http://www.projectzero.org:80/service

The following points should be noted:

1. The URL matching algorithm requires the host address strings to be identical. For example, http://localhost/file.txt and http://127.0.0.1/file.txt will be treated as separate connection destinations.
2. The original target resource name associated with the connection request remains unaffected. For example, if the target resource name is http://www.projectzero.org/service?q=value, its normalized value can be matched against either a destination named http://www.projectzero.org:80/service or one named http://www.projectzero.org/service but the target resource name will continue to be http://www.projectzero.org/service?q=value
3. The normalization of target resource URLs is only applied when matching a target resource name against the configured connection destination names. It is not applied when reading destination configurations from the configuration file. For example, destination configurations named http://www.projectzero.org/* and http://www.projectzero.org:80/* remain discrete despite their normalized names being identical. A connection request to the target resource http://www.projectzero.org/service can match either destination after normalization, but only one will be selected. Care should be taken when configuring destinations to avoid such ambiguity.

Destination processing

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

1. The 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 a default destination configuration with no handlers or connection configuration is used.
3. If the destination configuration contains a handlers list, then the configured connection handlers' request phase methods are executed in the order specified.
   • If any connection handler determines that the request should go no further then response processing immediately begins at Step 7, starting with the previous connection handler.
   • If the target resource (/connection/request/target) value is changed during connection handler processing, the request is logically routed to the next destination and processing continues from Step 1.
4. If the final destination configuration contains a connection configuration, it is applied to the request.
5. The request is sent to the resource using the appropriate protocol transport implementation.
6. When the application requests the response, it is collected from the target resource.
7. Any configured connection handlers' response phase methods are executed, in reverse order.
8. If the request was logically routed through more than one destination then the response is returned to the previous destination and processing continues from Step 7.