ams-websocket-patterns
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 1
03 SKILL.md 正文
WebSocket Patterns
A frontend-focused companion to WebSocket fundamentals: the client-side patterns for reliable realtime web features — connection management, reconnection with resync, multiplexing topics, and scaling considerations from the web app's perspective.
Overview
From the web app's side, WebSockets are deceptively simple (new WebSocket(url)) and deceptively fragile (networks drop, servers restart, messages get missed). This skill covers the client patterns that make realtime features feel solid: a robust socket wrapper, reconnection with backoff and resync, topic multiplexing over one connection, and graceful degradation — plus what to ask of the backend.
When to use
- Adding live updates, chat, notifications, or presence to a web app.
- Building a reusable realtime client layer.
- Debugging missed messages after reconnects.
- Deciding message protocol and topic structure with the backend team.
Core concepts
- One connection, many topics. Multiplex: a single socket carrying subscriptions (
{ type: 'subscribe', topic: 'orders:123' }) rather than a socket per feature. Fewer handshakes, simpler lifecycle, one reconnect path. - Message envelope.
{ type, topic?, id, payload, ts }— types route to handlers, ids enable dedup/acks, timestamps help ordering and debugging. - Reconnection with backoff + jitter. Exponential backoff (1s → 2s → 4s..., capped ~30s) with random jitter prevents thundering herds after server restarts.
- Resync cursors. Track the last-seen message id per topic; on reconnect, send cursors and let the server replay what was missed — or trigger a full refresh of affected UI state.
- Connection state machine.
connecting → open → (reconnecting) → open → closed. Expose state to the UI (live indicator, "reconnecting…" banner, queued-action counts). - Heartbeat. Application-level ping every ~25s (in addition to protocol ping/pong) to detect half-open connections through proxies.
- Graceful degradation. If the socket can't connect after N tries: fall back to polling or show stale data with a clear "offline" state — never a silently dead UI.
Practical workflow
1. Build the client wrapper.
type Handler = (msg: Envelope) => void;
class RealtimeClient {
private ws?: WebSocket;
private retry = 0;
private subs = new Map<string, Handler[]>();
private cursors = new Map<string, string>();
state: 'connecting' | 'open' | 'reconnecting' | 'closed' = 'connecting';
constructor(private url: string) { this.connect(); }
connect() {
this.state = this.retry ? 'reconnecting' : 'connecting';
const ws = new WebSocket(this.url);
ws.onopen = () => {
this.retry = 0; this.state = 'open';
// re-auth + resubscribe with cursors
ws.send(JSON.stringify({ type: 'hello', subs: [...this.subs.keys()],
cursors: Object.fromEntries(this.cursors) }));
this.heartbeat();
};
ws.onmessage = (e) => this.route(JSON.parse(e.data));
ws.onclose = () => this.reconnect();
this.ws = ws;
}
private reconnect() {
this.state = 'reconnecting';
const delay = Math.min(1000 * 2 ** this.retry++, 30000) * (0.5 + Math.random());
setTimeout(() => this.connect(), delay);
}
subscribe(topic: string, fn: Handler) {
const list = this.subs.get(topic) ?? [];
list.push(fn); this.subs.set(topic, list);
this.send({ type: 'subscribe', topic });
return () => this.unsubscribe(topic, fn);
}
// route(): dispatch by topic, update cursors, dedupe by id
}
2. Wire into the app. Provide via context/hook (useSubscription('orders:123', handler)); components subscribe declaratively and clean up on unmount.
3. Show connection state. A subtle status indicator (live / reconnecting / offline); disable or queue mutating actions while offline ("will send when reconnected").
4. Coordinate with the backend. Agree on: envelope format, hello resync semantics, heartbeat interval, auth (cookie session or first-message token — not long-lived tokens in the URL), per-topic authorization.
5. Test the failure modes. Kill the server mid-session; throttle to offline in DevTools; sleep/wake the laptop. Verify: reconnects, resubscribes, resyncs, no duplicates rendered, UI state honest throughout.
Common pitfalls
- Naked
new WebSocket. No reconnection, no resync, no state — the #1 realtime bug. Always wrap. - Fixed retry delay. 10k clients retrying every 5s after a deploy = self-inflicted DDoS. Backoff + jitter.
- No resync. Reconnected clients silently miss messages. Cursors + replay, or explicit refresh.
- Duplicate rendering. Replayed messages rendered twice. Dedupe by message id client-side.
- Socket per component. N components × N sockets = N handshakes, N reconnect paths. One multiplexed connection.
- Leaking subscriptions. Components unmounting without unsubscribing = handlers firing on dead components. Return cleanup functions; enforce in review.
- State lies. UI showing "live" while the socket has been dead for minutes. Drive indicators from the real connection state machine.
- Auth token in URL.
wss://...?token=secretleaks into logs/proxies. Cookie sessions or post-connect auth frames. - No offline queue. User actions during disconnect vanish. Queue mutations locally, flush on reconnect, show pending state.
- Ignoring the fallback. Some networks block websockets entirely. Have a polling/SSE fallback path for critical features, or at minimum a clear degraded state.
04 同仓库更多 Skills
web-scrape
Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.
design-taste-frontend
tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).