# Routing

> Send Service calls to Services with Routers, with ordered fallback Targets.

URL: https://www.trakhound.com/docs/trakhound-framework/routing

A Router sends Service calls from modules to one or more [Services](https://www.trakhound.com/docs/trakhound-framework/services). Each module configuration sets the Router it uses with `routerId`, so changing where data is stored is a configuration change, not a code change. A module that doesn't name a Router uses its [Group's](https://www.trakhound.com/docs/trakhound-framework/configuration#groups) Router, then the one named `default`. A [Zone](https://www.trakhound.com/docs/trakhound-framework/zones) with a Router overrides all of them.

## Routers, Routes, and Targets

| Part | Description |
| --- | --- |
| **Router** | A named set of Routes. Modules send their Service calls to a Router. |
| **Route** | Matches calls by the kind of Service in its `patterns`: `Blobs`, `KeyValues`, `Messages`, `MessageQueues`, `Tables`, or `TimeSeries`, or `*` for all of them. |
| **Target** | Where a matching call is sent: a **Service**, or another **Router**. A Route's Targets are tried in order. |

## Fallback Targets

A call goes on to a Route's next Target only when the Target's result is one it **Falls Back On**. By default that is `NotFound`, `NotAvailable`, `Timeout`, and `InternalError`: the Service didn't have it, or couldn't answer. Calls that were wrong or not allowed (ex. Bad Request or Forbidden) are returned to the caller instead of being sent on.

| Result | Meaning |
| --- | --- |
| `NotFound` | The Service doesn't have what was asked for (404). |
| `NotAvailable` | The Service's backend can't be reached, or isn't configured (503). |
| `Timeout` | The backend didn't answer in time (504). |
| `InternalError` | The Service failed (500). |
| `BadRequest` | The Service rejected the call (400). Not a fallback by default. |
| `Empty` | The call succeeded with no results. The empty result is returned if no later Target has any. Not a fallback by default. |

Diagram: A Key-Value read goes to the default Router, whose KeyValues Route tries a Memory cache first. If the key isn't found or the cache is down, it falls back to Redis. If no Target has the key, 404 is returned. Results such as Bad Request are returned to the caller immediately.

A Target that doesn't handle the call (for example a Blob Service asked for Key-Values) is always skipped. For example, a `KeyValues` Route with a cache Service followed by a database Service reads from the database when the cache doesn't have the key, or when the cache server is down.

## Routers Diagram

Routers are edited in the admin UI under **Config > Routers**, which shows them as a diagram of Router, Route, and Target items:

1. Click **Router** or **Route** in the list on the left, or a Service or Router to add a Target. With an item selected, the new item is connected to it. Items can also be dragged onto the canvas.
2. Connect items by dragging from the right edge of one to the left edge of another (Router → Route → Target).
3. Select an item to edit it in the panel on the right: its Name, Patterns, a Target's order, and the results it **Falls Back On**. A Route's Pattern box suggests `*` and the kinds of Service to pick from, or type a Regular Expression. Patterns are case-sensitive, so a Pattern that matches none of them (ex. `keyvalues`) is marked with a warning. With nothing selected, the panel lists any problems, such as two Routers with the same Name, a Route without a Pattern, or Router Targets that loop.
4. Click **Save**. Only the Routers that changed are written. **Arrange** lays the items out in columns and **Fit** zooms to show them all.

A Service Target shows the Package of its Service. Each Router shows how many modules use it, and a selected Router lists them under **Used By**. Modules find a Router by its ID or its Name, so renaming or deleting a Router that modules use by Name stops their Service calls. The page warns about this before you save, and about modules that name a Router that doesn't exist.

### Routing Map

**Map** shows where Service calls would go, including changes that aren't saved yet: the modules on the left, then the Routers they use, their Routes, the Targets in the order they're tried, and the Services.

- Each Route is split into the kinds of request its Patterns match (ex. a `*` Route into `Blobs`, `KeyValues`, `Messages`, `MessageQueues`, `Tables`, and `TimeSeries`), linked only to the Targets that handle them. A kind that no Target handles is marked with a warning.
- Pick a kind of request to fade the Routes and Services it can't reach, and click a node to follow its requests. A selected Router or module lists the Targets each kind is tried against, and the ones that are skipped.
- Routers and Services that nothing uses are marked **Not used**. What a Service handles is read from the running Service, so a Service that isn't running shows **Kinds unknown**.
- A [Zone](https://www.trakhound.com/docs/trakhound-framework/zones) with a Router sends its members' calls through that Router. Calls a module sends to a different Router in its own code aren't shown.

## Router Configuration

Routers are stored as YAML in the profile's `router` configuration directory:

```
id: default
name: default
routes:
- id: key-values
  patterns:
  - KeyValues
  targets:
  - id: cache
    source: memory          # ID of the Service configuration
    type: Service
  - id: database
    source: redis
    type: Service
- id: everything-else
  patterns:
  - "*"
  targets:
  - id: sql
    source: sql-server
    type: Service
    fallbackOn: [NotFound, NotAvailable, Timeout, InternalError, Empty]
  - id: files
    source: file-system
    type: Service
```

| Key | Description |
| --- | --- |
| `id`, `name`, `description` | Identify the Router. |
| `routes[].patterns` | The kinds of Service the Route matches, or `*`. |
| `routes[].filters` | Optional filters that further limit matching calls. |
| `routes[].targets` | The Targets, in the order they are tried. Each has its own `id`, a `source` (the ID of the Service or Router configuration), and a `type` of `Service` or `Router`. |
| `targets[].fallbackOn` | The results that send the call on to the next Target. Leave it out for the default list; an empty list never falls back. |

> Earlier versions used Route Redirects for fallbacks. They have been replaced by ordered fallback Targets. Services now return `NotAvailable` (503) when their backend can't be reached, where earlier versions returned 404.

## Common Setups

- **Single machine** - Route everything to the File System, Memory, and MQTT Services on the same computer.
- **Shared infrastructure** - Route to SQL Server, Redis, and RabbitMQ Services so multiple Instances share the same data.
- **Cache and fallback** - Put a fast Service first and a durable one after it, so reads fall back when the first doesn't have the data or is down.
- **Another Instance** - Route to a `TrakHound.Http.Service` configuration to read and write the Services of another TrakHound Instance over HTTP.
- **Per module** - Give a module its own Router (with `routerId`) when its data belongs somewhere different from the rest of the Instance.
- **Per line** - Set a Router on a [Group](https://www.trakhound.com/docs/trakhound-framework/configuration#groups) so the modules of one line share it, without setting it on each module.
- **Test data** - Set a [Zone's](https://www.trakhound.com/docs/trakhound-framework/zones) Service Router to send every Service call its modules make to a Router for test data, whatever Router they ask for.
