@furystack/rest-service 14.1.3 → 14.1.4

package/src/helpers.ts

@@ -47,13 +47,23 @@ export interface ImplementApiOptions<T extends RestApi> {
   description?: string
   /** OpenAPI version. */
   version?: string
+  /** Maximum request body size in bytes. Defaults to 1 MiB. */
+  maxBodyBytes?: number
+  /** Maximum time in ms for handling a request action. When exceeded, responds with 504. Does not abort in-progress body reads. */
+  actionTimeoutMs?: number
+  /** Socket inactivity timeout in ms for the underlying HTTP server (shared per listening port). */
+  requestTimeout?: number
+  /** Time allowed for receiving request headers in ms (shared per listening port). */
+  headersTimeout?: number
+  /** Keep-alive idle timeout in ms (shared per listening port). */
+  keepAliveTimeout?: number
 }
 
 /**
  * Acquires a pooled HTTP server (creating one if needed), compiles `api`
  * and attaches a {@link ServerApi} that dispatches matching requests.
  * Multiple `useRestService` calls on the same `port` + `hostName` share a
- * single underlying HTTP server.
+ * single underlying HTTP server. Server timeout options apply to that shared server.
  */
 export const useRestService = async <T extends RestApi>(options: ImplementApiOptions<T>): Promise<ServerApi> => {
   const {
@@ -68,6 +78,11 @@ export const useRestService = async <T extends RestApi>(options: ImplementApiOpt
     name,
     description,
     version,
+    maxBodyBytes,
+    actionTimeoutMs,
+    requestTimeout,
+    headersTimeout,
+    keepAliveTimeout,
   } = options
 
   const extendedApi: typeof api = enableGetSchema
@@ -104,11 +119,13 @@ export const useRestService = async <T extends RestApi>(options: ImplementApiOpt
         injector,
         hostName,
         deserializeQueryParams,
+        maxBodyBytes,
+        actionTimeoutMs,
       }),
   }
 
   const pool = injector.get(HttpServerPoolToken)
-  const record = await pool.acquire({ port, hostName })
+  const record = await pool.acquire({ port, hostName, requestTimeout, headersTimeout, keepAliveTimeout })
   record.apis.push(serverApi)
   return serverApi
 }
