wasat.client

Gemini and Titan 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__(
    exception_type: object,
    exception_value: object,
    exception_traceback: 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.

delete `async`

delete(
    uri: str | AnyURI, *, token: str | None = None
) -> Response

Delete a resource via the Titan protocol by uploading zero bytes (size=0).

Parameters:

Name	Type	Description	Default
`uri`	`str \| AnyURI`	The target URI as a string, GeminiURI, or TitanURI.	required
`token`	`str \| None`	Optional authorisation token.	`None`

Returns:

Type	Description
`Response`	The final Response object.

edit `async`

edit(uri: str | AnyURI) -> Response

Request the raw content of a resource for editing using the Titan edit extension.

Sends a Titan request with the ';edit' parameter to lock the resource (if supported by the server) and retrieve its raw unrendered content.

Note

The Titan edit parameter is a proposed extension to the Titan specification designed for collaborative editing and raw content retrieval. It is supported by various Gemini and Titan servers.

Parameters:

Name	Type	Description	Default
`uri`	`str \| AnyURI`	The target URI as a string, GeminiURI, or TitanURI.	required

Returns:

Type	Description
`Response`	A Response instance containing the raw content for editing.

Raises:

Type	Description
`URIError`	If the URI is invalid.
`ConnectionError`	If network connection fails or times out.
`SecurityError`	If TLS or certificate validation fails.
`ProtocolError`	If the server response violates the 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.

request `async`

request(uri: str | AnyURI) -> Response

Perform a Gemini or Titan request and return the response.

Automatically handles redirection if configured.

Parameters:

Name	Type	Description	Default
`uri`	`str \| AnyURI`	The target URI as a string, GeminiURI, or TitanURI object.	required

Returns:

Type	Description
`Response`	The final 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 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.

upload `async`

upload(
    uri: str | GeminiURI | TitanURI,
    data: bytes
    | str
    | Path
    | AsyncIterator[bytes]
    | BinaryIO,
    *,
    mime: str | None = None,
    token: str | None = None,
) -> Response

Upload data to a Titan endpoint.

Parameters:

Name	Type	Description	Default
`uri`	`str \| GeminiURI \| TitanURI`	The target URI as a string, GeminiURI, or TitanURI.	required
`data`	`bytes \| str \| Path \| AsyncIterator[bytes] \| BinaryIO`	The content to upload. Can be raw bytes, a UTF-8 string, a Path, an async byte iterator, or a file-like stream.	required
`mime`	`str \| None`	The MIME type of the payload. If None, it is automatically inferred.	`None`
`token`	`str \| None`	Optional authorization token for the Titan transaction.	`None`

Returns:

Type	Description
`Response`	A Response instance representing the server's response.

Raises:

Type	Description
`URIError`	If the URI is invalid or cannot be converted to a Titan URI.
`ConnectionError`	If connection establishment fails.
`SecurityError`	If TLS or certificate validation fails.
`ProtocolError`	If the server response violates the protocol.
`RedirectError`	If redirect limits are exceeded or loops are detected.
`TypeError`	If the provided data type is unsupported.

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(size: int = -1) -> bytes

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

Parameters:

Name	Type	Description	Default
`size`	`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.

wasat.client

NewCertCallback

VerifyMode

Client

verify_mode

trust_store

trust_store_path

client_cert

client_key

client_cert_store

client_cert_store_path

on_client_certificate_required

on_new_certificate

follow_redirects

max_redirects

connect_timeout

read_timeout

ssl_context

client_cert_store property

trust_store property

__aenter__ async

__aexit__ async

close async

delete async

uri

token

edit async

uri

request async

uri

upload async

uri

data

mime

token

WrappedStreamReader

reader

writer

close async

read async

size

`verify_mode`

`trust_store`

`trust_store_path`

`client_cert`

`client_key`

`client_cert_store`

`client_cert_store_path`

`on_client_certificate_required`

`on_new_certificate`

`follow_redirects`

`max_redirects`

`connect_timeout`

`read_timeout`

`ssl_context`

client_cert_store `property`

trust_store `property`

aenter `async`

aexit `async`

close `async`

delete `async`

`uri`

`token`

edit `async`

`uri`

request `async`

`uri`

upload `async`

`uri`

`data`

`mime`

`token`

`reader`

`writer`

close `async`

read `async`

`size`