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_null

Immediately returns an empty response, matching the type of request sent to it. Get requests result in a MISS result. Set requests result in a NOT_STORED result. Numerical, touch, and delete commands result in NOT_FOUND.

route_null{}

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,
    miss = MISS_BOOLEAN,
    wait = WAIT_FLOAT,
}

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".

  • MISS_BOOLEAN: if true, wait until first good (hit) response or all children return

  • WAIT_FLOAT: wait at most this amount of time in seconds before returning the best result we have so far (fractional time allowed)

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,
    wait = WAIT_FLOAT,
    local_zone = ZONE_NAME,
}

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".
    • See Prioritize a route using local zones - if a zoned pool set is supplied and local_zone is configured, the local zone is tried first.
  • LOCAL_ZONE: Override the local zone.
  • 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.
  • WAIT_FLOAT: wait at most this amount of time in seconds before failing over to the next pool (fractional time allowed)

route_ratelim

NOTE: This route handler is EXPERIMENTAL, and the arguments or behavior may change.

This route handler uses a Token Bucket Filter algorithm to rate limit requests sent to the child pool. On failure a “null” response is returned (see route_null)

route_ratelim{
    child = "POOL_NAME",
    limit = LIMIT,
    fillrate = FILLRATE,
    tickrate = MILLISECONDS,
    global = GLOBAL_BOOLEAN,
    fail_until_limit = FAIL_UNTIL_BOOLEAN,
}

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

  • LIMIT: The maximum size of the buckets, in requests.
  • FILLRATE: The amount to refill the bucket, after every fillrate amount of time has passed.
  • TICKRATE: The amount of time, in milliseconds, between each refill of the bucket.
  • GLOBAL_BOOLEAN: By default one bucket is created for every worker thread the proxy is configured for. With this option set to true, this limit is global to the whole process, at the expense of being slower. In this case the bucket data structure is covered by a single mutex.
  • FAIL_UNTIL_BOOLEAN: With this set to true, the limiter will instead fail until the rate limit has been exceeded. This can be used to automatically enable a proxy-local data cache when the server is busy.

route_random

Routes to a random pool from the list of children.

route_random{
    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_zfailover

NOTE: This function has been deprecated. Its functionality is available in route_failover and route_allfatest

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