Python AsyncIO WebSockets Broadcaster — Cursor Rules Template

Overview

Direct answer: This is a Cursor Rules Template for a Python asyncio WebSocket broadcaster. It includes a copyable .cursorrules configuration and project guidance to enable safe, AI-assisted development with Cursor AI for real-time broadcasting.

This template covers Python 3.11+ with AsyncIO and the websockets approach, ensuring clean async boundaries, clear error handling, and container-friendly file organization. It is designed to help developers generate consistent, inspectable code with Cursor AI guidance while keeping security and testability front and center.

When to Use These Cursor Rules

• Implement a real-time message broadcaster using Python AsyncIO and websockets
• Require safe AI-assisted coding with enforced style and security constraints
• Need a repeatable project layout for scalable real-time services
• Aim for thorough testing and linting in CI while avoiding blocking code in the event loop
• Want to limit message size, validate origins, and manage authenticated connections

Copyable .cursorrules Configuration

framework: python-asyncio-websockets-broadcaster
role: System: You are Cursor AI assistant for Python asyncio WebSocket broadcaster. Provide precise, safe, and testable code guidance.
context: You must operate within Cursor AI rules for real-time Python services. Avoid blocking calls in the event loop and never expose secrets.

# Code Style and Style Guides
style: pep8
formatter: black
linter: flake8
typing: true

# Architecture & Directory Rules
directories:
  - src/broadcaster
  - src/broadcaster/handlers
  - src/broadcaster/ws
  - tests
  - config

# Authentication & Security Rules
auth:
  - method: jwt
  - upgrade: require Authorization header on WebSocket upgrade
  - origin_check: true

# Database and ORM patterns
database: none
orms: none

# Testing & Linting Workflows
testing:
  - pytest-asyncio
  - pytest
ci:
  - github-actions

# Prohibited Actions and Anti-patterns for the AI
do_not:
  - pickle for message serialization
  - eval on inbound messages
  - hardcoded secrets in code
  - blocking IO in the event loop
  - global mutable state per connection

# End of rules

Recommended Project Structure

project/
├── src/
│   └── broadcaster/
│       ├── __init__.py
│       ├── server.py
│       ├── handlers.py
│       └── ws_client.py
├── tests/
│   ├── test_server.py
│   └── test_handlers.py
├── config/
│   └── settings.py
├── requirements.txt
└── pyproject.toml

Core Engineering Principles

• Explicit async boundaries and non-blocking I/O throughout the code path
• Clear separation of concerns between connection management, message handling, and transport
• Deterministic, testable behavior with thorough unit and integration tests
• Safe AI-assisted development with strict do_not rules and auditing of generated code
• Strong observability: logging, structured metrics, and error propagation

Code Construction Rules

• Create an async WebSocket server that accepts connections, authenticates, and maintains per-connection state
• Use asyncio for concurrency and ensure message handling never blocks the event loop
• Serialize messages with a deterministic format (JSON) and validate schemas for inbound/outbound messages
• Encapsulate broadcast logic in a dedicated handler module with testable interfaces
• Include type hints and adhere to PEP 8; run black and flake8 in CI
• Do not hardcode secrets; pull credentials from env/config
• Do not use deprecated APIs; prefer modern asyncio features
• Do not rely on global mutable state for per-connection data

Security and Production Rules

• Validate JWT or token-based auth on WebSocket upgrade; reject unauthenticated peers
• Enforce TLS in deployment and never expose plain HTTP for ws endpoints
• Limit inbound message size and implement rate limiting per connection
• Check Origin header and blacklist suspicious sources
• Sanitize inbound data and avoid executing code from clients
• Close idle connections gracefully and implement proper close handshake

Testing Checklist

• Unit tests for message framing and serialization
• Integration tests for handshake, authentication, and broadcast flows using pytest-asyncio
• Performance tests focusing on message backpressure and asyncio task balance
• CI checks for linting, type checking, and test suite pass
• Security tests for token validation, origin checks, and input validation

Common Mistakes to Avoid

• Blocking operations in the event loop during message handling
• Improper authentication leading to open broadcast channels
• Unbounded growth of per-connection state without cleanup
• Disabling CSRF-like protections for WebSocket endpoints
• Ignoring test coverage for edge cases like invalid tokens or abrupt disconnects

FAQ

What is this Cursor Rules Template for Python asyncio WebSocket broadcaster?

The template provides a copyable .cursorrules block and project guidance to implement a secure, asynchronous WebSocket broadcaster in Python with Cursor AI rules for safe AI-assisted development.

Which stack does this template cover?

It covers Python 3.11+ with AsyncIO and the websockets library, focusing on a broadcaster pattern and Cursor AI rules that enforce non-blocking I/O, authentication, and testability.

How do I apply the .cursorrules file in my project?

Place the included .cursorrules configuration at the repository root. Cursor AI will use these rules to guide code generation, enforce style and security constraints, and generate test scaffolds consistent with the project structure.

What security considerations are included for WebSocket broadcasting?

Token-based authentication on upgrade, origin checks, message size limits, TLS in production, and sanitization of inbound data are enforced by the rules to minimize exposure and misuse.

How do I test the broadcaster with pytest-asyncio?

Tests should cover handshake flows, token validation, per-connection states, and broadcast behavior. The template includes testing guidance and example tests to bootstrap your suite.