Configuration

Resgate configuration and command-line usage

Command-line Usage

Resgate can be started with optional flags. Command line options will override configuration file settings.

resgate [options]

Server options

Option	Description	Default value
`-n, –nats <url>`	NATS Server URL	`nats://127.0.0.1:4222`
`-i, –addr <host>`	Bind to HOST address	`0.0.0.0`
`-p, –port <port>`	HTTP port for client connections	`8080`
`-w, –wspath <path>`	WebSocket path for clients	`/`
`-a, –apipath <path>`	Web resource path for clients	`/api/`
`-r, –reqtimeout <seconds>`	Timeout duration for NATS requests	`3000`
`-u, –headauth <method>`	Resource method for header authentication
`-t, –wsheadauth <method>`	Resource method for WebSocket header authentication
`-m, –metricsport <port>`	HTTP port for OpenMetrics connections	`0` (disabled)
`–apiencoding <type>`	Encoding for web resources: json, jsonflat	`json`
`–putmethod <methodName>`	Call method name mapped to HTTP PUT requests
`–deletemethod <methodName>`	Call method name mapped to HTTP DELETE requests
`–patchmethod <methodName>`	Call method name mapped to HTTP PATCH requests
`–wscompression`	Enable WebSocket per message compression
`–resetthrottle <limit>`	Limit on parallel requests sent on a system reset	`0` (no limit)
`–referencethrottle <limit>`	Limit on parallel requests sent following references	`0` (no limit)
`-c, –config <file>`	Configuration file in JSON format

Security options

Option	Description	Default value
`–tls`	Enable TLS for HTTP	`false`
`–tlscert <file>`	HTTP server certificate file
`–tlskey <file>`	Private key for HTTP server certificate
`–creds <file>`	NATS User Credentials file
`–natscert <file>`	NATS Client certificate file
`–natskey <file>`	NATS Client certificate key file
`–natsrootca <file>`	NATS Root CA file(s)
`–alloworigin <origin>`	Allowed origin(s): *, or <scheme>://<hostname>[:<port>]	`*`

Logging options

Option	Description
`-D, –debug`	Enable debugging output
`-V, –trace`	Enable trace logging
`-DV`	Debug and trace

Common options

Option	Description
`-h, –help`	Show usage message
`-v, –version`	Show version

Configuration file

The configuration file is a simple JSON file.

Tip
A new configuration file with default settings can be created by using the --config option, specifying a file path that does not yet exist.

resgate --config myconfig.json

Default configuration:

{
    "natsUrl": "nats://127.0.0.1:4222",
    "natsCreds": "",
    "natsCert": "",
    "natsKey": "",
    "natsRootCAs": [],
    "requestTimeout": 3000,
    "debug": false,
    "trace": false,
    "addr": "0.0.0.0",
    "port": 8080,
    "metricsPort": 0,
    "wsPath": "/",
    "apiPath": "/api",
    "apiEncoding": "json",
    "headerAuth": null,
    "wsHeaderAuth": null,
    "allowOrigin": "*",
    "putMethod": null,
    "deleteMethod": null,
    "patchMethod": null,
    "tls": false,
    "certFile": "",
    "keyFile": "",
    "wsCompression": false,
    "resetThrottle": 0
}

Below is a list of available settings:

Server configuration

natsUrl (string)
NATS Server URL. Must be a valid URI using nats:// as schema.
Example: "nats://127.0.0.1:4222"

addr (string)
Bind to HOST IPv4 or IPv6 address.
Empty string ("") means all IPv4 and IPv6 addresses.
Invalid or missing IP address defaults to 0.0.0.0.
Example: "0.0.0.0"

port (number)
Port for the http server to listen on.
If the port value is missing or 0, standard http(s) port is used.
Example: 8080

metricsPort (number)
Metrics port for the OpenMetrics http server to listen on.
If the port value is missing or 0, metrics are disabled.
Must be different from the configured api port.
Metrics are available at the path: /metrics
Example: 9080

wsPath (string)
Path for accessing the RES API websocket.
Example: "/ws"

apiPath (string)
Path prefix for accessing web resources.
To access a resource, example.model, from a Resgate without TLS listening at 127.0.0.1:8080 (default), the URL would be http://127.0.0.1:8080/<apiPath>/example/model.
Example: "/api/"

requestTimeout (number)
Timeout in milliseconds for NATS requests.
Example: 3000

headerAuth (string)
Header authentication resource method for web resources.
Prior to accessing the resource, this resource method will be called, allowing a service to set a token using information such as the request headers.
Missing value or null will disable header authentication.
Example: "authService.headerLogin"

wsHeaderAuth (string)
Header authentication resource method for WebSocket connections.
Prior to responding to a WebSocket connection, this resource method will be called, allowing a service to set a token using information such as the request headers.
Missing value or null will disable WebSocket header authentication.
Example: "authService.headerLogin"

apiEncoding (string)
Encoding to use in responses to HTTP requests.
Available encodings are:

json - JSON encoding with resource reference meta data
jsonflat - JSON encoding without resource reference meta data

Example: "json"

putMethod (string)
Call method name to map HTTP PUT method requests to.
Missing value or null will respond to PUT requests with the 405 Method Not Allowed status code.
Example: "put"

deleteMethod (string)
Call method name to map HTTP DELETE method requests to.
Missing value or null will respond DELETE requests with the 405 Method Not Allowed status code.
Example: "delete"

patchMethod (string)
Call method name to map HTTP PATCH method requests to.
Missing value or null will respond PATCH requests with the 405 Method Not Allowed status code.
Example: "patch"

wsCompression (boolean)
Flag enabling WebSocket per message compression (RFC 7692).
Example: false

resetThrottle (number)
Throttle on how many requests are sent in response to a system reset.
Once that the number of requests are sent, the server will await responses before sending more requests.
Zero (0) or null means no throttling.
Example: 32

referenceThrottle (number)
Throttle on how many requests are sent when recursively following resource references for a subscription.
Once that the number of requests are sent, the server will await responses before sending more requests.
Zero (0) or null means no throttling.
Example: 32

Security configuration

tls (boolean)
Flag enabling tls encryption.
Example: false

tlsCert (string)
Certificate file path for tls encryption.
Must be set if tls is set to true.
Example: "/etc/ssl/certs/ssl-cert.pem"

tlsKey (string)
Private key file path for tls encryption.
Must be set if tls is set to true.
Example: "/etc/ssl/private/ssl-cert.key"

natsCreds (string)
Optional NATS User Credentials file path.
Example: "ngs.creds"

natsCert (string)
NATS Client certificate file.
Example: "client-cert.pem"

natsKey (string)
NATS Client certificate key file.
Example: "client-key.pem"

natsRootCAs (array of string)
NATS Root CA files.
Example: ["rootCA.pem"]

allowOrigin (string)
Allowed origin for CORS requests, or * to allow all origins. Multiple origins are separated by semicolon.
WebSocket connections will not be accepted if they contain a non-null HTTP Origin header not matching allowedOrigin.
Origins should be in the format: <scheme>://<hostname>[:<port>]
Missing value or null defaults to *.
Example: "https://example.com;https://api.example.com"

Logging configuration

debug (boolean)
Flag enabling debug logging.
Logs additional output that may be relevant to debug issues.
Example: false

trace (boolean)
Flag enabling trace logging.
Logs all client connects and disconnects together with raw client and NATS traffic, including message payload.
Example: false