@azuliani/node-service 0.0.1

package/Client/SinkClient.js

@@ -0,0 +1,21 @@
+"use strict";
+const doValidation = require("../misc/Validation").SinkValidation;
+
+
+class SinkClient {
+    constructor(endpoint, transports){
+        this.endpoint = endpoint;
+        this.transport = transports.sink;
+        if (!this.transport)
+            throw "Trying to construct Sink endpoint without pushpull transport";
+    }
+
+    push(message){
+        doValidation(this.endpoint, message, false);
+
+        const OTW = message;
+        this.transport.send(JSON.stringify(OTW));
+    }
+}
+
+module.exports = SinkClient;

package/Client/SourceClient.js

@@ -0,0 +1,30 @@
+"use strict";
+
+const EventEmitter = require("events").EventEmitter;
+const doValidate = require("../misc/Validation").SourceValidation;
+
+class SourceClient extends EventEmitter{
+    constructor(endpoint, transports){
+        super();
+        this.endpoint = endpoint;
+        this.transport = transports.source;
+        if (!this.transport)
+            throw "Trying to construct Source endpoint without Source transport";
+    }
+
+    subscribe(){
+        this.transport.subscribe(this.endpoint.name);
+    };
+
+    unsubscribe(){
+        this.transport.unsubscribe(this.endpoint.name);
+    };
+    _processMessage(data){
+        if (this.endpoint.name === data.endpoint){
+            doValidate(this.endpoint, data.message, true);
+            this.emit('message', data.message);
+        }
+    }
+}
+
+module.exports = SourceClient;

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Alexander Zuliani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,116 @@
+# node-service
+
+Node.js library for building services with ZeroMQ-based messaging patterns. Provides both Service (server) and Client abstractions for different communication patterns.
+
+## Installation
+
+```bash
+npm install @azuliani/node-service
+```
+
+## Quick Start
+
+```javascript
+const { Service, Client } = require('@azuliani/node-service');
+
+// Define a descriptor
+const descriptor = {
+  transports: {
+    rpc: { client: "tcp://127.0.0.1:5555", server: "tcp://127.0.0.1:5555" }
+  },
+  endpoints: [
+    { name: "Echo", type: "RPC", requestSchema: { type: "string" }, replySchema: { type: "string" } }
+  ]
+};
+
+// Create a service
+const service = new Service(descriptor, {
+  Echo: (request) => request  // Echo handler
+});
+
+// Create a client
+const client = new Client(descriptor);
+const reply = await client.Echo("Hello");
+console.log(reply);  // "Hello"
+```
+
+## Service Types
+
+Services are servers that expose endpoints. Created via `new Service(descriptor, handlers, initials, options)`.
+
+| Type | Description |
+|------|-------------|
+| **RPCService** | Request/response pattern over ZMQ dealer/router |
+| **SourceService** | Publishes messages to subscribers (ZMQ pub socket) |
+| **SinkService** | Receives messages from clients (ZMQ pull socket) |
+| **PushService** | Pushes messages to workers (ZMQ push socket) |
+| **SharedObjectService** | Syncs object state to clients via diffs |
+
+### Service Options
+
+- `heartbeatMs` - Heartbeat interval in milliseconds (default: 5000)
+
+## Client Types
+
+Clients connect to services. Created via `new Client(descriptor, options)`.
+
+| Type | Description |
+|------|-------------|
+| **RPCClient** | Calls RPC endpoints with timeout support |
+| **SourceClient** | Subscribes to source messages (ZMQ sub socket) |
+| **SinkClient** | Sends messages to sink (ZMQ push socket) |
+| **PullClient** | Receives pushed messages (ZMQ pull socket) |
+| **SharedObjectClient** | Maintains synchronized copy of server's SharedObject |
+
+### Client Options
+
+- `initDelay` - Delay in ms before SharedObjectClient fetches full state after subscribe (default: 100)
+
+## Descriptor Format
+
+Both Service and Client use the same descriptor object:
+
+```javascript
+{
+  transports: {
+    source: { client: "tcp://...", server: "tcp://..." },
+    sink:   { client: "tcp://...", server: "tcp://..." },
+    rpc:    { client: "tcp://...", server: "tcp://..." },
+    pushpull: { client: "tcp://...", server: "tcp://..." }
+  },
+  endpoints: [
+    { name: "MyRPC", type: "RPC", requestSchema: {...}, replySchema: {...} },
+    { name: "MySource", type: "Source", messageSchema: {...} },
+    { name: "MySO", type: "SharedObject", objectSchema: {...} }
+  ]
+}
+```
+
+## Schema Validation
+
+Schema validation using `schema-inspector`. Schemas support:
+- Standard types: `string`, `number`, `object`, `array`
+- Special type `date` for automatic Date parsing from JSON
+- Wildcard `*` in object properties for dynamic keys
+- Set `skip: true` on schema to bypass validation
+
+## Heartbeat System
+
+Services automatically send heartbeat messages on the source transport. Clients detect disconnection when no messages arrive within 3x the heartbeat interval.
+
+- Client learns heartbeat frequency from the first heartbeat message
+- Heartbeat timeout triggers automatic disconnect/reconnect cycle
+- On disconnect, SharedObjectClient emits synthetic deletion diffs before flushing data
+
+## Lifecycle
+
+Both `Service` and `Client` have a `close()` method for proper cleanup:
+
+```javascript
+service.close();  // Stops heartbeat, closes all sockets
+client.close();   // Stops heartbeat checking, closes all sockets
+```
+
+## License
+
+MIT

