Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Public middleware API

See original GitHub issue

Problem We currently have an internal middleware API that was brought in via #295 and #268.

We should be looking at making that API (or a different form of it?) public so that users can extend the functionality of the client to fit their needs.

For example, a retry functionality (discussed in https://github.com/encode/httpx/issues/108 and drafted in https://github.com/encode/httpx/pull/134 then abandoned) could probably be implemented as a middleware (basic idea here: https://github.com/encode/httpx/pull/268#issuecomment-526909874).

Questions to be answered

Is a public middleware API still a good idea at all? (IMO, it is.)
We already have a middleware-side interface: request, get_response -> response. What’s the client-side API going to look like? Probably something like…

client = httpx.Client()
client.add_middleware(RetryMiddleware, max_retries=3)

Should we apply existing internal middleware such as auth and redirect by default?

IMO, yes: treat those as core middleware, and add custom middleware on top. It might depend on the use case, but we can start off with that.

Should users be able to we control at what level a new middleware is applied, and how?

@sethmlarson proposed an idea inspired by Pyramid here: https://github.com/encode/httpx/issues/295#issuecomment-526933309

Should middleware be able to store session-wide data, and how?

This was originally mentioned in https://github.com/encode/httpx/issues/295#issuecomment-526933309, and would be used to store state worth remembering such as cookies or Alt-Svc headers for HTTP/3 (see https://github.com/encode/httpx/issues/275#issuecomment-531067555).

IMO the use case still needs to be refined for us to clearly see what needs to be done.

What needs to be done

This is a proposal. 😃

Answer the questions above and add the public middleware API.
Document how to write middleware (Advanced section?). We learnt by experience (e.g. https://github.com/encode/httpx/pull/332#discussion_r322816118) that middleware instances shouldn’t hold any mutable state, so let’s make sure we mention that here.
Document how to use middleware (Advanced section?).
(Later) Figure out middleware ordering.
(Later) Figure out client-side storage.

All thoughts welcome!