osrv #

Dart-first unified server core with a single Server(...) API.

Status #

• Core API implemented: Server, middleware, plugins, lifecycle, error handling.
• dart:io runtime transport implemented and tested.
• WebSocket upgrade helper implemented for Dart/Node/Bun, and Edge adapters with provider-specific limits.
• Maintainer helper script available at dart run tool/build.dart (delegates to CLI build).
• dart run osrv build generates direct-deploy Node/Bun/Deno/Edge adapters under dist/ that load Dart-compiled JS core.

Edge WebSocket support:

• Cloudflare Workers: supported.
• Netlify Edge: supported when runtime exposes Deno.upgradeWebSocket (or WebSocketPair).
• Vercel Edge: not supported by runtime; adapter returns 501 for websocket upgrade attempts.

Install #

dart pub add osrv

Use osrv in your own package #

Published dependency:

dependencies:
  osrv: ^0.1.0

Then create bin/main.dart:

import 'package:osrv/osrv.dart';

Future<void> main() async {
  final server = Server(
    fetch: (request) => Response.json({'ok': true, 'path': request.url.path}),
  );
  await server.serve();
}

Local path dependency (for osrv contributors):

dependencies:
  osrv:
    path: ../osrv

Example package #

/example is a minimal non-publishable pub package that depends on osrv via path dependency.

cd example
dart pub get
dart run osrv serve
dart run osrv build

Quick start #

import 'package:osrv/osrv.dart';

Future<void> main() async {
  final server = Server(
    fetch: (request) async {
      return Response.json({'ok': true, 'path': request.url.path});
    },
  );

  await server.serve();
}

CLI #

dart run osrv serve
dart run osrv build

serve defaults to server.dart (fallback: bin/server.dart), and build also defaults to the same entry.

osrv.config.dart is not supported in V1. Use CLI flags, environment variables, or constructor options.

TLS/HTTP2 flags for local serve:

dart run osrv serve --tls --cert=cert.pem --key=key.pem --http2

http2 is tri-state in CLI:

• --http2: force on.
• --no-http2: force off.
• omitted: runtime default (auto).

Dependency-mode workflow (inside your app package):

1. Add osrv dependency.
2. Create server.dart with your server entrypoint.
3. Run dart run osrv serve for local run.
4. Run dart run osrv build for distributable artifacts.

CLI config precedence:

1. CLI flags
2. Environment variables
3. Defaults

Programmatic build API (for downstream packages):

import 'package:osrv/build.dart';

Future<void> main() async {
  await build(
    const BuildOptions(
      entry: 'server.dart',
      outDir: 'dist',
    ),
  );
}

Maintainer Build Helper #

dart run tool/build.dart

This is for local osrv repo development convenience. User/application build flow remains dart run osrv build.

Artifacts:

• dist/js/<runtime>/
• dist/edge/<provider>/
• dist/bin/

Test #

dart test

Contract runner:

dart run tool/contract.dart

Multi-runtime contract matrix (auto-detects available runtimes):

dart run tool/contract_matrix.dart

Benchmark gate (fractional overhead, 0.05 == 5%):

dart run tool/bench.dart --requests=200 --max-overhead=0.05

Docs #

• docs/troubleshooting.md
• docs/examples.md