CoCreate Server Autoscaler

A decentralized, self-healing, and autonomous cluster lifecycle manager designed for high-performance multi-tenant ecosystems. Driven directly by real-time telemetry metrics, this module orchestrates vertical and horizontal scaling across top cloud providers using a peer-to-peer, masterless replication model.

---

Documentation

For advanced cloud provider configurations, identity IAM role policies, and threshold triggers, refer to the CoCreate Server Autoscaler Documentation.

Table of Contents

• The Masterless Replicating Node Architecture
• Why CoCreate Server Autoscaler?
• Vertical & Horizontal Multi-Cloud Adaptability
• Self-Healing & Telemetry-Driven Lifecycle
• Cooperative Draining & Scale-Down Sequence
• Configuration
• Installation
• Announcements
• Roadmap
• How to Contribute
• About

---

The Masterless Replicating Node Architecture

Traditional autoscaling relies on a centralized coordinator or a dedicated third-party master server (like a Kubernetes Control Plane or a custom Orchestrator VM) to monitor worker health and issue creation commands. If that master node crashes, the entire cluster's scaling capabilities freeze.

@cocreate/autoscaler implements a Decentralized, Peer-to-Peer (P2P) Replication Model:

• Every Node is Both Master and Worker: There are no specialized roles. Each node independently monitors its own resource limits, registers its state within the shared platform database, and monitors peer health via the @cocreate/server-mesh Control Plane.
• Autonomous Self-Replication: If a node detects cluster-wide saturation or localized system boundaries, it doesn't wait for a central master to act. It directly contacts your cloud provider's API to clone its own VM image, dynamically spawning an exact sibling node to scale out immediately:

$$\text{Resource Boundary Tripped} \implies \text{Node } A \xrightarrow{\text{Direct Cloud API Call}} \text{Clone VM Image} \implies \text{Spawn Sibling Node } B$$

• Zero Single Point of Failure (SPOF): If any node drops offline or crashes, surviving peer nodes detect the loss of its keep-alive heartbeat on the mesh control plane and dynamically adjust scaling priorities.

---

Why CoCreate Server Autoscaler?

Unlike standard cloud-native autoscaling groups (like AWS ASGs) that only monitor generic hypervisor metrics like raw CPU and ignore application-level boundaries, @cocreate/autoscaler is tightly integrated with the CoCreate core.

It understands Multi-Tenant Boundaries and WebSocket Connection States. It makes scaling decisions based on real-time transaction lag, active user session counts, and memory footprints rather than inaccurate system-level averages.

---

Vertical & Horizontal Multi-Cloud Adaptability

The autoscaler features a robust, pluggable Cloud Adapter Plane that supports standard vertical and horizontal orchestrations across all major cloud hosting platforms (AWS, Google Cloud, Azure, DigitalOcean, and Vultr).

1. Horizontal Scaling (Scale In / Scale Out)

• Spawns identical replica instances (cloned VM images or container instances) to distribute multi-tenant WebSocket connections across more physical servers.
• Automatically registers new nodes with the @cocreate/server-mesh peer list upon boot.

2. Vertical Scaling (Scale Up / Scale Down)

• For cloud providers that support hot-swapping virtual resources, the autoscaler can programmatically upgrade instance tiers (increasing CPU/RAM limits) on-the-fly.
• If a hot-swap is not supported, it performs a seamless rolling vertical upgrade: it spawns a larger tier node, drains the smaller node, and terminates the old instance.

---

Self-Healing & Telemetry-Driven Lifecycle

The autoscaler connects directly to the local @cocreate/telemetry Data Engine pipeline. It processes system telemetry metrics to continuously calculate a weighted saturation index:

$$\text{Saturation Index} = \alpha \cdot \text{V8 CPU Lag} + \beta \cdot \text{RAM Utilization} + \gamma \cdot \text{Socket Density}$$

• Self-Healing Interventions: If the Saturation Index exceeds your configured safety threshold for a sustained period, the autoscaler initiates scaling protocols.
• Dead-Node Pruning: When a peer server drops offline without a clean exit (e.g., hardware failure or kernel panic), the active nodes wait for a stagger delay before pruning the dead node's records from the database registry and redistributing tenant routing channels.

---

Cooperative Draining & Scale-Down Sequence

To prevent cutting off active user sessions during a scale-down event, the autoscaler uses a secure, decoupled Cooperative Draining mechanism:

       [Autoscaler Trigger]
                │
                ▼
      [Cordon Target Node] ────► [HTTP Returns 307 Redirects] ────► [WebSocket Clients Migrated]
                │
                ▼
     [Telemetry Zero Check] ───► [Flush Final Billing Data] ─────► [Clean VM Termination]

• The Cordon Command: The autoscaler flags the targeted node as isCordon = true via the secure control plane.
• Session Migration: The target server's HTTP gateway begins returning 307 Temporary Redirect responses. It calls .destroyAll() on the local SocketServer to safely disconnect users, forcing their browsers to reconnect to other online sibling nodes.
• Standby Verification: The autoscaler monitors the target server's status in the database. Once the node reports activeConnections: 0, its buffers are fully flushed, and its database pools are closed, the autoscaler securely calls the cloud provider's API to destroy the instance.

