@fluojs/http

@fluojs/http

English 한국어

The HTTP execution layer that turns route metadata into a request pipeline with binding, validation, guards, interceptors, and response writing.

Table of Contents

• Installation
• When to Use
• Quick Start
• Common Patterns
• Request Cleanup and Portability
• Public API
• Related Packages
• Example Sources

Installation

npm install @fluojs/http

When to Use

Use this package when you need to:

• define REST-style controllers with decorators such as @Controller, @Get, and @Post
• bind request data into DTOs with @FromBody, @FromPath, @FromQuery, and related decorators
• run guards, interceptors, and middleware in a predictable request lifecycle
• access the active request through RequestContext without passing it through every function

Quick Start

import { Controller, FromBody, FromPath, Get, Post, RequestDto } from '@fluojs/http';
import { IsString, MinLength } from '@fluojs/validation';

class CreateUserDto {
  @FromBody()
  @IsString()
  @MinLength(3)
  name!: string;
}

class FindUserParamsDto {
  @FromPath('id')
  id!: string;
}

@Controller('/users')
export class UserController {
  @Post('/')
  @RequestDto(CreateUserDto)
  create(input: CreateUserDto) {
    return { id: '1', name: input.name };
  }

  @Get('/:id')
  @RequestDto(FindUserParamsDto)
  getById(input: FindUserParamsDto) {
    return { id: input.id, name: 'John Doe' };
  }
}

Route path contract

HTTP route decorators such as @Controller(), @Get(), and @Post() accept only:

• literal path segments like /users or /healthz
• full-segment path params like /:id or /users/:userId/posts/:postId

Trailing slashes and duplicate slashes are normalized during route mapping, so //users///:id/ resolves to /users/:id.

Route decorators do not support wildcard, regex-like, or mixed-segment syntax such as *, ?, /(.*), user-:id, or :id.json. Wildcard matching remains middleware-only via forRoutes('/users/*').

Common Patterns

Guards and interceptors

import { Controller, Get, UseGuards, UseInterceptors } from '@fluojs/http';

@Controller('/admin')
@UseGuards(AdminGuard)
@UseInterceptors(LoggingInterceptor)
class AdminController {
  @Get('/')
  dashboard() {
    return { data: 'secret' };
  }
}

Async request context

import { getCurrentRequestContext } from '@fluojs/http';

function someDeepHelper() {
  const ctx = getCurrentRequestContext();
  console.log(ctx?.requestId);
}

runWithRequestContext(...) preserves the active context across awaited work when the host provides AsyncLocalStorage through globalThis.AsyncLocalStorage or Node's built-in node:async_hooks module. The root @fluojs/http import does not probe or instantiate async-context storage; helpers resolve storage lazily on first use, guard process.getBuiltinModule(...) failures, and keep the first-call synchronous callback return and throw behavior unchanged while isolating promise continuations registered before Node async storage finishes resolving. Non-Node hosts without an async-context primitive use a synchronous stack fallback that clears the context before awaited continuations resume, avoiding cross-request leaks instead of pretending to isolate overlapping async work.

Rate limiting behind proxies

createRateLimitMiddleware(...) resolves client identity from the raw socket remoteAddress by default. To trust Forwarded, X-Forwarded-For, or X-Real-IP, opt in with trustProxyHeaders: true only when your adapter sits behind a trusted proxy that overwrites those headers. If your adapter exposes neither a trusted proxy chain nor a raw socket identity, provide an explicit keyResolver.

Server-sent events

import { Controller, Sse, type SseMessage } from '@fluojs/http';

@Controller('/orders')
export class OrdersEventsController {
  @Sse('/events')
  async *stream(): AsyncIterable<SseMessage<{ status: string }> | { heartbeat: true }> {
    yield { data: { status: 'connected' }, event: 'ready', id: 'orders-ready' };

    while (true) {
      await new Promise((resolve) => setTimeout(resolve, 15_000));
      yield { heartbeat: true };
    }
  }
}

