ember-router 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -119,21 +119,24 @@ ember-router decode < capture.bin
119
119
 
120
120
  ### Node.js socket client
121
121
 
122
- `encodePacket(packet)` converts a packet to send into bytes. `decodePacket(bytes)` converts one received packet to a JSON-shaped object. Use `decodePackets(socket)` to decode received packets from a stream.
122
+ Connect to a running `ember-router run --socket` instance from Node.js:
123
123
 
124
124
  ```js
125
- import { createConnection } from 'node:net';
126
- import { decodePackets, encodePacket } from 'ember-router';
125
+ import { createRouterClient } from 'ember-router/client';
127
126
 
128
- const socket = createConnection('/path/to/private/ember-router.sock');
129
- socket.write(encodePacket({ destination: 4660, clusterId: 513, payload: '1001001200' }));
130
- for await (const reply of decodePackets(socket)) {
127
+ const router = createRouterClient('/path/to/private/ember-router.sock', { timeout: 30_000 });
128
+ try {
129
+ const reply = await router.request({ destination: 4660, clusterId: 513, payload: '1001001200' });
131
130
  console.log(reply);
132
- socket.end();
133
- break;
131
+ } finally {
132
+ router.close();
134
133
  }
135
134
  ```
136
135
 
136
+ Requests share a connection and run one at a time. The timeout is in milliseconds and defaults to 30 seconds per exchange, starting when the request reaches the front of the queue. A router failure, timeout, or disconnect rejects the request. After a lost connection, the next request reconnects. A Zigbee error response is returned as a packet, so inspect its ZCL status when needed.
137
+
138
+ The package root exports the packet helpers. `encodePacket(packet)` produces request bytes, `decodePacket(bytes)` decodes one received packet, and `decodePackets(stream)` decodes a stream of packets.
139
+
137
140
  ### Read an attribute
138
141
 
139
142
  Read the occupied heating setpoint (`0x0012`) from short address `0x1234`, endpoint `1`, profile `0x0104`, and cluster `0x0201`.
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "ember-router",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "description": "ZigBee router CLI for EmberZNet-based adapters using ember-zli and zigbee-herdsman",
5
5
  "type": "module",
6
6
  "bin": "./index.js",
7
- "exports": "./packet.js",
7
+ "exports": {
8
+ ".": "./packet.js",
9
+ "./client": "./router-client.js"
10
+ },
8
11
  "files": [
9
12
  "*.js",
10
13
  "!.yarn/**"
@@ -0,0 +1,61 @@
1
+ import { createConnection } from "node:net";
2
+ import { decodePackets, encodePacket } from "./packet.js";
3
+
4
+ export function createRouterClient(path, { timeout = 30_000 } = {}) {
5
+ if (typeof path !== "string" || !path || path.includes("\0")) {
6
+ throw new TypeError("Expected a local socket or named pipe path.");
7
+ }
8
+ if (!Number.isInteger(timeout) || timeout < 0) {
9
+ throw new RangeError("timeout must be a positive integer.");
10
+ }
11
+
12
+ let connection;
13
+ let closed = false;
14
+ let pending = Promise.resolve();
15
+
16
+ async function exchange(bytes) {
17
+ if (closed) {
18
+ throw new Error("Router client is closed.");
19
+ }
20
+ if (!connection || connection.socket.destroyed || connection.socket.readableEnded) {
21
+ const socket = createConnection({ path });
22
+ // the decoder observes errors during exchanges. handle idle socket errors too
23
+ socket.on("error", () => {});
24
+ connection = { socket, replies: decodePackets(socket) };
25
+ }
26
+
27
+ const { socket, replies } = connection;
28
+ const deadline = setTimeout(() => socket.destroy(new Error("Timed out waiting for the router reply.")), timeout);
29
+ try {
30
+ socket.write(bytes);
31
+ const { done, value } = await replies.next();
32
+ if (done) {
33
+ throw new Error("Router disconnected before replying.");
34
+ }
35
+ return value;
36
+ } catch (error) {
37
+ socket.destroy();
38
+ throw error;
39
+ } finally {
40
+ clearTimeout(deadline);
41
+ }
42
+ }
43
+
44
+ return {
45
+ async request(packet) {
46
+ const bytes = encodePacket(packet);
47
+ // the socket protocol matches replies to requests by order
48
+ const result = pending.then(() => exchange(bytes));
49
+ pending = result.catch(() => {});
50
+ const reply = await result;
51
+ if (reply === null) {
52
+ throw new Error("Router could not complete the Zigbee request.");
53
+ }
54
+ return reply;
55
+ },
56
+ close() {
57
+ closed = true;
58
+ connection?.socket.destroy();
59
+ },
60
+ };
61
+ }