@fluojs/platform-express 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,86 @@
+# @fluojs/platform-express
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 런타임을 위한 Express 기반 HTTP 어댑터 패키지입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/platform-express express
+```
+
+## 사용 시점
+
+fluo 애플리케이션의 기본 HTTP 엔진으로 Express를 사용하려는 경우에 이 패키지를 사용합니다. 이는 fluo의 데코레이터 기반 아키텍처 내에서 Express의 강력한 생태계, 성숙한 Node.js 서버 처리 및 친숙한 요청/응답 생명주기를 활용하는 데 유용합니다.
+
+## 빠른 시작
+
+```typescript
+import { createExpressAdapter } from '@fluojs/platform-express';
+import { fluoFactory } from '@fluojs/runtime';
+import { AppModule } from './app.module';
+
+const app = await fluoFactory.create(AppModule, {
+  adapter: createExpressAdapter({ port: 3000 }),
+});
+
+await app.listen();
+```
+
+## 주요 패턴
+
+### 스트리밍 응답 처리 (SSE)
+Express 어댑터는 공유 `SseResponse` 유틸리티를 통해 Server-Sent Events(SSE)를 지원하며, Express 전용 스트림 처리를 추상화합니다.
+
+```typescript
+@Get('events')
+async streamEvents(@Res() res: FrameworkResponse) {
+  const events = new SseResponse();
+  events.send({ data: 'hello' });
+  return events;
+}
+```
+
+### 바디 파싱 및 멀티파트
+`rawBody` 및 멀티파트 form-data 파싱을 즉시 사용할 수 있습니다. 어댑터를 직접 생성할 때는 멀티파트 제한을 두 번째 인자로 전달하고, `bootstrapExpressApplication(...)` 및 `runExpressApplication(...)`에서는 같은 설정을 `options.multipart` 아래에 전달하면 됩니다.
+
+```typescript
+const adapter = createExpressAdapter(
+  {
+    port: 3000,
+    rawBody: true,
+  },
+  {
+    maxTotalSize: 10 * 1024 * 1024,
+  },
+);
+```
+
+## 공개 API 개요
+
+- `createExpressAdapter(options)`: Express HTTP 어댑터를 위한 팩토리입니다.
+- `bootstrapExpressApplication(module, options)`: 수동 제어를 위한 고급 부트스트랩 헬퍼입니다.
+- `runExpressApplication(module, options)`: 시그널 연결을 포함한 빠른 시작을 위한 호환 헬퍼입니다. timeout/실패 시에는 해당 상태를 로그와 `process.exitCode`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
+- `ExpressHttpApplicationAdapter`: 핵심 어댑터 구현 클래스입니다.
+
+## 관련 패키지
+
+- `@fluojs/runtime`: 핵심 프레임워크 런타임입니다.
+- `@fluojs/platform-fastify`: 고성능을 지향하는 대안 어댑터입니다.
+- `@fluojs/websockets`: Express를 위한 실시간 게이트웨이 지원을 제공합니다.
+
+## 예제 소스
+
+- `packages/platform-express/src/adapter.test.ts`
+- `examples/minimal/src/main.ts` (Fastify 기반이지만 공유 `fluoFactory` 패턴을 보여줌)

package/README.md

@@ -0,0 +1,86 @@
+# @fluojs/platform-express
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Express-backed HTTP adapter for the fluo runtime.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/platform-express express
+```
+
+## When to Use
+
+Use this package when you want to run a fluo application using Express as the underlying HTTP engine. This is useful for leveraging Express's robust ecosystem, mature Node.js server handling, and familiar request/response lifecycle within the fluo decorator-based architecture.
+
+## Quick Start
+
+```typescript
+import { createExpressAdapter } from '@fluojs/platform-express';
+import { fluoFactory } from '@fluojs/runtime';
+import { AppModule } from './app.module';
+
+const app = await fluoFactory.create(AppModule, {
+  adapter: createExpressAdapter({ port: 3000 }),
+});
+
+await app.listen();
+```
+
+## Common Patterns
+
+### Handling Streaming Responses (SSE)
+The Express adapter supports Server-Sent Events (SSE) via the shared `SseResponse` utility, abstracting away the Express-specific stream handling.
+
+```typescript
+@Get('events')
+async streamEvents(@Res() res: FrameworkResponse) {
+  const events = new SseResponse();
+  events.send({ data: 'hello' });
+  return events;
+}
+```
+
+### Body Parsing and Multipart
+The adapter handles `rawBody` and multipart form-data parsing out of the box. When you construct the adapter directly, pass multipart limits as the second argument. `bootstrapExpressApplication(...)` and `runExpressApplication(...)` accept the same multipart settings under `options.multipart`.
+
+```typescript
+const adapter = createExpressAdapter(
+  {
+    port: 3000,
+    rawBody: true,
+  },
+  {
+    maxTotalSize: 10 * 1024 * 1024,
+  },
+);
+```
+
+## Public API Overview
+
+- `createExpressAdapter(options)`: Factory for the Express HTTP adapter.
+- `bootstrapExpressApplication(module, options)`: Advanced bootstrap helper for manual control.
+- `runExpressApplication(module, options)`: Compatibility helper for quick startup with signal wiring. On timeout/failure it reports the condition through logging and `process.exitCode`, while leaving final process termination to the surrounding host.
+- `ExpressHttpApplicationAdapter`: The core adapter implementation class.
+
+## Related Packages
+
+- `@fluojs/runtime`: Core framework runtime.
+- `@fluojs/platform-fastify`: Alternative high-performance adapter.
+- `@fluojs/websockets`: Real-time gateway support for Express.
+
+## Example Sources
+
+- `packages/platform-express/src/adapter.test.ts`
+- `examples/minimal/src/main.ts` (Fastify-based, but demonstrates the shared `fluoFactory` pattern)

