msgpack-asgi
msgpack-asgi allows you to add automatic MessagePack content negotiation to ASGI applications (Starlette, FastAPI, Quart, etc.), with a single line of code:
app.add_middleware(MessagePackMiddleware)
(You may want to adapt this snippet to your framework-specific middleware API.)
This gives you the bandwitdth usage reduction benefits of MessagePack without having to change existing code.
Note: this comes at a CPU usage cost, since MessagePackMiddleware will perform MsgPack decoding while your application continues to decode and encode JSON data (see also How it works). If your use case is CPU-sensitive, rather than strictly focused on reducing network bandwidth, this package may not be for you.
Installation
Install with pip:
pip install "msgpack-asgi==1.*"
Quickstart
First, you'll need an ASGI application. Let's use this sample application, which exposes an endpoint that returns JSON data:
# For convenience, we use some ASGI components from Starlette.
# Install with: `$ pip install starlette`.
from starlette.requests import Request
from starlette.responses import JSONResponse
async def get_response(request):
if request.method == "POST":
data = await request.json()
return JSONResponse({"data": data})
else:
return JSONResponse({"message": "Hello, msgpack!"})
async def app(scope, receive, send):
assert scope["type"] == "http"
request = Request(scope=scope, receive=receive)
response = await get_response(request)
await response(scope, receive, send)
Then, wrap your application around MessagePackMiddleware:
from msgpack_asgi import MessagePackMiddleware
app = MessagePackMiddleware(app)
Serve your application using an ASGI server, for example with Uvicorn:
uvicorn app:app
Now, let's make a request that accepts MessagePack data in response:
curl -i http://localhost:8000 -H "Accept: application/x-msgpack"
You should get the following output:
HTTP/1.1 200 OK
date: Fri, 01 Nov 2019 17:40:14 GMT
server: uvicorn
content-length: 25
content-type: application/x-msgpack
��message�Hello, msgpack!
What happened? Since we told the application that we accepted MessagePack-encoded responses, msgpack-asgi automatically converted the JSON data returned by the Starlette application to MessagePack.
We can make sure the response contains valid MessagePack data by making the request again in Python, and decoding the response content:
>>> import requests
>>> import msgpack
>>> url = "http://localhost:8000"
>>> headers = {"accept": "application/x-msgpack"}
>>> r = requests.get(url, headers=headers)
>>> r.content
b'\x81\xa7message\xafHello, msgpack!'
>>> msgpack.unpackb(r.content, raw=False)
{'message': 'Hello, msgpack!'}
msgpack-asgi also works in reverse: it will automatically decode MessagePack-encoded data sent by the client to JSON. We can try this out by making a POST request to our sample application with a MessagePack-encoded body:
>>> import requests
>>> import msgpack
>>> url = "http://localhost:8000"
>>> data = msgpack.packb({"message": "Hi, there!"})
>>> headers = {"content-type": "application/x-msgpack"}
>>> r = requests.post(url, data=data, headers=headers)
>>> r.json()
{'data': {'message': 'Hi, there!'}}
That's all there is to it! You can now go reduce the size of your payloads.
Limitations
msgpack-asgi does not support request or response streaming. This is because the full request and response body content has to be loaded in memory before it can be re-encoded.
How it works
An ASGI application wrapped around MessagePackMiddleware will perform automatic content negotiation based on the client's capabilities. More precisely:
- If the client sends MessagePack-encoded data with the
application/x-msgpackcontent type,msgpack-asgiwill automatically re-encode it to JSON for your application to consume. - If the client sent the
Accept: application/x-msgpackheader,msgpack-asgiwill automatically re-encode any JSON response data to MessagePack for the client to consume.
(In other cases, msgpack-asgi won't intervene at all.)
License
MIT
309 Jan 04, 2023
2.3k Dec 30, 2022
135 Dec 19, 2022
310 Dec 14, 2022
351 Jan 04, 2023
140 Dec 27, 2022
7 Aug 01, 2022
3 Dec 05, 2022
2.1k Dec 31, 2022
9 Nov 15, 2022
0 Sep 24, 2022
225 Jan 05, 2023
543 Jan 05, 2023
58 Dec 29, 2022
441 Jan 05, 2023
7 May 04, 2022
22 Dec 20, 2022
31 Nov 25, 2022
1.5k Jan 04, 2023
11 Dec 31, 2022