Crate tor_rtcompat

tor-rtcompat

Compatibility between different async runtimes for Arti.

Overview

Rust’s support for asynchronous programming is powerful, but still a bit immature: there are multiple powerful runtimes you can use, but they do not expose a consistent set of interfaces.

The [futures] API abstracts much of the differences among these runtime libraries, but there are still areas where no standard API yet exists, including:

• Network programming.
• Time and delays.
• Launching new tasks
• Blocking until a task is finished.

Additionally, the AsyncRead and AsyncWrite traits provide by [futures] are not the same as those provided by tokio, and require compatibility wrappers to use.

To solve these problems, the tor-rtcompat crate provides a set of traits that represent a runtime’s ability to perform these tasks, along with implementations for these traits for the tokio and async-std runtimes. In the future we hope to add support for other runtimes as needed.

This crate is part of Arti, a project to implement Tor in Rust. As such, it does not currently include (or plan to include) any functionality beyond what Arti needs to implement Tor.

We hope that in the future this crate can be replaced (or mostly replaced) with standardized and general-purpose versions of the traits it provides.

Using tor-rtcompat

The tor-rtcompat crate provides several traits that encapsulate different runtime capabilities.

• A runtime is a BlockOn if it can block on a future.
• A runtime is a SleepProvider if it can make timer futures that become Ready after a given interval of time.
• A runtime is a CoarseTimeProvider if it provides a monotonic clock which is fast to query, but perhaps has lower-precision or lower-accuracy.
• A runtime is a NetStreamProvider<std::net::SocketAddr> if it can make and receive TCP connections
• A runtime is a TlsProvider if it can make TLS connections.

For convenience, the Runtime trait derives from all the traits above, plus [futures::task::Spawn] and Send.

You can get a Runtime in several ways:

• If you already have an asynchronous backend (for example, one that you built with tokio by running with #[tokio::main]), you can wrap it as a Runtime with PreferredRuntime::current().

• If you want to construct a default runtime that you won’t be using for anything besides Arti, you can use PreferredRuntime::create().

Both of the above methods use the “preferred runtime”, which is usually Tokio. However, changing the set of Cargo features available can affect this; see PreferredRuntime for more.

• If you want to use a runtime with an explicitly chosen backend, name its type directly as async_std::AsyncStdNativeTlsRuntime, async_std::AsyncStdRustlsRuntime, tokio::TokioNativeTlsRuntime, or tokio::TokioRustlsRuntime. To construct one of these runtimes, call its create() method. Or if you have already constructed a Tokio runtime that you want to use, you can wrap it as a Runtime explicitly with current().

Advanced usage: implementing runtimes yourself

You might want to implement some of the traits above (especially NetStreamProvider and TlsProvider) if you’re embedding Arti, and want more control over the resources it uses. For example, you might want to perform actions when TCP connections open and close, replace the TLS stack with your own, or proxy TCP connections over your own custom transport.

This can be more easily accomplished using the CompoundRuntime type, which lets you create a Runtime from various implementors of the various traits (which don’t all need to be the same).

See arti-client/examples/hook-tcp.rs for a full example of this.

Cargo features

Features supported by this crate:

• tokio – build with Tokio support
• async-std – build with async-std support
• native-tls – build with the native-tls crate for TLS support
• static – link the native TLS library statically (enables the vendored feature of the native-tls crate).
• rustls – build with the rustls crate for TLS support. Note that rustls uses the ring crate, which uses the old (3BSD/SSLEay) OpenSSL license, which may introduce licensing compatibility issues.

By default, this crate doesn’t enable any features. However, you’re almost certainly using this as part of the arti-client crate, which will enable tokio and native-tls in its default configuration.

Design FAQ

Why support async_std?

Although Tokio currently a more popular and widely supported asynchronous runtime than async_std is, we believe that it’s critical to build Arti against multiple runtimes.

By supporting multiple runtimes, we avoid making tokio-specific assumptions in our code, which we hope will make it easier to port to other environments (like WASM) in the future.

Why a Runtime trait, and not a set of functions?

We could simplify this code significantly by removing most of the traits it exposes, and instead just exposing a single implementation. For example, instead of exposing a BlockOn trait to represent blocking until a task is done, we could just provide a single global block_on function.

That simplification would come at a cost, however. First of all, it would make it harder for us to use Rust’s “feature” system correctly. Current features are supposed to be additive only, but if had a single global runtime, then support for different backends would be mutually exclusive. (That is, you couldn’t have both the tokio and async-std features building at the same time.)

Secondly, much of our testing in the rest of Arti relies on the ability to replace Runtimes. By treating a runtime as an object, we can override a runtime’s view of time, or of the network, in order to test asynchronous code effectively. (See the [tor-rtmock] crate for examples.)

License: MIT OR Apache-2.0

Modules

• async_std(native-tls or rustls) and async-std
  Entry points for use with async_std runtimes.
• general
  Support for streams and listeners on general::SocketAddr.
• scheduler
  Utilities for dealing with periodic recurring tasks.
• task
  Functions for task management that don’t belong inside the Runtime trait.
• tls
  Traits used to describe TLS connections and objects that can create them.
• tokio(native-tls or rustls) and tokio
  Entry points for use with Tokio runtimes.
• unimpl
  Implementations for unsupported stream and listener types.
• unix
  Functionality for working with Unix addresses.

Macros

• test_with_all_runtimes(native-tls or rustls) and (tokio or async-std)
  Run a test closure, passing as argument every supported runtime.
• test_with_one_runtime(native-tls or rustls) and (tokio or async-std)
  Run a test closure, passing as argument one supported runtime.

Structs

• CoarseDuration
  A duration with reduced precision, and, in the future, saturating arithmetic
• CoarseInstant
  A monotonic timestamp with reduced precision, and, in the future, saturating arithmetic
• CompoundRuntime
  A runtime made of several parts, each of which implements one trait-group.
• DynTimeProvider
  Type-erased SleepProvider and CoarseTimeProvider
• NoOpStreamOpsHandle
  A StreamOps handle that always returns an error.
• PreferredRuntime(native-tls or rustls) and (async-std or tokio)
  The runtime that we prefer to use, out of all the runtimes compiled into the tor-rtcompat crate.
• RealCoarseTimeProvider
  Provider of reduced-precision timestamps using the real OS clock
• Timeout
  A timeout returned by SleepProviderExt::timeout.
• TimeoutError
  An error value given when a function times out.
• UnsupportedStreamOp
  Error: Tried to perform a StreamOps operation on an unsupported stream type or on an unsupported platform.

Traits

• BlockOn
  Trait for a runtime that can block on a future.
• CertifiedConn
  An object with a peer certificate: typically a TLS connection.
• CoarseTimeProvider
  A provider of reduced-precision timestamps
• NetStreamListener
  Trait for a local socket that accepts incoming streams.
• NetStreamProvider
  Trait for a runtime that can create and accept connections over network sockets.
• Runtime
  A runtime that we can use to run Tor as a client.
• RuntimeSubstExt
  Extension trait on Runtime: Construct new Runtimes that replace part of an original runtime.
• SleepProvider
  Trait for a runtime that can wait until a timer has expired.
• SleepProviderExt
  An extension trait on SleepProvider for timeouts and clock delays.
• SpawnBlocking
  Trait to run a task on a threadpool for blocking tasks
• StreamOps
  Trait providing additional operations on network sockets.
• TlsProvider
  Trait for a runtime that knows how to create TLS connections over TCP streams of type S.
• UdpProvider
  Trait for a runtime that can send and receive UDP datagrams.
• UdpSocket
  Trait for a locally bound Udp socket that can send and receive datagrams.