@stevvvns/act 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 stevvvns
+
+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,91 @@
+# act
+
+To define an actor, put it in its own directory and do something like:
+
+**`test/index.js`**
+```javascript
+import actor from 'act/actor.js';
+
+actor({
+  hello(name) {
+    return `hey, ${name}`;
+  }
+});
+```
+
+Then, define a config file for your actor(s):
+
+**`config.js`**
+```javascript
+import { resolve } from 'node:path';
+
+const mod = x => resolve('.', x);
+export default {
+  defaultTimeout: '10s',
+  maxMailbox: 500,
+  actors: {
+    test: {
+      mode: 'fork',
+      module: mod('test')
+    },
+  },
+  log: console.log
+};
+```
+
+Finally, to use the forked service:
+
+**`entry.js`**
+```javascript
+import act from '../src/index.js';
+import config from './config.js';
+
+const sys = await act(config);
+console.log(await sys.test.hello('jerks').timeout('30s')); // optional timeout override
+sys.shutdown();
+```
+
+## Remote Actors
+
+***You MUST firewall your remote actors so that only your app may access them, it is not safe to leave the port open!***
+
+The actor **`test/index.js`** and **`entry.js`** are exactly the same as above.
+
+On the remote server, you need to define a config file for the actors you plan to serve:
+
+**`actors.js`**
+```javascript
+import { resolve } from 'node:path';
+
+const mod = x => resolve(process.cwd(), x);
+export default {
+  log: console.log,
+  listen: '0.0.0.0',
+  actors: {
+    remoteTest: mod('test'),
+    maxMailbox: 500
+  }
+}
+```
+
+Next, you need to run `remote-service.js` from this package as a service, with the path to the above config as an argument:
+
+`$ node node_modules/act/remote-service.js actors.js`
+
+You should do this with something like supervisord to have some fault tolerance.
+
+After running the service, modify the `config.js` file for the controlling service to specify the host:
+
+**`config.js`**
+```javascript
+export default {
+  defaultTimeout: '10s',
+  actors: {
+    test: {
+      mode: 'remote',
+      host: 'localhost' #  or wherever, note the dire warning above about firewalling this
+    },
+  },
+  log: console.log
+};
+```

package/eslint.config.js

@@ -0,0 +1,12 @@
+import js from "@eslint/js";
+import globals from "globals";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    files: ["src/*.{js,mjs,cjs}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: { globals: globals.node }
+  },
+]);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@stevvvns/act",
+  "type": "module",
+  "version": "0.0.1",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "lint": "npx eslint src --fix; npx prettier src --single-quote --write"
+  },
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "ms": "^2.1.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.2.0",
+    "globals": "^17.5.0"
+  }
+}

package/src/actor.js

@@ -0,0 +1,27 @@
+import { encode, decode } from '@msgpack/msgpack';
+
+export default function actor(callbacks) {
+  const reply = (msg) => {
+    process.send(Object.values(encode(msg)));
+  };
+
+  process.on('message', async (msg) => {
+    if (msg === 'exit') {
+      process.exit(0);
+    }
+    const [id, mtd, args] = decode(msg);
+    if (!callbacks[mtd]) {
+      reply([id, 'error', `no such method ${mtd}`]);
+      return;
+    }
+    try {
+      if (Math.random() > 0.8) {
+        //throw new Error('crash');
+      }
+      reply([id, 'ok', await callbacks[mtd](...args)]);
+    } catch (ex) {
+      reply([id, 'error', ex.toString()]);
+      throw ex;
+    }
+  });
+}

package/src/index.js

