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.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) → 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.

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.

property host_name: str¶: Remote hostname

property port: int¶: Remote port

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.

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.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) → 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.

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

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.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

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

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.

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.

property response_status_code: int | None¶

The response status code.

This is None until a response arrives.

Type:: int

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.