Orbis

A high-performance, self-healing distributed caching engine designed for modern applications.

---

What is Orbis?

Orbis acts as a high-speed memory layer sitting between your application and database. Built from the ground up for enterprise-grade reliability, it dramatically reduces database load by caching heavy query results, session data, and API responses in a highly available, distributed cluster.

Orbis abstracts away the complexity of distributed systems—automatically managing data distribution, node failures, and memory limits so you can focus on building your app.

---

✨ Core Features

• Consistent Hashing: Keys are evenly distributed across nodes using a virtual hash ring, minimizing data movement when nodes join or leave.
• Zero-Downtime Failover: The Coordinator actively monitors nodes via heartbeats. If a node crashes, traffic is instantly rerouted to healthy replicas.
• LRU Eviction & TTL: Out-of-the-box memory management via Least Recently Used (LRU) algorithms and Time-To-Live expiries.
• Disk Persistence: Nodes take periodic snapshots of their in-memory data, ensuring seamless recovery upon restarts.
• Universal Compatibility: Access your cache natively through the Node.js SDK or via standard HTTP REST API from Python, Java, Go, and more.
• Beautiful Dashboard: A built-in graphical control center featuring live cluster analytics, an interactive API Playground, and comprehensive documentation.

---

Architecture & Folder Structure

This repository is a monorepo containing the core components of the Orbis ecosystem:

distributed-cache/
├── packages/
│   ├── orbis-cache-server/   # The backend daemon. Runs the coordinator and the storage nodes.
│   │   ├── src/
│   │   │   ├── Dashboard/    # The GUI control center (HTML/CSS/JS)
│   │   │   ├── coordinator.js# Manages the hash ring and health checks
│   │   │   ├── node.js       # The actual storage engine holding the data
│   │   │   └── server.js     # Entry point for the CLI
│   │   └── package.json
│   │
│   └── orbis-cache/          # The lightweight Node.js Client SDK
│       ├── src/
│       │   └── index.js      # Main OrbisClient class
│       └── package.json

---

Quick Start Guide

You can have a fully distributed caching cluster running on your local machine in under 2 minutes.

1. Start the Cluster

Install and boot up the Orbis server globally via npx:

npx orbis-cache-server start

(By default, this runs on port 4000. Use --port=PORT or --auth-key=SECRET for advanced config).

2. View the Dashboard

Once the server is running, open your browser and navigate to:

http://localhost:4000

Here you can view your live metrics, explore the topology ring, and test the cache in real-time.

3. Connect your Application

Install the Node.js client SDK in your project:

npm install orbis-cache

Use it in your code:

const { OrbisClient } = require('orbis-cache');

// Connect to the coordinator
const cache = new OrbisClient({ port: 4000 });

async function getUserProfile(userId) {
  // 1. Check Cache
  const cachedUser = await cache.get(`user:${userId}`);
  if (cachedUser) return cachedUser;

  // 2. Fetch from Database (Cache Miss)
  const dbUser = { id: userId, name: "Aman" }; // Simulated DB call

  // 3. Store in Cache for 5 minutes (300s)
  await cache.set(`user:${userId}`, dbUser, 300);
  
  return dbUser;
}

---

🌍 Universal REST API (Any Language)

Not using Node.js? No problem. Orbis communicates over standard HTTP.

Python Example:

import requests

# Set Data
requests.post("http://localhost:4000/set", json={
    "key": "my_key",
    "value": "Hello World",
    "ttl": 300
})

# Get Data
response = requests.get("http://localhost:4000/get/my_key")
print(response.json())

---

Advanced Usage

Securing the Cluster

Protect your cache endpoints using the --auth-key flag:

npx orbis-cache-server start --auth-key=supersecret123

Then pass it in the client SDK:

const cache = new OrbisClient({ 
  port: 4000, 
  authKey: 'supersecret123' 
});

Adding Worker Nodes (Horizontal Scaling)

If you want to scale out, you can boot up extra storage nodes and attach them to the coordinator:

npx orbis-cache-server start-node --coordinator=http://localhost:4000 --port=4001
npx orbis-cache-server start-node --coordinator=http://localhost:4000 --port=4002

---

Contributing

Contributions, issues, and feature requests are always welcome! Feel free to check the issues page on GitHub.

License

This project is open-sourced under the MIT License.

---

🧠 Behind the Scenes

Want to get a brief about the theoretical concepts and distributed systems architecture used in this product? Refer to my own handwritten notes in a very brief way: notes.MD.