From 0495afb3c6f9462d55aa3b7e52824ba6c3c56510 Mon Sep 17 00:00:00 2001
From: Christien Rioux <chris@veilid.org>
Date: Fri, 25 Oct 2024 17:19:53 -0700
Subject: [PATCH] placeholder for network shim

---
 veilid-tools/src/lib.rs              |  1 +
 veilid-tools/src/network_shim/mod.rs | 50 ++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 veilid-tools/src/network_shim/mod.rs

diff --git a/veilid-tools/src/lib.rs b/veilid-tools/src/lib.rs
index 856d287a..13b715b5 100644
--- a/veilid-tools/src/lib.rs
+++ b/veilid-tools/src/lib.rs
@@ -46,6 +46,7 @@ pub mod mutable_future;
 #[cfg(not(target_arch = "wasm32"))]
 pub mod network_interfaces;
 pub mod network_result;
+pub mod network_shim;
 pub mod random;
 pub mod single_shot_eventual;
 pub mod sleep;
diff --git a/veilid-tools/src/network_shim/mod.rs b/veilid-tools/src/network_shim/mod.rs
new file mode 100644
index 00000000..726fa1ee
--- /dev/null
+++ b/veilid-tools/src/network_shim/mod.rs
@@ -0,0 +1,50 @@
+//! # Network Shim
+//!
+//! ## Networking abstraction layer
+//!
+//! Support for mocking and virtualizing network connections, as well as passing through to supported
+//! networking functionality.
+//!
+//! The following structs are available that allow connecting to a centralized virtual
+//! router to emulate a large scale network.
+//!
+//! * RouterClient
+//! * RouterServer
+//!
+//! Additional traits are is implemented for all shimmed APIs that have static methods
+//! like `new()`, `default()`, `connect()` and `bind()` to allow optional namespacing
+//! such that the structs they produce are new network router clients with their own
+//! distinct IP addresses, network segments, and network characteristics as allocated
+//! by the [RouterServer].
+//!
+//! A singleton RouterClient is created by this module that is used by default unless the
+//! extension traits on the shimmed APIs are used to override it with another RouterClient instance.
+//!
+//! ## Available shims
+//!
+//! API-compatible shims for:
+//! * Tokio (Native)
+//!   - [tokio::net::TcpListener]
+//!   - [tokio::net::TcpStream]
+//!   - [tokio::net::UdpSocket]
+//!   - [tokio_stream::wrappers::TcpListenerStream]
+//! * Async-std (Native)
+//!   - [async_std::net::TcpListener]
+//!   - [async_std::net::TcpStream]
+//!   - [async_std::net::UdpSocket]
+//!   - [async_std::net::Incoming]
+//! * std::net (Native)
+//!   - [std::net::TcpListener]
+//!   - [std::net::TcpStream]
+//!   - [std::net::UdpSocket]
+//!   - [std::net::Incoming]
+//! * ws_stream_wasm (browser WASM)
+//!   - [ws_stream_wasm::WsMeta]
+//!   - [ws_stream_wasm::WsStream]
+//!   - [ws_stream_wasm::WsStreamIo]
+//!
+//! ## Other modules leveraging this module
+//!
+//! * `veilid-core`'s network `native` and `wasm` modules
+//! * This crate's `network_interfaces` module
+//! * This crate's `dns_lookup` module