Node.js Backend

Backend covers the wire contract this implements. Here's the actual server, a standalone Node.js process handling both XHR and WebSocket traffic, built on express, express-session and ws. Requires Node.js 20 or later.

This is a separate process, not middleware plugged into an existing pipeline the way the .NET Backend is. In production it runs as its own IIS application under /nodebackend, on the same origin as the rest of the site, so the browser treats it as same-origin and CORS doesn't come into it. Running it locally on a port of its own is different: a different port is a different origin, which is what the CORS middleware in the setup code below is for. Either way, dataServerURL has to point at it explicitly, since it isn't the site's default /DataServer endpoint.

Wiring it up

npm install express express-session ws in the server's own folder, then wire session handling, BindaryServer and the WebSocket-capable HTTP server together in one entry point:

const fs = require('fs');
const http = require('http');
const https = require('https');
const express = require('express');
const session = require('express-session');
const { Server: BindaryServer } = require('./bindary-server');
const { DataUpdateManager, ClientActivityMonitor } = require('./bindary-data');
const { NotesController } = require('./services/notes-controller');

const config = require('./config.json');
const ALLOWED_ORIGINS = config.allowedOrigins;

const app = express();

let httpServer;

if (config.production)
{
    // SmarterASP/IIS handles HTTPS
    httpServer = http.createServer(app);
}
else
{
    // Local development handles HTTPS itself
    httpServer = https.createServer(
        {
            cert: fs.readFileSync('./localhost.pem'),
            key: fs.readFileSync('./localhost-key.pem')
        },
        app
    );
}

// ---------------------------------------------------------------------------
// Local-testing-only cross-origin setup. In production this server runs
// under the same origin as the rest of the site, folder-scoped and none
// of this is needed. This is purely for pointing a locally running docs
// site at a Node server on a different port during development. Hand
// rolled rather than pulling in a separate cors package, this is small
// enough not to need one and keeps the dependency list to exactly
// ws + express + express-session.
// ---------------------------------------------------------------------------

app.use((req, res, next) =>
{
    const origin = req.headers.origin;

    // A request with no Origin header at all isn't a cross-origin browser
    // request, nothing to check here, let it through untouched.
    if (origin)
    {
        if (!ALLOWED_ORIGINS.includes(origin))
        {
            res.sendStatus(403);
            return;
        }

        res.setHeader('Access-Control-Allow-Origin', origin);
        res.setHeader('Access-Control-Allow-Credentials', 'true');
        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
    }

    if (req.method === 'OPTIONS')
    {
        res.sendStatus(204);
        return;
    }

    next();
});

// Kept as its own variable, rather than passed straight to app.use(),
// so the exact same middleware instance can also be handed to
// BindaryServer below. WebSocket upgrades bypass Express, this is what
// lets req.session (and therefore session-based client ids) work for
// WebSocket clients too, not just XHR ones.
const sessionMiddleware = session({
    secret: config.sessionSecret, // for session cookie protection
    resave: false,
    saveUninitialized: true,
    cookie: { httpOnly: true, secure: false, sameSite: 'lax' }
});

app.use(sessionMiddleware);

// ---------------------------------------------------------------------------
// Bindary server
// ---------------------------------------------------------------------------

// A plain object passed by reference: BindaryServer stores this exact
// object, not a copy, so it can be populated with the controller instance
// after construction, resolving the circular dependency between the
// server (which controllers need for .send()) and the controllers map
// (which the server needs at construction time).
const controllers = {};

const server = new BindaryServer({
    controllers,
    getSession: (req) => req.session,
    useSessionForClients: true,
    path: '/nodebackend/dataserver',
    xhrPath: '/nodebackend/dataserver',
    sessionMiddleware,
    acceptWebSocketRequest: (req) => ALLOWED_ORIGINS.includes(req.headers.origin)
});

const dataUpdateManager = new DataUpdateManager();
const notesController = new NotesController(dataUpdateManager, server);

controllers['Notes.Controller'] = notesController;
notesController.registerActions();

