@furystack/rest-service 14.0.0 → 14.1.0

package/src/request-action-implementation.ts

@@ -1,12 +1,17 @@
 import type { Injector } from '@furystack/inject'
 import type { IncomingMessage, ServerResponse } from 'http'
 
+/**
+ * The shape returned by every {@link RequestAction}. Consumed by the runtime
+ * to write the response (`statusCode`, `headers`, serialized `chunk`).
+ */
 export interface ActionResult<T> {
   statusCode: number
   headers: { [K: string]: string }
   chunk: T
 }
 
+/** {@link ActionResult} with `application/json`. Default status 200. */
 export const JsonResult = <T extends object>(chunk: T, statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -17,6 +22,7 @@ export const JsonResult = <T extends object>(chunk: T, statusCode = 200, headers
     },
   }) as ActionResult<T>
 
+/** {@link ActionResult} with `plain/text`. Default status 200. */
 export const PlainTextResult = (text: string, statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -27,6 +33,7 @@ export const PlainTextResult = (text: string, statusCode = 200, headers?: { [K:
     },
   }) as ActionResult<string>
 
+/** {@link ActionResult} with `application/xml;charset=utf-8`. Default status 200. */
 export const XmlResult = (text: string, statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -37,6 +44,7 @@ export const XmlResult = (text: string, statusCode = 200, headers?: { [K: string
     },
   }) as ActionResult<string>
 
+/** {@link ActionResult} with no body. Use for `204 No Content` responses. */
 export const EmptyResult = (statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -45,11 +53,22 @@ export const EmptyResult = (statusCode = 200, headers?: { [K: string]: string })
     },
   }) as ActionResult<undefined>
 
+/**
+ * Sentinel result that signals "skip this action; let the runtime fall
+ * through to the next matching handler (or 404 if none)". Returned from
+ * an action when it decides not to handle the request after inspection.
+ */
 export const BypassResult = () =>
   ({
     chunk: 'BypassResult',
   }) as ActionResult<'BypassResult'>
 