@@ -0,0 +1,294 @@
+import { fork } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { encode, decode } from '@msgpack/msgpack';
+import { createConnection } from 'node:net';
+import toMs from 'ms';
+import { EventEmitter } from 'node:events';
+
+export class DurableSocket extends EventEmitter {
+  constructor({
+    host,
+    port,
+    log,
+    name,
+    initialDelay = 100,
+    maxDelay = 10000,
+    factor = 2,
+    downRetries = 20,
+  }) {
+    super();
+    this.host = host;
+    this.port = port;
+    this.log = log;
+    this.name = name;
+    this.initialDelay = this.reconnectDelay = initialDelay;
+    this.maxDelay = maxDelay;
+    this.factor = factor;
+    this.downRetries = downRetries;
+
+    this.connect();
+  }
+
+  connect() {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.socket = createConnection({
+      host: this.host,
+      port: this.port,
+    });
+
+    this.socket.on('connect', () => {
+      this.retries = 0;
+      this.connected = true;
+      this.reconnectDelay = this.initialDelay;
+      this.log({ evt: 'remote connected', name: this.name });
+      this.emit('connect');
+    });
+
+    this.socket.on('data', (data) => {
+      this.emit('data', data);
+    });
+
+    this.socket.on('error', (err) => {
+      this.log({ evt: 'remote error', name: this.name, err });
+      this.emit('error', err);
+    });
+
+    this.socket.on('close', (err) => {
+      this.connected = false;
+      this.socket = null;
+
+      this.emit('close', err);
+
+      if (!this.destroyed) {
+        this.scheduleReconnect();
+      }
+    });
+  }
+
+  write(chunk) {
+    if (this.destroyed) {
+      throw new Error('socket destroyed');
+    }
+
+    if (this.connected && this.socket?.writable) {
+      return this.socket.write(chunk);
+    }
+
+    throw new Error('not connected');
+  }
+
+  destroy() {
+    this.destroyed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+
+    this.socket?.destroy();
+  }
+
+  scheduleReconnect() {
+    if (this.reconnectTimer) {
+      return;
+    }
+    if (++this.retries > this.downRetries) {
+      this.emit('down');
+      this.log({ evt: 'remote down', name: this.name });
+    }
+    this.log({ evt: 'remote reconnect', name: this.name });
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, this.reconnectDelay);
+    this.reconnectDelay =
+      Math.min(this.reconnectDelay * this.factor, this.maxDelay) +
+      (0.8 + Math.random() * 0.4);
+  }
+}
+
+export default async function act(config) {
+  const log = config.log ? config.log : () => {};
+  const rv = {};
+  const dispatch = {};
+  const defaultMaxMailbox = config.maxMailbox ?? 500;
+  const defaultPort = config.remotePort ?? 22327;
+  const maxMb = {};
+  let shuttingDown = false;
+  const timeout = (() => {
+    if (!config.defaultTimeout) {
+      return 1000;
+    }
+    if (typeof config.defaultTimeout === 'string') {
+      return toMs(config.defaultTimeout);
+    }
+    return config.defaultTimeout;
+  })();
+  const procs = {};
+  const timeouts = {};
+
+  function shutdown() {
+    if (!shuttingDown) {
+      log({ evt: 'shutdown' });
+      shuttingDown = true;
+    }
+    for (const [name, inFlight] of Object.entries(dispatch)) {
+      if (Object.values(inFlight).length === 0) {
+        log({ evt: 'exit', name });
+        procs[name].send('exit');
+      } else {
+        log({ evt: 'drain', name });
+      }
+    }
+  }
+  function handleResponse(name, payload) {
+    const [id, status, resp] = payload;
+    if (timeouts[id]) {
+      clearTimeout(timeouts[id]);
+      delete timeouts[id];
+    }
+    log({ evt: 'incoming', name, id, status, resp });
+    if (!dispatch[name][id]) {
+      log({ evt: 'internal error', name, type: 'received unexpected message' });
+      return;
+    }
+    dispatch[name][id][status === 'ok' ? 'resolve' : 'reject'](resp);
+    delete dispatch[name][id];
+    if (shuttingDown) {
+      shutdown();
+    }
+  }
+
+  log({ evt: 'startup', defaultTimeout: timeout });
+  for (const [name, settings] of Object.entries(config.actors)) {
+    if (name === 'shutdown') {
+      throw new Error('"shutdown" is a reserved name');
+    }
+    if (!['fork', 'remote'].includes(settings.mode)) {
+      throw new Error(`${name}: unhandled mode ${settings.mode}`);
+    }
+    log({ evt: 'register', name, ...settings });
+    maxMb[name] = settings.maxMailbox ?? defaultMaxMailbox;
+    dispatch[name] = {};
+
+    function handleRequest({ send, checkConnected }) {
+      return new Proxy(
+        {},
+        {
+          get(_, mtd) {
+            return (...args) => {
+              const id = randomUUID();
+              const pr = new Promise((resolve, reject) => {
+                if (shuttingDown) {
+                  return;
+                }
+                if (Object.keys(dispatch[name]).length >= maxMb[name]) {
+                  log({ evt: 'full mailbox', name, max: maxMb[name] });
+                  return reject('mailbox full');
+                }
+                if (checkConnected && !procs[name].connected) {
+                  for (const [id, { reject }] of Object.entries(
+                    dispatch[name],
+                  )) {
+                    if (timeouts[id]) {
+                      clearTimeout(timeouts.id);
+                    }
+                    reject('disconnected');
+                  }
+                  dispatch[name] = {};
+                  procs[name] = fork(settings.module);
+                  procs[name].on('message', (msg) =>
+                    handleResponse(name, decode(msg)),
+                  );
+                  return reject('disconnected');
+                }
+                dispatch[name][id] = { resolve, reject };
+                log({ evt: 'outgoing', name, id, mtd, args });
+                send(id, mtd, args);
+              });
+              const reaper = () => {
+                if (dispatch[name][id]) {
+                  dispatch[name][id].reject('actor timed out');
+                }
+              };
+              timeouts[id] = setTimeout(reaper, timeout);
+              pr.timeout = (num) => {
+                clearTimeout(timeouts[id]);
+                const asMs = typeof num === 'string' ? toMs(num) : num;
+                timeouts[id] = setTimeout(reaper, asMs);
+                return pr;
+              };
+              return pr;
+            };
+          },
+        },
+      );
+    }
+
+    if (settings.mode === 'fork') {
+      procs[name] = fork(settings.module);
+      procs[name].on('message', (msg) => handleResponse(name, decode(msg)));
+
+      rv[name] = handleRequest({
+        send(id, mtd, args) {
+          procs[name].send(Object.values(encode([id, mtd, args])));
+        },
+        checkConnected: true,
+      });
+      continue;
+    }
+    // TODO could share a socket for same host/port w/ different actors, but meh
+    await new Promise((resolve, reject) => {
+      const port = settings.port ?? defaultPort;
+      const host = settings.host ?? 'localhost';
+      const sock = new DurableSocket({ host, port, log, name });
+      sock.on('error', (err) => {
+        if (!sock.connected) {
+          reject(`failed to connect: ${err}`);
+        }
+      });
+      procs[name] = {
+        send(msg) {
+          if (msg === 'exit') {
+            sock.destroy();
+            return;
+          }
+          sock.write(encode(msg));
+        },
+      };
+      sock.on('data', (msg) => {
+        const [op, payload] = decode(msg);
+        log({ evt: 'incoming', remote: true, name, op, payload });
+        if (op === 'ensure') {
+          if (payload.status === 'ok') {
+            resolve();
+          } else {
+            reject(`misconfiguration: ${host}:${port} cannot service ${name}`);
+          }
+        } else if (op === 'call') {
+          handleResponse(name, payload);
+        } else if (op === 'crash') {
+          for (const [id, { reject }] of Object.entries(dispatch[name])) {
+            if (timeouts[id]) {
+              clearTimeout(timeouts.id);
+            }
+            reject('disconnected');
+          }
+          dispatch[payload] = {};
+        }
+      });
+      sock.on('connect', () => {
+        procs[name].send(['ensure', name]);
+      });
+    });
+    // TODO move mailbox restriction to remote-service, dedupe with fork proxy
+    rv[name] = handleRequest({
+      send(id, mtd, args) {
+        procs[name].send(['call', [id, name, mtd, args]]);
+      },
+    });
+  }
+  rv.shutdown = shutdown;
+  return rv;
+}

