Crate wtx 

WTX

A collection of different transport implementations and related tools focused primarily on web technologies. Features the in-house development of 8 IETF RFCs along side other elements.

Works on embedded devices with heap allocators. If you find this crate interesting, please consider giving it a star ⭐ on GitHub.

Specification	URL
gRPC	https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
HPACK	https://datatracker.ietf.org/doc/html/rfc7541
HTTP Cookies	https://datatracker.ietf.org/doc/html/rfc6265
HTTP/2	https://datatracker.ietf.org/doc/html/rfc9113
PostgreSQL	https://www.postgresql.org/docs/current/protocol.html
TLS 1.3 (soon)	https://datatracker.ietf.org/doc/html/rfc7301
WebSocket	https://datatracker.ietf.org/doc/html/rfc6455
WebSocket Compression	https://datatracker.ietf.org/doc/html/rfc7692
WebSocket over HTTP/2	https://datatracker.ietf.org/doc/html/rfc8441
X.509	https://datatracker.ietf.org/doc/html/rfc5280

Crypto Backend

Taking aside very few exceptions, WTX does not have built-in cryptographic algorithms, as such, it is necessary to select a backend when working with features that require them.

• crypto-aws-lc-rs
• crypto-graviola
• crypto-openssl
• crypto-ring

Calling methods will halt/panic the application if no backend is selected. These panicking branches will hopefully be erased by dead code analysis if the crypto feature is somehow active but never actually used.

In practice many things require cryptography algorithms. For example, PostgreSQL uses HMAC and secure HTTP cookies use AEAD.

Performance

Many things that generally improve performance are used in the project, to name a few:

1. Manual vectorization: When an algorithm is known for processing large amounts of data, several experiments are performed to analyze the best way to split loops in order to allow the compiler to take advantage of SIMD instructions in x86 processors.
2. Memory allocation: Whenever possible, all heap allocations are called only once at the start of an instance creation and additionally, stack memory usage is preferably prioritized over heap memory.
3. Fewer dependencies: No third-party is injected by default. In other words, additional dependencies are up to the user through the selection of Cargo features, which decreases compilation times. For example, you can see the mere 13 dependencies required by the PostgreSQL client using cargo tree -e normal --features postgres.

Since memory are usually held at the instance level instead of being created and dropped on the fly, its usage can growth significantly depending on the use-case. If appropriated, try using a shared pool of resources or try limiting how much data can be exchanged between parties.

High-level benchmarks

Checkout wtx-bench to see a variety of benchmarks or feel free to point any misunderstandings or misconfigurations.

There are mainly 2 things that impact performance, the chosen runtime and the number of pre-allocated bytes. Specially for servers that have to create a new instance for each handshake, pre-allocating a high number of bytes for short-lived or low-transfer connections can have a negative impact.

Low-level benchmarks

Anything marked with #[bench] in the repository is considered a low-level benchmark in the sense that they measure very specific operations that generally serve as the basis for other parts.

Take a look at https://bencher.dev/perf/wtx to see all low-level benchmarks over different periods of time.

Development benchmarks

These numbers provide an estimate of the expected waiting times when developing with WTX. If desired, you can compare them with other similar Rust projects through the dev-bench.sh script.

Technology	Required Deps 1	All Deps 2	Clean Check	Clean Debug Build	Clean Opt Build	Opt size
Client API Framework	0	31	6.42s	7.79s	8.45s	872K
gRPC Client	2	16	4.80s	6.04s	6.53s	736K
HTTP Client Pool	2	15	4.60s	5.84s	6.44s	728K
HTTP Server Framework	2	34	7.87s	10.53s	10.60s	996K
Postgres Client	13	26	5.12s	6.19s	6.69s	652K
WebSocket Client	10	22	4.24s	5.04s	5.31s	560K

Transport Layer Security (TLS)

When using a feature that requires network connection, it is often necessary to perform encrypted communication and since WTX is not hard-coded with a specific stream implementation, it is up to you to choose the best TLS provider.

Some utilities like TokioRustlsConnector or TokioRustlsAcceptor are available to make things more convenient but keep in mind that it is still necessary to activate a crate that provides certificates for client usage.

Examples

Demonstrations of different use-cases can be found in the wtx-examples directory as well as in the documentation.

Limitations

• Does not support systems with a pointer length of 16 bits.

• Expects the infallible sum of the lengths of an arbitrary number of slices, otherwise the program will likely trigger an overflow that can possibly result in unexpected operations. For example, in a 32bit system such a scenario should be viable without swap memory or through specific limiters like ulimit.

---

1. Internal dependencies required by the feature. ↩

2. The sum of optional and required dependencies used by the associated binaries. ↩

Modules

asn1asn1

Abstract Syntax Notation One (ASN.1)

calendar

Simple time utilities

client_api_frameworkclient-api-framework

A flexible client API framework for writing asynchronous, fast, organizable, scalable and maintainable applications.

codec

Decode/Encode

collection

Collection types

cryptocrypto

Algorithms that prevent third parties or the public from reading private messages.

databasedatabase

Client connection and schema management.

executorexecutor

Simple dependency-free runtime intended for tests, toy programs and demonstrations,

grpcgrpc

gRPC (gRPC Remote Procedure Calls) is a high performance remote procedure call (RPC) framework.

httphttp

Generic HTTP elements

http2http2

Low-level HTTP/2. You should probably look into higher abstractions like the HTTP server framework.

misc

Miscellaneous

pool

Pool Manager

rng

Random Number Generators

stream

Abstractions over different types of data streams.

sync

Synchronizing primitives

web_socketweb-socket

A computer communications protocol, providing full-duplex communication channels over a single TCP connection.

x509x509

Implementation of https://datatracker.ietf.org/doc/html/rfc5280.

Macros

create_enum

Implements a bunch of auxiliary methods for enums.

create_packages_aux_wrapperclient-api-framework

Useful to automatically create a local PkgsAux wrapper that implements core::ops::DerefMut in case you want to use a fluent-like interface for your APIs.

pathshttp and http-server-framework

Shortcut that avoids having to explicit import types related to paths.

Enums

Error

Grouped individual errors

RecvError

An error returned by the receiving part of a channel

SendError

An error returned by the sending part of a channel

Type Aliases

Result

Shortcut of core::result::Result<T, Error>.

Attribute Macros

apimacros

API

dbmacros

Allows the execution of asynchronous database tests using the runtime provided by WTX.

mainmacros

Allows the execution of asynchronous programs using the runtime provided by WTX.

pkgmacros

Package

testmacros

Allows the execution of asynchronous tests using the runtime provided by WTX.

Derive Macros

ConnAuxmacros

Connection Auxiliary

FromRecordsmacros

From records

FromVarsmacros

Implements the FromVars trait.

Tablemacros

Generates table fields separated by commas