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.
For a complete guide, deployment examples, and API reference, visit the CoCreate Server Documentation.
- Architectural Overview & Core Design
- Core Server Modules
- Component Mesh Architecture
- Programmatic API Reference
- Ingress & Connection Controls
- Process & OS Lifecycle Management
- IPC Transport Engine
- Reactive Cluster Storage Manager
- Distributed Cluster Orchestration
- Targeting Matrix & Routing Directives
- Self-Healing & Jittered Reconnection Logic
- Dynamic Tenant Eviction & Cascading Teardown Sequence
- Security-Hardened Design
- Installation
- Quick Start
- Announcements
- Roadmap
- How to Contribute
- About
- License
@cocreate/server is engineered to run stateless, highly available workloads across multi-core systems and distributed cloud infrastructure.
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
The server minimizes startup time, memory usage, and supply-chain risk by maintaining a lightweight dependency footprint while composing functionality through CoCreate modules.
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.
| 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 |
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 |
Every server instance extends Node.js EventEmitter.
| 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 |
server.on("status_change", ({ oldStatus, newStatus }) => {
console.log(`State changed from ${oldStatus} to ${newStatus}`);
});Enable or disable maintenance mode.
server.cordon(true);
server.emit("cordon", {
value: true
});
server.cordon(false);Drain selected organizations.
server.shed([
"org_abc123",
"org_xyz789"
]);
server.shed(false);Gracefully disconnect active clients.
server.drain(true);
server.drain(false);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
server.reboot();Gracefully reboots the operating system after draining connections.
server.shutdown();Gracefully powers off the machine after draining connections.
The IPC subsystem synchronizes Primary and Worker processes.
Broadcast:
server.send({
method: "custom_worker_event",
broadcast: true,
data: {
status: "ok"
}
});Target worker:
server.send({
method: "restart",
worker: 2
});Multiple workers:
server.send({
method: "drain",
workers: [1, 3]
});Cluster-wide synchronized key/value storage.
await server.storage.set(
"node_capacity",
{
availableSlots: 45
}
);
const capacity =
await server.storage.get(
"node_capacity"
);
const totalKeys =
await server.storage.size();
await server.storage.delete(
"node_capacity"
);
await server.storage.clear();Reactive listeners:
server.storage.on(
"change:node_capacity",
(newValue) => {
console.log(newValue);
}
);
server.storage.on(
"delete:node_capacity",
() => {
console.log("Deleted");
}
);Cluster communication is provided by @cocreate/server-mesh.
server.mesh.send({
method: "mesh.custom_command",
server: "server_b_id",
data: {
key: "value"
}
});| 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 } |
Peer reconnections use exponential backoff with randomized jitter.
\min \left( 30000, 1000\times1.5^{attempt} \right) + random(500,4500) $$
This prevents reconnect storms after temporary outages.
Tenant lifecycle is driven by active socket connections.
Once the final client disconnects:
- A 60-second timer begins.
- Workers release tenant resources.
- Peer servers receive notification.
- Database pools, telemetry buffers, and mesh tunnels are released.
- Mutual TLS encrypted cluster communication
- Dedicated internal mesh network
- Automatic UUID generation for distributed tracing
- Ephemeral TLS certificates managed by
@cocreate/acme
npm install @cocreate/serveryarn add @cocreate/serverimport CoCreateServer from "@cocreate/server";
async function startServer() {
const server =
await CoCreateServer.init();
server.on(
"status_change",
({ oldStatus, newStatus }) => {
console.log(
`${oldStatus} -> ${newStatus}`
);
}
);
}
startServer();Release notes include new features, performance improvements, security updates, and compatibility changes. Follow the repository to stay informed about the latest releases.
Upcoming improvements include:
- Enhanced cluster orchestration
- Improved process supervision
- Adaptive worker allocation
- Expanded telemetry integration
- Additional deployment adapters
Community contributions are welcome.
Please review:
- Documentation
- CONTRIBUTING.md
- GitHub Issues
- GitHub Discussions
Bug reports, feature requests, documentation improvements, and pull requests are appreciated.
@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.
This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
For open-source projects and non-commercial use, this software is available under the AGPLv3. See the LICENSE file for complete license terms.
Organizations requiring proprietary use may obtain a commercial license from CoCreate.