---

Configuration

Configure the autoscaler with the following policy structure. Cloud-provider connection details remain in the provider API configuration.

{
  "scaleOut": {
    "cpuThreshold": 85,
    "memoryThreshold": 85,
    "consecutiveFlushes": 3,
    "maxClusterSize": 0
  },
  "scaleIn": {
    "cpuThreshold": 10,
    "memoryThreshold": 45,
    "consecutiveFlushes": 10,
    "preservation": "continent",
    "minClusterSize": 2,
    "decommissionStrategy": "oldest"
  },
  "geoScale": {
    "enabled": true,
    "sheddingThreshold": 20,
    "densityBy": "continent"
  },
  "vertical": {
    "enabled": true,
    "maxNodesPerTier": 2,
    "min": { "vCPU": 1, "memoryGb": 2 },
    "max": { "vCPU": 64, "memoryGb": 256 }
  }
}

Vertical resource bounds

vertical.min defines the first server size and vertical.max defines the upper resource boundary. The autoscaler can add up to maxNodesPerTier regional servers at the current size. Once that count is reached, the next target doubles the current vCPU and memory values, capped independently by their configured maximums. The cloud adapter then selects the smallest available provider instance that satisfies both target values.

Decommission strategy

scaleIn.decommissionStrategy supports two values:

• oldest selects the active server with the earliest created.on timestamp. When that timestamp is unavailable, the timestamp embedded in a MongoDB ObjectId is used as a deterministic fallback.
• local selects the server running the autoscaler, allowing an eligible node to decommission itself autonomously. If that server is not present in the active cluster records, scale-in is rejected rather than targeting another node.

Unrecognized strategy values safely fall back to oldest.

---

Installation

You can install this package locally via npm:

npm i @cocreate/autoscaler

Or via yarn:

yarn add @cocreate/autoscaler

---

Announcements

All scaling adaptations, cloud adapter API patches, and metric evaluation revisions are tracked inside our release logs on the CoCreate Server Autoscaler GitHub Releases page. Please subscribe to our release notifications for breaking updates on cloud provider parameters.

---

Roadmap

Upcoming enhancements planned for our autonomous scaling system include:

• Predictive Scaling Engine: Utilizing linear regression models on historical time-series telemetry to preemptively scale up cluster capacity before scheduled traffic spikes.
• Kubernetes KEDA Adapter: Native scaling support for containerized Kubernetes workloads using CoCreate telemetry events as custom HPA metrics.

---

How to Contribute

We encourage contribution to our libraries (you might even score some nifty swag), please see our CONTRIBUTING.md guide for details. If you encounter any bugs or wish to make feature requests, please submit an issue on our GitHub Issues tracker. We want this library to be community-driven, and CoCreate led. We need your help to realize this goal.

For broader system configurations and API guides, please visit our CoCreate Server Autoscaler Documentation.

---

About

@cocreate/autoscaler is designed, built, and supported by the CoCreate Developer Experience Team.

Note

Please contact the Developer Experience Team via GitHub Discussions or join our Discord channel for any architecture or deployment queries.

@cocreate/autoscaler is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.

Master status and available capacity

Available capacity and telemetry averages include only running masters. Provisioning is pending capacity. Draining/terminating masters are tracked separately for removal coordination; stopped, failed and terminated masters are excluded. Worker status and drain/cordon flags do not change server eligibility. State.save preserves failed/terminating outcomes by skipping subsequent State saves; scaling policy remains unchanged.

Delayed server inventory cleanup

Initialization schedules an own-cluster sweep every ten minutes, with no startup sweep. Retirement commits master.status terminating before the provider API call. Success retains that state; failure overrides it with failed. Only terminating records are selected for cleanup; failed records remain for investigation, and their Manager update cancels pending Manager cleanup directly. The shared deleteServer helper removes inventory without another server-status lookup or cloud API request. An already-missing record is success. Managed local cleanup also sends object.delete servers to Manager for its platform copy; unmanaged cleanup stays local. Manager uses the same helper one minute after persisting a terminating report, deleting the tenant copy before the platform copy. Manager deletion receipts do not mirror back.

Cleanup helpers receive an explicit server context so Manager workers can use them without initializing an AutoScaler instance. Server instances expose deleteServer and collectTerminatingServers on server.autoscaler. Timers are process-local; they do not provide persistent scheduling or a platform-wide tenant sweep. Initial provisioning remains Manager's responsibility, and failed inventory is never selected automatically.

Organization-driven scale-to-zero

Mesh's confirmed organization.inactive event invokes the existing scaleIn operation when the organization matches this node, autoscaling is enabled and minClusterSize is zero, selecting the local node through the existing selection lookup. Each node retires itself; ordinary scaling retains its configured selection strategy. Organization activation clears the idle marker. CPU/memory scale-in alone retains the final node. The final idle removal does not require CPU/memory samples when no capacity remains; other capacity-change checks still apply. Evaluation already in progress can defer the retained idle request until a subsequent telemetry evaluation. No client counts or peer registrations are validated again by AutoScaler. Drain, provider termination, shutdown and inventory cleanup follow the existing lifecycle.