How ospab/ostp works
1. This is a Rust monorepo with one shared protocol core and several frontends.
The central dependency is ostp-core, which implements the wire protocol, cryptography, framing, congestion/reliability logic, DNS probing, and session resumption. Everything else is a runtime wrapper around that core.
2. The main boundary is between local traffic handling and encrypted transport.
On the client side, local app traffic enters through a tunnel/proxy layer, is routed and policy-checked, then handed to a transport implementation. On the server side, the inverse happens: transport packets are decrypted/authenticated, then relayed onward to the Internet or other outbound targets.
3. ostp-core is the protocol engine shared by client and server.
Its submodules show the architecture: crypto for Noise/AEAD/obfuscation, framing for packet structure and padding, congestion for ARQ behavior, relay and resumption for session handling, and dns / dnstt for DNS-related transport support. This crate is the trust boundary for packet integrity and masking.
4. Transport is abstracted from the protocol.
The repo supports multiple carriers, including UDP and UDP-over-TCP (uot), with additional DNS- and XHTTP-style transport code on the client/server sides. The transport layer is where anti-DPI behavior, handshake fragmentation, junk packets, masking, and padding are applied before packets leave the host.
5. ostp-client is the local endpoint process.
It loads config, starts runtime services (runner, signal, logging), and exposes inbounds such as local_proxy and tun. It then selects an outbound such as ostp, socks, direct, or block, making the client a policy-and-routing hub rather than a single-purpose tunnel.
6. Client traffic flow includes routing, sniffing, and NAT handling.
Modules like router, exclusion, process_lookup, sni_sniff, and udp_nat show that the client inspects flows, decides whether they should be tunneled, and maintains UDP mappings for stateful traffic. This is the part you would diagram as “local applications → policy/routing → tunnel or bypass.”
7. ostp-server is the remote termination and relay node.
It contains transport listeners, dispatch logic, relay/outbound handling, and router/fallback logic. It also exposes a management API (api.rs) for server administration, metrics, and key-related operations, so the server has both data-plane and control-plane responsibilities.
8. There is a separate TUN/network-stack subsystem for full-system routing.
ostp-tun, ostp-tun-helper, and netstack-smoltcp provide cross-platform TUN integration and a user-space TCP/IP stack. This is the architecture used when the client needs to route all device traffic without relying on an external tun2socks dependency. The netstack-smoltcp crate is the reusable network stack/forwarding engine; the helper crates bind it to OS-specific TUN devices and route setup.
9. Platform frontends are thin shells over the same backend concepts.
ostp-gui is a Tauri desktop app with a JS frontend and Rust backend; ostp-flutter is the Android UI with OstpVpnService, OstpTileService, and a bundled tun2socks asset; ostp-jni bridges Rust client functionality into Android/Kotlin. These frontends mainly handle user interaction and platform-specific VPN/TUN integration, not protocol logic.
10. Deployment and control are split from the protocol runtime.
The repo includes prebuilt web assets for ostp-control, plus CI/build scripts for Rust, Android, Tauri, and Flutter. That means the architecture has a core runtime plane, a management plane, and multiple packaged UI surfaces targeting Windows, Linux, macOS, and Android.
Main entry points: src/lib.rs ostp-core · mod.rs Tunnel · src/lib.rs ostp-server · src/lib.rs ostp-client
Components 25
Protocol Core
Shared wire-protocol and crypto engine used by all runtimes.
- ostp-core · Shared protocol implementation: crypto, framing, congestion, relay, resumption, and DNS support.
ostp-core/src/lib.rs - Crypto · Noise, AEAD, obfuscation, and reality primitives.
ostp-core/src/crypto/mod.rs - Framing · Packet structure, padding, and websocket-style framing.
ostp-core/src/framing/mod.rs - Congestion · ARQ/congestion behavior for protocol delivery.
ostp-core/src/congestion.rs - DNS · DNS probing and DNS-based transport support.
ostp-core/src/dns.rs
Client Runtime
Local endpoint that handles apps, policy, routing, and outbound selection.
- ostp-client · Local client process for config, runtime services, inbounds, routing, and outbounds.
ostp-client/src/lib.rs - Runtime · Runner, signals, and logging for the client process.
ostp-client/src/runner.rs - Tunnel · Traffic classification, routing, exclusions, sniffing, and UDP NAT.
ostp-client/src/tunnel/mod.rs - Inbounds · Local proxy and TUN ingress points for application traffic.
ostp-client/src/tunnel/inbounds/mod.rs - Outbounds · Policy targets such as OSTP, SOCKS, direct, or block.
ostp-client/src/tunnel/outbounds/mod.rs - Client transport · Client-side transport adapters such as DNS and XHTTP-style transport.
ostp-client/src/transport/mod.rs
Server Runtime
Remote terminator that authenticates traffic and relays it onward.
- ostp-server · Remote termination node with relay, dispatch, router, and admin API.
ostp-server/src/lib.rs - Server transport · UDP, DNS, and UOT transport listeners/encoders for inbound packets.
ostp-server/src/transport/mod.rs - Relay · Dispatch, outbound forwarding, relay handling, and fallback logic.
ostp-server/src/relay.rs - Admin API · Management interface for server operations, metrics, and key-related actions.
ostp-server/src/api.rs
TUN Stack
Reusable virtual-network and user-space stack components.
- netstack-smoltcp · Reusable TCP/IP forwarding engine for full-system routing.
netstack-smoltcp/src/lib.rs - tun-helper · OS-specific TUN setup and routing helper binary.
ostp-tun-helper/src/main.rs - ostp-tun · Cross-platform TUN abstraction and route integration for desktop/mobile clients.
ostp-tun/src/lib.rs
Frontends
Desktop, mobile, and JNI shells around the shared backend.
- ostp-gui · Tauri desktop shell with JS frontend and Rust backend.
ostp-gui/src/main.js - Tauri backend · Rust backend for desktop integration and DNS/IPC helpers.
ostp-gui/src-tauri/src/lib.rs - ostp-flutter · Flutter Android frontend and VPN service integration.
ostp-flutter/lib/main.dart - VPN service · Android VPN/tile services and bundled tun2socks asset.
ostp-flutter/android/app/src/main/kotlin/com/ospab/ostp_client/OstpVpnService.kt - ostp-jni · Rust-to-Kotlin bridge for Android client functionality.
ostp-jni/src/lib.rs
Control and Packaging
Build artifacts, web control assets, and the standalone CLI surface.
- ostp-control · Prebuilt control-plane frontend assets shipped with the repo.
ostp-control/dist/index.html - ostp CLI · Repository-root binary surface and DNS probing entrypoint.
ostp/src/main.rs
Connections 24
- ostp-core → Crypto: uses · Core protocol relies on cryptographic primitives.
- ostp-core → Framing: uses · Core protocol defines packet framing and padding.
- ostp-core → Congestion: uses · Core protocol handles reliability and congestion behavior.
- ostp-core → DNS: uses · Core protocol includes DNS probing and DNS transport support.
- ostp-client → Runtime: starts · Client process initializes runtime services.
- ostp-client → Tunnel: routes through · Client funnels local traffic into tunnel policy.
- Tunnel → Inbounds: accepts · Tunnel receives traffic from local ingress points.
- Tunnel → Outbounds: selects · Tunnel chooses bypass, block, or encrypted egress.
- Tunnel → Client transport: hands off · Tunnel forwards tunneled traffic to transport adapters.
- Client transport → ostp-core: encapsulates via · Client transport uses the shared protocol engine.
- ostp-server → Server transport: listens on · Server accepts packets through transport listeners.
- ostp-server → Relay: forwards via · Server relay handles decrypted traffic and outbound delivery.
- ostp-server → Admin API: exposes · Server publishes management/control APIs.
- Server transport → ostp-core: decodes via · Server transport relies on the shared protocol engine.
- Relay → ostp-core: terminates via · Relay uses protocol session handling and resumption.
- ostp-tun → netstack-smoltcp: embeds · TUN layer can feed a reusable user-space network stack.
- tun-helper → ostp-tun: binds · Helper connects OS TUN devices and routes to the shared TUN layer.
- ostp-gui → Tauri backend: backs with · Desktop UI is paired with a Rust Tauri backend.
- Tauri backend → ostp-client: controls · Desktop backend drives the client runtime.
- ostp-flutter → VPN service: uses · Flutter app delegates VPN/TUN handling to Android services.
- ostp-flutter → ostp-jni: bridges to · Flutter/mobile surface can interoperate with the JNI bridge.
- ostp-jni → ostp-client: wraps · JNI exposes client capabilities to Kotlin/Android.
- ostp-control → ostp-server: manages · Static control assets serve the server management plane.
- ostp CLI → ostp-core: probes · Standalone CLI includes DNS probing around the shared core.