awscrt.http¶

HTTP

All network operations in awscrt.http are asynchronous.

class awscrt.http.HttpVersion(value)¶

HTTP protocol version enumeration

Unknown = 0¶: Unknown

Http1_0 = 1¶: HTTP/1.0

Http1_1 = 2¶: HTTP/1.1

Http2 = 3¶: HTTP/2

class awscrt.http.Http2SettingID(value)¶: HTTP/2 Predefined settings(RFC-9113 6.5.2).

class awscrt.http.Http2Setting(id: Http2SettingID, value: int)¶

HTTP/2 Setting. Settings are very complicated in HTTP/2. Each end has its own settings, and the local settings cannot be applied until the remote end acknowledges it. Each end can change its settings at any time, while the order of the settings changed may also result in different behavior.

Each setting has its boundary and initial values defined in RFC-9113 6.5.2: Initial values are listed below, while the range can be found in VALID_RANGES: HEADER_TABLE_SIZE: 4096 ENABLE_PUSH: 1 MAX_CONCURRENT_STREAMS: 2^32-1 INITIAL_WINDOW_SIZE: 2^16-1 MAX_FRAME_SIZE: 2^14 MAX_HEADER_LIST_SIZE: 2^32-1

Parameters:

id (Http2SettingID) – Setting ID.
value (int) – Setting value.

class awscrt.http.HttpClientConnectionBase¶

property host_name: str¶: Remote hostname

property port: int¶: Remote port

is_open() → bool¶

Returns:: bool – True if this connection is open and usable, False otherwise. Check shutdown_future to know when the connection is completely finished shutting down.

property shutdown_future: concurrent.futures.Future¶

Completes when this connection has finished shutting down. Future will contain a result of None, or an exception indicating why shutdown occurred. Note that the connection may have been garbage-collected before this future completes.

Type:: concurrent.futures.Future

property version: HttpVersion¶

Protocol used by this connection

Type:: HttpVersion

class awscrt.http.HttpClientConnection¶

An HTTP client connection.

Use HttpClientConnection.new() to establish a new connection.

classmethod new(host_name: str, port: int, bootstrap: ClientBootstrap | None = None, socket_options: SocketOptions | None = None, tls_connection_options: TlsConnectionOptions | None = None, proxy_options: HttpProxyOptions | None = None, manual_window_management: bool = False, initial_window_size: int | None = None, read_buffer_capacity: int | None = None) → concurrent.futures.Future¶

Asynchronously establish a new HttpClientConnection.

Parameters:

host_name (str) – Connect to host.
port (int) – Connect to port.
bootstrap (Optional [ClientBootstrap]) – Client bootstrap to use when initiating socket connection. If None is provided, the default singleton is used.
socket_options (Optional[SocketOptions]) – Optional socket options. If None is provided, then default options are used.
tls_connection_options (Optional[TlsConnectionOptions]) – Optional TLS connection options. If None is provided, then the connection will be attempted over plain-text.
proxy_options (Optional[HttpProxyOptions]) – Optional proxy options. If None is provided then a proxy is not used.
manual_window_management (bool) – Set to True to manually manage the flow-control window of each stream. If False, the connection maintains flow-control windows such that no back-pressure is applied and data arrives as fast as possible. If True, the flow-control window of each stream shrinks as body data is received (headers, padding, and other metadata do not affect the window). initial_window_size determines the starting size of each stream’s window. When a stream’s window reaches 0, no further data is received until update_window() is called. Default is False.
initial_window_size (Optional[int]) – The starting size of each stream’s flow-control window. Required if manual_window_management is True, ignored otherwise. Must be <= 2^31-1 or connection fails. If set to 0 with manual_window_management True, streams start with zero window. Required if manual_window_management is True, ignored otherwise.
read_buffer_capacity (Optional[int]) – Capacity in bytes of the HTTP/1.1 connection’s read buffer. The buffer grows when the flow-control window of the incoming stream reaches zero. Ignored if manual_window_management is False. A capacity that is too small may hinder throughput. A capacity that is too large may waste memory without improving throughput. If None or zero, a default value is used.

Returns:

concurrent.futures.Future – A Future which completes when connection succeeds or fails. If successful, the Future will contain a new HttpClientConnection. Otherwise, it will contain an exception.

request(request: HttpRequest, on_response: Callable[[...], None] | None = None, on_body: Callable[[...], None] | None = None) → HttpClientStream¶

Create HttpClientStream to carry out the request/response exchange.

NOTE: The HTTP stream sends no data until HttpClientStream.activate() is called. Call activate() when you’re ready for callbacks and events to fire.

Parameters:

request (HttpRequest) – Definition for outgoing request.
on_response –
Optional callback invoked once main response headers are received. The function should take the following arguments and return nothing:
- http_stream (HttpClientStream): HTTP stream carrying out this request/response exchange.
- status_code (int): Response status code.
- headers (List[Tuple[str, str]]): Response headers as a list of (name,value) pairs.
- **kwargs (dict): Forward compatibility kwargs.
An exception raise by this function will cause the HTTP stream to end in error. This callback is always invoked on the connection’s event-loop thread.
on_body –
Optional callback invoked 0+ times as response body data is received. The function should take the following arguments and return nothing:
- http_stream (HttpClientStream): HTTP stream carrying out this request/response exchange.
- chunk (buffer): Response body data (not necessarily a whole “chunk” of chunked encoding).
- **kwargs (dict): Forward-compatibility kwargs.
An exception raise by this function will cause the HTTP stream to end in error. This callback is always invoked on the connection’s event-loop thread.

Returns:

HttpClientStream

close() → concurrent.futures.Future¶

Close the connection.

Shutdown is asynchronous. This call has no effect if the connection is already closing.

Returns:: concurrent.futures.Future – This connection’s shutdown_future, which completes when shutdown has finished.

property host_name: str¶: Remote hostname

is_open() → bool¶

Returns:: bool – True if this connection is open and usable, False otherwise. Check shutdown_future to know when the connection is completely finished shutting down.

property port: int¶: Remote port

property shutdown_future: concurrent.futures.Future¶

Completes when this connection has finished shutting down. Future will contain a result of None, or an exception indicating why shutdown occurred. Note that the connection may have been garbage-collected before this future completes.

Type:: concurrent.futures.Future

property version: HttpVersion¶

Protocol used by this connection

Type:: HttpVersion

class awscrt.http.Http2ClientConnection¶

classmethod new(host_name: str, port: int, bootstrap: ClientBootstrap | None = None, socket_options: SocketOptions | None = None, tls_connection_options: TlsConnectionOptions | None = None, proxy_options: HttpProxyOptions | None = None, initial_settings: List[Http2Setting] | None = None, on_remote_settings_changed: Callable[[List[Http2Setting]], None] | None = None, manual_window_management: bool = False, initial_window_size: int | None = None, conn_manual_window_management: bool = False, conn_window_size_threshold: int | None = None, stream_window_size_threshold: int | None = None) → concurrent.futures.Future¶

Asynchronously establish an HTTP/2 client connection. Notes: to set up the connection, the server must support HTTP/2 and TlsConnectionOptions

This class extends HttpClientConnection with HTTP/2 specific functionality.

HTTP/2 specific args:

initial_settings (List[Http2Setting]): The initial settings to change for the connection.

on_remote_settings_changed: Optional callback invoked once the remote peer changes its settings.

And the settings are acknowledged by the local connection. The function should take the following arguments and return nothing:

settings (List[Http2Setting]): List of settings that were changed.

manual_window_management (bool): If True, enables manual flow control window management.

Default is False.

initial_window_size (Optional[int]): Initial window size for flow control.

Required if manual_window_management is True, ignored otherwise.

conn_manual_window_management (bool): If True, enables manual connection-level flow control

for the entire HTTP/2 connection. When enabled, the connection’s flow-control window shrinks as body data is received across all streams. The initial connection window is 65,535 bytes. When the window reaches 0, all streams stop receiving data until update_window() is called to increment the connection’s window. Note: Padding in DATA frames counts against the window, but window updates for padding are sent automatically even in manual mode. Default is False.

conn_window_size_threshold (Optional[int]): Threshold for sending connection-level WINDOW_UPDATE

frames. Ignored if conn_manual_window_management is False. When the connection’s window is above this threshold, WINDOW_UPDATE frames are batched. When it drops below, the update is sent. Default is 32,767 (half of the initial 65,535 window).

stream_window_size_threshold (Optional[int]): Threshold for sending stream-level WINDOW_UPDATE

frames. Ignored if manual_window_management is False. When a stream’s window is above this threshold, WINDOW_UPDATE frames are batched. When it drops below, the update is sent. Default is half of initial_window_size.

request(request: HttpRequest, on_response: Callable[[...], None] | None = None, on_body: Callable[[...], None] | None = None, manual_write: bool = False) → Http2ClientStream¶

Create Http2ClientStream to carry out the request/response exchange.

NOTE: The HTTP stream sends no data until Http2ClientStream.activate() is called. Call activate() when you’re ready for callbacks and events to fire.

Parameters:

