Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/build-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,25 @@ concurrency:
cancel-in-progress: true

jobs:
test:
name: Local regression tests (Node ${{ matrix.node }})
runs-on: ubuntu-latest
strategy:
matrix:
node: ["22.18.0", "24.19.0"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm run typecheck
- run: npm test

build-docker:
name: Build Docker
needs: test
runs-on: ubuntu-latest
steps:
- name: Checkout
Expand Down
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@ js
.idea
*.iml
private
dist
dist
/planning/
7 changes: 4 additions & 3 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
FROM node:lts-alpine AS build
ARG NODE_IMAGE=node:22.18.0-alpine@sha256:1b2479dd35a99687d6638f5976fd235e26c5b37e8122f786fcd5fe231d63de5b
FROM ${NODE_IMAGE} AS build
WORKDIR /app

COPY /tsconfig.json ./
COPY /package.json ./
COPY /package-lock.json ./
RUN npm install
RUN npm ci
COPY /build.mjs ./

COPY /src ./src
RUN npm run build

FROM node:lts-alpine
FROM ${NODE_IMAGE}

EXPOSE 3000
EXPOSE 8080
Expand Down
62 changes: 62 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,68 @@ Additionally, there are some environment variables that can optionally be specif
| `HOST` | The address that the HTTP and websocket servers should bind to. | `127.0.0.1` |
| `HTTP_PORT` | The port that the HTTP server should listen on. | `3000` |
| `WEBSOCKET_PORT` | The port that the websocket server should listen on. | `8080` |
| `REQUEST_TIMEOUT_MS` | Maximum wait for a complete controller response, in milliseconds. Must be an integer from 1 to 300000; invalid values fall back to the default with a warning. | `60000` |

## Connection and request behavior

Controllers are authenticated before registration and protocol handling. A new
connection using an already connected device key is rejected; it does not replace
the existing owner. Authentication has a ten-second deadline; timeout rejects with
close code `1011`, and late results cannot register the connection. Disconnecting
during authentication releases its deadline and wait state. MySQL queries also
have a ten-second driver inactivity limit; a lookup that completes after the
socket's deadline is ignored. The existing 10-second ping interval and missed-pong policy
are preserved. Policy rejections use WebSocket close code `1008`; authentication
backend failures use `1011`. Rejected connections receive an `ERR:` message and a
close frame, with forced termination after five seconds if closing stalls.

Pending requests belong to their individual controller session. A disconnected
controller fails its pending requests with HTTP `408`, and requests for an absent
controller receive `404`. Requests exceeding `REQUEST_TIMEOUT_MS` receive `408`
with `{"message":"Controller did not respond."}`. Browser departure releases
the pending request without waiting for the controller. A timeout or browser
departure does not cancel an action already sent to the controller.

The proxy never automatically resends a forwarded request, including GETs:
OpenSprinkler uses GET for some state-changing commands. A timed-out command may
already have executed, so its outcome can be unknown.

Request IDs remain four hexadecimal characters and are allocated sequentially
within each session, starting at a random value and skipping pending IDs. Full
capacity returns HTTP `429`. The unchanged wire format has no generation field:
a sufficiently delayed response can match a newer request after same-session ID
reuse. Skipping occupied IDs means a counter cycle need not represent 65,536
forwarded requests. Responses on an old connection cannot answer requests on a
replacement connection.

Lifecycle logs include connection IDs, token fingerprints, cleanup/rejection
reasons, heartbeat age, and pending counts. HTTP and request-settlement logs retain
recognized endpoint names such as `/jc`, `/cm` and `/s2id_gen`. Unknown endpoints
are logged as `/other`; subsequent path segments are dropped. HTTP logging omits
URLs, query strings, headers, and response headers to avoid leaking tokens and
passwords. Startup diagnostics identify missing or invalid setting names without
printing their values. Malformed
payloads and raw database errors are not logged. Rejection and other repeated
diagnostic events have bounded output and aggregation state.

Both Docker stages use Node `22.18.0` on Alpine, pinned to the immutable image
index digest in `Dockerfile`. Dependency installation uses `npm ci`. Updating the
base image requires an intentional digest change and runtime validation; it no
longer follows the floating Node LTS tag.

## Local validation

```bash
npm ci
npm run typecheck
npm test
```

Tests start isolated HTTP/WebSocket servers on loopback with fake device keys and
stubbed authentication. They include a real 31-second response to verify that the
60-second default accommodates a request taking longer than 30 seconds. The suite
does not contact production or physical controllers. Real legacy-client pacing
and device compatibility still require separately authorized staging tests.



Expand Down
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@
"scripts": {
"build": "node build.mjs",
"start": "node dist/index.cjs",
"test": "echo \"Error: no test specified\" && exit 1"
"test": "npm run build && node tests/run.mjs",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"body-parser": "^1.20.2",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { Logger } from "pino";
import { AuthenticationPlugin } from "../AuthenticationPlugin";
import { ConfigurationError } from "../configuration";

/** Validates device keys by checking if they're listed in the environment variable `DEVICE_KEYS`. */
export default class EnvironmentVariableAuthenticationPlugin extends AuthenticationPlugin {
Expand All @@ -9,7 +10,7 @@ export default class EnvironmentVariableAuthenticationPlugin extends Authenticat
public async init(logger: Logger): Promise<void> {
this.logger = logger;
if (!process.env.DEVICE_KEYS) {
throw `Environment variable 'DEVICE_KEYS' is not defined.`;
throw new ConfigurationError("DEVICE_KEYS", "missing");
}

this.deviceKeys = process.env.DEVICE_KEYS.split(",");
Expand Down
22 changes: 16 additions & 6 deletions src/authenticationPlugins/MySQLAuthenticationPlugin.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import { Logger } from "pino";
import { AuthenticationPlugin } from "../AuthenticationPlugin";
import * as mysql from "mysql";
import { backendErrorCode } from "../diagnostics";
import { ConfigurationError } from "../configuration";

/**
* Validates device keys by checking if they exist in a MySQL database.
Expand All @@ -13,27 +15,35 @@ export default class MySQLAuthenticationPlugin extends AuthenticationPlugin {
this.logger = logger;
return new Promise((resolve, reject) => {
// Make sure that necessary variables have been defined.
for (const key of ["MYSQL_TABLE", "MYSQL_CONNECTION_URL"]) {
for (const key of ["MYSQL_TABLE", "MYSQL_CONNECTION_URL"] as const) {
if (!process.env[key]) {
reject(`Environment variable '${key}' is not defined.`);
reject(new ConfigurationError(key, "missing"));
return;
}
}

this.pool = mysql.createPool(process.env.MYSQL_CONNECTION_URL);
try {
this.pool = mysql.createPool(process.env.MYSQL_CONNECTION_URL);
} catch {
reject(new ConfigurationError("MYSQL_CONNECTION_URL", "invalid"));
return;
}
resolve();
});
}

public validateKey(deviceKey: string): Promise<boolean> {
return new Promise<boolean>((resolve, reject) => {
this.pool.query(
"SELECT * FROM ?? WHERE device_key = ?",
{ sql: "SELECT * FROM ?? WHERE device_key = ?", timeout: 10_000 },
[process.env.MYSQL_TABLE, deviceKey],
(err, results, fields) => {
if (err) {
this.logger.error(err, "Error querying MySQL database");
resolve(false);
// mysql errors include the formatted SQL and key. The
// forwarder rate-limits logging of this sanitized failure.
const failure = new Error("Authentication backend unavailable");
Object.assign(failure, { code: backendErrorCode(err) });
reject(failure);
return;
}

Expand Down
21 changes: 21 additions & 0 deletions src/configuration.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
type Setting = "AUTHENTICATION_PLUGIN" | "DEVICE_KEYS" | "MYSQL_TABLE" | "MYSQL_CONNECTION_URL";

// These messages are safe to log: they name settings, never their values.
export class ConfigurationError extends Error {
constructor(readonly setting: Setting, readonly reason: "missing" | "unsupported" | "invalid") {
super(`${setting} is ${reason}`);
this.name = "ConfigurationError";
}
}

export function startupFailure(error: unknown) {
if (error instanceof ConfigurationError) {
return { event: "startup_failure", setting: error.setting,
reason: error.reason, message: error.message };
}
const code = (error as { code?: unknown })?.code;
const known = ["EADDRINUSE", "EADDRNOTAVAIL", "EACCES", "EMFILE", "ENFILE"];
return { event: "startup_failure", reason: "initialization_failed",
errorCode: typeof code === "string" && known.includes(code) ? code : undefined,
message: "Unable to initialize proxy" };
}
80 changes: 80 additions & 0 deletions src/diagnostics.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import { createHash } from "crypto";
import { Logger } from "pino";

export function tokenFingerprint(token: string): string {
return createHash("sha256").update(token).digest("hex").slice(0, 8);
}

const ENDPOINTS = new Set([
"", "index.html", "cv", "jc", "dp", "cp", "cr", "mp", "up", "jp", "jpa",
"co", "jo", "sp", "js", "cm", "cs", "jn", "je", "jl", "dl", "su", "cu",
"ja", "pq", "db", "lf", "df", "jsn", "csn", "dsn", "jsl", "dsl", "jsd",
"update", "jsap", "ccap", "jtap", "vo", "vl", "ad", "cc", "jt",
"resetall", "clearlog", "s2id_gen",
]);

export function forwardedEndpoint(url: string): string | undefined {
const match = /^\/forward\/v1\/[^/?]+(?:\/([^/?#]*))?/.exec(url);
if (!match) return undefined;
const endpoint = match[1] || "";
// Generic IoT paths can contain secrets too. Log only recognized endpoint
// names, dropping query strings and all subsequent path segments.
return ENDPOINTS.has(endpoint) ? `/${endpoint}` : "/other";
}

// Limit both repeated identities and a burst of distinct, untrusted identities.
// Suppression counts are reported with the next permitted event.
export class EventLimiter {
private entries = new Map<string, { at: number; suppressed: number }>();
private windowStart: number;
private emitted = 0;
private suppressed = 0;

constructor(
private readonly windowMs = 60_000,
private readonly maxEntries = 256,
private readonly maxEvents = 100,
private readonly now = Date.now
) {
this.windowStart = now();
}

log(logger: Logger, level: "info" | "warn" | "debug", event: string,
identity: string, fields: Record<string, unknown> = {}): void {
const now = this.now();
if (now - this.windowStart >= this.windowMs) {
this.windowStart = now;
this.emitted = 0;
}
if (this.emitted >= this.maxEvents) {
this.suppressed++;
return;
}
const key = `${event}:${identity}`;
const entry = this.entries.get(key);
if (entry && now - entry.at < this.windowMs) {
entry.suppressed++;
return;
}
if (!entry && this.entries.size >= this.maxEntries) {
this.entries.delete(this.entries.keys().next().value);
}
this.entries.set(key, { at: now, suppressed: 0 });
this.emitted++;
logger[level]({ ...fields, event,
suppressed: (entry?.suppressed || 0) + this.suppressed });
this.suppressed = 0;
}
}

// Never serialize backend error objects: mysql errors may contain SQL and keys.
export function backendErrorCode(error: unknown): string {
const code = (error as { code?: unknown })?.code;
const known = new Set([
"ECONNREFUSED", "ETIMEDOUT", "ECONNRESET", "ENOTFOUND",
"PROTOCOL_CONNECTION_LOST", "PROTOCOL_SEQUENCE_TIMEOUT", "ER_ACCESS_DENIED_ERROR", "ER_BAD_DB_ERROR",
"ER_NO_SUCH_TABLE", "ER_PARSE_ERROR", "ER_CON_COUNT_ERROR",
"POOL_ENQUEUELIMIT",
]);
return typeof code === "string" && known.has(code) ? code : "AUTH_BACKEND_ERROR";
}
55 changes: 55 additions & 0 deletions src/httpApp.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import bodyParser from "body-parser";
import cors from "cors";
import express, { RequestHandler } from "express";
import { Logger } from "pino";
import { pinoHttp } from "pino-http";
import { forwardedEndpoint, tokenFingerprint } from "./diagnostics";

export function createHttpApp(forward: RequestHandler, logger: Logger) {
const app = express();
app.use(pinoHttp({
logger: logger.child({ name: "http" }),
customSuccessMessage(req, res) {
if ((res as express.Response).locals?.controllerResponseForwarded) {
return "controller response forwarded";
}
return !req.readableAborted && res.writableEnded ? "request completed" : "request aborted";
},
serializers: {
req(req) {
const match = /^\/forward\/v1\/([^/?]+)/.exec(req.url || "");
return { id: req.id, method: req.method,
route: match ? "/forward/v1/:deviceKey" : "other",
endpoint: forwardedEndpoint(req.url || ""),
tokenHash: match ? tokenFingerprint(match[1]) : undefined };
},
// Redirect Location headers can also contain the token and password.
res(res) {
// Pino's standard wrapper reports null until Express sends
// headers. Raw controller replies bypass that Express state.
const raw = res.raw as express.Response;
return { statusCode: raw?.locals?.controllerResponseForwarded
? raw.statusCode : res.statusCode };
},
err() { return { message: "HTTP request failed" }; },
},
}));
app.use(cors());
app.use(bodyParser.text({ type: "*/*", limit: "1mb" }));
app.all("/forward/v1/:deviceKey$", (req, res) => {
res.redirect(301, req.url + "/");
});
app.all("/forward/v1/:deviceKey*?", forward);
const errorHandler: express.ErrorRequestHandler = (err, req, res, _next) => {
req.log.warn({ event: "http_request_error" });
if (res.headersSent) {
res.destroy();
return;
}
const status = Number.isInteger(err?.status) && err.status >= 400 && err.status < 500
? err.status : 500;
res.status(status).json({ message: "Unable to process request." });
};
app.use(errorHandler);
return app;
}
14 changes: 14 additions & 0 deletions src/requestIds.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { randomInt } from "crypto";

export class RequestIds {
constructor(private next = randomInt(0x10000)) {}

allocate(pending: ReadonlyMap<string, unknown>): string | undefined {
for (let checked = 0; checked < 0x10000; checked++) {
const id = this.next.toString(16).padStart(4, "0");
this.next = (this.next + 1) & 0xffff;
if (!pending.has(id)) return id;
}
return undefined;
}
}
Loading
Loading