@Sse(path) registers a GET route and declares text/event-stream produced media type metadata. Handlers may either return SseResponse for manual stream control or return AsyncIterable<SseMessage<T> | T> for managed streaming. Managed async iterables are converted with the same encodeSseMessage(...) behavior as SseResponse: plain yielded values become data: frames, while yielded objects with a data field may also provide event, id, and retry. The dispatcher stops consuming the source when RequestContext.request.signal aborts or the response stream closes, calls FrameworkResponseStream.waitForDrain() when a write reports backpressure, closes the stream on completion or source errors, and routes thrown source errors through the normal dispatcher error/observer seam after the already-committed SSE response is closed. Observable values remain out of scope and no RxJS dependency is required.

On the browser side, create the EventSource inside the React effect that owns it and always close it from the cleanup function so route changes, Strict Mode remounts, and component unmounts do not leave duplicate streams open:

import { useEffect, useState } from 'react';

export function OrderEvents({ orderId }: { orderId: string }) {
  const [events, setEvents] = useState<string[]>([]);

  useEffect(() => {
    const source = new EventSource(`/orders/events?orderId=${encodeURIComponent(orderId)}`, {
      withCredentials: true,
    });

    source.addEventListener('ready', (event) => {
      setEvents((current) => [...current, event.data]);
    });

    source.onerror = () => {
      // Browsers reconnect automatically unless the server closes with a terminal status.
      console.warn('Order event stream disconnected; waiting for browser retry.');
    };

    return () => {
      source.close();
    };
  }, [orderId]);

  return <output>{events.join('\n')}</output>;
}

Browser EventSource does not let callers attach arbitrary Authorization headers. Authenticate SSE endpoints with same-origin cookies, withCredentials plus explicit CORS credentials policy, or a short-lived signed URL/query token that your guard validates. Do not document a bearer-header browser example unless you are using a custom fetch-based SSE client instead of the built-in EventSource API.

Operationally, keep SSE connections unbuffered and long-lived: allow credentials in CORS only for trusted origins, disable proxy buffering and response transforms (SseResponse sets Cache-Control: no-cache, no-transform and X-Accel-Buffering: no), avoid compression middleware that buffers text/event-stream, set load balancer or platform idle timeouts above your heartbeat interval, send comment heartbeats such as sse.comment('heartbeat'), and persist enough event history to honor Last-Event-ID when clients reconnect and need replay.

Versioning

createHandlerMapping(...) supports URI, header, media-type, and custom versioning strategies through VersioningType and the versioning option. Route registration keeps exact/static matches ahead of fallbacks while preserving registration order for equivalent normalized routes.

Request context helpers

Use runWithRequestContext(...), assertRequestContext(), createRequestContext(...), createContextKey(...), getContextValue(...), and setContextValue(...) when framework integrations need explicit request context boundaries or typed per-request storage.

Fast-path observability

The dispatcher exposes fast-path observability for adapters and diagnostics through FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats(...), and getDispatcherFastPathStats(...).

Bun decorator bundling compatibility

Fluo's HTTP decorators are standard TC39 decorators and continue to record metadata through context.metadata when the runtime or compiler provides the standard decorator context. When Bun bundles an application through its legacy TypeScript decorator transform, the same controller, route, DTO binding, guard/interceptor, header, redirect, versioning, status, request DTO, and @Produces(...) metadata is recorded through Fluo's internal metadata stores so generated Bun bundles preserve route mapping behavior.

This compatibility path is an execution fallback for Bun bundle output; application source should still use Fluo's standard decorators and should not enable emitDecoratorMetadata or rely on reflect-metadata.

Request Cleanup and Portability

The dispatcher binds RequestContext with host async-context storage for the active dispatch only. On hosts with AsyncLocalStorage, including supported Node 20+ runtimes, the context remains available across awaited work. On non-Node hosts without an async-context primitive, the fallback context is synchronous-only and intentionally unavailable after await so overlapping requests cannot observe one another's context. When a request may use request-scoped DI through its controller graph, middleware, guards, interceptors, observers, DTO converters, a custom binder, or manual getCurrentRequestContext() / assertRequestContext() container access, the dispatcher creates and disposes an isolated request-scoped DI container from its finally path after request observers finish. Singleton-only routes skip that container lifecycle until RequestContext.container is accessed, so the baseline path avoids unnecessary per-request allocation while preserving request-scoped provider isolation whenever the graph is ambiguous or request-scoped. Public RequestContext.container reads are therefore always safe for resolving request-scoped providers; the singleton-only fast path is an internal dispatcher optimization, not a promise that the public context exposes the root container.