package/src/remote-service.js

@@ -0,0 +1,56 @@
+import { createServer } from 'node:net';
+import { resolve } from 'node:path';
+import { fork } from 'node:child_process';
+import { encode, decode } from '@msgpack/msgpack';
+
+if (process.argv.length !== 3) {
+  console.error(
+    'you must provide a path to a configuration file as an argument',
+  );
+  process.exit(1);
+}
+const config = (await import(resolve(process.cwd(), process.argv[2]))).default;
+const host = config.listen ?? '127.0.0.1';
+if (!['127.0.0.1', 'localhost'].includes(host)) {
+  console.warn(
+    'WARNING: it is dangerous to use this service without firewalling it so that only your application(s) can access it!',
+  );
+}
+const log = config.log ? config.log : () => {};
+const actors = {};
+for (const [name, path] of Object.entries(config.actors)) {
+  log({ evt: 'register', name, path });
+  actors[name] = fork(path);
+}
+
+createServer((sock) => {
+  sock.on('data', async (msg) => {
+    const [op, payload] = decode(msg);
+    log({ evt: 'rcv', op, payload });
+    if (op === 'ensure') {
+      sock.write(
+        encode([
+          'ensure',
+          { status: actors[payload] ? 'ok' : 'na', name: payload },
+        ]),
+      );
+      if (actors[payload]) {
+        actors[payload].on('message', (msg) => {
+          sock.write(encode(['call', decode(msg)]));
+        });
+      }
+    }
+    if (op === 'call') {
+      const [id, name, mtd, args] = payload;
+      if (!actors[name].connected) {
+        actors[name] = fork(config.actors[name]);
+        actors[name].on('message', (msg) => {
+          sock.write(encode(['call', decode(msg)]));
+        });
+        sock.write(encode(['crash', { name }]));
+        return;
+      }
+      actors[name].send(Object.values(encode([id, mtd, args])));
+    }
+  });
+}).listen(config.port ? parseInt(config.port) : 22327, host);

