Skip to main content

OpenNet

Struct OpenNet 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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)?;
Source

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.

Source

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.

Source

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.

Source

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?;
Source

pub fn get_ws_client( &self, thread_name: &str, ) -> Result<WebSocketClient, NetError>

Returns a shared handle to an existing WebSocket client.

Source

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.

Source

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

Source

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.

Source

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?;
Source

pub fn get_net_status_client( &self, thread_name: &str, ) -> Result<NetStatusClient, NetError>

Returns a shared handle to a named network-status client.

Source

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.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more