@znight/websocket 0.0.0-stage → 0.6.0

package/src/compiler/constants.ts

@@ -0,0 +1,102 @@
+/**
+ * Constants shared by the compiler extension modules. This module stays free of runtime imports: the
+ * extension entry is loaded by the compiler, which must never load the WebSocket runtime (spec §2).
+ */
+import type { ErrorCode } from '@znight/core'
+
+/** Name of the extension, also the key of `metadata.extensions.websocket`. */
+export const EXTENSION_NAME = 'websocket'
+
+/** Module the generated code imports its helpers and types from. */
+export const RUNTIME_MODULE = '@znight/websocket'
+
+/** Canonical identities of the decorators owned by the extension. */
+export const WsDecorator: {
+  readonly Gateway: '@znight/websocket#Gateway'
+  readonly OnConnect: '@znight/websocket#OnConnect'
+  readonly OnMessage: '@znight/websocket#OnMessage'
+  readonly OnDisconnect: '@znight/websocket#OnDisconnect'
+  readonly Payload: '@znight/websocket#Payload'
+  readonly Conn: '@znight/websocket#Conn'
+  readonly Ctx: '@znight/websocket#Ctx'
+  readonly UseHandshakeGuard: '@znight/websocket#UseHandshakeGuard'
+  readonly UseMessageGuard: '@znight/websocket#UseMessageGuard'
+} = Object.freeze({
+  Gateway: '@znight/websocket#Gateway',
+  OnConnect: '@znight/websocket#OnConnect',
+  OnMessage: '@znight/websocket#OnMessage',
+  OnDisconnect: '@znight/websocket#OnDisconnect',
+  Payload: '@znight/websocket#Payload',
+  Conn: '@znight/websocket#Conn',
+  Ctx: '@znight/websocket#Ctx',
+  UseHandshakeGuard: '@znight/websocket#UseHandshakeGuard',
+  UseMessageGuard: '@znight/websocket#UseMessageGuard',
+})
+
+/** Decorators giving a method a role. */
+export const ROLE_DECORATORS: ReadonlySet<string> = new Set([
+  WsDecorator.OnConnect,
+  WsDecorator.OnMessage,
+  WsDecorator.OnDisconnect,
+])
+
+/** Decorators applied to methods (roles and message guards). */
+export const METHOD_DECORATORS: ReadonlySet<string> = new Set([...ROLE_DECORATORS, WsDecorator.UseMessageGuard])
+
+/** Decorators applied to handler parameters. */
+export const PARAMETER_DECORATORS: ReadonlySet<string> = new Set([
+  WsDecorator.Payload,
+  WsDecorator.Conn,
+  WsDecorator.Ctx,
+])
+
+/** ZNIGHT005: invalid decorator usage. */
+export const INVALID_DECORATOR: ErrorCode = 'ZNIGHT005'
+/** ZNIGHT007: invalid or conflicting gateway path. */
+export const INVALID_ROUTE: ErrorCode = 'ZNIGHT007'
+/** ZNIGHT017: non-primitive `@Payload()` without schema. */
+export const UNVALIDATED_INPUT: ErrorCode = 'ZNIGHT017'
+/** ZNIGHT023: a gateway without a decision of a required route decorator group (RFC 0001). */
+export const MISSING_ROUTE_DECISION: ErrorCode = 'ZNIGHT023'
+/** ZNIGHT050: invalid gateway. */
+export const INVALID_GATEWAY: ErrorCode = 'ZNIGHT050'
+
+/** Event names of the `events` protocol (the runtime `EVENT_NAME`, checked by the tests). */
+export const EVENT_NAME: RegExp = /^[A-Za-z][\w.:/-]{0,127}$/
+
+/** RFC 7230 token: subprotocol names. */
+export const SUBPROTOCOL: RegExp = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+/** Deterministic string comparison (never `localeCompare`). */
+export function compareStrings(a: string, b: string): number {
+  if (a === b) return 0
+  return a < b ? -1 : 1
+}
+
+const UNITS: Readonly<Record<string, number>> = {
+  b: 1,
+  k: 1024,
+  kb: 1024,
+  kib: 1024,
+  m: 1024 ** 2,
+  mb: 1024 ** 2,
+  mib: 1024 ** 2,
+  g: 1024 ** 3,
+  gb: 1024 ** 3,
+  gib: 1024 ** 3,
+}
+
+const SIZE = /^(\d+(?:\.\d+)?|\.\d+)\s*([a-z]*)$/i
+
+/** A positive byte size (`'64kb'`, `65536`), the grammar of `ByteSize`; `undefined` otherwise. */
+export function parseSize(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isSafeInteger(value) && value > 0 ? value : undefined
+  if (typeof value !== 'string') return undefined
+  const match = SIZE.exec(value.trim())
+  if (match === null) return undefined
+  const unit = (match[2] as string).toLowerCase()
+  const multiplier = unit === '' ? 1 : UNITS[unit]
+  if (multiplier === undefined) return undefined
+  const bytes = Math.floor(Number(match[1]) * multiplier)
+  return Number.isSafeInteger(bytes) && bytes > 0 ? bytes : undefined
+}

