Add openHabTrigger node by florian-h05 · Pull Request #5 · openhab/openhab-n8n

florian-h05 · 2026-04-20T16:41:46Z

As n8n requires verified nodes to not have any runtime dependencies, I had to implement my own WebSocket client based on Node.js primitives. Node.js introduced a WebSocket client in Node.js 22, but this one doesn't support ignoring invalid TLS certs, sending additional headers etc.

The WebSocket client and its unit tests were generated with Gemini and reviewed and tested myself.

Including tests against a real WebSocket server. Signed-off-by: Florian Hotze <dev@florianhotze.com>

Signed-off-by: Florian Hotze <dev@florianhotze.com>

Copilot

Pull request overview

Adds an openHAB Trigger node to the n8n community package and introduces a small internal WebSocket client (plus Jest-based unit tests) to avoid runtime dependencies while supporting custom headers and optional insecure TLS for local setups.

Changes:

Added openHABTrigger node to listen to openHAB event bus via WebSocket and emit incoming events into workflows.
Introduced a custom WebSocket client (util/ws.ts) with unit tests and Jest configuration.
Updated build/lint/TS configs and packaging metadata to include the new node and util code.

Reviewed changes

Copilot reviewed 10 out of 15 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`util/ws.ts`	New dependency-free WebSocket client used by the trigger node (handshake, framing, ping/pong).
`util/ws.test.ts`	Jest tests for the WebSocket client (plain + TLS, headers, protocols, ping/pong).
`util/openHABApi.ts`	Shared helper to validate credentials/build base URL/source used by trigger and future code.
`nodes/openHABTrigger/openHABTrigger.node.ts`	New trigger node implementation subscribing to openHAB events and applying filters/heartbeat.
`nodes/openHABTrigger/openhab.svg`	Icon asset for the new trigger node.
`package.json`	Registers the trigger node, adds Jest tooling deps, and updates scripts (including asset copying).
`jest.config.js`	Adds Jest/ts-jest configuration and coverage output directory.
`tsconfig.json` / `tsconfig.eslint.json`	Includes `util/**`, adjusts excludes for build vs lint typechecking.
`eslint.config.mjs`	Switches ESLint project file to `tsconfig.eslint.json` and ignores coverage output.
`index.ts`	Exports the new node from the package entrypoint.
`README.md`	Documents the new trigger node usage and output schema.
`.gitignore` / `.eslintrc.json`	Ignores Jest coverage output; removes legacy ESLint config in favor of flat config.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-20T20:13:59Z

+    // Inject Sec-WebSocket-Protocol if requested
+    if (this.options.protocols) {
+      const protocolsStr = Array.isArray(this.options.protocols)
+        ? this.options.protocols.join(', ')
+        : this.options.protocols;
+      request += `Sec-WebSocket-Protocol: ${protocolsStr}\r\n`;
+    }
+
+    if (this.options.headers) {
+      for (const [headerName, headerValue] of Object.entries(this.options.headers)) {
+        request += `${headerName}: ${headerValue}\r\n`;
+      }
+    }


The handshake request is built by string-concatenating protocols and headers values directly into the HTTP header block. If any value contains \r/\n, it can inject additional headers or corrupt the request (request smuggling). Reject or sanitize header names/values and subprotocol strings to disallow CR/LF characters before writing the request.

The WebSocketClient is only used by our own, trusted code. I don't think we have to handle this.

Copilot · 2026-04-20T20:14:00Z

+	const encodedAccessToken = accessToken ? Buffer.from(accessToken).toString('base64').replace(/=*$/, '') : null
+	const subProtocols = encodedAccessToken ? [`org.openhab.ws.accessToken.base64.${encodedAccessToken}`, 'org.openhab.ws.protocol.default'] : [];
+


Sec-WebSocket-Protocol values are defined as HTTP tokens (RFC6455), so the subprotocol string must not contain characters like / or =. Buffer.from(accessToken).toString('base64') can produce + and / (and you only strip =), which can make the handshake fail on stricter servers/proxies. Consider using base64url encoding for the token part (replace +→-, /→_, and strip =) to keep the subprotocol token RFC-compliant.

This code works fine in Main UI for quite some time now:

https://github.com/openhab/openhab-webui/blob/6a86839ab1b94f6e41f74cecf203822c726c870d/bundles/org.openhab.ui/web/src/js/openhab/ws.ts#L126-L132

Signed-off-by: Florian Hotze <dev@florianhotze.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 15 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Florian Hotze <dev@florianhotze.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 15 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-20T22:10:02Z

+  it('should emit error on connection failure', (done) => {
+    const client = new WebSocketClient(`ws://localhost:1`);
+    client.on('error', (err) => {
+      expect(err).toBeDefined();
+      done();
+    });
+    client.connect();
+  });