Adapters should pass an AbortSignal on FrameworkRequest.signal when the platform exposes one, or an isAborted() probe when allocating a signal is not practical. The dispatcher preserves both abort surfaces on its per-dispatch request clone and checks them before and after handler work so adapters without AbortSignal can still stop abandoned requests. For SSE, adapters should also expose FrameworkResponse.stream.onClose(...) when possible; SseResponse listens to both request abort and raw stream close, closes idempotently, and removes registered listeners when either side terminates first.

Public API

• Routing decorators: Controller, Get, Sse, Post, Put, Patch, Delete, All, Options, Head
• Binding decorators: FromBody, FromQuery, FromPath, FromHeader, FromCookie, RequestDto, Optional, Convert
• Execution decorators: UseGuards, UseInterceptors, HttpCode, Version, Header, Redirect, Produces
• Core runtime types: RequestContext, FrameworkRequest, FrameworkResponse, SseResponse, SseMessage, Middleware, MiddlewareContext, MiddlewareRouteConfig, Next, Guard, GuardContext, Interceptor, InterceptorContext, CallHandler, RequestObserver, DispatcherLogger
• Adapter API: HttpApplicationAdapter, createNoopHttpApplicationAdapter, createServerBackedHttpAdapterRealtimeCapability, createUnsupportedHttpAdapterRealtimeCapability, createFetchStyleHttpAdapterRealtimeCapability
• Exceptions and errors: HttpException, BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, ConflictException, NotAcceptableException, TooManyRequestsException, InternalServerErrorException, PayloadTooLargeException, createErrorResponse, RouteConflictError, InvalidRoutePathError, HandlerNotFoundError, RequestAbortedError
• Helpers: createHandlerMapping, createDispatcher, forRoutes, normalizeRoutePattern, matchRoutePattern, isMiddlewareRouteConfig, createCorrelationMiddleware, createCorsMiddleware, createRateLimitMiddleware, createMemoryRateLimitStore, createSecurityHeadersMiddleware, runWithRequestContext, getCurrentRequestContext, assertRequestContext, createRequestContext, createContextKey, getContextValue, setContextValue, encodeSseComment, encodeSseMessage, isSseMessage
• Option and store types: CorsOptions, RateLimitOptions, RateLimitStore, RateLimitStoreEntry, SecurityHeadersOptions, SseSendOptions

Internal Subpath (@fluojs/http/internal)

The ./internal subpath exports only the low-level utilities used by platform adapters and the core runtime. These are subject to change and should not be used in typical application code.

• DefaultBinder: Default DTO/request binder used by the runtime bootstrap path.
• bindRawRequestNativeRouteHandoff(...) / attachFrameworkRequestNativeRouteHandoff(...): Internal adapter/runtime helpers for reusing semantically safe native route matches without widening the public dispatcher API.
• consumeRawRequestNativeRouteHandoff(...) / readFrameworkRequestNativeRouteHandoff(...): Internal helpers for reading or consuming native route handoffs.
• Native route handoffs snapshot the framework request method and path when attached; if app middleware rewrites either value before handler matching, the dispatcher ignores the stale handoff and falls back to normal route matching.
• isRoutePathNormalizationSensitive(path): Internal guard for keeping duplicate-slash and trailing-slash requests on the generic dispatcher path.
• resolveClientIdentity(request): Conservative client identity resolver used by rate limiting and other runtime integrations.
• createFetchStyleHttpAdapterRealtimeCapability(...), Dispatcher, and HttpApplicationAdapter: internal adapter seams for edge/fetch-style platform packages that must avoid instantiating the full HTTP root barrel.

Related Packages

• @fluojs/core: stores controller, route, and DTO metadata
• @fluojs/validation: validates DTOs after HTTP binding
• @fluojs/runtime: assembles the dispatcher during application bootstrap
• @fluojs/passport: plugs auth guards into the same HTTP guard chain

Example Sources

• examples/realworld-api/src/users/create-user.dto.ts
• examples/auth-jwt-passport/src/auth/auth.controller.ts
• packages/http/src/dispatch/dispatcher.test.ts