[Upd4ting]

Why

@Connection() is documented as WebSocket-only, but on an HTTP handler it passed undefined without any error. Route decorators now refuse it when the class is defined, in the modes that never receive a connection.

Fixes #76

What changed

• ProcessCallback throws a TypeError and registers no route for the handler when a handler parameter receives @Connection in handler, prefix or postfix mode. websocket and monitor mode stay allowed.
• The @Connection TSDoc, docs/4.parameters.md and the api-interface skill state the rule by mode.
• The verify scenario for injected values now puts @Connection on a WebSocket handler and checks that a @Get handler is refused.

Scope

• Class properties with @Connection stay allowed, because every handler of the controller shares them. They stay undefined outside a WebSocket request.
• Handlers declared above a refused handler in the same class stay registered, as for every other TypeError from ProcessCallback.
• A child method shares the parameter records of the parent method with the same name, so a @Get override of a parent @WebsocketHandler method that uses @Connection is refused too. The shared records also cause a separate bug, filed as A child controller's parameter decorator overwrites the parent handler's parameter of the same method name #100.

Tradeoffs

• The issue also offered a docs-only fix. It leaves the silent undefined, so no test can fail on it.
• Monitors stay allowed. @antelopejs/api runs them after the upgrade with the connection set, and a probe showed a @Monitor receives the socket on a WebSocket route.
• Limiting the check to callback.length parameters was tried and rejected. Handlers with default, rest or wrapped parameters still received the connection.

Blast Radius

Code that used @Connection on an HTTP, prefix or postfix handler now fails when the class is defined, where it used to get undefined. WebSocket and monitor handlers are not affected.

Verification

• src/tests/connection.test.ts: 4 of 5 tests fail on main and all 5 pass on this branch. The outputs are below.
• antelopejs-verify: all 12 planned journeys pass on the packed build.
• pnpm run checks: Checks: 9 passed, 0 failed.

flowchart TD
  A[Route decorator] --> B[ProcessCallback]
  B --> C{A handler parameter receives @Connection?}
  C -- no --> R[RegisterRoute]
  C -- yes --> D{mode is websocket or monitor?}
  D -- yes --> R
  D -- no --> E[TypeError when the class is defined, no route]

Loading

Test output on main (82bbb2a) with this branch's test file

  @Connection handler modes
    1) refuses a @Get handler and registers nothing
    2) refuses @Prefix and @Postfix handlers, which never see a connection
    ✔ accepts a @Monitor handler, which runs after a WebSocket upgrade
    3) refuses @Connection after a default-valued parameter of a @Get handler
    4) refuses a child @Get override that inherits the parent's @Connection
  1 passing (9ms)
  4 failing
  1) @Connection handler modes
       refuses a @Get handler and registers nothing:
     AssertionError [ERR_ASSERTION]: Missing expected exception (TypeError).
      at Context.<anonymous> (dist/tests/connection.test.js:26:31)
      at process.processImmediate (node:internal/timers:574:21)
  2) @Connection handler modes
       refuses @Prefix and @Postfix handlers, which never see a connection:
     AssertionError [ERR_ASSERTION]: Missing expected exception.
      at Context.<anonymous> (dist/tests/connection.test.js:47:31)
      at process.processImmediate (node:internal/timers:574:21)
  3) @Connection handler modes
       refuses @Connection after a default-valued parameter of a @Get handler:
     AssertionError [ERR_ASSERTION]: Missing expected exception.
      at Context.<anonymous> (dist/tests/connection.test.js:98:31)
      at process.processImmediate (node:internal/timers:574:21)
  4) @Connection handler modes
       refuses a child @Get override that inherits the parent's @Connection:
     AssertionError [ERR_ASSERTION]: Missing expected exception.
      at Context.<anonymous> (dist/tests/connection.test.js:128:31)
      at process.processImmediate (node:internal/timers:574:21)

Test output on this branch

  @Connection handler modes
    ✔ refuses a @Get handler and registers nothing
    ✔ refuses @Prefix and @Postfix handlers, which never see a connection
    ✔ accepts a @Monitor handler, which runs after a WebSocket upgrade
    ✔ refuses @Connection after a default-valued parameter of a @Get handler
    ✔ refuses a child @Get override that inherits the parent's @Connection
  5 passing (32ms)