This test assumes ws://localhost:1 will fail, but port 1 could be open/forwarded in some environments, making the test flaky. Prefer connecting to a guaranteed-unused port (e.g., bind a server to port 0 to obtain an ephemeral port, close it, then connect and assert ECONNREFUSED) or mock net.connect to deterministically trigger an error.

Copilot · 2026-04-20T22:10:02Z

+    }
+  } else {
+    const token = credentials.token as string;
+    if (!token || !token.trim()) {


Credential validation here treats a whitespace-only token as missing (if (!token || !token.trim())), but the existing openHAB node’s request helper only checks if (!token) (see nodes/openHAB/openHAB.node.ts), so the two nodes will behave differently for the same credential edge-case. Consider aligning the validation logic across nodes (or reusing a single shared helper) to avoid inconsistent user experience.

Suggested change

if (!token || !token.trim()) {

if (!token) {

Will be aligned in a follow-up PR.

Signed-off-by: Florian Hotze <dev@florianhotze.com>

florian-h05 changed the title ~~Trigger~~ Implement openHABTrigger node Apr 20, 2026

florian-h05 changed the title ~~Implement openHABTrigger node~~ Add openHABTrigger node Apr 20, 2026

florian-h05 force-pushed the trigger branch 3 times, most recently from 0a3be2b to 46eca56 Compare April 20, 2026 19:53

florian-h05 marked this pull request as ready for review April 20, 2026 19:56

florian-h05 requested a review from a team as a code owner April 20, 2026 19:56

florian-h05 added 6 commits April 20, 2026 22:00

Implement a pure TS WebSocketClient

5e90ac0

Including tests against a real WebSocket server. Signed-off-by: Florian Hotze <dev@florianhotze.com>

Remove obsolete .eslintrc.json

aedf42c

Signed-off-by: Florian Hotze <dev@florianhotze.com>

Add openHABTrigger node

00d5d23

Signed-off-by: Florian Hotze <dev@florianhotze.com>

Update README

c99c980

Signed-off-by: Florian Hotze <dev@florianhotze.com>

openHABApi.ts: Add JSDoc

c750968

Signed-off-by: Florian Hotze <dev@florianhotze.com>

Reorganise README

df50cb8

Signed-off-by: Florian Hotze <dev@florianhotze.com>

florian-h05 force-pushed the trigger branch from daea3d4 to df50cb8 Compare April 20, 2026 20:00

kaikreuzer reviewed Apr 20, 2026

View reviewed changes

Comment thread README.md Outdated

kaikreuzer requested a review from Copilot April 20, 2026 20:09

Copilot started reviewing on behalf of kaikreuzer April 20, 2026 20:09 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Address Copilot review

ecb6be5

Signed-off-by: Florian Hotze <dev@florianhotze.com>

florian-h05 requested a review from Copilot April 20, 2026 21:43

Copilot started reviewing on behalf of florian-h05 April 20, 2026 21:43 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Comment thread util/ws.ts

Comment thread util/ws.ts Outdated

Comment thread nodes/openHABTrigger/openHABTrigger.node.ts

Comment thread util/ws.test.ts Outdated

Comment thread util/openHABApi.ts

Address Copilot review

ac06b73

Signed-off-by: Florian Hotze <dev@florianhotze.com>

florian-h05 requested a review from Copilot April 20, 2026 22:06

Copilot started reviewing on behalf of florian-h05 April 20, 2026 22:06 View session

WS tests: Generate self-signed cert on the fly

9640938

Signed-off-by: Florian Hotze <dev@florianhotze.com>

florian-h05 force-pushed the trigger branch from 53cd072 to 9640938 Compare April 20, 2026 22:08

Copilot AI reviewed Apr 20, 2026

View reviewed changes

florian-h05 changed the title ~~Add openHABTrigger node~~ Add openHabTrigger node Apr 20, 2026

Address Copilot review

fad7d8c

Signed-off-by: Florian Hotze <dev@florianhotze.com>

florian-h05 requested a review from kaikreuzer April 20, 2026 22:15

Run unit tests in CI

d4d4a1f

Signed-off-by: Florian Hotze <dev@florianhotze.com>

		const encodedAccessToken = accessToken ? Buffer.from(accessToken).toString('base64').replace(/=*$/, '') : null
		const subProtocols = encodedAccessToken ? [`org.openhab.ws.accessToken.base64.${encodedAccessToken}`, 'org.openhab.ws.protocol.default'] : [];

Uh oh!

Conversation

florian-h05 commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

florian-h05 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

florian-h05 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

florian-h05 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

florian-h05 commented Apr 20, 2026 •

edited

Loading