Skip to content

Commit ea72cfd

Browse files
stefanrammostefanrammo
authored
Add proxy protocol support for CDP 5.1+ (#22)
Enable single WebSocket connection to access multiple CDP applications via ServiceMessage tunneling (compatVersion >= 4). Key features: - ServicesRequest/ServicesNotification for proxy service discovery - ServiceMessage tunneling (eConnect, eConnected, eData, eDisconnect, eError) - Send buffering to prevent race conditions before eConnected - Dynamic sibling discovery via subscribeToStructure - Client-level structure subscriptions for app ADD/REMOVE notifications - 30-second connect timeout with automatic cleanup - Graceful cleanup on primary connection close Also: - Update studioapi.proto.js with service message types - Add README proxy example - Add Jest tests and GitHub Actions CI
1 parent b88174a commit ea72cfd

17 files changed

Lines changed: 9735 additions & 409 deletions

‎.github/workflows/test.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [main, master]
6+
pull_request:
7+
branches: [main, master]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18, 20, 22]
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Use Node.js ${{ matrix.node-version }}
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: ${{ matrix.node-version }}
24+
cache: 'npm'
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Run tests
30+
run: npm test

‎README.rst‎

Lines changed: 76 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,55 @@ Installation
1212

1313
$ npm install cdp-client
1414

15+
Example
16+
-------
17+
18+
.. code:: javascript
19+
20+
const studio = require("cdp-client");
21+
22+
const client = new studio.api.Client("127.0.0.1:7690", {
23+
credentialsRequested: async (request) => {
24+
return { Username: "cdpuser", Password: "cdpuser" };
25+
}
26+
});
27+
28+
function subscribeToApp(appName) {
29+
client.find(appName + '.CPULoad').then(node => {
30+
node.subscribeToValues(value => {
31+
console.log(`[${appName}] CPULoad: ${value}`);
32+
});
33+
}).catch(() => {}); // Not all apps have CPULoad
34+
}
35+
36+
client.root().then(root => {
37+
root.forEachChild(app => subscribeToApp(app.name()));
38+
root.subscribeToStructure((name, change) => {
39+
if (change === studio.api.structure.ADD)
40+
subscribeToApp(name);
41+
});
42+
}).catch(err => console.error("Connection failed:", err));
43+
44+
Proxy Support (CDP 5.1+)
45+
------------------------
46+
47+
CDP 5.1 introduced proxy support which allows a single WebSocket connection to access
48+
multiple backend CDP applications through multiplexing. In older CDP versions, the client
49+
connected directly to each CDP application, meaning a dedicated port had to be opened for
50+
each application.
51+
52+
When connecting to a CDP 5.1+ application configured as a proxy, the client automatically
53+
discovers and connects to all backend applications. All discovered applications appear as
54+
children of the root system node, enabling transparent access to their structure and values
55+
through the standard API. The example above works the same whether the server has proxy
56+
support or not.
57+
58+
Benefits
59+
~~~~~~~~
60+
61+
- Simplified firewall configuration - only one port needs to be opened
62+
- SSH port forwarding - forward a single port to access entire CDP system
63+
1564
API
1665
---
1766

@@ -303,6 +352,20 @@ client.find(path)
303352
// use the load object referring to CPULoad in MyApp
304353
});
305354
355+
client.close()
356+
^^^^^^^^^^^^^^
357+
358+
- Usage
359+
360+
Close all connections managed by this client. This stops reconnection attempts
361+
and cleans up all resources. Call this when you are done using the client.
362+
363+
- Example
364+
365+
.. code:: javascript
366+
367+
client.close();
368+
306369
Instance Methods / INode
307370
~~~~~~~~~~~~~~~~~~~~~~~~
308371

