### Install Mcrouter on Ubuntu 16.04

Source: https://github.com/facebook/mcrouter/wiki/mcrouter-installation

Commands to clone the repository, run the automated installation script, and verify the installation.

```bash
$ git clone git@github.com:facebook/mcrouter.git
$ ./mcrouter/mcrouter/scripts/install_ubuntu_16.04.sh /home/$USER/mcrouter-install/ -j4
[sudo] password for ...:
...
$ ~/mcrouter-install/install/bin/mcrouter --help
```

--------------------------------

### Build and Install Mcrouter

Source: https://github.com/facebook/mcrouter/wiki/Home

Standard autotools build process for compiling and installing the software.

```Shell
autoreconf --install
./configure
make
sudo make install
mcrouter --help
```

--------------------------------

### Standalone Flavor Example File

Source: https://github.com/facebook/mcrouter/wiki/Flavors

Example content for a standalone flavor file, specifying overrides for libmcrouter options and standalone process options.

```javascript
{
  "libmcrouter_options": {
    "default_route": "/region3/"
  },
  "standalone_options": {
    "ports": "5000"
  }
}
```

--------------------------------

### Install gnutls-utils

Source: https://github.com/facebook/mcrouter/wiki/SSL-Setup

Installs the necessary utilities for certificate management. Use yum for RHEL/CentOS/Fedora and apt-get for Debian/Ubuntu.

```bash
yum install gnutls-utils
```

```bash
apt-get install gnutls-utils
```

--------------------------------

### Build and Install from Source

Source: https://github.com/facebook/mcrouter/blob/main/README.md

Standard autotools build process for compiling Mcrouter from source.

```bash
$ autoreconf --install
$ ./configure
$ make
$ sudo make install
$ mcrouter --help
```

--------------------------------

### Run Mcrouter with Basic Configuration

Source: https://github.com/facebook/mcrouter/blob/main/README.md

Start a local mcrouter instance and test it using netcat.

```bash
$ mcrouter \
    --config-str='{"pools":{"A":{"servers":["127.0.0.1:5001"]}},
                  "route":"PoolRoute|A"}' \
    -p 5000
$ echo -ne "get key\r\n" | nc 0 5000
```

--------------------------------

### Start mcpiper

Source: https://github.com/facebook/mcrouter/wiki/Mcpiper

Basic command to start mcpiper, optionally specifying a custom fifo root directory.

```bash
$ mcpiper 
# If you started mcrouter using another directory as the debug fifos root:
$ mcpiper --fifo-root="<PATH>"
```

--------------------------------

### If Macro Example

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Example of calling the built-in 'if' macro.

```APIDOC
## If Macro Example

### Description
Calling a call to a built-in macro `if` in extended form.

### Request Example
```json
{
  "type": "if",
  "vars": {
    "A": 5
  },
  "condition": true,
  "is_true": "&#064;add(%A%, 1)",
  "is_false": "&#064;add(%A%, 2)"
}
```

Note: here we have three required parameters (condition, is_true, is_false) for the macro `if`, we also define a local variable `A`. We can write similar code in an inline form `&#064;if(&#064;bool(true),&#064;add(5,1),&#064;add(5,2))`, though we don't have a way to define local vars.
```

--------------------------------

### Install Mcrouter on Ubuntu

Source: https://github.com/facebook/mcrouter/blob/main/README.md

Commands to add the repository key, update sources, and install the package on Ubuntu Bionic.

```bash
$ wget -O - https://facebook.github.io/mcrouter/debrepo/bionic/PUBLIC.KEY | sudo apt-key add
```

```bash
deb https://facebook.github.io/mcrouter/debrepo/bionic bionic contrib
```

```bash
$ sudo apt-get update
```

```bash
$ sudo apt-get install mcrouter
```

--------------------------------

### Merge Operation Examples

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Examples demonstrating the merge operation for strings, arrays, and objects. Note that object properties are merged with later keys overriding earlier ones.

```php
{
  "type": "merge",
  "params": [ "foo", "bar" ]
}
```

```php
{
  "type": "merge",
  "params": [ [ "a", "b", "c" ], [ "ab", "c" ] ]
}
```

```php
{
  "type": "merge",
  "parmas": [
    {
      "foo": 1
    },
    {
      "bar": 2
    },
    {
      "foo": 3
    }
  ]
}
```

```php
{
  "foo": 3,
  "bar": 2
}
```

--------------------------------

### OperationSelectorRoute Configuration Example

Source: https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles

Configure OperationSelectorRoute to direct traffic based on request operations. This example sends gets and sets to pool A, and deletes to pools A and B.

```json
{
  "type": "OperationSelectorRoute",
  "default_policy": "PoolRoute|A",
  "operation_policies": {
    "delete": {
      "type": "AllSyncRoute",
      "children": [ "PoolRoute|A", "PoolRoute|B" ]
    }
  }
}
```

--------------------------------

### Install mcrouter Headers

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Installs header files from the mcrouter/ subdirectory, excluding specific patterns. Use this to ensure necessary header files are available for external projects.

```cmake
install(
  DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/mcrouter/
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/mcrouter
  FILES_MATCHING
    PATTERN "*.h"
    PATTERN "*.tcc"
    PATTERN "facebook" EXCLUDE
    PATTERN "test" EXCLUDE
    PATTERN "build" EXCLUDE
)
```

--------------------------------

### Run Mcrouter with Basic Configuration

Source: https://github.com/facebook/mcrouter/wiki/Home

Starts the proxy on port 5000, routing requests to a memcached instance on port 5001.

```Shell
mcrouter \
    --config-str='{"pools":{"A":{"servers":["127.0.0.1:5001"]}},"route":"PoolRoute|A"}' \
    -p 5000
