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
`–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,
    "wsPath": "/",
    "apiPath": "/api",
    "apiEncoding": "json",
    "headerAuth": 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

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 validating access permissions for the resource, this resource method will be called, allowing an auth service to set a token using information such as the request headers.
Missing value or null will disable 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