+/**
+ * Argument shape passed to a {@link RequestAction}. Conditional members
+ * (`getBody`, `getUrlParams`, `getQuery`, `headers`) are present only when
+ * the action's contract declares the corresponding key — keeping unrelated
+ * actions free of unused parser allocations.
+ */
 export type RequestActionOptions<T extends { result: unknown }> = {
   request: IncomingMessage
   response: ServerResponse
@@ -64,6 +83,12 @@ export type RequestActionOptions<T extends { result: unknown }> = {
   (T extends { result: unknown; query: infer U } ? { getQuery: () => U } : unknown) &
   (T extends { result: unknown; headers: infer U } ? { headers: U } : unknown)
 
+/**
+ * Server-side implementation of a typed REST endpoint contract `T` (declared
+ * via `@furystack/rest`). Receives {@link RequestActionOptions} narrowed to
+ * the contract's body/url/query/headers and resolves to an {@link ActionResult}
+ * carrying the contract's `result` shape.
+ */
 export type RequestAction<T extends { result: unknown }> = (
   options: RequestActionOptions<T>,
 ) => Promise<ActionResult<T['result']>>

package/src/rest-api-runtime.spec.ts

@@ -15,7 +15,7 @@ type SampleApi = {
 const buildImplementation = (): RestApiImplementation<SampleApi> => ({
   GET: {
     '/items': async () => JsonResult({ items: [1, 2, 3] }),
-    '/items/:id': async ({ getUrlParams }) => JsonResult({ id: (getUrlParams() as { id: string }).id }),
+    '/items/:id': async ({ getUrlParams }) => JsonResult({ id: getUrlParams().id }),
   },
   POST: {
     '/items': async ({ getBody }) => JsonResult(await getBody()),

package/src/server-telemetry.ts

@@ -4,32 +4,24 @@ import type { IncomingMessage, ServerResponse } from 'http'
 import type { Data, WebSocket } from 'ws'
 
 /**
- * Union of every server-lifecycle event the rest-service runtime emits. Replaces
- * the `EventHub`s that used to live on the deleted `ServerManager`,
- * `ProxyManager` and `WebSocketApi` classes — consumers subscribe once to the
- * telemetry singleton and receive events from every source.
+ * Union of every server-lifecycle event the rest-service runtime emits.
+ * The HTTP server pool, proxy runtime and websocket-api all forward into
+ * this single hub so subscribers can observe every source from one place.
  */
 export type ServerTelemetryEvents = {
-  /** Emitted when the pool successfully opens an HTTP listener. */
   onServerListening: { url: string; port: number; hostName?: string }
-  /** Emitted when the pool closes an HTTP listener during disposal. */
   onServerClosed: { url: string }
-  /** Emitted when an API's `onRequest` rejects. Tuple matches the original `ServerManager` payload. */
+  /** Tuple-shaped to match the underlying Node `request` callback signature. */
   onRequestFailed: [unknown, IncomingMessage, ServerResponse<IncomingMessage>]
-  /** Emitted when an HTTP proxy round-trip fails. */
   onProxyFailed: { from: string; to: string; error: unknown }
-  /** Emitted when a WebSocket proxy upgrade fails. */
   onWebSocketProxyFailed: { from: string; to: string; error: unknown }
-  /** Emitted when a WebSocket API action fails during lookup or execution. */
   onWebSocketActionFailed: { error: unknown; data?: Data; socket?: WebSocket }
-  /** Emitted when a listener registered on this telemetry hub throws. */
   onListenerError: ListenerErrorPayload
 }
 
 /**
- * Telemetry surface exposed to applications. Extending {@link EventHub}
- * gives subscribers the same `addListener` / `subscribe` / `emit` API they
- * were using on the pre-migration managers.
+ * Application-facing telemetry surface. Extends {@link EventHub} so
+ * subscribers use the standard `addListener` / `subscribe` API.
  */
 export class ServerTelemetry extends EventHub<ServerTelemetryEvents> {}
 

package/src/user-resolution-cache.spec.ts

@@ -0,0 +1,241 @@
+import type { User } from '@furystack/core'
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { HttpAuthenticationSettings, defaultHttpAuthenticationSettings } from './http-authentication-settings.js'
+import { resolveUserCacheKey, UserResolutionCache } from './user-resolution-cache.js'
+
+const testUser: User = { username: 'alice', roles: ['reader'] }
+const otherUser: User = { username: 'bob', roles: [] }
+
+describe('UserResolutionCache', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('resolve', () => {
+    it('returns the loader result on first call and reuses it on subsequent calls within TTL', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(async () => testUser)
+        const first = await cache.resolve('cookie:abc', loader)
+        const second = await cache.resolve('cookie:abc', loader)
+        expect(first).toBe(testUser)
+        expect(second).toBe(testUser)
+        expect(loader).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('treats distinct cache keys independently', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loaderA = vi.fn(async () => testUser)
+        const loaderB = vi.fn(async () => otherUser)
+        expect(await cache.resolve('cookie:a', loaderA)).toBe(testUser)
+        expect(await cache.resolve('cookie:b', loaderB)).toBe(otherUser)
+        expect(await cache.resolve('cookie:a', loaderA)).toBe(testUser)
+        expect(loaderA).toHaveBeenCalledTimes(1)
+        expect(loaderB).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('drops the entry once cacheTimeMs has elapsed', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 100,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(async () => testUser)
+        await cache.resolve('cookie:ttl', loader)
+        await vi.advanceTimersByTimeAsync(150)
+        await cache.resolve('cookie:ttl', loader)
+        expect(loader).toHaveBeenCalledTimes(2)
+      })
+    })
+
+    it('runs the loader on every call when ttl is 0', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 0,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(async () => testUser)
+        await cache.resolve('cookie:disabled', loader)
+        await cache.resolve('cookie:disabled', loader)
+        expect(loader).toHaveBeenCalledTimes(2)
+        expect(cache.size).toBe(0)
+      })
+    })
+
+    it('dedupes concurrent loaders for the same key', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(
+          () =>
+            new Promise<User>((resolve) => {
+              setTimeout(() => resolve(testUser), 100)
+            }),
+        )
+        const both = Promise.all([cache.resolve('cookie:dedupe', loader), cache.resolve('cookie:dedupe', loader)])
+        await vi.advanceTimersByTimeAsync(150)
+        const [a, b] = await both
+        expect(a).toBe(testUser)
+        expect(b).toBe(testUser)
+        expect(loader).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('rejects (without caching) when the loader throws', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi
+          .fn<() => Promise<User>>()
+          .mockRejectedValueOnce(new Error('boom'))
+          .mockResolvedValueOnce(testUser)
+        await expect(cache.resolve('cookie:err', loader)).rejects.toThrow('boom')
+        await expect(cache.resolve('cookie:err', loader)).resolves.toBe(testUser)
+        expect(loader).toHaveBeenCalledTimes(2)
+      })
+    })
+  })
+
+  describe('invalidate', () => {
+    it('drops the targeted entry only', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loaderA = vi.fn(async () => testUser)
+        const loaderB = vi.fn(async () => otherUser)
+        await cache.resolve('cookie:a', loaderA)
+        await cache.resolve('cookie:b', loaderB)
+        cache.invalidate('cookie:a')
+        await cache.resolve('cookie:a', loaderA)
+        await cache.resolve('cookie:b', loaderB)
+        expect(loaderA).toHaveBeenCalledTimes(2)
+        expect(loaderB).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+
+  describe('invalidateAll', () => {
+    it('flushes every entry', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        await cache.resolve('cookie:a', async () => testUser)
+        await cache.resolve('cookie:b', async () => otherUser)
+        expect(cache.size).toBe(2)
+        cache.invalidateAll()
+        expect(cache.size).toBe(0)
+      })
+    })
+  })
+
+  describe('invalidateByUser', () => {
+    it('drops every cached session that resolved to the supplied username', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const aliceLoaderA = vi.fn(async () => testUser)
+        const aliceLoaderB = vi.fn(async () => testUser)
+        const bobLoader = vi.fn(async () => otherUser)
+        await cache.resolve('cookie:alice-1', aliceLoaderA)
+        await cache.resolve('cookie:alice-2', aliceLoaderB)
+        await cache.resolve('cookie:bob-1', bobLoader)
+        expect(cache.size).toBe(3)
+
+        cache.invalidateByUser('alice')
+
+        expect(cache.size).toBe(1)
+        await cache.resolve('cookie:alice-1', aliceLoaderA)
+        await cache.resolve('cookie:alice-2', aliceLoaderB)
+        await cache.resolve('cookie:bob-1', bobLoader)
+        expect(aliceLoaderA).toHaveBeenCalledTimes(2)
+        expect(aliceLoaderB).toHaveBeenCalledTimes(2)
+        expect(bobLoader).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('is a no-op when the username is unknown', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        await cache.resolve('cookie:alice-1', async () => testUser)
+        await cache.resolve('cookie:bob-1', async () => otherUser)
+        cache.invalidateByUser('charlie')
+        expect(cache.size).toBe(2)
+      })
+    })
+
+    it('is a no-op when caching is disabled (ttl = 0)', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 0,
+        }))
+        const cache = i.get(UserResolutionCache)
+        expect(() => cache.invalidateByUser('alice')).not.toThrow()
+        expect(cache.size).toBe(0)
+      })
+    })
+  })
+})
+
+describe('resolveUserCacheKey', () => {
+  it('returns the first non-null key from the configured providers', () => {
+    const settings = {
+      ...defaultHttpAuthenticationSettings(),
+      authenticationProviders: [
+        { name: 'first', authenticate: async () => null, getCacheKey: () => null },
+        { name: 'second', authenticate: async () => null, getCacheKey: () => 'cookie:matched' },
+        { name: 'third', authenticate: async () => null, getCacheKey: () => 'jwt:not-reached' },
+      ],
+    }
+    expect(resolveUserCacheKey(settings, { headers: {} })).toBe('cookie:matched')
+  })
+
+  it('returns null when every provider opts out', () => {
+    const settings = {
+      ...defaultHttpAuthenticationSettings(),
+      authenticationProviders: [
+        { name: 'a', authenticate: async () => null },
+        { name: 'b', authenticate: async () => null, getCacheKey: () => null },
+      ],
+    }
+    expect(resolveUserCacheKey(settings, { headers: {} })).toBeNull()
+  })
+})

