@fluojs/platform-bun

@fluojs/platform-bun

English 한국어

Bun-backed HTTP adapter for the fluo runtime, built on native Bun.serve().

Table of Contents

• Installation
• When to Use
• Quick Start
• Common Patterns
• Public API Overview
• Adapter Contract
• Conformance Coverage
• Related Packages
• Example Sources

Installation

npm install @fluojs/platform-bun

This package is intended to run on Bun. The published manifest intentionally does not declare engines.node, so npm metadata stays aligned with the Bun runtime contract; the repository's Node.js 20+ requirement only applies to the maintainer build/test toolchain.

When to Use

Use this package when running fluo applications on the Bun runtime. This adapter leverages Bun's high-performance Request/Response bridge and native fetch-style architecture, providing a seamless and fast experience for Bun users.

During application shutdown, the adapter stops all new ingress, including websocket upgrade attempts, with a 503 shutdown response and gives every accepted request a bounded drain window that covers realtime binding evaluation through its HTTP response or upgrade outcome before Bun forcefully tears the server down. If signal-driven shutdown exceeds forceExitTimeoutMs or fails, fluo reports that condition through logging and process.exitCode while leaving final process termination to Bun or the surrounding host.

Quick Start

import { createBunAdapter } from '@fluojs/platform-bun';
import { fluoFactory } from '@fluojs/runtime';
import { AppModule } from './app.module';

const app = await fluoFactory.create(AppModule, {
  adapter: createBunAdapter({ port: 3000 }),
});

await app.listen();

Common Patterns

Manual Fetch Handling

If you prefer to manage the Bun server yourself, you can use the fetch handler directly. The dispatcher should come from the already bootstrapped application via app.getHttpDispatcher(). createBunFetchHandler(...) synchronously creates the fetch bridge and preserves raw-body and multipart request parsing, while shutdown ownership, websocket upgrades, and native routes acceleration remain responsibilities of the surrounding Bun.serve(...) host or the managed adapter path.

import { createBunFetchHandler } from '@fluojs/platform-bun';

const handler = createBunFetchHandler({
  dispatcher: app.getHttpDispatcher(),
});

Bun.serve({
  fetch: handler,
  port: 3000,
});

Native WebSocket Upgrade

The adapter supports Bun's native server.upgrade() through the @fluojs/websockets/bun binding.

// gateways automatically use Bun's native upgrade when the Bun adapter is active
@WebSocketGateway({ path: '/ws' })
export class MyGateway {}

Native routes Object Acceleration

On Bun >=1.2.3, the adapter opportunistically registers safe static and parameterized fluo routes through Bun.serve({ routes }) while still routing matched requests back through the shared fluo dispatcher.

For semantically safe unversioned routes, Bun hands the pre-matched descriptor and params to the shared dispatcher so duplicate route matching is skipped while raw body, multipart, SSE, error responses, shutdown drain behavior, and websocket upgrade delegation stay on the same shared execution path. If route shape parity is unsafe, such as same-shape parameter routes with different param names, ALL-method handlers, normalization-sensitive paths, or non-URI versioning, the adapter falls back to fetch-only dispatch for those routes instead of changing fluo semantics.

If app middleware rewrites the framework request method or path after a Bun native handoff is attached, the dispatcher discards that stale handoff and rematches the rewritten request. Unsupported methods such as OPTIONS and CORS preflight behavior remain owned by the shared dispatcher/middleware path unless a fluo route explicitly owns them.

Public API Overview

• createBunAdapter(options): Recommended factory for the Bun adapter.
• createBunFetchHandler(options): Creates a native fetch(request) handler for custom Bun.serve() setups.
• bootstrapBunApplication(module, options): Advanced bootstrap without implicit startup logging.
• runBunApplication(module, options): Compatibility helper for quick startup with signal wiring.

The adapter also exports the typed Bun integration seams used by realtime packages:

• BunHttpApplicationAdapter: HttpApplicationAdapter implementation backed by Bun.serve().
• BunAdapterOptions: host, port, TLS, raw-body, multipart, and shutdown options accepted by createBunAdapter().
• BootstrapBunApplicationOptions and RunBunApplicationOptions: application bootstrap/run options for Bun-hosted apps.
• BunWebSocketBinding, BunWebSocketUpgradeHost, and BunRealtimeBindingHost: binding contracts used by @fluojs/websockets/bun before normal HTTP dispatch. Bindings receive only an upgrade-capable host, not the adapter-owned Bun server lifecycle or raw fetch handler.
• BunWebSocketBindingHost: Backward-compatible alias for configuring Bun realtime bindings.
• BunServeOptions, BunServerLike, BunWebSocketHandler, BunServerWebSocket, BunWebSocketMessage, BunApplicationSignal, BunCorsInput, BunTlsOptions, and CreateBunFetchHandlerOptions: Lower-level Bun host, websocket, signal, CORS, TLS, and fetch-handler integration types.

