Skip to main content

Native HTTP on the process port

By default, Genesis processes exchange messages with each other over raw TCP, and only GENESIS_ROUTER answers HTTP requests. If you switch a process to the WebSocket messaging channel, it keeps serving Genesis messaging and also answers plain HTTP on the same port, the process's port from its service definition (*-service-definitions.xml). Under Genesis Start with a port offset, the port is shifted; the Application view shows the port each process was given. Each of its request servers, event handlers and custom endpoints gets an HTTP route. You can call those routes directly from inside your cluster, or let the Genesis Router forward HTTP requests to them as a proxy.

A process stays on TCP, and loads none of the HTTP layer, until you configure the channel.

Enable the WebSocket channel​

Set messaging.channel to WEBSOCKET in the network configuration YAML. Use network-config.yaml to change every process, or network-config-<PROCESS_NAME>.yaml to change one process. When both files exist, the process file is applied over the application file.

Put the files in your application's cfg folder (src/main/genesis/cfg/). The build deploys them to site-specific/cfg/ under GENESIS_HOME, not to the product's own cfg folder. Keep the file name exactly network-config.yaml (or network-config-<processName>.yaml); a product prefix on the name means the file is not read.

messaging:
channel: WEBSOCKET

Processes on TCP and processes on WebSocket can run side by side in the same application: a client picks the channel for each target process automatically. The channel is carried in the process's service-discovery record; no start-up log line, console command or DbMon field shows it. To confirm a connection is using WebSocket, look in the calling process's log: a process that connects to another over WebSocket logs WebSocket handshake complete with <host>:<port> at INFO, naming the target's host and port.

For the other messaging settings, including the webSocket and http blocks, see the network configuration YAML reference.

Routes​

ResourceRouteExample
Request server HELLO_WORLDGET /req-hello-worldGET /req-hello-world?REQUEST.NAME=World
Request server requestReply(WIDGET)GET /req-widgetGET /req-widget
Event handler EVENT_CUSTOM_MODIFYPOST /event-custom-modifybody {"DETAILS": {"NAME": "http-test"}}
Data servernoneData servers are served by the Genesis Router only
Custom endpointthe method and path it declaressee Custom endpoints on a process

The route for a request server or event handler is its resource name converted from UPPER_UNDERSCORE to lower-hyphen, and request servers get a req- prefix. The prefix is added to the name the request server was given, so REQ_ is never doubled: requestReply(WIDGET) is served at /req-widget, not /req-req-widget. An event handler's resource name is EVENT_ plus the name it was declared with, so eventHandler(name = "CUSTOM_MODIFY") is served at /event-custom-modify. This is the same URL scheme the Genesis Router uses, so a URL that works through the router also works on the process port. Paths are matched exactly: /EVENT_CUSTOM_MODIFY returns 404.

Request and response bodies use the same JSON format as the router. The reply is the JSON form of the reply message; for example, an event handler replies with "MESSAGE_TYPE": "EVENT_ACK".

To call an event handler on the process port, send a POST to its route with the event's fields under DETAILS. The route supplies the message type, so leave MESSAGE_TYPE out of the body; for example, for EVENT_WIDGET_INSERT:

POST /event-widget-insert
{"DETAILS": {"NAME": "x", "PRICE": 1.0, "QUANTITY": 1}}

If a DETAILS field can't be converted to the event's type, for example a number sent as a string, the reply is a NACK with UNKNOWN_MESSAGE_TYPE in an HTTP 200, so check the field types first.

Status codes​

SituationStatus
No route for the path404
The route exists, but not for this method405; the body lists the methods it accepts
The request doesn't match any custom endpoint's required request parameters or its accepts and produces content types, or it matches more than one (custom endpoints only)406
No valid session token (missing, unknown or expired) on a route that requires a login401
Logged in, but without the endpoint's permission codes (custom endpoints only)403
The body isn't a JSON object, for example an array or malformed JSON, or an event handler's body is empty. A request server called with query parameters doesn't read its body400; the body says why, for example The request body for EVENT_WIDGET_INSERT cannot be read: it is empty. Send the body as a JSON object.
Request body larger than maxContentLength (64 MiB by default)413
A custom endpoint threw an exception (an exception in a request server or event handler comes back as a 200 NACK, below)500
The request couldn't be dispatched or timed out (any route type)500
A reply from a request server or event handler, including a NACK200

When authentication is on, a caller without a valid session token gets 401 instead of 404, 405 or 406, unless the path has endpoints and none of them needs authentication. An unknown path also gets 401.

By default a NACK from a request server or event handler comes back with status 200. If the StrictHttpStatusCode system definition item is true, the process maps the NACK's error status code to the HTTP status instead. See StrictHttpStatusCode on the router page; the same item applies whether the request arrives directly or through the router's HTTP proxy.

Authentication​

