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

What to know before running Orbit in production. This page describes the current state of main; it is updated when a limitation is fixed. For security reporting see SECURITY.md, and for planned work see ROADMAP.md.

1. HTTP/3 and gRPC are experimental

HTTP/3 (QUIC). HTTP/3 requests go through the same router as HTTP/1.1 and HTTP/2, including files and streamed responses, but HTTP/3 has only been tested by Orbit's own test suite (libcurl with HTTP/3). It has not been checked against browsers or other HTTP/3 implementations. QUIC runs on the first event loop only, the TCP listener sends no Alt-Svc, and 0-RTT is off. Serve production traffic over HTTP/1.1 or HTTP/2. Details: http3.md.

gRPC. server::GrpcServer (ORBIT_ENABLE_GRPC, off by default) is a minimal pass-through to grpc::ServerBuilder with insecure credentials only, checked by a smoke test. It does not share Orbit's event loops, TLS configuration or middleware.

Both may change in any release until they are declared stable.

2. Several event loops need Linux

An event loop is the thread that accepts connections and performs socket I/O and TLS; handlers run on a worker thread pool (ServerConfig::worker_threads). By default (event_loops = 0, --event-loops auto) an App runs one loop per CPU this process may use (its affinity mask, so containers and taskset are respected). Each loop has its own SO_REUSEPORT listening socket; the kernel spreads new connections across them and a connection stays on its loop. --event-loops N sets the number; --event-loops 1 gives the single-loop behaviour of 2.0.

That is Linux only. Elsewhere one loop is used, because other systems do not balance SO_REUSEPORT sockets; run several processes instead. HTTP/3 (QUIC) stays on the first loop.

--threads auto sizes the handler pool by the same CPU count, --cpu-affinity pins each loop to its own CPU, and --engine auto picks io_uring when the kernel supports it (Linux 5.7+) and epoll otherwise; those three are opt-in, and the engine defaults to epoll. The server logs what it chose at start-up, and App::effective_config() returns it.

3. Large default dependency set

PostgreSQL, MariaDB, MongoDB, Redis, brotli and zstd are enabled by default; HTTP/3 and gRPC are experimental and off unless enabled. With vcpkg, the manifest features follow the ORBIT_ENABLE_* options (#36), so turning a backend off (-DORBIT_ENABLE_POSTGRES=OFF, ...) also stops vcpkg from building its library. The default set still takes a while on a first build; -DORBIT_ENABLE_POSTGRES=OFF -DORBIT_ENABLE_MARIADB=OFF -DORBIT_ENABLE_MONGODB=OFF (or the core preset) gives a minimal build.

4. Custom protocol parsers

Multipart and WebSocket parsing are implemented in Orbit rather than taken from a widely deployed library, which makes them the main attack surface. HTTP/1.1 requests are parsed by llhttp, the parser Node.js uses. Mitigations in place:

  • the parsers are fuzzed in CI (.github/workflows/fuzz.yml);
  • WebSocket handling is checked against the Autobahn TestSuite (.github/workflows/autobahn.yml);
  • the test suite runs under Valgrind in CI and under ASan/UBSan in local Debug builds;
  • request framing follows RFC 9112 strictly (conflicting Content-Length, Transfer-Encoding with Content-Length, oversized headers and bodies are rejected), and every connection phase has a timeout.

Orbit has not had a third-party security audit or penetration test.

5. Asynchronous lifetimes

Handlers may finish after they return (database coroutines, thread-pool work, SSE streams). A coroutine handler can use the HttpRequest& it takes as a parameter until it finishes. Other callbacks (a lambda handed to the thread pool, a subscriber list) must capture the std::shared_ptr<ResponseWriter> (and any request data they need) by value; references to the HttpRequest or to locals are dangling once the handler has returned. A writer kept for later can check is_open() or register on_close() to learn that its client has gone.

6. Platform coverage is uneven

CI builds and tests every change on Ubuntu (epoll), macOS (kqueue) and Windows (IOCP). Not covered by CI:

  • the io_uring engine (ServerConfig::engine = EventEngine::IoUring), which is opt-in;
  • HTTP/2 on Windows has one known intermittent test failure (#86).

7. No API or ABI stability yet

1.x is pre-stable: minor releases may change the API, and there is no ABI guarantee — rebuild your application for each Orbit release. Every breaking change is listed in CHANGELOG.md, with upgrade steps in migration.md.

8. Test coverage

Line coverage is measured on every push and published in coverage.md. HTTP/1.1, routing, middleware and WebSockets are the best exercised; HTTP/2, HTTP/3, the gRPC wrapper and parts of the ORM have thinner coverage.

9. Swagger UI loads from a CDN

App::enable_openapi() serves a Swagger UI page that loads its CSS and script from unpkg by default, pinned with Subresource Integrity hashes. Pass assets_url (e.g. "/swagger-ui" served by static_files, with the files from swagger-ui-dist 5.11.0) to keep the page off third-party origins.

The page has no inline script: its bootstrap is served at <docs_path>/init.js. Under a Content-Security-Policy it needs ‘script-src 'self’plus the asset origin, and Swagger UI's own styling needs style-srcwith that origin and'unsafe-inline'`, for example:

default-src 'self'; script-src 'self' https://unpkg.com;
style-src 'self' https://unpkg.com 'unsafe-inline'; img-src 'self' data:

Enable the docs page only where the API description may be public.