channels-binding 1.1.6

Channels Binding exposes an JSON API streaming system over django channels, in very few code lines, with a very simple and verboseless exchange structure, where each django Models would be easily binded and come with native basics operations like 'retrieve', 'search', 'update', 'create', 'delete' and subscription We could made the comparaison with django restframework with the REST system.

Channels Binding API

Channels Binding exposes an JSON API streaming system over channels, in very few code lines, with a very simple and verboseless exchange structure, where each django Models would be easily binded and come with native basics operations like ‘retrieve’, ‘search’, ‘update’, ‘create’, ‘delete’ and subscription We could made the comparaison with django restframework with the REST system.

• Gettings Started

Capabilities

• Full support of ‘retrieve’, ‘search’, ‘list’, ‘update’, ‘create’, ‘save’, ‘delete’, ‘subscribe’ events

• Support of Hashed events for targeted subscribers (example: 2 lists on the same stream/event/model but with different filtering)

• Auto channels subscribing groups of interest ‘retrieve’, ‘list’, ‘delete’

• Custom bindings events through decorators

• Compatible with Django restframework serializers (soon ready)

• Both Async or Sync Consumers (not yet)

• Both HTTP Rest or WS API (not yet)

Exchanges Structure

SELF SEND => {
    event: "auth.User.search",
    data: {
        page: 2
    }
}
SELF RECEIVE => {
    event: "auth.User.search",
    data: {
        page: 2,
        limit: 25,
        count: 102,
        rows: [{
            id: 5763,
            username: "Admin",
            email: "[e-mail]"
        }, ... ]
    }
}

SELF SEND => {
    event: "auth.User.retrieve",
    data: {
        id: 5763
    }
}
SELF RECEIVE => {
    event: "auth.User.retrieve",
    data: {
        id: 5763,
        username: "Admin",
        email: "[e-mail]",
        ...andMoreDetails
    }
}

SELF SEND => {
    event: "auth.User.update",
    data: {
        id: 5763,
        username: "Changed Username"
    }
}
SELF RECEIVE => {
    event: "auth.User.update",
    data: {
        success: true
    }
}
GROUP RECEIVE => {
    event: "auth.User.retrieve",
    data: {
        id: 5763,
        username: "Changed Username",
        email: "[e-mail]",
        ...andMoreDetails
    }
}

Getting Started

• Assume that you have already django and channels>=2.0.0 installed

• Add channels-binding to requirements.txt

pip install channels-binding

• Add channels_binding to INSTALLED_APPS

INSTALLED_APPS = (
    'channels',
    'channels_binding',
)

• Configure some optionnals SETTINGS

CHANNEL_LAYERS = {
    'default': {
        ...some channels config
    },
}
CHANNELS_BINDING = {
    "AUTHENTIFICATION_CLASSES": (
        'authentification.AuthenticationStrategyClass',
    ),
    "DEFAULT_PAGE_SIZE": 25,
    "ANONYMOUS_CONNECTION_ALLOWED": False, # Reject connection of non connected users
}

• Add a new AsyncConsumer in your asgi application routing (Read the channels docs)

# asgi.py

from django.urls import path
from channels.sessions import SessionMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels_binding.consumers import AsyncConsumer

application = ProtocolTypeRouter({
    'websocket': SessionMiddlewareStack(
        URLRouter([
            path('', AsyncConsumer, name="root"),
        ])
    )
})

• Add bindinds inside an app or root bindigns folder

# apps/your_app/bindings.py

from channels_binding.consumers import AsyncBinding
from .models import YourModel

'''
    All bindings in apps/*/bindings.py or app/bindings/*.py are auto discovered, like models.py
'''
class YourModelBinding(AsyncBinding):

    model = YourModel
    # stream = by default '{app_name.model_name}' if model is set
    # permission_class = by default None (may change in future)
    # serializer_class = by default None (soon compatible with restframwork serializer)
    # queryset = by default YourModel.objects.all()
    # page_size = by default 25 rows for the 'search' and 'list' events
    # post_save_retrieve = by default True, if is True, an instance post_save send the 'retrieve' event to all the stream subscribers

• Let’s start to communicate with a simple retrieve action on a frontal javascript thirdparty

var ws = new WebSocket("ws://" + window.location.host + "/")
ws.onmessage = function(e){
    console.log(e.data)
    /*
       Receive:
       {
            event: "your_app.YourModel.retrieve",
            data: {
                id: 5763,
                ...someData
            }
       }
    */
}
ws.send(JSON.stringify({
    event: "your_app.YourModel.retrieve",
    data: {
        id: 5763
    }
}))