Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
Orbit Framework

πŸš€ Orbit Framework

A fast, asynchronous C++20 web framework with HTTP/2, WebSockets, a built-in ORM, and experimental HTTP/3

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:

int main() {
config.port = 8080;
// 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();
}
a class to store JSON values
Definition json.hpp:19401
The main application class for the Orbit Framework.
Definition App.hpp:36
Definition Config.hpp:8
Definition Config.hpp:30
Represents an incoming HTTP request.
Definition HttpRequest.hpp:54
std::unordered_map< std::string, std::string > params
Definition HttpRequest.hpp:62

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.

</blockquote>

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.

</blockquote>

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.

</blockquote>

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

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"]}};
});
});
Manages routing of HTTP requests to their appropriate handlers.
Definition Router.hpp:46
void use(Middleware m)
Router & get(const std::string &path, RouteHandler handler)
routing::Middleware jwt_auth(JwtOptions options)
Verifies an Authorization: Bearer JWT and stores its claims in req.user.
routing::Middleware cors(CorsOptions options=CorsOptions{})
Returns a middleware that handles CORS.
auto rate_limit(RateLimitOptions options)
Definition RateLimiter.hpp:62
std::unordered_map< std::string_view, std::string_view, utils::CaseInsensitiveHash, utils::CaseInsensitiveEqual > headers
Definition HttpRequest.hpp:60

C++20 Coroutines & Database ORM

struct User { int id; std::string name; int 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();
});
#define ORBIT_REGISTER_MODEL(Type, TableName)
Registers a standard C++ struct as an ORM Model mapping to a database table.
Definition Model.hpp:14
Represents an HTTP response to be sent to a client.
Definition HttpResponse.hpp:107
A database column, allowing C++ operators to build parameterized SQL conditions.
Definition QueryBuilder.hpp:203
#define NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Type,...)
macro
Definition json.hpp:2769
Definition Task.hpp:10
Definition Awaitable.hpp:10
Definition json.hpp:5363
Fire-and-forget coroutine type, used as the return type of coroutine route handlers.
Definition Task.hpp:36

WebSocket EventRouter (Socket.IO-style)

struct PlayerSession { std::string name; int score = 0; };
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");
Represents a connected client in the EventRouter.
Definition EventRouter.hpp:26

πŸ—οΈ 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 Release history and breaking changes
🧭 Migration Guide Upgrading between releases, with before/after code
πŸ“Š Test Coverage Measured coverage, per-file gaps, and how to reproduce
πŸ”­ Observability JSON logs, access logs, request IDs, tracing, metrics
⚑ Benchmarks Throughput figures, methodology, and their limits
🧭 Performance bottlenecks Where Orbit loses time today, the alternatives and their trade-offs
🏷️ Release Process Versioning policy, release contents, verifying signatures

πŸ”’ 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](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.


Built with ❀️ for the C++ community