@fluojs/http

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;
}

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

  @Get('/:id')
  getById(@FromPath('id') id: string) {
    return { 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);
}

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 { Get, SseResponse, type RequestContext } from '@fluojs/http';

@Get('/events')
stream(_input: undefined, ctx: RequestContext) {
  const sse = new SseResponse(ctx);
  sse.send({ message: 'hello' });
  return sse;
}

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 AsyncLocalStorage for the active dispatch only. 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. 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, 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
• 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, createSecurityHeadersMiddleware, runWithRequestContext, getCurrentRequestContext, assertRequestContext, createRequestContext, createContextKey, getContextValue, setContextValue, encodeSseComment, encodeSseMessage
• Option types: CorsOptions, RateLimitOptions, RateLimitStore, 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.

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