@@ -118,9 +135,13 @@ export const useRestService = async <T extends RestApi>(options: ImplementApiOpt
  * chain (Basic + Cookie by default), appends any caller-provided providers
  * and rebinds {@link HttpAuthenticationSettings}.
  *
- * Prerequisite: {@link UserStore} and {@link SessionStore} must be bound to
- * persistent implementations before calling this helper, since the Basic
- * and Cookie providers need to read users and sessions immediately.
+ * Prerequisites:
+ * - Bind {@link UserStore} and {@link SessionStore} to persistent store implementations first.
+ * - Ensure the backing user/session stores and datasets are registered on the injector.
+ * - Provide `overrides.userDataSet` (or configure a valid `HttpAuthenticationSettings.userDataSet`)
+ *   so user lookups can be resolved.
+ *
+ * The Basic and Cookie providers read users/sessions during setup, so missing bindings will fail early.
  */
 export const useHttpAuthentication = (injector: Injector, overrides?: Partial<HttpAuthenticationSettings>): void => {
   const mergedSettings: HttpAuthenticationSettings = {

package/src/http-authentication-settings.ts

@@ -52,6 +52,20 @@ export interface HttpAuthenticationSettings {
    * {@link DEFAULT_USER_CACHE_CAPACITY} is used by `UserResolutionCache`.
    */
   userCacheCapacity?: number
+  /**
+   * SameSite attribute for the session cookie. Defaults to `'Lax'`.
+   */
+  cookieSameSite?: 'Lax' | 'Strict' | 'None'
+  /**
+   * When `true`, adds the `Secure` attribute so browsers only send the cookie
+   * over HTTPS. Defaults to `false` to allow plain HTTP development setups.
+   */
+  cookieSecure?: boolean
+  /**
+   * Max-Age in seconds for the session cookie. Omit to create a session cookie
+   * without an explicit lifetime attribute.
+   */
+  cookieMaxAgeSeconds?: number
 }
 
 /** Default TTL applied to the user-resolution cache (30 seconds). */
@@ -72,6 +86,8 @@ export const defaultHttpAuthenticationSettings = (): HttpAuthenticationSettings
   authenticationProviders: [],
   userCacheTtlMs: DEFAULT_USER_CACHE_TTL_MS,
   userCacheCapacity: DEFAULT_USER_CACHE_CAPACITY,
+  cookieSameSite: 'Lax',
+  cookieSecure: false,
 })
 
 /**

package/src/http-server-pool.spec.ts

@@ -217,4 +217,31 @@ describe('HttpServerPool', () => {
       await injector[Symbol.asyncDispose]()
     }
   })
+
+  it('Should apply explicit server timeout options', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      const record = await pool.acquire({
+        port,
+        requestTimeout: 12_345,
+        headersTimeout: 23_456,
+        keepAliveTimeout: 3_456,
+      })
+      expect(record.server.requestTimeout).toBe(12_345)
+      expect(record.server.headersTimeout).toBe(23_456)
+      expect(record.server.keepAliveTimeout).toBe(3_456)
+    })
+  })
+
+  it('Should reapply timeout options when acquiring an existing server', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      await pool.acquire({ port, requestTimeout: 10_000 })
+      const record = await pool.acquire({ port, requestTimeout: 20_000, headersTimeout: 30_000 })
+      expect(record.server.requestTimeout).toBe(20_000)
+      expect(record.server.headersTimeout).toBe(30_000)
+    })
+  })
 })

package/src/http-server-pool.ts

@@ -11,6 +11,12 @@ import { ServerTelemetryToken } from './server-telemetry.js'
 export interface ServerOptions {
   hostName?: string
   port: number
+  /** Socket inactivity timeout in ms. Defaults to Node's `server.requestTimeout`. */
+  requestTimeout?: number
+  /** Time allowed for receiving request headers in ms. Defaults to Node's `server.headersTimeout`. */
+  headersTimeout?: number
+  /** Keep-alive idle timeout in ms. Defaults to Node's `server.keepAliveTimeout`. */
+  keepAliveTimeout?: number
 }
 
 /** Payload passed to every {@link ServerApi.onRequest} invocation. */
@@ -99,6 +105,9 @@ export const HttpServerPoolToken: Token<HttpServerPool, 'scoped'> = defineServic
         }
         res.destroy()
       })
