orbiter
An HTTP backend framework for Dart designed to stay close to raw dart:io, with the routing, interceptors and
cleanup you would otherwise write by hand.
On a simple endpoint, a large share of a Dart server's time can go to the framework rather than to your code:
wrapper objects, buffered bodies, zone lookups, a middleware chain rebuilt on every call. orbiter is designed
around removing that overhead. Responses stream straight to dart:io's HttpResponse, the interceptor chain is
folded once at startup, routes are matched in a radix tree, and per-request state lives on the request itself
instead of in zones. What you get on top is the part every backend needs: typed request context, error boundaries,
safe defaults, and cleanup hooks that run only after the response is fully written, so a pooled database connection
always goes back.
It has no database dependency. Each database gets a small kit package that wires it in; for PostgreSQL that is
orbiter_postgres, with one row-level-security transaction per
request in a single interceptor.
Features
- Streaming responses: bodies go straight to
HttpResponse, with no pre-buffering and few intermediate objects on the request path. - Pipeline folded at startup: interceptors are composed once, when the handler is built, so a request pays no chain-assembly cost; any interceptor can short-circuit.
- Radix router: lookup by path segment, static routes before dynamic ones, parameters (
:id), wildcards (*path), and correct404and405with theAllowheader. - Typed request context without zones:
request.context.set(value)/get<T>(), stored on the request. - Guaranteed cleanup: hooks run in reverse order after the response is written (streamed bodies included), also on uncaught errors and client disconnects.
- Safe defaults: a 1 MiB body limit, generic
500s to the client with details only on the server, CORS that refuses*with credentials, graceful shutdown that drains in-flight requests;securityHeaders()andrequestLogger()ready to add. - Multiple workers: one server per isolate on the same port, each with its own pool and dependencies.
- Admission control: an optional
ConcurrencyLimitcaps the requests running at once, queues a few for a short time and answers the rest with503andRetry-After, so overload is refused fast instead of piling up.
Install
dart pub add orbiter
Experimental (pre-1.0).
Quickstart
import 'dart:io';
import 'package:orbiter/orbiter.dart';
void main() async {
final router = Router();
router.get('/health', (request) => Response.json({'status': 'ok'}));
router.get('/users/:id', (request) {
final id = request.pathParam('id');
return Response.ok(body: 'User: $id');
});
final app = Pipeline()
.add(securityHeaders())
.add(requestLogger())
.addHandler(router.handler);
final server = await BackendServer.bind(
handler: app,
address: InternetAddress.anyIPv4,
port: 8080,
);
print('Server listening on http://localhost:${server.port}');
}
example/main.dart adds an interceptor of its own and a graceful shutdown.
Multiple workers
MultiWorkerServer runs one server per isolate on the same port (HttpServer.bind(shared: true)), one per CPU
core by default. You give it a setup function instead of a handler: it runs inside each worker, so the router,
the connection pool and anything else it builds belong to that worker alone.
WorkerApp buildWorker(WorkerContext worker) {
final pool = openPool(); // one pool per worker
return WorkerApp(
handler: buildRouter(pool).handler,
onShutdown: pool.close, // runs after the worker's in-flight requests drain
);
}
final server = await MultiWorkerServer.start(setup: buildWorker, port: 8080);
// ...
await server.close();
- The isolate that calls
startonly supervises; it does not serve requests. - The setup function is sent to each isolate. If it captures something that cannot cross isolates (an open pool,
a
ReceivePort),startthrows. Build those objects inside the setup. port: 0works: the first worker gets the ephemeral port and the others join it; read it fromserver.port.- For HTTPS, pass
securityContext: () => SecurityContext()..useCertificateChain(...). ASecurityContextcannot cross isolates, so each worker builds its own. - If any worker fails to start, the others are stopped and
startthrowsMultiWorkerStartException. - A worker that dies (an uncaught error) is reported to
onErrorasWorkerExitedExceptionand is not restarted; the others keep serving. The connection that worker had open is never answered.
example/multi_worker.dart is a runnable version.
The family
| Package | Role |
|---|---|
orbiter |
This framework. |
orbiter_postgres |
PostgreSQL kit: one row-level-security transaction per request, prefix search. |
slingshot_postgres |
PostgreSQL driver over libpq, with a native connection pool. |
slingshot |
The contract every slingshot driver implements. |
An app depends on the framework and on the kit of each database it uses.
Writing an interceptor
An interceptor receives the request and next, the rest of the pipeline. It either returns a Response itself,
which ends the request there, or calls next(request) and may inspect or replace what comes back. Interceptors run
in the order they were added to the Pipeline, and the chain is folded once, when addHandler is called.
The plain form is a function with the InterceptorFunction signature:
FutureOr<Response> requireApiKey(Request request, NextFunction next) {
final key = request.getHeader('x-api-key');
if (key == null) return Response.unauthorized();
request.context.set(ApiKey(key)); // typed, one value per type
return next(request);
}
// In a handler further down:
final key = request.context.get<ApiKey>(); // getOrNull<ApiKey>() when it may be absent
When the interceptor holds configuration or state, implement Interceptor and add its intercept method:
final class Timing implements Interceptor {
Timing(this.slowThreshold);
final Duration slowThreshold;
@override
Future<Response> intercept(Request request, NextFunction next) async {
final watch = Stopwatch()..start();
final response = await next(request);
if (watch.elapsed > slowThreshold) print('slow: ${request.uri.path}');
return response;
}
}
final app = Pipeline()
.add(requireApiKey)
.add(Timing(const Duration(milliseconds: 200)).intercept)
.addHandler(router.handler);
request.context is created on first use and lives as long as the request; setKey / getKeyOrNull store values
under an explicit key when two values share a type. To release a resource after the response is fully written,
register request.addCleanupHook instead of relying on code after next, which runs before a streamed body ends.
Errors and logging
Two hooks on BackendServer.bind handle failures, and they do different jobs:
errorHandlerturns an unhandled error into the response the client gets. The default answers413forPayloadTooLargeExceptionand a generic500for anything else. A custom handler replaces the default, so it has to answer the413case itself.onErrorreports the failure on the server side and returns nothing. It receives every unhandled handler error (exceptPayloadTooLargeException) and every failure while writing the response, including the ones that happen after the client already has the status line. The default writes one line tostderr.
final server = await BackendServer.bind(
handler: app,
port: 8080,
errorHandler: (error, stackTrace, request) => switch (error) {
PayloadTooLargeException() => Response(413),
NotFoundError() => Response.notFound(),
_ => Response.internalServerError(),
},
onError: (error, stackTrace, request) =>
log.severe('${request?.uri.path}', error, stackTrace),
);
If the errorHandler itself throws, the error goes to onError and the client gets a plain 500.
requestLogger() writes one line per request (method, path, status, duration) with print; pass logFn to send
it somewhere else, e.g. requestLogger(logFn: log.info).
Safety Defaults
- Body limit:
request.readAsBytes()/readAsString()/readAsJson()reject bodies abovemaxBodySize(default 1 MiB) withPayloadTooLargeException, answered as413. Configure it inBackendServer.bind(maxBodySize: ...);nulldisables the limit. - Error reporting: unhandled handler errors and response-write failures go to
onError(default: one line onstderr). The client only sees a generic500. - Response writing: an invalid header value (e.g. containing
\r\n) yields a500instead of a hanging connection. - CORS:
cors()with'*'answersAccess-Control-Allow-Origin: *and cannot be combined withallowCredentials. With an explicit list, the requestOriginis reflected when allowed (plusVary: Origin); other origins get no CORS headers. OnlyOPTIONSrequests carryingOriginandAccess-Control-Request-Methodare treated as preflight. - Path parameters are percent-decoded before reaching the handler.
- Concurrency limit (opt-in):
BackendServer.bind(concurrencyLimit: ConcurrencyLimit(maxInFlight: 32))admits at mostmaxInFlightrequests at once. A request holds its slot until its cleanup hooks finish, which is where a database transaction or connection is released. When every slot is taken, up tomaxQueuedrequests (default:maxInFlight) wait in arrival order for at mostqueueTimeout(default 250 ms); the rest get503withRetry-After(default 1 s) and{"error":"Service Unavailable","code":503}, without running the handler.HttpDispatcherexposesadmitted,queuedandrejected. WithMultiWorkerServerthe limit is per worker. There is no per-request timeout: a running handler cannot be cancelled, so bound the time where the work happens (the database'sstatement_timeout, the pool's acquire timeout).
Example with PostgreSQL
A runnable CRUD server wired to slingshot_postgres is the example of
orbiter_postgres, because it is the package that depends on
both.
Benchmarks and research
The project started as an MBA thesis in Software Engineering at the University of São Paulo (USP), whose
cross-language benchmark suite found that, on endpoints without database access, swapping the HTTP framework for a
raw dart:io server raised throughput by 55% to 60% with the same driver. orbiter was built from that finding. The
suite, the results and the evaluated code are public at
tganzerli/dart_db_connector (see
benchmarks/RESULTS.md).
orbiter's own throughput measurements are not published there yet.
License
MIT, see LICENSE.
Libraries
- orbiter
- High-throughput, low-allocation HTTP backend framework for Dart.