package/Service/PushService.js

@@ -0,0 +1,29 @@
+"use strict";
+
+const doValidation = require("../misc/Validation").SinkValidation;
+
+class SourceService{
+    constructor(endpoint, transports){
+        this.endpoint = endpoint;
+        this.transport = transports.pushpull;
+        if (!this.transport)
+            throw "Trying to construct PushPull endpoint without pushpull transport";
+        this.stats = {updates: 0};
+    }
+
+    push(message){
+        doValidation(this.endpoint, message, false);
+
+        const OTW = message;
+        this.transport.send(JSON.stringify(OTW));
+        this.stats.updates++;
+    }
+
+    getStats(){
+        const current_stats = JSON.parse(JSON.stringify(this.stats));
+        this.stats.updates = 0;
+        return current_stats;
+    }
+}
+
+module.exports = SourceService;

package/Service/RPCService.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const assert = require("assert");
+
+const doValidation = require("../misc/Validation").RPCValidation;
+
+class RPCService{
+    constructor(endpoint, handler){
+        this.endpoint = endpoint;
+        this.handler = handler;
+        this.stats = {updates: 0};
+    }
+
+    call(data, callback){
+        assert(this.endpoint.name === data.endpoint);
+
+        doValidation(this.endpoint, 'input', data.input, true);
+
+        this.stats.updates++;
+
+        this.handler(data.input, (err, res) => {
+
+            if (!err){
+                doValidation(this.endpoint, 'output', res, false);
+            }
+
+            const reply = JSON.stringify({err,res});
+            callback(reply);
+        });
+    }
+
+    getStats(){
+        const current_stats = JSON.parse(JSON.stringify(this.stats));
+        this.stats.updates = 0;
+        return current_stats;
+    }
+}
+
+module.exports = RPCService;

package/Service/Service.js