server.attach(app, httpServer);

// ---------------------------------------------------------------------------
// ClientActivityMonitor
// ---------------------------------------------------------------------------

const monitor = new ClientActivityMonitor(server, dataUpdateManager);
monitor.start();

// ---------------------------------------------------------------------------
// Start
// ---------------------------------------------------------------------------

const PORT = process.env.PORT || config.port;

httpServer.listen(PORT, () =>
{
    console.log(`Notes demo server running on port ${PORT}`);
});

On the client, this is the URL a route's dataServerLoad/dataServerUnload points at or wherever dataConnect is left at its default, same as the .NET version, just pointed at /nodebackend/dataserver instead.

Browsers don't apply the same-origin policy to WebSocket connections, they open one to any address a page asks for. The Origin header is the only reliable indication of which page did the asking, which is what acceptWebSocketRequest checks against allowedOrigins above. A session or authentication check alone doesn't replace it: pages on another subdomain, or another port on localhost, still send the session cookie with their handshake.

The certificate matters locally, not just in production. Browsers block an insecure ws:// connection from a page loaded over https as mixed content, the same rule that blocks an insecure image or script. Testing this against a site running under IIS Express, itself https, means the Node server needs a trusted certificate too, even just on localhost. mkcert generates one: mkcert -install once, then mkcert localhost in the server's folder, which is where localhost.pem and localhost-key.pem above come from.

config.json, holding the session secret and allowed origins, is environment-specific and never belongs in source control, same reasoning as node_modules. process.env.PORT takes priority over config.port deliberately: hosting environments that manage the Node process themselves assign the port through that environment variable, config.json's value is only the local-dev fallback.

The BindaryServer class

Construct one BindaryServer and override its hooks, either by passing functions in the options object, as above or by subclassing and overriding the methods directly. Every request, WebSocket or XHR, flows through them in this order:

acceptWebSocketRequest(req) fires before the WebSocket connection is accepted, returning or resolving false denies it. Default implementation accepts everything. req.session is already populated here if sessionMiddleware was supplied, this is the moment to deny unauthenticated users:
```
acceptWebSocketRequest: (req) => !!req.session?.userId
```
onOpen(req) fires on every request, WebSocket or XHR, before anything else.
onClientLoaded(message, request, client) fires once the client has been identified or created, for both connection types. Session state lives on client.session from here on.
onMessage(message) fires when an incoming WebSocket text message fails to deserialize into a DataRequest. Everything that parses successfully, WebSocket or XHR, goes through onDataRequest(request) instead.
onMessageBinary(message) fires for raw WebSocket binary messages.
onError(ex, request, client) fires for exceptions raised while handling a request. A response can still go back to the client here, the usual place to build and send an error DataResponse.
onServerError(ex) fires for exceptions outside that, connection-level failures. A response can no longer be sent, this is for logging.

There's no dedicated close hook here the way .NET's Close is exposed. Connection teardown is handled internally, clearing the client's socket reference, rather than as something a subclass overrides. Something to build out if per-connection close logic ever becomes necessary, it isn't currently part of the public surface.

A handful of constructor options configure behaviour, all optional: useSessionForClients (default true, uses the session id as the client id), getSession (default reads req.session), sessionMiddleware (needed for req.session to exist on the WebSocket path at all, see the required note above), path/xhrPath (both default /dataserver) and maxMessageBytes (default 4MB).

Client

