Orbit Framework

---

Orbit brings Express.js ergonomics to C++20, powered by raw kernel performance (io_uring / epoll / kqueue / IOCP) and next-gen protocols (HTTP/2, and experimental HTTP/3 + QUIC). Write async web servers, REST APIs, and real-time apps — without sacrificing the speed of C++.

⚡ Why Orbit?

Feature	Details
Fast	~106k req/s on a trivial keep-alive workload with 6 event loops, about 40% of Drogon and Crow on the same machine (measured; closing the gap is #163); asynchronous Proactor pattern over io_uring, epoll, kqueue, and Windows IOCP
Modern Protocols	HTTP/1.1 and HTTP/2, plus HTTP/3 & QUIC (experimental) — no external proxy needed
Express-Style API	Routing, middleware chains, route groups, and dynamic parameters
Magic Returns	Return std::string, structs, or nlohmann::json from handlers — Orbit auto-serializes
Built-in ORM	Expression DSL: Col("age") >= 18 builds SQL with bound parameters, never spliced values
Real-Time	RFC 6455 WebSockets + Socket.IO-style EventRouter with rooms & sessions
13+ Middlewares	CORS, JWT Auth, Rate Limiting, CSRF, Compression, Proxy, OAuth2, and more
4 Database Clients	PostgreSQL and MySQL/MariaDB async on the event loop (C++20 coroutines), MongoDB on the thread pool, Redis synchronous
Cross-Platform CI	Tested on Ubuntu, macOS, and Windows with Valgrind leak detection

---

🚀 Quick Start

1. Install

curl -fsSL https://raw.githubusercontent.com/varuns2903/orbit-framework/main/install.sh | bash

Windows, and every other way to get Orbit — FetchContent, vcpkg, Conan, Docker, find_package — are covered under Installation. If you would rather not install anything system-wide, FetchContent drops Orbit straight into an existing CMake project.

2. Create a Project

orbit new myapp
cd myapp

This scaffolds main.cpp, a CMakeLists.txt wired to Orbit, and a vcpkg.json listing the dependencies.

3. Write Your Server

Edit main.cpp:

#include <orbit/server/App.hpp>
#include <orbit/config/Config.hpp>
#include <orbit/http/json.hpp>

int main() {
    orbit::config::ServerConfig config;
    config.port = 8080;

    orbit::server::App app(config);

    // Return a string — Orbit handles the HTTP response automatically
    app.get("/", []() -> std::string {
        return "Hello from Orbit! 🚀";
    });

    // Return JSON
    app.get("/api/status", []() -> nlohmann::json {
        return {{"status", "ok"}, {"version", "2.0.0"}};
    });

    // Dynamic route parameters
    app.get("/users/:id", [](const orbit::http::HttpRequest& req) -> nlohmann::json {
        return {{"user_id", req.params.at("id")}};
    });

    app.listen();
}

4. Build & Run

orbit build --release
orbit run

$ curl http://localhost:8080/
Hello from Orbit! 🚀

$ curl http://localhost:8080/api/status
{"status":"ok","version":"2.0.0"}

$ curl http://localhost:8080/users/42
{"user_id":"42"}

---

📦 Installation

Orbit can be consumed in several ways. Pick by what you are doing:

You want to…	Use	Needs a system install?
Try Orbit quickly on Linux/macOS/Windows	One-command installer	Yes
Start a new app from a template	Orbit CLI	Yes (installer provides it)
Add Orbit to an existing CMake project	CMake FetchContent	No
Link a system-wide build	find_package	Yes
Manage deps with vcpkg	vcpkg	No
Manage deps with Conan	Conan 2.x	No
Ship a container	Docker	No
Hack on Orbit itself	Build from source	No
Produce .deb / .rpm / .tar.gz	CPack packages	No

Version note. Use v2.0.0 or later. v1.6.x and earlier contain a security vulnerability fixed in v2.0.0, v1.5.1 and earlier contain further vulnerabilities fixed in v1.6.0, and v1.4.0 and earlier also contain a CMake defect that corrupted the stack of every consuming application. Code written for 1.x builds against 2.0; see the migration guide. See CHANGELOG.md and API Stability.

Prerequisites

Common to every method that builds from source:

• C++20 compiler — GCC 11+, Clang 14+, or MSVC 19.30+
• CMake 3.20+
• Linux kernel 5.6+ for the io_uring backend (falls back to epoll)

Orbit links OpenSSL, zlib, libcurl, nghttp2, and — depending on enabled features — ngtcp2, nghttp3, libpq, MariaDB Connector/C, mongo-c-driver, and liburing. Let vcpkg or Conan supply them rather than installing by hand. Full list and licences: THIRD_PARTY_NOTICES.md.

---

One-Command Installer

Builds Orbit in Release mode, installs the library (to /usr/local by default), and installs the orbit CLI.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/varuns2903/orbit-framework/main/install.sh | bash

Windows (PowerShell as Administrator)

iwr -useb https://raw.githubusercontent.com/varuns2903/orbit-framework/main/install.ps1 | iex

The script installs the latest release (not the development branch), bootstraps vcpkg pinned to the release's dependency baseline, compiles every dependency, and installs. Expect 20–40 minutes on first run; a binary cache under ~/.cache/vcpkg-binary-cache makes repeat runs far quicker.

Variable	Default	Meaning
ORBIT_VERSION	latest release	Tag to install, e.g. v2.0.0; main installs the development branch
ORBIT_PREFIX	/usr/local (Windows: C:\Program Files\OrbitFramework)	Install location; sudo is only used if it is not writable
ORBIT_JOBS	limited by free memory (~2 GB per job)	Parallel build jobs

# Example: a specific release, installed for your user only, without sudo
curl -fsSL https://raw.githubusercontent.com/varuns2903/orbit-framework/main/install.sh \
  | ORBIT_VERSION=v2.0.0 ORBIT_PREFIX="$HOME/.local" bash

Piping a script into a shell runs arbitrary code as you, with sudo for the install step when the prefix needs it. Read install.sh first if that matters to you, or use FetchContent, which needs no system install at all.

---

Orbit CLI

Available once the installer has run.

orbit new myapp          # scaffold main.cpp, CMakeLists.txt, vcpkg.json
orbit new myapp --fetch  # scaffold using FetchContent instead of find_package
cd myapp
orbit build              # RelWithDebInfo (optimized, with debug symbols)
orbit build --debug      # Debug
orbit build --release    # Release with LTO
orbit build -j 2         # limit parallel compile jobs
orbit run

orbit build picks up VCPKG_ROOT if set, otherwise a vcpkg/ directory beside your project, and warns if it finds neither. It compiles with one job per CPU but at most one per 2 GB of RAM, since Orbit's sources are large to compile. The generated vcpkg.json lists every library Orbit and its default features need, pinned to the same builtin-baseline as Orbit.

---

CMake FetchContent

The lightest option: no system install, and the version is pinned in your own build files. Orbit skips its examples, tests, and install rules when built as a subproject, so you get just the library.

cmake_minimum_required(VERSION 3.20)
project(my_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)
FetchContent_Declare(
  OrbitFramework
  GIT_REPOSITORY https://github.com/varuns2903/orbit-framework.git
  GIT_TAG        v2.0.0        # pin a release; avoid v1.4.0 and earlier
)
FetchContent_MakeAvailable(OrbitFramework)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE OrbitFramework::core)