@@ -0,0 +1,179 @@
+"use strict";
+
+const zmq = require("zeromq/v5-compat");
+const http = require("http");
+const EventEmitter = require("events").EventEmitter;
+
+const RPCService = require("./RPCService");
+const SourceService = require("./SourceService");
+const SharedObjectService = require("./SharedObjectService");
+const PushService = require("./PushService");
+const SinkService = require("./SinkService");
+
+class Service {
+    constructor(descriptor, handlers, initials, options = {}) {
+        this.descriptor = descriptor;
+        this.transports = {};
+        this.handlers = handlers || {};
+        this.initials = initials || {};
+        this._heartbeatMs = options.heartbeatMs ?? 5000;
+
+        this._setupTransports();
+        this._setupEndpoints();
+    }
+
+    _setupTransports() {
+        for (let transport in this.descriptor.transports) {
+            switch (transport) {
+                case 'source':
+                    this._setupSource(this.descriptor.transports.source.server);
+                    break;
+                case 'sink':
+                    this._setupSink(this.descriptor.transports.sink.server);
+                    break;
+                case 'rpc':
+                    this._setupRpc(this.descriptor.transports.rpc.server);
+                    break;
+                case 'pushpull':
+                    this._setupPushPull(this.descriptor.transports.pushpull.server);
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+
+    _setupSource(hostname) {
+        const sock = new zmq.socket('pub');
+
+        sock.setsockopt(zmq.ZMQ_SNDHWM, 10000);
+        sock.setsockopt(zmq.ZMQ_LINGER, 0);
+        sock.setsockopt(39, 1); // ZMQ_IMMEDIATE
+
+        this.transports.source = sock;
+        sock.bind(hostname);
+        this._setupHeartbeat();
+    }
+
+    _setupHeartbeat() {
+        this._heartbeatInterval = setInterval(this._sendHeartbeat.bind(this), this._heartbeatMs);
+    }
+
+    _sendHeartbeat() {
+        const OTW = {
+            endpoint: '_heartbeat',
+            frequencyMs: this._heartbeatMs
+        };
+        this.transports.source.send([OTW.endpoint, JSON.stringify(OTW)]);
+    }
+
+    _setupSink(hostname) {
+        const sock = new zmq.socket('pull');
+        this.transports.sink = sock;
+
+        sock.bind(hostname);
+        sock.on('message', this._sinkCallback.bind(this));
+    }
+
+    _sinkCallback(message) {
+        if (!this.SinkEndpoint) {
+            throw new Error("Got a pull message, but ot Pull enpoint is connected!");
+        }
+        this.SinkEndpoint._processMessage(JSON.parse(message));
+    }
+
+    _setupRpc(hostname) {
+        this.transports.rpc = new EventEmitter();
+
+        const hostnameAndPort = hostname.split(":");
+        const url = hostnameAndPort[1].substr(2);
+        const port = hostnameAndPort[2];
+        this._httpServer = http.createServer(this._rpcCallback.bind(this));
+        this._httpServer.listen(port, url);
+    }
+
+    _rpcCallback(req, res) {
+        if (req.method === 'POST') {
+            let body = "";
+            req.on('data', function (data) {
+                body += data;
+            });
+            const self = this;
+            req.on('end', function () {
+                const parsedReq = JSON.parse(body);
+                const handler = self.RPCServices[parsedReq.endpoint];
+                if (handler) {
+                    handler.call(parsedReq, (result) => {
+                        res.writeHead(200, {'Content-Type': 'application/json'});
+                        res.end(result);
+                    });
+                } else {
+                    res.writeHead(404, {'Content-Type': 'application/json'});
+                    res.end(JSON.stringify({err: `Unknown endpoint: ${parsedReq.endpoint}`}));
+                }
+            });
+        }
+        else {
+            res.writeHead(200, {'Content-Type': 'text/html'});
+            res.end("-");
+        }
+    }
+
+    _setupPushPull(hostname) {
+        const sock = new zmq.socket('push');
+        sock.bind(hostname);
+        this.transports.pushpull = sock;
+    }
+
+    _setupEndpoints() {
+        this.RPCServices = {};
+
+        for (let endpoint of this.descriptor.endpoints) {
+            switch (endpoint.type) {
+                case 'RPC': {
+                    const handler = this.handlers[endpoint.name];
+                    if (!handler)
+                        throw "Missing handler: " + endpoint.name;
+                    this.RPCServices[endpoint.name] = new RPCService(endpoint, handler);
+                    break;
+                }
+                case 'Source':
+                    this[endpoint.name] = new SourceService(endpoint, this.transports);
+                    break;
+                case 'SharedObject':
+                    this[endpoint.name] = new SharedObjectService(endpoint, this.transports, this.initials[endpoint.name]);
+                    this.RPCServices["_SO_" + endpoint.name] = this[endpoint.name];
+                    break;
+                case 'PushPull':
+                    this[endpoint.name] = new PushService(endpoint, this.transports);
+                    break;
+                case 'Sink':
+                    this[endpoint.name] = new SinkService(endpoint, this.transports);
+                    this.SinkEndpoint = this[endpoint.name];
+                    break;
+                default:
+                    throw "Unknown endpoint type";
+            }
+        }
+    }
+
+    close() {
+        if (this._heartbeatInterval) {
+            clearInterval(this._heartbeatInterval);
+        }
+        if (this._httpServer) {
+            this._httpServer.close();
+        }
+        if (this.transports.source) {
+            this.transports.source.close();
+        }
+        if (this.transports.sink) {
+            this.transports.sink.close();
+        }
+        if (this.transports.pushpull) {
+            this.transports.pushpull.close();
+        }
+    }
+}
+
+module.exports = Service;

package/Service/SharedObjectService.js

@@ -0,0 +1,125 @@
+"use strict";
+
+const assert = require("assert");
+const fastcopy = require("fast-copy").default;
+const doValidate = require("../misc/Validation").SharedObjectValidation;
+const deepDiff = require("@azuliani/deep-diff");
+
+class SharedObjectService{
+    constructor(endpoint, transports, initial){
+        if (!transports.rpc || !transports.source)
+            throw new Error("Shared objects need both Source and RPC transports to be configured");
+
+        doValidate(endpoint, initial);
+        this.data = initial;
+        this._lastTransmit = fastcopy(initial);
+        this._v = 0;
+        this.endpoint = endpoint;
+        this.diffTransport = transports.source;
+        this.stats = {updates: 0};
+    }
+
+    call(data, callback) {
+        if (data.input === "init") {
+            callback(JSON.stringify({err: null, res: {data: this.data, v: this._v}}));
+        } else {
+            callback(JSON.stringify({err: `Unknown command: ${data.input}`}));
+        }
+    }
+
+    notify(hint, dirtyBypass){
+        const now = new Date();
+
+        if (!hint)
+            hint = [];
+
+        doValidate(this.endpoint, this.data, hint);
+
+        const diffs = diffAndReverseAndApplyWithHint(this._lastTransmit, this.data, hint, dirtyBypass);
+
+        if (diffs && diffs.length) {
+            this.stats.updates++;
+            this._v++;
+            const OTW = {
+                endpoint: "_SO_" + this.endpoint.name,
+                message: {diffs, v: this._v, now}
+            };
+            this.diffTransport.send([OTW.endpoint,JSON.stringify(OTW)]);
+        }
+    }
+
+    getStats(){
+        const current_stats = JSON.parse(JSON.stringify(this.stats));
+        this.stats.updates = 0;
+        return current_stats;
+    }
+}
+
+function diffAndReverseAndApplyWithHint(lhs, rhs, hint, bypass){
+    let lhsWithHint = lhs;
+    let rhsWithHint = rhs;
+    let lhsParent = null;
+    let i = 0;
+
+    while(i < hint.length){
+        // Stop if add or delete.
+        if (!(hint[i] in lhsWithHint) || !(hint[i] in rhsWithHint)){
+            break
+        }
+
+        lhsParent = lhsWithHint;
+
+        lhsWithHint = lhsWithHint[hint[i]];
+        rhsWithHint = rhsWithHint[hint[i]];
+        i++;
+    }
+
+    const hintUsed = hint.slice(0,i);
+
+    const reportDiffs = []; // Separate because of clone changes
+
+    if (hintUsed.length < hint.length){ // SHORTCUT
+         if (!(hint[i] in lhsWithHint) && (hint[i] in rhsWithHint)){ // SHORTCUT ADD
+             const cloned = fastcopy(rhsWithHint[hint[i]]);
+             reportDiffs.push({kind: 'N', path: [...hintUsed, hint[i]], rhs: cloned});
+             lhsWithHint[hint[i]] = cloned
+         }else if (!(hint[i] in rhsWithHint)){ // SHORTCUT DEL
+             reportDiffs.push({kind: 'D', path: [...hintUsed, hint[i]], lhs: lhsWithHint[hint[i]]});
+             delete lhsWithHint[hint[i]];
+         }else{
+             throw new Error("Wut?");
+         }
+    } else {
+        if (!bypass) {
+            const diffs = deepDiff.diff(lhsWithHint, rhsWithHint);
+            if (diffs) {
+                for (let i = diffs.length - 1; i >= 0; i--) {
+                    const diff = fastcopy(diffs[i]);
+                    if (diff.path) {
+                        diff.path = [...hintUsed, ...diff.path];
+                    } else {
+                        diff.path = hintUsed;
+                    }
+                    deepDiff.applyChange(lhs, rhs, diff);
+                    reportDiffs.push(diff);
+                }
+            }
+        } else {
+            // BYPASS
+            assert(lhsParent && hint[0]);
+
+            reportDiffs.push({
+                kind: 'N',
+                path: hint,
+                rhs: rhsWithHint
+            });
+
+            lhsParent[hint[hint.length-1]] = rhsWithHint;
+
+        }
+    }
+
+    return reportDiffs;
+}
+
+module.exports = SharedObjectService;

package/Service/SinkService.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const EventEmitter = require("events").EventEmitter;
+
+class SinkService extends EventEmitter {
+    constructor(endpoint, transports, hostname) {
+        super();
+        this.endpoint = endpoint;
+        this.transport = transports.sink;
+        this.hostname = hostname;
+        if (!this.transport)
+            throw new Error("Trying to construct Sink endpoint without Source transport");
+        this.stats = {updates: 0};
+    }
+
+    subscribe() {
+        this.transport.connect(this.hostname);
+    };
+
+    unsubscribe() {
+        this.transport.disconnect(this.hostname);
+    };
+
+    _processMessage(data) {
+        this.stats.updates++;
+        this.emit("message", data);
+    }
+
+    getStats(){
+        const current_stats = JSON.parse(JSON.stringify(this.stats));
+        this.stats.updates = 0;
+        return current_stats;
+    }
+}
+
+
+module.exports = SinkService;

package/Service/SourceService.js

@@ -0,0 +1,31 @@
+"use strict";
+
+const doValidation = require("../misc/Validation").SourceValidation;
+
+class SourceService{
+    constructor(endpoint, transports){
+        this.endpoint = endpoint;
+        this.transport = transports.source;
+        if (!this.transport)
+            throw "Trying to construct Source endpoint without Source transport";
+        this.stats = {updates: 0};
+    }
+
+    send(message){
+        doValidation(this.endpoint, message, false);
+        const OTW = {
+            endpoint: this.endpoint.name,
+            message: message
+        };
+        this.transport.send([OTW.endpoint, JSON.stringify(OTW)]);
+        this.stats.updates++;
+    }
+
+    getStats(){
+        const current_stats = JSON.parse(JSON.stringify(this.stats));
+        this.stats.updates = 0;
+        return current_stats;
+    }
+}
+
+module.exports = SourceService;

package/index.js

@@ -0,0 +1,9 @@
+"use strict";
+
+const Service = require("./Service/Service");
+const Client = require("./Client/Client");
+
+module.exports = {
+    Service,
+    Client
+};