Installation

Requirements

Chanx has the following dependencies:

• Python 3.10+

• Django 4.0+

• Django Channels 4.0+

• Django REST Framework 3.13+

• Pydantic 2.0+

• Structlog 23.0+

Installing Chanx

You can install Chanx from PyPI:

pip install chanx

Or install from source:

git clone https://github.com/username/chanx.git
cd chanx
pip install -e .

Configuration

1. Add Chanx to your INSTALLED_APPS in Django settings:

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'channels',
    'chanx',
    # ...
]

2. Make sure Django Channels is properly configured:

# settings.py
ASGI_APPLICATION = "myproject.asgi.application"

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": [("127.0.0.1", 6379)],
        },
    },
}

3. Configure Chanx settings (optional):

# settings.py
CHANX = {
    'SEND_COMPLETION': True,
    'SEND_AUTHENTICATION_MESSAGE': True,
    'LOG_RECEIVED_MESSAGE': True,
    'LOG_SENT_MESSAGE': True,
    'LOG_IGNORED_ACTIONS': ['ping', 'pong'],
    'WEBSOCKET_BASE_URL': 'ws://localhost:8000',
}

4. Set up your ASGI application with a WebSocket router:

# asgi.py
import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack

from myapp.routing import websocket_urlpatterns

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": AuthMiddlewareStack(
        URLRouter(websocket_urlpatterns)
    ),
})

5. Create your WebSocket URL patterns:

# myapp/routing.py
from django.urls import re_path
from myapp.consumers import MyConsumer

websocket_urlpatterns = [
    re_path(r'ws/myendpoint/$', MyConsumer.as_asgi()),
]

6. (Optional) Set up the WebSocket playground:

# myproject/urls.py
from django.urls import path, include

urlpatterns = [
    # ...
    path('chanx/', include('chanx.playground.urls')),
    # ...
]

Verifying Installation

To verify that Chanx is correctly installed and configured:

1. Start your Django development server:

python manage.py runserver

2. If you've set up the playground, navigate to:

   http://localhost:8000/chanx/playground/websocket/

   You should see the WebSocket playground interface where you can explore your WebSocket endpoints.

3. Access the WebSocket endpoint with a client like wscat:

wscat -c ws://localhost:8000/ws/myendpoint/

Troubleshooting

Can't connect to WebSocket endpoint

• Ensure your ASGI server is running

• Check your URL patterns in routing.py

• Verify your ProtocolTypeRouter setup

• Check authentication requirements

Authentication issues

• Verify your authentication classes are properly configured

• Check that your WebSocket request includes necessary headers

• Inspect the WebSocket authentication message response

Django server won't start

• Look for import errors related to Chanx dependencies

• Verify your ASGI_APPLICATION setting is correct

• Check for exceptions during application startup

Next Steps

Now that you have Chanx installed and configured, proceed to the Quick Start guide to create your first WebSocket consumer.