websocket

name	websocket
description	Use when creating, updating, reviewing, or debugging WebSocket, real-time updates, socket events, live notifications, chat, presence, rooms, subscriptions, reconnects, or real-time security.

WebSocket

Use this skill for safe and maintainable real-time communication.

Rules

• Follow the project’s existing WebSocket/realtime pattern.
• Do not add a new WebSocket library, pub/sub system, broker, or realtime provider unless already used or explicitly requested.
• Authenticate connections before allowing subscriptions or events.
• Validate every client-sent event payload.
• Check authorization before joining rooms, subscribing, or broadcasting.
• Scope rooms/channels by user, organization, tenant, workspace, or resource when needed.
• Never broadcast private data to a global or unscoped channel.
• Keep socket payloads small and safe.
• Clean up listeners, timers, presence, and resources on disconnect.
• Handle reconnects without duplicating subscriptions or side effects.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing realtime code, check existing patterns for:

• WebSocket library/provider
• connection authentication
• room/channel naming
• event naming
• payload validation
• authorization checks
• presence handling
• reconnect behavior
• heartbeat/timeout handling
• scaling/pub-sub strategy
• logging
• test style

Implementation Checklist

• Identify the realtime event or subscription.
• Reuse existing socket/server/client helpers.
• Authenticate at connection or subscription boundary.
• Validate payloads before processing.
• Verify user permission and ownership.
• Join only allowed rooms/channels.
• Broadcast only to the correct scope.
• Avoid sending sensitive raw records.
• Add disconnect cleanup.
• Add reconnect-safe behavior.
• Add or update relevant tests.

Security Rules

• Reject unauthenticated connections where auth is required.
• Do not trust userId, role, tenantId, room, or resource IDs sent by the client.
• Derive scope from verified auth/session/context.
• Prevent cross-user, cross-tenant, or cross-organization broadcasts.
• Enforce payload size limits when the project supports them.
• Do not log tokens, cookies, private messages, or sensitive payloads.
• Do not expose internal errors over socket events.

Event Rules

• Keep event names consistent with the project.
• Keep payload contracts explicit.
• Validate incoming payloads.
• Return safe errors for invalid events.
• Make side-effecting events idempotent when retries or reconnects can duplicate them.
• Avoid sending full database objects unless already sanitized.
• Prefer minimal DTOs for outbound events.

Room and Subscription Rules

• Use scoped rooms/channels for private data.
• Verify membership before join.
• Leave rooms on disconnect or when permission changes.
• Use user-specific rooms for personal notifications.
• Use resource-specific rooms for shared documents, chats, dashboards, or orders.
• Use tenant/workspace rooms only when all members are allowed to receive the event.

Lifecycle Rules

• Handle connect.
• Handle disconnect.
• Handle reconnect.
• Clean up timers, listeners, and presence state.
• Avoid memory leaks from repeated subscriptions.
• Use heartbeat/ping behavior if the project has it.
• Ensure workers/services can broadcast through the existing realtime layer safely.

Failure Handling

• Invalid auth: reject connection or subscription.
• Invalid payload: return safe validation error.
• Forbidden room: reject join.
• Disconnected client: do not fail critical server workflows.
• Duplicate reconnect: avoid duplicate listeners or repeated side effects.
• Broadcast failure: log safely using existing project pattern.

Tests

Cover relevant paths:

• authenticated connection
• unauthenticated rejection
• event validation
• forbidden subscription
• scoped broadcast
• no cross-tenant/user leak
• disconnect cleanup
• reconnect behavior
• duplicate event prevention if relevant