asyncapi-ws-plugin

Live WebSocket execution plugin for @asyncapi/react-component (asyncapi-react#1299).

Rendered into the component's operation slot, it turns a WebSocket spec into something you can exercise: connect to the server the spec names, send a message built from its schema, and watch frames arrive, labelled and checked against the spec. Design notes live in PROJECT.MD.

Install

npm install asyncapi-ws-plugin

@asyncapi/react-component (>= 3.2.0) and react (>= 18) are peer dependencies.

Usage

import AsyncApi from '@asyncapi/react-component';
import { createWsPlugin } from 'asyncapi-ws-plugin';

// Create it once, outside render, so panels keep their connections across re-renders.
const plugins = [createWsPlugin()];

<AsyncApi schema={spec} plugins={plugins} />;

The plugin closes its connections when it is unregistered and when <AsyncApi> unmounts, through the library's uninstall hook.

What each panel does

• Connection bar: the URL resolved from the spec's server, channel address and ws binding query defaults, with connect/disconnect and a status indicator. Editable unless you turn that off.
• Auth: reads the server's security. API keys that go in the query string get a field; cookie and client-certificate schemes are explained; schemes needing a request header say why a browser can't send them. Credentials stay in memory and never reach the URL field, the log or plugin events.
• Composer (operations the client sends): seeded from the message's examples or its schema, validated as you type, never blocking a deliberately invalid send.
• Log: every frame, labelled with the spec message it matches, ✓/✗ against its schema, and replies linked to their requests by correlationId. Frames matching nothing are marked unmatched rather than hidden, which is what surfaces spec drift.

Plugin options

createWsPlugin({
  allowedHosts: ['ws.kraken.com', '*.example.com', 'localhost:8787'],
  allowUrlEditing: false,
});

| Option | Default | Purpose | |---|---|---| | allowedHosts | any host | Hosts panels may connect to: api.example.com (any port), localhost:8787 (that port), *.example.com (subdomains, not the apex), or a RegExp tested against the host. Checked on every connect, including edited URLs. | | allowUrlEditing | true | When false, the URL field is read-only and panels only connect to URLs resolved from the spec. | | auth.credentials | none | ({ serverId, scheme, signal }) => string \| undefined (may be async). Supplies credentials so signed-in users don't paste tokens. Called once per server and scheme, and never overrides a typed value. signal is aborted when the plugin is torn down: pass it to fetch() to stop in-flight requests, and anything resolving after it aborts is discarded. | | auth.subprotocol | none | ({ serverId, url, schemes, credential }) => string[] \| undefined. Carries a token in Sec-WebSocket-Protocol for servers that accept it, which also makes bearer and header-key schemes enterable. Opt-in: if the server selects none of the offered subprotocols, the browser closes the connection. | | connectTimeoutMs | 10000 | How long to wait for the handshake. | | maxFrames | 500 | Frames kept per connection. | | maxFrameLength | 1000000 | Characters of a single frame kept in the log. Longer frames are truncated in the log and not parsed, so they aren't matched to messages or requests. They are still sent and received in full. | | maxLogLength | 10000000 | Total characters kept per connection. The oldest frames are dropped beyond it. |

Deploying

• CSP connect-src. WebSocket connections are governed by connect-src. List every host panels should reach, e.g. connect-src 'self' wss://ws.kraken.com. A blocked connection only shows up as "Could not connect (code 1006)".
• CSP unsafe-eval. @asyncapi/parser, used by @asyncapi/react-component, compiles schemas with Ajv, which generates code at runtime. With code generation disabled, importing the parser throws in Node, so expect pages rendering <AsyncApi> to need 'unsafe-eval' regardless of this plugin. This plugin's own payload validation uses @cfworker/json-schema, which does not.
• Your own spec: set allowedHosts to the hosts it lists, and consider allowUrlEditing: false.
• Point specs at sandbox servers. Docs visitors become real clients of the API, subject to its rate limits, from their own IP addresses.
• Auth. Browsers can't send headers on a WebSocket handshake, so header-based auth isn't usable from a docs page. Tokens in query strings end up in server and proxy logs.

Development

Requires Node 22.12+ (Vitest 5).

npm install
npm test

@asyncapi/react-component is both a peer dependency and a devDependency, so tests and the build resolve it from node_modules like any consumer would. To try changes to the library itself, point the devDependency at a local checkout (npm install ../asyncapi-react/library) or use npm link.

| Script | Purpose | |---|---| | npm test | Vitest, once | | npm run test:watch | Vitest, watch mode | | npm run typecheck | tsc --noEmit, including the aliased library sources | | npm run build | Emits dist/ (ESM + declarations) |

Layout

src/
  index.ts          createWsPlugin() — the AsyncApiPlugin
  engine/           framework-free logic (connections, routing, correlation, validation, auth)
  ui/               slot components