@cocreate/socket-server 1.33.0 → 1.33.1
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 +136 -37
- package/denotest.json +8 -0
- package/package.json +12 -12
- package/src/index.js +5 -8
package/README.md
CHANGED
|
@@ -1,65 +1,164 @@
|
|
|
1
|
-
# CoCreate
|
|
1
|
+
# CoCreate Socket Server
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A high-performance, multi-tenant WebSocket orchestration layer engineered for real-time collaboration, instant data synchronization, and ultra-low latency event streaming. This module serves as the primary gateway for end-user web applications interacting with the CoCreate clustered network.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
---
|
|
9
6
|
|
|
10
|
-
|
|
7
|
+
## Documentation
|
|
11
8
|
|
|
12
|
-
[CoCreate
|
|
9
|
+
For complete API references, protocol event schemas, configuration guides, and examples, visit the **[CoCreate Socket Server Documentation](https://cocreatejs.com/docs/socket-server)**.
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
## Table of Contents
|
|
15
12
|
|
|
16
|
-
|
|
13
|
+
- [Documentation](#documentation)
|
|
14
|
+
- [The Real-Time Multiplexing Core](#the-real-time-multiplexing-core)
|
|
15
|
+
- [Why CoCreate Socket Server?](#why-cocreate-socket-server)
|
|
16
|
+
- [Multi-Tenant Rooms & Subscriptions](#multi-tenant-rooms--subscriptions)
|
|
17
|
+
- [The Connection Degradation Vector](#the-connection-degradation-vector)
|
|
18
|
+
- [Graceful Reconnection & State Recovery](#graceful-reconnection--state-recovery)
|
|
19
|
+
- [Configuration](#configuration)
|
|
20
|
+
- [Installation](#installation)
|
|
21
|
+
- [How to Contribute](#how-to-contribute)
|
|
22
|
+
- [License](#license)
|
|
17
23
|
|
|
18
|
-
|
|
24
|
+
---
|
|
19
25
|
|
|
20
|
-
-
|
|
21
|
-
- [Announcements](#announcements)
|
|
22
|
-
- [Roadmap](#roadmap)
|
|
23
|
-
- [How to Contribute](#how-to-contribute)
|
|
24
|
-
- [About](#about)
|
|
25
|
-
- [License](#license)
|
|
26
|
+
## The Real-Time Multiplexing Core
|
|
26
27
|
|
|
27
|
-
|
|
28
|
+
`@cocreate/socket-server` manages hundreds of thousands of concurrent persistent client connections with a zero-allocation, stream-oriented architecture.
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
### Native Binary Transport
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
To minimize serialization overhead and avoid high CPU usage, all real-time payloads can be encoded natively as binary streams using protocol buffers or compact JSON-in-MsgPack formats. This reduces network payload size by up to 60% compared to raw stringified JSON payloads.
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
### Organization & Room Isolation
|
|
34
35
|
|
|
35
|
-
|
|
36
|
+
Sockets are automatically classified upon connection based on authenticated organization context. Client connections can only subscribe to channels matching their tenant scopes, keeping data partitions strict and secure at the gateway edge.
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
$$
|
|
39
|
+
\text{Client Connection Request}
|
|
40
|
+
\xrightarrow{\text{JWT Authentication}}
|
|
41
|
+
\text{Isolated Tenant Context}
|
|
42
|
+
\implies
|
|
43
|
+
\begin{cases}
|
|
44
|
+
\text{Room 1} & \text{(Document Sync)} \\
|
|
45
|
+
\text{Room 2} & \text{(Presence Engine)}
|
|
46
|
+
\end{cases}
|
|
47
|
+
$$
|
|
38
48
|
|
|
39
|
-
|
|
49
|
+
```text
|
|
50
|
+
[Client App] ──► [WebSocket Connection] ──► [Socket Server Edge] ──► [Tenant Context Mapping]
|
|
51
|
+
│
|
|
52
|
+
▼
|
|
53
|
+
[Enforced Privacy]
|
|
54
|
+
```
|
|
40
55
|
|
|
41
|
-
|
|
56
|
+
---
|
|
42
57
|
|
|
43
|
-
|
|
58
|
+
## Why CoCreate Socket Server?
|
|
44
59
|
|
|
45
|
-
|
|
60
|
+
Standard real-time libraries (such as Socket.IO) introduce protocol wrapping overhead and maintain relatively heavy memory footprints per client, limiting total connection density on typical hardware.
|
|
46
61
|
|
|
47
|
-
|
|
62
|
+
`@cocreate/socket-server` is built on top of high-performance, low-level engine bindings, ensuring near-native socket operations. It tracks user presence, real-time collaboration, and administrative events with minimal overhead, allowing a single server instance to support tens of thousands of concurrent active connections.
|
|
48
63
|
|
|
49
|
-
|
|
64
|
+
---
|
|
50
65
|
|
|
51
|
-
|
|
66
|
+
## Multi-Tenant Rooms & Subscriptions
|
|
52
67
|
|
|
53
|
-
|
|
68
|
+
The socket server divides message distributions into isolated communication layers.
|
|
54
69
|
|
|
55
|
-
|
|
70
|
+
| Channel Scope | Delivery Mechanism | Common Use Case |
|
|
71
|
+
| --- | --- | --- |
|
|
72
|
+
| **Organization Room** | Broadcast across tenant nodes | System announcements and configuration synchronization. |
|
|
73
|
+
| **Document Room** | Focused cluster routing | Real-time collaboration, cursor synchronization, and document updates. |
|
|
74
|
+
| **User Direct Channel** | Unicast targeted messaging | Personal notifications and account-specific events. |
|
|
75
|
+
| **Mesh Control Tunnel** | Internal inter-server communication | Administrative coordination and node draining. |
|
|
56
76
|
|
|
57
|
-
|
|
77
|
+
---
|
|
58
78
|
|
|
59
|
-
|
|
79
|
+
## The Connection Degradation Vector
|
|
80
|
+
|
|
81
|
+
To help `@cocreate/server-telemetry` evaluate worker saturation, the socket server continuously tracks local connection density ($D_c$).
|
|
82
|
+
|
|
83
|
+
$$
|
|
84
|
+
D_c =
|
|
85
|
+
\frac{\text{Active Sockets}}
|
|
86
|
+
{\text{Max Node Capacity}}
|
|
87
|
+
\cdot
|
|
88
|
+
\ln(\text{Messages Per Second}+1)
|
|
89
|
+
$$
|
|
90
|
+
|
|
91
|
+
As connection density approaches configured limits, the socket server notifies the surrounding infrastructure so new client connections can be routed toward healthier nodes.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Graceful Reconnection & State Recovery
|
|
96
|
+
|
|
97
|
+
Temporary network interruptions should not interrupt collaboration.
|
|
98
|
+
|
|
99
|
+
When a client disconnects unexpectedly, its session is placed into a short-lived recovery state. Outbound events are temporarily buffered in memory. If the client reconnects with its session identifier before the recovery window expires, pending events are replayed and synchronization continues without requiring the application to rebuild state.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Configuration
|
|
104
|
+
|
|
105
|
+
Create a `socket.config.json` file in your server root directory.
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"port": 8080,
|
|
110
|
+
"maxConnections": 50000,
|
|
111
|
+
"pingIntervalMs": 25000,
|
|
112
|
+
"pingTimeoutMs": 5000,
|
|
113
|
+
"maxPayloadBytes": 1048576,
|
|
114
|
+
"compression": {
|
|
115
|
+
"enabled": true,
|
|
116
|
+
"thresholdBytes": 1024
|
|
117
|
+
},
|
|
118
|
+
"security": {
|
|
119
|
+
"requireAuth": true,
|
|
120
|
+
"authTimeoutMs": 5000
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
60
126
|
|
|
61
|
-
|
|
127
|
+
## Installation
|
|
62
128
|
|
|
63
|
-
|
|
129
|
+
### npm
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
npm install @cocreate/socket-server
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Yarn
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
yarn add @cocreate/socket-server
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## How to Contribute
|
|
144
|
+
|
|
145
|
+
We encourage contributions to all CoCreate libraries. Please see our
|
|
146
|
+
[CONTRIBUTING.md](https://github.com/CoCreate-app/CoCreate-socket-server/blob/master/CONTRIBUTING.md)
|
|
147
|
+
guide for development workflows and contribution guidelines.
|
|
148
|
+
|
|
149
|
+
If you discover a bug or would like to request a feature, please open an issue on our
|
|
150
|
+
[GitHub Issues](https://github.com/CoCreate-app/CoCreate-socket-server/issues)
|
|
151
|
+
tracker.
|
|
152
|
+
|
|
153
|
+
For complete documentation, examples, and integration guides, visit:
|
|
154
|
+
|
|
155
|
+
https://cocreatejs.com/docs/socket-server
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## License
|
|
160
|
+
|
|
161
|
+
This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
|
|
64
162
|
|
|
65
|
-
|
|
163
|
+
- **Open Source Use:** For open-source projects and non-commercial use, this software is available under the AGPLv3. See the LICENSE file for the complete license text.
|
|
164
|
+
- **Commercial Use:** Commercial users must obtain a commercial license. Commercial licenses are available when signing up for an API key through the CoCreate platform.
|
package/denotest.json
ADDED
package/package.json
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cocreate/socket-server",
|
|
3
|
-
"version": "1.33.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.33.1",
|
|
4
|
+
"description": "High-density multi-tenant WebSocket orchestration server for real-time state synchronization and cluster-mesh collaboration.",
|
|
5
5
|
"keywords": [
|
|
6
|
-
"
|
|
7
|
-
"
|
|
8
|
-
"
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"
|
|
13
|
-
"
|
|
6
|
+
"websocket-server",
|
|
7
|
+
"real-time-collaboration",
|
|
8
|
+
"multi-tenancy",
|
|
9
|
+
"state-synchronization",
|
|
10
|
+
"cluster-mesh",
|
|
11
|
+
"headless-cms",
|
|
12
|
+
"low-latency",
|
|
13
|
+
"p2p-replication",
|
|
14
|
+
"event-streaming"
|
|
14
15
|
],
|
|
15
16
|
"publishConfig": {
|
|
16
17
|
"access": "public"
|
|
@@ -34,7 +35,6 @@
|
|
|
34
35
|
"dependencies": {
|
|
35
36
|
"@cocreate/config": "^1.13.4",
|
|
36
37
|
"@cocreate/utils": "^1.42.2",
|
|
37
|
-
"
|
|
38
|
-
"ws": "^8.21.0"
|
|
38
|
+
"ws": "^8.21.1"
|
|
39
39
|
}
|
|
40
40
|
}
|
package/src/index.js
CHANGED
|
@@ -21,13 +21,9 @@
|
|
|
21
21
|
// For details, visit <https://cocreate.app/licenses/> or contact us at sales@cocreate.app.
|
|
22
22
|
|
|
23
23
|
import { EventEmitter } from 'node:events';
|
|
24
|
-
import
|
|
25
|
-
|
|
26
|
-
// Robustly fallback across all versions/build environments of ws (CJS vs ESM wrappers)
|
|
27
|
-
const WebSocketServer = ws.Server || ws.WebSocketServer;
|
|
28
|
-
|
|
24
|
+
import { WebSocketServer } from 'ws';
|
|
29
25
|
import { URL } from 'node:url';
|
|
30
|
-
import
|
|
26
|
+
import { uuid } from '@cocreate/utils';
|
|
31
27
|
import config from '@cocreate/config';
|
|
32
28
|
|
|
33
29
|
export class SocketServer extends EventEmitter {
|
|
@@ -36,7 +32,7 @@ export class SocketServer extends EventEmitter {
|
|
|
36
32
|
|
|
37
33
|
// Cache reference to primary server process manager - Must be defined
|
|
38
34
|
this.server = server;
|
|
39
|
-
this.serverId =
|
|
35
|
+
this.serverId = uuid(12);
|
|
40
36
|
|
|
41
37
|
// Dynamic reference tracking context bound to our cluster process topology
|
|
42
38
|
this.workerId = server.workerId;
|
|
@@ -51,7 +47,7 @@ export class SocketServer extends EventEmitter {
|
|
|
51
47
|
this.authenticate = server.authenticate;
|
|
52
48
|
this.authorize = server.authorize;
|
|
53
49
|
|
|
54
|
-
config({ organization_id: { prompt: "Enter your organization_id: " } });
|
|
50
|
+
config.request({ organization_id: { prompt: "Enter your organization_id: " } });
|
|
55
51
|
|
|
56
52
|
this.wss = new WebSocketServer({ noServer: true });
|
|
57
53
|
|
|
@@ -164,6 +160,7 @@ export class SocketServer extends EventEmitter {
|
|
|
164
160
|
socket.organization_id = organization_id;
|
|
165
161
|
socket.id = options.socketId;
|
|
166
162
|
socket.clientId = options.clientId;
|
|
163
|
+
socket.clientInfo = options.clientInfo;
|
|
167
164
|
socket.pathname = request.url;
|
|
168
165
|
socket.origin = request.headers.origin;
|
|
169
166
|
socket.host = request.headers.host;
|