devicelink 0.1.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026, Yassen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# devicelink (beta)
+
+### _Zero-configuration local network discovery and bidirectional messaging for Node.js._
+
+devicelink abstracts away the friction of IP hunting, port configuration, and manual endpoint routing. Whether you are building a distributed task queue across multiple laptops, orchestrating IoT microcontrollers, or just trying to get two local machines to talk to each other on the same subnet, devicelink handles the handshake and messaging instantly.
+
+## Features:
+
+- **Auto-Discovery:** Concurrently scan your local subnet to find active nodes in under 2 seconds.
+- **Zero-Config Handshakes:** Connect instances securely without manually tracking IP addresses.
+- **Instant JSON Messaging:** Fire bidirectional JSON payloads between connected devices immediately.
+- **Secure Routing:** Built-in IP validation prevents rogue network requests from spoofing messages.
+
+## Installation:
+
+```bash
+npm install devicelink
+```
+
+## Quick Start:
+
+Here is a complete example of two machines finding each other and communicating.
+
+1. **The Worker Node:** Run this on the first machine (or a separate terminal). It waits for a connection and listens for instructions.
+
+```js
+const Devicelink = require("devicelink");
+
+// Initialize on port 3000
+const dl = new Devicelink(3000, "Worker-Node-1");
+
+dl.onMessage((payload) => {
+  console.log(`[Message Received]:`, payload);
+
+  // Process task and respond...
+  if (payload.task === "ping") {
+    dl.message({ status: "success", response: "pong" });
+  }
+});
+
+dl.start();
+console.log("Worker listening for connections...");
+```
+
+2. **The Master Node:** Run this on the second machine. It searches the network, connects to the worker, and sends a task.
+
+```js
+const Devicelink = require("devicelink");
+
+const dl = new Devicelink(4000, "Master-Server");
+dl.start();
+
+(async () {
+  console.log("Scanning local network...");
+
+  // Search for devicelink instances running on port 3000
+  const foundDevices = await dl.search(3000);
+
+  if (foundDevices.length === 0) {
+    return console.log("No devices found on the network.");
+  }
+
+  const target = foundDevices[0];
+  console.log(`Found device: ${target.deviceName} at ${target.host}`);
+
+  // Lock the connection
+  await dl.connect(target);
+
+  // Define what happens when the worker replies
+  dl.onMessage((reply) => {
+    console.log(`[Reply from Worker]:`, reply);
+  });
+
+  // Send a JSON payload
+  await dl.message({ task: "ping", timestamp: Date.now() });
+})()
+```
+
+## API Reference:
+
+```js
+new Devicelink(port?, deviceName?)
+```
+
+Creates a new Devicelink instance.
+
+- **port:** `(Number)` The port your local instance will listen on. Defaults to 3000.
+- **deviceName:** `(String)` A human-readable identifier for this node. Defaults to "Unnamed".
+
+```js
+Devicelink.start();
+```
+
+Mounts the internal server and begins listening for incoming discovery pings and connections. Must be called before searching or receiving messages.\
+
+```js
+Devicelink.search(port?)
+```
+
+_Returns:_ `Promise<DevicelinkDevice[]>`
+Scans the entire local subnet concurrently for other active devicelink instances.
+
+- **port:** `(Number)` The target port to scan for. Defaults to the instance's own port.
+
+```js
+Devicelink.connect(device);
+```
+
+_Returns:_ `Promise<void>`
+
+Initiates a secure handshake with a DevicelinkDevice (usually obtained via .search()). Locks the instance into a 1-to-1 communication channel with the target.
+
+```js
+Devicelink.message(payload);
+```
+
+_Returns:_ `Promise<void>`
+
+Sends a JSON-serializable object to the currently connected device.
+
+```js
+Devicelink.onConnect(callback);
+```
+
+Registers a callback function that is triggered whenever a remote device successfully connects to this instance.
+
+- **callback:** `(device: DevicelinkDevice) => void`
+
+```js
+Devicelink.onMessage(callback);
+```
+
+Registers a callback function that is triggered whenever a valid JSON payload is received from the connected device.
+
+- **callback:** `(payload: Object) => void`
+
+## Architecture & Roadmap:
+
+devicelink is currently in active v0.x development. The current architecture relies on concurrent HTTP subnet scanning and standard POST requests for high reliability across diverse environments.
+
+## License: ISC

package/index.js

