galbe 0.15.5 → 0.16.0

package/src/schema.ts

@@ -13,18 +13,29 @@ export interface Options {
    * `examples`). On any other schema: a single example value.
    */
   examples?: any
-  /**
-   * Response-only: declares response headers. Each value is a Galbe schema
-   * describing the header's value type.
-   */
-  headers?: Record<string, any>
   /** Marks the schema as deprecated. Surfaced by spec generators (e.g. OpenAPI). */
   deprecated?: boolean
+  /**
+   * Documentation only: marks the value as sent by the server and never by the
+   * client (OpenAPI `readOnly`). Galbe does not enforce it — a `readOnly`
+   * property in a request body is still validated like any other.
+   */
+  readOnly?: boolean
+  /**
+   * Documentation only: marks the value as sent by the client and never
+   * returned by the server (OpenAPI `writeOnly`). Not enforced at runtime.
+   */
+  writeOnly?: boolean
   /**
    * Response-only: declares response headers emitted in the OpenAPI `responses` object.
    * Distinct from the request-level `headers` field.
    */
   responseHeaders?: Record<string, any>
+  /**
+   * Response-only, documentation only: the OpenAPI `links` object — operations
+   * reachable from this response, keyed by name. Carried verbatim.
+   */
+  responseLinks?: Record<string, any>
 }
 export interface ByteArrayOptions extends Options {
   minLength?: number
@@ -41,11 +52,71 @@ export interface NumberOptions extends Options {
   max?: number
   exclusiveMin?: number
   exclusiveMax?: number
+  /** The value must be an exact multiple of this number. */
+  multipleOf?: number
+  /**
+   * The numeric format, surfaced as OpenAPI's `format`. The four machine-integer
+   * formats (`int32`, `uint32`, `int64`, `uint64`) also constrain the value's
+   * range at runtime; every other format — `float` and `double` included — is
+   * documentation only, since any finite JSON number is a valid double.
+   */
+  format?: NumberFormat | (string & {})
+}
+export type NumberFormat = 'int32' | 'uint32' | 'int64' | 'uint64' | 'float' | 'double' | 'decimal'
+/**
+ * Ranges for the integer formats, as `[min, max]`. The 64-bit bounds are not
+ * exactly representable as doubles, so they land on ±2^63 / 2^64: the check
+ * catches an overflow by orders of magnitude, which is what it is for, and
+ * never rejects a value a double could have held.
+ */
+export const NUMBER_FORMAT_RANGES: Record<string, [number, number]> = {
+  int32: [-2147483648, 2147483647],
+  uint32: [0, 4294967295],
+  int64: [-(2 ** 63), 2 ** 63 - 1],
+  uint64: [0, 2 ** 64 - 1],
 }
 export interface ArrayOptions extends Options {
   minLength?: number
   maxLength?: number
   unique?: boolean
+  /**
+   * Query parameters only: the delimiter that splits a single value into
+   * several items — `?tags=a,b` with the default `','`. Repeated keys
+   * (`?tags=a&tags=b`) are always accepted regardless.
+   *
+   * `false` disables splitting, so a value containing the delimiter stays one
+   * item. `'|'` and `' '` are OpenAPI's `pipeDelimited` and `spaceDelimited`,
+   * and are emitted as such by spec generators.
+   */
+  split?: string | false
+}
+/** Per-part serialization details for a multipart body, as OpenAPI's `encoding`. */
+export type EncodingProperty = {
+  contentType?: string
+  style?: string
+  explode?: boolean
+  allowReserved?: boolean
+  headers?: Record<string, any>
+}
+export interface MultipartFormOptions extends Options {
+  /**
+   * Documentation only: how each part is serialized, keyed by property name.
+   * Emitted as the media type's `encoding` object — Galbe's multipart parser
+   * validates parts from the schema alone and does not read this.
+   */
+  encoding?: Record<string, EncodingProperty>
+}
+export interface ObjectOptions extends Options {
+  /**
+   * What may appear beside the declared properties, mirroring OpenAPI's
+   * `additionalProperties`. A schema validates every undeclared property against
+   * it — `$T.record` is the sugar for the property-less case. `false` rejects
+   * undeclared properties outright. Unset (the default) accepts and ignores them.
+   *
+   * `Static<>` only ever surfaces the declared properties: an object that mixes
+   * both would otherwise index every declared key through the value schema too.
+   */
+  additionalProperties?: STSchema | false
 }
 export interface STSchema extends Options {
   [Kind]:
@@ -71,17 +142,7 @@ export interface STSchema extends Options {
   static: unknown
 }
 export type STPropsValue =
-  | STBoolean
-  | STByteArray
-  | STNumber
-  | STInteger
-  | STString
-  | STLiteral
-  | STArray
-  | STObject
-  | STUnion
-  | STAny
-  | STNull
+  STBoolean | STByteArray | STNumber | STInteger | STString | STLiteral | STArray | STObject | STUnion | STAny | STNull
 export type STProps = Record<string | number, STPropsValue>
 
 type Evaluate<T> = T extends infer O ? { [K in keyof O]: O[K] } : never
@@ -209,6 +270,18 @@ export interface STObject<T extends STProps = STProps> extends STSchema {
   [Kind]: 'object'
   static: ObjectStatic<T, this['params']>
   props: T
+  additionalProperties?: STSchema | false
+}
+/**
+ * A free-form map: no declared properties, every value validated against one
+ * schema. Kind stays `'object'` — a record *is* an object with
+ * `additionalProperties`, so every consumer that walks objects keeps working.
+ */
+export interface STRecord<V extends STSchema = STSchema> extends STSchema {
+  [Kind]: 'object'
+  static: Record<string, Static<V, this['params']>>
+  props: STProps
+  additionalProperties: V
 }
 export interface STJson<T extends STBoolean | STNumber | STString | STObject = any> extends STSchema {
   [Kind]: 'json'
@@ -223,7 +296,7 @@ type RequiredPropertyKeys<T extends STProps> = keyof Omit<T, OptionalPropertyKey
 type ObjectStaticProps<T extends STProps, R extends Record<keyof any, unknown>> = Evaluate<
   Partial<Pick<R, OptionalPropertyKeys<T>>> & Required<Pick<R, RequiredPropertyKeys<T>>>
 >
-function _Object<T extends STProps>(properties?: T, options: Options = {}): STObject<T> {
+function _Object<T extends STProps>(properties?: T, options: ObjectOptions = {}): STObject<T> {
   if (!properties) return { ...options, [Kind]: 'object' } as unknown as STObject<T>
   const propertyKeys = globalThis.Object.getOwnPropertyNames(properties)
   const optionalKeys = propertyKeys.filter(key => properties[key]?.[Optional])
@@ -251,7 +324,7 @@ export interface MultipartFormData<K extends string = string, V extends Static<S
   headers: { type?: string; name: K; filename?: string }
   content: V
 }
-export interface STMultipartForm<T extends STProps = STProps> extends STSchema {
+export interface STMultipartForm<T extends STProps = STProps> extends STSchema, MultipartFormOptions {
   [Kind]: 'multipartForm'
   static: T extends undefined
     ? {
@@ -268,7 +341,7 @@ export interface STMultipartForm<T extends STProps = STProps> extends STSchema {
       }
   props: T
 }
-function _MultipartForm<T extends STProps>(properties?: T, options: Options = {}): STMultipartForm<T> {
+function _MultipartForm<T extends STProps>(properties?: T, options: MultipartFormOptions = {}): STMultipartForm<T> {
   if (!properties) return { ...options, [Kind]: 'multipartForm' } as unknown as STMultipartForm<T>
   const propertyKeys = globalThis.Object.getOwnPropertyNames(properties)
   const optionalKeys = propertyKeys.filter(key => properties[key]?.[Optional])
@@ -403,9 +476,18 @@ export class SchemaType {
     return _Any(options)
   }
   /** Creates an Object Schema Type */
-  public object<T extends STProps>(properties?: T, options: Options = {}): STObject<T> {
+  public object<T extends STProps>(properties?: T, options: ObjectOptions = {}): STObject<T> {
     return _Object(properties, options)
   }
+  /**
+   * Creates a Record Schema Type: an object with no declared properties whose
+   * every value validates against `value`. Sugar for
+   * `$T.object(undefined, { additionalProperties: value })`, typed as
+   * `Record<string, Static<V>>`.
+   */
+  public record<V extends STSchema>(value: V, options: Options = {}): STRecord<V> {
+    return _Object(undefined, { ...options, additionalProperties: value }) as unknown as STRecord<V>
+  }
   /** Creates a JSON Schema Type */
   public json<T extends STString | STBoolean | STNumber | STObject<STProps>>(
     value: T,
@@ -414,7 +496,7 @@ export class SchemaType {
     return _Json(value, options)
   }
   /** Creates a MultipartForm Schema Type */
-  public multipartForm<T extends STProps>(properties?: T, options: Options = {}): STMultipartForm<T> {
+  public multipartForm<T extends STProps>(properties?: T, options: MultipartFormOptions = {}): STMultipartForm<T> {
     return _MultipartForm(properties, options)
   }
   /** Creates an Array Schema Type */
@@ -458,12 +540,14 @@ export class SchemaType {
   ): Omit<STStream<T>, 'static'> & {
     static: AsyncGenerator<
       Entries<{
-        [P in KeysOfUnion<MemberProps<T['members'][number]>> as ValueAt<
-          MemberProps<T['members'][number]>,
-          P
-        > extends STSchema
-          ? P
-          : never]: Static<ValueAt<MemberProps<T['members'][number]>, P>>
+        [
+          P in KeysOfUnion<MemberProps<T['members'][number]>> as ValueAt<
+            MemberProps<T['members'][number]>,
+            P
+          > extends STSchema
+            ? P
+            : never
+        ]: Static<ValueAt<MemberProps<T['members'][number]>, P>>
       }>
     >
     params: unknown[]
@@ -536,10 +620,18 @@ export const schemaToTypeStr = (schema: STSchema): string => {
   } else if (kind === 'array') {
     type = `Array<${schemaToTypeStr((schema as STArray).items)}>`
   } else if (kind === 'object') {
-    let props = (schema as STObject).props
-    type = `{${Object.entries(props)
-      .map(([k, v]) => `${typeof k === 'string' ? `'${k}'` : k}${v?.[Optional] ? '?' : ''}:${schemaToTypeStr(v)}`)
-      .join(';')}}`
+    let entries = Object.entries((schema as STObject).props ?? {})
+    const ap = (schema as STObject).additionalProperties
+    // prop-less object accepts any object at runtime, so `{}` would be too loose
+    type = entries.length
+      ? // declared properties win: intersecting them with the record type would
+        // resolve every declared key to `declared & value`, i.e. usually `never`
+        `{${entries
+          .map(([k, v]) => `${typeof k === 'string' ? `'${k}'` : k}${v?.[Optional] ? '?' : ''}:${schemaToTypeStr(v)}`)
+          .join(';')}}`
+      : ap
+        ? `Record<string, ${schemaToTypeStr(ap)}>`
+        : 'Record<string, unknown>'
   } else if (kind === 'json') {
     type = `Json<${schemaToTypeStr((schema as STJson).value)}>`
   } else if (kind === 'anyOf' || kind === 'oneOf') {

package/src/server.ts

@@ -1,12 +1,13 @@
-import type { Context, Method, Route } from './types'
+import type { Context, GalbePlugin, Method, Route } from './types'
 
-import { InternalServerError, RequestError } from './types'
+import { InternalServerError, PayloadTooLargeError, RequestError } from './types'
 import { parseEntry, requestBodyParser, requestPathParser, responseParser } from './parser'
 import { Galbe } from './index'
 import { validateResponse } from './validator'
 const normalizeContentType = (ct: string | null): string | undefined =>
   ct ? (ct.split(';')[0] ?? '').trim() || undefined : undefined
 import { readCookies, stringifyCookie } from './cookies'
+import { clientAddressResolver } from './util'
 
 type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
 
@@ -18,11 +19,14 @@ const handleInternalError = (error: any) => {
   return new InternalServerError()
 }
 
+// the predicates narrow the hook to non-optional, so the lifecycle can call it
+// without a null check it has already made
+type PluginWith<K extends keyof GalbePlugin> = GalbePlugin & Required<Pick<GalbePlugin, K>>
 const setupPluginCallbacks = (galbe: Galbe) => ({
-  onFetch: galbe.plugins.filter(p => p.onFetch),
-  onRoute: galbe.plugins.filter(p => p.onRoute),
-  beforeHandle: galbe.plugins.filter(p => p.beforeHandle),
-  afterHandle: galbe.plugins.filter(p => p.afterHandle),
+  onFetch: galbe.plugins.filter((p): p is PluginWith<'onFetch'> => !!p.onFetch),
+  onRoute: galbe.plugins.filter((p): p is PluginWith<'onRoute'> => !!p.onRoute),
+  beforeHandle: galbe.plugins.filter((p): p is PluginWith<'beforeHandle'> => !!p.beforeHandle),
+  afterHandle: galbe.plugins.filter((p): p is PluginWith<'afterHandle'> => !!p.afterHandle),
 })
 
 export default async (galbe: Galbe, port?: number, hostname?: string) => {
@@ -30,6 +34,8 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
   if (galbe?.config?.basePath && galbe?.config?.basePath[0] !== '/')
     galbe.config.basePath = `/${galbe?.config?.basePath}`
   let pluginsCb = setupPluginCallbacks(galbe)
+  // compiled once: a trustProxy misconfiguration must fail at boot, not per request
+  const resolveClientAddress = clientAddressResolver(galbe.config?.trustProxy)
 
   // config.server is passed through to Bun.serve; port/fetch/error are owned by
   // Galbe and the dedicated config keys (port, hostname, reusePort, tls) win
@@ -48,25 +54,47 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
     async fetch(req) {
       if (!METHODS.includes(req.method)) return new Response('', { status: 501 })
       const cookies: string[] = []
+      let reqHeaders: Record<string, any> | undefined
+      let clientAddress: string | null | undefined
+      const peer = server.requestIP(req)
       const context = {
         request: req,
+        // null-prototype: header names are untrusted keys and must never reach
+        // Object.prototype members (constructor, __proto__, toString, …)
+        get headers() {
+          if (reqHeaders) return reqHeaders
+          const h: Record<string, any> = Object.create(null)
+          for (const [k, v] of req.headers) h[k] = v
+          return (reqHeaders = h)
+        },
+        set headers(v: Record<string, any>) {
+          reqHeaders = v
+        },
         contentType: !EMPTY_BODY_METHODS.includes(req.method)
           ? normalizeContentType(req.headers.get('content-type'))
           : undefined,
-        remoteAddress: server.requestIP(req),
+        remoteAddress: peer,
+        // lazy like `headers`: an app that never asks does not pay for the
+        // X-Forwarded-For walk. `remoteAddress` stays the raw socket peer.
+        get clientAddress() {
+          if (clientAddress === undefined) clientAddress = resolveClientAddress(req, peer?.address ?? null)
+          return clientAddress
+        },
         set: {
           headers: { 'set-cookie': [] },
           cookie: (name, value, opt = { path: '/' }) => cookies.push(stringifyCookie(name, value, opt)),
         },
         state: {},
         cookies: readCookies(req.headers.get('cookie')),
-      } as MakeOptional<Context, 'headers' | 'params' | 'query' | 'body'>
+      } as MakeOptional<Context, 'params' | 'query' | 'body'>
       const url = new URL(req.url)
-      let route: Route
+      let route: Route | undefined
       let response: any = ''
+      // the route-scoped post-parse stage runs once per request, so a hook that
+      // threw on the success path is not run a second time on the error response
+      let postRan = false
       try {
         for (const p of pluginsCb.onFetch) {
-          //@ts-ignore
           const r = await p.onFetch(context)
           if (r) return r
         }
@@ -80,17 +108,22 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
         context.route = route
 
         for (const p of pluginsCb.onRoute) {
-          //@ts-ignore
           const r = await p.onRoute(context)
           if (r) return r
         }
 
+        // middleware pre-parse slot, composed at registration (see composePreParse):
+        // the route is known, nothing has been committed yet — an auth or rate
+        // limit rejection here answers before a byte of body is read
+        if (route.composedPre) {
+          const r = await route.composedPre(context)
+          if (r) return r
+        }
+
         // parse request
         const schema = route.schema
-        // null-prototype maps: keys are untrusted, a plain {} would collide with
+        // null-prototype map: keys are untrusted, a plain {} would collide with
         // Object.prototype members (constructor, __proto__, toString, …)
-        const inHeaders: Record<string, any> = Object.create(null)
-        for (let [k, v] of req.headers) inHeaders[k] = v
         let inQuery: Record<string, any> = Object.create(null)
         for (let [k, v] of url.searchParams) {
           if (k in inQuery) {
@@ -101,13 +134,17 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
         }
         let inParams = requestPathParser(url.pathname, route.path)
 
+        // reject oversized bodies declared by honest clients before reading a byte
+        const bodyLimit = schema.bodyLimit ?? galbe.config?.bodyLimit
+        if (bodyLimit !== undefined && Number(req.headers.get('content-length')) > bodyLimit)
+          throw new PayloadTooLargeError()
+
         context.body = await requestBodyParser(
-          req.body,
-          inHeaders,
+          req,
           EMPTY_BODY_METHODS.includes(req.method) ? undefined : schema.body,
-          context.contentType
+          context.contentType,
+          bodyLimit
         )
-        context.headers = inHeaders
         context.query = inQuery
         context.params = inParams
 
@@ -136,63 +173,78 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
             if (error instanceof RequestError) errors.push(error)
             else throw handleInternalError(error)
           }
+          try {
+            // declared cookies are parsed and validated; undeclared ones stay
+            // on the context as the raw strings they arrived as
+            if (schema?.cookies)
+              context.cookies = {
+                ...context.cookies,
+                ...parseEntry(context.cookies, schema.cookies, { name: 'cookies' }),
+              }
+          } catch (error) {
+            if (error instanceof RequestError) errors.push(error)
+            else throw handleInternalError(error)
+          }
           if (errors.length) {
             throw new RequestError({ status: 400, payload: errors.reduce((acc, c) => ({ ...acc, ...c.payload }), {}) })
           }
         }
 
         for (const p of pluginsCb.beforeHandle) {
-          //@ts-ignore
-          const r = await p.beforeHandle(context)
+          const r = await p.beforeHandle(context as Context)
           if (r) return r
         }
 
-        // call chain
-        let handlerCalled = false
-        const handlerWrapper = async (context: Context) => {
-          handlerCalled = true
-          return route.handler(context)
-        }
-        const callChain: { call: () => any }[] = route.hooks.map((hook, idx) => ({
-          call: async () => {
-            let nextCalled = false
-            let next = async () => {
-              if (nextCalled) console.error('Hook already called - ignored')
-              else {
-                nextCalled = true
-                return await callChain[idx + 1]!.call()
-              }
-            }
-            let r = await hook(context as Context, next)
-            if (r) return r
-            if (!nextCalled && !handlerCalled) return await next()
-          },
-        }))
-        callChain.push({
-          call: async () => {
-            response = await handlerWrapper(context as Context)
-            context.set.status = response instanceof Response ? response.status : context.set.status || 200
-          },
-        })
-        const r = await callChain[0]!.call()
-        if (r) response = r
-        if (context.set.status === undefined)
-          context.set.status = response instanceof Response ? response.status : 200
+        // hook/handler chain, composed once at route registration (see galbeMethod)
+        response = await route.composed(context as Context)
+        if (context.set.status === undefined) context.set.status = response instanceof Response ? response.status : 200
 
         const parsedResponse = responseParser(response, context as Context, cookies, schema.response)
 
         if (galbe.config?.responseValidator?.enabled !== false && schema.response && !(response instanceof Response))
           validateResponse(response, schema.response, parsedResponse.status || 200)
 
+        // middleware post-parse slot, composed at registration (see composePost):
+        // route-scoped, so it runs inside the app-scoped plugin slot below
+        let finalResponse = parsedResponse
+        if (route.composedPost) {
+          postRan = true
+          finalResponse = await route.composedPost(finalResponse, context as Context)
+        }
+
         for (const p of pluginsCb.afterHandle) {
-          //@ts-ignore
-          const r = await p.afterHandle(parsedResponse, context)
+          const r = await p.afterHandle(finalResponse, context as Context)
           if (r) return r
         }
 
-        return parsedResponse
+        // HEAD falls back to the GET route in the router (RFC 9110 §9.3.3):
+        // run the normal lifecycle, then strip the body while preserving the
+        // status and headers (incl. content-length) the GET would have sent.
+        if (req.method === 'HEAD')
+          return new Response(null, {
+            status: finalResponse.status,
+            statusText: finalResponse.statusText,
+            headers: finalResponse.headers,
+          })
+
+        return finalResponse
       } catch (error) {
         context.set.status = error instanceof RequestError ? error.status : 500
+        // Route-scoped post-parse hooks run on the error response too: a 400
+        // from validation and a 401 from a `beforeParse` middleware are exactly
+        // the responses an access log exists for. One that throws while an error
+        // is already being answered must not cost us that answer.
+        const post = postRan ? undefined : route?.composedPost
+        const respond = async (res: Response) => {
+          if (!post) return res
+          postRan = true
+          try {
+            return await post(res, context as Context, error)
+          } catch (postError) {
+            console.log(postError)
+            return res
+          }
+        }
         let customError
         for (let eh of galbe.errorCb) {
           const result = await eh(error, context as Context)
@@ -200,14 +252,18 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
           customError = responseParser(result, context as Context, cookies)
           break
         }
-        if (customError) return customError
+        if (customError) return await respond(customError)
         if (error instanceof InternalServerError) {
           let internalPayload = 'Internal Server Error'
-          try { internalPayload = JSON.stringify(error?.payload || internalPayload) } catch {}
-          return new Response(internalPayload, {
-            status: error.status,
-            headers: { 'content-type': 'application/json' },
-          })
+          try {
+            internalPayload = JSON.stringify(error?.payload || internalPayload)
+          } catch {}
+          return await respond(
+            new Response(internalPayload, {
+              status: error.status,
+              headers: { 'content-type': 'application/json' },
+            })
+          )
         } else if (error instanceof RequestError) {
           let payload = error.payload
           // append semantics: context.set.headers always carries the
@@ -234,17 +290,21 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
               } catch (err) {}
             }
           }
-          return new Response(payload, {
-            status: error.status,
-            headers,
-          })
+          return await respond(
+            new Response(payload, {
+              status: error.status,
+              headers,
+            })
+          )
         } else console.log(error)
-        return new Response('"Internal Server Error"', {
-          status: 500,
-          headers: {
-            'content-type': 'application/json',
-          },
-        })
+        return await respond(
+          new Response('"Internal Server Error"', {
+            status: 500,
+            headers: {
+              'content-type': 'application/json',
+            },
+          })
+        )
       }
     },
     error(error) {