wasat.client

Gemini Protocol async client implementation.

NewCertCallback

NewCertCallback = Callable[
    [str, int, str], Coroutine[None, None, bool]
]

Async callback function signature for verifying a new certificate.

VerifyMode

VerifyMode = Literal['ca', 'tofu', 'off', 'hybrid']

Type alias for the certificate verification mode.

Client

Client(
    *,
    verify_mode: VerifyMode = "ca",
    trust_store: TrustStore | None = None,
    trust_store_path: str | Path | None = None,
    client_cert: str | Path | None = None,
    client_key: str | Path | None = None,
    client_cert_store: ClientCertificateStore | None = None,
    client_cert_store_path: str | Path | None = None,
    on_client_certificate_required: ClientCertCallback
    | None = None,
    on_new_certificate: NewCertCallback | None = None,
    follow_redirects: bool = True,
    max_redirects: int = 5,
    connect_timeout: float = 10.0,
    read_timeout: float = 30.0,
    ssl_context: SSLContext | None = None,
)

Asynchronous Gemini Protocol Client.

Parameters:

Name	Type	Description	Default
verify_mode	VerifyMode	The certificate verification mode: - 'ca': Trust certificates signed by system CAs. - 'tofu': Trust-On-First-Use validation. - 'off': Disable certificate verification (insecure). - 'hybrid': Combine CA validation with TOFU fallback (falls back to TOFU only for untrusted root or self-signed certificates; raises SecurityError for expired certs or hostname mismatches).	'ca'
trust_store	TrustStore | None	Custom TrustStore instance for TOFU mode.	None
trust_store_path	str | Path | None	Filepath for the default FileTrustStore in TOFU mode.	None
client_cert	str | Path | None	Path to client TLS certificate (for client auth).	None
client_key	str | Path | None	Path to client TLS private key (optional if in cert file).	None
client_cert_store	ClientCertificateStore | None	Custom ClientCertificateStore instance.	None
client_cert_store_path	str | Path | None	Directory path for the default FileClientCertificateStore.	None
on_client_certificate_required	ClientCertCallback | None	Async callback invoked when client certificate is required (status code 60). Returns 'transient', 'persistent' or 'ignore'.	None
on_new_certificate	NewCertCallback | None	Async callback called when a new certificate is encountered in TOFU mode. Must return True to accept, False to reject.	None
follow_redirects	bool	If True, automatically follow redirects.	True
max_redirects	int	Maximum number of redirects to follow.	5
connect_timeout	float	Timeout in seconds for establishing a connection.	10.0
read_timeout	float	Timeout in seconds for reading the response line.	30.0
ssl_context	SSLContext | None	Pre-configured ssl.SSLContext. Overrides verify_mode/cert config.	None

client_cert_store property

client_cert_store: ClientCertificateStore

The client certificate store used by this client.

Returns:

Type	Description
ClientCertificateStore	The client certificate store instance.

trust_store property

trust_store: TrustStore | None

The trust store used by this client for TOFU verification.

This will be None if not in TOFU mode.

__aenter__ async

__aenter__() -> Self

Enter the async context manager.

Returns:

Type	Description
Self	The Client instance.

__aexit__ async

__aexit__(
    exc_type: object, exc_val: object, exc_tb: object
) -> None

Exit the async context manager, closing resources.

close async

close() -> None

Close the client and clean up resources, including the client certificate store.

request async

request(uri: str | GeminiURI) -> Response

Perform a Gemini request and return the response.

Automatically handles redirection if configured.

Parameters:

Name	Type	Description	Default
uri	str | GeminiURI	The target URI as a string or GeminiURI object.	required

Returns:

Type	Description
Response	The final Gemini Response object.

Raises:

Type	Description
URIError	If the URI is invalid.
ConnectionError	If network connection fails or times out.
SecurityError	If TLS/certificate check fails.
ProtocolError	If the server response violates the Gemini protocol.
RedirectError	If redirect limits are exceeded or loops are detected.
ValueError	If client certificate generation parameters are invalid.
OSError	If creating directories or writing client certificate files fails.
RuntimeError	If saving the updated client certificate store index fails.

WrappedStreamReader

WrappedStreamReader(
    reader: StreamReader, writer: StreamWriter
)

Wraps StreamReader to ensure the StreamWriter is closed upon reaching EOF or on error.

Parameters:

Name	Type	Description	Default
reader	StreamReader	The stream reader to wrap.	required
writer	StreamWriter	The stream writer to close on EOF or error.	required

close async

close() -> None

Close the writer transport.

read async

read(n: int = -1) -> bytes

Read data from the stream, closing the connection at EOF.

Parameters:

Name	Type	Description	Default
n	int	Number of bytes to read, or -1 to read until EOF.	-1

Returns:

Type	Description
bytes	The read bytes.

Raises:

Type	Description
Exception	Any exception raised by the underlying reader.