pub struct OpenNet { /* private fields */ }Expand description
Top-level networking engine that owns runtime workers and named client instances.
Cloneable client handles remain valid until their named client is destroyed or the engine is dropped.
Implementations§
Source§impl OpenNet
impl OpenNet
Sourcepub fn begin_shutdown(&self)
pub fn begin_shutdown(&self)
Permanently close this engine’s admission and request cancellation.
Idempotent and safe inside SDK callbacks. It does not wait for callback,
provider, worker or runtime retirement. Use Self::shutdown from an
external control flow to confirm completion. The engine cannot reopen.
Sourcepub async fn shutdown(&self) -> Result<(), NetError>
pub async fn shutdown(&self) -> Result<(), NetError>
Close this engine and wait for its running resources to exit.
The first poll also calls Self::begin_shutdown. Concurrent/repeated
waiters share the result; cancelling a waiter never cancels cleanup.
No caller Tokio runtime is required. Success confirms retirement of
registered clients, their SDK callbacks/providers, network monitoring,
engine callback workers and runtime, even while public handles survive.
Standalone HTTP workers, other engines, process-wide logging and the process-wide retirement reaper are outside this boundary. A standalone HTTP client using this engine’s network context keeps its HTTP workers; only its engine-owned observations retire. User-retained data is not freed. Application tasks on an application-owned runtime remain its owner’s duty.
SDK callback/worker contexts are conservatively rejected on every poll
with InvalidInput (field open_net.shutdown, stage Close), including
cross-engine waits. Closing still starts; use begin_shutdown then return.
Indirect cross-thread waits cannot be detected. A callback/provider that
never returns can prevent completion; a caller timeout only ends its wait.
Errors do not certify that all resources have retired. Dropping the engine
still initiates automatic cleanup, but Drop itself is not a completion receipt.
Sourcepub fn new_with_network_config(config: NetworkConfig) -> Result<Self, NetError>
pub fn new_with_network_config(config: NetworkConfig) -> Result<Self, NetError>
Creates an engine with an immutable default network policy for WebSocket clients.
Proxy and TLS settings are validated before any work starts. This constructor currently applies only to WebSocket clients; use the per-client network-config constructor to override defaults.
Sourcepub fn new() -> Result<Self, NetError>
pub fn new() -> Result<Self, NetError>
Creates an engine with default settings and queue capacities of 128.
When the ws-client feature is enabled, the default WebSocket TLS
connector is compiled during this call. Supply a provider with
Self::new_with_network_config or install the application’s process
provider before calling this constructor. The SDK never installs one.
Sourcepub fn new_with_config(config: OpenNetConfig) -> Result<Self, NetError>
pub fn new_with_config(config: OpenNetConfig) -> Result<Self, NetError>
Creates an engine with the supplied runtime, queue capacities, and network policy.
Validates configuration before creating channels or workers. Invalid
capacities, worker counts, or missing WebSocket TLS providers return
InvalidConfig; values remain fixed thereafter.
use open_net::{config::OpenNetConfig, NetError, OpenNet};
#[cfg(feature = "ws-client")]
use open_net::network::{NetworkConfig, TlsConfig};
#[cfg(feature = "ws-client")]
use std::sync::Arc;
let config = OpenNetConfig::default()
.with_async_queue_capacity(256)
.with_sync_queue_capacity(128);
#[cfg(feature = "ws-client")]
let config = config.with_network_config(
NetworkConfig::default().with_tls(
TlsConfig::default().with_crypto_provider(Arc::new(
rustls_openssl::default_provider(),
)),
),
);
let net = OpenNet::new_with_config(config)?;Sourcepub async fn create_ws_client(
&self,
thread_name: &str,
) -> Result<WebSocketClient, NetError>
pub async fn create_ws_client( &self, thread_name: &str, ) -> Result<WebSocketClient, NetError>
Creates a WebSocket client with default parameters and waits for its worker to become ready.
The returned client is disconnected; call connect or start_session to establish a session.
Sourcepub async fn create_ws_client_with_config(
&self,
thread_name: &str,
config: WebSocketClientConfig,
) -> Result<WebSocketClient, NetError>
pub async fn create_ws_client_with_config( &self, thread_name: &str, config: WebSocketClientConfig, ) -> Result<WebSocketClient, NetError>
Creates a WebSocket client with the supplied parameters and engine network policy.
Cancelling the wait does not cancel submitted creation; retrieve the
client later with get_ws_client and release it with destroy_ws_client.
Sourcepub async fn get_or_create_ws_client_with_config(
&self,
thread_name: &str,
config: WebSocketClientConfig,
) -> Result<WebSocketClient, NetError>
pub async fn get_or_create_ws_client_with_config( &self, thread_name: &str, config: WebSocketClientConfig, ) -> Result<WebSocketClient, NetError>
Returns the named WebSocket client, creating it when the name is not registered yet.
The supplied configuration is used only when this call creates the
client. If another caller has already registered the name, this method
returns a clone of that client and keeps its original immutable
configuration. Concurrent callers wait for the same lifecycle
transition and do not receive ClientAlreadyExists for the same name.
Sourcepub async fn create_ws_client_with_network_config(
&self,
thread_name: &str,
config: WebSocketClientConfig,
network_config: NetworkConfig,
) -> Result<WebSocketClient, NetError>
pub async fn create_ws_client_with_network_config( &self, thread_name: &str, config: WebSocketClientConfig, network_config: NetworkConfig, ) -> Result<WebSocketClient, NetError>
Creates a WebSocket client with an immutable per-client proxy and TLS policy.
The supplied policy completely replaces engine defaults. default() selects
direct mode and WebPKI roots; connect, retry, and reconnect use this snapshot.
Waits for the worker to become ready but does not connect. Dropping the future does not cancel creation; retrieve and later destroy the client by name.
use open_net::{
network::{NetworkConfig, ProxyConfig, TlsConfig},
tls::CryptoProvider,
ws::WebSocketClientConfig,
NetError, OpenNet,
};
use std::sync::Arc;
let provider: Arc<CryptoProvider> =
Arc::new(rustls_openssl::default_provider());
let defaults = NetworkConfig::default()
.with_proxy(ProxyConfig::http_connect("http://127.0.0.1:8080", None)?)
.with_tls(TlsConfig::default().with_crypto_provider(Arc::clone(&provider)));
let net = OpenNet::new_with_network_config(defaults.clone())?;
let inherited = net.create_ws_client("inherited").await?;
let direct = net.create_ws_client_with_network_config(
"direct", WebSocketClientConfig::default(),
NetworkConfig::default().with_tls(
TlsConfig::default().with_crypto_provider(Arc::clone(&provider)),
),
).await?;
let other = net.create_ws_client_with_network_config(
"other", WebSocketClientConfig::default(),
defaults.with_proxy(ProxyConfig::http_connect("http://127.0.0.1:8081", None)?),
).await?;
net.destroy_ws_client("inherited").await?;
net.destroy_ws_client("direct").await?;
net.destroy_ws_client("other").await?;Sourcepub fn get_ws_client(
&self,
thread_name: &str,
) -> Result<WebSocketClient, NetError>
pub fn get_ws_client( &self, thread_name: &str, ) -> Result<WebSocketClient, NetError>
Returns a shared handle to an existing WebSocket client.
Sourcepub async fn destroy_ws_client(&self, thread_name: &str) -> Result<(), NetError>
pub async fn destroy_ws_client(&self, thread_name: &str) -> Result<(), NetError>
Permanently destroys a named WebSocket client after its worker exits.
This future can be awaited without a caller Tokio runtime, including via
futures::executor::block_on. The SDK owns the worker join. Cancelling
the wait does not cancel cleanup or release the name before worker exit.
A concurrent destroy returns crate::error::ErrorKind::ConnectionClosing;
an absent name returns crate::error::ErrorKind::ClientNotFound. Use
Self::destroy_ws_client_if_exists for repeated, idempotent cleanup.
Sourcepub async fn destroy_ws_client_if_exists(
&self,
thread_name: &str,
) -> Result<(), NetError>
pub async fn destroy_ws_client_if_exists( &self, thread_name: &str, ) -> Result<(), NetError>
Permanently destroys a named WebSocket client when it exists.
Missing names are treated as success, so this method can be used from
repeated or best-effort cleanup paths. If creation or destruction is
already in progress, it waits for that lifecycle operation and then
completes the requested cleanup.
Like Self::destroy_ws_client, this does not require a caller Tokio
runtime and accepted cleanup continues if its waiter is cancelled.
Source§impl OpenNet
impl OpenNet
Sourcepub fn network_status_context(&self) -> NetworkStatusContext
pub fn network_status_context(&self) -> NetworkStatusContext
Export this engine’s cached network state for an explicitly configured standalone HTTP client. Reading the context never starts monitoring. The context remains bound to this engine and becomes Closed on engine drop.
Sourcepub async fn create_net_status_client(
&self,
thread_name: &str,
) -> Result<NetStatusClient, NetError>
pub async fn create_net_status_client( &self, thread_name: &str, ) -> Result<NetStatusClient, NetError>
Creates a network-status client; call start().await to begin monitoring.
Names are trimmed and must be unique within an engine. Requires the
net-status feature, also enabled by http-client and ws-client.
use open_net::{NetError, OpenNet};
#[cfg(feature = "ws-client")]
use open_net::network::{NetworkConfig, TlsConfig};
#[cfg(feature = "ws-client")]
use std::sync::Arc;
#[cfg(feature = "ws-client")]
let net = OpenNet::new_with_network_config(
NetworkConfig::default().with_tls(
TlsConfig::default().with_crypto_provider(Arc::new(
rustls_openssl::default_provider(),
)),
),
)?;
#[cfg(not(feature = "ws-client"))]
let net = OpenNet::new()?;
let client = net.create_net_status_client("network-status").await?;
client.start().await?;
let snapshot = client.snapshot()?;
let status = snapshot.reachability;
let ip_stack = snapshot.ip_stack;
net.destroy_net_status_client("network-status").await?;Sourcepub fn get_net_status_client(
&self,
thread_name: &str,
) -> Result<NetStatusClient, NetError>
pub fn get_net_status_client( &self, thread_name: &str, ) -> Result<NetStatusClient, NetError>
Returns a shared handle to a named network-status client.
Sourcepub async fn destroy_net_status_client(
&self,
thread_name: &str,
) -> Result<(), NetError>
pub async fn destroy_net_status_client( &self, thread_name: &str, ) -> Result<(), NetError>
Permanently stops a client, waits for monitoring to exit, and releases its name.
Cancelling the wait does not cancel submitted destruction; the name remains
reserved until cleanup completes. Use NetStatusClient::stop to pause instead.