The process reads the session token from the SESSION_AUTH_TOKEN request header, never from a query parameter, and looks the session up in its own USER_SESSION table, caching it as the router does (see Auth tokens). A token is accepted until its session times out, sessionTimeoutMins after the session started, as on the router. A request server or event handler request runs as the session's user, whatever USER_NAME the request sends. Request server and event handler routes require a logged-in user, and don't check any permission codes at the route; permissioning inside the request server or event handler still applies. Custom endpoints apply the permissioning they declare.

To turn authentication off for a process's native HTTP, set the system definition item HttpAuthDisabled to true for that process. Every request is then treated as anonymous. The default is false. With authentication off, the process takes USER_NAME from the request header, as the router does with authDisabled, so it is not a verified identity. Requests forwarded by the router's HTTP proxy are authenticated by the process, not the router, so set HttpAuthDisabled the same way as the router's authDisabled. If you set it with the process-scoped override (a <config> entry for the process in processes.xml), sync (Genesis Start's sync, or POST /api/sync) before you restart the process. A plain restart does not pick up a new <config>, because the launcher builds the process's -config argument at sync, not at start.

For example, as an environment variable for a process named POSITION_APP_EVENT_HANDLER:

GENESIS_SYSDEF_POSITION_APP_EVENT_HANDLER_HttpAuthDisabled=true

Custom endpoints on a process​

A process on the WebSocket channel can also load *-web-handler.kts files itself. Unless the router's HTTP proxy is on, GENESIS_ROUTER keeps serving the same script, so both the router and the process answer (this holds only for endpoints not marked internal; see Internal resources). Add the script file name to the process's script entry in processes.xml, comma-separated from any other scripts. The script content is the same as for the router. Each endpoint is registered on the process port and published to service discovery, so a router in proxy mode can forward requests to it. To confirm which endpoints a process registered, set the logger global.genesis.process.http.ProcessWebEndpointLoader to DEBUG on that process, as described in Logging. It then logs Registered HTTP endpoint: <method> <path> → custom handler (auth: …) for each one. The INFO line "HTTP endpoint handler installed on native port" does not name them.

<process name="POSITION_APP_EVENT_HANDLER">
...
<script>position_app-eventhandler.kts,position_app-web-handler.kts</script>
...
</process>

The process reads the script once, at startup, so restart the process after you add the script to its script entry.

The endpoint is served at the path it declares, on the process port, with no process-name or base-path prefix. A leading slash is optional: endpoint(GET, "custom-endpoint") and endpoint(GET, "/custom-endpoint") declare the same route. For example, for a script that declares endpoint(GET, "custom-endpoint"), call it with the session token in the SESSION_AUTH_TOKEN header, as for any other process-port call:

curl -H "SESSION_AUTH_TOKEN: <session-token>" http://<host>:<process-port>/custom-endpoint

Multipart uploads and file downloads work on the process port in the same way as on the router. For the script syntax, see Custom endpoints.

Internal resources​

You can mark an event handler, request server or custom endpoint as internal. The process still serves it on its own port, so calls from inside your cluster work as before, but the Genesis Router refuses it to external callers. A caller who isn't logged in gets 401 for any resource name, internal or unknown, because authentication is checked first. A logged-in caller gets the same 404 for an internal name as for an unknown one. A custom endpoint marked internal that the router would serve itself, because the HTTP proxy is off, is not registered on the router: the router logs a warning and refuses it like a missing endpoint. To serve an internal endpoint to callers inside the cluster, load it on a process (see Custom endpoints on a process).

Event handlers and custom endpoints: a file-level setting applies to the definitions that come after it in the file.

Request servers: a file-level config { internal = true } applies to every table or view request server in the file that sets no configuration of its own, wherever the block sits. A custom request server, or one with its own config block or a setting such as timeout, only takes the file-level settings that come before it.

For all of these, put the file-level setting at the top of the file and it applies to every definition. You can override it on each definition.

// *-eventhandler.kts
eventHandler {
internal = true // every event handler defined after this line
eventHandler<Trade>(name = "TRADE_SYNC") {
internal = true // or on one event handler
// ...
}
}

// *-reqrep.kts
requestReplies {
config { internal = true } // every table or view request server in the file without its own config
requestReply(TRADE) {
config { internal = true } // or on one request server
}
}

// *-web-handler.kts
webHandlers {
internal = true // every endpoint defined after this line
endpoint(GET, "health") {
internal = true // or on one endpoint
// ...
}
}

The endpoint bodies in the snippet above are elided (// ...), so it is not complete code on its own. A custom endpoint needs a handleRequest block; for a full example, see Custom endpoints.

Through the Genesis Router​

To route HTTP from the front end to these processes, enable the router's HTTP proxy. With the proxy on, the router forwards requests for resources owned by a process on the WebSocket channel, and streams the request and response through without buffering them. Requests for data servers, for resources on TCP processes, and for the authentication events such as EVENT_LOGIN_AUTH, are handled by the router as before.

See HTTP proxy on the Genesis Router page.