|
Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server 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++.
| 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 |
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.
This scaffolds main.cpp, a CMakeLists.txt wired to Orbit, and a vcpkg.json listing the dependencies.
Edit main.cpp:
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.0or later.v1.6.xand earlier contain a security vulnerability fixed inv2.0.0,v1.5.1and earlier contain further vulnerabilities fixed inv1.6.0, andv1.4.0and 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.
Common to every method that builds from source:
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.
Builds Orbit in Release mode, installs the library (to /usr/local by default), and installs the orbit CLI.
Linux / macOS
Windows (PowerShell as Administrator)
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 |
Piping a script into a shell runs arbitrary code as you, with
sudofor 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.
Available once the installer has 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.
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.
Configure with a vcpkg toolchain so Orbit's own dependencies resolve:
Turn off what you do not need to cut build time substantially:
Build and install once, then link from any project.
Then, in your own project:
If you installed to a custom prefix, point CMake at it:
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_corealso resolves, as older examples used that name.OrbitFramework::coreis canonical.
Manifest mode β Orbit's own vcpkg.json lists its dependencies, and this is how CI builds:
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:
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.
Or export Orbit into your local Conan cache and depend on it by name:
The recipe reads its version from CMakeLists.txt, so it always matches the project. Orbit is not on ConanCenter β see #6 on the roadmap.
ngtcp2andnghttp3have no ConanCenter recipes, so the Conan path builds without HTTP/3 unless you supply them yourself. Use vcpkg if you need QUIC.
A multi-stage Dockerfile builds quictls, nghttp3, and ngtcp2 from source for full HTTP/3 support, then ships a slim runtime image.
docker-compose.yml brings up Orbit alongside PostgreSQL and Redis with health-gated startup:
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.
For working on Orbit itself. See CONTRIBUTING.md for the full workflow.
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:
| 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.
CPack is configured, so you can produce native packages from a build tree:
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.
Orbit is built as a modular stack of composable layers:
All features are modular β turn subsystems on or off with CMake flags:
| 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 |
Orbit is versioned with Semantic Versioning, but it has not yet reached a frozen public API. Treat 1.x as pre-stable.
FetchContent or your package manager, and upgrade deliberately after reading the changelog.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.
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.
Found a security issue? Do not open a public issue β follow SECURITY.md.
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.