request (HttpRequest) – Definition for outgoing request.
on_response –
Optional callback invoked once main response headers are received. The function should take the following arguments and return nothing:
- http_stream (Http2ClientStream): HTTP/2 stream carrying out this request/response exchange.
- status_code (int): Response status code.
- headers (List[Tuple[str, str]]): Response headers as a list of (name,value) pairs.
- **kwargs (dict): Forward compatibility kwargs.
on_body –
Optional callback invoked 0+ times as response body data is received. The function should take the following arguments and return nothing:
- http_stream (Http2ClientStream): HTTP/2 stream carrying out this request/response exchange.
- chunk (buffer): Response body data (not necessarily a whole “chunk” of chunked encoding).
- **kwargs (dict): Forward-compatibility kwargs.
manual_write (bool) – If True, enables manual data writing on the stream. This allows calling write_data() to stream the request body in chunks. Note: In the asyncio version, this is replaced by the async_body parameter.

Returns:

Http2ClientStream – Stream for the HTTP/2 request/response exchange.

close() → concurrent.futures.Future¶

Close the connection.

Shutdown is asynchronous. This call has no effect if the connection is already closing.

Returns:: concurrent.futures.Future – This connection’s shutdown_future, which completes when shutdown has finished.

update_window(increment_size: int) → None¶

Update the connection’s flow control window.

Parameters:: increment_size (int) – Number of bytes to increment the window by.

property host_name: str¶: Remote hostname

is_open() → bool¶

Returns:: bool – True if this connection is open and usable, False otherwise. Check shutdown_future to know when the connection is completely finished shutting down.

property port: int¶: Remote port

property shutdown_future: concurrent.futures.Future¶

Completes when this connection has finished shutting down. Future will contain a result of None, or an exception indicating why shutdown occurred. Note that the connection may have been garbage-collected before this future completes.

Type:: concurrent.futures.Future

property version: HttpVersion¶

Protocol used by this connection

Type:: HttpVersion

class awscrt.http.HttpClientStreamBase(connection, on_body: Callable[[...], None] | None = None)¶

Base for HTTP client stream classes.

connection¶: This stream’s connection.

completion_future¶: Future that completes when the request/response exchange is finished.

property version: HttpVersion¶

Protocol used by this stream

Type:: HttpVersion

property response_status_code: int | None¶

The response status code.

This is None until a response arrives.

Type:: int

update_window(increment_size: int) → None¶

Update the stream’s flow control window.

Parameters:: increment_size (int) – Number of bytes to increment the window by.

class awscrt.http.HttpClientStream(connection: HttpClientConnection, request: HttpRequest, on_response: Callable[[...], None] | None = None, on_body: Callable[[...], None] | None = None)¶

HTTP stream that sends a request and receives a response.

Create an HttpClientStream with HttpClientConnection.request().

NOTE: The HTTP stream sends no data until HttpClientStream.activate() is called. Call activate() when you’re ready for callbacks and events to fire.

connection¶

This stream’s connection.

Type:: HttpClientConnection

completion_future¶

Future that will contain the response status code (int) when the request/response exchange completes. If the exchange fails to complete, the Future will contain an exception indicating why it failed.

Type:: concurrent.futures.Future

activate() → None¶

Begin sending the request.

The HTTP stream does nothing until this is called. Call activate() when you are ready for its callbacks and events to fire.

property response_status_code: int | None¶

The response status code.

This is None until a response arrives.

Type:: int

update_window(increment_size: int) → None¶

Update the stream’s flow control window.

Parameters:: increment_size (int) – Number of bytes to increment the window by.

property version: HttpVersion¶

Protocol used by this stream

Type:: HttpVersion

class awscrt.http.Http2ClientStream(connection: HttpClientConnection, request: HttpRequest, on_response: Callable[[...], None] | None = None, on_body: Callable[[...], None] | None = None, manual_write: bool = False)¶

activate() → None¶

Begin sending the request.

The HTTP stream does nothing until this is called. Call activate() when you are ready for its callbacks and events to fire.

write_data(data_stream: InputStream | Any, end_stream: bool = False) → concurrent.futures.Future¶

Write a chunk of data to the request body stream.

This method is only available when the stream was created with manual_write=True. This allows incremental writing of request data.

Note: In the asyncio version, this is replaced by the request_body_generator parameter which accepts an async generator.

Parameters:

data_stream (Union[InputStream, Any]) – Data to write. If not an InputStream, it will be wrapped in one. Can be None to send an empty chunk.
end_stream (bool) – True to indicate this is the last chunk and no more data will be sent. False if more chunks will follow.

Returns:

concurrent.futures.Future –

Future that completes when the write operation: is done. The future will contain None on success, or an exception on failure.