@@ -0,0 +1,343 @@
+const { log } = require("console");
+const express = require("express");
+const os = require("os");
+
+class Devicelink {
+  #app;
+  #onMessageCallback;
+  #onConnectCallback;
+
+  /**
+   * Creates a new Devicelink instance.
+   *
+   * @param {number} [port=3000] - The port the HTTP server will use.
+   * @param {string} [deviceName="Unnamed"] - The local device name.
+   */
+  constructor(port = 3000, deviceName = "Unnamed") {
+    this.port = port;
+    this.deviceName = deviceName;
+    this.lanAddress = getLanAddress();
+    this.isConnected = false;
+    this.isActive = false;
+    this.connectedDevice = new DevicelinkDevice();
+    this.#app = express();
+
+    /**
+     *
+     * @param {JSON} payload
+     * @returns
+     */
+    this.#onMessageCallback = (payload) => {
+      return;
+    };
+
+    /**
+     *
+     * @param {DevicelinkDevice} device
+     * @returns
+     */
+    this.#onConnectCallback = (device) => {
+      return;
+    };
+  }
+
+  /**
+   * Starts the Devicelink HTTP server and starts listening.
+   * @returns {void}
+   */
+  start() {
+    this.#app.set("trust proxy", true);
+    this.#app.use(express.json());
+
+    this.#app.post("/devicelink/connect", (req, res) => {
+      const deviceName = req.body["device_name"];
+      const isConnected = req.body["is_connected"];
+      const isActive = req.body["is_active"];
+
+      const host = getRequestHost(req);
+      this.connectedDevice = new DevicelinkDevice(
+        host,
+        deviceName,
+        true,
+        isActive,
+      );
+      res.sendStatus(200);
+      this.#onConnectCallback(this.connectedDevice);
+    });
+
+    this.#app.get("/devicelink/status", (req, res) => {
+      res.json({
+        device_name: this.deviceName,
+        is_connected: this.isConnected,
+        is_active: this.isActive,
+      });
+    });
+
+    this.#app.post(
+      "/devicelink/message",
+      (req, res, next) => this.#validateConnection(req, res, next),
+      (req, res) => {
+        const payload = req.body;
+        this.#onMessageCallback(payload);
+        res.sendStatus(200);
+      },
+    );
+
+    this.#app.listen(this.port);
+    this.isActive = true;
+  }
+
+  #validateConnection(req, res, next) {
+    const host = getRequestHost(req);
+    if (host != this.connectedDevice.host)
+      res.status(401).send("Unauthorized access");
+    else {
+      next();
+    }
+  }
+
+  /**
+   * Register a callback for when a devicelink connection is established.
+   * @param {(device: DevicelinkDevice) => void} callback Callback invoked with the connected device.
+   * @returns {void}
+   */
+  onConnect(callback) {
+    this.#onConnectCallback = callback;
+  }
+
+  /**
+   * Register a callback for incoming devicelink messages.
+   * @param {(payload: JSON) => void} callback Callback invoked with the message payload.
+   * @returns {void}
+   */
+  onMessage(callback) {
+    this.#onMessageCallback = callback;
+  }
+
+  /**
+   * Connect to other devicelink instance.
+   * @param {DevicelinkDevice} device A devicelink device to connect to.
+   * @returns
+   */
+  async connect(device) {
+    try {
+      const response = await fetch(`http://${device.host}/devicelink/connect`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Devicelink-Port": this.port,
+        },
+        body: JSON.stringify({
+          device_name: this.deviceName,
+          is_connected: this.isConnected,
+          is_active: this.isActive,
+        }),
+      });
+      if (!response.ok)
+        return console.error(`Failed to connect to ${device.deviceName}`);
+      this.connectedDevice = device;
+      this.isConnected = true;
+      this.#onConnectCallback(device);
+    } catch (error) {
+      console.error(
+        `Network error: Could not reach ${this.connectedDevice.deviceName}`,
+      );
+    }
+  }
+
+  /**
+   * Send a devicelink message to the currently connected device.
+   * @param {Object} payload JSON-serializable payload to send in the request body.
+   * @returns {Promise<void>} Resolves when the request completes; logs an error on failure.
+   */
+  async message(payload) {
+    try {
+      const response = await fetch(
+        `http://${this.connectedDevice.host}/devicelink/message`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Devicelink-Port": this.port,
+          },
+          body: JSON.stringify(payload),
+        },
+      );
+      if (!response.ok)
+        return console.error(
+          `Failed to send message to ${this.connectedDevice.deviceName}`,
+        );
+    } catch (error) {
+      console.error(
+        `Network error: Could not reach ${this.connectedDevice.deviceName}`,
+      );
+    }
+  }
+
+  /**
+   * Search all nearby devices in current subnet for an active devicelink instance.
+   * @param {Number} port The port devicelink will search in (defaults to current port).
+   * @returns {Promise<DevicelinkDevice[]>} A list of discovered active devices.
+   */
+  async search(port = this.port) {
+    const baseIp = getBaseIp(this.lanAddress);
+    const promises = [];
+    const timeoutMs = 1500;
+
+    for (let i = 1; i <= 254; i++) {
+      const targetIp = baseIp + i;
+      promises.push(this.#pingDevice(targetIp, port, timeoutMs));
+    }
+
+    const results = await Promise.allSettled(promises);
+
+    const foundDevices = results
+      .filter(
+        (result) => result.status === "fulfilled" && result.value !== null,
+      )
+      .map((result) => result.value);
+
+    return foundDevices;
+  }
+
+  async #pingDevice(ip, port, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const host = `${ip}:${port}`;
+
+    try {
+      const url = `http://${host}/devicelink/status`;
+      const response = await fetch(url, { signal: controller.signal });
+
+      if (response.ok) {
+        const data = await response.json();
+
+        if (data) {
+          const device = new DevicelinkDevice(
+            host,
+            data["device_name"],
+            data["is_connected"],
+            data["is_active"],
+          );
+          return device;
+        }
+      }
+    } catch (error) {
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    return null;
+  }
+}
+
+class DevicelinkDevice {
+  #host;
+  #deviceName;
+  #isConnected;
+  #isActive;
+
+  /**
+   * Creates a new Devicelink device instance.
+   *
+   * @param {string} host - The device host in `ip:port` format.
+   * @param {string} deviceName - The device name.
+   * @param {boolean} isConnected - Whether the device is connected.
+   * @param {boolean} isActive - Whether the device is active.
+   */
+  constructor(host, deviceName, isConnected, isActive) {
+    this.#host = host;
+    this.#deviceName = deviceName;
+    this.#isConnected = isConnected;
+    this.#isActive = isActive;
+  }
+
+  /**
+   * Gets the device host.
+   *
+   * @returns {string} The host in `ip:port` format.
+   */
+  get host() {
+    return this.#host;
+  }
+
+  /**
+   * Gets the device name.
+   *
+   * @returns {string} The device name.
+   */
+  get deviceName() {
+    return this.#deviceName;
+  }
+
+  /**
+   * Gets whether the device is connected.
+   *
+   * @returns {boolean} True when connected.
+   */
+  get isConnected() {
+    return this.#isConnected;
+  }
+
+  /**
+   * Gets whether the device is active.
+   *
+   * @returns {boolean} True when active.
+   */
+  get isActive() {
+    return this.#isActive;
+  }
+
+  /**
+   * Returns a custom Node.js inspection string.
+   *
+   * @returns {string} A formatted device description.
+   */
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return `<DevicelinkDevice [${this.#deviceName}] at ${this.#host} (connected: ${this.#isConnected}, active: ${this.#isActive})>`;
+  }
+}
+
+function getLanAddress() {
+  const nets = os.networkInterfaces();
+  for (const name of Object.keys(nets)) {
+    for (const net of nets[name]) {
+      if (net.family === "IPv4" && !net.internal) {
+        return net.address;
+      }
+    }
+  }
+  return "127.0.0.1";
+}
+
+function getBaseIp(ip = "121.0.0.1") {
+  const parts = ip.split(".");
+  parts.pop();
+  return parts.join(".") + ".";
+}
+
+function convertToIpv4(ip = "::ffff:121.0.0.1") {
+  if (ip == "::1") return "127.0.0.1";
+  if (ip.substring(0, 7) === "::ffff:") {
+    ip = ip.substring(7);
+  }
+
+  return ip;
+}
+
+/**
+ * Builds a callback host string from the request IP and `x-callback-port` header.
+ * @param {Object} req - The request object.
+ * @param {string} [req.ip] - The request IP address.
+ * @param {Object} req.socket - The socket object.
+ * @param {string} req.socket.remoteAddress - The socket remote address.
+ * @returns {string} The formatted host address in `ip:port` format.
+ */
+function getRequestHost(req) {
+  const ip = convertToIpv4(req.ip || req.socket.remoteAddress);
+  const port = req.headers["x-devicelink-port"];
+  const host = `${ip}:${port}`;
+  return host;
+}
+
+module.exports = Devicelink;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "devicelink",
+  "version": "0.1.1",
+  "description": "A way to get multiple devices on the same network to talk with each other.",
+  "license": "ISC",
+  "author": "YasoXtreme",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "express": "^5.2.1"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ]
+}