package/src/compiler/data.ts

@@ -0,0 +1,78 @@
+/** What `analyzeClass` stores for `validate` and `generate` (plain, serialisable data). */
+import type { ClassRef, Location, ValueRef } from '@znight/compiler'
+import type { Token } from '@znight/core'
+import type { MetaEntry } from '@znight/http/compiler'
+
+/** A parameter of a handler, as the generated `invoke` passes it. */
+export type WsParamData =
+  | { readonly kind: 'payload' }
+  | { readonly kind: 'validated'; readonly schema: ValueRef }
+  | { readonly kind: 'connection' }
+  | { readonly kind: 'context' }
+  /** An optional parameter without decorator, or a parameter in error (reported). */
+  | { readonly kind: 'undefined'; readonly optional: boolean }
+
+/** `@OnConnect` or `@OnDisconnect`. */
+export interface LifecycleData {
+  readonly method: string
+  readonly params: readonly WsParamData[]
+  readonly declaredBy: string
+  readonly location: Location
+}
+
+/** One `@OnMessage` handler (a method decorated several times gives one entry per event). */
+export interface HandlerData {
+  readonly method: string
+  /** `undefined`: the default handler. */
+  readonly event: string | undefined
+  /** Route decorators of the method. */
+  readonly meta: readonly MetaEntry[]
+  /** `@UseMessageGuard` of the method. */
+  readonly guards: readonly ClassRef[]
+  readonly params: readonly WsParamData[]
+  readonly declaredBy: string
+  readonly location: Location
+}
+
+/** Static options of `@Gateway`. */
+export interface GatewayOptionsData {
+  readonly protocol: 'events' | 'raw'
+  readonly protocols?: readonly string[]
+  readonly maxPayload?: number
+  readonly concurrency?: number
+  readonly rateLimit?: { readonly messages: number; readonly intervalMs: number; readonly onLimit: 'reject' | 'close' }
+  readonly backpressure?: { readonly limit?: number; readonly onLimit?: 'close' | 'drop' }
+}
+
+/** A `@Gateway` class. */
+export interface GatewayData {
+  readonly kind: 'gateway'
+  readonly token: Token
+  readonly identity: string
+  readonly displayName: string
+  /** Normalised path; `undefined` when invalid (reported). */
+  readonly path: string | undefined
+  readonly options: GatewayOptionsData
+  /** Route decorators of the class. */
+  readonly meta: readonly MetaEntry[]
+  readonly handshakeGuards: readonly ClassRef[]
+  readonly messageGuards: readonly ClassRef[]
+  readonly onConnect: LifecycleData | undefined
+  readonly onDisconnect: LifecycleData | undefined
+  readonly handlers: readonly HandlerData[]
+  /** Identities of the class and its analysable bases (nearest first). */
+  readonly chain: readonly string[]
+  readonly location: Location
+}
+
+/** A class carrying websocket decorators without `@Gateway` (a base class, or a mistake). */
+export interface MemberClassData {
+  readonly kind: 'members'
+  readonly identity: string
+  readonly displayName: string
+  readonly abstract: boolean
+  readonly decorators: readonly { readonly name: string; readonly location: Location }[]
+}
+
+/** Everything the extension stores. */
+export type WebSocketData = GatewayData | MemberClassData

package/src/compiler/generate.ts

