User Guide

This user guide provides detailed information about each component of Chanx and how to use them effectively in your applications.

Core Components

Chanx consists of several core components that work together to provide a comprehensive WebSocket framework:

1. WebSocket Consumers: Base consumer classes with authentication, messages, and group handling

2. Message System: Pydantic-based message validation and routing

3. Authentication: DRF-style authentication for WebSocket connections

4. Testing: Specialized tools for testing WebSocket endpoints

5. Playground: Interactive UI for exploring and testing WebSocket endpoints

Getting Started

If you're new to Chanx, we recommend working through the guides in this order:

1. Start with Authentication to understand how WebSocket connections are secured

2. Move on to Messages System to learn about structured message handling

3. Explore Consumers to see how consumers pull everything together

4. See Testing for guidance on testing your WebSocket endpoints

5. Try the WebSocket Playground for interactive exploration of your endpoints

Or jump directly to the guide that addresses your current need.

Contents

• Authentication
  • How Authentication Works
  • Configuration
  • Authentication Classes
  • Client-Side Authentication
  • Object-Level Permissions
  • Authentication Messages
  • Custom Authentication
  • Testing Authentication
  • Best Practices
  • Next Steps
• Messages System
  • Base Classes
  • Message Structure
  • Creating Custom Message Types
  • Defining Message Schema
  • Message Validation
  • Handling Messages
  • Sending Messages
  • Group Messages
  • Standard Message Types
  • Completion Messages
  • Advanced Usage
  • Best Practices
  • Next Steps
• Consumers
  • Consumer Basics
  • Minimal Consumer Example
  • Consumer Lifecycle
  • Authentication Configuration
  • Message Handling
  • Group Management
  • Sending Messages
  • Configuration Options
  • Accessing User and Context
  • Post-Authentication Hook
  • Error Handling
  • Testing Consumers
  • Routing Configuration
  • Best Practices
  • Next Steps
• Testing
  • Testing Overview
  • WebsocketTestCase
  • Authentication in Tests
  • Enhanced WebsocketCommunicator
  • Testing Message Exchange
  • Testing Group Messages
  • Testing Error Handling
  • Testing Disconnection
  • Testing Permissions
  • Testing Utilities
  • Best Practices
  • Next Steps
• WebSocket Playground
  • Features
  • Enabling the Playground
  • Using the Playground
  • Generating Example Messages
  • Security Considerations
  • Customizing the Playground
  • Advanced Usage

Best Practices

Authentication

• Always use authentication for WebSocket endpoints that access user data

• Keep permission logic consistent between REST API and WebSockets

• Use object-level permissions for endpoints that deal with specific resources

Messages

• Define clear message contracts with well-documented types

• Keep message types focused with single responsibilities

• Use strict typing to catch errors early

• Validate complex payloads with Pydantic validators

Consumers

• Keep consumers focused on specific domains

• Use type hints for better IDE support

• Document expected message formats

• Implement proper error handling

Testing

• Test both happy paths and failure scenarios

• Test reconnection and error handling

• Use the provided WebsocketTestCase for consistent testing

• Mock external dependencies when testing consumers

General

• Follow the Django principle of "explicit is better than implicit"

• Use structured logging to track WebSocket activity

• Keep consumers small and focused

• Define clear boundaries between components

Next Steps

After reviewing the user guide, check out the Examples for complete applications using Chanx.