Every client carries a clientId, this is its Node-side representation: id, ipv4/ipv6, socket (the WebSocket, if connected that way), session, isWebSocket, isNew (this is the client's first request) and lastActivity.

server.clients is the full connected-client Map, keyed by client id.

Sending responses

server.send(client, response, xhrRequestId) sends a DataResponse. For an XHR request, this either answers the current request directly or, if called outside the request that's currently open for that client, queues the message for their next one, whichever applies is handled automatically. server.broadcast(message) sends to every connected client.

DataResponse has no generic variants here, JavaScript has no generics to carry them, it's one class with data.appData, data.viewData and data.routeData all available, set whichever ones you're actually sending:

const response = new DataResponse(request.callbackId);
response.data.appData = { notes };

See the response, on Backend, for how this lines up with what the client actually receives.

Rules

DataRules tells the client how to merge incoming data into what it already has, rather than replacing it outright. Attached per data-key, on appDataRules, routeDataRules or viewDataRules.

path: the hierarchical path on the target object being added or updated.
updateKey / removeByKeyValues: match array items by a key's value rather than by index, update the ones that match, remove the ones named for removal.
addIndex / removeIndex / removeCount: position-based insertion and removal. Leave addIndex unset to append.
update: true merges onto existing data, false overwrites it outright.
equalityCheck: compare incoming data against what's already there first, skip the update entirely if nothing actually changed.
recreate: rebuild the element for an updated index/key instead of updating it in place.
ignoreNullValues / omitKeys: skip null fields in the response or specific keys entirely, when merging.
routeIndex / routePath: target a different route than the one currently active, rather than the client's own.

Field names match the client-side merge logic directly here, updateKey stays updateKey, no PascalCase-to-camelCase translation to keep straight the way the .NET version needs.

This is a different shape from the arrayUpdateRules covered on Data changes. That one is for the client telling itself about a change it just made locally. This one is for the server telling the client how to apply data that's arriving from outside. Related purpose, different fields, don't assume they're interchangeable. It's also not identical to the client-side rules shape covered on Backend, close, but this class adds updateKey/removeByKeyValues and equalityCheck beyond what the client-side version documents.

See the demo below for updateKey and path both used for real, against a live server.

ClientActivityMonitor

A background interval that periodically removes inactive clients, WebSocket clients whose connection has been closed for too long and XHR clients that haven't made a request in a while. It isn't started automatically, call it once, typically alongside the rest of your startup wiring:

const { ClientActivityMonitor } = require('./bindary-data');

const monitor = new ClientActivityMonitor(server, dataUpdateManager);

monitor.start({
    removeInactiveClientsInterval: 60,   // how often to check, in seconds
    inactiveClientXhrTimeout: 1200,      // 20 minutes of no XHR activity
    disconnectedWebSocketTimeout: 120,   // 2 minutes disconnected
    callback: (client) =>
    {
        // return false to keep this specific client despite the timeout
        return true;
    }
});

DataUpdateManager

A subscription layer for pushing data to specific clients outside the normal request/response cycle. A client subscribes to an update id and any code, anywhere, can later trigger that id and reach every subscriber. addUpdateAction registers what happens when an id fires, subscribe adds a client to it, update triggers it for everyone currently subscribed.

This is instantiated, not static the way .NET's DataUpdateManager is. One instance gets constructed alongside the server and threaded through to whatever controllers need it, rather than called as a global. Keeps test isolation clean, no shared state leaking between unrelated tests, but it does mean passing the instance around rather than reaching for a static class from anywhere.

This is entirely optional. Plenty of routes never need it, request/response through onDataRequest or a server-side method is enough on its own. Reach for it specifically when something happening on the server, unrelated to any one client's own request, needs to reach a client that's just sitting there, connected, waiting. See the demo below for all three methods used together.

Server-side methods

A route's serverMethod (or a request's serverMethod) names a method to invoke directly, dot-separated type and method name, resolved against the controllers map passed to BindaryServer rather than routed through onDataRequest yourself:

const controllers = {
    'Notes.Controller': notesController // an already-constructed instance
};

class OrderMethods
{
    async getOrder(client, request)
    {
        const response = new DataResponse(request.callbackId);
        response.data.appData = await loadOrder(request.dataDictionary.orderId);
        await server.send(client, response);
    }
}

// a class, instantiated and cached on first use
controllers['Order.Methods'] = OrderMethods;

The method must take exactly (client, request) and return a Promise, called as Order.Methods.getOrder from the client.

