@knead-js/http

bun add @knead-js/core @knead-js/http

@knead-js/core is a peer dependency. The package requires Bun 1.4.3 or later.

@knead-js/http turns a module tree into a Bun.serve server. KneadFactory.create() bootstraps the modules, and listen() compiles every controller route into Bun's native router, wraps each in its middleware, guards, validation and exception filters, and binds the listener. The package also holds the error types, the WebSocket endpoint registry, and the network and logging helpers the other Knead packages build on.

Guides: controllers, request context, validation, errors, middleware, guards, exception filters, the server and WebSockets.

#Application

export async function main(): Promise<void> {
  const app = await KneadFactory.create(AppModule);
  app.enableShutdownHooks();
  await app.listen({ hostname: '127.0.0.1', port: 3000 });
  for (const route of app.routes) {
    app.logger.info(`${route.method} ${route.path} -> ${route.handler}`);
  }
}

#KneadFactory

KneadFactory.create(root, options?) returns Promise<HttpApplication>. It bootstraps the module tree from root (a module class or dynamic module) with HttpCoreModule registered as a global module, and resolves the LOGGER. The onModuleInit and onApplicationBootstrap hooks of the bootstrapped providers run here.

CreateApplicationOptions:

#HttpCoreModule

The global module KneadFactory registers. It provides and exports WsRegistry and ErrorLog to every module. HTTP_DEVELOPMENT (the same token as core's DEVELOPMENT) is provided to every module by the application context, from the development option. You never import it yourself.

#HttpApplication

HttpApplication is the application returned by KneadFactory.create().

A listen() that failed to bind (for example, the port is in use) leaves nothing bound and can be retried, but the context stays open: call await app.close() if you give up. A listen() that failed because a lifecycle hook threw has closed the application. See the server.

#ListenOptions

ListenOptions is the argument of app.listen().

The numeric options must be numbers within those ranges: a string (such as an unparsed environment variable), NaN or Infinity is an HttpConfigError at listen(), before anything binds.

Both listeners run with Bun's development mode set to the application's development flag (Bun's own default turns it on whenever NODE_ENV is not 'production', which renders an HTML page with the error's message, stack and source). An error that escapes every Knead handler is logged and answered with a masked 500 problem, never Bun's error page.

#redirectToHttps

redirectToHttps(req, httpsPort, host?) returns a 308 response to the same path and query on HTTPS, with Cache-Control: no-store and nosniff. With host (a plain host[:port]), the Location uses it and ignores the request's Host; a port in host overrides httpsPort, and an invalid host throws HttpConfigError. Without it, the request's Host is used with its port replaced by httpsPort, and a Host that is not a plain host[:port] gets 400 Invalid Host header. Port 443 is left out of the URL. The redirectHttp listener uses this function.

#Decorators

#Controllers and routes

path is a string and options a RouteOptions. A route decorator returns a RouteDecorator<P, O> that types the handler's ctx from the path P and the options O (see RouteInput), and throws a TypeError on a static or #private method. See controllers.

#Pipeline decorators

The three Use* decorators return a ClassOrMethodDecorator, a decorator type that accepts both a class and a method context. On a class the items are added at the controller level; on a method, at the route level, after the ones given in the route decorator's options.

#createRouteDecorator

createRouteDecorator<T>(key) returns (value: T) => ClassOrMethodDecorator, a decorator that writes { [key]: value } into route metadata, read as ctx.meta[key]. On a class it applies to every route of the controller; a method-level value wins over the class-level one. See route metadata.

#Request context types

#Ctx

Ctx<I extends CtxInput = {}> is the request context (see request context):

#Route and controller options

ControllerOptions:

RouteOptions extends ControllerOptions with:

#Middleware, guards and filters

Middleware must return a Response; a layer that returns anything else is answered as a 500 error. listen() checks every middleware, guard and filter reference (global, module, controller and route) and rejects with an HttpConfigError naming where it is listed for one that is undefined (often a circular import), lacks its method, or is a class whose use, canActivate or catch is an arrow-function field. A filter is never a plain function. If the error handling itself fails (a filter's @Catch() metadata cannot be read, or an exception's extensions do not serialize), the request still gets a problem response: extensions that do not serialize, such as a BigInt, are dropped, and anything else is a masked 500 with the instance. See middleware, guards and exception filters for ordering and examples.

#assertGuardRef

assertGuardRef(ref, where) asserts that ref is a guard: an object with a canActivate function, a function, or a class with canActivate on its prototype. Anything else (including undefined from a circular import, or a class whose canActivate is an arrow-function field) throws HttpConfigError: Invalid guard in <where>: .... Knead runs this check on every guard at listen(); packages that accept guards in their own options use it to fail the same way.

#resolveGuard

resolveGuard(ref, injector, where = 'a guard list') returns Guard<any>: it resolves a GuardRef in a ModuleInjector (a class is constructed through the injector, a function is adapted, an object is returned as is), after assertGuardRef(ref, where). Used by @knead-js/graphql for resolver guards.

#Tokens

Class references in APP_GUARD, APP_FILTER and APP_MIDDLEWARE are resolved with the injector of the module that provides them.

#Errors

See errors for the response format and production masking.

#HttpException

new HttpException(status, detail?, options?), where status is an integer from 400 to 599 (otherwise a RangeError). Properties: status, detail (string | undefined), type, title, extensions, headers (a Headers), plus message (the detail, or the title) and name (the class name). toProblem(instance?) returns the ProblemDetails body.

HttpExceptionOptions:

#Subclasses

Each takes (detail?, options?).

#ValidationException

ValidationException is thrown when a route's schemas reject a request: new ValidationException(issues) is a BadRequestException with the detail Request validation failed, the extension issues, and a read-only issues property. The validation types:

#ValidationOptions

listen({ validation }). redactIssueMessages (default false) replaces the messages of params, query and body issues with Invalid value. Issues from headers always have the message Invalid header value. See validation.

#HttpConfigError

A KneadError (from @knead-js/core) for configuration problems found while the application is bootstrapped, compiled or started: invalid route definitions, invalid guards, invalid listen() options, WebSocket endpoints registered after listen(), and calling listen() twice.

#Problem helpers

#Responses

withHeaders(res, headers, overwrite = true) adds headers to a Response and returns it. When the response's headers are immutable (as on Response.redirect()), it returns a copy with the headers added. Set-Cookie values are appended; with overwrite false, headers the response already has are kept.

isHeaderValue(value) is true when value can be sent as a header value: no CR, LF or NUL and Latin-1 only. Knead uses it to validate header values given as options at bootstrap.

export function noStore(res: Response): Response {
  // Mutates res when its headers are mutable, otherwise returns a copy.
  return withHeaders(res, { 'cache-control': 'no-store' });
}

export function pathOf(req: Request): string {
  // Never throws, even for a request whose Host header is not a valid URL authority.
  return requestUrl(req).pathname;
}

requestUrl(req) returns the request's URL as a URL. A request whose Host header does not form a valid URL has a relative req.url in Bun; it is resolved against http://host.invalid instead of throwing.

DEFAULT_MAX_PARAMS is 1000, the default of listen({ maxParams }).

#Routes table

#Metadata keys

The decorators store their data under these MetadataKeys (all knead:-prefixed), readable with getMetadata(), getOwnMetadata() and getMethodMetadata() from @knead-js/core. Use them to build tooling, such as a route listing; the decorators are the supported way to write them.

ROUTES is inherited by subclasses; CONTROLLER must be the class's own.

#WebSockets

See WebSockets for endpoints, origin checks, limits and revocation.

#WsRegistry

The injectable registry of WebSocket endpoints (Bun allows one WebSocket handler per server, so modules register endpoints here). Inject it with inject(WsRegistry).

#WebSocket types

WsEndpointOptions:

#WsServerOptions

listen({ websocket }). The defaults are in WS_DEFAULTS, a frozen object; an option passed as undefined keeps its default. The connection slot of an upgrade whose socket has not opened after 30 seconds is given back; a socket that opens later takes a slot again, or is closed with 1013 when none is free.

#originAllowed

originAllowed(origin, host, secure, allowed?) returns whether a WebSocket upgrade's Origin may connect: when origin is null (no header, not a browser), when allowed is '*' or lists the origin (allowed is an array of origins, or a ReadonlySet of normalized origins, as new URL(entry).origin writes them), or when it is the request's own origin (scheme from secure, host and port from host, default ports normalized). Origin: null is rejected. Exported for transports that check origins themselves.

#Network helpers

parseIp(), isLoopbackHostname(), plaintextRedisHost() and defaultRedisUrl() are re-exported from @knead-js/core.

#Logging

These are re-exported from @knead-js/core as the same objects, so code that imports them from either package shares one LOGGER token. See logging and the @knead-js/core reference.

#Error logging

#Runtime version