Configure with a vcpkg toolchain so Orbit's own dependencies resolve:

cmake -B build -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --parallel

Turn off what you do not need to cut build time substantially:

cmake -B build -DORBIT_ENABLE_MONGODB=OFF -DORBIT_ENABLE_MARIADB=OFF

---

System-Wide Install (find_package)

Build and install once, then link from any project.

git clone https://github.com/varuns2903/orbit-framework.git
cd orbit-framework
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh          # bootstrap-vcpkg.bat on Windows

cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DORBIT_BUILD_TESTS=OFF \
  -DORBIT_BUILD_EXAMPLES=OFF
cmake --build build --parallel
sudo cmake --install build          # honours CMAKE_INSTALL_PREFIX

Then, in your own project:

find_package(OrbitFramework REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE OrbitFramework::core)

If you installed to a custom prefix, point CMake at it:

cmake -B build -DCMAKE_PREFIX_PATH=/opt/orbit

The installed package records which subsystems it was built with and asks only for those dependencies, so an Orbit built with -DORBIT_ENABLE_MONGODB=OFF will not demand mongo-c-driver from your project.

OrbitFramework::server_core also resolves, as older examples used that name. OrbitFramework::core is canonical.

---

vcpkg

Manifest mode — Orbit's own vcpkg.json lists its dependencies, and this is how CI builds:

git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
cmake -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake

The dependency set is pinned with builtin-baseline, so everyone resolves the same versions.