@@ -0,0 +1,262 @@
+/**
+ * `generate` of the websocket extension (RFC 0003 §7): `metadata.extensions.websocket`, gateways
+ * sorted by token, handlers in declaration order (bases first), optional fields omitted.
+ *
+ * ```ts
+ * {
+ *   gateways: [{
+ *     token: 'src/chat/chat.gateway.ts#ChatGateway',
+ *     path: '/chat',
+ *     protocol: 'events',
+ *     meta: { authenticated: true },
+ *     handshakeGuards: [],
+ *     messageGuards: [],
+ *     onConnect: { method: 'connected', invoke: (g: ChatGateway, c: WsConnection) => g.connected(c as never) },
+ *     handlers: [{
+ *       method: 'join', event: 'room.join', meta: {}, guards: [], params: [...],
+ *       invoke: async (g: ChatGateway, m: WsMessageContext) => g.join(m.connection as never, await validatePayload(JoinRoom, m.data)),
+ *     }],
+ *   }],
+ * }
+ * ```
+ */
+import type { ClassRef, GenerateContext, GenInput, GenNode } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+import type { GatewayData, HandlerData, LifecycleData, WebSocketData, WsParamData } from './data.ts'
+
+import { compareStrings, RUNTIME_MODULE } from './constants.ts'
+
+type Context = GenerateContext<WebSocketData>
+
+/** Imports of the runtime helpers, created on first use (no unused import in the module). */
+interface Helpers {
+  connection(): GenNode
+  messageContext(): GenNode
+  validatePayload(): GenNode
+}
+
+/** Builds the websocket section; `undefined` (no section) without gateways. */
+export function generateWebSocket(ctx: Context): GenNode | undefined {
+  const gateways = ctx.stored
+    .filter((data): data is GatewayData => data.kind === 'gateway')
+    .sort((a, b) => compareStrings(a.token, b.token))
+  if (gateways.length === 0) return undefined
+  const helpers = lazyHelpers(ctx)
+  const entries: [string, GenInput][] = [
+    ['gateways', ctx.arr(gateways.map(gateway => gatewayNode(ctx, gateway, helpers)))],
+  ]
+  const groups = groupsNode(ctx, gateways)
+  if (groups !== undefined) entries.push(['groups', groups])
+  return ctx.obj(entries)
+}
+
+function gatewayNode(ctx: Context, gateway: GatewayData, helpers: Helpers): GenNode {
+  let classType: GenNode | undefined
+  const gatewayType = (): GenNode => {
+    classType ??= ctx.importType(gateway.identity)
+    return classType
+  }
+  const options = gateway.options
+  const entries: [string, GenInput][] = [
+    ['token', gateway.token],
+    ['path', gateway.path ?? '/'],
+    ['protocol', options.protocol],
+  ]
+  if (options.protocols !== undefined) entries.push(['protocols', ctx.lit([...options.protocols])])
+  if (options.maxPayload !== undefined) entries.push(['maxPayload', options.maxPayload])
+  if (options.concurrency !== undefined) entries.push(['concurrency', options.concurrency])
+  if (options.rateLimit !== undefined) entries.push(['rateLimit', ctx.lit({ ...options.rateLimit })])
+  if (options.backpressure !== undefined) entries.push(['backpressure', ctx.lit({ ...options.backpressure })])
+  entries.push(
+    ['meta', metaNode(ctx, gateway.meta)],
+    ['handshakeGuards', tokens(ctx, gateway.handshakeGuards)],
+    ['messageGuards', tokens(ctx, gateway.messageGuards)],
+  )
+  if (gateway.onConnect !== undefined) {
+    entries.push(['onConnect', lifecycleNode(ctx, gateway.onConnect, gatewayType, helpers)])
+  }
+  if (gateway.onDisconnect !== undefined) {
+    entries.push(['onDisconnect', lifecycleNode(ctx, gateway.onDisconnect, gatewayType, helpers)])
+  }
+  entries.push(['handlers', ctx.arr(gateway.handlers.map(handler => handlerNode(ctx, handler, gatewayType, helpers)))])
+  return ctx.obj(entries)
+}
+
+function metaNode(ctx: Context, meta: readonly MetaEntry[]): GenNode {
+  return ctx.obj(meta.map(entry => [entry.key, ctx.lit(entry.value)] as const))
+}
+
+function tokens(ctx: Context, refs: readonly ClassRef[]): GenNode {
+  return ctx.arr(refs.map(ref => ctx.tokenOf(ref) ?? ref.token))
+}
+
+/** Trailing parameters left `undefined` are not passed. */
+function trimmed(params: readonly WsParamData[]): WsParamData[] {
+  const list = [...params]
+  while (list.length > 0 && list[list.length - 1]?.kind === 'undefined') list.pop()
+  return list
+}
+
+/** `{ method, invoke: (g: Gateway, c: WsConnection) => g.method(c as never) }`. */
+function lifecycleNode(ctx: Context, lifecycle: LifecycleData, gatewayType: () => GenNode, helpers: Helpers): GenNode {
+  const params = trimmed(lifecycle.params)
+  const invoke =
+    params.length === 0
+      ? ctx.arrow([['g', gatewayType()]], g => ctx.call(ctx.member(g, lifecycle.method)))
+      : ctx.arrow(
+          [
+            ['g', gatewayType()],
+            ['c', helpers.connection()],
+          ],
+          (g, c) =>
+            ctx.call(
+              ctx.member(g, lifecycle.method),
+              params.map(param =>
+                param.kind === 'connection' ? ctx.code`${c as GenNode} as never` : ctx.lit(undefined),
+              ),
+            ),
+        )
+  return ctx.obj([
+    ['method', lifecycle.method],
+    ['invoke', invoke],
+  ])
+}
+
+function handlerNode(ctx: Context, handler: HandlerData, gatewayType: () => GenNode, helpers: Helpers): GenNode {
+  const entries: [string, GenInput][] = [['method', handler.method]]
+  if (handler.event !== undefined) entries.push(['event', handler.event])
+  entries.push(
+    ['meta', metaNode(ctx, handler.meta)],
+    ['guards', tokens(ctx, handler.guards)],
+    ['params', ctx.arr(handler.params.flatMap((param, index) => paramNode(ctx, param, index)))],
+    ['invoke', invokeNode(ctx, handler, gatewayType, helpers)],
+  )
+  return ctx.obj(entries)
+}
+
+/** The informational `params` entry of a parameter (none for a parameter left `undefined`). */
+function paramNode(ctx: Context, param: WsParamData, index: number): GenNode[] {
+  switch (param.kind) {
+    case 'payload':
+      return [
+        ctx.obj([
+          ['index', index],
+          ['source', 'payload'],
+        ]),
+      ]
+    case 'validated':
+      return [
+        ctx.obj([
+          ['index', index],
+          ['source', 'payload'],
+          ['schema', true],
+        ]),
+      ]
+    case 'connection':
+      return [
+        ctx.obj([
+          ['index', index],
+          ['source', 'connection'],
+        ]),
+      ]
+    case 'context':
+      return [
+        ctx.obj([
+          ['index', index],
+          ['source', 'context'],
+        ]),
+      ]
+    case 'undefined':
+      return []
+  }
+}
+
+/** `(g: Gateway, m: WsMessageContext) => g.method(...args)`, `async` when a payload is validated. */
+function invokeNode(ctx: Context, handler: HandlerData, gatewayType: () => GenNode, helpers: Helpers): GenNode {
+  const params = trimmed(handler.params)
+  if (params.length === 0) {
+    return ctx.arrow([['g', gatewayType()]], g => ctx.call(ctx.member(g, handler.method)))
+  }
+  return ctx.arrow(
+    [
+      ['g', gatewayType()],
+      ['m', helpers.messageContext()],
+    ],
+    (g, m) =>
+      ctx.call(
+        ctx.member(g, handler.method),
+        params.map(param => argumentNode(ctx, param, m as GenNode, helpers)),
+      ),
+    { async: params.some(param => param.kind === 'validated') },
+  )
+}
+
+function argumentNode(ctx: Context, param: WsParamData, m: GenNode, helpers: Helpers): GenNode {
+  switch (param.kind) {
+    case 'payload':
+      return ctx.code`${ctx.member(m, 'data')} as never`
+    case 'validated':
+      return ctx.code`await ${ctx.call(helpers.validatePayload(), [ctx.importValue(param.schema), ctx.member(m, 'data')])}`
+    case 'connection':
+      return ctx.code`${ctx.member(m, 'connection')} as never`
+    case 'context':
+      return m
+    case 'undefined':
+      return ctx.lit(undefined)
+  }
+}
+
+/**
+ * `groups`: the route decorator groups the runtime needs (required, holding several keys, or named
+ * differently from their key), sorted; `undefined` when there is none (as `extensions.http`).
+ */
+function groupsNode(ctx: Context, gateways: readonly GatewayData[]): GenNode | undefined {
+  const groups = new Map<string, { readonly keys: Set<string>; required: boolean }>()
+  const visit = (entries: readonly MetaEntry[]): void => {
+    for (const entry of entries) {
+      const group = groups.get(entry.group)
+      if (group === undefined) groups.set(entry.group, { keys: new Set([entry.key]), required: entry.required })
+      else {
+        group.keys.add(entry.key)
+        group.required ||= entry.required
+      }
+    }
+  }
+  for (const gateway of gateways) {
+    visit(gateway.meta)
+    for (const handler of gateway.handlers) visit(handler.meta)
+  }
+  const needed = [...groups]
+    .filter(([name, group]) => group.required || group.keys.size > 1 || !group.keys.has(name))
+    .sort(([a], [b]) => compareStrings(a, b))
+  if (needed.length === 0) return undefined
+  return ctx.obj(
+    needed.map(
+      ([name, group]) =>
+        [
+          name,
+          ctx.obj([
+            ['keys', ctx.lit([...group.keys].sort(compareStrings))],
+            ['required', group.required],
+          ]),
+        ] as const,
+    ),
+  )
+}
+
+function lazyHelpers(ctx: Context): Helpers {
+  const cache = new Map<string, GenNode>()
+  const get = (name: string, type: boolean): GenNode => {
+    let node = cache.get(name)
+    if (node === undefined) {
+      node = ctx.importFrom(RUNTIME_MODULE, name, type ? { type: true } : {})
+      cache.set(name, node)
+    }
+    return node
+  }
+  return {
+    connection: () => get('WsConnection', true),
+    messageContext: () => get('WsMessageContext', true),
+    validatePayload: () => get('validatePayload', false),
+  }
+}