```

--------------------------------

### Configure and Install CMake Package Config File

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Generates and installs the mcrouter CMake package configuration file. This is essential for other projects to find and use mcrouter via `find_package`.

```cmake
include(CMakePackageConfigHelpers)
configure_package_config_file(
  ${CMAKE_CURRENT_SOURCE_DIR}/CMake/mcrouter-config.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/mcrouter-config.cmake
  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/mcrouter
)

install(
  FILES ${CMAKE_CURRENT_BINARY_DIR}/mcrouter-config.cmake
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/mcrouter
)
```

--------------------------------

### Start Mcrouter with Default Route

Source: https://github.com/facebook/mcrouter/wiki/Multi-cluster-broadcast-setup

Command to launch mcrouter specifying a configuration file, port, and default routing prefix.

```bash
./mcrouter -f $CONFIG_FILE -p $PORT -R /a/a/
```

--------------------------------

### Constant Definition Example

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Shows how to define a reusable constant with a string value in mcrouter.

```php
{
  "type": "constDef",
  "result": {
    "foo": "bar"
  }
}
```

--------------------------------

### JSONM Comments Example

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Demonstrates how C-style comments are handled in JSONM and removed during preprocessing.

```php
{
  // some comment here
  "key": /* and one more comment here */ "value/**/"
}
```

```php
{
  "key": "value/**/"
}
```

--------------------------------

### Install Generated Headers

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Installs generated header files required by mcrouter. These are typically created during the build process.

```cmake
install(
  FILES
    ${CMAKE_CURRENT_BINARY_DIR}/mcrouter/config.h
    ${CMAKE_CURRENT_BINARY_DIR}/mcrouter/config-impl.h
    ${CMAKE_CURRENT_BINARY_DIR}/mcrouter/RouterRegistry.h
    ${CMAKE_CURRENT_BINARY_DIR}/mcrouter/ThriftAcceptor.h
    ${CMAKE_CURRENT_BINARY_DIR}/mcrouter/mcrouter_sr_deps.h
    ${CMAKE_CURRENT_BINARY_DIR}/mcrouter/HostWithShard-fwd.h
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/mcrouter
)
```

--------------------------------

### Example: Merging Libmcrouter and Standalone Flavors

Source: https://github.com/facebook/mcrouter/wiki/Flavors

Illustrates how standalone flavor options, specifically in 'libmcrouter_options', can override settings from the base libmcrouter flavor file.

```bash
$ mcrouter /var/mcrouter/myflavor
```

```bash
$ mcrouter --default-route='/region3/' --config-file='mcrouter_config.json' -p 5000
```

--------------------------------

### Iteration 'foreach' macro configuration

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Example of a 'foreach' macro used to filter and transform items from an input collection.

```json
{
  "type": "foreach",
  "key": "keyRename",
  "item": "itemRename",
  "from": {
    "foo": 1,
    "bar": 2,
    "baz": 3,
    "abc": 5
  }
  "where": "@equals(@mod(@int(%itemRename%), @int(2)), 1)",
  "use": [ "%keyRename%" ],
  "top": 2
}
```

--------------------------------

### Mcrouter Configuration Example

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Illustrates a complex mcrouter configuration with macros and an import statement. This config requires two files: 'test.json' for the main configuration and 'pools.json' for pool definitions.

```json
{
  "macros": {
    "myRoute": {
      "type": "macroDef",
      "params": ["poolName"],
      "result": "PoolRoute|%poolName%"
    }
  },
  "pools": "@import(pools.json)",
  "route": {
    "type": "AllSyncRoute",
    "children": [
      "@myRoute(foo)",
      "@myRoute(bar)"
    ]
  }
}
```

```json
{
  "foo": { "servers": ["localhost:10001"] },
  "bar": { "servers": ["localhost:10002"] }
}
```

--------------------------------

### Mcrouter Command Line for Clusters

Source: https://github.com/facebook/mcrouter/wiki/Routing-Prefix

Use these commands to start mcrouter in different clusters, specifying the configuration file, port, and default routing prefix.

```bash
./mcrouter -f $CONFIG_FILE -p $PORT -R /datacenter/cluster0/
```

```bash
./mcrouter -f $CONFIG_FILE -p $PORT -R /datacenter/cluster1/
```

--------------------------------

### Extended If Macro Example

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Demonstrates the extended form of the 'if' macro, including local variable definition and conditional logic.

```php
{
  "type": "if",
  "vars": {
    "A": 5
  },
  "condition": true,
  "is_true": "@add(%A%, 1)",
  "is_false": "@add(%A%, 2)",
}
```

--------------------------------

### Test Mcrouter Connectivity

Source: https://github.com/facebook/mcrouter/wiki/Home

Uses Netcat to send a memcached get command to the proxy.

```Shell
echo -ne "get key\r\n" | nc 0 5000
```

--------------------------------

### Conditional 'if' macro configuration

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Example of an 'if' macro configuration that conditionally selects keys based on a modulo operation.

```json
      "type": "if",
      "condition": "@equals(@int(0), @mod(%myCustomItemName%, @int(2)))",
      "is_true": [ "%myCustomKeyName%", "%myCustomKeyName%-clone" ],
      "is_false": "%myCustomKeyName%"
    }
  }
}
```

```json
{
  "bar": 1,
  "baz": 2,
  "baz-clone": 2,
}
```

--------------------------------

### Install mcrouter Targets Export

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Installs the mcrouter targets export file, which allows other CMake projects to link against mcrouter targets using a specified namespace.

```cmake
install(
  EXPORT mcrouter-targets
  NAMESPACE mcrouter::
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/mcrouter
)
```

--------------------------------

### Get Mcrouter Options

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves a list of command-line options and their values, separated by spaces. Options are identified by their internal names.

```bash
get __mcrouter__.options
```

--------------------------------

### Get Mcrouter Version

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the version string of the mcrouter build. This command is equivalent to running the 'version' command.

```bash
get __mcrouter__.version
```

--------------------------------

### Get Mcrouter Preprocessed Config

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Displays the loaded configuration with all macros expanded. This is useful for debugging macro definitions.

```bash
get __mcrouter__.preprocessed_config
```

--------------------------------

### Get Mcrouter Config String

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the configuration string of mcrouter. This command will return an error if the configuration was loaded from a file.

```bash
get __mcrouter__.config
```

--------------------------------

### Asynclog v1 Entry Format

Source: https://github.com/facebook/mcrouter/wiki/Features

Example of a JSON serialized array entry in the v1 asynclog format, representing a failed delete command.

```json
["AS1.0",1410611165.754,"C",["127.0.0.1",5001,"delete key\r\n"]]
```

--------------------------------

### Get Mcrouter Config Sources Info

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Provides MD5 hashes for each tracked configuration file, including those imported via '@import'. This is useful for verifying that mcrouter is running with the correct configuration version.

```bash
get __mcrouter__.config_sources_info
```

--------------------------------

### Define Day in Seconds Macro

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Example of defining a constant value for 'dayInSeconds' using a multiplication macro. This is useful for time-based configurations.

```json
[
  ],
  [
    {
      "dayInSeconds": {
        "type": "constDef",
        "result": "@mul(3600,24)"
      }
    }
  ]
]
```

--------------------------------

### Macro Definitions Example

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Illustrates defining a macro named 'isOdd' that checks if a given value is odd. It accepts one parameter 'value' and uses built-in macros for the check.

```php
[
  [
    {
      "isOdd": {
        "type": "macroDef",
        "params": [ "value" ],
        "result": "@equals(@mod(%value%,2),1)"
      }
    }
  ]
]
```

--------------------------------

### Get Mcrouter Config File Location

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the location of the configuration file. This command will return an error if the configuration was loaded from a string.

```bash
get __mcrouter__.config_file
```

--------------------------------

### Define Target Include Directories

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Specifies interface include directories for the mcrouter_deps target, including build and install paths, and external library include directories.

```cmake
target_include_directories(mcrouter_deps
  INTERFACE
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
    $<BUILD_INTERFACE:${LIBEVENT_INCLUDE_DIR}>
    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)
