OPENPPP2

English | 简体中文

OPENPPP2 is a source-driven, cross-platform network runtime built around the C++ executable ppp, with an optional Go management backend. The real implementation boundary lives in main.cpp, ppp/configurations, ppp/transmissions, ppp/app/protocol, ppp/app/client, ppp/app/server, and the platform-specific integration directories.

It is not a single-purpose VPN app. The code implements a layered system:

The documentation is written from code facts upward. It explains what the system does, why each layer exists, and where the implementation boundaries really are.

1. System Architecture Overview
2. Start Here
3. Reading Paths
4. Documentation Set
5. Repository Layout
6. Build Instructions
7. Quick Start
8. Configuration Overview
9. Protocol and Transport Overview
10. Client Runtime Summary
11. Server Runtime Summary
12. Platform Integration Summary
13. Concurrency and Threading Model
14. Error Handling Summary
15. Management Backend
16. Security Summary
17. Code Facts That Shape The Docs
18. Boundaries
19. Quick Reference
20. Notes

The following diagram shows the top-level layering of the OPENPPP2 runtime. Each box corresponds to real source directories.

graph TD
    subgraph "Process: ppp"
        A[main.cpp\nPppApplication::Run] --> B[AppConfiguration\nppp/configurations]
        A --> C[Platform Setup\nwindows/ linux/ darwin/ android/]
        B --> D[ITransmission\nppp/transmissions]
        D --> E[VirtualEthernetLinklayer\nppp/app/protocol]
        E --> F[Client Runtime\nppp/app/client]
        E --> G[Server Runtime\nppp/app/server]
        F --> H[Virtual NIC / TAP\nppp/tap]
        G --> I[Session Exchanger\nVirtualEthernetSwitcher]
        H --> J[lwIP VNetstack\nppp/ethernet]
        I --> K[Management Backend\ngo/]
    end
    L[OS Network Stack] --> C
    M[Remote Peer] -->|TCP / WS / WSS| D

flowchart LR
    A[PreparedArgumentEnvironment] --> B[LoadConfiguration]
    B --> C[AppPrivilege Check]
    C --> D[prevent_rerun_ Lock]
    D --> E[Windows_PreparedEthernetEnvironment\nclient only]
    E --> F[PreparedLoopbackEnvironment]
    F --> G[ConsoleUI::Start]
    G --> H[NextTickAlwaysTimeout]
    H --> I[io_context::run]
    I --> J[OnTick loop]

sequenceDiagram
    participant OS as OS Signal
    participant App as PppApplication
    participant UI as ConsoleUI
    participant RT as Runtime
    participant Lock as prevent_rerun_

    OS->>App: SIGINT / CTRL+C
    App->>App: cancel tick timer
    App->>UI: ConsoleUI::Stop()
    App->>RT: Dispose()
    RT->>RT: IPv6 rollback (server)
    RT->>RT: Route/DNS rollback (client)
    RT->>Lock: prevent_rerun_.Release()
    App->>App: io_context::stop()

1. docs/ENGINEERING_CONCEPTS.md
2. docs/ARCHITECTURE.md
3. docs/STARTUP_AND_LIFECYCLE.md
4. docs/TRANSMISSION.md
5. docs/HANDSHAKE_SEQUENCE.md
6. docs/PACKET_FORMATS.md
7. docs/CLIENT_ARCHITECTURE.md
8. docs/SERVER_ARCHITECTURE.md
9. docs/ROUTING_AND_DNS.md
10. docs/PLATFORMS.md
11. docs/DEPLOYMENT.md
12. docs/OPERATIONS.md