Adapter Contract

• Runtime host: This package requires globalThis.Bun.serve() at listen time. Tests may provide a Bun-compatible test double, but production use is Bun-only.
• Request portability: Fetch requests are translated through the shared web dispatcher, preserving malformed cookie values, query arrays, JSON/text raw bodies when rawBody: true, byte-exact request handoff for custom createBunFetchHandler(...) setups, and SSE framing.
• Native route acceleration: When Bun's routes object is available and a fluo route shape is semantically safe to pre-register, the adapter lets Bun short-circuit path matching before handing the request back to the shared dispatcher. Unsupported or ambiguous route shapes fall back to the regular fetch path, and stale handoffs are ignored if middleware rewrites method/path before handler matching.
• Native route gate: Native routes are enabled only on Bun >=1.2.3; the adapter omits the routes option entirely unless safe native-route entries are concretely enabled. Versioned routes, ALL handlers, same-shape conflicts, normalization-sensitive paths, and OPTIONS/CORS preflight stay on the fetch/shared-dispatch path.
• Multipart behavior: Multipart requests never expose rawBody, and multipart limits continue to flow through the shared runtime parser.
• Startup target: hostname, port, and tls are forwarded to Bun.serve(). Startup logs report the configured HTTP or HTTPS listen URL.
• Lifecycle guards: listen() is idempotent for an already-started adapter and keeps the original live dispatcher binding. Realtime/websocket bindings must be configured before listen() starts; later attempts to set or clear the binding fail fast instead of being accepted without affecting live wiring.
• Shutdown ownership: close() stops new HTTP and websocket-upgrade ingress with a 503 shutdown response, waits for every accepted request from realtime binding evaluation through HTTP response or upgrade completion, clears adapter state after drain settles, and removes signal listeners registered by runBunApplication().
• Realtime seam: Bun websocket bindings must be configured before listen() starts the server. Upgrade requests are offered to the configured binding before falling back to HTTP dispatch while the adapter is accepting new ingress; an accepted request keeps its dispatcher available if shutdown begins during asynchronous binding evaluation, and HTTP fallback is suppressed only after the binding returns a response or successfully upgrades the request. The binding host exposes only upgrade(...), so adapter-owned stop() and raw fetch() control remain outside the realtime seam.
• Adapter instance helpers: BunHttpApplicationAdapter exposes getServer(), getListenTarget(), getRealtimeCapability(), configureRealtimeBinding(), configureWebSocketBinding(), listen(), and close().

Conformance Coverage

packages/platform-bun/src/adapter.test.ts is the package-local regression target for the documented contract. It includes Bun fetch-style portability assertions for malformed cookies, byte-exact JSON/text raw-body preservation, multipart raw-body exclusion for managed and custom fetch handlers, SSE framing, native-route param parity, same-path multi-method handoff, stale native handoff rematching after middleware rewrites the request path or method, versioning fallback, normalization-sensitive fallback, OPTIONS/CORS ownership, same-shape route fallback, and TLS listen-target reporting, plus focused tests for startup logging, duplicate listen idempotency, shutdown listener cleanup, in-flight drain behavior, close during asynchronous realtime binding evaluation, HTTP fallback after binding completion, timeout validation/reporting, shutdown 503 ingress rejection, signal-driven close rejection reporting, and websocket binding delegation/short-circuit behavior through an upgrade-only host.

The broader repository suite also exercises Bun through createWebRuntimeHttpAdapterPortabilityHarness(...) alongside Deno and Cloudflare Workers in packages/testing/src/portability/web-runtime-adapter-portability.test.ts, keeping the shared web-runtime portability baseline aligned across fetch-style platforms.

Related Packages

• @fluojs/runtime: Core framework runtime.
• @fluojs/websockets: Includes specific subpath @fluojs/websockets/bun.
• @fluojs/socket.io: Supports the native Bun engine.

Example Sources

• packages/platform-bun/src/adapter.test.ts
• packages/websockets/src/bun/bun.test.ts