Package: asgi-idempotency-header
Idempotency Header ASGI MiddlewareA middleware for making 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.
Additionally, only configured HTTP methods (by default,POSTandPATCH) that return JSON payloads are cached and replayed.This is largely modelled afterstripe' implementation.The middleware is compatible with bothStarletteandFastAPIapps.Installationpip install asgi-idempotency-headerSetupAdd the middleware to your app like this:fromfastapiimportFastAPIfromidempotency_header_middlewareimportIdempotencyHeaderMiddlewarefromidempotency_header_middleware.backendsimportRedisBackendbackend=RedisBackend(redis=redis)app=FastAPI()app.add_middleware(IdempotencyHeaderMiddleware(backend=backend))or like this:fromfastapiimportFastAPIfromfastapi.middlewareimportMiddlewarefromidempotency_header_middlewareimportIdempotencyHeaderMiddlewarefromidempotency_header_middleware.backendsimportRedisBackendbackend=RedisBackend(redis=redis)app=FastAPI(middleware=[Middleware(IdempotencyHeaderMiddleware,backend=backend,)])If you're usingStarlette, just substituteFastAPIforStarletteand it should work the same.ConfigurationThe middleware takes a few arguments. A full example looks like this:fromaioredisimportfrom_urlfromidempotency_header_middlewareimportIdempotencyHeaderMiddlewarefromidempotency_header_middleware.backendsimportRedisBackendredis=from_url(redis_url)backend=RedisBackend(redis=redis)IdempotencyHeaderMiddleware(backend,idempotency_header_key='Idempotency-Key',replay_header_key='Idempotent-Replayed',enforce_uuid4_formatting=False,expiry=60*60*24,applicable_methods=['POST','PATCH'])The following section describes each argument:Backendfromidempotency_header_middleware.backendsimportRedisBackend,MemoryBackendbackend:Union[RedisBackend,MemoryBackend]The backend is the only required argument, as it defineshowandwhereto store a response.The package comes with anaioredisbackend 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 keyidempotency_header_key:str='Idempotency-Key'The idempotency header key is the header value to check for. When present, the middleware will be used if the HTTP
method is in theapplicable methods.The default value is"Idempotency-Key", but it can be defined as any string.Replay header keyreplay_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 formattingenforce_uuid4_formatting:bool=FalseConvenience 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.Expiryexpiry:int=60*60*24How long to cache responses for, measured in seconds. Set to 24 hours by default.Applicable Methodsapplicable_methods=['POST','PATCH']What HTTP methods to consider for idempotency. If the request method is one of the methods in this list, and theidempotency headeris sent, the middleware will be used. By default, onlyPOSTandPATCHmethods are cached and replayed.Quick summary of behavioursBriefly summarized, this is how the middleware functions:The first request is processed, and consequent requests are replayed, until the response expires.expirycanbe 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 middlwarebeforethe 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.By default, the middleware only handles requests withPOSTandPATCHmethods. Other HTTP methods skip this middleware.Only valid JSON responses withcontent-type==application/jsonare cached.