1. docs/SOURCE_READING_GUIDE.md
2. main.cpp
3. ppp/configurations/*
4. ppp/transmissions/*
5. ppp/app/protocol/*
6. ppp/app/client/*
7. ppp/app/server/*
8. Platform directories
9. go/* when managed deployment is used

1. docs/CONFIGURATION.md
2. docs/CLI_REFERENCE.md
3. docs/PLATFORMS.md
4. docs/ROUTING_AND_DNS.md
5. docs/DEPLOYMENT.md
6. docs/OPERATIONS.md
7. docs/SECURITY.md

1. docs/CONCURRENCY_MODEL.md
2. docs/EDSM_STATE_MACHINES.md
3. docs/PACKET_LIFECYCLE.md
4. docs/LINKLAYER_PROTOCOL.md
5. docs/TRANSMISSION_PACK_SESSIONID.md
6. docs/TUNNEL_DESIGN.md
7. docs/ERROR_CODES.md
8. docs/ERROR_HANDLING_API.md
9. docs/DIAGNOSTICS_ERROR_SYSTEM.md

1. docs/IPV6_LEASE_MANAGEMENT.md
2. docs/IPV6_TRANSIT_PLANE.md
3. docs/IPV6_NDP_PROXY.md
4. docs/IPV6_CLIENT_ASSIGNMENT.md

The repository contains paired English/Chinese documents plus the root README pair. Each Chinese document has a one-to-one English counterpart.

.
├── main.cpp                      # Process entry point: PppApplication::Run()
├── ppp/
│   ├── stdafx.h                  # Master header: macros, type aliases (read first)
│   ├── configurations/
│   │   ├── AppConfiguration.h    # Runtime configuration model
│   │   └── AppConfiguration.cpp  # Loaded(): policy compiler and normalizer
│   ├── transmissions/
│   │   ├── ITransmission.h/.cpp  # Protected transport + handshake
│   │   ├── ITcpipTransmission.h/.cpp  # TCP carrier
│   │   └── IWebsocketTransmission.h/.cpp  # WS/WSS carrier
│   ├── app/
│   │   ├── protocol/
│   │   │   ├── VirtualEthernetLinklayer.h/.cpp  # Opcode-based tunnel actions
│   │   │   ├── VirtualEthernetInformation.h/.cpp # Session envelope
│   │   │   └── VirtualEthernetPacket.cpp  # Static packet pack/unpack
│   │   ├── client/
│   │   │   ├── VEthernetExchanger.h/.cpp     # Client session exchanger
│   │   │   └── VEthernetNetworkSwitcher.h/.cpp # Route/DNS management
│   │   ├── server/
│   │   │   ├── VirtualEthernetSwitcher.h/.cpp   # Session coordination
│   │   │   ├── VirtualEthernetExchanger.h/.cpp  # Per-session server handler
│   │   │   ├── VirtualEthernetManagedServer.h/.cpp # Go backend bridge
│   │   │   ├── VirtualEthernetDatagramPort.h    # Server UDP forwarding
│   │   │   └── VirtualEthernetNamespaceCache.h  # DNS cache
│   │   └── ConsoleUI.h/.cpp      # TUI: render + input threads
│   ├── diagnostics/
│   │   ├── Error.h/.cpp          # Error code definitions and setters
│   │   ├── ErrorCodes.def        # X-macro source: 628 error codes
│   │   └── ErrorHandler.h/.cpp   # Handler registration / dispatch
│   ├── tap/
│   │   └── ITap.h/.cpp           # Virtual NIC abstraction interface
│   ├── ethernet/
│   │   ├── VEthernet.cpp         # TAP frame dispatch, Output()
│   │   └── VNetstack.cpp         # lwIP integration: UDP/TCP/ICMP hooks
│   ├── threading/
│   │   └── Executors.h/.cpp      # Thread pool and io_context management
│   └── net/                      # Sockets, ASIO, HTTP proxy, ICMP, firewall
├── windows/
│   └── ppp/tap/TapWindows.h/.cpp # Wintun / TAP-Windows implementation
├── linux/
│   └── ppp/tap/TapLinux.h/.cpp   # Linux TUN implementation
├── darwin/
│   └── ppp/tap/TapDarwin.h/.cpp  # macOS utun implementation
├── android/
│   └── libopenppp2.cpp           # Android JNI bridge
├── builds/                        # Named CMakeLists.txt variants
├── go/                            # Optional Go management backend
└── docs/                          # Paired EN + _CN.md documentation
    ├── *.md
    └── *_CN.md

See docs/TESTING.md for unit test commands and the GitHub Actions Test · Unit workflow.

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Output: bin/ppp

Third-party library path: THIRD_PARTY_LIBRARY_DIR defaults to /root/dev. Override before building:

sed -i 's|SET(THIRD_PARTY_LIBRARY_DIR /root/dev)|SET(THIRD_PARTY_LIBRARY_DIR /your/path)|' CMakeLists.txt
# macOS: sed -i '' '...' CMakeLists.txt

Expected layout under THIRD_PARTY_LIBRARY_DIR:

boost/        # headers + stage/lib/*.a       (Boost 1.86.0)
jemalloc/     # headers + lib/libjemalloc.a   (jemalloc 5.3.0)
openssl/      # libssl.a, libcrypto.a, include/ (OpenSSL 3.0.13)

Optional CMake flags:

build_windows.bat                  # Release x64 (default)
build_windows.bat Debug x64
build_windows.bat Release x86
build_windows.bat Release all      # Both x86 and x64

Uses CMake + Ninja (not MSBuild). vcpkg is required with static triplets x86-windows-static / x64-windows-static.

vcpkg discovery order:

1. VCPKG_CMAKE_TOOLCHAIN_FILE environment variable
2. VCPKG_ROOT environment variable
3. %LOCALAPPDATA%\vcpkg\vcpkg.path.txt
4. ..\vcpkg relative path
5. Visual Studio integrated vcpkg

Output: bin\Release\x64\ppp.exe, bin\Release\x86\ppp.exe

# NDK_ROOT must be set (NDK r20b)
cd android
./build.sh all    # arm64-v8a, x86_64, armeabi-v7a, x86
./build.sh arm64  # single ABI

Output: android/bin/android/<ABI>/libopenppp2.so

Minimum API: 23 (Android 6.0). Android system provides jemalloc natively; no additional jemalloc dependency needed.

builds/ contains named CMakeLists.txt variants:

Use build-openppp2-by-builds.sh to compile all variants into bin/<variant>.zip.

{
    "concurrent": 4,
    "key": {
        "kf": 154543927,
        "kx": 128,
        "kl": 10,
        "kh": 12,
        "protocol": "aes-128-cfb",
        "protocol-key": "TSAO_PPP",
        "transport": "aes-256-cfb",
        "transport-key": "TSAO_PPP"
    },
    "tcp": {
        "listen": { "port": 20000 }
    },
    "server": {
        "subnet": true,
        "ipv4-pool": {
            "network": "10.0.0.0",
            "mask": "255.255.0.0"
        }
    }
}

Run: ./ppp --mode=server --config=./appsettings.json

{
    "concurrent": 2,
    "key": {
        "kf": 154543927,
        "kx": 128,
        "kl": 10,
        "kh": 12,
        "protocol": "aes-128-cfb",
        "protocol-key": "TSAO_PPP",
        "transport": "aes-256-cfb",
        "transport-key": "TSAO_PPP"
    },
    "client": {
        "server": "ppp://your-server-ip:20000/"
    }
}

Run: ./ppp --mode=client --config=./appsettings.json

AppConfiguration (ppp/configurations/AppConfiguration.h) is the central configuration model. Its Loaded() method is a policy compiler: it clamps, validates, and derives all secondary values from the raw JSON input.

flowchart TD
    A[Raw JSON] --> B[AppConfiguration::Load]
    B --> C[AppConfiguration::Loaded]
    C --> D{Field validation}
    D -->|out-of-range| E[Clamp to safe default]
    D -->|invalid combination| F[Disable feature]
    D -->|ok| G[Derive secondary values]
    E --> H[Runtime-ready AppConfiguration]
    F --> H
    G --> H

Key configuration groups:

Full reference: docs/CONFIGURATION.md

ITransmission (ppp/transmissions/ITransmission.h) owns:

• Handshake: NOP exchange → session ID → ivv → nmux → cipher rebuild
• Framing: base94 frame header (first packet: 4+3 bytes, later: 4 bytes)
• Masking: byte-level mask applied to payload header bytes
• Delta encoding: incremental delta compression on payload data
• Two cipher layers: protocol cipher (header metadata) and transport cipher (payload), both rebuilt from base_key + ivv_str

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: NOP packets (count = f(key.kl, key.kh))
    S->>C: NOP packets
    S->>C: Session ID (sid)
    C->>S: ivv (initialization vector variant)
    S->>C: nmux (mux flag in low bit)
    Note over C,S: Both sides rebuild cipher from ivv+nmux+base_key
    Note over C,S: handshaked_ = true
    C->>S: Tunnel traffic (opcode-framed)

Carrier implementations:

VirtualEthernetLinklayer (ppp/app/protocol/VirtualEthernetLinklayer.h) defines the tunnel protocol. Every tunnel packet begins with a 1-byte opcode.

graph LR
    subgraph "Outbound (Do*)"
        D1[DoLan] --> OUT[ITransmission::Write]
        D2[DoFrpEntry] --> OUT
        D3[DoEcho] --> OUT
        D4[DoKeepAlived] --> OUT
        D5[DoMux] --> OUT
    end
    subgraph "Inbound (On*)"
        IN[PacketInput] --> O1[OnLan]
        IN --> O2[OnFrpEntry]
        IN --> O3[OnEcho]
        IN --> O4[OnKeepAlived]
        IN --> O5[OnMux]
    end

Key opcodes:

Full opcode reference: docs/LINKLAYER_PROTOCOL.md

The client runtime (ppp/app/client/) connects to the server and integrates with the host OS networking.

graph TD
    A[VEthernetNetworkSwitcher] --> B[ITransmission]
    A --> C[Virtual TAP / NIC]
    A --> D[Route Table\nmodification]
    A --> E[DNS redirect]
    C --> F[VEthernet / VNetstack\nlwIP]
    F --> G[VEthernetExchanger]
    G --> B
    B -->|TCP/WS/WSS| H[Server]

Responsibilities:

Restart modes:

Full reference: docs/CLIENT_ARCHITECTURE.md

The server runtime (ppp/app/server/) accepts connections and coordinates per-session state.

graph TD
    A[Listen Socket] --> B[VirtualEthernetSwitcher\nAcceptor]
    B --> C[VirtualEthernetExchanger\nPer session handler]
    C --> D[ITransmission\nPer session transport]
    C --> E[UDP DatagramPort pool]
    C --> F[TCP NAT table\nconn_id keyed]
    C --> G[IPv6 lease manager]
    B --> H[VirtualEthernetManagedServer\nGo backend bridge]
    H --> I[Go management service\nWebSocket]

Session lifecycle:

stateDiagram-v2
    [*] --> Accepting: listen()
    Accepting --> Handshaking: accept()
    Handshaking --> Active: handshaked_ = true
    Active --> Disposing: client disconnect / timeout
    Active --> Disposing: keepalive timeout
    Disposing --> [*]: Dispose() complete

Key facts:

• TCP conn_id: 32-bit, monotonically increasing per session, client-assigned. Server NAT table key = (session_id, conn_id). Released on OnDisconnect.
• QoS token bucket: per-session, refill rate from bandwidth field (bytes/sec). Coroutine suspends on exhaustion.
• OnTick() tasks: stats refresh, tunnel liveness check, session aging, IPv6 lease aging, TUI dirty-flag publish.

Full reference: docs/SERVER_ARCHITECTURE.md

The virtual NIC layer is abstracted by ITap (ppp/tap/ITap.h). Platform implementations differ significantly.

graph TD
    A[ITap interface\nppp/tap/ITap.h] --> B[TapLinux\nlinux/ppp/tap]
    A --> C[TapWindows\nwindows/ppp/tap]
    A --> D[TapDarwin\ndarwin/ppp/tap]
    A --> E[Android TapLinux variant\nandroid/libopenppp2.cpp]
    B --> B1[/dev/net/tun\nIFF_TUN or IFF_MULTI_QUEUE SSMT]
    C --> C1[Wintun ring-buffer\npreferred]
    C --> C2[TAP-Windows overlapped I/O\nfallback]
    D --> D1[/dev/utun*\n4-byte AF prefix strip/prepend]
    E --> E1[VpnService fd\nno /dev/net/tun open]

Platform-specific behaviors:

Full reference: docs/PLATFORMS.md

OPENPPP2 uses Boost.Asio io_context as its event loop, combined with C++ coroutines via YieldContext.

graph TD
    subgraph "Thread Pool (Executors)"
        T1[io_context thread 0]
        T2[io_context thread 1]
        TN[io_context thread N]
        TR[TUI render thread]
        TI[TUI input thread]
    end
    subgraph "Per io_context"
        T1 --> B1[64KB shared buffer\nExecutors::Buffers]
        T1 --> S1[asio::strand\nper session]
    end
    subgraph "Coroutines"
        S1 --> Y[YieldContext\nasio::spawn]
    end

Critical rules:

• Never block the IO thread.
• Cross-thread shared state: std::shared_ptr / std::weak_ptr for object lifetime.
• Lifecycle flags: std::atomic<bool> with compare_exchange_strong(memory_order_acq_rel).
• Executors::Awaitable<T>: bridge for OS-thread callers waiting on IO-thread results. Await() must never be called from an IO thread.
• nullof<YieldContext>() returns a sentinel address for non-coroutine callers. Used deliberately in DoKeepAlived() and DNS paths.

YieldContext state transitions:

stateDiagram-v2
    [*] --> RESUMED: spawn
    RESUMED --> SUSPENDING: yield requested
    SUSPENDING --> SUSPENDED: CAS success
    SUSPENDED --> RESUMING: completion handler
    RESUMING --> RESUMED: CAS success

Full reference: docs/CONCURRENCY_MODEL.md

Errors are represented as typed error codes defined in ppp/diagnostics/ErrorCodes.def via X-macro. There are 628 error codes.

flowchart LR
    A[Failure detected] --> B[SetLastErrorCode\nError::XYZ]
    B --> C[Return sentinel\nnullptr / false / -1]
    C --> D[Caller propagates\nsentinel upward]
    D --> E[Top-level handler\ndispatches to ErrorHandler]

Error code categories (partial):

Normal-operation benign codes (high frequency, not problems):

• GenericCanceled, GenericTimeout, SocketDisconnected, SessionDisposed, FirewallSegmentBlocked

Problem-indicating codes (require operator attention):

• AppPrivilegeRequired, TunnelOpenFailed, ProtocolCipherMismatch, AuthCredentialInvalid, InternalLogicStateCorrupted

Atomic error snapshot: high 32 bits = truncated millisecond timestamp; low 32 bits = error code value.

Full reference: docs/ERROR_CODES.md, docs/ERROR_HANDLING_API.md

The Go backend (go/) is a completely separate optional process. It provides managed authentication and webhook capability that the C++ server calls over WebSocket.

sequenceDiagram
    participant C as C++ Server
    participant G as Go Management Service
    participant DB as Auth/Policy Database

    C->>G: WebSocket connect
    G-->>C: Connected
    C->>G: Auth request (session_id, credentials)
    G->>DB: Credential lookup
    DB-->>G: Policy record
    G-->>C: Auth result + bandwidth policy
    C->>C: Apply policy to session

Build and run independently:

cd go && go build -o ppp-go .
./ppp-go --config=./management.json

The C++ server enables managed mode by setting server.managed to the Go service address in appsettings.json. Without the Go backend, the server runs in standalone mode with no external auth.

Full reference: docs/MANAGEMENT_BACKEND.md

Security operates at two independent layers:

Additional obfuscation features (configured via key.*):

Supported cipher algorithms: AES-128-CFB, AES-256-CFB, and variants. The kf, kx, kl, kh fields in key control the NOP handshake timing and framing shape, making traffic fingerprinting significantly harder.

Full reference: docs/SECURITY.md

• Example configuration values are examples, not production defaults.
• Linux is the most complete server-side IPv6 data-plane target.
• The documentation uses long-form bilingual writing because the system is implementation-heavy.
• main.cpp is the fastest entry point for understanding how the pieces connect.
• C++17 strictly — no C++20 features anywhere in the codebase.
• All code uses ppp:: type aliases (ppp::string, ppp::vector<T>, ppp::Byte, etc.) defined in ppp/stdafx.h.
• Memory allocation routes through ppp::Malloc / ppp::Mfree, which use jemalloc when JEMALLOC is defined.
• Platform guards use repo macros only: _WIN32, _LINUX, _MACOS, _ANDROID. Never use #ifdef __linux__ or #ifdef _MSC_VER in ppp/ shared files.
• All public APIs are documented with Doxygen (@brief, @param, @return, @note, @warning).
• All functions aim to be noexcept. Exceptions are caught and converted to error codes at the boundary.

OPENPPP2 includes a full IPv6 lease management and data-plane forwarding system on the server side. This is one of the more complex subsystems.

graph TD
    A[Client connects\nrequests IPv6] --> B[VirtualEthernetSwitcher\nLease allocator]
    B --> C{Pool available?}
    C -->|yes| D[Assign /128 lease\nfrom configured prefix]
    C -->|no| E[IPv6LeaseConflict error]
    D --> F[NDP Proxy\nannounce to upstream]
    F --> G[IPv6 Transit Plane\nroute packets]
    G --> H[Client virtual NIC\nreceives IPv6]
    B --> I[Lease aging\nOnTick]
    I -->|expired| J[Release lease\nrevoke NDP]

stateDiagram-v2
    [*] --> Requested: client DoIPv6 opcode
    Requested --> Allocated: pool assigns /128
    Allocated --> Active: NDP proxy announced
    Active --> Renewing: renewal request
    Renewing --> Active: renewed
    Active --> Expired: OnTick aging check
    Expired --> Released: NDP revoked, pool freed
    Released --> [*]

Key facts:

• Server maintains a lease table keyed by (session_id, ipv6_address).
• NDP proxy announces leased addresses to the upstream router so return traffic is routed correctly.
• IPv6 lease aging runs in OnTick() — not in a separate thread.
• Linux is the primary platform for IPv6 data-plane. Windows and Android have limited IPv6 support in this context.

Full reference: docs/IPV6_LEASE_MANAGEMENT.md, docs/IPV6_TRANSIT_PLANE.md, docs/IPV6_NDP_PROXY.md, docs/IPV6_CLIENT_ASSIGNMENT.md

OPENPPP2 includes a built-in terminal UI (ppp/app/ConsoleUI.h). It runs on two dedicated threads (render and input), both outside the Boost.Asio io_context pool.

graph LR
    subgraph "ConsoleUI"
        RI[render thread] --> RD{dirty flag?}
        RD -->|yes| DRAW[redraw screen]
        RD -->|no| WAIT[wait up to 100ms\nrender_cv_]
        II[input thread] --> READ[read keystroke]
        READ --> CMD[dispatch command]
        CMD --> DF[set dirty flag\nnotify render_cv_]
    end
    subgraph "io_context threads"
        RT[Runtime\nOnTick] --> DF2[publish dirty flag]
        DF2 --> DF
    end

TUI layout:

• Fixed 10-row header (connection status, session stats, bandwidth)
• Scrollable 3-section body: info / command output / input history
• Fixed 5-row footer (input prompt)
• Alternate screen buffer (\x1b[?1049h on enter, \x1b[?1049l on exit)
• Real cursor hidden for full TUI lifetime
• Minimum terminal size: 40 columns × 20 rows

Full reference: docs/TUI_DESIGN.md

Beyond tunneling Ethernet frames, OPENPPP2 supports two special forwarding paths: NAT and Static.

flowchart TD
    A[IP packet from client TAP] --> B{Routing decision}
    B -->|default route| C[FRP path\nTCP/UDP per-connection]
    B -->|static route match| D[Static path\nmask_id non-zero\nfsid 128-bit]
    B -->|NAT rule match| E[NAT path\nserver-side NAT table]
    C --> F[Server forwards\nto real destination]
    D --> G[Server static\nforwarding table]
    E --> H[Server NAT\ntranslation + forward]

Static packet constraints:

• mask_id must be non-zero (identifies the static route entry).
• session_id sign encodes address family: positive = UDP, negative = IP.
• fsid is a 128-bit identifier (Int128) for the flow.
• Checksum covers header + payload after all transforms.
• Pack pipeline has 14 steps; unpack exactly reverses them.

Full reference: docs/PACKET_FORMATS.md, docs/TUNNEL_DESIGN.md

The MUX subsystem allows multiple logical sub-connections to share a single ITransmission carrier.

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: PacketAction_MUXON (VLAN tag = channel_id)
    S-->>C: MUX channel open ACK
    C->>S: PacketAction_MUX (data, VLAN tag = channel_id)
    S->>S: Demux by VLAN tag
    S->>S: Forward to sub-connection
    C->>S: PacketAction_MUX (another channel)
    Note over C,S: Multiple channels share one ITransmission

Key facts:

• VLAN tag in the MUX packet header identifies the logical channel.
• nmux low bit in the handshake enables MUX mode.
• All sub-connections share the same underlying TCP/WS connection.
• Reduces connection setup overhead when many concurrent streams are needed.

Full reference: docs/LINKLAYER_PROTOCOL.md

A full end-to-end packet journey from client application to remote host and back:

sequenceDiagram
    participant APP as Client App
    participant TAP as Virtual TAP
    participant LWIP as lwIP VNetstack
    participant EX as VEthernetExchanger
    participant TX as ITransmission
    participant SRV as Server
    participant DST as Destination

    APP->>TAP: write IP packet
    TAP->>LWIP: OnInput frame
    LWIP->>EX: TCP/UDP/ICMP hook
    EX->>TX: DoFrpEntry / DoFrpPush / DoFrpSendTo
    TX->>TX: frame + mask + delta + cipher
    TX->>SRV: encrypted bytes
    SRV->>SRV: decipher + decode
    SRV->>DST: forward to real host
    DST-->>SRV: reply
    SRV-->>TX: re-encrypt + send
    TX-->>EX: decipher + OnFrpPush
    EX-->>LWIP: inject reply
    LWIP-->>TAP: Output frame
    TAP-->>APP: IP reply packet

Full reference: docs/PACKET_LIFECYCLE.md

OPENPPP2 uses an event-driven state machine (EDSM) architecture at every level: per-session, per-connection, per-transmission, and at the application lifecycle level.

stateDiagram-v2
    [*] --> Idle
    Idle --> Connecting: Connect()
    Connecting --> Handshaking: socket connected
    Handshaking --> Running: handshaked_ = true
    Running --> Reconnecting: transport error
    Running --> Stopping: Dispose() called
    Reconnecting --> Connecting: restart delay elapsed
    Stopping --> [*]: cleanup complete

Each state transition is driven by an Asio completion handler or a coroutine resume, not by a polling loop. The state machine never advances from a blocked OS thread.

State machine properties:

• All transitions happen on an asio::strand to avoid concurrent state mutations.
• compare_exchange_strong guards lifecycle flag transitions.
• Dispose() is idempotent: calling it multiple times is safe.
• Objects are kept alive by std::shared_ptr reference counting until all in-flight coroutines complete.

Full reference: docs/EDSM_STATE_MACHINES.md

Session identity is packed into the framed transmission stream. The TRANSMISSION_PACK_SESSIONID document covers the exact byte layout.

graph LR
    subgraph "First packet (extended header)"
        H1[4 bytes: length+flags] --> H2[3 bytes: session ID extension]
        H2 --> P[payload]
    end
    subgraph "Subsequent packets (simple header)"
        S1[4 bytes: length+flags] --> SP[payload]
    end
    H1 --> FT[frame_tn_ / frame_rn_ counter\ncontrols header mode]

The transition from extended to simple header is controlled by frame_tn_ (transmit) and frame_rn_ (receive) counters. The first packet in each direction uses the extended header; all subsequent packets use the simple 4-byte header.

Full reference: docs/TRANSMISSION_PACK_SESSIONID.md

graph LR
    C1[Client A] -->|ppp://server:20000/| S[ppp server]
    C2[Client B] -->|ppp://server:20000/| S
    C3[Client C] -->|ppp://ws/server:20000/| S
    S --> I[Internet]

graph LR
    C1[Client A] --> S[ppp server]
    C2[Client B] --> S
    S -->|WebSocket auth| G[ppp-go management]
    G --> DB[(User/Policy DB)]
    S --> I[Internet]

graph LR
    C1[Client] -->|HTTPS/WSS| CDN[CDN or reverse proxy]
    CDN -->|WS| S[ppp server]
    S --> I[Internet]

The cdn field in appsettings.json configures port-mode obfuscation to make the traffic appear as regular HTTP/WebSocket to intermediate proxies.

Full reference: docs/DEPLOYMENT.md

The main runtime tick fires on a configurable interval (default ~1 second). Each tick:

1. Refresh bandwidth / session statistics.
2. Check tunnel liveness (keepalive timeout detection).
3. Age out stale sessions (server).
4. Age out expired IPv6 leases (server).
5. Publish dirty flag to TUI render thread.
6. Reschedule via NextTickAlwaysTimeout(false).

Full reference: docs/OPERATIONS.md

The diagnostics subsystem provides structured error reporting without logging.

flowchart TD
    A[Error occurs\nin any subsystem] --> B[SetLastErrorCode\nError::XYZ\nthread-local]
    B --> C[Atomic snapshot\nhigh32=timestamp\nlow32=error_code]
    C --> D[ErrorHandler::Dispatch\nregistered callbacks]
    D --> E[TUI error display]
    D --> F[Management backend\nerror reporting]
    D --> G[Caller return value\nsentinel propagation]

The error snapshot is atomic: it can be read from any thread without locking. The timestamp is truncated milliseconds, sufficient for ordering events within a session.

Full reference: docs/DIAGNOSTICS_ERROR_SYSTEM.md, docs/ERROR_CODES.md