@b9g/platform-bun 0.1.15 → 0.1.17

package/README.md

@@ -1,83 +1,124 @@
 # @b9g/platform-bun
 
-Bun platform adapter for Shovel. Runs ServiceWorker applications on Bun with native HTTP server integration and fast hot reloading.
+Bun platform adapter for Shovel. Runs ServiceWorker applications on [Bun](https://bun.sh) with native HTTP server, WebSocket support, and OS-level load balancing via `reusePort`.
 
 ## Features
 
-- Bun HTTP server integration
-- Fast hot module reloading
-- Worker thread support for concurrency
-- Memory and filesystem cache backends
-- File System Access API implementation via BunBucket
+- Native `Bun.serve()` HTTP + WebSocket server
+- Built-in TypeScript/JSX support (no transpilation step)
+- Worker threads with `reusePort` for zero-overhead load balancing
+- Hot module reloading for development
+- ServiceWorker lifecycle support (install, activate, fetch events)
+- File System Access API via `@b9g/filesystem`
 
 ## Installation
 
 ```bash
-bun install @b9g/platform-bun
+bun add @b9g/platform-bun
 ```
 
 ## Usage
 
-```javascript
-import BunPlatform from '@b9g/platform-bun';
+### ServiceWorker Application
 
-const platform = new BunPlatform({
-  cache: { type: 'memory' },
-  filesystem: { type: 'local', directory: './dist' }
-});
+```typescript
+import BunPlatform from "@b9g/platform-bun";
 
-const server = platform.createServer(async (request) => {
-  return new Response('Hello from Bun');
-}, { port: 7777, host: 'localhost' });
+const platform = new BunPlatform({port: 3000, workers: 4});
+await platform.serviceWorker.register("./dist/server/worker.js");
+await platform.serviceWorker.ready;
+await platform.listen();
+```
+
+### Standalone Server
+
+```typescript
+import BunPlatform from "@b9g/platform-bun";
 
+const platform = new BunPlatform();
+const server = platform.createServer(async (request) => {
+  return new Response("Hello from Bun");
+});
 await server.listen();
 ```
 
 ## Exports
 
-### Classes
+- **`BunPlatform`** (default) -- Main platform class
+- **`BunServiceWorkerContainer`** -- ServiceWorker container managing worker lifecycle
+- **`BunPlatformOptions`** -- Constructor options type
+- **`DefaultCache`** -- Re-exported `MemoryCache` for config references
 
-- `BunPlatform` - Bun platform implementation (extends BasePlatform)
+## API
 
-### Types
+### `new BunPlatform(options?)`
 
-- `BunPlatformOptions` - Configuration options for BunPlatform
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | `number` | `7777` | Server port |
+| `host` | `string` | `"localhost"` | Server host |
+| `cwd` | `string` | `process.cwd()` | Working directory |
+| `workers` | `number` | `1` | Number of worker threads |
+| `config` | `ShovelConfig` | -- | Shovel config (caches, directories) |
 
-### Re-exports from @b9g/platform
+### `platform.createServer(handler, options?)`
 
-- `Platform`, `CacheConfig`, `StaticConfig`, `Handler`, `Server`, `ServerOptions`
+Creates a Bun HTTP server with WebSocket upgrade support.
 
-### Default Export
+- **`handler`**: `(request: Request) => Promise<Response | HandleResult>`
+- **`options.port`**: Override port
+- **`options.host`**: Override host
+- **`options.reusePort`**: Enable OS-level load balancing (used in multi-worker production)
 
-- `BunPlatform` - The platform class
+Returns a `Server` with `listen()`, `close()`, `url`, `address()`, and `ready`.
 
-## API
+### `platform.serviceWorker`
 
-### `new BunPlatform(options?)`
+`BunServiceWorkerContainer` implementing the standard `ServiceWorkerContainer` interface:
+
+- **`register(scriptURL, options?)`** -- Register a ServiceWorker, spawns worker threads
+- **`ready`** -- Promise resolving when registration is active
+- **`getRegistration(scope?)`** / **`getRegistrations()`** -- Query registrations
+
+### `platform.getEntryPoints(userEntryPath, mode)`
+
+Returns generated entry point code for bundling. Used by the build system.
+
+- **Development**: `{worker}` -- Single worker with message loop
+- **Production**: `{supervisor, worker}` -- Supervisor spawns workers with `reusePort`
 
-Creates a new Bun platform instance.
+### `platform.getESBuildConfig()`
 
-**Options:**
-- `cache`: Cache configuration (memory, filesystem)
-- `filesystem`: Filesystem configuration (local directory)
-- `port`: Default port (default: 7777)
-- `host`: Default host (default: localhost)
-- `cwd`: Working directory for file resolution
+Returns Bun-specific esbuild configuration: `platform: "node"`, externals for `node:*`, `bun`, `bun:*`, and Node.js builtins.
 
-### `platform.createServer(handler, options)`
+## Worker Architecture
 
-Creates a Bun HTTP server with the given request handler.
+### Development
 
-**Options:**
-- `port`: Port to listen on
-- `host`: Host to bind to
+Single worker managed by the `shovel develop` CLI. The develop command owns the HTTP server; the worker handles requests via message loop.
+
+### Production
+
+Each worker creates its own `Bun.serve()` with `reusePort`, letting the OS kernel load-balance connections. No message passing overhead between supervisor and workers.
+
+```
+Supervisor (index.js)
+  ├── Worker 1 (worker.js) ── Bun.serve(:3000, reusePort)
+  ├── Worker 2 (worker.js) ── Bun.serve(:3000, reusePort)
+  └── Worker N (worker.js) ── Bun.serve(:3000, reusePort)
+```
 
-Returns a Server instance with `listen()` and `close()` methods.
+The supervisor handles graceful shutdown (SIGINT/SIGTERM) and BroadcastChannel relay between workers.
 
-## Cache Backends
+## How It Differs from @b9g/platform-node
 
-- `memory`: In-memory caching using MemoryCache
-- `filesystem`: Filesystem-based caching using BunBucket
+| | Bun | Node.js |
+|---|---|---|
+| **HTTP** | `Bun.serve()` | `node:http` + `ws` |
+| **WebSocket** | Built-in | Requires `ws` package |
+| **Load balancing** | OS-level via `reusePort` | Round-robin message passing |
+| **TypeScript** | Native support | VM module transpilation |
+| **Multi-worker** | Each worker binds own port | Supervisor distributes requests |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform-bun",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Bun platform adapter for Shovel with hot reloading and built-in TypeScript/JSX support",
   "keywords": [
     "shovel",
@@ -13,15 +13,15 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/bikeshaving/shovel.git",
+    "url": "git+https://github.com/bikeshaving/shovel.git",
     "directory": "packages/platform-bun"
   },
   "dependencies": {
     "@b9g/assets": "^0.2.1",
     "@b9g/cache": "^0.2.2",
     "@b9g/http-errors": "^0.2.1",
-    "@b9g/platform": "^0.1.17",
-    "@logtape/logtape": "^1.2.0"
+    "@b9g/platform": "^0.1.19",
+    "@logtape/logtape": "^2.0.0"
   },
   "devDependencies": {
     "@b9g/libuild": "^0.1.18"

package/src/index.js

@@ -1,5 +1,5 @@
 /// <reference types="./index.d.ts" />
-// src/index.ts
+// packages/platform-bun/src/index.ts
 import { builtinModules } from "node:module";
 import { tmpdir } from "node:os";
 import * as Path from "node:path";
@@ -250,7 +250,7 @@ var BunPlatform = class {
     const prodWorkerCode = `// Bun Production Worker
 import BunPlatform from "@b9g/platform-bun";
 import {getLogger} from "@logtape/logtape";
-import {configureLogging, initWorkerRuntime, runLifecycle, dispatchRequest} from "@b9g/platform/runtime";
+import {configureLogging, initWorkerRuntime, runLifecycle, dispatchRequest, setBroadcastChannelRelay, deliverBroadcastMessage} from "@b9g/platform/runtime";
 import {config} from "shovel:config";
 
 await configureLogging(config.logging);
@@ -260,13 +260,15 @@ const logger = getLogger(["shovel", "platform"]);
 let server;
 let databases;
 
-// Register shutdown handler before async startup
+// Register message handler for shutdown and broadcast relay
 self.onmessage = async (event) => {
 	if (event.data.type === "shutdown") {
 		logger.info("Worker shutting down");
 		if (server) await server.close();
 		if (databases) await databases.closeAll();
 		postMessage({type: "shutdown-complete"});
+	} else if (event.data.type === "broadcast:deliver") {
+		deliverBroadcastMessage(event.data.channel, event.data.data);
 	}
 };
 
@@ -275,6 +277,11 @@ const result = await initWorkerRuntime({config, usePostMessage: false});
 const registration = result.registration;
 databases = result.databases;
 
+// Set up broadcast relay (posts go to supervisor for fan-out to other workers)
+setBroadcastChannelRelay((channelName, data) => {
+	postMessage({type: "broadcast:post", channel: channelName, data});
+});
+
 // Import user code (registers event handlers)
 await import("${userEntryPath}");
 

package/src/platform.js

@@ -1,5 +1,5 @@
 /// <reference types="./platform.d.ts" />
-// src/platform.ts
+// packages/platform-bun/src/platform.ts
 import { builtinModules } from "node:module";
 import { getLogger } from "@logtape/logtape";
 var logger = getLogger(["shovel", "platform"]);