package/src/user-resolution-cache.ts

@@ -0,0 +1,164 @@
+import type { User } from '@furystack/core'
+import { Cache } from '@furystack/cache'
+import { defineService, type Token } from '@furystack/inject'
+import type { IncomingMessage } from 'http'
+import type { AuthenticationProvider } from './authentication-providers/authentication-provider.js'
+import {
+  DEFAULT_USER_CACHE_CAPACITY,
+  DEFAULT_USER_CACHE_TTL_MS,
+  HttpAuthenticationSettings,
+} from './http-authentication-settings.js'
+import type { HttpUserContext } from './http-user-context.js'
+import { userCacheTag, type UserCacheTag } from './identity-cache-keys.js'
+
+/**
+ * Singleton TTL cache that memoizes successful identity resolutions across
+ * requests within a single process.
+ *
+ * Cache keys are produced by the configured {@link AuthenticationProvider}s
+ * via their `getCacheKey` method (e.g. cookie-auth keys by session id). The
+ * cache's `load` callback runs the same provider chain that
+ * {@link HttpUserContext.authenticateRequest} would run — it is supplied via
+ * an internal "loader" registered when the {@link HttpUserContext} is
+ * resolved.
+ *
+ * Entries expire after `HttpAuthenticationSettings.userCacheTtlMs`; capacity
+ * is bounded by `HttpAuthenticationSettings.userCacheCapacity`. Setting the
+ * TTL to `0` disables caching (the loader runs on every call).
+ *
+ * **Multi-node note:** session invalidation on one instance does not
+ * propagate to siblings — the TTL bounds the staleness window. Apps that
+ * need stricter freshness must shorten the TTL or invalidate explicitly via
+ * {@link UserResolutionCache.invalidate} /
+ * {@link UserResolutionCache.invalidateByUser}.
+ */
+export interface UserResolutionCache extends Disposable {
+  /**
+   * Returns the cached or freshly-resolved `User` for the supplied
+   * cache key. The `loader` is invoked on cache miss; concurrent calls for
+   * the same key dedupe to a single loader invocation.
+   */
+  resolve(cacheKey: string, loader: () => Promise<User>): Promise<User>
+  /** Drops a single cache entry. No-op when the key is unknown. */
+  invalidate(cacheKey: string): void
+  /**
+   * Drops every cached entry that resolved to `username`, regardless of
+   * which {@link AuthenticationProvider}'s key originally populated it.
+   * Backed by the cache's reverse tag index — no per-call O(n) scan.
+   *
+   * Use after role / password / account-state changes that must take
+   * effect immediately on the next request, instead of waiting for the
+   * TTL window to elapse.
+   */
+  invalidateByUser(username: string): void
+  /** Drops every cached entry. */
+  invalidateAll(): void
+  /** Returns the current entry count (for diagnostics / tests). */
+  readonly size: number
+}
+
+class UserResolutionCacheImpl implements UserResolutionCache {
+  private readonly loaders = new Map<string, () => Promise<User>>()
+  private readonly cache: Cache<User, [string], UserCacheTag> | null
+
+  constructor(ttlMs: number, capacity: number) {
+    if (ttlMs <= 0) {
+      this.cache = null
+      return
+    }
+    this.cache = new Cache<User, [string], UserCacheTag>({
+      load: (cacheKey) => {
+        const loader = this.loaders.get(cacheKey)
+        if (!loader) {
+          // The loader is only registered for the duration of a `resolve()`
+          // call. A reload triggered via `cache.get(key)` outside that call
+          // (e.g. from `getObservable`) would have no loader; refuse the
+          // load instead of caching `null`.
+          return Promise.reject(new Error(`No loader registered for cache key '${cacheKey}'`))
+        }
+        return loader()
+      },
+      cacheTimeMs: ttlMs,
+      capacity,
+      getKey: (cacheKey) => cacheKey,
+      getTags: (user) => [userCacheTag(user.username)],
+    })
+  }
+
+  public async resolve(cacheKey: string, loader: () => Promise<User>): Promise<User> {
+    if (!this.cache) {
+      return loader()
+    }
+    this.loaders.set(cacheKey, loader)
+    try {
+      return await this.cache.get(cacheKey)
+    } finally {
+      // Loader is per-request; clearing prevents the cache from re-running it
+      // out-of-band when the entry transitions to obsolete and a sibling call
+      // queries `getObservable`.
+      this.loaders.delete(cacheKey)
+    }
+  }
+
+  public invalidate(cacheKey: string): void {
+    this.cache?.remove(cacheKey)
+  }
+
+  public invalidateByUser(username: string): void {
+    this.cache?.removeByTag(userCacheTag(username))
+  }
+
+  public invalidateAll(): void {
+    this.cache?.flushAll()
+  }
+
+  public get size(): number {
+    return this.cache?.getCount() ?? 0
+  }
+
+  public [Symbol.dispose](): void {
+    this.cache?.[Symbol.dispose]()
+    this.loaders.clear()
+  }
+}
+
+/**
+ * DI token for the singleton {@link UserResolutionCache}. Resolved lazily
+ * by {@link HttpUserContext}; sized from {@link HttpAuthenticationSettings}.
+ */
+export const UserResolutionCache: Token<UserResolutionCache, 'singleton'> = defineService({
+  name: 'furystack/rest-service/UserResolutionCache',
+  lifetime: 'singleton',
+  factory: ({ inject, onDispose }): UserResolutionCache => {
+    const settings = inject(HttpAuthenticationSettings)
+    const ttlMs = settings.userCacheTtlMs ?? DEFAULT_USER_CACHE_TTL_MS
+    const capacity = settings.userCacheCapacity ?? DEFAULT_USER_CACHE_CAPACITY
+    const impl = new UserResolutionCacheImpl(ttlMs, capacity)
+    onDispose(() => {
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- onDispose is the teardown hook
+      impl[Symbol.dispose]()
+    })
+    return impl
+  },
+})
+
+/**
+ * Resolves the configured cache key for the supplied request by walking the
+ * authentication providers in order and returning the first non-null key.
+ *
+ * Returns `null` when no provider opts in to caching (e.g. Basic Auth, or
+ * an anonymous request). The caller should bypass the cache in that case.
+ *
+ * Exported so plugins / tests can derive the same key the cache uses.
+ */
+export const resolveUserCacheKey = (
+  settings: HttpAuthenticationSettings,
+  request: Pick<IncomingMessage, 'headers'>,
+): string | null => {
+  for (const provider of settings.authenticationProviders) {
+    if (!provider.getCacheKey) continue
+    const key = provider.getCacheKey(request)
+    if (key) return key
+  }
+  return null
+}

