Merge branch 'master' into patch-4

CHANGELOG.md

@@ -4,9 +4,10 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## Unreleased
+## 1.0.4 (February 21st, 2024)
 
-- Fix support for connection Upgrade and CONNECT when some data in the stream has been read. (#882)
+- Add `target` request extension. (#888)
+- Fix support for connection `Upgrade` and `CONNECT` when some data in the stream has been read. (#882)
 
 ## 1.0.3 (February 13th, 2024)
 

docs/extensions.md

@@ -166,6 +166,28 @@ response = httpcore.request(
 )
 ```
 
+### `"target"`
+
+The target that is used as [the HTTP target instead of the URL path](https://datatracker.ietf.org/doc/html/rfc2616#section-5.1.2).
+
+This enables support constructing requests that would otherwise be unsupported. In particular...
+
+* Forward proxy requests using an absolute URI.
+* Tunneling proxy requests using `CONNECT` with hostname as the target.
+* Server-wide `OPTIONS *` requests.
+
+For example:
+
+```python
+extensions = {"target": b"www.encode.io:443"}
+response = httpcore.request(
+    "CONNECT",
+    "http://your-tunnel-proxy.com",
+    headers=headers,
+    extensions=extensions
+)
+```
+
 ## Response Extensions
 
 ### `"http_version"`
@@ -214,9 +236,9 @@ A proxy CONNECT request using the network stream:
 # 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:
+url = "http://127.0.0.1:8080"
+extensions = {"target: "http://www.example.com"}
+with httpcore.stream("CONNECT", url, extensions=extensions) as response:
     network_stream = response.extensions["network_stream"]
 
     # Upgrade to an SSL stream...

httpcore/__init__.py

@@ -130,7 +130,7 @@ def __init__(self, *args, **kwargs):  # type: ignore
     "WriteError",
 ]
 
-__version__ = "1.0.3"
+__version__ = "1.0.4"
 
 
 __locals = locals()

httpcore/_models.py

@@ -353,6 +353,14 @@ def __init__(
         )
         self.extensions = {} if extensions is None else extensions
 
+        if "target" in self.extensions:
+            self.url = URL(
+                scheme=self.url.scheme,
+                host=self.url.host,
+                port=self.url.port,
+                target=self.extensions["target"],
+            )
+
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} [{self.method!r}]>"
 

scripts/check

@@ -11,4 +11,4 @@ set -x
 ${PREFIX}ruff check --show-source $SOURCE_FILES
 ${PREFIX}ruff format $SOURCE_FILES --diff
 ${PREFIX}mypy $SOURCE_FILES
-scripts/unasync --check
+${PREFIX}python scripts/unasync.py --check

scripts/lint

@@ -13,4 +13,4 @@ ${PREFIX}ruff format $SOURCE_FILES
 
 # Run unasync last because its `--check` mode is not aware of code formatters.
 # (This means sync code isn't prettified, and that's mostly okay.)
-scripts/unasync
+${PREFIX}python scripts/unasync.py

tests/test_models.py

@@ -58,6 +58,20 @@ def test_request():
     assert repr(request.stream) == "<ByteStream [0 bytes]>"
 
 
+def test_request_with_target_extension():
+    extensions = {"target": b"/another_path"}
+    request = httpcore.Request(
+        "GET", "https://www.example.com/path", extensions=extensions
+    )
+    assert request.url.target == b"/another_path"
+
+    extensions = {"target": b"/unescaped|path"}
+    request = httpcore.Request(
+        "GET", "https://www.example.com/path", extensions=extensions
+    )
+    assert request.url.target == b"/unescaped|path"
+
+
 def test_request_with_invalid_method():
     with pytest.raises(TypeError) as exc_info:
         httpcore.Request(123, "https://www.example.com/")  # type: ignore