osrv 0.6.0

Unified Dart server runtime for Dart, Node, Bun, Deno, Cloudflare, Vercel, and Netlify.

osrv

osrv is a unified server runtime for Dart applications.

It provides one portable Server contract and explicit runtime entrypoints for:

• dart
• node
• bun
• deno
• cloudflare
• vercel
• netlify

osrv is a runtime layer focused on running the same server contract across different host families, while keeping runtime capabilities and host-specific extensions explicit.

Why osrv

Use osrv when you want:

• one request-handling contract across multiple runtime families
• explicit runtime selection instead of host auto-detection
• honest capability reporting instead of fake cross-platform uniformity
• typed runtime extensions for host-specific access

Features

• Unified Server contract built around Request, Response, and RequestContext
• Explicit runtime selection through runtime-specific serve(...) or defineFetchExport(...)
• Runtime capability model via RuntimeCapabilities
• Request-scoped websocket upgrades on supported runtimes through package:osrv/websocket.dart
• Lifecycle hooks: onStart, onStop, and onError
• Typed runtime-specific extension access
• Separate entry models for listener runtimes and fetch-export runtimes

Installation

dart pub add osrv

Supported Runtimes

Runtime	Entry model	Import
dart	serve(server, host: ..., port: ...)	package:osrv/runtime/dart.dart
node	serve(server, host: ..., port: ...)	package:osrv/runtime/node.dart
bun	serve(server, host: ..., port: ...)	package:osrv/runtime/bun.dart
deno	serve(server, host: ..., port: ...)	package:osrv/runtime/deno.dart
cloudflare	defineFetchExport(server)	package:osrv/runtime/cloudflare.dart
vercel	defineFetchExport(server)	package:osrv/runtime/vercel.dart
netlify	defineFetchExport(server)	package:osrv/runtime/netlify.dart

Target notes:

• package:osrv/runtime/dart.dart is the native Dart listener entry.
• package:osrv/runtime/node.dart, package:osrv/runtime/bun.dart, package:osrv/runtime/deno.dart, package:osrv/runtime/cloudflare.dart, package:osrv/runtime/vercel.dart, and package:osrv/runtime/netlify.dart are JavaScript-target runtime entries and intentionally do not compile to native executables.

Quick Start

Serve-Based Runtime

import 'package:osrv/osrv.dart';
import 'package:osrv/runtime/dart.dart';

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

  final runtime = await serve(
    server,
    host: '127.0.0.1',
    port: 3000,
  );

  print('Listening on ${runtime.url}');
}

Fetch-Export Runtime

import 'package:osrv/osrv.dart';
import 'package:osrv/runtime/cloudflare.dart';

void main() {
  defineFetchExport(
    Server(
      fetch: (request, context) => Response.text('Hello from osrv'),
    ),
  );
}

Example JavaScript shim:

import './cloudflare.dart.js';

export default { fetch: globalThis.__osrv_fetch__ };

For Vercel, use a bootstrap entry that sets globalThis.self ??= globalThis before importing the compiled Dart module. The deploying project must also include @vercel/functions, use an ESM entry such as .mjs, and provide a minimal vercel.json. See doc/runtime/vercel.md.

Core API

The public core entrypoints are:

• package:osrv/osrv.dart
• package:osrv/websocket.dart for websocket-specific types

Main exported concepts:

• Server
• Runtime
• RequestContext
• RuntimeCapabilities
• RuntimeExtension

For runtime entry APIs, use the matching runtime entrypoint such as package:osrv/runtime/dart.dart, package:osrv/runtime/node.dart, package:osrv/runtime/bun.dart, package:osrv/runtime/cloudflare.dart, or package:osrv/runtime/vercel.dart.

Documentation

• Documentation Index
• Architecture
• Configuration
• Capabilities
• Core API
• Runtime API
• Public Surface
• Runtime Guides
• Usage Examples

Local CI

You can run the repository's GitHub Actions workflow locally before pushing.

Preferred path:

brew install act
./tool/ci_local.sh

That runs .github/workflows/ci.yml locally through nektos/act, which is specifically designed to execute GitHub Actions on your machine using Docker.

Useful variants:

./tool/ci_local.sh analyze
./tool/ci_local.sh --job test-unit
./tool/ci_local.sh --job test-node-integration
./tool/ci_local.sh --native

--native skips act and runs the CI-equivalent commands directly. This is useful when you want fast local verification or do not have act installed.

The repository keeps black-box runtime checks under integration_test/. Each runtime has its own folder and app-shaped fixture layout, for example integration_test/node/app/ or integration_test/cloudflare/app/, so host-specific bootstrap files can live next to the behavior tests that use them. These are still plain package:test suites for this pure Dart package, and the local runner / CI invoke them explicitly. The top-level test/ directory is reserved for portable tests only.

Examples

The example directory contains runnable minimal entries for:

• dart
• node
• bun
• cloudflare
• vercel

License

MIT