A Router sends Service calls from modules to one or more 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 Router, then the one named default. A Zone 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. |
default Routerdefault › Route KeyValues
Matches the kind of data, then tries its Targets in orderBadRequest, Conflict, or Forbidden,
are returned to the caller from whichever Target produced them. Add Empty to a Target's Falls Back On to also move on when it returns no results.
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:
- 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.
- Connect items by dragging from the right edge of one to the left edge of another (Router → Route → Target).
- 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. - 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 intoBlobs,KeyValues,Messages,MessageQueues,Tables, andTimeSeries), 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 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. |
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.Serviceconfiguration 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 so the modules of one line share it, without setting it on each module.
- Test data - Set a Zone's Service Router to send every Service call its modules make to a Router for test data, whatever Router they ask for.