open-net 0.3.2

A cross-platform async networking library with WebSocket clients and network status monitoring.
Documentation

open-net

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.

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
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 refresh of reachability and network name, with cached IP-stack capability
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. From the consumer's directory, add the dependency with Cargo and select the features your application needs. For an HTTP-only application:

cargo add open-net --no-default-features --features http-client

The guides use a local path dependency for building from source. Point it at the open-net directory containing this package's Cargo.toml. For a dependency added from crates.io, keep Cargo's dependency entry and apply the guide's feature selection. Add the example's application dependencies (such as Tokio and a TLS provider) to your consumer too; the library's test dependencies are not automatically available to your application.

Integration Guides

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.