Passing an already-constructed instance is the direct equivalent of a [Reusable]-marked class in .NET, that one instance, however you built it, served every future call. Passing the class itself gets it constructed with no arguments the first time it's called, then cached and reused after that, there's no per-call, un-cached instantiation option the way plain instance methods work in .NET. Anything needing constructor arguments, a shared DataUpdateManager, for example, has to be built and registered as an instance up front.

Putting it together

The same shared notes list as the .NET demo, running against a separate Node.js server instead. Click the button, the server picks the text and everyone currently viewing this page sees it appear, live, without refreshing. Open this page in a second tab to check it: add a note in one, watch it appear in the other, even though only one tab clicked anything.

This Result block below connects to componyx.com/nodebackend/dataserver, a Node server running as its own /nodebackend application on this site, not this site's own .NET backend.

Server

// services/notes-controller.js
const { DataResponse, DataRules } = require('../bindary-data');

const UPDATE_NOTES_ID = 'notes';

const SAMPLE_NOTES =
[
    'Bindary is neat',
    'Hello from the docs',
    'This is a shared note',
    'Testing the live update',
    'Notes stay short',
    'Pushed, not polled',
    'Nice to see you here',
    'Works across tabs',
    'Straight from the server',
    'No refresh needed'
];

class NotesController
{
    #notes = [];
    #nextId = 1;
    #dataUpdateManager;
    #server;

    constructor(dataUpdateManager, server)
    {
        this.#dataUpdateManager = dataUpdateManager;
        this.#server = server;
    }

    registerActions()
    {
        this.#dataUpdateManager.addUpdateAction(
            UPDATE_NOTES_ID, this.#sendNotes.bind(this));
    }

    // called once, when the demo section first renders
    async subscribe(client, request)
    {
        this.#dataUpdateManager.subscribe(UPDATE_NOTES_ID, client);
        await this.#sendNotes(client);
    }

