PingGateway 2024.9

Router

A Handler that performs the following tasks:

  • Defines the routes directory and loads routes into the configuration.

  • Depending on the scanning interval, periodically scans the routes directory and updates the PingGateway configuration when routes are added, removed, or changed. The router updates the PingGateway configuration without needing to restart PingGateway or access the route.

  • Manages an internal list of routes, where routes are ordered lexicographically by route name. If a route is not named, then the route ID is used instead. For more information, refer to Route.

  • Routes requests to the first route in the internal list of routes, whose condition is satisfied.

    Because the list of routes is ordered lexicographically by route name, name your routes with this in mind:

    • If a request satisfies the condition of more than one route, it is routed to the first route in the list whose condition is met.

    • Even if the request matches a later route in the list, it might never reach that route.

    If a request does not satisfy the condition of any route, it is routed to the default handler if one is configured.

The router does not have to know about specific routes in advance - you can configure the router first and then add routes while PingGateway is running.

Studio deploys and undeploys routes through a main router named _router, which is the name of the main router in the default configuration. If you use a custom config.json, make sure it contains a main router named _router.

Learn about Router metrics:

Usage

{
    "name": string,
    "type": "Router",
    "config": {
        "defaultHandler": Handler reference,
        "directory": configuration expression<string>,
        "scanInterval": configuration expression<duration>,
        "delayRouteMetrics": configuration expression<boolean>
    }
}

An alternative value for type is RouterHandler.

Properties

"defaultHandler": Handler reference, optional

Handler to use when a request does not satisfy the condition of any route.

Provide either the name of a handler object defined in the heap or an inline handler configuration object.

Default: If no default route is set either here or in the route configurations, PingGateway aborts the request with an internal error.

See also Handlers.

"directory": configuration expression<string>, optional

Directory from which to load route configuration files. This must reference an existing directory PingGateway can read.

Default: The default directory for route configuration files, at $HOME/.openig(on Windows, %appdata%\OpenIG).

With the following example, route configuration files are loaded from /path/to/safe/routes instead of from the default directory:

{
  "type": "Router",
  "config": {
    "directory": "/path/to/safe/routes"
  }
}
If you define multiple routers, configure directory so that the routers load route configuration files from different directories.

An infinite route-loading sequence is triggered when a router starts a route that, directly or indirectly, starts another router, which then loads route configuration files from the same directory.

See also Expressions.

"scanInterval": configuration expression<duration>, optional

Time interval at which PingGateway scans the specified directory for changes to routes. When a route is added, removed, or changed, the router updates the PingGateway configuration without needing to restart PingGateway or access the route.

When an integer is used for the scanInterval, the time unit is seconds.

To load routes at startup only, and prevent changes to the configuration if the routes are changed, set the scan interval to disabled.

Default: 10 seconds

"delayRouteMetrics": configuration expression<boolean>, optional

Whether to delay creation of route metrics until the first request passes through the route.

If you have many routes, consider setting "delayRouteMetrics": true to improve PingGateway startup time.

Default: false

Example

The following config.json file configures a Router:

{
  "handler": {
    "type": "Router",
    "name": "_router",
    "baseURI": "http://app.example.com:8081",
    "capture": "all"
  },
  "heap": [
    {
      "name": "JwtSession",
      "type": "JwtSession"
    },
    {
      "name": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    }
  ]
}

All requests pass with the default settings to the Router. The Router scans $HOME/.openig/config/routes at startup, and rescans the directory every 10 seconds. If routes have been added, deleted, or changed, the router applies the changes.

The main router and any subrouters build the monitoring endpoints. For information about monitoring endpoints, refer to Monitoring.