Skip to content

Commit 72563f7

Browse files
stefanrammostefanrammo
committed
Add proxy protocol support for CDP 5.1+
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 72563f7

17 files changed

Lines changed: 9732 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: 71 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,50 @@ 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+
client.root().then(root => {
29+
// Subscribe to each app's CPULoad signal
30+
root.forEachChild(app => {
31+
client.find(app.name() + '.CPULoad').then(node => {
32+
node.subscribeToValues(value => {
33+
console.log(`[${app.name()}] CPULoad: ${value}`);
34+
});
35+
});
36+
});
37+
}).catch(err => console.error("Connection failed:", err));
38+
39+
Proxy Support (CDP 5.1+)
40+
------------------------
41+
42+
CDP 5.1 introduced proxy support which allows a single WebSocket connection to access
43+
multiple backend CDP applications through multiplexing. In older CDP versions, the client
44+
connected directly to each CDP application, meaning a dedicated port had to be opened for
45+
each application.
46+
47+
When connecting to a CDP 5.1+ application configured as a proxy, the client automatically
48+
discovers and connects to all backend applications. All discovered applications appear as
49+
children of the root system node, enabling transparent access to their structure and values
50+
through the standard API. The example above works the same whether the server has proxy
51+
support or not.
52+
53+
Benefits
54+
~~~~~~~~
55+
56+
- Simplified firewall configuration - only one port needs to be opened
57+
- SSH port forwarding - forward a single port to access entire CDP system
58+
1559
API
1660
---
1761

@@ -303,6 +347,20 @@ client.find(path)
303347
// use the load object referring to CPULoad in MyApp
304348
});
305349
350+
client.close()
351+
^^^^^^^^^^^^^^
352+
353+
- Usage
354+
355+
Close all connections managed by this client. This stops reconnection attempts
356+
and cleans up all resources. Call this when you are done using the client.
357+
358+
- Example
359+
360+
.. code:: javascript
361+
362+
client.close();
363+
306364
Instance Methods / INode
307365
~~~~~~~~~~~~~~~~~~~~~~~~
308366

@@ -334,11 +392,11 @@ node.info()
334392
+------------------+------------------------------+---------------------------------------------------------------+
335393
| Property | Type | Description |
336394
+==================+==============================+===============================================================+
337-
| Info.node_id | number | Application wide unique ID for each instance in CDP structure |
395+
| Info.nodeId | number | Application wide unique ID for each instance in CDP structure |
338396
+------------------+------------------------------+---------------------------------------------------------------+
339397
| Info.name | string | Nodes short name |
340398
+------------------+------------------------------+---------------------------------------------------------------+
341-
| Info.node_type | studio.protocol.CDPNodeType | | Direct CDP base type of the class. One of the following: |
399+
| Info.nodeType | studio.protocol.CDPNodeType | | Direct CDP base type of the class. One of the following: |
342400
| | | - CDP_UNDEFINED |
343401
| | | - CDP_APPLICATION |
344402
| | | - CDP_COMPONENT |
@@ -351,7 +409,7 @@ node.info()
351409
| | | - CDP_OPERATOR |
352410
| | | - CDP_NODE |
353411
+------------------+------------------------------+---------------------------------------------------------------+
354-
| Info.value_type | studio.protocol.CDPValueType | | Optional: Value primitive type the node holds |
412+
| Info.valueType | studio.protocol.CDPValueType | | Optional: Value primitive type the node holds |
355413
| | | | if node may hold a value. One of the following: |
356414
| | | - eUNDEFINED |
357415
| | | - eDOUBLE |
@@ -367,15 +425,15 @@ node.info()
367425
| | | - eBOOL |
368426
| | | - eSTRING |
369427
+------------------+------------------------------+---------------------------------------------------------------+
370-
| Info.type_name | string | Optional: Class name of the reflected node |
428+
| Info.typeName | string | Optional: Class name of the reflected node |
371429
+------------------+------------------------------+---------------------------------------------------------------+
372-
| Info.server_addr | string | Optional: StudioAPI IP present on application nodes that |
373-
| | | have **Info.is_local == false** |
430+
| Info.serverAddr | string | Optional: StudioAPI IP present on application nodes that |
431+
| | | have **Info.isLocal == false** |
374432
+------------------+------------------------------+---------------------------------------------------------------+
375-
| Info.server_port | number | Optional: StudioAPI Port present on application nodes that |
376-
| | | have **Info.is_local == false** |
433+
| Info.serverPort | number | Optional: StudioAPI Port present on application nodes that |
434+
| | | have **Info.isLocal == false** |
377435
+------------------+------------------------------+---------------------------------------------------------------+
378-
| Info.is_local | boolean | Optional: When multiple applications are present in root node |
436+
| Info.isLocal | boolean | Optional: When multiple applications are present in root node |
379437
| | | this flag is set to true for the application that the client |
380438
| | | is connected to |
381439
+------------------+------------------------------+---------------------------------------------------------------+
@@ -435,7 +493,7 @@ node.forEachChild(iteratorCallback)
435493
.. code:: javascript
436494
437495
cdpapp.forEachChild(function (child) {
438-
if (child.info().node_type == studio.protocol.CDPNodeType.CDP_COMPONENT) {
496+
if (child.info().nodeType == studio.protocol.CDPNodeType.CDP_COMPONENT) {
439497
// Use child object of type {INode} that is a CDP component.
440498
}
441499
});
@@ -477,7 +535,7 @@ node.subscribeToValues(valueConsumer, fs, sampleRate)
477535
- Usage
478536

479537
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).
538+
with value of the nodes valueType and UTC Unix timestamp in nanoseconds (nanoseconds from 01.01.1970).
481539
Timestamp refers to the time of value change in connected application on target controller.
482540

483541
- Example
@@ -579,7 +637,7 @@ node.subscribeToEvents(eventConsumer, timestampFrom)
579637
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------+
580638
| Event.code | studio.protocol.EventCode | Optional: Event code flags. Any of: |
581639
| | +-----------------------------+---------------------------------------------------------------------------------------------+
582-
| | | - eAlarmSet | The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" |
640+
| | | - aAlarmSet | The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" |
583641
| | +-----------------------------+---------------------------------------------------------------------------------------------+
584642
| | | - eAlarmClr | The alarm's Set flag was cleared. The Unack state is unchanged. |
585643
| | +-----------------------------+---------------------------------------------------------------------------------------------+
@@ -591,7 +649,7 @@ node.subscribeToEvents(eventConsumer, timestampFrom)
591649
| | +-----------------------------+---------------------------------------------------------------------------------------------+
592650
| | | - eNodeBoot | The provider reports that the CDPEventNode just have booted. |
593651
+-------------------+-----------------------------+-----------------------------+---------------------------------------------------------------------------------------------+
594-
| Event.status | studio.protocol.EventStatus | Optional: Value primitive type the node holds if node may hold a value. Any of: |
652+
| Event.status | studio.protocol.EventStatus | Optional: Status flags as a numeric bitfield. Possible flag values: |
595653
| | +-----------------------------+---------------------------------------------------------------------------------------------+
596654
| | | - eStatusOK | No alarm set |
597655
| | +-----------------------------+---------------------------------------------------------------------------------------------+

0 commit comments

Comments
 (0)