@cocreate/server 1.6.1 → 1.6.2

package/README.md

@@ -1,98 +1,478 @@
-# CoCreate-server
+# CoCreate Server
 
-CoCreate-server is a dynamic SSL certificate manager that simplifies the process of managing and generating SSL certificates for your web applications. It supports both proxy servers like NGINX and Node.js SSL termination, making it a versatile tool for securing your connections.
+A secure, stateless, clustered headless server built for high-performance multi-tenancy, real-time collaboration, dynamic process orchestration, and distributed mesh execution. This module serves as the primary orchestrator of the CoCreate ecosystem.
 
-![minified](https://img.badgesize.io/https://cdn.cocreate.app/server/latest/CoCreate-server.min.js?style=flat-square&label=minified&color=orange)
-![gzip](https://img.badgesize.io/https://cdn.cocreate.app/server/latest/CoCreate-server.min.js?compression=gzip&style=flat-square&label=gzip&color=yellow)
-![brotli](https://img.badgesize.io/https://cdn.cocreate.app/server/latest/CoCreate-server.min.js?compression=brotli&style=flat-square&label=brotli)
-![GitHub latest release](https://img.shields.io/github/v/release/CoCreate-app/CoCreate-server?style=flat-square)
-![License](https://img.shields.io/github/license/CoCreate-app/CoCreate-server?style=flat-square)
-![Hiring](https://img.shields.io/static/v1?style=flat-square&label=&message=Hiring&color=blueviolet)
+---
 
-## Features
+## Documentation
 
--   **Dynamic SSL Management:** Automatically manages and renews SSL certificates.
--   **Proxy Support:** Designed to work with popular proxy servers like NGINX.
--   **Fallback to Node.js:** Can also terminate SSL directly in Node.js for environments without a proxy.
--   **ACME Protocol Integration:** Utilizes ACME to automate the certificate issuance process.
+For a complete guide, deployment examples, and API reference, visit the **CoCreate Server Documentation**.
 
-![CoCreate-server](https://cdn.cocreate.app/docs/CoCreate-server.gif)
+## Table of Contents
 
-## [Docs & Demo](https://cocreate.app/docs/server)
+- [Architectural Overview & Core Design](#architectural-overview--core-design)
+- [Core Server Modules](#core-server-modules)
+- [Component Mesh Architecture](#component-mesh-architecture)
+- [Programmatic API Reference](#programmatic-api-reference)
+- [Ingress & Connection Controls](#ingress--connection-controls)
+- [Process & OS Lifecycle Management](#process--os-lifecycle-management)
+- [IPC Transport Engine](#ipc-transport-engine)
+- [Reactive Cluster Storage Manager](#reactive-cluster-storage-manager)
+- [Distributed Cluster Orchestration](#distributed-cluster-orchestration)
+- [Targeting Matrix & Routing Directives](#targeting-matrix--routing-directives)
+- [Self-Healing & Jittered Reconnection Logic](#self-healing--jittered-reconnection-logic)
+- [Dynamic Tenant Eviction & Cascading Teardown Sequence](#dynamic-tenant-eviction--cascading-teardown-sequence)
+- [Security-Hardened Design](#security-hardened-design)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Announcements](#announcements)
+- [Roadmap](#roadmap)
+- [How to Contribute](#how-to-contribute)
+- [About](#about)
+- [License](#license)
 
-For a complete guide and working demo refer to the [doumentation](https://cocreate.app/docs/server)
+---
 
-## CDN
+## Architectural Overview & Core Design
 
-```html
-<script src="https://cdn.cocreate.app/server/latest/CoCreate-server.min.js"></script>
+`@cocreate/server` is engineered to run stateless, highly available workloads across multi-core systems and distributed cloud infrastructure.
+
+### Clustered IPC Architecture
+
+The server operates a single **Primary** process that forks and manages worker processes across CPU cores.
+
+The Primary process is responsible for:
+
+- Cluster orchestration
+- Worker lifecycle management
+- Fallback HTTP/HTTPS listeners
+- Inter-process communication (IPC)
+
+Each Worker runs an identical application stack handling:
+
+- HTTP requests
+- WebSocket connections
+- API routing
+- Database operations
+- Static asset delivery
+
+$$
+\text{Primary Process}
+\xrightarrow{\text{Native IPC}}
+\begin{cases}
+\text{Worker 1}\\
+\text{Worker 2}\\
+\vdots\\
+\text{Worker N}
+\end{cases}
+$$
+
+### Zero Dependency Core
+
+The server minimizes startup time, memory usage, and supply-chain risk by maintaining a lightweight dependency footprint while composing functionality through CoCreate modules.
+
+### Automatic Fallback & Cordoning
+
+When every worker enters draining or cordoned mode, the Primary process automatically serves HTTP **307 Temporary Redirect** responses so incoming requests can immediately reconnect through external load balancers without downtime.
+
+---
+
+## Core Server Modules
+
+| Module | Purpose |
+| --- | --- |
+| `index.js` | Primary server orchestrator |
+| `ipc.js` | Inter-process communication engine |
+| `storage.js` | Cluster-wide reactive storage |
+| `getInfrastructure.js` | Infrastructure detection |
+| `getIp.js` | Public and private IP resolution |
+
+---
+
+## Component Mesh Architecture
+
+The server composes multiple standalone CoCreate modules into a unified runtime.
+
+| Module | Responsibility |
+| --- | --- |
+| `@cocreate/acme` | TLS certificate management |
+| `@cocreate/socket-server` | WebSocket server |
+| `@cocreate/server-mesh` | Cluster communication |
+| `@cocreate/crud-server` | Database routing |
+| `@cocreate/server-autoscaler` | Automatic scaling |
+| `@cocreate/server-telemetry` | Monitoring and metrics |
+| `@cocreate/api` | Dynamic API execution |
+| `@cocreate/file-server` | Static file serving |
+| `@cocreate/lazy-loader` | Lazy loading and webhooks |
+
+---
+
+## Programmatic API Reference
+
+Every server instance extends Node.js `EventEmitter`.
+
+### Instance Properties
+
+| Property | Description |
+| --- | --- |
+| `id` | Unique server identifier |
+| `isPrimary` | Indicates Primary process |
+| `workerId` | Worker identifier |
+| `totalWorkers` | Number of workers |
+| `state` | Current server state |
+| `storage` / `store` | Reactive cluster storage |
+| `send()` | IPC message dispatcher |
+
+### Status Events
+
+```javascript
+server.on("status_change", ({ oldStatus, newStatus }) => {
+	console.log(`State changed from ${oldStatus} to ${newStatus}`);
+});
+```
+
+---
+
+## Ingress & Connection Controls
+
+### `server.cordon(value)`
+
+Enable or disable maintenance mode.
+
+```javascript
+server.cordon(true);
+
+server.emit("cordon", {
+	value: true
+});
+
+server.cordon(false);
+```
+
+---
+
+### `server.shed(organizations)`
+
+Drain selected organizations.
+
+```javascript
+server.shed([
+	"org_abc123",
+	"org_xyz789"
+]);
+
+server.shed(false);
+```
+
+---
+
+### `server.drain(value)`
+
+Gracefully disconnect active clients.
+
+```javascript
+server.drain(true);
+
+server.drain(false);
+```
+
+---
+
+## Process & OS Lifecycle Management
+
+### Restart
+
+```javascript
+server.restart();
+
+server.restart({
+	isPrimary: true
+});
+```
+
+Worker restart:
+
+- Drains connections
+- Exits gracefully
+- Primary automatically forks replacement
+
+Primary restart:
+
+- Closes cluster services
+- Exits cleanly
+- System service restarts application
+
+---
+
+### Reboot
+
+```javascript
+server.reboot();
+```
+
+Gracefully reboots the operating system after draining connections.
+
+---
+
+### Shutdown
+
+```javascript
+server.shutdown();
 ```
 
-```html
-<script src="https://cdn.cocreate.app/server/latest/CoCreate-server.min.css"></script>
+Gracefully powers off the machine after draining connections.
+
+---
+
+## IPC Transport Engine
+
+The IPC subsystem synchronizes Primary and Worker processes.
+
+Broadcast:
+
+```javascript
+server.send({
+	method: "custom_worker_event",
+	broadcast: true,
+	data: {
+		status: "ok"
+	}
+});
 ```
 
-## NPM
+Target worker:
 
-```shell
-$ npm i @cocreate/server
+```javascript
+server.send({
+	method: "restart",
+	worker: 2
+});
 ```
 
-## yarn
+Multiple workers:
 
-```shell
-$ yarn install @cocreate/server
+```javascript
+server.send({
+	method: "drain",
+	workers: [1, 3]
+});
 ```
 
-# Table of Contents
+---
+
+## Reactive Cluster Storage Manager
 
--   [Table of Contents](#table-of-contents)
--   [Announcements](#announcements)
--   [Roadmap](#roadmap)
--   [How to Contribute](#how-to-contribute)
--   [About](#about)
--   [License](#license)
+Cluster-wide synchronized key/value storage.
 
-<a name="announcements"></a>
+```javascript
+await server.storage.set(
+	"node_capacity",
+	{
+		availableSlots: 45
+	}
+);
 
-# Announcements
+const capacity =
+	await server.storage.get(
+		"node_capacity"
+	);
 
-All updates to this library are documented in our [CHANGELOG](https://github.com/CoCreate-app/CoCreate-server/blob/master/CHANGELOG.md) and [releases](https://github.com/CoCreate-app/CoCreate-server/releases). You may also subscribe to email for releases and breaking changes.
+const totalKeys =
+	await server.storage.size();
 
-<a name="roadmap"></a>
+await server.storage.delete(
+	"node_capacity"
+);
 
-# Roadmap
+await server.storage.clear();
+```
 
-If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/CoCreate-app/CoCreate-server/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-server/pulls). We would love to hear your feedback.
+Reactive listeners:
+
+```javascript
+server.storage.on(
+	"change:node_capacity",
+	(newValue) => {
+		console.log(newValue);
+	}
+);
+
+server.storage.on(
+	"delete:node_capacity",
+	() => {
+		console.log("Deleted");
+	}
+);
+```
 
-<a name="about"></a>
+---
 
-# About
+## Distributed Cluster Orchestration
+
+Cluster communication is provided by `@cocreate/server-mesh`.
+
+```javascript
+server.mesh.send({
+	method: "mesh.custom_command",
+	server: "server_b_id",
+	data: {
+		key: "value"
+	}
+});
+```
 
-CoCreate-server is guided and supported by the CoCreate Developer Experience Team.
+---
 
-Please Email the Developer Experience Team [here](mailto:develop@cocreate.app) in case of any queries.
+## Targeting Matrix & Routing Directives
 
-CoCreate-server is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.
+| Target | Example |
+| --- | --- |
+| Single server | `{ server: "server_b_id" }` |
+| Multiple servers | `{ server: ["server_b_id","server_c_id"] }` |
+| Worker | `{ server: "server_b_id", worker: 2 }` |
+| Broadcast | `{ broadcast: true }` |
 
-<a name="contribute"></a>
+---
 
-# How to Contribute
+## Self-Healing & Jittered Reconnection Logic
 
-We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/CoCreate-app/CoCreate-server/blob/master/CONTRIBUTING.md) guide for details.
+Peer reconnections use exponential backoff with randomized jitter.
 
-We want this library to be community-driven, and CoCreate led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/CoCreate-app/CoCreate-server/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-server/pulls) or merely upvote or comment on existing issues or pull requests.
+$$
+T_{delay}
+=
+\min
+\left(
+30000,
+1000\times1.5^{attempt}
+\right)
++
+random(500,4500)
+$$
 
-We appreciate your continued support, thank you!
+This prevents reconnect storms after temporary outages.
 
-<a name="license"></a>
+---
 
-# License
+## Dynamic Tenant Eviction & Cascading Teardown Sequence
+
+Tenant lifecycle is driven by active socket connections.
+
+$$
+\text{Client Disconnect}
+\rightarrow
+\text{60 Second Grace Period}
+\rightarrow
+\text{Organization Removed}
+$$
+
+Once the final client disconnects:
+
+1. A 60-second timer begins.
+2. Workers release tenant resources.
+3. Peer servers receive notification.
+4. Database pools, telemetry buffers, and mesh tunnels are released.
+
+---
+
+## Security-Hardened Design
+
+- Mutual TLS encrypted cluster communication
+- Dedicated internal mesh network
+- Automatic UUID generation for distributed tracing
+- Ephemeral TLS certificates managed by `@cocreate/acme`
+
+---
+
+## Installation
+
+### NPM
+
+```bash
+npm install @cocreate/server
+```
+
+### Yarn
+
+```bash
+yarn add @cocreate/server
+```
+
+---
+
+## Quick Start
+
+```javascript
+import CoCreateServer from "@cocreate/server";
+
+async function startServer() {
+	const server =
+		await CoCreateServer.init();
+
+	server.on(
+		"status_change",
+		({ oldStatus, newStatus }) => {
+			console.log(
+				`${oldStatus} -> ${newStatus}`
+			);
+		}
+	);
+}
+
+startServer();
+```
+
+---
+
+## Announcements
+
+Release notes include new features, performance improvements, security updates, and compatibility changes. Follow the repository to stay informed about the latest releases.
+
+---
+
+## Roadmap
+
+Upcoming improvements include:
+
+- Enhanced cluster orchestration
+- Improved process supervision
+- Adaptive worker allocation
+- Expanded telemetry integration
+- Additional deployment adapters
+
+---
+
+## How to Contribute
+
+Community contributions are welcome.
+
+Please review:
+
+- Documentation
+- CONTRIBUTING.md
+- GitHub Issues
+- GitHub Discussions
+
+Bug reports, feature requests, documentation improvements, and pull requests are appreciated.
+
+---
+
+## About
+
+`@cocreate/server` is designed, built, and maintained by the CoCreate Developer Experience Team.
+
+It serves as the core runtime responsible for process orchestration, clustering, networking, module composition, and lifecycle management across the CoCreate platform.
+
+---
+
+## 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. The AGPLv3 allows you to freely use, modify, and distribute this software, provided that all modifications and derivative works are also licensed under the AGPLv3. For the full license text, see the [LICENSE file](https://github.com/CoCreate-app/CoCreate-socket-client/blob/master/LICENSE).
+### Open Source
+
+For open-source projects and non-commercial use, this software is available under the AGPLv3. See the `LICENSE` file for complete license terms.
 
--   **Commercial Use**: For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our [website](https://cocreate.app). This license permits proprietary use and modification of the software without the copyleft requirements of the AGPLv3. It is ideal for integrating this software into proprietary commercial products and applications.
+### Commercial
 
-If you have not purchased a commercial license and intend to use this software for commercial purposes, you are required to sign up for an API key on our website.
+Organizations requiring proprietary use may obtain a commercial license from CoCreate.

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@cocreate/server",
-  "version": "1.6.1",
-  "description": "A dynamic SSL certificate management and generation tool for proxies like NGINX, with a fallback to Node.js SSL termination. It seamlessly integrates HTTP, HTTPS, and ACME protocols to ensure secure, encrypted connections.",
+  "version": "1.6.2",
+  "description": "A secure, stateless, clustered headless server built for high-performance multi-tenancy, real-time collaboration, and sandboxed AST execution.",
   "keywords": [
-    "ssl-certificate-management",
-    "nginx",
-    "nodejs-ssl-termination",
-    "https",
+    "stateless-server",
+    "headless-architecture",
+    "realtime-collaboration",
+    "node-cluster",
+    "clustering-ipc",
+    "ast-flow-engine",
+    "multi-tenancy",
+    "websocket-server",
+    "dynamic-ssl-generation",
     "acme-protocol",
     "secure-connections",
-    "encryption",
-    "dynamic-ssl-generation",
-    "proxy-security",
+    "zero-dependency-policy",
+    "byodb",
+    "orchestration",
     "web-security"
   ],
   "publishConfig": {