@znight/http 0.1.2 → 0.1.4

package/src/plugin-routes.ts

@@ -8,11 +8,13 @@ import type { HttpContext } from './context.ts'
 import type { RouteMetaEntry } from './decorators.ts'
 import type { HttpMethod } from './metadata.ts'
 import type { GuardRef } from './plugin.ts'
+import type { ByteSize } from './size.ts'
 
 import { ErrorCode, ZnightError } from '@znight/core'
 
 import { isGroupOf } from './decorators.ts'
 import { joinPaths, normalizePath, parseRoutePath, type RoutePath, RoutePathError } from './path.ts'
+import { parseByteSize } from './size.ts'
 
 /**
  * A route served by `HttpPlugin` on behalf of another plugin. It runs through the same pipeline as
@@ -35,6 +37,13 @@ export interface PluginRoute {
   readonly meta?: readonly RouteMetaEntry[]
   /** Guards of the route (provider classes or instances), run after the global guards. */
   readonly guards?: readonly GuardRef[]
+  /**
+   * Maximum body size of this route (`'100kb'`, `1048576`, `Infinity`), with the grammar of the
+   * `HttpPlugin` option `bodyLimit`, which it replaces for this route only (lower or higher, like
+   * `@BodyLimit` on a controller route). Past it, reading the body answers 413. Default: the
+   * `HttpPlugin` option.
+   */
+  readonly bodyLimit?: ByteSize
 }
 
 /** What {@link PluginHttpRoutes.httpRoutes} receives. */
@@ -78,6 +87,8 @@ export interface CollectedPluginRoute {
   readonly handler: (ctx: HttpContext) => unknown
   readonly meta: readonly NormalizedMetaEntry[]
   readonly guards: readonly unknown[]
+  /** Parsed `bodyLimit` in bytes, `undefined`: the plugin limit. */
+  readonly bodyLimit: number | undefined
 }
 
 /** A plugin route metadata entry with its group (internal). */
@@ -147,6 +158,13 @@ function validateRoute(instance: object, plugin: string, value: unknown, prefix:
   }
   const guards = route.guards ?? []
   if (!Array.isArray(guards)) throw invalid(plugin, `the guards of the route ${where} must be an array`)
+  const bodyLimit = route.bodyLimit === undefined ? undefined : parseByteSize(route.bodyLimit)
+  if (route.bodyLimit !== undefined && bodyLimit === undefined) {
+    throw invalid(
+      plugin,
+      `invalid bodyLimit ${describe(route.bodyLimit)} of the route ${where}: expected a size in bytes (1048576, '100kb', Infinity)`,
+    )
+  }
   return {
     plugin,
     instance,
@@ -157,6 +175,7 @@ function validateRoute(instance: object, plugin: string, value: unknown, prefix:
     handler: route.handler,
     meta: entries,
     guards,
+    bodyLimit,
   }
 }
 

package/src/plugin.ts