property response_status_code: int | None¶

The response status code.

This is None until a response arrives.

Type:: int

update_window(increment_size: int) → None¶

Update the stream’s flow control window.

Parameters:: increment_size (int) – Number of bytes to increment the window by.

property version: HttpVersion¶

Protocol used by this stream

Type:: HttpVersion

class awscrt.http.HttpRequest(method: str = 'GET', path: str = '/', headers: HttpHeaders | None = None, body_stream: InputStream | Any | None = None)¶

Definition for an outgoing HTTP request.

The request may be transformed (ex: signing the request) before its data is eventually sent.

Parameters:

method (str) – HTTP request method (verb). Default value is “GET”.
path (str) – HTTP path-and-query value. Default value is “/”.
headers (Optional[HttpHeaders]) – Optional headers. If None specified, an empty HttpHeaders is created.
body_stream (Optional[Union[InputStream, io.IOBase]]) – Optional body as binary stream.

property method: str¶

HTTP request method (verb).

Type:: str

property path: str¶

HTTP path-and-query value.

Type:: str

property headers: HttpHeaders¶

Headers to send.

Type:: HttpHeaders

class awscrt.http.HttpHeaders(name_value_pairs: List[Tuple[str, str]] | None = None)¶

Collection of HTTP headers.

A given header name may have multiple values. Header names are always treated in a case-insensitive manner. HttpHeaders can be iterated over as (name,value) pairs.

Parameters:: name_value_pairs (Optional[List[Tuple[str, str]]]) – Construct from a collection of (name,value) pairs.

add(name: str, value: str) → None¶

Add a name-value pair.

Parameters:

name (str) – Name.
value (str) – Value.

add_pairs(name_value_pairs: List[Tuple[str, str]]) → None¶

Add list of (name,value) pairs.

Parameters:: name_value_pairs (List[Tuple[str, str]]) – List of (name,value) pairs.

set(name: str, value: str) → None¶

Set a name-value pair, any existing values for the name are removed.

Parameters:

name (str) – Name.
value (str) – Value.

get_values(name: str) → Iterator[str]¶

Return an iterator over the values for this name.

Parameters:: name (str) – Name.
Returns:: Iterator[str] – Iterator over values for this header name

get(name: str, default: str | None = None) → str | None¶

Get the first value for this name, ignoring any additional values. Returns default if no values exist.

Parameters:

name (str) – Name.
default (Optional[str]) – If name not found, this value is returned. Defaults to None.

Returns:

Optional[str] – Header value or default

remove(name: str) → None¶

Remove all values for this name. Raises a KeyError if name not found.

Parameters:: name (str) – Header name.

remove_value(name: str, value: str) → None¶

Remove a specific value for this name. Raises a ValueError if value not found.

Parameters:

name (str) – Name.
value (str) – Value.

clear() → None¶: Clear all headers.

class awscrt.http.HttpProxyConnectionType(value)¶

Proxy connection type enumeration

Legacy = 0¶

Use the old connection establishment logic that would use:

Forwarding if not using TLS
Tunneling if using TLS

Forwarding = 1¶

Establish a request forwarding connection to the proxy.

In this case, TLS is not a valid option.

Tunneling = 2¶: Establish a tunneling connection through the proxy to the ultimate endpoint.

class awscrt.http.HttpProxyAuthenticationType(value)¶

Proxy authentication type enumeration.

Nothing = 0¶: No authentication

Basic = 1¶: Username and password

class awscrt.http.HttpProxyOptions(host_name: str, port: int, tls_connection_options: TlsConnectionOptions | None = None, auth_type: HttpProxyAuthenticationType = HttpProxyAuthenticationType.Nothing, auth_username: str | None = None, auth_password: str | None = None, connection_type: HttpProxyConnectionType = HttpProxyConnectionType.Legacy)¶

Proxy options for HTTP clients.

Parameters:

host_name (str) – Name of the proxy server to connect through.
port (int) – Port number of the proxy server to connect through.
tls_connection_options (Optional[TlsConnectionOptions]) – Optional TlsConnectionOptions for the Local to Proxy connection. Must be distinct from the TlsConnectionOptions provided to the HTTP connection.
auth_type (HttpProxyAuthenticationType) – Type of proxy authentication to use. Default is HttpProxyAuthenticationType.Nothing.
auth_username (Optional[str]) – Username to use when auth_type is HttpProxyAuthenticationType.Basic.
auth_password (Optional[str]) – Username to use when auth_type is HttpProxyAuthenticationType.Basic.
connection_type (Optional[HttpProxyConnectionType) – Type of proxy connection to make. Default is HttpProxyConnectionType.Legacy.