Idempotency Header ASGI Middleware
A middleware for making POST and PATCH endpoints idempotent.
The purpose of the middleware is to guarantee that execution of mutating endpoints happens exactly once, regardless of the number of requests. We achieve this by caching responses, and returning already-saved responses to the user on repeated requests. Responses are only cached when an idempotency-key HTTP header is present, so clients must opt-into this behaviour.
This is largely modelled after stripe' implementation.
The middleware is compatible with both Starlette and FastAPI apps.
Installation
pip install asgi-idempotency-header
Setup
Add the middleware to your app like this:
from fastapi import FastAPI
from idempotency_header_middleware import IdempotencyHeaderMiddleware
from idempotency_header_middleware.backends import AioredisBackend
backend = AioredisBackend(redis=redis)
app = FastAPI()
app.add_middleware(IdempotencyHeaderMiddleware(backend=backend))
or like this:
from fastapi import FastAPI
from fastapi.middleware import Middleware
from idempotency_header_middleware import IdempotencyHeaderMiddleware
from idempotency_header_middleware.backends import AioredisBackend
backend = AioredisBackend(redis=redis)
app = FastAPI(
middleware=[
Middleware(
IdempotencyHeaderMiddleware,
backend=backend,
)
]
)
If you're using Starlette, just substitute FastAPI for Starlette and it should work the same.
Configuration
The middleware takes a few arguments. A full example looks like this:
from aioredis import from_url
from idempotency_header_middleware import IdempotencyHeaderMiddleware
from idempotency_header_middleware.backends import AioredisBackend
redis = from_url(redis_url)
backend = AioredisBackend(redis=redis)
IdempotencyHeaderMiddleware(
backend,
idempotency_header_key='Idempotency-Key',
replay_header_key='Idempotent-Replayed',
enforce_uuid4_formatting=False,
expiry=60 * 60 * 24,
)
The following section describes each argument:
Backend
from idempotency_header_middleware.backends import AioredisBackend, MemoryBackend
backend: Union[AioredisBackend, MemoryBackend]
The backend is the only required argument, as it defines how and where to store a response.
The package comes with an aioredis backend implementation, and a memory-backend for testing.
Contributions for more backends are welcomed, and configuring a custom backend is pretty simple - just take a look at the existing ones.
Idempotency header key
idempotency_header_key: str = 'Idempotency-Key'
The idempotency header key is the header value to check for. When present, the middleware is used.
The default value is "Idempotency-Key", but it can be defined as any string.
Replay header key
replay_header_key: str = 'Idempotent-Replayed'
The replay header is added to replayed responses. It provides a way for the client to tell whether the action was performed for the first time or not.
Enforce UUID formatting
enforce_uuid4_formatting: bool = False
Convenience option for stricter header value validation.
Clients can technically set any value they want in their header, but the shorter the key value is, the higher the risk of value-collisions is from other users. If two users accidentally send in the same header value for what's meant to be two separate requests, the middleware will interpret them as the same.
By enabling this option, you can force users to use UUIDs as header values, and pretty much eliminate this risk.
When validation fails, a 422 response is returned from the middleware, informing the user that the header value is malformed.
Expiry
expiry: int = 60 * 60 * 24
How long to cache responses for, measured in seconds. Set to 24 hours by default.
Quick summary of behaviours
Briefly summarized, this is how the middleware functions:
- The first request is processed, and consequent requests are replayed, until the response expires.
expirycan be set toNoneto skip expiry, but most likely you will want to expire responses after a while. - If two requests comes in at the same time - i.e., if a second request hits the middlware before the first request has finished, the middleware will return a 409, informing the user that a request is being processed, and that we cannot handle the second request.
- The middleware only handles HTTP requests.
- The middleware only handles requests with
POSTandPATCHmethods. Other HTTP methods are idempotent by default.
4 Mar 29, 2022
15 Dec 31, 2022
1 Jan 10, 2022
20 Feb 08, 2022
150 Nov 29, 2022
33 Dec 18, 2022
1 Nov 13, 2021
143 Nov 15, 2022
109 Dec 23, 2022
3 May 17, 2022
301 Dec 09, 2022
99 Dec 27, 2022
147 Nov 02, 2022
1 Oct 27, 2021
1 Jan 03, 2022
1 Jan 07, 2023
7 Oct 19, 2022
14.5k Jan 08, 2023