Crate gel_stream

Expand description

§gel-stream

This crate provides a runtime and TLS agnostic client and server stream API for services requiring TCP/Unix socket, plaintext, TLS, and STARTTLS connections.

The crate may be used with either an OpenSSL or Rustls TLS implementation without changing the API.

§Features

full: Enable all features (not recommended).
openssl: Enable OpenSSL support.
rustls: Enable Rustls support.
tokio: Enable Tokio support (default).
hickory: Enable Hickory support.
keepalive: Enable keepalive support.
serde: Enable serde serialization support for most types.
pem: Enable PEM support for TLS parameters.

§TLS

TLS is supported via the openssl or rustls features. Regardless of which TLS library is used, the API is the same.

§Usage

The crate provides a Target and Connector for clients and a Acceptor for servers.

§Examples

Creating and connecting to a TCP server:

use gel_stream::*;
use std::net::*;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use futures::TryStreamExt;

#[tokio::main]
async fn run() -> Result<(), Box<dyn std::error::Error>> {
    // Create a server that listens on all interfaces on a random port.
    let acceptor = Acceptor::new_tcp(SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0));
    let mut server = acceptor.bind().await?;
    let addr = server.local_address()?;

    /// When creating servers, clients and servers should be run in separate tasks.
    let task1 = tokio::spawn(async move {
        let mut server_conn = server.try_next().await?.expect("Didn't get a connection");
        server_conn.write_all(b"Hello, world!").await?;
        std::io::Result::Ok(())
    });

    let task2 = tokio::spawn(async move {
        let mut client_conn = Connector::new(Target::new_resolved(addr))?.connect().await?;
        let mut buffer = String::new();
        client_conn.read_to_string(&mut buffer).await?;
        assert_eq!(buffer, "Hello, world!");
        std::io::Result::Ok(())
    });

    task1.await??;
    task2.await??;

    Ok(())
}

Creating a TLS server with a given key and certificate, and connecting to it:

use gel_stream::*;
use std::net::*;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use futures::TryStreamExt;

#[tokio::main]
async fn run() -> Result<(), Box<dyn std::error::Error>> {
    // Create a server that listens on all interfaces on a random port.
    let tls_params = TlsServerParameters::new_with_certificate(
        gel_stream::test_keys::SERVER_KEY.clone_key()
    );
    let acceptor = Acceptor::new_tcp_tls(
        SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
        TlsServerParameterProvider::new(tls_params),
    );
    let mut server = acceptor.bind().await?;
    let addr = server.local_address()?;

    /// When creating servers, clients and servers should be run in separate tasks.
    let task1 = tokio::spawn(async move {
        let mut server_conn = server.try_next().await?.expect("Didn't get a connection");
        server_conn.write_all(b"Hello, world!").await?;
        std::io::Result::Ok(())
    });

    let task2 = tokio::spawn(async move {
        let mut client_conn = Connector::new(Target::new_resolved_tls(addr, TlsParameters::insecure()))?.connect().await?;
        let mut buffer = String::new();
        client_conn.read_to_string(&mut buffer).await?;
        assert_eq!(buffer, "Hello, world!");
        std::io::Result::Ok(())
    });

    task1.await??;
    task2.await??;

    Ok(())
}

Re-exports§

pub use rustls_pki_types as pki_types;

Structs§

Acceptor
Connector: A connector can be used to connect multiple times to the same target.
NullTlsDriver: A TLS driver that fails when TLS is requested.
OpensslDriver
Preview: A preview of the initial bytes of the stream.
PreviewConfiguration: Configuration for the initial preview of the client connection.
ResolveResult: The result of a resolution. It may be synchronous or asynchronous, but you can always call .await on it.
Resolver: An async resolver for hostnames to IP addresses.
RustlsDriver
SslVersionParseError
Target: A target describes the TCP or Unix socket that a client will connect to, along with any optional TLS parameters.
TargetName: A target name describes the TCP or Unix socket that a client will connect to.
TlsAlpn
TlsHandshake: Negotiated TLS handshake information.
TlsKey
TlsParameters
TlsServerParameterProvider
TlsServerParameters
UpgradableStream

Enums§

BulkStreamDirection
CommonError
ConnectionError
ResolvedTarget: The resolved target of a connection attempt.
SslError
SslVersion
StreamOptimization
TlsCert
TlsClientCertVerify
TlsServerCertVerify: Verification modes for TLS that are a superset of both PostgreSQL and EdgeDB/Gel.
Transport: The transport of a stream.

Constants§

DEFAULT_PREVIEW_BUFFER_SIZE: The default preview buffer size for the server.
DEFAULT_TCP_BACKLOG: The default TCP backlog for the server.
DEFAULT_TLS_BACKLOG: The default TLS backlog for the server.

Traits§

AsHandle: A trait for streams that can be converted to a handle or file descriptor.
LocalAddress: A trait for types that have a local address.
PeekableStream: A trait for streams that can be peeked asynchronously.
PeerCred
RemoteAddress: A trait for types that have a local address.
Resolvable: A trait for types that can be resolved to a target.
Rewindable
Stream: A convenience trait for streams from this crate.
StreamMetadata: A trait for stream metadata.
StreamOptimizationExt
StreamUpgrade: A trait for streams that can be upgraded to a TLS stream.

Type Aliases§

RawStream
Ssl
TlsServerParameterLookupFn: A function that looks up TLS server parameters based on the server name and/or stream metadata.

Crate gel_streamCopy item path