```

--------------------------------

### Configure Full Replication for 2-Level Caching

Source: https://github.com/facebook/mcrouter/wiki/Two-level-caching

Replicates all write operations to both shared and local pools to ensure data consistency. Gets use MissFailoverRoute to check the local instance before the shared pool.

```JavaScript
 {
   "pools": {
     "shared": { "servers": [ /* shared memcached hosts */ ] },
     "local": { "servers": [ /* local memcached instance (e.g. "localhost:<port>") */ ] },
     "all_local": { "servers": [ /* ALL local memcached instances across the fleet */ ] }
   },
   "route": {
     "type": "OperationSelectorRoute",
     "operation_policies": {
       "get": {
         "type": "MissFailoverRoute",
         "children": [
           "PoolRoute|local",
           "PoolRoute|shared"
         ]
       }
     },
     "default_policy": {
       "type": "AllSyncRoute",
       "children": [
         "PoolRoute|shared",
         "Pool|all_local"
       ]
     }
   }
 }
```

--------------------------------

### Get Mcrouter Route Destinations

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Lists the destinations where a given request (operation and key) would be routed. The key must be a valid memcache key, with no spaces around commas or brackets.

```bash
get __mcrouter__.route(set,mykey)
```

--------------------------------

### Startup Options File Format

Source: https://github.com/facebook/mcrouter/wiki/Stats-files

Represents the JSON structure of the startup_options file containing command line arguments and default values.

```JavaScript
 {
   "probe_delay_max_ms" : "60000",
   "probe_delay_initial_ms" : "10000",
   "cross_region_timeout_ms" : "0",
   "disable_tko_tracking" : "0",
   "config_str" : "{\"pools\":{\"A\":{\"servers\":[\"[::1]:5001\"]}},\"route\":\"PoolRoute|A\"}",
   "server_timeout_ms" : "1000",
   "disable_reload_configs" : "0",
   /* some options are omitted */
}
```

--------------------------------

### View Help Information

Source: https://github.com/facebook/mcrouter/wiki/Mcpiper

Display the help menu for mcpiper usage.

```bash
$ mcpiper --help
```

--------------------------------

### Asynclog v2 Sample Entry

Source: https://github.com/facebook/mcrouter/wiki/Features

A sample Asynclog v2 entry showing version, timestamp, command, and routing details. Use this format for logging failed requests.

```json
["AS2.0",1410611229.747,"C",{"k":"key","p":"A","h":"[127.0.0.1]:5001","f":"5000"}]
```

--------------------------------

### GET /stats

Source: https://github.com/facebook/mcrouter/wiki/Stats-list

Retrieves the current operational statistics for the mcrouter instance.

```APIDOC
## GET /stats

### Description
Retrieves a comprehensive list of current mcrouter statistics, including basic system info, request counts, and processing durations.

### Method
GET