    // called from the "Add note" button. The client never supplies the
    // text, the server always picks it, so there's nothing here for a
    // request built by hand, dev console or otherwise, to actually control.
    async addNote(client, request)
    {
        const text = SAMPLE_NOTES[Math.floor(Math.random() * SAMPLE_NOTES.length)];

        this.#notes.push({ id: this.#nextId++, text });

        if (this.#notes.length > 10)
            this.#notes.shift(); // cap growth

        // ack, so dataSendAsync resolves
        const ack = new DataResponse(request.callbackId);
        await this.#server.send(client, ack, request.xhrRequestId);

        // push to every subscribed client, including this one
        await this.#dataUpdateManager.update(UPDATE_NOTES_ID);
    }

    async #sendNotes(client)
    {
        const response = new DataResponse();
        const rule = new DataRules();

        rule.update = true;
        rule.updateKey = 'id';
        rule.path = 'demo.nodeBackendDemo.notes';

        response.data.appData = { notes: this.#notes };
        response.data.appDataRules = { notes: rule };

        await this.#server.send(client, response);
    }
}

module.exports = { NotesController };

subscribe/addNote are camelCase here, where the .NET version uses Subscribe/AddNote. The two dataSendAsync calls in the client script below have to match exactly, the dispatch is a case-sensitive string lookup against the method name, both sides drift out of sync otherwise.

The server picks the text, not the client. Nothing sent in the request is ever read for this, so there's no way, dev console included, to make this list say anything the server didn't already approve.

Registered once, alongside the rest of the server's startup wiring:

const notesController = new NotesController(dataUpdateManager, server);

controllers['Notes.Controller'] = notesController;
notesController.registerActions();

Client

ctrl.subscribeNodeNotes = async () =>
{
    await $bindary.dataSendAsync(null, 'Notes.Controller.subscribe');
};

ctrl.addNodeNote = async () =>
{
    await $bindary.dataSendAsync(null, 'Notes.Controller.addNote');
};

Same shape as the .NET demo's client code, because it's the same API either way, this assumes $bindary.dataServerURL already points at this Node server, set once, normally, the same way any Node.js-backed site configures it.

Named subscribeNodeNotes/addNodeNote rather than subscribeNotes/addNote deliberately. Docs pages share one controller, bindary-docs.js, the .NET Backend page's demo already claims those two names, reusing them here would silently overwrite one or the other depending on load order. Not something a normal Node.js site would ever need to think about, this only matters because both demos share one controller file on this particular reference site.

Running this demo alongside the .NET one

This reference site's own default connection already belongs to the .NET backend, that's what the rest of the site talks to. Getting this one page to talk to the Node server instead, without breaking every other page, needs some extra glue specific to running two demos side by side, not something a Node.js-backed site would ever need on its own:

ctrl.setNodeDataServerURL = () =>
{
    $bindary.disconnect();
    $bindary.relativeDataServerURL = false;
    $bindary.dataServerURL = 'componyx.com/nodebackend/dataserver';
    $bindary.onUnload.once(ctrl.resetDataServerURL);
};

ctrl.resetDataServerURL = () =>
{
    $bindary.disconnect();
    $bindary.relativeDataServerURL = true;
    $bindary.dataServerURL =
        getLocationOrigin().replace(/http(s)*:\/\//, "") + '/DataServer';
};

On this reference site, the real subscribeNodeNotes, in bindary-docs.js, actually calls ctrl.setNodeDataServerURL(); as its first line, that's what makes this specific page's demo work. Left out of the sample above deliberately, a Node.js-backed site copying this pattern for its own use wouldn't add that line at all, it only exists here because of the dual-demo setup, not because Bindary needs it.

$bindary.disconnect() isn't optional here. Reassigning dataServerURL on a connection that's already open, which it is, the site's own backend connects on first page load, does nothing by itself: sending on an open WebSocket just uses the existing socket and never looks at dataServerURL again. Only once the connection is actually closed does the next send reconnect and pick up the new address.

No scheme prefix on the Node URL, not https://, not wss://. Bindary adds that itself based on secure, prepending it onto whatever's already there without checking for a duplicate first. Include one here and the connection ends up pointed at something like wss://https://..., broken.

relativeDataServerURL = false because the address above is written out in full, host and /nodebackend application path both, rather than the site's own /DataServer endpoint that resetDataServerURL restores.

$bindary.onUnload.once(...) is what puts the connection back once this section is no longer showing, without it, navigating away would leave the whole site still pointed at the Node server. Every route that reassigns dataServerURL needs to restore it on its own way out, this isn't automatic.

<div b-post-render="subscribeNodeNotes">
    <ul>
        <li b-repeat="demo.nodeBackendDemo.notes" b-value="text"></li>
    </ul>
    <a ui-type="Button" ui-text="Add note"
       ui-command="$bindary.controller.addNodeNote"></a>
</div>

demo.nodeBackendDemo.notes has to already exist client-side before this renders. b-repeat resolves its data-key the moment this markup renders, before subscribeNodeNotes even runs, let alone before its response comes back, so there's nothing that would create it in time on its own. It's seeded as an empty array in ctrl.load, in bindary-docs.js, the same shared function that seeds every other reference page's demo data on this site, demo.backendDemo.notes included.

Result

Every push here sends the whole list, all ten notes, not just the new one. updateKey: 'id' is what makes that safe: a matching id gets updated in place, a new id gets appended, so resending the full list on every push doesn't duplicate anything already there. path is why this lands at demo.nodeBackendDemo.notes specifically, rather than merging directly onto appData's own root.

Sending everything every time is a deliberate simplification for this demo, not the only way to use this. Sending only what's genuinely new, tracking per-subscriber what a client has already seen, means less to send as a list grows, with updateKey then acting as a safety net against an accidental duplicate rather than doing the main work. Worth reaching for once "resend everything" stops being cheap enough.

updateKey is matched against the property name as it arrives client-side. Here that's simply 'id', the same as it's written server-side, no casing translation to get wrong the way the .NET version requires getting right. Get it wrong on either side regardless and every comparison quietly reads undefined on both sides, which counts as a match, so the merge always updates whichever item happens to be first, no error, nothing obviously broken, just the wrong item overwritten every time.