PingGateway 2024.11

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 isn’t named, then the route ID is used instead. Learn more inRoute.

  • 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 doesn’t satisfy the condition of any route, it is routed to the default handler if one is configured.

The router doesn’t 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 doesn’t 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. If this isn’t an existing directory PingGateway can read, PingGateway creates the directory.

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

The default setting is deprecated. Setting the "directory" will be required in a future release.

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.

Learn more in 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": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    }
  ],
  "session": {
    "type": "JwtSessionManager"
  }
}

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. Learn more about information about monitoring endpoints in Monitoring.

More information

org.forgerock.openig.handler.router.RouterHandler