### Endpoint
/stats

### Response
#### Success Response (200)
- **version** (string) - Version of mcrouter binary.
- **time** (integer) - Current server time.
- **child_pid** (integer) - Process id of mcrouter instance.
- **uptime** (integer) - How long ago (in seconds) mcrouter has started.
- **duration_us** (float) - Average time of processing a request.
- **config_age** (integer) - How long ago (in seconds) mcrouter has reconfigured.
```

--------------------------------

### Define local context with @define

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Demonstrates defining a local context with variables for a macro.

```json
{
  "type": "if",
  "vars": {
    "A": 0,
    "B": 1,
    "C": 2
  },
```

--------------------------------

### Runtime Configuration

Source: https://github.com/facebook/mcrouter/wiki/Command-line-options

Configures thread counts, fiber pools, and stack management for runtime performance.

```APIDOC
## Runtime Configuration

### Description
Performance tuning parameters for Mcrouter threads and fiber management.

### Parameters
- **--num-proxies** (integer) - Optional - Number of threads to run.
- **--fibers-max-pool-size** (integer) - Optional - Maximum preallocated free fibers per thread.
- **--fibers-stack-size** (integer) - Optional - Stack size per fiber in bytes.
- **--disable-fibers-use-guard-pages** (boolean) - Optional - Disable guard pages for fiber stacks.
```

--------------------------------

### Get Mcrouter Config Age

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the time in seconds since the last configuration reload.

```bash
get __mcrouter__.config_age
```

--------------------------------

### Configure mcrouter with SSL

Source: https://github.com/facebook/mcrouter/wiki/SSL-Setup

Launches mcrouter with SSL enabled, specifying the paths to the server's certificate, private key, and the CA certificate.

```bash
mcrouter --ssl-port 11433 --pem-cert-path=my_server.crt --pem-key-path=my_server_private_key.pem --pem-ca-path=ca.crt
```

--------------------------------

### Slice Operation (@slice)

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Obtains a subrange of a string, array, or object based on specified start and end indices or keys.

```APIDOC
## @slice

### Description
Extracts a portion of the input dictionary based on inclusive start and end bounds.

### Parameters
- **dictionary** (string/array/object) - Required - The source data to slice.
- **from** (int/string) - Required - Starting index or key to include (inclusive).
- **to** (int/string) - Required - Ending index or key to include (inclusive).

### Response
- **result** (string/array/object) - Returns the subset of the original dictionary based on the provided range.
```

--------------------------------

### Configure 2-Level Caching with WarmUpRoute

Source: https://github.com/facebook/mcrouter/wiki/Two-level-caching

Uses WarmUpRoute to check a local pool first, falling back to a shared pool on a miss. Sets and deletes are synchronized to both pools, with local sets using a 10-second TTL.

```JavaScript
 {
   "pools": {
     "shared": { "servers": [ /* shared memcached hosts */ ] },
     "local": { "servers": [ /* local memcached instance (e.g. "localhost:<port>") */ ] }
   },
   "route": {
     "type": "OperationSelectorRoute",
     "operation_policies": {
       "get": {
         "type": "WarmUpRoute",
         "cold": "PoolRoute|local",
         "warm": "PoolRoute|shared",
         "exptime": 10
       }
     },
     "default_policy": {
       "type": "AllSyncRoute",
       "children": [
         "PoolRoute|shared",
         {
           "type": "ModifyExptimeRoute",
           "target": "PoolRoute|local",
           "exptime": 10
         }
       ]
     }
   }
 }
```

--------------------------------

### Usage: Running Mcrouter with a Flavor

Source: https://github.com/facebook/mcrouter/wiki/Flavors

To use a flavor, provide its path to the mcrouter command. The '-standalone' suffix should not be used on the command line.

```bash
$ mcrouter /path/to/flavor
```

--------------------------------

### Get Specific Mcrouter Option Value

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the value of a specific mcrouter option, such as 'num_proxies', using its internal name.

```bash
get __mcrouter__.options(num_proxies)
```

--------------------------------

### PrefixSelectorRoute Configuration

Source: https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles

Routes requests to different targets based on specified key prefixes.

```APIDOC
## PrefixSelectorRoute

### Description
Sends to different targets based on specified key prefixes. Note: Can only be used as a topmost route handle.

### Request Body
- **wildcard** (string) - Required - Default route handle if prefix does not match.
- **policies** (object) - Required - Map of operation names to route handles.

### Request Example
{
  "type": "PrefixSelectorRoute",
  "policies": {
    "shr": "PoolRoute|shared_pool"
  },
  "wildcard": "PoolRoute|local_pool_in_second_cluster"
}
```

--------------------------------

### Get Mcrouter Host ID

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the host ID of the mcrouter instance as an unsigned 32-bit integer in decimal format.

```bash
get __mcrouter__.hostid
```

--------------------------------

### Macro Library - @import

Source: https://github.com/facebook/mcrouter/wiki/JSONM

The @import macro allows for modular configurations by including content from external resources. It requires an ImportResolver to map resource names to their content.

```APIDOC
## @import Macro

### Description
Allows you to make configs more modular or depend on external configuration sources. The `@import` macro reads some external resource and gets replaced with the contents of that resource. The JSONM preprocessor requires a caller to pass in an ImportResolver object that knows how to resolve resource name to its contents. The convention for the resource name is `"resource_type:name"` (e.g. `"file:myFile.json"`).

### Parameters
- **resource_name** (string) - Required - The name of the resource to import, typically in the format `"resource_type:name"`.
```

--------------------------------

### Mcrouter Pattern Matching for Routing

Source: https://github.com/facebook/mcrouter/wiki/Routing-Prefix

Demonstrates using '*' as a wildcard in routing prefixes for mcrouter. This allows a single configuration to apply to multiple clusters or sub-paths.

```bash
set /datacenter/*/a
```

```bash
set /*/cluster*/a
```

--------------------------------

### Configure Project Version and Package String

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Sets the mcrouter package version and configures a header file with build information.

```cmake
set(MCROUTER_PACKAGE_STRING "${MCROUTER_PACKAGE_VERSION} ${PACKAGE_NAME}")
configure_file(
  "${CMAKE_CURRENT_SOURCE_DIR}/CMake/config.h.in"
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/config.h"
  @ONLY
)
```

--------------------------------

### Configure Replicated Pool Routing

Source: https://github.com/facebook/mcrouter/wiki/Replicated-pools-setup

Defines a pool of servers and uses OperationSelectorRoute to direct gets to a single host and writes to all hosts.

```JavaScript
 {
   "pools": {
      "A": {
         "servers": [
            // hosts of replicated pool, e.g.:
           "127.0.0.1:12345",
           "[::1]:12346"
         ]
      }
   },
   "route": {
     "type": "OperationSelectorRoute",
     "operation_policies": {
       "add": "AllSyncRoute|Pool|A",
       "delete": "AllSyncRoute|Pool|A",
       "get": "LatestRoute|Pool|A",
       "set": "AllSyncRoute|Pool|A"
     }
   }
 }
```

--------------------------------

### GET __mcrouter__ Special Commands

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

A collection of special commands used to retrieve version, configuration, routing, and diagnostic information from the mcrouter instance.

```APIDOC
## GET __mcrouter__.version
### Description
Returns the version string of the build.

## GET __mcrouter__.config
### Description
Returns the current configuration string. Returns an error if configured from a file.

## GET __mcrouter__.config_age
### Description
Returns the time in seconds since the last configuration reload.

## GET __mcrouter__.config_file
### Description
Returns the configuration file location. Returns an error if configured from a string.

## GET __mcrouter__.hostid
### Description
Returns the hostid of this mcrouter instance as an unsigned 32-bit integer.

## GET __mcrouter__.options
### Description
Returns a list of space-separated command line options and their values.

## GET __mcrouter__.options(option_name)
### Description
Returns the value of a specific command line option.

## GET __mcrouter__.route(<op>,<key>)
### Description
Returns the list of destinations where a given request would be routed based on current routing logic.

## GET __mcrouter__.route_handles(<op>,<key>)
### Description
Returns the representation of the route handle graph that a given request would traverse.

## GET __mcrouter__.config_md5_digest
### Description
Returns the MD5 hash of the main configuration file.

## GET __mcrouter__.config_sources_info
### Description
Returns MD5 hashes for each tracked configuration file, including imported files.

## GET __mcrouter__.preprocessed_config
### Description
Returns the loaded configuration with all macros expanded.
```

--------------------------------

### Asynclog v2 Entry Structure Explanation

Source: https://github.com/facebook/mcrouter/wiki/Features

Explains the structure of an Asynclog v2 entry, detailing each component and its meaning. This is useful for understanding the logged data.

```plaintext
[version (always "AS2.0"), timestamp, command (always "C"),
  {"k": key,
   "p": pool name,
   "h": "[destination host]:destination port",
   "f": "mcrouter port or instance name"}]
```

--------------------------------

### Import Macro

Source: https://github.com/facebook/mcrouter/wiki/JSONM

The import macro allows fetching content from external resources, with optional default values for failure cases.

```APIDOC
## Import Macro

### Description
Fetches content from an external resource specified by a file path. If the import fails, a default value can be provided to prevent preprocessing failure.

### Parameters
#### Path Parameters
- **path** (string) - Required - The resource identifier (file path).
- **default** (valueWithMacros) - Optional - A default value to use if the import fails.

### Return
Content of the external resource.

### Example
Assume `citiesByCountry.json` contains:
```json
{
  "ukraine": [ "Kyiv", "Lviv" ],
  "usa": [ "Menlo Park" ]
}
```
And `allCities.json` contains:
```json
{
  "cities": "@merge(@values(@import(file:citiesByCountry.json)))"
}
```
After preprocessing, `allCities.json` would result in:
```json
{
  "cities": [ "Kyiv", "Lviv", "Menlo Park" ]
}
```
```

--------------------------------

### Configure PrefixSelectorRoute Policies

Source: https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles

Define routing policies for PrefixSelectorRoute based on key prefixes. The 'policies' object maps operation names to route handles, and 'wildcard' specifies the default route.

```JavaScript
"route": {
        "type": "PrefixSelectorRoute",
        "policies": {
          "shr": "PoolRoute|shared_pool"
        },
        "wildcard": "PoolRoute|local_pool_in_second_cluster"
      }
```

--------------------------------

### Terminate with Failure Reason

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Use the `@fail` macro to terminate preprocessing with a specified failure reason. The `msg` parameter is required and must evaluate to a string.

```mcrouter
@fail(failure)
```

--------------------------------

### WarmUpRoute Configuration

Source: https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles

Details on the WarmUpRoute configuration properties and operational logic.

```APIDOC
## WarmUpRoute

### Description
Allows for substantial changes to the number of boxes in a pool without increasing the miss rate. All sets and deletes go to the 'cold' route handle. Gets are attempted on the 'cold' route handle; if a miss occurs, data is fetched from the 'warm' route handle. If the 'warm' route returns a hit, the response is forwarded to the client and an asynchronous request updates the 'cold' route handle.

### Properties
- **cold** (Route handle) - Required - Route handle that routes to 'cold' destination (with empty cache).
- **warm** (Route handle) - Required - Route handle that routes to 'warm' destination (with filled cache).
- **exptime** (int) - Optional - Expiration time for warm up requests in seconds.
```

--------------------------------

### Get Mcrouter Config MD5 Digest

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Retrieves the MD5 hash of the main configuration file. This command does not account for additional tracked files like those included via '@import'.

```bash
get __mcrouter__.config_md5_digest
```

--------------------------------

### Get Mcrouter Route Handle Graph

Source: https://github.com/facebook/mcrouter/wiki/Admin-requests

Represents the route handle graph that a request would traverse based on the configuration. Leaf nodes include additional destination information.

```bash
get __mcrouter__.route_handles(set,mykey)
```

--------------------------------

### Configure PoolRoute with Rate Limiting

Source: https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles

Apply rate limiting to a PoolRoute to prevent server overload. Specify rates and burst values for different operations like gets, sets, and deletes.

```JavaScript
{
  "type": "PoolRoute",
  "pool": "MyPool",
  "rates": {
    "gets_rate": double (optional)
    "gets_burst": double (optional)
    "sets_rate": double (optional)
    "sets_burst": double (optional)
    "deletes_rate": double (optional)
    "deletes_burst": double (optional)
  }
}
```

--------------------------------

### Network Configuration

Source: https://github.com/facebook/mcrouter/wiki/Command-line-options

Configures network ports, keepalive settings, and connection management.

```APIDOC
## Network Configuration

### Description
Settings for network listeners, TCP keepalive behavior, and connection timeouts.

### Parameters
- **--port** (string) - Optional - Comma separated list of ports to listen on.
- **--reset-inactive-connection-interval** (integer) - Optional - Period in ms to close inactive outgoing connections.
- **--keepalive-count** (integer) - Optional - TCP KEEPALIVE count for outgoing connections.
- **--keepalive-interval** (integer) - Optional - TCP KEEPALIVE interval in seconds.
- **--keepalive-idle** (integer) - Optional - TCP KEEPALIVE idle time in seconds.
```

--------------------------------

### Macro Definitions Set

Source: https://github.com/facebook/mcrouter/wiki/JSONM

A collection of macro and constant definitions.

```APIDOC
## macroDefinitions

### Description
Set of macroDefinition's and constDefinitions. Can be either an object of type valueWithMacros or a recursive list of such objects. During preprocessing the list is flattened and objects are merged to form a final dictionary of definitions with keys being names of the defined macro or constants.

### Request Example
```json
[
  [
    {
      "isOdd": {
        "type": "macroDef",
        "params": [ "value" ],
        "result": "&#064;equals(&#064;mod(%value%,2),1)"
      }
    }
  ]
]
```
```

--------------------------------

### SSL Configuration

Source: https://github.com/facebook/mcrouter/wiki/Command-line-options

Configures SSL ports and certificate paths for secure communication.

```APIDOC
## SSL Configuration

### Description
Settings for enabling SSL on specific ports and providing certificate paths.

### Parameters
- **--ssl-port** (string) - Optional - Comma separated list of SSL ports.
- **--pem-cert-path** (string) - Optional - Path to pem-style certificate.
- **--pem-key-path** (string) - Optional - Path to pem-style key.
- **--pem-ca-path** (string) - Optional - Path to pem-style CA certificate.
```

--------------------------------

### Configure Implementation Headers

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Copies implementation header files from the source directory to the build directory, renaming them to their final public names. This is used for generating configuration and core Mcrouter headers.

```cmake
configure_file(
  "${CMAKE_CURRENT_SOURCE_DIR}/CMake/config-impl.h.in"
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/config-impl.h"
  COPYONLY
)
```

```cmake
configure_file(
  "${MCROUTER_DIR}/RouterRegistry-impl.h"
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/RouterRegistry.h"
  COPYONLY
)
```

```cmake
configure_file(
  "${MCROUTER_DIR}/ThriftAcceptor-impl.h"
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/ThriftAcceptor.h"
  COPYONLY
)
```

```cmake
configure_file(
  "${MCROUTER_DIR}/mcrouter_sr_deps-impl.h"
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/mcrouter_sr_deps.h"
  COPYONLY
)
```

```cmake
configure_file(
  "${MCROUTER_DIR}/HostWithShard-fwd-impl.h"
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/HostWithShard-fwd.h"
  COPYONLY
)
```

--------------------------------

### Configure PrefixSelectorRoute

Source: https://github.com/facebook/mcrouter/wiki/Config-Files

Use PrefixSelectorRoute to route requests to different pools based on key prefixes. The longest matching prefix takes precedence, with a wildcard fallback.

```json
 {
   "pools": { /* define pool A, B and C */ }
   "routes": [
     {
       "aliases": [ "/a/a/" ],
       "route": {
         "type": "PrefixSelectorRoute",
         "policies": {
           "a": "PoolRoute|A",
           "ab": "PoolRoute|B"
         },
         "wildcard": "PoolRoute|C"
       }
     }
   ]
 }
```

--------------------------------

### Standalone Mcrouter Flavor Configuration

Source: https://github.com/facebook/mcrouter/wiki/Flavors

Configure mcrouter process parameters using this JSON. It includes options for logging and ports, and can override libmcrouter options.

```javascript
{
  "libmcrouter_options": {
    "default_route": "/region1/cluster1/",
    "config_file": "mcrouter_config.json"
  },
  "standalone_options": {
    "log_file": "/var/logs/mcrouter-web.log",
    "ports": "8888"
  }
}
```

--------------------------------

### Importing External Resources with @import

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Use the @import macro to include the content of an external resource. The 'path' parameter is required and specifies the resource identifier. An optional 'default' parameter can provide a fallback value if the import fails.

```json
{
  "ukraine": [
    "Kyiv",
    "Lviv"
  ],
  "usa": [
    "Menlo Park"
  ]
}
```

```json
{
  "cities": "@merge(@values(@import(file:citiesByCountry.json)))"
}
```

```json
{
  "cities": [
    "Kyiv",
    "Lviv",
    "Menlo Park"
  ]
}
```

--------------------------------

### Find Required Dependencies

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Finds and configures essential build dependencies for mcrouter, including Boost, OpenSSL, and various libraries like folly, wangle, and FBThrift.

```cmake
set(CMAKE_THREAD_PREFER_PTHREAD ON)
set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
find_package(folly CONFIG REQUIRED)
find_package(wangle CONFIG REQUIRED)
find_package(fizz CONFIG REQUIRED)
find_package(fmt CONFIG REQUIRED)
find_package(FBThrift CONFIG REQUIRED)
find_package(gflags CONFIG REQUIRED)
find_package(glog CONFIG REQUIRED)
find_package(Boost 1.69.0 REQUIRED
  COMPONENTS
    context
    filesystem
    program_options
    regex
    system
    thread
)
find_package(OpenSSL REQUIRED)
find_package(LibEvent MODULE REQUIRED)
find_package(ZLIB REQUIRED)
```

--------------------------------

### JSONM Macro Call Inline Form

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Illustrates the inline syntax for calling macros in JSONM, including parameter handling and potential type casting.

```json
"@macroName(param1,param2,...)"
```

```json
" @if(@bool(true), foo, bar) "
```

--------------------------------

### Generate Parser with Ragel

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Configures a custom command to generate C++ parser code from a Ragel input file. This is used for McAsciiParser.

```cmake
set(RAGEL_INPUT "${MCROUTER_DIR}/lib/network/McAsciiParser.rl")
set(RAGEL_OUTPUT
  "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/lib/network/McAsciiParser-gen.cpp"
)

file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/mcrouter/lib/network")

add_custom_command(
  OUTPUT ${RAGEL_OUTPUT}
  COMMAND ${RAGEL_EXECUTABLE} -G1 -o ${RAGEL_OUTPUT} ${RAGEL_INPUT}
  DEPENDS ${RAGEL_INPUT}
  COMMENT "Generating McAsciiParser from Ragel"
)

add_custom_target(mcrouter_ragel_gen DEPENDS ${RAGEL_OUTPUT})
```

--------------------------------

### Define default route

Source: https://github.com/facebook/mcrouter/wiki/Config-Files

Uses the 'route' property for configurations without specific routing prefixes.

```javascript
 {
   "route": /* some route handle tree */
 }
```

```javascript
 {
   "routes": [
     {
       "aliases": [ /* default routing prefix specified on mcrouter command line */ ],
       "route": /* some route handle tree */
     }
   ]
 }
```

--------------------------------

### Generate Thrift C++ Library

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Defines a C++ library from Thrift IDL files using the add_fbthrift_cpp_library macro. Includes options for stack arguments, sync methods, and return try.

```cmake
add_fbthrift_cpp_library(
  mcrouter_carbon_result_thrift
  mcrouter/lib/carbon/carbon_result.thrift
  OPTIONS stack_arguments sync_methods_return_try
)
```

```cmake
add_fbthrift_cpp_library(
  mcrouter_carbon_thrift
  mcrouter/lib/carbon/carbon.thrift
  DEPENDS mcrouter_carbon_result_thrift
  OPTIONS stack_arguments sync_methods_return_try
)
```

```cmake
add_fbthrift_cpp_library(
  mcrouter_common_thrift
  mcrouter/lib/network/gen/Common.thrift
  DEPENDS mcrouter_carbon_thrift
  OPTIONS stack_arguments sync_methods_return_try
)
```

```cmake
add_fbthrift_cpp_library(
  mcrouter_memcache_thrift
  mcrouter/lib/network/gen/Memcache.thrift
  DEPENDS mcrouter_common_thrift
  OPTIONS stack_arguments sync_methods_return_try
)
```

```cmake
add_fbthrift_cpp_library(
  mcrouter_memcache_service_thrift
  mcrouter/lib/network/gen/MemcacheService.thrift
  SERVICES Memcache
  DEPENDS mcrouter_memcache_thrift
  OPTIONS stack_arguments sync_methods_return_try
)
```

--------------------------------

### Import External JSON Resource

Source: https://github.com/facebook/mcrouter/wiki/JSONM

The @import macro allows modularity by reading and replacing itself with the content of an external resource. Requires an ImportResolver to map resource names to content.

```json
"resource_type:name"
```

--------------------------------

### Configure WarmUpRoute in Mcrouter

Source: https://github.com/facebook/mcrouter/wiki/Cold-cache-warm-up-setup

Defines the pools and routing logic to redirect cache misses from a cold pool to a warm pool for data retrieval.

```JSON
 {
   "pools": {
     "cold": { "servers": [ /* cold hosts */ ] },
     "warm": { "servers": [ /* warm hosts */ ] }
   },
   "route": {
     "type": "WarmUpRoute",
     "cold": "PoolRoute|cold",
     "warm": "PoolRoute|warm"
   }
 }
```

--------------------------------

### Add Mcrouter Server Executable

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Defines the mcrouter_server executable target, linking it with mcroutercore and setting output properties.

```cmake
set(MCROUTER_SERVER_SOURCES
  mcrouter/main.cpp
  mcrouter/RequestAclChecker.cpp
  mcrouter/StandaloneConfig.cpp
  mcrouter/StandaloneUtils.cpp
)

add_executable(mcrouter_server ${MCROUTER_SERVER_SOURCES})
target_link_libraries(mcrouter_server PRIVATE mcroutercore)
set_target_properties(mcrouter_server PROPERTIES
  OUTPUT_NAME mcrouter
  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/bin"
)
```

--------------------------------

### Create Build Directory

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Ensures the 'mcrouter' subdirectory exists within the CMake build tree for generated files. This is a prerequisite for copying configuration headers.

```cmake
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/mcrouter")
```

--------------------------------

### Define and use macros in Mcrouter configuration

Source: https://github.com/facebook/mcrouter/wiki/Routing-Prefix

Macros allow for parameterization of configuration segments using the macroDef type. Expansion occurs prior to parsing, making it agnostic to Mcrouter's internal semantics.

```javascript
{
  "pools": {
    "cluster0.local_pool": {
      "servers": [ /* hosts of pool */ ]
    },
    "cluster1.local_pool": {
      "servers": [ /* hosts of pool */ ]
    },
    "shared_pool": {
      "servers": [ /* hosts of pool */ ]
    }
  },
  "macros": {
    "cluster_route": {
      "type": "macroDef",
      "params": [ "id" ],
      "result": {
        "aliases": [
          "/datacenter/cluster%id%/"
        ],
        "route": {
          "type": "PrefixSelectorRoute",
          "policies": {
            "shr": "PoolRoute|shared_pool"
          },
          "wildcard": "PoolRoute|cluster%id%.local_pool"
        }
      }
    }
  },
  "routes": [
    "@cluster_route(0)",
    "@cluster_route(1)"
  ]
}
```

--------------------------------

### Configure PrefixSelectorRoute for workload isolation

Source: https://github.com/facebook/mcrouter/wiki/Prefix-routing-setup

Defines multiple server pools and a routing policy that maps key prefixes to specific pools using the PrefixSelectorRoute type.

```JSON
 {
   "pools": {
     "workload1": { "servers": [ /* list of cache hosts for workload1 */ ] },
     "workload2": { "servers": [ /* list of cache hosts for workload2 */ ] },
     "workload3": { "servers": [ /* list of cache hosts for workload3 */ ] },
     "common_cache": { "servers": [ /* list of cache hosts for common use */ ] }
   },
   "route": {
     "type": "PrefixSelectorRoute",
     "policies": {
       "a": "PoolRoute|workload1",
       "b": "PoolRoute|workload2",
       "ab": "PoolRoute|workload3"
     },
     "wildcard": "PoolRoute|common_cache"
   }
 }
```

--------------------------------

### Configure Failover Rate Limiting

Source: https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles

Implement rate limiting for failover requests using a token bucket algorithm. This controls the frequency of failovers based on a rate and burst capacity.

```json
{
  "rate": double, /* 0.0 <= rate <= 1.0 */
  "burst": integer /* 1 <= burst <= 1000000000 */ 
}
```

--------------------------------

### Configure Mcrouter Traffic Shadowing

Source: https://github.com/facebook/mcrouter/wiki/Shadowing-setup

Use this configuration to shadow a percentage of production traffic to a test pool. Specify the target pool, index range for specific hosts, and key fraction for selective shadowing.

```JSON
{
  "pools": {
    "production": {
      "servers": [ /* production hosts */ ]
    },
    "test": {
      "servers": [ /* test hosts */ ]
    }
  },
  "route": {
    "type": "PoolRoute",
    "pool": "production",
    "shadows": [
      {
        "target": "PoolRoute|test",
        "index_range": [0, 2],
        "key_fraction_range": [0, 0.1]
      }
    ]
  }
}
```

--------------------------------

### CA Signing Configuration

Source: https://github.com/facebook/mcrouter/wiki/SSL-Setup

Configuration file for CA signing, specifying indefinite validity and honoring certificate request extensions.

```ini
expiration_days = -1
honor_crq_extensions
```

--------------------------------

### Select an item from input

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Performs a lookup in an array by index or an object by key. Throws an error if the key is missing and no default is provided.

```php
{
```

--------------------------------

### Find Ragel Executable

Source: https://github.com/facebook/mcrouter/blob/main/CMakeLists.txt

Locates the Ragel executable, which is required for building mcrouter. If not found, the build will fail.

```cmake
find_program(RAGEL_EXECUTABLE ragel)
if(NOT RAGEL_EXECUTABLE)
  message(FATAL_ERROR "Ragel is required to build mcrouter")
endif()
message(STATUS "Found Ragel: ${RAGEL_EXECUTABLE}")
```

--------------------------------

### Type Conversions

Source: https://github.com/facebook/mcrouter/wiki/JSONM

Macros for converting values between integer, double, boolean, and string types.

```APIDOC
## Type Conversions (@int, @double, @bool, @str)

### Description
Allows type conversion between integer, boolean, and string types. Conversion follows the `folly::to<T>(arg)` logic.

### Parameters
#### Path Parameters
- **value** (valueWithMacros) - Required - The value to convert.

### Examples
- `@int(123)`
- `@double(5.5)`
- `@bool(1)`
- `@bool(true)`
- `@bool(false)`
- `@str(12345)`
- `@str(true)`
```