package/src/compiler/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `@znight/websocket/compiler`: the compiler extension of `@znight/websocket` (RFC 0003 §6, §7).
+ *
+ * Loaded by `@znight/compiler` through the package manifest (`package.json#znight.compiler`). It
+ * reads `@Gateway` classes, their `@OnConnect` / `@OnMessage` / `@OnDisconnect` methods, `@Payload`
+ * / `@Conn` / `@Ctx` parameters, guards and route decorators, registers gateways as providers,
+ * reports invalid gateways at build time and generates `metadata.extensions.websocket`.
+ *
+ * This entry only `import type`s from `@znight/compiler`, imports `@znight/http/compiler` and
+ * `@znight/http/path` (both runtime-free) and never loads the WebSocket runtime.
+ */
+import type { CompilerExtension, DecoratorSpec } from '@znight/compiler'
+import type { WebSocketData } from './data.ts'
+
+import { analyzeWebSocketClass } from './analyze.ts'
+import { EXTENSION_NAME, WsDecorator } from './constants.ts'
+import { generateWebSocket } from './generate.ts'
+import { validateWebSocket } from './validate.ts'
+
+export type {
+  GatewayData,
+  GatewayOptionsData,
+  HandlerData,
+  LifecycleData,
+  MemberClassData,
+  WebSocketData,
+  WsParamData,
+} from './data.ts'
+
+/** Decorators owned by the extension (static / value arguments, spec §4.6). */
+const decorators: Readonly<Record<string, DecoratorSpec>> = Object.freeze({
+  [WsDecorator.Gateway]: { targets: ['class'], params: ['static'] },
+  [WsDecorator.OnConnect]: { targets: ['method'], params: [] },
+  [WsDecorator.OnDisconnect]: { targets: ['method'], params: [] },
+  [WsDecorator.OnMessage]: { targets: ['method'], params: ['static'] },
+  [WsDecorator.Payload]: { targets: ['parameter'], params: ['value'] },
+  [WsDecorator.Conn]: { targets: ['parameter'], params: [] },
+  [WsDecorator.Ctx]: { targets: ['parameter'], params: [] },
+  [WsDecorator.UseHandshakeGuard]: { targets: ['class'], params: [], rest: 'value' },
+  [WsDecorator.UseMessageGuard]: { targets: ['class', 'method'], params: [], rest: 'value' },
+} satisfies Record<string, DecoratorSpec>)
+
+/** The `@znight/websocket` compiler extension. */
+export const webSocketCompilerExtension: CompilerExtension<WebSocketData> = Object.freeze({
+  apiVersion: 1,
+  name: EXTENSION_NAME,
+  decorators,
+  analyzeClass: analyzeWebSocketClass,
+  validate: validateWebSocket,
+  generate: generateWebSocket,
+})
+
+export default webSocketCompilerExtension

