Node.js
There are two ways to write a Node.js service for SOAJS:
- The
soajsframework, which builds the Express 5 app for you, validates inputs and runs the maintenance port. See Your first service. - The
soajs.nodejsmiddleware, for an app you already have. It loads the registry and decodes the gateway’ssoajsinjectobjheader intoreq.soajs. You keep your own routing, validation and server.
This page covers soajs.nodejs (version 2.0.4).
Install
Section titled “Install”npm install soajs.nodejsUse with Express
Section titled “Use with Express”const express = require("express");const soajsMW = require("soajs.nodejs");
const app = express();
app.use(soajsMW({ serviceName: "orders", serviceGroup: "Shop", servicePort: 4300, serviceVersion: 1}, (err) => { if (err) { console.error("SOAJS middleware failed to initialize:", err); process.exit(1); }}));
app.get("/list", (req, res) => { const tenant = req.soajs.tenant; // id, code, key, application, ... const user = req.soajs.urac; // set when the service gets the user res.json({ tenant: tenant.code });});
app.listen(4300);The optional callback receives (err, reg) once the registry has loaded.
MCP tools
Section titled “MCP tools”The gateway can list a service’s APIs as MCP tools for AI agents. A service
using this middleware describes its APIs with its Swagger 2.0 or OpenAPI 3 document, and the
middleware serves it on GET /mcp/tools:
app.use(soajsMW({ serviceName: "orders", serviceVersion: 1, swaggerFilename: "/swagger.yml" // the default, relative to the folder the service runs from}));swaggerDocument(an object, for example from swagger-jsdoc) wins over the file.- A
.jsonfile is sent parsed, YAML as text. No document: the service has no tools. - Only the gateway’s own call is answered; a client request through the gateway goes to your app.
- If your app mounts its routes itself:
app.get("/mcp/tools", soajsMW.mcpTools(config)).
The soajs framework needs none of this: its services describe their APIs from config.js.
Environment variables
Section titled “Environment variables”| Variable | Description |
|---|---|
SOAJS_REGISTRY_API |
hostname:port of the gateway maintenance port. Required to load the registry. |
SOAJS_ENV |
Environment code. Required to load the registry. |
SOAJS_DEPLOY_MANUAL |
When set (and not 0), the middleware registers the service with the gateway (/register) using the configuration you passed. |
SOAJS_DEPLOY_HA |
Set in Kubernetes; enables direct interConnect routing in awareness.connect. |
When registering, the middleware sends serviceName, serviceGroup, servicePort, serviceVersion, requestTimeout, requestTimeoutRenewal, extKeyRequired, urac, urac_Profile, urac_ACL and the other flags from your configuration, so pass the same keys you would put in a soajs config.js.
req.soajs
Section titled “req.soajs”| Property | Content |
|---|---|
tenant |
id, code, type, name, main, profile, key (iKey, eKey), application (product, package, appId, acl) |
urac |
The logged-in user, when forwarded by the gateway. |
servicesConfig |
Configuration stored on the tenant key: the commonFields entry plus the entry named after this service. |
device, geo |
Device and geo information. |
awareness |
getHost and connect for calling other services. |
reg |
Registry access (below). |
Registry access
Section titled “Registry access”const all = req.soajs.reg.getDatabases(); // core and tenant meta databasesconst db = req.soajs.reg.getDatabases("orders"); // one databaseconst cfg = req.soajs.reg.getServiceConfig();const custom = req.soajs.reg.getCustom();const resources = req.soajs.reg.getResources();const svc = req.soajs.reg.getServices("payment");const daemons = req.soajs.reg.getDaemons();req.soajs.reg.reload((err, ok) => { /* ... */ });req.soajs.reg.stopAutoReload();The middleware reloads the registry periodically when the environment’s service configuration (getServiceConfig()) has awareness.autoReloadRegistry set, in milliseconds.
Calling other services
Section titled “Calling other services”req.soajs.awareness.connect("payment", "1", (response) => { // response.host -> where to send the call // response.headers -> headers to forward});- In Kubernetes (
SOAJS_DEPLOY_HAset) with the target listed ininterConnect,hostis the target service directly andheaderscarriessoajsinjectobj, so the target sees the same tenant and user. - Otherwise
hostis the gateway URL for the service, andheaderscarries the caller’skeyandaccess_token.
The version argument is optional: connect("payment", cb) targets the latest version.
Examples
Section titled “Examples”- Express: soajs/soajs.nodejs.express
- Hapi: soajs/soajs.nodejs.hapi
