Add target request extension

[karpetrosyan]

Refs: encode/httpx#2949 (reply in thread)

This PR adds a target extension, which can be used to force HTTP target to a specific bytes-encoded string.

Check out https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#request_line to read more about HTTP message structure and what HTTP target is.

[tomchristie]

Okay... interesting. I was expecting this to be applied in httpx.HTTPTransport.

We actually support this in httpcore already, because the httpcore.URL() instances are a deliberately simple tuple of scheme, host, port, target.

Perhaps that distinction is subtle enough that it makes sense for us to apply this extension at the httpcore level even though it can be supported with the existing httpcore API?

---

Note to self our Request/Response/URL docs are missing here... https://github.com/encode/httpcore/blob/d4678e61b0af24747676c18fb0cb0b2027867bb0/docs/requests-responses-urls.md

[karpetrosyan]

I thought it is more natural to have this kind of extension logic in the httpcore package + all the transports will support it.

[tomchristie]

How does this (does this?) effect (affect?) the proxies?

[tomchristie]

So here's where I was expecting we'd implement this...

https://github.com/encode/httpx/blob/3faa4a8f2e0d406167b913bbfd3afab087662d03/httpx/_transports/default.py#L222-L227

https://github.com/encode/httpx/blob/3faa4a8f2e0d406167b913bbfd3afab087662d03/httpx/_transports/default.py#L362-L367

Thoughts?

[karpetrosyan]

I don't see any differences, If you like to see this at the httpx layer, I can close this one and open a new PR.

But, is there anything wrong with this one? Passing the target extension directly to the H11 target makes more sense to me.

[tomchristie]

But, is there anything wrong with this one?

You're probably right that it's sensible to implement this directly in httpcore, since all the other extensions we support are also there. Good call.

I think the neatest way is implementing this elsewhere...

httpcore/httpcore/_models.py

Line 354 in 908013c

self.extensions = {} if extensions is None else extensions

if 'target' in extensions:
    self.url = URL(
        scheme=self.url.scheme,
        host=self.url.host,
        port=self.url.port,
        target=extensions['target'],
    )

That'll update the target once, and be passed through everywhere.

Reasonable?

[karpetrosyan]

Reasonable?

Much neater, thanks.

[tomchristie]

Looks good, thanks. 😊

I'd suggest also updating the CONNECT requests docs...

httpcore/docs/extensions.md

Lines 212 to 219 in 908013c

	# Formulate a CONNECT request...
	#
	# This will establish a connection to 127.0.0.1:8080, and then send the following...
	#
	# CONNECT http://www.example.com HTTP/1.1
	# Host: 127.0.0.1:8080
	url = httpcore.URL(b"http", b"127.0.0.1", 8080, b"http://www.example.com")
	with httpcore.stream("CONNECT", url) as response:

Since we can now express this with...

url = "http://127.0.0.1:8080"
extensions = {"target: "http://www.example.com"}
with httpcore.stream("CONNECT", url, extensions=extensions) as response: 

Then, yep let's get this in.

[tomchristie]

Made a couple of additional docs changes on top of this.
Fantastic addition, thanks @karpetrosyan. 🎉