package/src/compiler/validate.ts

@@ -0,0 +1,81 @@
+/**
+ * `validate` of the websocket extension (RFC 0003 §6.2): what needs every gateway. Duplicate path
+ * shapes (ZNIGHT007), decorators on a class that is neither a gateway nor one of its bases
+ * (ZNIGHT005), and the required route decorator groups of RFC 0001 on handshakes (ZNIGHT023).
+ */
+import type { ValidateContext } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+import type { GatewayData, WebSocketData } from './data.ts'
+
+import { requiredRouteGroups } from '@znight/http/compiler'
+import { parseRoutePath } from '@znight/http/path'
+
+import { compareStrings, INVALID_DECORATOR, INVALID_ROUTE, MISSING_ROUTE_DECISION } from './constants.ts'
+
+/** Validates the gateways of the application. */
+export function validateWebSocket(ctx: ValidateContext<WebSocketData>): void {
+  const gateways = ctx.stored
+    .filter((data): data is GatewayData => data.kind === 'gateway')
+    .sort((a, b) => compareStrings(a.token, b.token))
+
+  const byShape = new Map<string, GatewayData>()
+  for (const gateway of gateways) {
+    if (gateway.path === undefined) continue
+    const shape = parseRoutePath(gateway.path).shape
+    const first = byShape.get(shape)
+    if (first === undefined) {
+      byShape.set(shape, gateway)
+      continue
+    }
+    ctx.report({
+      code: INVALID_ROUTE,
+      severity: 'error',
+      message: `${first.displayName} (${first.path}) and ${gateway.displayName} (${gateway.path}) serve the same path`,
+      location: gateway.location,
+      hints: ['Two gateways cannot match the same handshake: change one of the paths'],
+      related: [{ message: `${first.displayName} serves ${first.path}`, location: first.location }],
+    })
+  }
+
+  const bases = new Set(gateways.flatMap(gateway => gateway.chain))
+  for (const data of ctx.stored) {
+    if (data.kind !== 'members' || data.abstract || bases.has(data.identity)) continue
+    for (const decorator of data.decorators) {
+      ctx.report({
+        code: INVALID_DECORATOR,
+        severity: 'error',
+        message: `@${decorator.name} has no effect: ${data.displayName} is not a @Gateway`,
+        location: decorator.location,
+        hints: [
+          `Add @Gateway('/path') to ${data.displayName}, or extend it from a @Gateway class`,
+          'Base classes holding shared handlers should be abstract',
+        ],
+      })
+    }
+  }
+
+  const applied: MetaEntry[] = []
+  for (const gateway of gateways) {
+    applied.push(...gateway.meta)
+    for (const handler of gateway.handlers) applied.push(...handler.meta)
+  }
+  const required = requiredRouteGroups(ctx, applied)
+  if (required.length === 0) return
+  for (const gateway of gateways) {
+    const decided = new Set(gateway.meta.map(entry => entry.group))
+    for (const group of required) {
+      if (decided.has(group.group)) continue
+      const definition = group.decorators[0] as { readonly definition?: GatewayData['location'] } | undefined
+      ctx.report({
+        code: MISSING_ROUTE_DECISION,
+        severity: 'error',
+        message: `Gateway ${gateway.displayName} (${gateway.path ?? '?'}) has no "${group.group}" decision`,
+        location: gateway.location,
+        hints: [`Add ${group.suggestion} to ${gateway.displayName}: the handshake is an HTTP request`],
+        ...(definition?.definition === undefined
+          ? {}
+          : { related: [{ message: `The "${group.group}" group is required`, location: definition.definition }] }),
+      })
+    }
+  }
+}