package/src/t

@@ -0,0 +1,87 @@
+         # remote
+         return (...args) => {
+            const id = randomUUID();
+            const pr = new Promise((resolve, reject) => {
+              if (shuttingDown) {
+                return;
+              }
+              if (Object.keys(dispatch[name]).length >= maxMb[name]) {
+                log({ evt: 'full mailbox', name, max: maxMb[name] });
+                return reject('mailbox full');
+              }
+              dispatch[name][id] = { resolve, reject };
+              log({ evt: 'outgoing', remote: true, name, id, mtd, args });
+              try {
+                ##
+                procs[name].send(['call', [id, name, mtd, args]]);
+                ##
+              }
+              catch (ex) {
+                reject(ex);
+              }
+            });
+            const reaper = () => {
+              if (dispatch[name][id]) {
+                dispatch[name][id].reject('actor timed out');
+              }
+            };
+            timeouts[id] = setTimeout(reaper, timeout);
+            pr.timeout = num => {
+              clearTimeout(timeouts[id]);
+              const asMs = typeof num === 'string' ? toMs(num) : num;
+              timeouts[id] = setTimeout(reaper, asMs);
+              return pr;
+            };
+            return pr;
+          };
+
+          # fork
+          return (...args) => {
+            const id = randomUUID();
+            const pr = new Promise((resolve, reject) => {
+              if (shuttingDown) {
+                return;
+              }
+              if (Object.keys(dispatch[name]).length >= maxMb[name]) {
+                log({ evt: 'full mailbox', name, max: maxMb[name] });
+                return reject('mailbox full');
+              }
+              ### fork only
+              if (!procs[name].connected) {
+                for (const [id, { reject }] of Object.entries(dispatch[name])) {
+                  if (timeouts[id]) {
+                    clearTimeout(timeouts.id);
+                  }
+                  reject('disconnected');
+                }
+                dispatch[name] = {};
+                procs[name] = fork(settings.module);
+                procs[name].on('message', msg => handleResponse(name, decode(msg)));
+                return reject('disconnected');
+              }
+              ###
+              dispatch[name][id] = { resolve, reject };
+              log({ evt: 'outgoing', name, id, mtd, args });
+              try {
+                ##
+                procs[name].send(Object.values(encode([id, mtd, args])));
+                ##
+              }
+              catch (ex) {
+                reject(ex);
+              }
+            });
+            const reaper = () => {
+              if (dispatch[name][id]) {
+                dispatch[name][id].reject('actor timed out');
+              }
+            };
+            timeouts[id] = setTimeout(reaper, timeout);
+            pr.timeout = num => {
+              clearTimeout(timeouts[id]);
+              const asMs = typeof num === 'string' ? toMs(num) : num;
+              timeouts[id] = setTimeout(reaper, asMs);
+              return pr;
+            };
+            return pr;
+          };