@@ -1,6 +1,5 @@
 import type { Container, Plugin, PluginContext, PluginOptions, ProviderKey, Token, ZnightMetadata } from '@znight/core'
 import type {
-  AdapterReply,
   HttpAdapter,
   HttpServerAddress,
   InjectRequest,
@@ -519,7 +518,7 @@ export class HttpPlugin implements Plugin {
       adapter.registerRoute({
         method: registration.method,
         path: registration.path,
-        handler: (request): Promise<AdapterReply> => pipeline.handle(plan, request),
+        handler: pipeline.handler(plan),
       })
       routes.push(
         Object.freeze({
@@ -1036,7 +1035,12 @@ function buildRegistrations(
       invoke: (_plugin: unknown, http: HttpContext): unknown => handler(http),
     })
     const instance: Resolvable<object> = { instance: route.instance }
-    const body = bodyPlan({}, options.bodyLimit, options.uploads)
+    // the route's own limit (`bodyLimit`), otherwise the plugin limit
+    const body = bodyPlan(
+      route.bodyLimit === undefined ? {} : { bodyLimit: route.bodyLimit },
+      options.bodyLimit,
+      options.uploads,
+    )
     const chain = guards.map(guard => guard.resolvable)
     const path = route.path
     declared.push({

package/src/response.ts

@@ -229,12 +229,10 @@ function withCookie(cookies: readonly ResponseCookie[], cookie: ResponseCookie):
 
 /** Whether `value` is an {@link HttpResponse} (also across duplicated package copies). */
 export function isHttpResponse(value: unknown): value is HttpResponse {
-  return (
-    value instanceof HttpResponse ||
-    (value !== null &&
-      typeof value === 'object' &&
-      (value as { constructor?: { name?: unknown } }).constructor?.name === 'HttpResponse' &&
-      'body' in value &&
-      'headers' in value)
-  )
+  if (value instanceof HttpResponse) return true
+  if (value === null || typeof value !== 'object') return false
+  const type = (value as { constructor?: { name?: unknown } }).constructor
+  // object literals and arrays (most handler results): reading a function's name is slow
+  if (type === Object || type === Array) return false
+  return type?.name === 'HttpResponse' && 'body' in value && 'headers' in value
 }

package/src/serialize.ts

@@ -13,7 +13,7 @@ import { isHttpResponse } from './response.ts'
 import { isSseBody } from './sse.ts'
 import { isBodylessStatus } from './status.ts'
 import { discardStream, isByteStream, toByteStream } from './stream.ts'
-import { emptyRecord, isBun } from './utils.ts'
+import { fastRecord, isBun } from './utils.ts'
 
 const ENCODER = new TextEncoder()
 
@@ -96,8 +96,16 @@ export function serializeResult(result: unknown, options: SerializeOptions): Ser
     cookies = cookiesOf(result)
   }
   const finalStatus = options.status ?? status ?? defaultStatus(options.routeMethod, payload)
-  const headers = emptyRecord<HeaderValue>()
-  const body = encode(payload, headers)
+  const headers = fastRecord<HeaderValue>()
+  const encoded = encode(payload, headers)
+  let body: ReplyBody
+  let text: string | undefined
+  if (typeof encoded === 'string') {
+    text = encoded
+    body = encodeText(encoded, headers, sendsBody(finalStatus, options.method))
+  } else {
+    body = encoded
+  }
   let own = true
   if (options.headers !== undefined) {
     assignHeaders(headers, options.headers)
@@ -111,7 +119,7 @@ export function serializeResult(result: unknown, options: SerializeOptions): Ser
     assignHeaders(headers, extra)
     own = false
   }
-  return withCookies(finish(finalStatus, headers, body, options.method, own), cookies)
+  return withCookies(finish(finalStatus, headers, body, options.method, text, own), cookies)
 }
 
 /**
@@ -127,7 +135,7 @@ export function serializeSseReply(
   options: SerializeOptions,
 ): SerializedReply {
   const status = options.status ?? response?.status ?? 200
-  const headers = emptyRecord<HeaderValue>()
+  const headers = fastRecord<HeaderValue>()
   headers['cache-control'] = 'no-cache, no-transform'
   headers['x-accel-buffering'] = 'no'
   if (options.headers !== undefined) assignHeaders(headers, options.headers)
@@ -161,7 +169,7 @@ export function serializeFileReply(
   options: SerializeOptions,
 ): SerializedReply {
   const status = file.status === 200 ? (options.status ?? response.status ?? 200) : file.status
-  const headers = emptyRecord<HeaderValue>()
+  const headers = fastRecord<HeaderValue>()
   assignHeaders(headers, file.headers)
   if (options.headers !== undefined) assignHeaders(headers, options.headers)
   if (options.context !== undefined) assignHeaders(headers, options.context)
@@ -177,9 +185,10 @@ function defaultStatus(routeMethod: string, payload: unknown): number {
 
 /** Serialises an error body as JSON. */
 export function serializeError(status: number, body: HttpErrorBody | unknown, method: string): SerializedReply {
-  const headers = emptyRecord<HeaderValue>()
+  const headers = fastRecord<HeaderValue>()
   const encoded = encode(body, headers)
-  return finish(status, headers, encoded, method)
+  if (typeof encoded !== 'string') return finish(status, headers, encoded, method)
+  return finish(status, headers, encodeText(encoded, headers, sendsBody(status, method)), method, encoded)
 }
 
 /** Copies headers with lower-case names (later values win). */
@@ -206,14 +215,15 @@ export function addMissingHeaders(
 }
 
 /**
- * The reply of a body: a string (see {@link encode}) is sent as its UTF-8 bytes, with its text.
- * `own`: only {@link encode} set `headers`, which are then valid for a text body.
+ * The reply of a body: `text` is the string `body` encodes (see {@link encodeText}). `own`: only
+ * {@link encode} set `headers`, which are then valid for a text body.
  */
 function finish(
   status: number,
   headers: Record<string, HeaderValue>,
-  body: ReplyBody | string,
+  body: ReplyBody,
   method: string,
+  text?: string,
   own = false,
 ): SerializedReply {
   if (isBodylessStatus(status)) {
@@ -226,19 +236,38 @@ function finish(
     discard(body)
     return { status, headers, body: null }
   }
-  if (typeof body !== 'string') return { status, headers, body }
-  return own
-    ? { status, headers, body: utf8(body), text: body, ownHeaders: true }
-    : { status, headers, body: utf8(body), text: body }
+  if (text === undefined) return { status, headers, body }
+  return own ? { status, headers, body, text, ownHeaders: true } : { status, headers, body, text }
 }
 
-function discard(body: ReplyBody | string): void {
+function discard(body: ReplyBody): void {
   if (body instanceof ReadableStream) discardStream(body)
 }
 
+/** Whether a reply with this status, to this method, carries its body (see {@link finish}). */
+function sendsBody(status: number, method: string): boolean {
+  return method !== 'HEAD' && !isBodylessStatus(status)
+}
+
+/**
+ * Sets the `content-length` of a text body (right after its `content-type`, before the route
+ * headers) and returns its UTF-8 bytes: their length is the header, a lone surrogate counting as
+ * U+FFFD. `null` when the reply sends no body (`HEAD`, bodyless status): nothing is encoded then,
+ * `Buffer.byteLength` counts the same bytes.
+ */
+function encodeText(text: string, headers: Record<string, HeaderValue>, sent: boolean): Uint8Array | null {
+  if (!sent) {
+    headers['content-length'] = String(Buffer.byteLength(text, 'utf8'))
+    return null
+  }
+  const bytes = utf8(text)
+  headers['content-length'] = String(bytes.byteLength)
+  return bytes
+}
+
 /**
- * The body of a payload, its `content-type` and, for bytes and text, its `content-length` set in
- * `headers`. Text (a string, JSON) is returned as a string, encoded as UTF-8 by {@link finish}.
+ * The body of a payload, its `content-type` and, for bytes, its `content-length` set in `headers`.
+ * Text (a string, JSON) is returned as a string: {@link encodeText} sets its length and encodes it.
  */
 function encode(payload: unknown, headers: Record<string, HeaderValue>): ReplyBody | string {
   if (payload === undefined) return null
@@ -277,8 +306,6 @@ function bytes(data: Uint8Array, headers: Record<string, HeaderValue>, type: str
 
 function text(data: string, headers: Record<string, HeaderValue>, type: string): string {
   headers['content-type'] = type
-  // the length of its UTF-8 encoding (a lone surrogate counts as U+FFFD, like the encoders)
-  headers['content-length'] = String(Buffer.byteLength(data, 'utf8'))
   return data
 }
 
@@ -294,7 +321,7 @@ function isNodeReadable(value: unknown): value is Readable {
 }
 
 function fromWebResponse(response: Response, method: string): SerializedReply {
-  const headers = emptyRecord<HeaderValue>()
+  const headers = fastRecord<HeaderValue>()
   for (const [name, value] of response.headers) {
     if (name !== 'set-cookie') headers[name] = value
   }

package/src/utils.ts

@@ -1,7 +1,13 @@
 /** Internal helpers (not part of the public API). */
 
-/** Whether `value` is a promise-like object (has a callable `then`). */
-export function isThenable(value: unknown): value is PromiseLike<unknown> {
+/**
+ * Whether `value` is a promise-like object (has a callable `then`). The guard keeps the thenable
+ * part of the value's type (`Promise<R>` of `R | Promise<R>`, even when `R` is `object` or `any`), so
+ * that generated code awaiting it gets `R`.
+ */
+export function isThenable<T>(
+  value: T,
+): value is unknown extends T ? T & PromiseLike<unknown> : Extract<T, PromiseLike<unknown>> {
   return (
     value !== null &&
     (typeof value === 'object' || typeof value === 'function') &&
@@ -25,6 +31,23 @@ export function emptyRecord<V>(): Record<string, V> {
   return Object.create(null) as Record<string, V>
 }
 
+/**
+ * Constructor of {@link fastRecord}: its prototype is an empty, frozen object without prototype, so
+ * nothing is inherited (`__proto__`, `constructor`, `toString`... are plain own keys).
+ */
+const FastRecord = function FastRecord() {} as unknown as new () => object
+FastRecord.prototype = Object.freeze(Object.create(null))
+
+/**
+ * A `Record` that inherits nothing, like {@link emptyRecord}, but that V8 keeps in fast mode: an
+ * `Object.create(null)` object is a dictionary, about twice as slow to fill and enumerate (response
+ * headers: built, completed and enumerated on every request). Its prototype is not `null` (an empty
+ * frozen object): use {@link emptyRecord} for records handed to user code (query, fields...).
+ */
+export function fastRecord<V>(): Record<string, V> {
+  return new FastRecord() as Record<string, V>
+}
+
 /** Whether the code runs on Bun. */
 export function isBun(): boolean {
   return typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'

package/src/validate.ts

@@ -1,20 +1,28 @@
-import { ValidationException } from './exceptions.ts'
-import {
-  type InferSchemaOutput,
-  isStandardSchema,
-  type StandardSchemaV1,
-  type StandardSchemaV1Issue,
-  type StandardSchemaV1Result,
+import type {
+  InferSchemaOutput,
+  StandardSchemaV1,
+  StandardSchemaV1Issue,
+  StandardSchemaV1Props,
+  StandardSchemaV1Result,
 } from './standard-schema.ts'
+
+import { ValidationException } from './exceptions.ts'
 import { isThenable } from './utils.ts'
 
+/**
+ * Whether `value` is a promise-like object (has a callable `then`). Called by the generated
+ * `invoke` functions on the result of {@link validate} (README, "Compiler contract").
+ */
+export { isThenable } from './utils.ts'
+
 /**
  * Validates `value` with a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType...)
  * and returns the schema **output** (defaults applied, transforms run, unknown keys stripped when
  * the schema strips them).
  *
  * Returns synchronously when the schema validates synchronously, a promise otherwise (async
- * refinements): generated code always `await`s it.
+ * refinements): generated code calls the handler directly with the value, and `await`s the value
+ * when it is a thenable (`isThenable`).
  *
  * @param location what is validated, used in the error message: `body`, `query`, `query "page"`,
  *   `param "id"`, `headers`, `cookie "sid"`, `cookies`...
@@ -28,12 +36,20 @@ export function validate<S extends StandardSchemaV1>(
   value: unknown,
   location: string,
 ): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>> {
-  if (!isStandardSchema(schema)) {
+  // `~standard` is read once (the same checks as `isStandardSchema`)
+  const props =
+    schema !== null && (typeof schema === 'object' || typeof schema === 'function')
+      ? (schema as { readonly '~standard'?: unknown })['~standard']
+      : undefined
+  if (
+    props === null ||
+    typeof props !== 'object' ||
+    (props as { readonly version?: unknown }).version !== 1 ||
+    typeof (props as { readonly validate?: unknown }).validate !== 'function'
+  ) {
     throw new TypeError(`The schema of ${location} is not a Standard Schema v1 (missing "~standard.validate")`)
   }
-  const result = schema['~standard'].validate(value) as
-    | StandardSchemaV1Result<InferSchemaOutput<S>>
-    | Promise<StandardSchemaV1Result<InferSchemaOutput<S>>>
+  const result = (props as StandardSchemaV1Props<unknown, InferSchemaOutput<S>>).validate(value)
   if (isThenable(result)) return Promise.resolve(result).then(settled => unwrap(settled, location))
   return unwrap(result, location)
 }

package/dist/utils-DCbu3a4w.mjs

@@ -1,27 +0,0 @@
-// src/utils.ts
-/** Internal helpers (not part of the public API). */
-/** Whether `value` is a promise-like object (has a callable `then`). */
-function isThenable(value) {
-	return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
-}
-/** Message of any thrown value. */
-function errorMessage(error) {
-	if (error instanceof Error) return error.message;
-	if (typeof error === "string") return error;
-	try {
-		return String(error);
-	} catch {
-		return Object.prototype.toString.call(error);
-	}
-}
-/** A `Record` without prototype (safe for user-controlled keys such as `__proto__`). */
-function emptyRecord() {
-	return Object.create(null);
-}
-/** Whether the code runs on Bun. */
-function isBun() {
-	return typeof globalThis.Bun !== "undefined";
-}
-export { isThenable as i, errorMessage as n, isBun as r, emptyRecord as t };
-
-//# sourceMappingURL=utils-DCbu3a4w.mjs.map

package/dist/utils-DCbu3a4w.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils-DCbu3a4w.mjs","names":[],"sources":["../src/utils.ts"],"sourcesContent":["/** Internal helpers (not part of the public API). */\n\n/** Whether `value` is a promise-like object (has a callable `then`). */\nexport function isThenable(value: unknown): value is PromiseLike<unknown> {\n  return (\n    value !== null &&\n    (typeof value === 'object' || typeof value === 'function') &&\n    typeof (value as { then?: unknown }).then === 'function'\n  )\n}\n\n/** Message of any thrown value. */\nexport function errorMessage(error: unknown): string {\n  if (error instanceof Error) return error.message\n  if (typeof error === 'string') return error\n  try {\n    return String(error)\n  } catch {\n    return Object.prototype.toString.call(error)\n  }\n}\n\n/** A `Record` without prototype (safe for user-controlled keys such as `__proto__`). */\nexport function emptyRecord<V>(): Record<string, V> {\n  return Object.create(null) as Record<string, V>\n}\n\n/** Whether the code runs on Bun. */\nexport function isBun(): boolean {\n  return typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'\n}\n"],"mappings":";;;AAGA,SAAgB,WAAW,OAA+C;CACxE,OACE,UAAU,SACT,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,OAAQ,MAA6B,SAAS;AAElD;;AAGA,SAAgB,aAAa,OAAwB;CACnD,IAAI,iBAAiB,OAAO,OAAO,MAAM;CACzC,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI;EACF,OAAO,OAAO,KAAK;CACrB,QAAQ;EACN,OAAO,OAAO,UAAU,SAAS,KAAK,KAAK;CAC7C;AACF;;AAGA,SAAgB,cAAoC;CAClD,OAAO,OAAO,OAAO,IAAI;AAC3B;;AAGA,SAAgB,QAAiB;CAC/B,OAAO,OAAQ,WAAiC,QAAQ;AAC1D"}