As a vcpkg port — the port in packaging/vcpkg-port/ builds Orbit the way the vcpkg registry would (no network during the build, features mapped to ORBIT_ENABLE_*) and is checked in CI by building a consumer against it. It is not in the upstream registry yet (#20), so use it as an overlay:

vcpkg install orbit-framework --overlay-ports=packaging/vcpkg-port
# then, in your CMakeLists.txt:
#   find_package(OrbitFramework CONFIG REQUIRED)
#   target_link_libraries(app PRIVATE OrbitFramework::core)

Default features: postgres, mariadb, mongodb, brotli, zstd; http3 and grpc are experimental and opt-in (orbit-framework[http3], orbit-framework[grpc]), and orbit-framework[core] builds without any of them.

---

Conan 2.x

conan install . --output-folder=build --build=missing
cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Or export Orbit into your local Conan cache and depend on it by name:

conan create .

The recipe reads its version from CMakeLists.txt, so it always matches the project. Orbit is not on ConanCenter — see #6 on the roadmap.

ngtcp2 and nghttp3 have no ConanCenter recipes, so the Conan path builds without HTTP/3 unless you supply them yourself. Use vcpkg if you need QUIC.

---

Docker

A multi-stage Dockerfile builds quictls, nghttp3, and ngtcp2 from source for full HTTP/3 support, then ships a slim runtime image.

docker build -t orbit-app .
docker run -p 8080:8080 -p 8443:8443 -p 8443:8443/udp orbit-app

docker-compose.yml brings up Orbit alongside PostgreSQL and Redis with health-gated startup:

docker compose up --build

Use it as a base for your own service by copying your sources in and building against the installed framework. The build is long — the QUIC stack is compiled from source — so lean on Docker layer caching.

---

Build From Source

For working on Orbit itself. See CONTRIBUTING.md for the full workflow.

git clone https://github.com/varuns2903/orbit-framework.git
cd orbit-framework
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh

cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel

cd build && ctest --output-on-failure
./benchmark_server

Debug builds enable AddressSanitizer and UndefinedBehaviorSanitizer by default.

Without vcpkg, using system packages — you are responsible for satisfying every dependency, and distribution packages are often too old for HTTP/3:

# Debian / Ubuntu
sudo apt install build-essential cmake pkg-config libssl-dev zlib1g-dev \
     libcurl4-openssl-dev libnghttp2-dev liburing-dev libpq-dev \
     libmariadb-dev libmongoc-dev

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Build Options

Option	Default	Effect
ORBIT_ENABLE_HTTP3	OFF	HTTP/3 and QUIC, experimental (needs ngtcp2 + nghttp3; enable at runtime with --http-version 3)
ORBIT_ENABLE_REDIS	ON	Redis client
ORBIT_ENABLE_POSTGRES	ON	PostgreSQL client
ORBIT_ENABLE_MARIADB	ON	MySQL/MariaDB client
ORBIT_ENABLE_MONGODB	ON	MongoDB client
ORBIT_ENABLE_GRPC	OFF	gRPC server wrapper (experimental, see #22)
ORBIT_BUILD_TESTS	ON	Test suite (downloads GoogleTest)
ORBIT_BUILD_EXAMPLES	ON	Example servers
ENABLE_SANITIZERS	ON when building Orbit itself, OFF as a dependency	ASan + UBSan in Debug builds; when on, applications linking Orbit get the sanitizer runtime too
ORBIT_ENABLE_COVERAGE	OFF	gcov instrumentation
BUILD_SHARED_LIBS	OFF	Shared instead of static library
ENABLE_FUZZING	OFF	libFuzzer targets (requires Clang)

These flags change the layout of public headers, and they propagate to your project automatically through OrbitFramework::core — do not set them by hand in a consuming project.

Building Distributable Packages

CPack is configured, so you can produce native packages from a build tree:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DORBIT_BUILD_TESTS=OFF
cmake --build build --parallel
cd build && cpack

Generates .tar.gz and .zip everywhere, plus .deb and .rpm on Linux, a .dmg on macOS, and an NSIS installer on Windows. No prebuilt packages are attached to GitHub Releases yet, so build your own for now.

---

📝 Features in Action

Middleware & Authentication

#include <orbit/middleware/Cors.hpp>
#include <orbit/middleware/JwtAuth.hpp>
#include <orbit/middleware/RateLimiter.hpp>

app.use(orbit::middleware::cors());                                        // Global CORS
app.use(orbit::middleware::rate_limit(1000, std::chrono::seconds(60)));    // Rate limit

// Protected route group
app.group("/api/v1", [](orbit::routing::Router& r) {
    r.use(orbit::middleware::jwt_auth("your-secret-key"));
    r.get("/profile", [](orbit::http::HttpRequest& req) -> nlohmann::json {
        return {{"user", req.headers["X-User-Id"]}};
    });
});

C++20 Coroutines & Database ORM

#include <orbit/orm/Model.hpp>
#include <orbit/database/PostgresClient.hpp>

struct User { int id; std::string name; int age; };
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(User, id, name, age)
ORBIT_REGISTER_MODEL(User, "users")

app.get("/adults", [](orbit::http::HttpRequest& req, std::shared_ptr<orbit::http::ResponseWriter> writer) {
    auto coro = [writer]() -> orbit::concurrency::Task {
        auto db = std::make_shared<orbit::database::PostgresClient>(&writer->proactor(), "dbname=myapp");
        co_await connect_async(db);

        // Expression DSL → parameterized SQL (values are bound, not spliced)
        auto users = co_await query_User(db)
            .where(orbit::orm::Col("age") >= 18)
            .get_async();

        writer->send(orbit::http::HttpResponse().status(200).send(nlohmann::json(users).dump()));
    };
    coro();
});

WebSocket EventRouter (Socket.IO-style)

#include <orbit/websocket/EventRouter.hpp>

struct PlayerSession { std::string name; int score = 0; };

orbit::websocket::EventRouter<PlayerSession> events;

events.on<std::string>("chat", [](auto& ws, const std::string& msg) {
    ws.to("lobby").emit("chat", ws.session().name + ": " + msg);
});

events.on_connect([](auto& ws) {
    ws.join("lobby");
});

events.attach(app, "/ws/game");

---

🏗️ Architecture

Orbit is built as a modular stack of composable layers:

┌─────────────────────────────────────┐
│           Your Application          │
├─────────────────────────────────────┤
│   Middleware Chain (CORS, Auth...)  │
├─────────────────────────────────────┤
│ Router (hash map + pattern match)   │
├─────────────────────────────────────┤
│  HTTP/1.1 │ HTTP/2 │ HTTP/3 (QUIC)  │
├─────────────────────────────────────┤
│  TLS/SSL  │ WebSockets │ SSE        │
├─────────────────────────────────────┤
│  Proactor Event Engine              │
│  io_uring │ epoll │ kqueue │ IOCP   │
└─────────────────────────────────────┘

All features are modular — turn subsystems on or off with CMake flags:

cmake -B build \
  -DORBIT_ENABLE_MONGODB=OFF \
  -DORBIT_ENABLE_HTTP3=ON     # experimental, off by default

---

📖 Documentation

Guide	Description
🚀 Getting Started	Installation, vcpkg, Conan, and FetchContent
📚 API Reference	Auto-generated Doxygen API Documentation
🛣️ Routing & Streaming	Routes, parameters, groups, and chunked responses
🛡️ Middleware	Built-in middleware and custom middleware authoring
💾 Database & Coroutines	PostgreSQL, Redis, and C++20 async/await
🔀 Proxy & Load Balancing	Reverse proxy, connection pooling, and load balancing
🌐 HTTP Client	Outbound requests with coroutines, timeouts, TLS verification
🔌 WebSockets	RFC 6455 WebSockets and EventRouter
⚡ HTTP/3 & QUIC	Enabling and using HTTP/3 (experimental)
🧪 Testing	In-process test client: call routes without a server or sockets
📋 Changelog

---

🔒 API Stability

Orbit is versioned with Semantic Versioning, but it has not yet reached a frozen public API. Treat 1.x as pre-stable.

• The API may change in minor releases. Roadmap item 31, maintain API/ABI compatibility, is not yet met. Every breaking change is documented in CHANGELOG.md, and docs/migration.md shows how to update code for each one, but a minor bump is not a guarantee of a drop-in upgrade.
• There is no ABI stability guarantee. Rebuild your application against a new Orbit release rather than swapping the shared library underneath it.
• Pin your version. Use an exact tag with FetchContent or your package manager, and upgrade deliberately after reading the changelog.
• Subsystem maturity varies. HTTP/1.1, routing, middleware, and WebSockets are the best exercised. HTTP/2, HTTP/3 and parts of the ORM have thinner test coverage, and the gRPC wrapper is experimental: a minimal pass-through to grpc::ServerBuilder (insecure credentials only), checked by a smoke test rather than the main CI matrix — see docs/ROADMAP.md for the honest state of each area and docs/loopholes_and_drawbacks.md for known architectural caveats.

If you are evaluating Orbit for production, read docs/loopholes_and_drawbacks.md first.

---

🤝 Contributing

Contributions are welcome — and you don't need to write C++ to help. Test coverage, documentation, examples, and platform testing are all high-impact right now.

• Read CONTRIBUTING.md for build setup, coding standards, and the PR process
• Browse good first issues for a scoped starting point
• See docs/ROADMAP.md for what's planned and what's unclaimed
• All participation is governed by our Code of Conduct

Found a security issue? Do not open a public issue — follow SECURITY.md.

📄 License

Distributed under the MIT License. See LICENSE for details.

Orbit bundles and links third-party components under their own licenses — including a vendored copy of nlohmann/json. See THIRD_PARTY_NOTICES.md for the full list and for guidance if your project already uses nlohmann/json.

---