Repository navigation
Transport API #768
Description
What is the dispatcher API, and why is it useful?...
The dispatcher is the part of the system that's responsible for actually sending the request and returning a response to the client. Having an API to override the dispatcher used by the client allows you to take complete control over that process, and switch out the default behaviour with something else.
For instance the "plug in to a WSGI app" and "plug in to an ASGI app" cases that we support are implemented as dispatcher classes, that send the request to a Python web application, rather than sending a network request.
Currently the dispatchers are considered private API, but really we'd like a public API here at some point. This issue is for discussing what we think that API should be.
Right now the API is...
def send(request: Request, timeout: Timeout = None) -> Response:
...
def close():
...Withasync equivelents for the async case.
That's actually pretty okay, but if we're looking at a public API, we ought to figure out if it's actually what we want to expose. There's a case to be made for making the dispatcher API just take plain primitive datastructures, rather than dealing with Request/Response models. That'd make for a more portable interface, that could be used in other packages without importing httpx.
That might look something like this...
def send(self, method: bytes, url: Typle[bytes, bytes, int, bytes], headers: List[Tuple[bytes, bytes]], body: ClosableIterator[bytes] = None, timeout: Timeout = None):
...
return (status_code: int, http_version: bytes, reason_phrase: bytes, headers: List[Tuple[bytes, bytes]], body: ClosableIterator[bytes])
def close():
...Both the request and response bodies would be byte-iterable, closable interfaces (or byte async-iterable, closable interfaces). Everything else would be plain ol' Python datastructures.
Thoughts:
- It's feasible that
urlcould be defined as a tuple or url components instead, so that we can keep pass a parsed url objects from the client to a dispatcher interface? **Update: I've tweaked the interface to describe it that way around, as "scheme", "host", "port", "full_path". - We do need to have the timeout be part of the dispatch interface, since we want to be able to support configured-per-request timeout values - I'd guess we'd need to define that as an optional four-tuple of connect/read/write/pool float timeout values.
- We might want to think about defining expected exception types.
- There's no support for HTTP trailing headers in this interface. Perhaps we don't care about that, or could the
ContentStream.close()perhaps optionally return a list of headers, maybe?
Something that'd potentially be interesting about defining this interface in a really strict, primitive datastructures way, would be that we could pull out our dispatcher implementations into a really tightly scoped package httpcore, that'd just provide the plain network dispatchers, without any client smarts around them. (Interesting amongst other things because it'd provide a nice just-the-network-backend for other client libs to potentially use too / switch too.)
I think a useful first take onto all of this might? be an exploratory pull request that switches us over to using a plainer dispatch API, just to get a feel for how that'd look. A very first initial take on that could still use the URL, ContentStream, and Timeout primitives.
(This also potentially ties in with whatever the hip team's plans are. For instance, right now we're using our own dispatcher implementation - currently in the async case only, but planned for both cases - but we would have the option of using the hip backend, once it's available. It's not obvious to me if we'd want to do that, or if we'd prefer to continue with our existing backend, which is looking pretty nice now, but it could be a point of collaboration, or something to discuss.)
Alternately, we might decide that this falls into architecture astronauting territory, and that the existing API is "just fine thankyouverymuch".
Activity
lovelydinosaur commentedon Jan 30, 2020
I think it's probably a good time for us to start pushing ahead with this, and ensuring that we've got a nice clean interface split between everything in the dispatcher implementation vs. everything at the client level.
Here's a plan towards how we could approach that...
cert,verify,trust_envfromConnectionPool, and configure using a plainssl_context: SSLContext = Noneat that level. (The client would passssl_config.ssl_contextwhen instantiating theConnectionPool)pool_limitsfrom ConnectionPool, and instead providemax_keepaliveandmax_connectionsconfiguration at that level. (The client would passpool_limits.soft_limit/pool_limits.hard_limitwhen instantiating theConnectionPool) - Related to that we might want to rename soft_limit/hard_limit?At that point we've got both the Dispatcher API, and the connection pool init nicely decoupled from any model/httpx-config-classes info, and it'd probably be a good point to tackle our
unasync'ed sync connection pool implementation, that'd allow us to dropurllib3as the sync default.I think that a neat tack at that point might be to spin up a completely seperate
httpcorerepo, containing just the dispatch and backends, and the tests for those. We wouldn't include the ASGI, WSGI, and urllib3 dispatch classes in there either since we won't be runningunasyncon those. Then...httpcorerepo.unasyncinto the mix, to provide aSyncConnectionPoolimplementation.httpcore.AsyncConnectionPool, andhttpcore.AsyncHTTPProxy.httpcore.SyncConnectionPoolandhttpcore.SyncHTTPProxy. (With ourURLLib3Dispatcher()class remaining as an optional alternative)One possible outcome that designing out a really strict interface could potentially have here would be to put us in a better position to be able to collaborate with the
hipteam, since we've got a nice clear options of "switch to a hip-based backend" or "switch to a hip-based backend for HTTP/1.1 only, or httpcore if HTTP/2 is enabled". Not clear if that's feasible, but at least it gives us options.I'm not absolutely sold on the neccessity of pulling the dispatch out into a seperate package, but...
httpcorework as exploratory and take a view on "just include this all in the same package" vs. "enforced split" once we've done the unasync work.lovelydinosaur commentedon Jan 30, 2020
There's other potentially productive points of collaboration here too, since
httpcorewould be a nice minimal dependency for other client libs to use for their core networking too.One good example here would be adding a
requestsadapter class usinghttpcore. https://github.com/psf/requests/blob/master/requests/adapters.py#L55florimondmanca commentedon Jan 30, 2020
I can't express how excited I am about this.
We've been talking about trying to draw the line between "low-level/network/just-make-an-HTTP-request stuff" vs "client-with-smarts stuff" for some time, including reaching out for comments in python-http/discussions#9.
So the idea of "let's just try to make it happen" by experimenting from own our code is exciting because it gives a concrete view on how things could be organized.
lovelydinosaur commentedon Jan 30, 2020
Ace! 🌟😃🌟
I've created https://github.com/encode/httpcore - for my part I'll probably start by drawing up the documentation for it. We essentially know what the interface will look like.
(Also, we'll repurpose the
httpcorePyPI project whichhttpxwas under while it was still in its earliest days of devlopement.)StephenBrown2 commentedon Jan 30, 2020
Tangentially related to prior renames/rebrands, the https://pypi.org/project/requests-async/ and https://pypi.org/project/http3/ projects should have their documentation updated to point to https://pypi.org/project/httpx/ / https://www.python-httpx.org/
lovelydinosaur commentedon Jan 30, 2020
Here we go... 👉 https://www.encode.io/httpcore/
lovelydinosaur commentedon Jan 30, 2020
@StephenBrown2 Yup, good point.
lovelydinosaur commentedon May 13, 2020
Things I think we need to do for 1.0...
transport=..., withdispatch=...placed on the deprecation path, right?transport = httpcore.SyncConnectionPool(...). to help users see how that fits together.transport = httpx.URLLib3Transport(...).We might also need to think about a "mount" API, and/or how to document proxy transport classes alongside this.
[-]Dispatcher API[/-][+]Transport API[/+]lovelydinosaur commentedon May 21, 2020
Gives me warm fuzzies how tightly defined our low-level transport API is. 👍💚