open-net
This README and the linked integration guides cover open-net 0.3.3. See installation and version compatibility for setup and the API and privacy changes from 0.3.2.
Overview
open-net is an asynchronous networking library for Rust applications. It provides
NetStatusClient for observing network state, HttpClient for HTTP requests and
responses, and WebSocketClient for persistent WebSocket connections. OpenNet
manages named clients and shared engine resources. HTTP clients can also be
constructed independently with HttpClient::new.
Reuse open-net's HTTP and WebSocket clients, network status subscriptions, configurable retry policies, WebSocket reconnection and heartbeats, and client lifecycle management across applications. These shared capabilities let you focus on business logic while avoiding repeated implementation and debugging of common networking infrastructure.
For AI-assisted development, this reuse is designed to save development time and AI coding tokens by reducing the amount of networking code that needs to be generated, reviewed, and debugged for each project. Enable the Cargo features your application needs and configure retry and connection policies for its requirements; see the feature table and integration guides below.
Supported Platforms
| Platform | Support scope |
|---|---|
| macOS | Native desktop applications |
| Windows | Native desktop applications |
| Ubuntu | Linux kernel 5.0 or later |
Cargo Features
| Capability | Minimum feature | Automatically enables / additional requirements |
|---|---|---|
| Engine, basic configuration, logging, errors, shared subscription types | None | Available with default-features = false |
| Shared retry schedules, built-in backoff, jitter and reports | None | Import from open_net::api::retry; transport policies remain protocol-specific |
| Passive HTTP/WS phase diagnostics | quality-doctor |
Default Off; explicit accessor activates bounded storage lazily; does not enable transports. See QualityDoctor. |
| Network monitoring, snapshots, IPv4/IPv6 capability, state subscriptions and ordered events | net-status |
Create a named NetStatusClient through OpenNet |
| Recoverable event callbacks | net-status |
Stable subscription identity; queue overflow reconciles to a new atomic baseline |
| On-demand network observation | net-status |
Windows; async and blocking reachability refresh, with cached IP-stack capability; no network-name collection |
| Explicit network-name observation | net-status |
NetworkNameObserver; Windows only, separately owned and explicitly requested |
| LAN IPv4 candidates and evidence-based recommendation | net-status |
network::lan_ipv4_snapshot() or NetStatusClient::query_lan_ipv4(); fresh synchronous OS query |
| Subnet-based LAN IPv4 selection | net-status |
network::preferred_lan_ipv4() ranks candidates by subnet priority |
| WebSocket client | ws-client |
Default; enables net-status; select a TLS provider separately |
| HTTP/HTTPS, GET/POST, custom methods, headers, byte request bodies | http-client |
Enables net-status; import from open_net::api::http |
| Lazy named HTTP clients and shared shutdown | http-client |
OpenNet::managed_http; fixed configuration with SDK-owned initialization and cleanup |
| Buffered responses, text/JSON parsing, explicit HTTP status checks | http-client |
JSON response parsing does not require codecs |
| Streaming response bytes and raw SSE bytes | http-client |
No SSE event parser is included |
| Custom request traits, callback submission, completion handles | http-client |
No extra feature |
| Timeouts, retries, admission capacity, cancellation, shutdown | http-client |
No separate timeout or retry feature |
| HTTP proxy, custom root certificates, mutual TLS | http-client |
Use HTTP-specific proxy and TLS configuration |
| HTTP network snapshots and subscriptions | http-client |
Standalone clients require a supplied network context for observation |
| Query, JSON, form, multipart request encoding | http-client-codecs |
Enables http-client; manual body bytes need no codecs |
| Cookie storage, limits, persistence snapshots | http-client-cookies |
Enables http-client; also install a cookie store |
| HTTP/2, version policy, flow control | http-client-http2 |
Enables http-client; Http2Only requires HTTPS for the initial URL and redirect targets, with no HTTP/1 fallback |
| HTTP middleware | http-client-middleware |
Enables http-client; concrete buffered/streaming requests, not trait send* |
| Basic/Bearer auth, asynchronous providers, token refresh | http-client-auth |
Enables http-client; manually setting Authorization needs no auth feature |
The default feature is ws-client, which also enables net-status. Adding
features = ["http-client"] keeps that default WebSocket feature enabled. For an
HTTP-only dependency, use default-features = false, features = ["http-client"].
For network monitoring alone, use
default-features = false, features = ["net-status"].
ws-client and http-client use rustls without bundling or selecting a
cryptographic provider. Supply a compatible rustls 0.23 CryptoProvider
explicitly or install one in the host application before client creation.
A missing provider returns InvalidConfig for tls.provider
when the client is built, including clients intended for plain HTTP or WS.
With ws-client enabled, OpenNet also compiles its default WebSocket connector
during engine construction, so supply the engine's provider before that step.
See TLS providers for complete examples and provider-specific build
requirements. open-net does not enable AWS-LC or ring, or depend on OpenSSL in
production. There are no built-in provider features.
Cargo features are additive: another dependency can enable a feature even when
one declaration disables defaults, including rustls's AWS-LC or ring features.
This library has no features named http,
json, sse, retry, or tls.
Using this library from your application
Start with Rust 1.89 or later and create a consumer with cargo new my-app.
For an HTTP-only application, add the dependency from your application's directory:
The guides below use version = "0.3.3". When upgrading from 0.3.2, follow the
retry and privacy migration instructions; the new APIs and behavior described
here must not be assumed when using the older version.
For Git integration, use a verified tag or commit from the official repository. The installation guide explains how to choose the matching source version. Add each example's application dependencies, such as Tokio and a TLS provider; the library's development dependencies are not automatically available to your application.
Integration Guides
- Installation, version compatibility and example privacy
- Engine and client lifecycle
- Logging, subscriptions and drop statistics
- NetStatusClient
- LAN IPv4 candidates and selection
- TLS providers, OpenSSL setup and custom cryptography
- Shared retry schedules and observations
- HttpClient: installation and first request
- Network-name observation and privacy migration
- WebSocketClient
- WebSocket HTTPS proxies and authentication migration
- Third-Party Dependencies
Engine shutdown
Use OpenNet::begin_shutdown() to request permanent shutdown synchronously,
including from SDK callbacks. Await OpenNet::shutdown() from an external
control flow to confirm that the engine's owned workers, registered clients,
monitoring and callbacks/providers have retired. Cancelling or timing out the
wait leaves cleanup running. No caller Tokio runtime is required for this wait.
Standalone HTTP workers, other engines, process-wide log subscriptions and application-created tasks have separate owners. Drop initiates cleanup but does not confirm completion. See engine and client lifecycle for a comparison of shutdown APIs, callback restrictions and complete examples.