update doc and add test

Author: azkrishpy

awscrt/http.py

@@ -325,9 +325,28 @@ def request(self,
                 This allows calling :meth:`HttpClientStream.write_data()` to stream
                 the request body in chunks. Works for both HTTP/1.1 and HTTP/2.
 
+                By design, CRT does not support setting both a body stream and
+                enabling manual writes for HTTP/1.1. Body streams are intended
+                for requests whose payload is available at the time of sending.
+                Manual writes let the caller control when data is sent. The two
+                cannot coexist on HTTP/1.1.
+
+                If ``manual_write`` is True and ``request`` has a ``body_stream``,
+                this method raises :class:`ValueError`.
+
+                HTTP/2 does not have this restriction.
+
         Returns:
             HttpClientStream:
+
+        Raises:
+            ValueError: If ``manual_write`` is True and the request has a
+                ``body_stream`` set (HTTP/1.1 only).
         """
+        if manual_write and request.body_stream is not None:
+            raise ValueError(
+                "Cannot use manual data writes with a body_stream on an HTTP/1.1 request. "
+                "Either remove the body_stream or set manual_write=False.")
         return HttpClientStream(self, request, on_response, on_body, manual_write)
 
     def close(self) -> "concurrent.futures.Future":
@@ -531,7 +550,7 @@ def _init_common(self,
                      request: 'HttpRequest',
                      on_response: Optional[Callable[..., None]] = None,
                      on_body: Optional[Callable[..., None]] = None,
-                     http2_manual_write: bool = False) -> None:
+                     manual_write: bool = False) -> None:
         assert isinstance(connection, HttpClientConnectionBase)
         assert isinstance(request, HttpRequest)
         assert callable(on_response) or on_response is None
@@ -545,7 +564,7 @@ def _init_common(self,
         # keep HttpRequest alive until stream completes
         self._request = request
         self._version = connection.version
-        self._binding = _awscrt.http_client_stream_new(self, connection, request, http2_manual_write)
+        self._binding = _awscrt.http_client_stream_new(self, connection, request, manual_write)
 
     @property
     def version(self) -> HttpVersion:
@@ -676,20 +695,9 @@ def write_data(self,
         The stream must have been created with ``manual_write=True`` and
         :meth:`activate()` must have been called before using this method.
 
-        .. important::
-            HTTP/1.1 does **not** support combining a body stream with manual
-            writes. The underlying H1 encoder uses a modal state machine that
-            commits to a single body-delivery path at initialisation time.
-            If the :class:`HttpRequest` was created with a ``body_stream``,
-            calling this method will raise :class:`RuntimeError`.
-
-            HTTP/2 does not have this limitation — see
-            :meth:`Http2ClientStream.write_data`.
-
-        .. deprecated:: 0.x
-            This method supersedes the C-level ``aws_http1_stream_write_chunk``
-            API. Use ``write_data`` for all manual body writes on both HTTP/1.1
-            and HTTP/2 streams.
+        This method supersedes the deprecated ``write_chunk`` API.
+        Use ``write_data()`` for all manual body writes on both HTTP/1.1
+        and HTTP/2 streams.
 
         Args:
             data_stream: Data to write. Wrapped in :class:`~awscrt.io.InputStream` if
@@ -698,18 +706,7 @@ def write_data(self,
 
         Returns:
             concurrent.futures.Future: Completes with ``None`` on success.
-
-        Raises:
-            RuntimeError: If the request has a ``body_stream`` set.
         '''
-        if self._request and self._request.body_stream is not None:
-            raise RuntimeError(
-                "Cannot use write_data() on an HTTP/1.1 stream whose HttpRequest "
-                "has a body_stream set. The H1 encoder is modal — it picks one "
-                "body delivery path at init time and cannot switch mid-stream. "
-                "Either remove the body_stream and use write_data() exclusively, "
-                "or use the body_stream without calling write_data()."
-            )
         return super().write_data(data_stream, end_stream)
 
 
@@ -781,21 +778,11 @@ def write_data(self,
         The stream must have been created with ``manual_write=True`` and
         :meth:`activate()` must have been called before using this method.
 
-        Unlike HTTP/1.1, HTTP/2 uses a queue-based write design
-        (``outgoing_writes`` queue of ``aws_h2_stream_data_write`` structs).
-        The body stream, if present, is simply the first item in the queue,
-        and manual writes append additional items. The connection scheduler
-        drains the queue and encodes DATA frames regardless of origin. This
-        means HTTP/2 **can** combine a ``body_stream`` with subsequent
-        ``write_data()`` calls — the two compose naturally.
-
-        This is a key design difference from HTTP/1.1, whose encoder is
-        *modal* (picks one body path at init) rather than *compositional*.
-
-        .. deprecated:: 0.x
-            This method supersedes the C-level ``aws_http1_stream_write_chunk``
-            API. Use ``write_data`` for all manual body writes on both HTTP/1.1
-            and HTTP/2 streams.
+        When both a body stream and manual writes are enabled, the body
+        stream is sent first and the connection then waits asynchronously
+        for subsequent ``write_data()`` calls. However, if the body stream
+        has not signalled end-of-stream, the event loop will keep getting
+        scheduled for requesting more data until it completes.
 
         Args:
             data_stream: Data to write. Wrapped in :class:`~awscrt.io.InputStream` if

test/test_http_client.py

@@ -961,5 +961,129 @@ def test_h2_remote_end_stream_ordering(self):
         connection.close().result(self.timeout)
 
 
+@unittest.skipUnless(os.environ.get('AWS_TEST_LOCALHOST'), 'set env var to run test: AWS_TEST_LOCALHOST')
+class TestH1WriteData(LocalServerTestBase):
+    """HTTP/1.1 write_data() tests — mirrors Java WriteDataTest scenarios.
+    Uses the existing LocalServerTestBase and PUT echo pattern."""
+    timeout = 10
+
+    def _new_h1_tls_connection(self):
+        """Create HTTP/1.1 TLS connection to local server"""
+        tls_ctx_opt = TlsContextOptions()
+        tls_ctx_opt.verify_peer = False
+        tls_ctx = ClientTlsContext(tls_ctx_opt)
+        tls_conn_opt = tls_ctx.new_connection_options()
+        tls_conn_opt.set_server_name(self.hostname)
+
+        event_loop_group = EventLoopGroup()
+        host_resolver = DefaultHostResolver(event_loop_group)
+        bootstrap = ClientBootstrap(event_loop_group, host_resolver)
+
+        connection = HttpClientConnection.new(
+            host_name=self.hostname,
+            port=self.port,
+            bootstrap=bootstrap,
+            tls_connection_options=tls_conn_opt,
+        ).result(self.timeout)
+        self.assertEqual(connection.version, HttpVersion.Http1_1)
+        return connection
+
+    def test_h1_write_data(self):
+        """H1 PUT with manual write — mirrors Java testHttp1WriteData"""
+        self._start_server(secure=True)
+        try:
+            connection = self._new_h1_tls_connection()
+            payload = b'hello from writeData h1'
+
+            request = HttpRequest('PUT', '/write_data_test')
+            request.headers.add('host', self.hostname)
+            request.headers.add('Content-Length', str(len(payload)))
+
+            response = Response()
+            stream = connection.request(request, response.on_response, response.on_body, manual_write=True)
+            stream.activate()
+
+            stream.write_data(BytesIO(payload), end_stream=True).result(self.timeout)
+            status = stream.completion_future.result(self.timeout)
+
+            self.assertEqual(200, status)
+            self.assertEqual(payload, self.server.put_requests.get('/write_data_test'))
+
+            connection.close().result(self.timeout)
+        finally:
+            self._stop_server()
+
+    def test_h1_write_data_end_stream_only(self):
+        """H1 PUT with zero-byte body — mirrors Java testHttp1WriteDataEndStreamOnly"""
+        self._start_server(secure=True)
+        try:
+            connection = self._new_h1_tls_connection()
+
+            request = HttpRequest('PUT', '/write_data_empty')
+            request.headers.add('host', self.hostname)
+            request.headers.add('Content-Length', '0')
+
+            response = Response()
+            stream = connection.request(request, response.on_response, response.on_body, manual_write=True)
+            stream.activate()
+
+            stream.write_data(None, end_stream=True).result(self.timeout)
+            status = stream.completion_future.result(self.timeout)
+
+            self.assertEqual(200, status)
+            self.assertEqual(b'', self.server.put_requests.get('/write_data_empty'))
+
+            connection.close().result(self.timeout)
+        finally:
+            self._stop_server()
+
+    def test_h1_write_data_multi_chunk(self):
+        """H1 PUT with multiple write_data calls"""
+        self._start_server(secure=True)
+        try:
+            connection = self._new_h1_tls_connection()
+            chunks = [b'chunk1', b'chunk2', b'chunk3']
+            total = b''.join(chunks)
+
+            request = HttpRequest('PUT', '/write_data_multi')
+            request.headers.add('host', self.hostname)
+            request.headers.add('Content-Length', str(len(total)))
+
+            response = Response()
+            stream = connection.request(request, response.on_response, response.on_body, manual_write=True)
+            stream.activate()
+
+            for i, chunk in enumerate(chunks):
+                stream.write_data(BytesIO(chunk), end_stream=(i == len(chunks) - 1)).result(self.timeout)
+
+            status = stream.completion_future.result(self.timeout)
+
+            self.assertEqual(200, status)
+            self.assertEqual(total, self.server.put_requests.get('/write_data_multi'))
+
+            connection.close().result(self.timeout)
+        finally:
+            self._stop_server()
+
+    def test_h1_write_data_with_body_stream_raises(self):
+        """H1 request() must raise ValueError if manual_write=True and body_stream is set."""
+        self._start_server(secure=True)
+        try:
+            connection = self._new_h1_tls_connection()
+
+            request = HttpRequest('PUT', '/write_data_guard', body_stream=BytesIO(b'body'))
+            request.headers.add('host', self.hostname)
+            request.headers.add('Content-Length', '4')
+
+            with self.assertRaises(ValueError) as ctx:
+                connection.request(request, manual_write=True)
+
+            self.assertIn('body_stream', str(ctx.exception))
+
+            connection.close().result(self.timeout)
+        finally:
+            self._stop_server()
+
+
 if __name__ == '__main__':
     unittest.main()