index.nct

//! Authenticated TLS client byte streams.
//!
//! `TlsStream` uses the operating system trust store, verifies the requested server name, requires
//! TLS 1.2 or newer, and preserves the same unique stream ownership and timeout model as TCP.

use /io.{BlockingReader, BlockingWriter, Reader, TimedReader, TimedWriter, Writer}
use /net.{SocketAddress, TcpShutdown}
use /time.Duration
see ./trust_anchor.nct
see ./stream.nct
see ./async_stream.nct

/// One uniquely owned authenticated TLS client byte stream.
pub struct TlsStream

/// One owned DER certificate added to, rather than substituted for, the system trust store.
pub struct TrustAnchor

construct TrustAnchor {
    /// Copies one non-empty DER-encoded X.509 certificate.
    pub func from_der(certificate: &[u8]): Self!
}

instance TrustAnchor {
    pub(/) noalloc method &self.bytes(): &[u8] from self
}

construct TlsStream {
    /// Resolves `host` and connects to the first authenticated address in system order.
    pub blocking func connect_blocking(host: &str, port: u16): Self!

    /// Resolves and authenticates candidates without restarting `timeout` for each address.
    pub blocking func connect_with_timeout_blocking(
        host: &str,
        port: u16,
        timeout: Duration,
    ): Self!

    /// Authenticates with the system trust store plus one caller-supplied root certificate.
    pub blocking func connect_with_trust_anchor_blocking(
        host: &str,
        port: u16,
        trust_anchor: &TrustAnchor,
    ): Self!

    /// Authenticates with an additional root without restarting the fixed timeout per address.
    pub blocking func connect_with_trust_anchor_and_timeout_blocking(
        host: &str,
        port: u16,
        trust_anchor: &TrustAnchor,
        timeout: Duration,
    ): Self!
}

/// Validates, resolves, and authenticates one host while the future is driven.
pub async func connect(host: &str, port: u16): TlsStream!

/// Resolves and authenticates through the provider before one future-owned fixed timeout.
pub async func connect_with_timeout(
    host: &str,
    port: u16,
    timeout: Duration,
): TlsStream!

/// Resolves and authenticates asynchronously with one retained additional root.
pub async func connect_with_trust_anchor(
    host: &str,
    port: u16,
    trust_anchor: &TrustAnchor,
): TlsStream!

/// Authenticates asynchronously with an additional root before one fixed timeout.
pub async func connect_with_trust_anchor_and_timeout(
    host: &str,
    port: u16,
    trust_anchor: &TrustAnchor,
    timeout: Duration,
): TlsStream!

/// Opens one package-internal TLS stream that requires negotiated HTTP/1.1.
pub(/) blocking func connect_http1_blocking(host: &str, port: u16): TlsStream!

/// Opens one package-internal HTTP/1.1 TLS stream before a fixed timeout.
pub(/) blocking func connect_http1_with_timeout_blocking(
    host: &str,
    port: u16,
    timeout: Duration,
): TlsStream!

/// Opens one package-internal HTTP/1.1 stream with an additional trust root.
pub(/) blocking func connect_http1_with_trust_anchor_blocking(
    host: &str,
    port: u16,
    trust_anchor: &TrustAnchor,
): TlsStream!

/// Opens one package-internal custom-trust HTTP/1.1 stream before a fixed timeout.
pub(/) blocking func connect_http1_with_trust_anchor_and_timeout_blocking(
    host: &str,
    port: u16,
    trust_anchor: &TrustAnchor,
    timeout: Duration,
): TlsStream!

/// Validates, resolves, and opens one package-internal HTTP/1.1 TLS stream asynchronously.
pub(/) async func connect_http1(host: &str, port: u16): TlsStream!

/// Resolves and authenticates HTTP/1.1 TLS before a future-owned fixed timeout.
pub(/) async func connect_http1_with_timeout(
    host: &str,
    port: u16,
    timeout: Duration,
): TlsStream!

/// Returns one package-internal HTTP/1.1 computation with an additional trust root.
pub(/) async func connect_http1_with_trust_anchor(
    host: &str,
    port: u16,
    trust_anchor: &TrustAnchor,
): TlsStream!

/// Returns one custom-trust HTTP/1.1 computation bounded by a fixed timeout.
pub(/) async func connect_http1_with_trust_anchor_and_timeout(
    host: &str,
    port: u16,
    trust_anchor: &TrustAnchor,
    timeout: Duration,
): TlsStream!

instance TlsStream {
    impl BlockingReader
    impl BlockingWriter
    impl Reader
    impl TimedReader
    impl TimedWriter
    impl Writer

    /// Returns the effective local socket address.
    pub noalloc method &self.local_address(): SocketAddress!

    /// Returns the authenticated peer socket address.
    pub noalloc method &self.peer_address(): SocketAddress!

    /// Replaces the read timeout; absence permits an unlimited wait.
    pub noalloc method &+self.set_read_timeout(timeout: Duration?): void

    /// Returns the configured read timeout.
    pub noalloc method &self.read_timeout(): Duration?

    /// Replaces the write timeout; absence permits an unlimited wait.
    pub noalloc method &+self.set_write_timeout(timeout: Duration?): void

    /// Returns the configured write timeout.
    pub noalloc method &self.write_timeout(): Duration?

    /// Shuts down selected local stream directions.
    pub noalloc blocking method &+self.shutdown(direction: TcpShutdown): void!

    /// Cancels provider progress and releases the stream exactly once.
    pub noalloc method &+self.close(): void

    /// Reads one decrypted provider chunk without blocking the executor thread.
    pub async method &+self.read(buffer: &+[u8]): usize!

    /// Reads asynchronously until the fixed relative timeout expires.
    pub async method &+self.read_with_timeout(
        buffer: &+[u8],
        timeout: Duration,
    ): usize!

    /// Sends the complete plaintext view without blocking the executor thread.
    pub async method &+self.write(bytes: &[u8]): void!

    /// Sends asynchronously until completion or the fixed relative timeout expires.
    pub async method &+self.write_with_timeout(
        bytes: &[u8],
        timeout: Duration,
    ): void!
}