Features
Built-in proxy
Route handler reference

Route handler reference

This page is a reference for the route handlers provided by the standard route library of the Memcached built-in proxy.

For a guide to invoking these route handlers in your proxy configuration file, see Configure the built-in proxy. For examples, see Example configuration files.

Route handlers

route_direct

Routes the request to a single pool, and returns the result.

route_direct{
    child = "POOL_NAME"
}

Replace POOL_NAME with the name of a pool defined in the pools{} block of your configuration file.

route_allsync

Routes the request to a list of pools, in parallel.

The proxy waits for all responses to complete. If the proxy receives an error from any of the pools, then the proxy returns the first error that it received. Otherwise, it returns the last result that it received.

route_allsync{
    children = POOL_LIST_OR_SET_NAME
}

Replace POOL_LIST_OR_SET_NAME with either one of the following:

  • A bracketed, comma-separated list of of pool names defined in the pools{} block of your configuration file—for example, { "cust_pool_1", "cust_pool_2" }.

  • The name of a set defined in the pools{} block of your configuration file—for example, "set_cust_pools".

route_allfastest

Routes the request a list of pools, in parallel.

The proxy returns the first response that it receives from any pool.

route_allfastest{
    children = POOL_LIST_OR_SET_NAME
}

Replace POOL_LIST_OR_SET_NAME with either one of the following:

  • A bracketed, comma-separated list of of pool names defined in the pools{} block of your configuration file—for example, { "cust_pool_1", "cust_pool_2" }.

  • The name of a set defined in the pools{} block of your configuration file—for example, "set_cust_pools".

route_split

Routes a request to exactly two pools.

The proxy waits only for a response from the pool assigned to the argumment child_a, and returns the result received from it.

route_split{
    child_a = "POOL_NAME_A"
    child_b = "POOL_NAME_B"
}

Replace the following:

  • POOL_NAME_A: the name of a pool defined in the pools{} block of your proxy configuration file.
  • POOL_NAME_B: the name of a different pool defined in the pools{} block of your proxy configuration file.

route_ttl

Sets the time to live in a set, add, cas, or ms request.

For more information about these requests, see Basic Text Protocol.

route_ttl{
  ttl = TTL,
  child = "POOL_NAME"
}

Replace the following:

  • TTL: an integer representing the new TTL value.
  • POOL_NAME: the name of a pool defined in the pools{} block of your configuration file.

route_failover

Routes the request to a list of pools, serially. You can tune the behavior of this handler by passing in additional arguments.

route_failover{
    children = POOL_LIST_OR_SET_NAME,
    failover_count = FAILOVER_COUNT,
    shuffle = SHUFFLE_BOOLEAN,
    miss = MISS_BOOLEAN,
}

Replace the following:

  • POOL_LIST_OR_SET_NAME: either one of the following:
    • A bracketed, comma-separated list of of pool names defined in the pools{} block of your configuration file—for example, { "cust_pool_1", "cust_pool_2" }.
    • The name of a set defined in the pools{} block of your configuration file—for example, "set_cust_pools".
  • FAILOVER_COUNT: the number of times we will try another pool in the list before returning an error.
  • SHUFFLE_BOOLEAN: if true, then the proxy randomizes the list of pools before routing the request. Otherwise, uses the list of pools in the given order.
  • MISS_BOOLEAN: if true, then the proxy treats both misses and errors as failures. Otherwise, the proxy counts only errors as failures.

route_zfailover

Routes the request to a named set of pools. You can tune the behavior of this handler by passing in additional arguments.

To use this handler, you need to define zones in your configuration file. For more information, see Prioritize a route using local zones.

route_zfailover{
    children = "SET_NAME",
    stats = true,
    miss = true
}

Replace the following:

  • SET_NAME: the name of a set of pools defined in the pools{} block of your configuration file.
  • STATS_BOOLEAN: if true, then Memcached includes a tally of failovers in the response to the stats proxy command.
  • MISS_BOOLEAN: if true, then the proxy treats both errors and missing cache data failures. Otherwise, the proxy counts only errors as failures.

Restrict route handlers to certain commands

By default, the proxy chooses a route for a request regardless of the Memcached command in that request. You can restrict routes to handle only certain Memcached commands by wrapping route handler invocations in a cmdmap{} call:

cmdmap {
    COMMAND = ROUTE_HANDLER
}

Replace the following:

  • COMMAND: a Memcached command—for example, set. For a command list, see Basic Text Protocol.
  • ROUTE_HANDLER: a full route-handler defnition—for example, route_direct{ [...] }.

You can use a cmdmap{} call in your configuration file in any place where a route handler call is valid. The following example map{} block defines a route that proxy uses only for keys with the prefix main and the command set:

    map = {
        main = cmdmap{
            set = route_direct{
                child = "main_pool",
            },
        },
    },
Frequently asked questionsProxy settings reference