Servers and routes

A server is a backend service the gateway can forward to. A route maps a public path to one server.

Servers

Servers live under ServerConfigs, keyed by a name of your choice. At least one is required.

ServerConfigs:
  svc-a:
    URL: "http://svc-a:9090"
  svc-b:
    URL: "https://svc-b:9090"
    TLS:
      CACertFile: "/etc/gateway/certs/ca.pem"
    HeaderRule: strip-and-set
    UsageControlRules: [limit-b-server]

Key	Required	Description
URL	yes	Where requests are forwarded, including the scheme, e.g. http://localhost:9090.
TLS	no	Options for HTTPS backends. See below.
HeaderRule, ClientIDRule, AuthMethod	no	Default for every route that targets this server.
UsageControlRules	no	Usage control rules applied to every route of this server.
UsageControlMode	no	Cascade (default) or Strict. See usage control mode.

A server that no route targets is reported as a warning, because it can never be reached.

HTTPS backends

HTTPS is used when URL starts with https://. By default the backend certificate is verified against the system trust store. The optional TLS block covers two cases:

Key	Description
CACertFile	PEM file with the certificate authority that signed the backend certificate. Use it for internal CAs. The file must exist and contain a valid certificate, nocleye check verifies it. A relative name is looked for in /etc/nocleye-beta/gateway/certs/ first, then used as given when the gateway starts.
InsecureSkipVerify	true disables certificate verification. Do not use in production, nocleye check warns about it.

A TLS block on a server whose URL does not use https has no effect and is reported as a warning.

Routes

Routes live under ServerRoutes, keyed by a name of your choice. At least one is required.

ServerRoutes:
  auth-v1:
    TargetServer: auth-server
    PathPattern: /api/auth
    RemovePathPatternFromFinalRoute: true
    AddPrefixToFinalRoute: /api/v1

Key	Required	Description
TargetServer	yes	Name of a server in ServerConfigs.
PathPattern	yes	Path prefix this route handles, e.g. /api/users.
RemovePathPatternFromFinalRoute	no	true removes PathPattern from the path before forwarding. Default false.
AddPrefixToFinalRoute	no	Prefix added to the path before forwarding. Applied after the pattern is removed.
HeaderRule, ClientIDRule, AuthMethod	no	Override the server and global value for this route.
UsageControlRules	no	Usage control rules applied to this route.
UsageControlMode	no	Cascade (default) or Strict. See usage control mode.

Matching

• A request matches a route when its path starts with the route’s PathPattern, on a path segment boundary.
• When several routes match, the one with the longest PathPattern wins.
• Two routes with exactly the same PathPattern are an error.
• A request that matches no route gets 404.
• Paths containing . or .. segments are rejected with 400.

Rewriting the path

The path the backend receives is built in two steps:

1. If RemovePathPatternFromFinalRoute is true, PathPattern is removed from the start of the path.
2. If AddPrefixToFinalRoute is set, it is added to the start of the result.

Request path	PathPattern	Remove	Prefix	Backend receives
/api/auth/login	/api/auth	true	/api/v1	/api/v1/login
/api/checkout/pay	/api/checkout	false	/v1	/v1/api/checkout/pay
/a/open/status/500	/a/open	true	none	/status/500

The query string is always forwarded unchanged.

Forwarded headers

The gateway adds X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto to forwarded requests, and a request ID header, X-Nocleye-Request-Id, that is also written to the access log. Any X-Forwarded-* value sent by the client is discarded, unless the request comes from a trusted proxy.

Errors returned by the gateway

Status	When
400	Path contains . or .. segments.
401	Authentication failed.
404	No route matches the path.
429	A usage control limit was exceeded.
502	The backend could not be reached.