# containers/gvisor-tap-vsock architecture

> Architecture diagram of the GitHub repository containers/gvisor-tap-vsock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containers/gvisor-tap-vsock
- Repository: https://github.com/containers/gvisor-tap-vsock

## Overview

- Host Proxy (gvproxy): This is the central daemon that listens on one or more endpoints (TCP, UNIX, vsock) and bridges communications. Represent it as a main service.
- Supporting Binaries/Tools: Include related executables such as qemu-wrapper, ssh-over-vsock, win-sshproxy, and test-companion, which help integrate or test various networking scenarios.
- Internal Packages: Optionally break down internal architectural layers (found in the pkg folder) into:
- Client and Transport Layers (e.g., pkg/client, pkg/transport): These handle the lower-level connection, dialing, listening, tunneling.
- Services and Virtual Network Functions (e.g., pkg/services/dhcp, pkg/services/dns, pkg/virtualnetwork): These implement the DHCP server, DNS service, port forwarding logic, and packet manipulation.
- SSH Components (pkg/sshclient) and Utilities (pkg/utils, pkg/fs): These support non-network functionalities.
- API Exposure: Show the HTTP API endpoint that is available on the host when using the --listen or --services options. This component is used for retrieving stats, managing dynamic ports, and even tunneling.

##### Interactions and Flow
- From the VM’s tap device to the host’s gvproxy daemon via communication channels (TCP/unix/vsock).
- How the gvproxy uses its internal modules to translate Ethernet packets into API calls for DNS queries, DHCP events, or port-forwarding requests.
- The flow from external networks or clients to the host’s API for exposing ports and then routing responses back to the VM’s network stack.

##### Architectural Patterns and Design Principles
- Modularity: The clear separation into commands (in the cmd directory) and reusable packages (pkg) shows a modular architecture where networking, transport, and services are abstracted.
- API-Centric Design: Emphasize the HTTP API service that is used both for exposing services (like dynamic port forwarding) and for monitoring/statistics.
- Extensibility: Note how components such as DNS, DHCP, and tunneling are strictly separated so that future modifications or integrations (for different virtualization platforms) are manageable.

##### Relevant Technologies/Frameworks
- Go as the core language and structure (shown via file organization and modules such as go.mod).
- Use of vsock for Windows integration and general cross-platform support. Mark the conditional deployment paths for Linux, macOS, and Windows.

##### Be Detailed But Organized
- Every component has a clear function, and group similar functionalities together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VM Side
    subgraph "VM Side"
        VMTap("VM Tap Interface"):::vm
        TapPkg("Tap Package"):::vm
    end

    %% Host Side
    subgraph "Host Side"
        GVProxy("Host Proxy (gvproxy)"):::host
        API("HTTP API Endpoint"):::host

        subgraph "Internal Layers"
            Client("Client Layer"):::client
            Transport("Transport Layer"):::client
            subgraph "Services"
                DHCP("DHCP Service"):::service
                DNS("DNS Service"):::service
                Forwarder("Port Forwarding"):::service
                VirtualNetwork("Virtual Network Services"):::service
            end
            SSHComp("SSH Components"):::client
            Utils("Utilities"):::client
            FSD("FS Helpers"):::client
        end
    end

    %% Supporting Binaries
    subgraph "Supporting Binaries"
        QEMU("QEMU Wrapper"):::binary
        SSHVsock("SSH over vsock"):::binary
        WinSSH("Win-sshproxy"):::binary
        TestComp("Test Companion"):::binary
    end

    %% External Entity
    Internet("Internet"):::service

    %% Data Flow from VM to Host
    VMTap -->|"EthernetPacket"| GVProxy
    TapPkg -.-> VMTap

    %% Host Proxy Internal Invocations
    GVProxy -->|"APIRequest"| API
    API -->|"ForwardTo"| Internet
    GVProxy -->|"Dial"| Client
    GVProxy -->|"Dial"| Transport
    GVProxy -->|"Invoke"| DHCP
    GVProxy -->|"Invoke"| DNS
    GVProxy -->|"Invoke"| Forwarder
    GVProxy -->|"Invoke"| VirtualNetwork
    GVProxy -->|"Tunnel"| SSHComp

    %% Supporting Binaries Interaction
    QEMU -->|"Integrate"| GVProxy
    SSHVsock -->|"Integrate"| GVProxy
    WinSSH -->|"Integrate"| GVProxy
    TestComp -->|"TestCalls"| GVProxy

    %% Internal Utilities Connection
    Utils -->|"FS Call"| FSD

    %% Click Events
    click GVProxy "https://github.com/containers/gvisor-tap-vsock/blob/main/cmd/gvproxy/main.go"
    click VMTap "https://github.com/containers/gvisor-tap-vsock/blob/main/cmd/vm/main_linux.go"
    click TapPkg "https://github.com/containers/gvisor-tap-vsock/tree/main/pkg/tap/"
    click QEMU "https://github.com/containers/gvisor-tap-vsock/blob/main/cmd/qemu-wrapper/main.go"
    click SSHVsock "https://github.com/containers/gvisor-tap-vsock/blob/main/cmd/ssh-over-vsock/main.go"
    click WinSSH "https://github.com/containers/gvisor-tap-vsock/blob/main/cmd/win-sshproxy/main.go"
    click TestComp "https://github.com/containers/gvisor-tap-vsock/blob/main/cmd/test-companion/main.go"
    click Client "https://github.com/containers/gvisor-tap-vsock/blob/main/pkg/client/client.go"
    click Transport "https://github.com/containers/gvisor-tap-vsock/tree/main/pkg/transport/"
    click DHCP "https://github.com/containers/gvisor-tap-vsock/blob/main/pkg/services/dhcp/dhcp.go"
    click DNS "https://github.com/containers/gvisor-tap-vsock/blob/main/pkg/services/dns/dns.go"
    click Forwarder "https://github.com/containers/gvisor-tap-vsock/tree/main/pkg/services/forwarder/"
    click VirtualNetwork "https://github.com/containers/gvisor-tap-vsock/tree/main/pkg/virtualnetwork/"
    click SSHComp "https://github.com/containers/gvisor-tap-vsock/tree/main/pkg/sshclient/"
    click Utils "https://github.com/containers/gvisor-tap-vsock/blob/main/pkg/utils/retry.go"
    click FSD "https://github.com/containers/gvisor-tap-vsock/tree/main/pkg/fs/"

    %% Style Definitions
    classDef host fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef vm fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef service fill:#f94144,stroke:#333,stroke-width:2px;
    classDef client fill:#577590,stroke:#333,stroke-width:2px;
    classDef binary fill:#277da1,stroke:#fff,stroke-width:2px;
```
