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
-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

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