package/src/user-store.ts

@@ -1,5 +1,6 @@
 import { defineStore, type StoreToken, User } from '@furystack/core'
 import { defineDataSet, type DataSetToken } from '@furystack/repository'
+import type { HttpUserContext } from './http-user-context.js'
 import { DefaultSession } from './models/default-session.js'
 
 /**

package/src/validate.integration.spec.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unnecessary-type-assertion -- false positives: `client` is typed for a narrow `RestApi`; casts to `ReturnType<typeof createClient<...>>` widen it so this test can exercise endpoints (e.g. `/openapi.json`) the production type intentionally hides */
 import { InMemoryStore, User as UserModel } from '@furystack/core'
 import { getPort } from '@furystack/core/port-generator'
 import { createInjector } from '@furystack/inject'

package/src/validate.ts

@@ -1,9 +1,7 @@
 import type { ActionResult, RequestAction, RequestActionOptions } from './request-action-implementation.js'
+import type { SchemaValidationError } from './schema-validator/schema-validation-error.js'
 import { SchemaValidator } from './schema-validator/schema-validator.js'
 
-/**
- * Represents a JSON Schema definition structure
- */
 type JsonSchemaDefinition = {
   required?: string[]
   additionalProperties?: boolean
@@ -17,22 +15,26 @@ type JsonSchemaDefinition = {
   [key: string]: unknown
 }
 
-/**
- * Represents a JSON Schema with definitions
- */
 type JsonSchemaWithDefinitions = {
   definitions: Record<string, JsonSchemaDefinition>
 }
 
+/**
+ * Wraps a {@link RequestAction} with JSON Schema validation. The wrapper
+ * pre-validates `query`, `body`, `url` and `headers` against the named
+ * schema entry, throws {@link SchemaValidationError} on failure (caught by
+ * `ErrorAction` to return 400), then forwards the validated values to the
+ * inner action.
+ *
+ * The wrapped function exposes `schema` and `schemaName` so OpenAPI
+ * generators can reflect on the action without re-parsing the source.
+ *
+ * `furystack/rest-action-validate-wrapper` enforces this on REST actions.
+ */
 export const Validate =
   <TSchema extends JsonSchemaWithDefinitions>(validationOptions: {
-    /**
-     * The Schema object
-     */
     schema: TSchema
-    /**
-     * Entity key from the JSON Schema object
-     */
+    /** Entry under `schema.definitions` describing this endpoint's request shape. */
     schemaName: keyof TSchema['definitions']
   }) =>
   <T extends { result: unknown }>(