@cocreate/socket 0.0.0-stage → 3.0.0

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# CoCreate Socket
+
+Client and server WebSocket interfaces for CoCreate. Send JSON envelopes from browsers or Node.js, route them through application handlers and the server mesh, and relay responses across browser contexts.
+
+---
+
+## Documentation
+
+For complete API references, protocol event schemas, configuration guides, and examples, visit the **[CoCreate Socket Documentation](https://cocreatejs.com/docs/socket)**.
+
+## Table of Contents
+
+- [Documentation](#documentation)
+- [Client and server exports](#client-and-server-exports)
+- [Client usage](#client-usage)
+- [Client routing controls](#client-routing-controls)
+- [Browser-context delivery](#browser-context-delivery)
+- [Connection](#connection)
+- [Socket collection](#socket-collection)
+- [Message routing](#message-routing)
+- [Client and socket selection](#client-and-socket-selection)
+- [Authorization](#authorization)
+- [Server mesh](#server-mesh)
+- [Heartbeat and disconnection](#heartbeat-and-disconnection)
+- [Installation](#installation)
+- [Announcements and roadmap](#announcements-and-roadmap)
+- [About](#about)
+- [Tests](#tests)
+- [How to Contribute](#how-to-contribute)
+- [License](#license)
+
+---
+
+## Client and server exports
+
+This package now contains both implementations under `src/client/` and `src/server/`. Both roles share one package and retain their own transport lifecycle.
+
+```js
+import { SocketServer, SocketClient } from "@cocreate/socket";
+
+// Separate entry points:
+import Server from "@cocreate/socket/server";
+import Client from "@cocreate/socket/client";
+```
+
+The Node entry exports both roles. Browser builds resolve the client entry without loading Node server dependencies. The root default export is SocketClient for compatibility with generated CoCreate dependency loaders. The client retains its existing initialization on import. Use the server entry point to import only the server.
+
+## Client usage
+
+Messages use one envelope. The `method` selects the event or operation and the remaining properties contain its payload.
+
+```js
+import { SocketClient } from "@cocreate/socket";
+
+const response = await SocketClient.send({
+    method: "notification",
+    message: "The workspace was updated",
+    broadcast: false,
+    broadcastClient: true
+});
+```
+
+The socket client automatically supplies connection metadata including `clientId`, `frameId`, `socketId`, `organization_id`, `uuid`, and `timeStamp`.
+
+## Client routing controls
+
+-   `clientId` identifies the browser and is shared by its tabs, windows, and same-origin frames.
+-   `frameId` identifies one client runtime, such as a tab, window, or iframe.
+-   `socketId` identifies an individual WebSocket instance. It is generated for each socket and is not shared through session storage.
+-   `broadcast` controls server delivery. `false` targets the originating or selected client; `true` targets eligible clients in the organization.
+-   `broadcastClient` controls whether a received server message is relayed to the browser's other same-origin contexts.
+-   `broadcastSender: false` prevents the originating frame from firing normal method listeners for the response. The response still returns and resolves its UUID promise.
+
+The socket server sends to one connected socket for each selected `clientId`. If one socket cannot be reached, it can try another socket belonging to that client. Browser-context distribution is then handled by the client when `broadcastClient` is enabled.
+
+## Browser-context delivery
+
+The client stores the complete relay payload in the `localSocketMessages` array of the shared `system` IndexedDB database. The `messageQueue` array uses the same internal database. Records retain `organization_id` for organization-scoped filtering, while application databases remain free of socket transport state. The client writes only the record ID and organization ID to the `localSocketMessage` local-storage key, allowing other contexts to retrieve the message without being constrained by local-storage value limits.
+
+The native `storage` event fires in the other same-origin contexts, not in the context that performed the write. The receiving contexts read the IndexedDB record and fire their local listeners. Each new relay also removes records older than five seconds.
+
+## Connection
+
+Initialize the socket manager with a CoCreate server instance. The server supplies its HTTP and/or HTTPS upgrade source along with optional authentication, authorization, usage, and mesh services.
+
+```js
+import { SocketServer } from "@cocreate/socket";
+
+const wsManager = await SocketServer.init(server);
+server.wsManager = wsManager; // Existing integrations remain supported.
+server.socket = wsManager.collection;
+```
+
+The first WebSocket URL path segment is the `organization_id`. Connection options can be supplied as query parameters or as an encoded JSON WebSocket protocol value. Socket-client supplies `socketId`, `clientId`, client information, user information, and an authentication token.
+
+The server groups each connection as:
+
+```text
+organization_id -> clientId -> socketId -> WebSocket
+```
+
+- `clientId` identifies a browser client and may have multiple connected sockets.
+- `socketId` identifies one WebSocket connection.
+- `frameId` identifies the originating client runtime, but is message metadata rather than a server-side delivery selector.
+
+## Socket collection
+
+CoCreate Server exposes `server.socket` over the existing manager's live indexes and delivery implementation.
+
+```js
+server.socket.get(socketId);             // Original WebSocket object.
+server.socket.set(socketId, { label: "editor" });
+server.socket.size;                      // Live sockets in this process.
+server.socket.send(envelope);
+server.socket.delete(socketId);          // Close and clean up.
+server.socket.clients.get(clientId)?.get(socketId);
+server.socket.organizations.get(organizationId)?.clients.get(clientId);
+server.socket.organizations.get(organizationId)?.subscriptions;
+```
+
+Socket collections support `get`, `has`, `add`, `set`, `delete`, `clear`, `size`, and iteration. `set` updates metadata in place without replacing transport methods, identity, or bookkeeping. It does not create missing sockets.
+
+Client and organization collections support `get`, `has`, `add`, `delete`, `clear`, `size`, and iteration. All `add` methods accept an already authenticated WebSocket with `id`, `clientId`, and `organization_id`, using the existing connection lifecycle. Root `add` returns the socket; client and organization `add` return their corresponding record. Re-adding the same socket is idempotent; conflicting socket IDs are rejected.
+
+Client deletion closes its sockets using the normal organization disconnect grace period. Organization deletion immediately evicts its sockets and presence. Operations preserve the existing `orgConnected` and `orgDisconnected` event flow. `wsManager` remains available for existing integrations.
+
+## Message routing
+
+Messages are JSON objects and must contain `method`. The same envelope is passed through application handlers and returned to clients.
+
+```js
+{
+    method: "notification",
+    message: "The workspace was updated",
+    organization_id: "ORGANIZATION_ID",
+    clientId: "CLIENT_ID",
+    broadcast: false
+}
+```
+
+Incoming envelopes are dispatched as follows:
+
+- `api` envelopes emit the `api` event.
+- CRUD methods beginning with `storage`, `database`, `array`, `index`, or `object` emit their complete method name.
+- `crdt` and `cursor` messages enter `server.send()`.
+- Other messages emit the top-level portion of `method`.
+
+## Client and socket selection
+
+`send(data)` resolves recipients by organization and client:
+
+- `broadcast: true` selects every client in the organization.
+- `socketId` identifies the originating socket and its client.
+- A server-originated direct message can provide `clientId` as one string or an array of strings.
+
+For each selected client, the server attempts its connected sockets in order and stops after the first successful write. The originating socket is tried first for its client, including subscription delivery. Subscription matches select clients, with other sockets for those clients available as fallbacks. A write succeeds only when the WebSocket send callback reports no error. This provides socket failover without sending duplicate copies to every socket belonging to the same browser client.
+
+`broadcastClient` and `broadcastSender` are forwarded to socket-client. Browser-context relaying and originating-frame listener suppression are handled on the client; they do not change socket selection on the server.
+
+## Authorization
+
+When authentication is configured, the connection token is decoded and a successfully authenticated socket receives `socket.user_id`. When authorization is configured, incoming messages are checked before dispatch and outgoing messages are checked once per selected client before a socket write is attempted.
+
+Incoming messages receive trusted `user_id`, `socketId`, `clientId`, `organization_id`, and `host` values from the connection. A `socket` payload field has no transport meaning and is preserved as ordinary application data. Authorization receives the authenticated user separately. `replyOrganizationId` is also stamped by the server so CRUD can restore the connection's reply scope when authorization redirects an operation to platform storage; it is removed from outgoing socket messages.
+
+Activity writes use `log: false`, and records in `activities` do not generate further activity records.
+
+Authorization may reject a message or return an authorized envelope. The authorized envelope becomes the payload delivered to that client.
+
+## Server mesh
+
+Components send responses through `server.send(envelope)`. The coordinator starts
+local `server.socket.send()` delivery, IPC delivery to the organization's workers,
+and primary-owned `server.cluster.send()` forwarding without waiting for the
+local socket loop first. Receiving workers call their local socket transport.
+Socket send does not call server send, so no socket forwarding flag is needed.
+`workerId` and `serverId` identify the origin to prevent duplicate delivery.
+
+Direct `server.socket.send()` delivers only to this process's clients. Its Promise
+resolves to `undefined` after local authorization and write attempts; awaiting it
+does not wait for a client application response. Use `server.send()` for normal
+component responses and cross-worker or peer delivery.
+
+## Heartbeat and disconnection
+
+The server sends WebSocket ping frames every 30 seconds. Connections that do not answer with a pong before the next heartbeat are terminated and removed from the organization, client, socket, and user maps. Reconnection and queued client messages are managed by socket-client rather than buffered by the server.
+
+---
+
+## Installation
+
+### npm
+
+```bash
+npm install @cocreate/socket
+```
+
+### Yarn
+
+```bash
+yarn add @cocreate/socket
+```
+
+---
+
+## Announcements and roadmap
+
+Updates are recorded in [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/CoCreateJS/socket/releases). Follow [issues](https://github.com/CoCreateJS/socket/issues) and [pull requests](https://github.com/CoCreateJS/socket/pulls) for planned work and feedback.
+
+## About
+
+CoCreate Socket is maintained and funded by CoCreate and supported by the CoCreate Developer Experience Team. Contact [develop@CoCreateJS.com](mailto:develop@CoCreateJS.com) with questions. CoCreate names and logos are trademarks of CoCreate, LLC.
+
+## Tests
+
+Tests are grouped by transport role under `test/server/` and `test/client/`.
+
+```bash
+npm test                # Both roles.
+npm run test:server     # Server collections and delivery.
+npm run test:client     # Client indexes and transport round trips.
+```
+
+## How to Contribute
+
+We encourage contributions to all CoCreate libraries. Please see our
+[CONTRIBUTING.md](https://github.com/CoCreateJS/socket/blob/master/CONTRIBUTING.md)
+guide for development workflows and contribution guidelines.
+
+If you discover a bug or would like to request a feature, please open an issue on our
+[GitHub Issues](https://github.com/CoCreateJS/socket/issues)
+tracker.
+
+For complete documentation, examples, and integration guides, visit:
+
+https://cocreatejs.com/docs/socket
+
+---
+
+## License
+
+This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
+
+- **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.
+- **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/demo/server.js

@@ -0,0 +1,24 @@
+'use strict';
+const express = require('express');
+const cors = require('cors')
+const urlencoded = require('body-parser').urlencoded;
+
+const app = express();
+app.use(cors())
+app.use(urlencoded({ extended: false }));
+
+const socketServer = require("@cocreate/socket")
+const wsManager = new socketServer("ws");
+
+const { createServer } = require('http');
+const server = createServer(app);
+server.on('upgrade', function upgrade(request, socket, head) {
+    if (!wsManager.handleUpgrade(request, socket, head)) {
+        socket.destroy();
+    }
+});
+
+const components = require("./components")
+components.init(app, wsManager)
+
+server.listen(process.env.PORT || 3000);

package/docs/index.html

@@ -0,0 +1,217 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>socket Documentation | CoCreateJS</title>
+		<link
+			rel="icon"
+			type="image/png"
+			sizes="32x32"
+			href="https://CoCreateJS.com/images/favicon.ico" />
+		<meta
+			name="description"
+			content="A simple HTML5 and pure javascript component. Easy configuration using data-attributes and highly styleable." />
+		<meta
+			name="keywords"
+			content="helper classes, utility classes, css framework, css library, inline style classes" />
+		<meta name="robots" content="index,follow" />
+
+		<link rel="manifest" href="/manifest.json" />
+	</head>
+
+	<body>
+		<div array="" object="" key="" id="cocreate-socket">
+			<div
+				class="display:flex flex-wrap:wrap justify-content:space-between margin:10px">
+				<div class="display:flex align-items:center">
+					<h2>socket</h2>
+				</div>
+				<div
+					class="display:flex align-items:center font-size:20px"
+					share-height="600"
+					share-width="500"
+					share-media="https://via.placeholder.com/300/09f/fff.png">
+					<a
+						href="https://github.com/CoCreateJS/socket"
+						target="_blank"
+						class="margin-right:15px"
+						><i class="fab fa-github"></i
+					></a>
+					<a
+						class="margin-right:15px share"
+						share-network="twitter"
+						title="Share on twitter"
+						><i class="fab fa-twitter"></i
+					></a>
+					<a
+						class="margin-right:15px share"
+						share-network="facebook"
+						title="Share on Facebook"
+						><i class="fab fa-facebook"></i
+					></a>
+					<a
+						class="margin-right:15px share"
+						share-network="instagram"
+						title="Share on instagram"
+						><i class="fab fa-instagram"></i
+					></a>
+					<a
+						class="margin-right:15px share"
+						share-network="share"
+						title="Share on share"
+						><i class="fas fa-share-alt"></i
+					></a>
+				</div>
+			</div>
+			<p class="max-width:500px margin:20px_10px">
+				A simple HTML5, CSS and pure javascript component. Easy
+				configuration using data-attributes and highly styleable.
+			</p>
+			<div id="socket-section" class="display:flex flex-wrap:wrap">
+				<div
+					class="flex-grow:1 min-width:300px width:50% padding:20px_10px">
+					<h2
+						class="border-bottom:1px_solid_lightgrey padding:5px_0px">
+						Install
+					</h2>
+					<pre
+						class="margin-top:15px"><code class="language-javascript">npm install @cocreate/socket</code></pre>
+					<p class="padding:10px_0px">Or you can use cdn link:</p>
+					<pre><code class="language-javascript">https://cdn.CoCreateJS.com/js/socket.min.js</code></pre>
+
+					<h2
+						class="border-bottom:1px_solid_lightgrey margin-top:20px padding:5px_0px">
+						Usage
+					</h2>
+					<p class="padding:10px_0px">socket usage content</p>
+					<pre><code class="language-html">&lt;div&gt;&lt;/div&gt;</code></pre>
+
+					<h2
+						class="border-bottom:1px_solid_lightgrey margin-top:20px padding:5px_0px">
+						Reference
+					</h2>
+					<p class="padding:10px_0px">
+						This is socket reference content
+					</p>
+					<pre><code class="language-javascript">&lt;div&gt;&lt;/div&gt;</code></pre>
+					<p class="padding:10px_0px">
+						This is socket reference content
+					</p>
+
+					<h2
+						class="border-bottom:1px_solid_lightgrey margin-top:20px padding:5px_0px">
+						Attributes
+					</h2>
+					<ul class="list-style-type:none">
+						<li
+							class="padding:15px_0px border-bottom:1px_solid_lightgrey">
+							<h4>
+								<span>socket</span>
+								<span class="cocreate-badge success"
+									>string</span
+								>
+								<span class="cocreate-badge warning"
+									>optional</span
+								>
+							</h4>
+							<p>socket-attribute</p>
+						</li>
+						<li
+							class="padding:15px_0px border-bottom:1px_solid_lightgrey">
+							<h4>
+								<span>socket</span>
+								<span class="cocreate-badge success"
+									>string</span
+								>
+								<span class="cocreate-badge warning"
+									>optional</span
+								>
+							</h4>
+							<p>socket-attribute</p>
+						</li>
+					</ul>
+				</div>
+
+				<div
+					class="flex-grow:1 min-width:300px width:50% padding:0px_10px margin:20px_0px border-bottom:1px_solid_lightgrey">
+					<!-- SandBox -->
+					<div
+						class="display:flex flex-direction:column position:relative overflow:hidden card border-radius:2px width:auto height:600px margin-top:20px"
+						id="playground">
+						<div
+							id="demo-code"
+							resizable
+							class="position:relative height:50%">
+							<textarea
+								type="code"
+								lang="html"
+								array="demos"
+								object=""
+								key="demo"
+								save="false"
+								id="demo"
+								class="height:100% width:100% outline:none border:none resize:none padding:5px"></textarea>
+							<div
+								resize="bottom"
+								class="background:lightgrey"></div>
+						</div>
+
+						<div
+							id="demo-preview"
+							class="position:relative overflow:auto background-color:white">
+							<div get-value="#demo" class="padding:20px"></div>
+						</div>
+
+						<div
+							class="font-size:20px position:absolute top:10px right:10px opacity:0.6">
+							<a
+								class="margin-right:10px"
+								id="eye"
+								show="#eye-slash"
+								hide="#eye, #demo-preview"
+								toggle="code-height"
+								toggle-query="#demo-code"
+								><i class="far fa-eye"></i
+							></a>
+							<a
+								class="margin-right:10px"
+								hidden
+								id="eye-slash"
+								show="#eye, #demo-preview"
+								hide="#eye-slash"
+								toggle="code-height"
+								toggle-query="#demo-code"
+								><i class="fas fa-eye-slash"></i
+							></a>
+							<a
+								class="margin-right:10px"
+								id="code"
+								show="#code-slash"
+								hide="#code, #demo-code"
+								><i class="fa fa-code"></i
+							></a>
+							<a
+								class="margin-right:10px"
+								hidden
+								id="code-slash"
+								show="#code, #demo-code"
+								hide="#code-slash"
+								><i class="fas fa-code"></i
+							></a>
+							<a
+								class="margin-right:5px"
+								fullscreen
+								target="#playground"
+								><i class="fas fa-expand"></i
+							></a>
+						</div>
+					</div>
+					<!-- End SandBox -->
+				</div>
+			</div>
+		</div>
+		<script src="https://CoCreateJS.com/dist/CoCreate.js"></script>
+	</body>
+</html>

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@cocreate/socket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.0",
+  "description": "Client and server WebSocket interfaces for CoCreate.",
+  "keywords": [
+    "websocket-server",
+    "real-time-collaboration",
+    "multi-tenancy",
+    "state-synchronization",
+    "cluster-mesh",
+    "headless-cms",
+    "low-latency",
+    "p2p-replication",
+    "event-streaming"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "scripts": {
+    "demo": "PORT=5000 node demo/server.js",
+    "test": "node --test",
+    "test:server": "node --test test/server/*.test.js",
+    "test:client": "node --test test/client/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CoCreateJS/socket.git"
+  },
+  "author": "CoCreate LLC",
+  "license": "AGPL-3.0",
+  "bugs": {
+    "url": "https://github.com/CoCreateJS/socket/issues"
+  },
+  "homepage": "https://CoCreateJS.com/docs/socket",
+  "dependencies": {
+    "@cocreate/config": "^2.0.0",
+    "@cocreate/utils": "^2.0.0",
+    "@cocreate/organizations": "^2.0.0",
+    "ws": "^8.21.1"
+  },
+  "exports": {
+    ".": {
+      "browser": "./src/client/index.js",
+      "default": "./src/index.js"
+    },
+    "./server": "./src/server/index.js",
+    "./client": "./src/client/index.js"
+  },
+  "browser": "./src/client/index.js"
+}

package/prettier.config.js

@@ -0,0 +1,16 @@
+module.exports = {
+        tabWidth: 4,
+        semi: true,
+        trailingComma: "none",
+        bracketSameLine: true,
+        useTabs: true,
+        overrides: [
+            {
+                files: ["*.json", "*.yml", "*.yaml"],
+                options: {
+                    tabWidth: 2,
+                    useTabs: false
+                },
+            }
+        ],  
+    };

package/release.config.js

@@ -0,0 +1,30 @@
+export default {
+  dryRun: false,
+  branches: ["main"],
+  plugins: [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        changelogFile: "CHANGELOG.md",
+      },
+    ],
+    "@semantic-release/npm", 
+    [
+      "@semantic-release/github", 
+      {
+        successComment: false,
+        failTitle: false,
+      },
+    ],
+    [
+      "@semantic-release/git", 
+      {
+        // Only stage and commit the changelog and package.json
+        assets: ["CHANGELOG.md", "package.json"],
+        message: "chore(release): ${nextRelease.version} [skip ci]",
+      },
+    ],
+  ],
+};