I got a TCL TV with Fire TV on Amazon Prime Day last year(2025). It’s a decent deal for the price, but the CPU is noticeably underpowered for the operating system. Most of time it’s functional enough that I appreciate it’s existence. Sometimes though, I want to throw a brick at it. The most infuriating case is when I browse Netflix, land on an interesting show, and press “OK” to see more details. Nothing happens. So I press it again. Then, after some silence and janky animations, the show starts playing, and then I’d struggle to go back, and then Netflix would mark that show as something I started watching. A show I never intended to watch becomes a forever mark in my identity, according to Netflix.
And when I think about this, the root cause is actually a classic replication failure. There are two nodes in the system, me and the machine. And our state were out of sync. You may disagree with this, and argue that it’s ridiculous to model human beings as nodes in a system. However, the way I think about it, is that whenever the rate of action in a system is faster than how fast a node, who acts based on local state, can keep up, the problems and challenges of a distributed systems emerges. This applies to computer to computer systems, computer to human systems, and even human to human systems(teams, organizations, etc.) too.
By this definition, web apps are always distributed systems, because, well, there’s always lag between the client and server, other users might mutate state, background processes on the server can mutate state, time is always passing, etc.
Here I’m assuming there’s no lag between human and the client, user’s actions are timely, relative to user’s rate of action, reflected on their screen.
In a distributed system, you can never safely assume that one node(the client)’s world state matches the other(server)’s. And yet, the vast majority of APIs are designed as if this isn’t true. They accept an action, which is generated by the client based on client’s state, execute it against current server state, and return a result or an error, leaving the client’s assumptions unvalidated. You would not do this in a distributed backend system.
This is the gap I want to talk about: the client’s observed world state is an implicit input to every API call, but most APIs never ask enough of it.
Consider a checkout API:
POST /checkout
{
"cart_id": "12345"
}
This tells the server what to do, but nothing about what the client believes to be true when asking. If the user had the cart open in two tabs and added an item in the other one, this request will silently checkout with items the user may not have intended to buy. If the price of an item changed after the user added it to their cart, they might be charged more than they expected.
A state-aware version changes the contract:
POST /checkout
{
"cart_id": "12345",
# assume the cart version updates whenever the cart item changes or price updates
"cart_version": "xxxx"
}
Now the server can validate: “is this the cart state the client was looking at?” If not, it rejects the request with a meaningful error instead of executing against a world the client didn’t see.
There are subtler examples too. Consider this API that’s called as the last step of enabling a paid feature during onboarding:
POST /enable_feature
{
"feature_name": "new_cool_feature"
}
On the backend, whether this generates an invoice depends on the user’s current plan. If the client doesn’t declare what it thinks will happen, you can end up charging a user who believed it was free, or skipping a charge for someone who agreed to pay. In cases where the user is acknowledging a pricing contract, it leads to financial or legal damage, because the client and the server may have different understandings of what the user agreed to to.
A better design would look like this:
POST /enable_feature
{
"feature_name": "new_cool_feature",
"acknowledged_tos": "paid_plan_tos_v3",
"acknowledged_pricing": "paid_plan_pricing_v3"
}
The server now validates that the client’s understanding of the situation matches reality before doing anything irreversible.
None of this is entirely new, the industry has developed several patterns that are, at their core, ways of encoding client world state into requests. They just haven’t been unified under this framing.
Idempotency keys are a client’s way of saying “this is what I am naming my world in which this operation is to be performed.” The server can use this to detect and reject duplicate requests from a stale view. (Although in practice, this can be implemented in a way before a request reaching the business logic or even before the app layer, but it still fits in the frame of one node claiming a world state to another node.)
Base version checks in version control work the same way. When you push a commit, you’re declaring what branch state you were working from. If someone else pushed in the meantime, your assumed base no longer matches reality, and the push is rejected - saving you from silently overwriting their work. This also allows the server to return useful error messages like “push rejected because your branch is out of date, you can force push or pull and merge first”.
Authentication headers are also a form of world state declaration: “I am this identity, and I expect you to treat this request through that lens.” The server validates the claim before proceeding.
Each of these is solving the same underlying problem in a narrow domain. What I’m arguing is that expressing client world state should be a first-class concept in API design, applied broadly and deliberately rather than as a case-by-case patch.
Treating world state as an explicit input has a few practical consequences for API design.
When the declared state doesn’t match server state, the API can return a specific, actionable error instead of silently succeeding against a world the client didn’t see, or throwing a non-actionable, generic error message. This is the difference between “checkout failed because your cart was updated” and a mysterious wrong order or a geneic “failed, please try again”.
It also forces a useful discipline on the API designer. Before finalizing any endpoint, ask:
At the end of the day, every web app is a distributed system. We spend lots of time designing for distributed state on the backend, but we often forget that the client, and the human is part of that system too.
]]>PS: if you’ve ever worked on any web app, you should confidently state on your resume that you have experience working with distributed systems. Because you do.
One way I like to think about Django deployment, or any kind of Web based service deployment, is by looking at who speaks what. In the context of Django, we know that Django itself speaks WSGI (or ASGI, for simplicity, I’ll use WSGI as the example) and the user’s browser speaks HTTP. So, apparently, there’s some translation needed. We need something that translates WSGI to HTTP. In many Django applications, the users would also like to access static files, such as images, style sheets, JavaScript files and files that are uploaded by users, these files usually lives in a file system, and they speak file system language, not WSGI, not HTTP, so there are translations to be done here too.
With this in mind, we can treat the server software as translators that can translates a language to another.
Because our Web services are eventually consumed by web browsers or other HTTP clients, the end goal of a successful deployment is to translate everything into HTTP and providing a single HTTP “access point” who knows how to pass things to other translators based on the requested path. As discussed above, there are really only two things needed to be translated: WSGI and files.
Things that translate WSGI to HTTP are called WSGI servers. They receive HTTP requests and translate them into WSGI environment variables and then calls your WSGI entry point with the WSGI environment variables, for Django, the WSGI entry point can be retrieved by calling django.core.wsgi.get_wsgi_application or is readily available in your projects’ wsgi.py file as application. There are plenty of WSGI servers to choose from, some common choices includes gunicorn and uWsgi. Django’s runserver command also starts a WSGI server. One thing to note though, is that uwsgi the protocol used by uWSGI is its own language, it is not HTTP and not WSGI, but uwsgi can be understood by nginx, a popular HTTP server, and you can configure uWSGI to speak HTTP directly. To simplify things, we can treat uWSGI and nginx together as a translator that translates WSGI to HTTP.
Now that WSGI to HTTP is handled, we have two path ahead of us for handling files on a file system.
The first one is to translate files to WSGI and because we already know how to translate WSGI to HTTP, the path from file to HTTP is also established.
The other one is to translate file directly to HTTP, this one is more efficient as you only need one translator instead of two. The problem is that (almost) all the WSGI servers can’t do this natively, meaning you can’t ask them to only translate paths that doesn’t starts with /static. To do this, you need a more generic HTTP server or proxy, such as nginx or caddy, you can ask them to serve files directly when the path starts with /static, otherwise, pass the HTTP request to your WSGI server. Note that it would be impossible to do this when we don’t have access to the HTTP server configuration, for example, when using Heroku.
Django’s built-in development server goes the first path, it turns all HTTP requests to WSGI and inside WSGI application if it sees the requested URL matches that of a static file, it then reads the file and returns its content. There are other libraries that does this better than Django’s built-in server, such as whitenoise. This approach is not completely unusable, especially when you have a CDN server that caches all static resources, so future requests only hits the CDN server not your Django applications.
When doing a production deployment, it’s not enough to just Django running. We need users to visit our website though a domain name, so a DNS record that points to our server will be required and port 80 will need to be open on the server. For security, we would like to provide HTTPS accessibility too. To do this, we can use nginx with some plugin to automatically request SSL certificates from Let's Encrypt. Cloudflare is a popular CDN/DNS service provider that have built-in support for HTTPS and caching.
It is also desired to have some kind of process manager to run our WSGI servers instead of running it on the foreground in the shell. Process managers allows us to monitor the status of servers, auto start servers when machine reboots, scale servers to have more processes and other benefits. supervisor is a popular option in Django community as a simple process manager.
As mentioned above, uWSGI can be configured to speak HTTP directly. Turns out, it can also be configured to serve static files. So you really can do a Django deployment with only uWSGI. Here’s an example configuration:
[uwsgi]
http = 0.0.0.0:80
static-map = /static=/myproj/static
static-map = /media=/myproj/media
chdir = /myproj
module = myproj.wsgi
home = /myproj/venv # this is the virtualenv path
master = true
processes = 10
vacuum = true
Hashids is a library that maps an integer to a string with provided salt, alphabet, and min_length. For example, it can turn integer 1 into "r87f" and convert it back when required.
It is a way to obfuscate ids and is particularly useful when you don’t want anyone to iterate through everything in your database by going through all the ids.
I have used Hashids a few times with Django. And every time I need to expose the id field, I would convert the id value to a hashids by calling something like this:
from utils import hashids
def to_json(obj):
exposed_id = hashids.encode(obj.id)
...
return {
'id': exposed_id,
...
}
And everywhere that exposed_id is used I need to convert it back, which ended up as a lot of code in different places.
Another issue with this approach is that it’s hard to use different configurations, such as salt and alphabet, for different models. The exposed_id for different models with the same actual id will be the same.
There are some existing projects that integrate the two, but they are more intrusive than I would like them to be. As they usually actually writes to the database, instead of just encode/decode between obfuscated id and integer ids on the fly.
This leads to this small library I made with less than 100 lines of code, called django-hashids.
django-hashids integrates Django with Hashids by introducing a “virtual” field to Django models. It is “virtual” because it does not have a column in the database but allows people to query it as if there were an actual database column.
Here’s a simple example:
class TestModel(Model):
hashid = HashidsField(real_field_name="id")
instance = TestModel.objects.create()
instance2 = TestModel.objects.create()
instance.id # 1
instance2.id # 2
# Allows access to the field
instance.hashid # '1Z'
instance2.hashid # '4x'
# Allows querying by the field
TestModel.objects.get(hashid="1Z")
TestModel.objects.filter(hashid="1Z")
TestModel.objects.filter(hashid__in=["1Z", "4x"])
TestModel.objects.filter(hashid__gt="1Z") # same as id__gt=1, would return instance 2
# Allows usage in queryset.values
TestModel.objects.values_list("hashid", flat=True) # ["1Z", "4x"]
TestModel.objects.filter(hashid__in=TestModel.objects.values("hashid"))
As you can see, it allows you to use TestModel.hashid like a real field with all the sensible lookups but queries are proxies to id field with encoding/decoding happening on the fly providing a seamless experience.
]]>For more usage and configuration options please visit django-hashids on github
This is a follow up to my last blog post: ASGI from scratch - Let’s build an ASGI web framework where I walked through the steps to build a simple but somewhat functional ASGI application framework. In that post, only HTTP is implemented and in this post, I’m going to go through the steps to add WebSocket support to the framework.
There are many ways to add WebSocket support to an ASGI framework. And I think ASGI’s WebSocket specification is already a good enough abstraction around WebSocket protocol. How it’s going to be implemented is very dependent on what kind of interface I want to provide to the framework’s users.
Assume I want to provide an interface as shown below, where the user can accept the connection and then read data from the client in an async generator.
# example-ws.py
from aaf import aaf
from aaf.routing import Router
router = Router()
@router.route('/ws_echo')
async def ws_echo(connection):
await connection.accept()
async for message in connection.iter_messages():
if (message == "QUIT"):
await connection.finish(close_code=1000)
break
await connection.send(message)
print("disconnected")
app = aaf([router])
Implementation of
Rouotuerclass andafffunction was covered in previous post
Here’s a simple diagram of the lifespan of a WebSocket connection in the context of ASGI.
sequenceDiagram
Note over Client,Server: WebSocket
Note over Server,Application: ASGI
Client->>Server: Handshake
Server->>Application: "websocket.connect"
alt Should accept connection?
Application->>Server: "websocket.accept"
Server->>Client: Http 101
else
Application->>Server: "websocket.close"
Server->>Client: Http 403
end
rect aliceblue
loop heartbeat
Client-->Server: ping
Client-->Server: pong
end
Client-->>Server: data frames
Server-->>Application: "websocket.receive"
Application-->>Server: "websocket.send"
Server-->>Client: data frames
end
alt Client/Server discnnect
Client->Server: Closed/lost connection
else application close connection
Application->>Server: "websocket.close"
Server->Client: Discnnect
end
Server->>Application: "websocket.disconnect"
It shows when each type of ASGI messages are sent and received. Every WebSocket connection starts with a websocket.connect message. When this message is received, the application can send a websocket.accept to accept a connection or a websocket.close message to reject it. After this handshake, data frames can be exchanged using websocket.send and websocket.receive messages. Both the application and client can initiate a disconnection, the application can do this by sending a websocket.close message. The server will send a websocket.disconnect message to the application whenever the connection between client and server is closed or lost.
To accept a connection, we can simply send a ASGI message with type websocket.accept along with subprotocol and headers:
class Connection:
...
async def accept(self, subprotocol=None):
headers = [
[k.encode("ascii"), v.encode("ascii")] for k, v in self.resp_headers.items()
]
await self.asgi_send(
{"type": "websocket.accept", "subprotocol": subprotocol, "headers": headers}
)
...
While this method works as a way to accept the connection, it cannot be called immediately after we get the connection like how I want it to in the goal section, because we are not making sure it is called after thewebsocket.connection message is received.
To make sure we are ready to accept the connection, we need to know the status of the connection. One simple way to do it is by having a ws_status property on Connection, like this:
class WSStatus(Enum):
init = "init" # got the scope, but haven't received any messages. The initial status
connecting = "connecting" # got the "websocket.connect" message
accepted = "accepted" # connection is accepted
closing = "closing" # application initiated a close of connection.
finished = "finished" # connection is closed
class Connection:
...
ws_status = WSStatus.init
Then, in order to set ws_status based on received ASGI messages, we can wrap self.asgi_receive in another method:
class Connection:
...
async def _ws_receive(self):
if self.ws_status == WSStatus.connecting:
raise RuntimeError(
"Unable to receive. Expect to accept or reject connection."
)
message = await self.asgi_receive()
if self.ws_status == WSStatus.init:
assert message["type"] == "websocket.connect"
self.ws_status = WSStatus.connecting
if message["type"] == "websocket.disconnect":
self.ws_status = WSStatus.finished
self.ws_close_code = message["code"]
self.finished = True
return message
Finally, back in the accept method, we can use a simple if statement to make sure a connection is ready to be accepted before accepting it:
async def accept(self, subprotocol=None):
if self.ws_status == WSStatus.init:
message = await self._ws_receive()
assert message["type"] == "websocket.connect"
...
To reject the connection, we can simply modify the finish method we have from previous post, just replace riase NotImplementedError() with these lines:
await self.asgi_send({"type": "websocket.close", "code": close_code})
self.ws_status = WSStatus.closing
self.ws_close_code = close_code
self.finished = True
Note that rejecting a connection and closing a connection from the application is the same thing. The difference is if the
"websocket.close"message is sent before or after a connection is accepted.
As described in goal section, I want to get received messages in an async generator. To do that, we can use a while loop to repeatedly receive ASGI messages, and yield the content of these messages when they are of type "websocket.receive" or stop the generator when "websocket.disconnect" is received.
async def iter_messages(self):
if self.ws_status != WSStatus.accepted:
return
while True:
message = await self._ws_receive()
if message["type"] == "websocket.disconnect":
break
if "bytes" in message and message["bytes"] is not None:
data = message["bytes"]
else:
data = message["text"]
yield data
The Connection.send method can just be a thin wrapper around self.asgi_send, that sends messages of type "websocket.send", and include either text or bytes depending on the type of messages.
async def send(self, data: Union[bytes, str] = b"", finish: Optional[bool] = False):
if self.finished:
raise ValueError("No message can be sent when connection closed")
if isinstance(data, str):
await self.asgi_send({"type": "websocket.send", "text": data})
else:
await self.asgi_send({"type": "websocket.send", "bytes": data})
Now with the ability to accept/reject connections and send/receive messages, the WebSocket implementation is finished. The implementation is quite simple. Because WebSocket itself is simple, it is just a way for server and client to exchange information, what information should be exchanged and what meaning should it carry is up to the application to decide. And ASGI is already a fairly good abstraction.
To test WebSocket support, we start the server in example-ws.py, open browser and run the following javascript code in console:
ws = new WebSocket('ws://localhost:8000/ws_echo');
ws.addEventListener("message",(msg) => console.log(msg.data));
ws.addEventListener("open", () => {
ws.send("hi");
});
You should be able to see “hi” printed back to the browser.
As a afterthought, I think it make sense for WebSocket connections to have its own class. Apart from making code easier to read, we can remove a lot of the if self.type === ConnectionType.HTTP statements, because when a connection is being created, we already know the connection type, and a connection would never change its type during throughout it’s whole life. To put it all together, here’s the code for the WebSocketConnection class:
class WebSocketConnection(Connection):
def __init__(self, scope, *, send, receive):
super().__init__(scope, send=send, receive=receive)
self.ws_status = WSStatus.init
self.ws_close_code = None
self.started = True
async def _ws_receive(self):
message = await self.asgi_receive()
if self.ws_status == WSStatus.connecting:
raise RuntimeError(
"Unable to receive. Expect to accept or reject connection."
)
if self.ws_status == WSStatus.init:
assert message["type"] == "websocket.connect"
self.ws_status = WSStatus.connecting
if message["type"] == "websocket.disconnect":
self.ws_status = WSStatus.finished
self.ws_close_code = message["code"]
self.finished = True
return message
async def accept(self, subprotocol=None):
if self.ws_status == WSStatus.init:
message = await self._ws_receive()
assert message["type"] == "websocket.connect"
headers = [
[k.encode("ascii"), v.encode("ascii")] for k, v in self.resp_headers.items()
]
await self.asgi_send(
{"type": "websocket.accept", "subprotocol": subprotocol, "headers": headers}
)
self.ws_status = WSStatus.accepted
async def send(self, data: Union[bytes, str] = b"", finish: Optional[bool] = False):
if self.finished:
raise ValueError("No message can be sent when connection closed")
if isinstance(data, str):
await self.asgi_send({"type": "websocket.send", "text": data})
else:
await self.asgi_send({"type": "websocket.send", "bytes": data})
async def finish(self, close_code: Optional[int] = 1000):
if self.finished:
raise ValueError("Connection already finished")
await self.asgi_send({"type": "websocket.close", "code": close_code})
self.ws_status = WSStatus.closing
self.ws_close_code = close_code
self.finished = True
async def iter_messages(self):
if self.ws_status != WSStatus.accepted:
return
while True:
message = await self._ws_receive()
if message["type"] == "websocket.disconnect":
break
if "bytes" in message and message["bytes"] is not None:
data = message["bytes"]
else:
data = message["text"]
yield data
Now to instantiate connection with the correct class in __init__.py:
...
conn_class = Connection
if (scope["type"] == "websocket"):
conn_class = WebSocketConnection
conn = conn_class(scope, send=send, receive=receive)
...
The first time I used ASGI(Asynchronous Server Gateway Interface) was through Channels 1.0 when ASGI spec was still a draft. It was my first interview project which helped me get my current job at Fellow. It felt magical at that time how easy it is to add WebSocket functionality to my Django app and handles authentication and other Django related things for me seamlessly.
ASGI specification is now at version 3 at the time of writing and both ASGI and Channels became part of Django Software Foundation. Compared to the draft version, it has matured a lot with added lifecycle calls and better application format, etc. Most excitingly, a healthy and fast-growing community is forming and we are seeing more and more ASGI servers running in production environments. At my company, we are serving a few million requests per day through ASGI running on Daphne, Netflix’s Dispatch is based on FastAPI, a popular ASGI web application framework, and apparently, Microsoft is using it too.
I would humbly advise anyone building web services in Python to learn about ASGI. And the best way to learn something is to built things with it, so in this blog post, I’ll walk through the steps to build a micro web application framework that speaks ASGI. I hope it can help explain how ASGI works.
Before writing the first line of code, we need to have a basic understanding of what ASGI is and what we are building towards.
Here’s a simple diagram showing how ASGI works at a high level.
graph TD
A[Client] -->|HTTP, WebSocket, ...| B(ASGI Server)
B --> |scope, send, receive| C(ASGI application)
To put it in simple words, A browser(client), establishes a connection to ASGI server with a certain type of request (HTTP or WebSocket), the ASGI server then calls ASGI application with information about the connection, encapsulated in a python dictionary called scope, and two callbacks, named send and receive, that the application can use to send and receive messages between server and client.
Here’s an example HTTP request scope
{
"type": "http",
"http_version": "1.1",
"server": ("127.0.0.1", 8000),
"client": ("127.0.0.1", 60457),
"scheme": "http",
"method": "GET",
"root_path": "",
"path": "/hello/a",
"raw_path": b"/hello/a",
"query_string": b"",
"headers": [
(b"host", b"localhost:8000"),
(b"connection", b"keep-alive"),
(
b"user-agent",
b"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36",
),
(
b"accept",
b"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
),
(b"accept-encoding", b"gzip, deflate, br"),
(b"accept-language", b"en-US,en;q=0.9"),
(
b"cookie",
b'csrftoken=dDA2IAPrvgPc7hkyBSyctxDk78KmhHAzUqR0LUpjXI3Xgki0QrGEWazE3RGZuLGl',
),
],
}
You might notice that scope is not too different from a WSGI environ. In fact, ASGI interface is very similar to WSGI interface, but instead of getting a environ and start_response to send headers and using the return value of WSGI application as the response body, ASGI interfaces with the connection and allows us to receive and send messages multiple times during the lifecycle of the connection asynchronously until the connection is closed. This allows a nice interface for both WebSocket and HTTP.
It’s also totally possible to wrap a WSGI application inside an ASGI application, just prepare a WSGI environ and start_response based on scope, receive, and send then call the WSGI application and it would work. If you delegate that call into a thread pool or something similar, you just made your WSGI application asynchronous. This is roughly how Channels wraps around Django.
When I say ASGI framework I refer it as a framework that makes building ASGI application easier and this does not include the ASGI server part. I’m mentioning this because some of the earlier Python asynchronous web frameworks have their own server implementation that also takes over tasks such as parsing HTTP requests, handles network connections, etc. We are not doing those in ASGI web framework. As a spiritual successor to WSGI, where web servers, such as Gunicorn and uwsgi, and web frameworks, such as Flask and Django, are separated, ASGI has this separation too.
So, what does an ASGI application look like?
A simple ASGI hello world application can be written as:
async def application(scope, receive, send):
name = scope["path"].split("/", 1)[-1] or "world"
await send(
{
"type": "http.response.start",
"status": 200,
"headers": [[b"content-type", b"text/plain"],],
}
)
await send(
{
"type": "http.response.body",
"body": f"Hello, {name}!".encode(),
"more_body": False,
}
)
http.response.start starts an HTTP response sending status code and response headers. In this example, it responds with the 200 OK status code and has content-type set to text/plain in the headers. http.response.body sends the response body, the more_body key tells the server if the response is finished. ASGI server might use this to know if a connection should be closed or automatically decide between a content-length header or a chunked encoding.
We can run the application with uvicorn:
uvicorn asgi-hello:application
And you should be able to visit http://localhost:8000/ and get Hello, world.Visiting http://localhost:8000/tom would get you Hello, tom.
By the way, uvicorn is pretty fast, a simple benchmark with
wrk -d10s http://localhost:8000/hion a 2018 lowest spec MacBook Air yieldsRequests/sec: 27857.87.
Although this approach works with a simple hello world example, it’s not exactly convenient to write a more complex application this way. For one, it doesn’t do routing, if you want to respond differently for different paths, you’ll probably end up with a huge if ... else if ... else clause. Secondly, having to write the ASGI message every time in the form of a python dict is quite arduous. Third, in a complex application, it gets harder to track the status of the connection, such as is the response started, is the response ended, should I start the response here, etc.
With the new framework, I hope to be able to write an ASGI application like this:
import asyncio
from aaf import aaf # Another ASGI framework
from aaf.routing import Router
from aaf.response import HttpResponse
router = Router()
@router.route('/')
@router.route('/<name>')
async def hello(connection, name='world'):
return HttpResponse(f"Hello, {name}")
@router.route('/count')
@router.route('/count/<int:number>')
async def count(connection, number=10):
for i in range(number):
await connection.send(f'count {i}\n', finish=False)
await asyncio.sleep(1)
await connection.send('', finish=True)
@router.route('/echo')
async def echo(connection):
body = await connection.body()
await connection.send(body, finish=True)
app = aaf([router])
I hope this snippet of how I want the framework to look like is self-explanatory. But here are some of the key things I want to achieve:
The Connection class will represent an ASGI HTTP or WebSocket connection. It’s a class that encapsulates the three basic elements in ASGI, namely scope, send and receive, and expose some convenient methods and properties so that users don’t need to verbosely write out all the ASGI messages and parse everything, such as cookies and headers, from scope. But it should allow users to access the original scope, send and receive when they want to, so that the composability of ASGI applications is maintained. For example, it should allow user to delegate certain connections to another ASGI application by calling another_asgi_app(connection.scope, connectionn.asgi_send, connection.asgi_receive).
Here’s a simple implementation of the Connection class.
from enum import Enum
from functools import cached_property
from http.cookies import SimpleCookie
from typing import Any, Awaitable, Callable, Optional, Union
from urllib.parse import parse_qsl, unquote_plus
from werkzeug.datastructures import Headers, MultiDict
CoroutineFunction = Callable[[Any], Awaitable]
class ConnectionType(Enum):
HTTP = "HTTP"
WebSocket = "WebSocket"
class Connection:
def __init__(
self, scope: dict, *, send: CoroutineFunction, receive: CoroutineFunction
):
self.scope = scope
self.asgi_send = send
self.asgi_receive = receive
self.started = False
self.finished = False
self.resp_headers = Headers()
self.resp_cookies: SimpleCookie = SimpleCookie()
self.resp_status_code: Optional[int] = None
self.http_body = b""
self.http_has_more_body = True
self.http_received_body_length = 0
@cached_property
def req_headers(self) -> Headers:
headers = Headers()
for (k, v) in self.scope["headers"]:
headers.add(k.decode("ascii"), v.decode("ascii"))
return headers
@cached_property
def req_cookies(self) -> SimpleCookie:
cookie = SimpleCookie()
cookie.load(self.req_headers.get("cookie", {}))
return cookie
@cached_property
def type(self) -> ConnectionType:
return (
ConnectionType.WebSocket
if self.scope.get("type") == "websocket"
else ConnectionType.HTTP
)
@cached_property
def method(self) -> str:
return self.scope["method"]
@cached_property
def path(self) -> str:
return self.scope["path"]
@cached_property
def query(self) -> MultiDict:
return MultiDict(parse_qsl(unquote_plus(self.scope["query_string"].decode())))
async def send(self, data: Union[bytes, str] = b"", finish: Optional[bool] = False):
if self.finished:
raise ValueError("No message can be sent when connection closed")
if self.type == ConnectionType.HTTP:
if isinstance(data, str):
data = data.encode()
await self._http_send(data, finish=finish)
else:
raise NotImplementedError()
async def _http_send(self, data: bytes = b"", *, finish: bool = False):
if not self.started:
if finish:
self.put_resp_header("content-length", str(len(data)))
await self.start_resp()
await self.asgi_send(
{"type": "http.response.body", "body": data or b"", "more_body": True}
)
if finish:
await self.finish()
async def finish(self, close_code: Optional[int] = 1000):
if self.type == ConnectionType.HTTP:
if self.finished:
raise ValueError("Connection already finished")
if not self.started:
self.resp_status_code = 204
await self.start_resp()
await self.asgi_send(
{"type": "http.response.body", "body": b"", "more_body": False}
)
else:
raise NotImplementedError()
# await self.asgi_send({"type": "websocket.close", "code": close_code})
self.finished = True
async def start_resp(self):
if self.started:
raise ValueError("resp already started")
if not self.resp_status_code:
self.resp_status_code = 200
headers = [
[k.encode("ascii"), v.encode("ascii")] for k, v in self.resp_headers.items()
]
for value in self.resp_cookies.values():
headers.append([b"Set-Cookie", value.OutputString().encode("ascii")])
await self.asgi_send(
{
"type": "http.response.start",
"status": self.resp_status_code,
"headers": headers,
}
)
self.started = True
async def body_iter(self):
if self.type != ConnectionType.HTTP:
raise ValueError("connection type is not HTTP")
if self.http_received_body_length > 0 and self.http_has_more_body:
raise ValueError("body iter is already started and is not finished")
if self.http_received_body_length > 0 and not self.http_has_more_body:
yield self.http_body
req_body_length = (
int(self.req_headers.get("content-length", "0"))
if not self.req_headers.get("transfer-encoding") == "chunked"
else None
)
while self.http_has_more_body:
if req_body_length and self.http_received_body_length > req_body_length:
raise ValueError("body is longer than declared")
message = await self.asgi_receive()
message_type = message.get("type")
if message.get("type") == "http.disconnect":
raise ValueError("Disconnected")
if message_type != "http.request":
continue
chunk = message.get("body", b"")
if not isinstance(chunk, bytes):
raise ValueError("Chunk is not bytes")
self.http_body += chunk
self.http_has_more_body = message.get("more_body", False) or False
self.http_received_body_length += len(chunk)
yield chunk
async def body(self):
return b"".join([chunks async for chunks in self.body_iter()])
def put_resp_header(self, key, value):
self.resp_headers.add(key, value)
def put_resp_cookie(self, key, value):
self.resp_cookies[key] = value
I hope this code is easy to read. All it does is providing us with an interface that makes it easier to access info about the request, read request body, make sure body length is not larger than declared, and send the response back to the client. It also provides some safeguards to ensure messages of the right type is sent in the right state. For example, it ensures that http.response.start messages are always sent before http.response.body, and no more messages are sent after connection closed. Most of the heavy lifting in parsing header, cookie, and query is done by werkzeug and other Python built-in superheroes.
Let’s make a simple ASGI application with the Connection class:
# example1.py
from aaf.connection import Connection
async def app(scope, receive, send):
conn = Connection(scope, receive=receive, send=send)
name = conn.query.get("name")
await conn.send("Hello, " + (name or "world"), finish=True)
We can run this example by executing uvicorn example_1:app. Requesting /?name=foo should correctly return Hello, foo.
We now have an ASGI application that’s shorter in code and does more (accessing HTTP query). That’s one step closer to what we want!
It’s usually not required to have fine control over when to send what in an HTTP request-response cycle, returning a response that knows how to set headers and send the body is more convenient and familiar. To do that, we can write a simple HttpResponse helper class.
A JsonResponse is also added while we are at it.
# response.py
import json
from typing import Union, Optional, Mapping, Any
from .connection import Connection
class HttpResponse:
def __init__(
self,
body: Optional[Union[bytes, str]] = b"",
connection: Optional[Connection] = None,
*,
status_code: int = 200,
headers: Optional[Mapping[str, str]] = None
):
self.body = body
self.connection = connection
self.status_code = status_code
self.headers = headers
def __await__(self):
if not self.connection:
raise ValueError("No connection")
self.connection.resp_status_code = self.status_code
if self.headers:
for k, v in self.headers.items():
self.connection.put_resp_header(k, v)
return self.connection.send(self.body, finish=True).__await__()
class JsonResponse(HttpResponse):
def __init__(
self, data: Any, connection: Optional[Connection] = None, *args, **kwargs
):
body = json.dumps(data)
headers = kwargs.get("headers")
if headers is None:
headers = {}
headers["content-type"] = "application/json"
super().__init__(body, connection, *args, **kwargs)
There’s not much going on in the HttpResponse class. All it does is providing a familiar interface allowing us to pass in a response body, optional headers, optional status code, and calls the underneath methods in Connection class for us. In the example of JsonResponse class, it also sets the content-type header.
Let’s write another ASGI application to test it:
async def app(scope, receive, send):
conn = Connection(scope, receive=receive, send=send)
await JsonResponse(conn.query.to_dict(flat=False), conn)
This application should return all query parameters in the form of a JSON object when visited.
Great, the application is even shorter!
You might have noticed that this is not exactly how it’s used in the Goal section, where we can just return the response object instead of await on it. This is because this example is a plain ASGI application and the one in the original Goal section is in the context of a Router, who calls the await for us. The connection argument is allowed to be None in the constructor for the same reason.
Router dispatches requests based on requested url and HTTP method to different handlers. Most router implementations also parses parameters in urls. For example, if we define a router
@router.route('/a/<param_a>/<param_b>')
async def handler(connection, param_a, param_b):
...
and then tell the router to match the URL /a/foo/bar, it should give us the handler function as well as the parameters param_a and params_b.
This is indeed not easy but luckily, werkzeug comes with a routing module with does exactly this and even more, such as automatically redirect in the case of missing trailing slash. With its help, we can implement our routing module in around 60 lines of code.
# routing.py
import functools
from typing import Callable, Iterable, Optional
from werkzeug.routing import Map, MethodNotAllowed, NotFound, RequestRedirect, Rule
from .connection import Connection
from .response import HttpResponse
class Router:
def __init__(self):
super().__init__()
self.url_map = Map()
self.endpoint_to_handler = {}
def route(self, rule, methods=None, name=None):
methods = set(methods) if methods is not None else None
if methods and not "OPTIONS" in methods:
methods.add("OPTIONS")
def decorator(name: Optional[str], handler: Callable):
self.add_route(
rule_string=rule, handler=handler, methods=methods, name=name
)
return handler
return functools.partial(decorator, name)
def add_route(
self,
*,
rule_string: str,
handler: Callable,
name: Optional[str] = None,
methods: Optional[Iterable[str]] = None,
):
if not name:
name = handler.__name__
existing_handler = self.endpoint_to_handler.get(name)
if existing_handler and existing_handler is not handler:
raise ValueError("Duplicated route name: %s" % (name))
self.url_map.add(Rule(rule_string, endpoint=name, methods=methods))
self.endpoint_to_handler[name] = handler
def get_url_binding_for_connection(self, connection: Connection):
scope = connection.scope
return self.url_map.bind(
connection.req_headers.get("host"),
path_info=scope.get("path"),
script_name=scope.get("root_path") or None,
url_scheme=scope.get("scheme"),
query_args=scope.get("query_string", b""),
)
async def __call__(self, connection: Connection):
try:
rule, args = self.get_url_binding_for_connection(connection).match(
return_rule=True, method=connection.scope.get("method")
)
except RequestRedirect as e:
connection.resp_status_code = 302
connection.put_resp_header("location", e.new_url)
return await connection.send(f"redirecting to: {e.new_url}", finish=True)
except MethodNotAllowed:
connection.resp_status_code = 405
return await connection.send(b"", finish=True)
except NotFound:
pass
else:
handler = self.endpoint_to_handler[rule.endpoint]
res = await handler(connection, **args)
if isinstance(res, HttpResponse):
res.connection = connection
await res
In the __call__ method, I’m checking if the returned type from the handler is HttpResponsoe, if it is indeed HttpResponsoe, the router can await the response and the response takes care of sending headers and body.
Use this simple app to test it:
from aaf.connection import Connection
from aaf.response import JsonResponse
from aaf.routing import Router
router = Router()
@router.route("/hello/<name>")
async def hello(connection, name):
return JsonResponse({'hello': name})
async def app(scope, receive, send):
conn = Connection(scope, receive=receive, send=send)
await router(conn)
Visiting /hello/world should return {"hello": "world"}.
The application gets longer, but hopefully, it’s clear that with more routes to handle a router makes it a lot easier to handle.
Now, routers are great, but they are still not ASGI applications. Even though we can always write an ASGI application by hand, make a Connection out of it, and then call a router with the connection, it just doesn’t feel like an ASGI framework but more like an ASGI toolbox.
So, let’s write a helper function that turns a list of routers into an ASGI application. The idea of receiving a list of routers instead of just one is to allow an unhandled path to failover to the next router.
# __init__.py
from typing import List, Callable
from .connection import Connection
def aaf(routers: List[Callable]):
async def asgi_app(scope, receive, send):
conn = Connection(scope, send=send, receive=receive)
for router in routers:
await router(conn)
if conn.finished:
return
if conn.started:
await conn.finish()
else:
conn.resp_status_code = 404
await conn.send("Not found", finish=True)
return asgi_app
It also includes a default 404 response.
With the help of this new function, the previous example can be rewritten as:
from aaf.connection import Connection
from aaf.response import JsonResponse
from aaf.routing import Router
from aaf import aaf
router = Router()
@router.route("/hello/<name>")
async def hello(connection, name):
return JsonResponse({'hello': name})
app = aaf([router])
In fact the example defined in the goal section should also work now. Give it a try!
An infinite number of things can be added to this framework. On the top of my head, there are
Connection methodsI will write some of the things in the near future. And I wish this post could give readers enough information on where to start implementing them on their own.
]]>You can run background tasks like this in a django view and it would just work.
from django_simple_task import defer
def task1():
time.sleep(1)
print("task1 done")
async def task2():
await asyncio.sleep(1)
print("task2 done")
def view(requests):
defer(task1)
defer(task2)
return HttpResponse(b"My View")
Here’s an overview of how it works:
Preventing people from saving video content from your web site is never possible, because, firstly, video contents are always streamed to users’ device, users just cannot watch the video without retrieving it, secondly, people can always do a screen recording to save content.
Watermarking seems to be a reasonable solution to protect your content. If people download your video file and put it onto their websites, at least, people will know who made the video and/or your website.
There are lots of software packages that can do this, but they are not suitable for doing this to many videos in a server environment. And, of course, life is short.
MoviePy is the go-to choice for this type of task.
MoviePy is a Python module for video editing, which can be used for basic operations (like cuts, concatenations, title insertions), video compositing (a.k.a. non-linear editing), video processing, or to create advanced effects. It can read and write the most common video formats, including GIF.
Actually, MoviePy is not the only thing you need to install, it is dependent on many libraries and packages.
Most dependencies are installed automatically when you run pip install moviepy. There are two dependencies need to be installed manually, ImageMagick and FFmpeg.
ImageMagick can be easily installed via your system’s package management tool.
According to the document of MoviePy, FFMPEG will be automatically installed during the first use of MoviePy. However, the automatically installed FFMPEG was somehow unable to use some of the codecs depending on your system. It’s better to install FFMPEG by yourself.
FFmpeg is not included in some of the system’s standard package repo, fortunately, FFMPEG’s website provides some useful information about how to get it running in different platforms.
Writing the script is easy based on the example HERE in the documentation.
The example is actually more complicated that what we want, removing the unnecessary parts of the code:
from moviepy.editor import *
my_clip = VideoFileClip("../../videos/moi_ukulele.MOV", audio=True) # The video file with audio enabled
w,h = my_clip.size # size of the clip
# A CLIP WITH A TEXT AND A BLACK SEMI-OPAQUE BACKGROUND
txt = TextClip("THE WATERMARK TEXT", font='Amiri-regular',
color='white',fontsize=24)
txt_col = txt.on_color(size=(my_clip.w + txt.w,txt.h-10),
color=(0,0,0), pos=(6,'center'), col_opacity=0.6)
# This example demonstrates a moving text effect where the position is a function of time(t, in seconds).
# You can fix the position of the text manually, of course. Remember, you can use strings,
# like 'top', 'left' to specify the position
txt_mov = txt_col.set_pos( lambda t: (max(w/30,int(w-0.5*w*t)),
max(5*h/6,int(100*t))) )
# Write the file to disk
final = CompositeVideoClip([my_clip,txt_mov])
final.duration = my_clip.duration
final.write_videofile("OUT.mp4",fps=24,codec='libx264')
Rewriting the script, wrapping it into a function that takes input_file and output_file as arguments. Then, you can list the files to be watermarked with something like glob.glob('./*.mp4') and do an iteration over them.
ffmpeg_params=['-movflags', 'faststart'] as an argument to write_videofile method.threads as an argument to accelerate the process.codec to make it work.