+      if (options.requestTimeout !== undefined) server.requestTimeout = options.requestTimeout
+      if (options.headersTimeout !== undefined) server.headersTimeout = options.headersTimeout
+      if (options.keepAliveTimeout !== undefined) server.keepAliveTimeout = options.keepAliveTimeout
       server.on('upgrade', (req, socket, head) => {
         const apiMatch = apis.find((api) => api.shouldExec({ req, res: {} as ServerResponse }))
         if (apiMatch?.onUpgrade) {
@@ -149,16 +158,26 @@ export const HttpServerPoolToken: Token<HttpServerPool, 'scoped'> = defineServic
       servers.clear()
     })
 
+    const applyServerTimeouts = (server: Server, options: ServerOptions): void => {
+      // shortcut: timeout values are per listening server (shared by port); later explicit values override
+      if (options.requestTimeout !== undefined) server.requestTimeout = options.requestTimeout
+      if (options.headersTimeout !== undefined) server.headersTimeout = options.headersTimeout
+      if (options.keepAliveTimeout !== undefined) server.keepAliveTimeout = options.keepAliveTimeout
+    }
+
     return {
       acquire: async (options) => {
         const url = buildHostUrl(options)
         const existing = servers.get(url)
         if (existing) {
+          applyServerTimeouts(existing.server, options)
           return existing
         }
         const pending = pendingCreates.get(url)
         if (pending) {
-          return pending
+          const record = await pending
+          applyServerTimeouts(record.server, options)
+          return record
         }
         const createPromise = createRecord(url, options)
         pendingCreates.set(url, createPromise)

package/src/http-user-context.spec.ts

@@ -370,6 +370,56 @@ describe('HttpUserContext', () => {
   })
 
   describe('cookieLogin / cookieLogout', () => {
+    it('sets SameSite=Lax and HttpOnly on login and can add Secure and Max-Age', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        prepareInjector(i)
+        const ctx = i.get(HttpUserContext)
+        ctx.authentication.cookieSecure = true
+        ctx.authentication.cookieMaxAgeSeconds = 3600
+        const setHeader = vi.fn()
+
+        await ctx.cookieLogin(testUser, { setHeader })
+        expect(setHeader).toHaveBeenCalledWith(
+          'Set-Cookie',
+          expect.stringContaining('Path=/; HttpOnly; SameSite=Lax; Secure; Max-Age=3600'),
+        )
+      })
+    })
+
+    it('uses settings-driven Max-Age and a custom cookie name on login', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        prepareInjector(i)
+        const ctx = i.get(HttpUserContext)
+        ctx.authentication.cookieName = 'sid'
+        ctx.authentication.cookieMaxAgeSeconds = 1800
+        const setHeader = vi.fn()
+
+        await ctx.cookieLogin(testUser, { setHeader })
+        expect(setHeader).toHaveBeenCalledWith(
+          'Set-Cookie',
+          expect.stringMatching(/^sid=[^;]+; Path=\/; HttpOnly; SameSite=Lax; Max-Age=1800$/),
+        )
+      })
+    })
+
+    it('supports SameSite=Strict and forces Secure for SameSite=None', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        prepareInjector(i)
+        const ctx = i.get(HttpUserContext)
+        const strictHeader = vi.fn()
+        ctx.authentication.cookieSameSite = 'Strict'
+        await ctx.cookieLogin(testUser, { setHeader: strictHeader })
+        expect(strictHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('; SameSite=Strict'))
+        expect(strictHeader).toHaveBeenCalledWith('Set-Cookie', expect.not.stringContaining('; Secure'))
+
+        const noneHeader = vi.fn()
+        ctx.authentication.cookieSameSite = 'None'
+        ctx.authentication.cookieSecure = false
+        await ctx.cookieLogin(testUser, { setHeader: noneHeader })
+        expect(noneHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('; SameSite=None; Secure'))
+      })
+    })
+
     it('persists the session, sets the cookie and emits onLogin', async () => {
       await usingAsync(createInjector(), async (i) => {
         prepareInjector(i)
@@ -381,6 +431,10 @@ describe('HttpUserContext', () => {
         const result = await ctx.cookieLogin(testUser, { setHeader })
         expect(result).toBe(testUser)
         expect(setHeader).toHaveBeenCalledTimes(1)
+        expect(setHeader).toHaveBeenCalledWith(
+          'Set-Cookie',
+          expect.stringMatching(/^fss=[^;]+; Path=\/; HttpOnly; SameSite=Lax$/),
+        )
         expect(onLogin).toHaveBeenCalledWith({ user: testUser })
 
         await usingAsync(useSystemIdentityContext({ injector: i, username: 'spec' }), async (systemScope) => {
@@ -411,7 +465,7 @@ describe('HttpUserContext', () => {
         )
         expect(logoutSetHeader).toHaveBeenCalledWith(
           'Set-Cookie',
-          `${ctx.authentication.cookieName}=; Path=/; HttpOnly`,
+          `${ctx.authentication.cookieName}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`,
         )
         expect(onLogout).toHaveBeenCalledWith(undefined)
 

package/src/http-user-context.ts

@@ -137,6 +137,19 @@ class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements Htt
     throw new UnauthenticatedError()
   }
 
+  private buildCookie(value: string, maxAgeSeconds?: number): string {
+    const { cookieName, cookieSameSite = 'Lax', cookieSecure, cookieMaxAgeSeconds } = this.authentication
+    const parts = [`${cookieName}=${value}`, 'Path=/', 'HttpOnly', `SameSite=${cookieSameSite}`]
+    if (cookieSecure || cookieSameSite === 'None') {
+      parts.push('Secure')
+    }
+    const age = maxAgeSeconds ?? cookieMaxAgeSeconds
+    if (age !== undefined) {
+      parts.push(`Max-Age=${age}`)
+    }
+    return parts.join('; ')
+  }
+
   public async cookieLogin(
     user: User,
     response: { setHeader: (header: string, value: string) => void },
@@ -144,7 +157,7 @@ class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements Htt
     const sessionId = randomBytes(32).toString('hex')
     const sessionDataSet = this.systemInjector.get(this.authentication.sessionDataSet)
     await sessionDataSet.add(this.systemInjector, { sessionId, username: user.username })
-    response.setHeader('Set-Cookie', `${this.authentication.cookieName}=${sessionId}; Path=/; HttpOnly`)
+    response.setHeader('Set-Cookie', this.buildCookie(sessionId))
     this.emit('onLogin', { user })
     return user
   }
@@ -154,7 +167,7 @@ class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements Htt
     response: { setHeader: (header: string, value: string) => void },
   ): Promise<void> {
     const sessionId = this.getSessionIdFromRequest(request)
-    response.setHeader('Set-Cookie', `${this.authentication.cookieName}=; Path=/; HttpOnly`)
+    response.setHeader('Set-Cookie', this.buildCookie('', 0))
 
     if (sessionId) {
       const sessionDataSet = this.systemInjector.get(this.authentication.sessionDataSet)

package/src/read-post-body.spec.ts

@@ -0,0 +1,94 @@
+import { getPort } from '@furystack/core/port-generator'
+import { createInjector } from '@furystack/inject'
+import type { IncomingMessage } from 'http'
+import { RequestError } from '@furystack/rest'
+import { usingAsync } from '@furystack/utils'
+import { Readable } from 'stream'
+import { describe, expect, it } from 'vitest'
+import { JsonResult } from './request-action-implementation.js'
+import { useRestService } from './helpers.js'
+import { readPostBody } from './read-post-body.js'
+
+const toRequest = (payload: string | Buffer, maxBytes?: number) => {
+  const body = typeof payload === 'string' ? Buffer.from(payload) : payload
+  return {
+    req: Object.assign(Readable.from([body]), {
+      headers: {},
+      readable: true,
+    }) as unknown as IncomingMessage,
+    options: maxBytes === undefined ? undefined : { maxBytes },
+  }
+}
+
+describe('readPostBody', () => {
+  it('should parse a normal small JSON body', async () => {
+    const { req } = toRequest(JSON.stringify({ ok: true }))
+    await expect(readPostBody<{ ok: boolean }>(req)).resolves.toEqual({ ok: true })
+  })
+
+  it('should accept a body exactly at the size limit', async () => {
+    const payload = 'x'.repeat(10)
+    const { req, options } = toRequest(payload, 10)
+    await expect(readPostBody(req, options)).rejects.toBeInstanceOf(SyntaxError)
+  })
+
+  it('should accept a JSON body exactly at the custom byte limit', async () => {
+    const payload = JSON.stringify({ a: 'b' })
+    const { req, options } = toRequest(payload, Buffer.byteLength(payload))
+    await expect(readPostBody<{ a: string }>(req, options)).resolves.toEqual({ a: 'b' })
+  })
+
+  it('should reject bodies exceeding the default size limit with 413', async () => {
+    const payload = JSON.stringify({ data: 'a'.repeat(1024 * 1024 + 1) })
+    const { req } = toRequest(payload)
+    await expect(readPostBody(req)).rejects.toSatisfy((error: unknown) => {
+      return error instanceof RequestError && error.responseCode === 413
+    })
+  })
+
+  it('should reject bodies exceeding a custom size limit with 413', async () => {
+    const payload = JSON.stringify({ data: 'too-large' })
+    const { req, options } = toRequest(payload, 10)
+    await expect(readPostBody(req, options)).rejects.toSatisfy((error: unknown) => {
+      return error instanceof RequestError && error.responseCode === 413
+    })
+  })
+
+  it('should accept bodies under a custom size limit', async () => {
+    const payload = JSON.stringify({ data: 'ok' })
+    const { req, options } = toRequest(payload, 1024)
+    await expect(readPostBody<{ data: string }>(req, options)).resolves.toEqual({ data: 'ok' })
+  })
+})
+
+describe('useRestService maxBodyBytes', () => {
+  it('should return 413 when the request body exceeds the configured limit', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const port = getPort()
+      await useRestService<{
+        POST: {
+          '/echo': { body: { value: string }; result: { value: string } }
+        }
+      }>({
+        injector: i,
+        root: '/api',
+        port,
+        maxBodyBytes: 16,
+        api: {
+          POST: {
+            '/echo': async ({ getBody }) => JsonResult(await getBody()),
+          },
+        },
+      })
+
+      const response = await fetch(`http://127.0.0.1:${port}/api/echo`, {
+        method: 'POST',
+        body: JSON.stringify({ value: 'this body is definitely too large' }),
+        headers: { 'content-type': 'application/json' },
+      })
+
+      expect(response.status).toBe(413)
+      await expect(response.json()).resolves.toMatchObject({ message: 'Payload Too Large' })
+    })
+  })
+})

package/src/read-post-body.ts

@@ -1,36 +1,73 @@
 import type { IncomingMessage } from 'http'
+import { RequestError } from '@furystack/rest'
 import './incoming-message-extensions.js'
 
-export const readPostBodyRaw = async (incomingMessage: IncomingMessage) => {
+/** Default maximum accepted request body size (1 MiB). */
+export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024
+
+export type ReadPostBodyOptions = {
+  /** Maximum allowed body size in bytes. Defaults to {@link DEFAULT_MAX_BODY_BYTES}. */
+  maxBytes?: number
+}
+
+/**
+ * Reads the full request body into a Buffer and returns it as a UTF-8 string.
+ * Throws `RequestError(413)` when the body exceeds `options.maxBytes`.
+ */
+export const readPostBodyRaw = async (incomingMessage: IncomingMessage, options?: ReadPostBodyOptions) => {
   if (!incomingMessage.readable) {
     throw Error('Incoming message is not readable')
   }
 
-  let body = ''
+  const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BODY_BYTES
+  const chunks: Buffer[] = []
+  let received = 0
+
   await new Promise<void>((resolve, reject) => {
-    incomingMessage.on('readable', () => {
-      const data = incomingMessage.read() as string
-      if (data) {
-        body += data
+    const cleanup = () => {
+      incomingMessage.removeListener('data', onData)
+      incomingMessage.removeListener('end', onEnd)
+      incomingMessage.removeListener('error', onError)
+    }
+
+    const onData = (chunk: Buffer | string) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      received += buffer.length
+      if (received > maxBytes) {
+        cleanup()
+        incomingMessage.resume()
+        reject(new RequestError('Payload Too Large', 413))
+        return
       }
-    })
-    incomingMessage.on('end', () => {
+      chunks.push(buffer)
+    }
+
+    const onEnd = () => {
+      cleanup()
       resolve()
-    })
-    incomingMessage.on('error', (err) => {
+    }
+
+    const onError = (err: Error) => {
+      cleanup()
       reject(err)
-    })
+    }
+
+    incomingMessage.on('data', onData)
+    incomingMessage.on('end', onEnd)
+    incomingMessage.on('error', onError)
   })
-  return body
+
+  return Buffer.concat(chunks).toString('utf8')
 }
 
 /**
- * Reads the post's body and returns a promise with a parsed value
+ * Reads the post's body and returns a promise with a parsed value.
  * @param incomingMessage The incoming message instance
+ * @param options Optional size limit overrides
  * @returns the parsed object from the post body
  */
-export const readPostBody = async <T>(incomingMessage: IncomingMessage): Promise<T> => {
-  const body = (incomingMessage.postBody as T) || (JSON.parse(await readPostBodyRaw(incomingMessage)) as T)
+export const readPostBody = async <T>(incomingMessage: IncomingMessage, options?: ReadPostBodyOptions): Promise<T> => {
+  const body = (incomingMessage.postBody as T) || (JSON.parse(await readPostBodyRaw(incomingMessage, options)) as T)
   incomingMessage.postBody = body
   return body
 }

package/src/rest-api-runtime.ts

@@ -57,6 +57,10 @@ export type OnRestApiMessageOptions = OnRequest & {
   cors?: CorsOptions
   supportedMethods: string[]
   deserializeQueryParams?: (param: string) => Record<string, unknown>
+  /** Maximum request body size in bytes. Defaults to 1 MiB. */
+  maxBodyBytes?: number
+  /** Maximum time in ms for handling a request action. When exceeded, responds with 504. */
+  actionTimeoutMs?: number
 }
 
 /**
@@ -122,7 +126,7 @@ const executeAction = async (
     params: unknown
   },
 ): Promise<void> => {
-  const { injector, req, res, fullUrl, action, deserializeQueryParams, params } = options
+  const { injector, req, res, fullUrl, action, deserializeQueryParams, params, maxBodyBytes, actionTimeoutMs } = options
   await usingAsync(injector.createScope({ owner: action }), async (scope) => {
     const httpUserContext = scope.get(HttpUserContext)
     scope.bind(IdentityContext, () => ({
@@ -130,27 +134,70 @@ const executeAction = async (
       isAuthorized: (...roles) => httpUserContext.isAuthorized(req, ...roles),
       isAuthenticated: () => httpUserContext.isAuthenticated(req),
     }))
-    try {
-      const actionResult = await action({
+
+    const canRespond = () => !res.writableEnded && !res.headersSent
+    const sendResult = (actionResult: Awaited<ReturnType<typeof action>>) => {
+      if (canRespond()) res.sendActionResult(actionResult)
+    }
+    const sendError = async (error: unknown) => {
+      if (!canRespond()) return
+      const errorActionResult = await ErrorAction({
         request: req,
         response: res,
         injector: scope,
-        getBody: () => readPostBody<never>(req),
-        headers: req.headers,
-        getQuery: () =>
-          deserializeQueryParams ? deserializeQueryParams(fullUrl.search) : deserializeQueryString(fullUrl.search),
-        getUrlParams: () => params as object,
+        getBody: async () => error,
       })
-      res.sendActionResult(actionResult)
-    } catch (error) {
-      const errorActionResult = await ErrorAction({
+      if (canRespond()) res.sendActionResult(errorActionResult)
+    }
+
+    const runAction = async () =>
+      action({
         request: req,
         response: res,
         injector: scope,
-        getBody: async () => error,
+        // shortcut: actionTimeoutMs does not abort in-progress body reads; use server/request timeouts for slow clients
+        getBody: () => readPostBody<never>(req, maxBodyBytes === undefined ? undefined : { maxBytes: maxBodyBytes }),
+        headers: req.headers,
+        getQuery: () =>
+          deserializeQueryParams ? deserializeQueryParams(fullUrl.search) : deserializeQueryString(fullUrl.search),
+        getUrlParams: () => params as object,
       })
-      res.sendActionResult(errorActionResult)
+
+    if (!actionTimeoutMs || actionTimeoutMs <= 0) {
+      try {
+        sendResult(await runAction())
+      } catch (error) {
+        await sendError(error)
+      }
+      return
     }
+
+    let timedOut = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    // shortcut: timed-out action may keep running (no AbortSignal) and scope may dispose before it settles; late writes/errors are suppressed
+    const actionPromise = runAction().then(
+      async (actionResult) => {
+        if (timedOut) return
+        sendResult(actionResult)
+      },
+      async (error) => {
+        if (timedOut) return
+        await sendError(error)
+      },
+    )
+
+    await new Promise<void>((resolve) => {
+      timer = setTimeout(() => {
+        timedOut = true
+        void sendError(new RequestError('Request Timeout', 504)).finally(resolve)
+      }, actionTimeoutMs)
+      void actionPromise.finally(() => {
+        if (!timedOut) {
+          if (timer) clearTimeout(timer)
+          resolve()
+        }
+      })
+    })
   })
 }
 

package/src/rest-service.integration.spec.ts

@@ -179,6 +179,82 @@ describe('@furystack/rest-service integration tests', () => {
       expect(result.message).toBe('Failed to decode URL path parameter')
     })
   })
+
+  it('returns 504 when an action exceeds actionTimeoutMs', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const port = getPort()
+      await useRestService<{ GET: { '/slow': { result: { ok: boolean } } } }>({
+        injector: i,
+        root: '/api',
+        port,
+        actionTimeoutMs: 50,
+        api: {
+          GET: {
+            '/slow': async () => new Promise<never>(() => {}),
+          },
+        },
+      })
+      const response = await fetch(`http://127.0.0.1:${port}/api/slow`)
+      expect(response.status).toBe(504)
+      await expect(response.json()).resolves.toMatchObject({ message: 'Request Timeout' })
+    })
+  })
+
+  it('returns a single 504 when an action resolves after timeout', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const port = getPort()
+      await useRestService<{ GET: { '/late-ok': { result: { ok: boolean } } } }>({
+        injector: i,
+        root: '/api',
+        port,
+        actionTimeoutMs: 30,
+        api: {
+          GET: {
+            '/late-ok': async () => {
+              await new Promise((r) => setTimeout(r, 80))
+              return JsonResult({ ok: true })
+            },
+          },
+        },
+      })
+      const response = await fetch(`http://127.0.0.1:${port}/api/late-ok`)
+      expect(response.status).toBe(504)
+      await expect(response.json()).resolves.toMatchObject({ message: 'Request Timeout' })
+      await new Promise((r) => setTimeout(r, 120))
+    })
+  })
+
+  it('returns a single 504 without unhandled rejection when an action rejects after timeout', async () => {
+    const unhandled: unknown[] = []
+    const onUnhandled = (reason: unknown) => unhandled.push(reason)
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      await usingAsync(createInjector(), async (i) => {
+        const port = getPort()
+        await useRestService<{ GET: { '/late-fail': { result: { ok: boolean } } } }>({
+          injector: i,
+          root: '/api',
+          port,
+          actionTimeoutMs: 30,
+          api: {
+            GET: {
+              '/late-fail': async () => {
+                await new Promise((r) => setTimeout(r, 80))
+                throw new Error('late boom')
+              },
+            },
+          },
+        })
+        const response = await fetch(`http://127.0.0.1:${port}/api/late-fail`)
+        expect(response.status).toBe(504)
+        await expect(response.json()).resolves.toMatchObject({ message: 'Request Timeout' })
+        await new Promise((r) => setTimeout(r, 120))
+      })
+      expect(unhandled).toEqual([])
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
 })
 
 describe('HttpServerPool telemetry', () => {