@@ -334,11 +397,11 @@ node.info()
334397
+------------------+------------------------------+---------------------------------------------------------------+
335398
| Property | Type | Description |
336399
+==================+==============================+===============================================================+
337-
| Info.node_id | number | Application wide unique ID for each instance in CDP structure |
400+
| Info.nodeId | number | Application wide unique ID for each instance in CDP structure |
338401
+------------------+------------------------------+---------------------------------------------------------------+
339402
| Info.name | string | Nodes short name |
340403
+------------------+------------------------------+---------------------------------------------------------------+
341-
| Info.node_type | studio.protocol.CDPNodeType | | Direct CDP base type of the class. One of the following: |
404+
| Info.nodeType | studio.protocol.CDPNodeType | | Direct CDP base type of the class. One of the following: |
342405
| | | - CDP_UNDEFINED |
343406
| | | - CDP_APPLICATION |
344407
| | | - CDP_COMPONENT |
@@ -351,7 +414,7 @@ node.info()
351414
| | | - CDP_OPERATOR |
352415
| | | - CDP_NODE |
353416
+------------------+------------------------------+---------------------------------------------------------------+
354-
| Info.value_type | studio.protocol.CDPValueType | | Optional: Value primitive type the node holds |
417+
| Info.valueType | studio.protocol.CDPValueType | | Optional: Value primitive type the node holds |
355418
| | | | if node may hold a value. One of the following: |
356419
| | | - eUNDEFINED |
357420
| | | - eDOUBLE |
@@ -367,15 +430,15 @@ node.info()
367430
| | | - eBOOL |
368431
| | | - eSTRING |
369432
+------------------+------------------------------+---------------------------------------------------------------+
370-
| Info.type_name | string | Optional: Class name of the reflected node |
433+
| Info.typeName | string | Optional: Class name of the reflected node |
371434
+------------------+------------------------------+---------------------------------------------------------------+
372-
| Info.server_addr | string | Optional: StudioAPI IP present on application nodes that |
373-
| | | have **Info.is_local == false** |
435+
| Info.serverAddr | string | Optional: StudioAPI IP present on application nodes that |
436+
| | | have **Info.isLocal == false** |
374437
+------------------+------------------------------+---------------------------------------------------------------+
375-
| Info.server_port | number | Optional: StudioAPI Port present on application nodes that |
376-
| | | have **Info.is_local == false** |
438+
| Info.serverPort | number | Optional: StudioAPI Port present on application nodes that |
439+
| | | have **Info.isLocal == false** |
377440
+------------------+------------------------------+---------------------------------------------------------------+
378-
| Info.is_local | boolean | Optional: When multiple applications are present in root node |
441+
| Info.isLocal | boolean | Optional: When multiple applications are present in root node |
379442
| | | this flag is set to true for the application that the client |
380443
| | | is connected to |
381444
+------------------+------------------------------+---------------------------------------------------------------+
@@ -435,7 +498,7 @@ node.forEachChild(iteratorCallback)
435498
.. code:: javascript
436499
437500
cdpapp.forEachChild(function (child) {
438-
if (child.info().node_type == studio.protocol.CDPNodeType.CDP_COMPONENT) {
501+
if (child.info().nodeType == studio.protocol.CDPNodeType.CDP_COMPONENT) {
439502
// Use child object of type {INode} that is a CDP component.
440503
}
441504
});
@@ -477,7 +540,7 @@ node.subscribeToValues(valueConsumer, fs, sampleRate)
477540
- Usage
478541

479542
Subscribe to value changes on this node. On each value change valueConsumer function is called
480-
with value of the nodes value_type and UTC Unix timestamp in nanoseconds (nanoseconds from 01.01.1970).
543+
with value of the nodes valueType and UTC Unix timestamp in nanoseconds (nanoseconds from 01.01.1970).
481544
Timestamp refers to the time of value change in connected application on target controller.
482545

483546
- Example
@@ -579,7 +642,7 @@ node.subscribeToEvents(eventConsumer, timestampFrom)
579642
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+
580643
| Event.code | studio.protocol.EventCode | Optional: Event code flags. Any of: |
581644
| | +-----------------------------+---------------------------------------------------------------------------------------------+
582-
| | | - eAlarmSet | The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" |
645+
| | | - aAlarmSet | The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" |
583646
| | +-----------------------------+---------------------------------------------------------------------------------------------+
584647
| | | - eAlarmClr | The alarm's Set flag was cleared. The Unack state is unchanged. |
585648
| | +-----------------------------+---------------------------------------------------------------------------------------------+
@@ -591,7 +654,7 @@ node.subscribeToEvents(eventConsumer, timestampFrom)
591654
| | +-----------------------------+---------------------------------------------------------------------------------------------+
592655
| | | - eNodeBoot | The provider reports that the CDPEventNode just have booted. |
593656
+-------------------+-----------------------------+-----------------------------+---------------------------------------------------------------------------------------------+
594-
| Event.status | studio.protocol.EventStatus | Optional: Value primitive type the node holds if node may hold a value. Any of: |
657+
| Event.status | studio.protocol.EventStatus | Optional: Status flags as a numeric bitfield. Possible flag values: |
595658
| | +-----------------------------+---------------------------------------------------------------------------------------------+
596659
| | | - eStatusOK | No alarm set |
597660
| | +-----------------------------+---------------------------------------------------------------------------------------------+

0 commit comments

Comments
 (0)