Routing

Send Service calls to Services with Routers, with ordered fallback Targets.
Framework Docs Menu

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

PartDescription
RouterA named set of Routes. Modules send their Service calls to a Router.
RouteMatches calls by the kind of Service in its patterns: Blobs, KeyValues, Messages, MessageQueues, Tables, or TimeSeries, or * for all of them.
TargetWhere 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.

ResultMeaning
NotFoundThe Service doesn't have what was asked for (404).
NotAvailableThe Service's backend can't be reached, or isn't configured (503).
TimeoutThe backend didn't answer in time (504).
InternalErrorThe Service failed (500).
BadRequestThe Service rejected the call (400). Not a fallback by default.
EmptyThe call succeeded with no results. The empty result is returned if no later Target has any. Not a fallback by default.
Client.Services.KeyValues.Read("machines", "M001") From a module whose configuration uses the default Router
Router default › Route KeyValues Matches the kind of data, then tries its Targets in order
Target 1 · memoryA fast in-memory cache
Found → returned to the caller
NotFound, NotAvailable, Timeout, or InternalError → next Target
Target 2 · redisThe durable store
Found → returned to the caller
NotFound → no Targets left
404 Not FoundReturned to the caller
Not sent on: results that mean the request itself was wrong or not allowed, such as BadRequest, 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.
Each Target lists the results it falls back on; the default is NotFound, NotAvailable, Timeout, and InternalError.

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 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
KeyDescription
id, name, descriptionIdentify the Router.
routes[].patternsThe kinds of Service the Route matches, or *.
routes[].filtersOptional filters that further limit matching calls.
routes[].targetsThe 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[].fallbackOnThe 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 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.