package/dist/adapter.d.ts

@@ -0,0 +1,77 @@
+import { type ServerOptions as HttpsServerOptions } from 'node:https';
+import { type CorsOptions, type Dispatcher, type HttpApplicationAdapter, type MiddlewareLike, type SecurityHeadersOptions } from '@fluojs/http';
+import type { Application, ApplicationLogger, CreateApplicationOptions, ModuleType, MultipartOptions, UploadedFile } from '@fluojs/runtime';
+declare module '@fluojs/http' {
+    interface FrameworkRequest {
+        files?: UploadedFile[];
+        rawBody?: Uint8Array;
+    }
+}
+export interface ExpressAdapterOptions {
+    host?: string;
+    https?: HttpsServerOptions;
+    maxBodySize?: number;
+    port?: number;
+    rawBody?: boolean;
+    retryDelayMs?: number;
+    retryLimit?: number;
+    shutdownTimeoutMs?: number;
+}
+export type ExpressApplicationSignal = 'SIGINT' | 'SIGTERM';
+export type CorsInput = false | string | string[] | CorsOptions;
+export interface BootstrapExpressApplicationOptions extends Omit<CreateApplicationOptions, 'adapter' | 'logger' | 'middleware'> {
+    cors?: CorsInput;
+    globalPrefix?: string;
+    globalPrefixExclude?: readonly string[];
+    host?: string;
+    https?: HttpsServerOptions;
+    logger?: ApplicationLogger;
+    maxBodySize?: number;
+    middleware?: MiddlewareLike[];
+    multipart?: MultipartOptions;
+    port?: number;
+    rawBody?: boolean;
+    retryDelayMs?: number;
+    retryLimit?: number;
+    securityHeaders?: false | SecurityHeadersOptions;
+    shutdownTimeoutMs?: number;
+}
+export interface RunExpressApplicationOptions extends BootstrapExpressApplicationOptions {
+    forceExitTimeoutMs?: number;
+    shutdownSignals?: false | readonly ExpressApplicationSignal[];
+}
+interface ExpressListenTarget {
+    bindTarget: string;
+    url: string;
+}
+export declare class ExpressHttpApplicationAdapter implements HttpApplicationAdapter {
+    private readonly port;
+    private readonly host;
+    private readonly retryDelayMs;
+    private readonly retryLimit;
+    private readonly httpsOptions;
+    private readonly multipartOptions?;
+    private readonly maxBodySize;
+    private readonly preserveRawBody;
+    private readonly shutdownTimeoutMs;
+    private closeInFlight?;
+    private dispatcher?;
+    private readonly app;
+    private readonly requestResponseFactory;
+    private readonly server;
+    private readonly sockets;
+    constructor(port: number, host: string | undefined, retryDelayMs: number | undefined, retryLimit: number | undefined, httpsOptions: HttpsServerOptions | undefined, multipartOptions?: MultipartOptions | undefined, maxBodySize?: number, preserveRawBody?: boolean, shutdownTimeoutMs?: number);
+    getServer(): unknown;
+    getRealtimeCapability(): import("@fluojs/http").ServerBackedHttpAdapterRealtimeCapability;
+    getListenTarget(): ExpressListenTarget;
+    listen(dispatcher: Dispatcher): Promise<void>;
+    close(): Promise<void>;
+    private listenWithRetry;
+    private handleRequest;
+}
+export declare function createExpressAdapter(options?: ExpressAdapterOptions, multipartOptions?: MultipartOptions): HttpApplicationAdapter;
+export declare function bootstrapExpressApplication(rootModule: ModuleType, options: BootstrapExpressApplicationOptions): Promise<Application>;
+export declare function runExpressApplication(rootModule: ModuleType, options: RunExpressApplicationOptions): Promise<Application>;
+export declare function isExpressMultipartTooLargeError(error: unknown): boolean;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -0,0 +1,612 @@
+import { createServer as createHttpServer } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { Readable } from 'node:stream';
+import { URL } from 'node:url';
+import express from 'express';
+import { BadRequestException, createServerBackedHttpAdapterRealtimeCapability, createErrorResponse, HttpException, InternalServerErrorException, PayloadTooLargeException } from '@fluojs/http';
+import { createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/runtime/node';
+import { parseMultipart } from '@fluojs/runtime/web';
+import { bootstrapHttpAdapterApplication, runHttpAdapterApplication } from '@fluojs/runtime/internal/http-adapter';
+import { dispatchWithRequestResponseFactory } from '@fluojs/runtime/internal/request-response-factory';
+const DEFAULT_MAX_BODY_SIZE = 1 * 1024 * 1024;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+export class ExpressHttpApplicationAdapter {
+  closeInFlight;
+  dispatcher;
+  app;
+  requestResponseFactory;
+  server;
+  sockets = new Set();
+  constructor(port, host, retryDelayMs = 150, retryLimit = 20, httpsOptions, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+    this.port = port;
+    this.host = host;
+    this.retryDelayMs = retryDelayMs;
+    this.retryLimit = retryLimit;
+    this.httpsOptions = httpsOptions;
+    this.multipartOptions = multipartOptions;
+    this.maxBodySize = maxBodySize;
+    this.preserveRawBody = preserveRawBody;
+    this.shutdownTimeoutMs = shutdownTimeoutMs;
+    this.app = express();
+    this.requestResponseFactory = createExpressRequestResponseFactory(this.multipartOptions, this.maxBodySize, this.preserveRawBody);
+    this.server = createExpressServer(this.httpsOptions, this.app);
+    this.app.use((request, response) => {
+      void this.handleRequest(request, response);
+    });
+    this.server.on('connection', socket => {
+      this.sockets.add(socket);
+      socket.once('close', () => {
+        this.sockets.delete(socket);
+      });
+    });
+  }
+  getServer() {
+    return this.server;
+  }
+  getRealtimeCapability() {
+    return createServerBackedHttpAdapterRealtimeCapability(this.server);
+  }
+  getListenTarget() {
+    return resolveListenTarget(this.server.address() ?? null, this.port, this.host, this.httpsOptions !== undefined);
+  }
+  async listen(dispatcher) {
+    this.dispatcher = dispatcher;
+    await this.listenWithRetry();
+  }
+  async close() {
+    if (!this.server.listening) {
+      this.dispatcher = undefined;
+      return;
+    }
+    if (!this.closeInFlight) {
+      const closePromise = closeServerWithDrain(this.server, this.sockets, this.shutdownTimeoutMs);
+      const closeInFlight = closePromise.finally(() => {
+        this.closeInFlight = undefined;
+        this.dispatcher = undefined;
+      });
+      this.closeInFlight = closeInFlight;
+      void closeInFlight.catch(() => {});
+    }
+    const closeInFlight = this.closeInFlight;
+    if (!closeInFlight) {
+      return;
+    }
+    await waitForCloseWithTimeout(closeInFlight, this.shutdownTimeoutMs);
+  }
+  async listenWithRetry() {
+    for (let attempt = 0;; attempt++) {
+      try {
+        await listenServer(this.server, this.port, this.host);
+        return;
+      } catch (error) {
+        if (!isAddressInUseError(error) || attempt >= this.retryLimit) {
+          throw error;
+        }
+        await closeServerSilently(this.server);
+        await delay(this.retryDelayMs);
+      }
+    }
+  }
+  async handleRequest(request, response) {
+    await dispatchWithRequestResponseFactory({
+      dispatcher: this.dispatcher,
+      dispatcherNotReadyMessage: 'Express adapter received a request before dispatcher binding completed.',
+      factory: this.requestResponseFactory,
+      rawRequest: request,
+      rawResponse: response
+    });
+  }
+}
+function createExpressRequestResponseFactory(multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
+  return {
+    async createRequest(request, signal) {
+      return createFrameworkRequest(request, signal, multipartOptions, maxBodySize, preserveRawBody);
+    },
+    createRequestSignal(response) {
+      return createRequestSignal(response);
+    },
+    createResponse(response) {
+      return createFrameworkResponse(response);
+    },
+    resolveRequestId(request) {
+      return resolveRequestIdFromHeaders(request.headers);
+    },
+    async writeErrorResponse(error, response, requestId) {
+      const httpError = toHttpException(error);
+      response.setStatus(httpError.status);
+      await response.send(createErrorResponse(httpError, requestId));
+    }
+  };
+}
+export function createExpressAdapter(options = {}, multipartOptions) {
+  return new ExpressHttpApplicationAdapter(resolvePort(options.port), options.host, options.retryDelayMs, options.retryLimit, options.https, multipartOptions, options.maxBodySize, options.rawBody, options.shutdownTimeoutMs);
+}
+export async function bootstrapExpressApplication(rootModule, options) {
+  return bootstrapHttpAdapterApplication(rootModule, options, createExpressAdapter(options, options.multipart));
+}
+export async function runExpressApplication(rootModule, options) {
+  const adapter = createExpressAdapter(options, options.multipart);
+  return runHttpAdapterApplication(rootModule, {
+    ...options,
+    shutdownRegistration: createNodeShutdownSignalRegistration(options.shutdownSignals ?? defaultNodeShutdownSignals())
+  }, adapter);
+}
+function createFrameworkResponse(response) {
+  return {
+    committed: response.headersSent || response.writableEnded,
+    headers: {},
+    raw: response,
+    stream: createFrameworkResponseStream(response),
+    redirect(status, location) {
+      this.setStatus(status);
+      this.setHeader('Location', location);
+      this.committed = true;
+      response.redirect(status, location);
+    },
+    async send(body) {
+      if (response.writableEnded) {
+        this.committed = true;
+        return;
+      }
+      const existingContentType = response.getHeader('content-type');
+      const serialized = serializeResponseBody(body, typeof existingContentType === 'string' ? existingContentType : undefined);
+      if (!response.hasHeader('content-type') && serialized.defaultContentType) {
+        response.setHeader('content-type', serialized.defaultContentType);
+      }
+      this.committed = true;
+      response.send(serialized.payload);
+    },
+    setHeader(name, value) {
+      const lowerName = name.toLowerCase();
+      if (lowerName === 'set-cookie') {
+        const merged = mergeSetCookieHeader(response.getHeader(name), value);
+        response.setHeader(name, merged);
+        this.headers[name] = merged;
+        return;
+      }
+      response.setHeader(name, value);
+      this.headers[name] = value;
+    },
+    setStatus(code) {
+      response.status(code);
+      this.statusCode = code;
+      this.statusSet = true;
+    },
+    statusCode: undefined,
+    statusSet: false
+  };
+}
+function createFrameworkResponseStream(response) {
+  return {
+    close() {
+      if (!response.writableEnded) {
+        response.end();
+      }
+    },
+    get closed() {
+      return response.writableEnded;
+    },
+    flush() {
+      response.flushHeaders?.();
+    },
+    onClose(listener) {
+      response.on('close', listener);
+      return () => {
+        response.removeListener('close', listener);
+      };
+    },
+    waitForDrain() {
+      if (response.writableEnded) {
+        return Promise.resolve();
+      }
+      return new Promise(resolve => {
+        response.once('drain', () => resolve());
+      });
+    },
+    write(chunk) {
+      return response.write(chunk);
+    }
+  };
+}
+async function createFrameworkRequest(request, signal, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
+  const rawUrl = request.originalUrl || request.url || '/';
+  const url = new URL(rawUrl, 'http://localhost');
+  const headers = normalizeHeaders(request.headers);
+  const contentType = readPrimaryHeaderValue(headers['content-type']);
+  const isMultipart = typeof contentType === 'string' && contentType.includes('multipart/form-data');
+  let body;
+  let files;
+  let rawBody;
+  if (isMultipart) {
+    const parsed = await parseMultipartRequest(request, multipartOptions);
+    body = parsed.fields;
+    files = parsed.files;
+  } else {
+    const bodyResult = await readRequestBody(request, headers['content-type'], maxBodySize, preserveRawBody);
+    body = bodyResult.body;
+    rawBody = bodyResult.rawBody;
+  }
+  const frameworkRequest = {
+    body,
+    cookies: parseCookieHeader(Array.isArray(headers.cookie) ? headers.cookie[0] : headers.cookie),
+    headers,
+    method: request.method,
+    params: {},
+    path: url.pathname,
+    query: parseQueryParams(url.searchParams),
+    raw: request,
+    signal,
+    url: url.pathname + url.search
+  };
+  if (files) {
+    frameworkRequest.files = files;
+  }
+  if (rawBody) {
+    frameworkRequest.rawBody = rawBody;
+  }
+  return frameworkRequest;
+}
+async function parseMultipartRequest(request, options = {}) {
+  try {
+    return await parseMultipart({
+      body: Readable.toWeb(request),
+      headers: normalizeHeaders(request.headers),
+      method: request.method,
+      url: new URL(request.url ?? '/', 'http://localhost').toString()
+    }, options);
+  } catch (error) {
+    if (isExpressMultipartTooLargeError(error)) {
+      if (error instanceof PayloadTooLargeException) {
+        throw error;
+      }
+      throw new PayloadTooLargeException('Request body exceeds the configured multipart limits.');
+    }
+    throw error;
+  }
+}
+export function isExpressMultipartTooLargeError(error) {
+  if (error instanceof PayloadTooLargeException) {
+    return true;
+  }
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const candidate = error;
+  if (candidate.statusCode === 413 || candidate.status === 413) {
+    return true;
+  }
+  if (typeof candidate.code === 'string' && /LIMIT|TOO_LARGE|ENTITY_TOO_LARGE|FILE_TOO_LARGE/i.test(candidate.code)) {
+    return true;
+  }
+  if (typeof candidate.type === 'string' && candidate.type.toLowerCase() === 'entity.too.large') {
+    return true;
+  }
+  return error.message.toLowerCase().includes('too large');
+}
+function normalizeHeaders(headers) {
+  const normalized = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (Array.isArray(value)) {
+      normalized[name] = value;
+      continue;
+    }
+    if (typeof value === 'number') {
+      normalized[name] = String(value);
+      continue;
+    }
+    if (typeof value === 'string' || value === undefined) {
+      normalized[name] = value;
+      continue;
+    }
+    normalized[name] = String(value);
+  }
+  return normalized;
+}
+function parseQueryParams(searchParams) {
+  const query = {};
+  for (const [key, value] of searchParams.entries()) {
+    const current = query[key];
+    if (current === undefined) {
+      query[key] = value;
+      continue;
+    }
+    if (Array.isArray(current)) {
+      current.push(value);
+      continue;
+    }
+    query[key] = [current, value];
+  }
+  return query;
+}
+function parseCookieHeader(cookieHeader) {
+  if (!cookieHeader) {
+    return {};
+  }
+  return Object.fromEntries(cookieHeader.split(';').map(pair => pair.trim()).filter(Boolean).map(pair => {
+    const index = pair.indexOf('=');
+    if (index === -1) {
+      return [pair.trim(), ''];
+    }
+    const rawValue = pair.slice(index + 1).trim();
+    try {
+      return [pair.slice(0, index).trim(), decodeURIComponent(rawValue)];
+    } catch {
+      return [pair.slice(0, index).trim(), rawValue];
+    }
+  }));
+}
+function createRequestSignal(response) {
+  const controller = new AbortController();
+  const abort = reason => {
+    if (!controller.signal.aborted) {
+      controller.abort(new Error(reason));
+    }
+  };
+  response.once('close', () => {
+    if (!response.writableEnded) {
+      abort('Response closed before response commit.');
+    }
+  });
+  return controller.signal;
+}
+function resolveRequestIdFromHeaders(headers) {
+  const requestId = headers['x-request-id'] ?? headers['x-correlation-id'];
+  return Array.isArray(requestId) ? requestId[0] : requestId;
+}
+function createExpressServer(httpsOptions, app) {
+  return httpsOptions ? createHttpsServer(httpsOptions, app) : createHttpServer(app);
+}
+function resolveListenTarget(address, port, host, useHttps) {
+  const protocol = useHttps ? 'https' : 'http';
+  const resolvedPort = typeof address === 'object' && address !== null ? address.port : port;
+  const bindHost = typeof address === 'object' && address !== null ? address.address : host ?? '0.0.0.0';
+  const publicHost = resolvePublicHost(host ?? bindHost);
+  const bindTarget = `${formatHostForAuthority(bindHost)}:${String(resolvedPort)}`;
+  const url = `${protocol}://${formatHostForAuthority(publicHost)}:${String(resolvedPort)}`;
+  return {
+    bindTarget,
+    url
+  };
+}
+function resolvePublicHost(host) {
+  return isWildcardHost(host) ? 'localhost' : host;
+}
+function isWildcardHost(host) {
+  return host === '0.0.0.0' || host === '::' || host === '[::]';
+}
+function formatHostForAuthority(host) {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+function resolvePort(value) {
+  const port = value ?? 3000;
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`Invalid PORT value: ${String(value ?? 3000)}.`);
+  }
+  return port;
+}
+async function listenServer(server, port, host) {
+  await new Promise((resolve, reject) => {
+    const onError = error => {
+      cleanup();
+      reject(error);
+    };
+    const onListening = () => {
+      cleanup();
+      resolve();
+    };
+    const cleanup = () => {
+      server.off('error', onError);
+      server.off('listening', onListening);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    try {
+      server.listen({
+        host,
+        port
+      });
+    } catch (error) {
+      cleanup();
+      reject(error);
+    }
+  });
+}
+function closeServerSilently(server) {
+  if (!server.listening) {
+    return Promise.resolve();
+  }
+  return new Promise(resolve => {
+    server.close(() => {
+      resolve();
+    });
+  });
+}
+function closeServerWithDrain(server, sockets, shutdownTimeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timeout = setTimeout(() => {
+      forceCloseConnections(server, sockets);
+    }, shutdownTimeoutMs);
+    const finish = error => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    };
+    server.close(error => {
+      finish(error);
+    });
+    closeIdleConnections(server);
+  });
+}
+function closeIdleConnections(server) {
+  server.closeIdleConnections?.();
+}
+function forceCloseConnections(server, sockets) {
+  if (typeof server.closeAllConnections === 'function') {
+    server.closeAllConnections();
+    return;
+  }
+  for (const socket of sockets) {
+    socket.destroy();
+  }
+}
+function toHttpException(error) {
+  if (error instanceof HttpException) {
+    return error;
+  }
+  return new InternalServerErrorException('Internal server error.', {
+    cause: error
+  });
+}
+function isAddressInUseError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.code === 'EADDRINUSE';
+}
+function delay(ms) {
+  return new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+}
+function waitForCloseWithTimeout(closePromise, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error(`Express adapter shutdown timeout exceeded ${String(timeoutMs)}ms.`));
+    }, timeoutMs);
+    void closePromise.then(() => {
+      clearTimeout(timeout);
+      resolve();
+    }, error => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+  });
+}
+function mergeSetCookieHeader(current, incoming) {
+  const nextValues = Array.isArray(incoming) ? incoming : [incoming];
+  if (current === undefined || typeof current === 'number') {
+    return nextValues.length === 1 ? nextValues[0] : [...nextValues];
+  }
+  const currentValues = Array.isArray(current) ? current : [current];
+  const merged = [...currentValues, ...nextValues];
+  return merged.length === 1 ? merged[0] : merged;
+}
+async function readRequestBody(request, contentType, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
+  const chunks = [];
+  let totalSize = 0;
+  for await (const chunk of request) {
+    const bufferChunk = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+    totalSize += bufferChunk.byteLength;
+    if (totalSize > maxBodySize) {
+      throw new PayloadTooLargeException('Request body exceeds the size limit.');
+    }
+    chunks.push(bufferChunk);
+  }
+  if (chunks.length === 0) {
+    return {
+      body: undefined
+    };
+  }
+  const rawBody = Buffer.concat(chunks);
+  const bodyText = rawBody.toString('utf8');
+  if (bodyText.length === 0) {
+    return {
+      body: undefined,
+      rawBody: preserveRawBody ? rawBody : undefined
+    };
+  }
+  const primaryContentType = readPrimaryHeaderValue(contentType);
+  if (typeof primaryContentType === 'string' && primaryContentType.includes('application/json')) {
+    try {
+      return {
+        body: JSON.parse(bodyText),
+        rawBody: preserveRawBody ? rawBody : undefined
+      };
+    } catch {
+      throw new BadRequestException('Request body contains invalid JSON.');
+    }
+  }
+  if (typeof primaryContentType === 'string' && primaryContentType.includes('application/x-www-form-urlencoded')) {
+    return {
+      body: parseUrlEncodedBody(bodyText),
+      rawBody: preserveRawBody ? rawBody : undefined
+    };
+  }
+  return {
+    body: bodyText,
+    rawBody: preserveRawBody ? rawBody : undefined
+  };
+}
+function parseUrlEncodedBody(bodyText) {
+  const fields = {};
+  const searchParams = new URLSearchParams(bodyText);
+  for (const [key, value] of searchParams.entries()) {
+    setMultiValue(fields, key, value);
+  }
+  return fields;
+}
+function readPrimaryHeaderValue(headerValue) {
+  if (Array.isArray(headerValue)) {
+    return headerValue[0];
+  }
+  return headerValue;
+}
+function setMultiValue(target, key, value) {
+  const existing = target[key];
+  if (existing === undefined) {
+    target[key] = value;
+    return;
+  }
+  if (Array.isArray(existing)) {
+    existing.push(value);
+    return;
+  }
+  target[key] = [existing, value];
+}
+function serializeResponseBody(body, contentType) {
+  if (body === undefined) {
+    return {
+      payload: ''
+    };
+  }
+  if (Buffer.isBuffer(body)) {
+    return {
+      defaultContentType: 'application/octet-stream',
+      payload: body
+    };
+  }
+  if (body instanceof Uint8Array) {
+    return {
+      defaultContentType: 'application/octet-stream',
+      payload: Buffer.from(body)
+    };
+  }
+  if (body instanceof ArrayBuffer) {
+    return {
+      defaultContentType: 'application/octet-stream',
+      payload: Buffer.from(body)
+    };
+  }
+  if (typeof body === 'string') {
+    const isJson = isJsonContentType(contentType);
+    return {
+      defaultContentType: isJson ? undefined : 'text/plain; charset=utf-8',
+      payload: isJson ? JSON.stringify(body) : body
+    };
+  }
+  return {
+    defaultContentType: 'application/json; charset=utf-8',
+    payload: JSON.stringify(body)
+  };
+}
+function isJsonContentType(contentType) {
+  return typeof contentType === 'string' && contentType.toLowerCase().includes('application/json');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './adapter.js';

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@fluojs/platform-express",
+  "description": "Express-based HTTP adapter for the Fluo runtime.",
+  "keywords": [
+    "fluo",
+    "express",
+    "http-adapter",
+    "platform",
+    "server"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/platform-express"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "express": "^5.1.0",
+    "@fluojs/http": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}