# cloudflare/ipvs architecture

> Architecture diagram of the GitHub repository cloudflare/ipvs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/ipvs
- Repository: https://github.com/cloudflare/ipvs

## Overview

##### Project type and purpose
- This is an open-source Go library (package “ipvs”) that provides programmatic access to Linux’s IPVS subsystem via netlink and genetlink.
- Its goal is to allow Go programs to manage IPVS services and destinations without requiring the `ipvsadm` CLI or CGO.

##### File structure
- Top-level files:
- client.go, client_linux.go, client_others.go, client_linux_test.go – the public client API and OS-specific implementations
- netmask/ – standalone subpackage for IP network mask operations
- internal/cipvs/ – core logic for interacting with IPVS over netlink/genetlink
- go.mod, go.sum – Go module definitions
- .github/workflows/ – CI pipelines (Go build, tests, semgrep linting)
- tools.go, zz_generated.stringer.go – code-generation and helper files
- testdata/ – rapid test fixtures
- Patterns:
- Layered modular design (public API, internal implementation, utility subpackage)
- OS abstraction (generic vs. Linux vs. others in separate source files)
- Encapsulation (core protocol code hidden under internal/cipvs)

##### README for additional insights
- Confirms use of mdlayher/netlink and mdlayher/genetlink to talk to the kernel
- Emphasizes library usage, e.g., “programmatic access to Linux’s IPVS,” no mention of GUI or CLI subcommands beyond tests and examples

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Path
    UA["User Application"]:::external
    subgraph "ipvs Library"
        API["ipvs.Client (client.go)"]:::library
        API_Linux["client_linux.go"]:::library
        API_Others["client_others.go"]:::library
        subgraph "API Tests"
            API_Test["client_linux_test.go"]:::ci
            Example_Test["example_test.go"]:::ci
        end
        subgraph "Internal Implementation"
            Core["internal/cipvs"]:::internal
        end
        subgraph "Netmask Utility"
            Mask1["mask.go"]:::library
            Mask2["mask_go124.go"]:::library
            MaskTest["mask_test.go"]:::ci
            MaskData["TestNetmask_TextMarshaller"]:::ci
        end
    end

    %% External Dependencies
    NL["mdlayher/netlink"]:::external
    GNL["mdlayher/genetlink"]:::external
    Kernel["Linux Kernel IPVS"]:::external

    %% Development & CI Path
    subgraph "Development Tools & CI"
        GoMod["go.mod/go.sum"]:::ci
        Tools["tools.go/zz_generated.stringer.go"]:::ci
        CI1[".github/workflows/go.yaml"]:::ci
        CI2[".github/workflows/semgrep.yml"]:::ci
        GeneralData["TestService_PackUnpack"]:::ci
    end

    %% Relationships
    UA -->|imports| API
    API -->|build tag linux| API_Linux
    API -->|build tag others| API_Others
    API -->|delegates| Core
    Core -->|uses| Mask1
    Core -->|uses| Mask2
    MaskTest -->|tests| Mask1
    Core -->|sends/receives| NL
    Core -->|sends/receives| GNL
    NL -->|kernel calls| Kernel
    GNL -->|kernel calls| Kernel
    API_Test -->|tests API| API
    Example_Test -->|tests API| API
    GeneralData -->|fixture| API_Test

    GoMod -->|module definitions| API
    Tools -->|code generation| API
    CI1 -->|CI build/test| API
    CI2 -->|CI lint| API

    %% Click Events
    click API "https://github.com/cloudflare/ipvs/blob/master/client.go"
    click API_Linux "https://github.com/cloudflare/ipvs/blob/master/client_linux.go"
    click API_Others "https://github.com/cloudflare/ipvs/blob/master/client_others.go"
    click API_Test "https://github.com/cloudflare/ipvs/blob/master/client_linux_test.go"
    click Example_Test "https://github.com/cloudflare/ipvs/blob/master/example_test.go"
    click Core "https://github.com/cloudflare/ipvs/blob/master/internal/cipvs/const.go"
    click Mask1 "https://github.com/cloudflare/ipvs/blob/master/netmask/mask.go"
    click Mask2 "https://github.com/cloudflare/ipvs/blob/master/netmask/mask_go124.go"
    click MaskTest "https://github.com/cloudflare/ipvs/blob/master/netmask/mask_test.go"
    click MaskData "https://github.com/cloudflare/ipvs/tree/master/netmask/testdata/rapid/TestNetmask_TextMarshaller"
    click GeneralData "https://github.com/cloudflare/ipvs/tree/master/testdata/rapid/TestService_PackUnpack"
    click CI1 "https://github.com/cloudflare/ipvs/blob/master/.github/workflows/go.yaml"
    click CI2 "https://github.com/cloudflare/ipvs/blob/master/.github/workflows/semgrep.yml"
    click GoMod "https://github.com/cloudflare/ipvs/blob/master/go.mod"
    click Tools "https://github.com/cloudflare/ipvs/blob/master/tools.go"

    %% Styles
    classDef library fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef internal fill:#dcedc8,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef ci fill:#f0f0f0,stroke:#333,stroke-width:1px
```
