# Proxy Pool Mermaid 图集

本图集依据最终需求语义绘制。图中的 100k QPS 是待压测验证的集群目标；Extract
均表示一次性独占发放，不存在 Lease、Renew 或 Release。

## 01 系统上下文

```mermaid
flowchart LR
    Client[Gateway Client] --> LB[Layer 4 Load Balancer]
    ExtractClient[Extract Client] --> Dist[Distribution API]
    Operator[Operator] --> Admin[Admin API]
    LB --> Gateway[Gateway Cluster]
    Gateway --> Internet[Target via Proxy]
    Dist --> Controller[Controller Cluster]
    Admin --> Controller
    Controller --> Provider[Provider APIs]
    Controller --> Checker[Checker Cluster]
    Controller --> PG[(PostgreSQL)]
    Controller --> Redis[(Redis)]
```

## 02 进程职责边界

```mermaid
flowchart TB
    subgraph DataPlane[Data Plane]
      G[proxy-gateway]
      Snap[Immutable Snapshot]
      G --> Snap
    end
    subgraph ControlPlane[Control Plane]
      C[proxy-controller]
      K[proxy-checker]
      C <--> K
    end
    subgraph Tools[Tools]
      L[proxy-loadgen]
    end
    C -->|Snapshot and ownership| G
    G -->|batched outcomes| C
    L --> G
```

## 03 领域模块依赖

```mermaid
flowchart TD
    Cmd[cmd assembly] --> Gateway[gateway modules]
    Cmd --> Controller[controller modules]
    Cmd --> Adapters[adapters]
    Gateway --> Domain[domain]
    Controller --> Domain
    Adapters --> Domain
    Domain -. no import .-> HTTP[(HTTP)]
    Domain -. no import .-> SQL[(SQL)]
    Domain -. no import .-> Redis[(Redis)]
```

## 04 Gateway 请求路径

```mermaid
sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant D as Dispatcher
    participant T as Transport
    participant P as Proxy
    C->>G: HTTP request
    G->>G: auth and admission
    G->>D: acquire route
    D->>D: reserve capacity with CAS
    D-->>G: allocation
    G->>T: execute
    T->>P: dial and handshake
    P-->>T: response
    T-->>C: stream response
    T->>D: release active and report
```

## 05 CONNECT 提交点

```mermaid
stateDiagram-v2
    [*] --> Accepted
    Accepted --> Reserved: Acquire
    Reserved --> Dialing: dial proxy
    Dialing --> Cancelled: fail before commit
    Dialing --> Active: proxy CONNECT succeeds
    Active --> TunnelCommitted: send 200 to client
    TunnelCommitted --> Closed: stream ends
    Cancelled --> [*]
    Closed --> [*]
    note right of TunnelCommitted: transparent replay forbidden
```

## 06 HTTP 安全重试决策

```mermaid
flowchart TD
    F[Attempt failed] --> H{Headers sent to client?}
    H -->|yes| Stop[Do not retry]
    H -->|no| M{Method allowed?}
    M -->|no| Stop
    M -->|GET or HEAD| A{Attempts remain?}
    A -->|no| Stop
    A -->|yes| X[Exclude failed Proxy]
    X --> N[Acquire another Proxy]
```

## 07 Routing 首条命中

```mermaid
flowchart TD
    Req[RouteRequest] --> R1{Rule 1 matches?}
    R1 -->|yes| U1[Use Rule 1 upstream strategy]
    R1 -->|no| R2{Rule 2 matches?}
    R2 -->|yes| U2[Use Rule 2 upstream strategy]
    R2 -->|no| RN{Default rule matches?}
    RN -->|yes| UN[Use default strategy]
    RN -->|no| Reject[Apply onUnavailable]
```

## 08 Sequential 原子切换

```mermaid
sequenceDiagram
    participant F1 as Fetch goroutine 1
    participant F2 as Fetch goroutine 2
    participant U as Upstream A counter
    participant R as Routing state
    F1->>U: empty reaches threshold
    F2->>U: concurrent empty
    U->>R: depleted generation 7
    U->>R: depleted generation 7
    R->>R: CAS A to B succeeds once
    R-->>F1: current B
    R-->>F2: current B
```

## 09 Provider Fetch 调度

```mermaid
flowchart TD
    Signal[Capacity signal] --> SF{Fetch already running?}
    SF -->|yes| Merge[Merge into bounded signal]
    SF -->|no| Leader[Acquire logical leader]
    Leader --> Demand[Recompute slot demand]
    Demand --> Limit{Below maxSize and maxTotal?}
    Limit -->|no| Done[Stop]
    Limit -->|yes| Rate[Wait requestInterval]
    Rate --> Call[Call Provider under maxInFlight]
    Call --> Classify[Classify result]
```

## 10 Fetch 结果分类

```mermaid
flowchart LR
    Response[Provider response] --> Transport{Transport and auth valid?}
    Transport -->|no| Error[Error and backoff]
    Transport -->|yes| Parse{Template and parse valid?}
    Parse -->|no| Error
    Parse -->|yes| Legal{Legal candidates count}
    Legal -->|zero| Empty[Empty plus one]
    Legal -->|positive| New{New after dedupe?}
    New -->|none| Duplicate[Duplicate-only and reset Empty]
    New -->|some| Success[Success and reset Empty]
```

## 11 退避与 Retry-After

```mermaid
stateDiagram-v2
    [*] --> Ready
    Ready --> Calling: rate token acquired
    Calling --> Ready: success or empty
    Calling --> RetryAfter: HTTP 429
    Calling --> Backoff: timeout or server error
    RetryAfter --> Ready: provider deadline reached
    Backoff --> Ready: exponential delay plus jitter
    Backoff --> Open: max attempts exhausted
    Open --> Ready: next scheduled cycle
```

## 12 Pool Reconcile

```mermaid
flowchart TD
    Inventory[Managed inventory] --> Count[Count states and pending expected]
    Capacity[Available slots] --> Need[Compute demand]
    Count --> Bound{pool maxSize reached?}
    Need --> Bound
    Bound -->|yes| NoFetch[Do not fetch]
    Bound -->|no| Quota{fetch maxTotal reached?}
    Quota -->|yes| NoFetch
    Quota -->|no| Fetch[Schedule bounded fetch]
```

## 13 Proxy 生命周期

```mermaid
stateDiagram-v2
    [*] --> FETCHED
    FETCHED --> CHECKING
    CHECKING --> AVAILABLE: passed
    CHECKING --> UNHEALTHY: exhausted
    AVAILABLE --> SUSPECT: meaningful failure
    SUSPECT --> AVAILABLE: recheck passed
    SUSPECT --> UNHEALTHY: failures reached
    AVAILABLE --> DRAINING: expiry or revoke
    AVAILABLE --> EXTRACTED: exclusive transaction
    DRAINING --> EXPIRED: capacity zero
    UNHEALTHY --> REMOVED
    EXTRACTED --> EXPIRED: TTL reached
    EXPIRED --> REMOVED
```

## 14 原子容量转换

```mermaid
flowchart LR
    C0[active A reserved R] --> Check{A plus R below limit?}
    Check -->|no| Full[Reject candidate]
    Check -->|yes CAS| Reserved[active A reserved R plus 1]
    Reserved -->|Commit| Active[active A plus 1 reserved R]
    Reserved -->|Cancel| C0
    Active -->|Release| C0
```

## 15 Worker 所有权

```mermaid
flowchart TB
    Controller[Controller allocator] -->|epoch 12| W1[Worker 1]
    Controller -->|epoch 12| W2[Worker 2]
    P1[Proxy shard A] --> W1
    P2[Proxy shard B] --> W2
    U[Unowned inventory] --> Controller
    W1 -. cannot allocate .-> P2
    W2 -. cannot allocate .-> P1
```

## 16 Snapshot 发布与 ACK

```mermaid
sequenceDiagram
    participant R as Redis Activity Pool
    participant C as Controller
    participant W as Worker
    R->>C: activity or ownership revision 42
    C->>C: build worker snapshot
    C->>W: epoch 8 version 42 checksum
    W->>W: validate and build indexes
    W->>W: atomic swap
    W-->>C: ACK epoch 8 version 42
    C->>R: record worker ACK with TTL
```

## 17 Snapshot 缺口恢复

```mermaid
flowchart TD
    Delta[Receive delta version 45] --> Current{Current version is 44?}
    Current -->|yes| Check[Verify checksum and epoch]
    Current -->|no current 42| Reject[Reject delta]
    Reject --> Full[Request full snapshot]
    Full --> Build[Build indexes in background]
    Check --> Apply[Apply delta atomically]
    Build --> Apply
```

## 18 Snapshot 陈旧状态

```mermaid
stateDiagram-v2
    [*] --> Fresh
    Fresh --> StaleAllowed: controller disconnected
    StaleAllowed --> Fresh: valid snapshot received
    StaleAllowed --> DrainOnly: maxStaleAge exceeded
    DrainOnly --> Fresh: full snapshot and new epoch
    DrainOnly --> Stopped: existing traffic drained
```

## 19 健康任务调度

```mermaid
flowchart TD
    Proxies[Proxy inventory] --> Priority{State priority}
    Priority -->|new| New[Immediate basic check]
    Priority -->|SUSPECT| Fast[Fast recheck]
    Priority -->|stable AVAILABLE| Normal[Normal interval]
    New --> Jitter[Stable hash plus jitter]
    Fast --> Jitter
    Normal --> Jitter
    Jitter --> Bound[maxInFlight semaphore]
    Bound --> Checker[Checker workers]
```

## 20 健康 Observation Reducer

```mermaid
flowchart LR
    Obs[Health Observation] --> Scope{Scope}
    Scope -->|global| Global[Global health reducer]
    Scope -->|route target| Target[Target profile reducer]
    Global --> Consecutive[Consecutive outcome state]
    Consecutive --> Transition[AVAILABLE SUSPECT UNHEALTHY]
    Target --> RouteHealth[Only affected route health]
    RouteHealth -. no direct global delete .-> Transition
```

## 21 Extract partial

```mermaid
sequenceDiagram
    participant C as Client
    participant API as Distribution
    participant R as Redis Activity Pool
    C->>API: count 10 fulfillment partial
    API->>R: atomic extract with filters and reserve
    R-->>API: mark 6 EXTRACTED and return them
    API-->>C: requested 10 returned 6
```

## 22 Extract allOrNothing

```mermaid
sequenceDiagram
    participant C as Client
    participant API as Distribution
    participant R as Redis Activity Pool
    C->>API: count 10 fulfillment allOrNothing
    API->>R: atomic extract with filters and reserve
    R-->>API: insufficient inventory and no mutation
    API-->>C: insufficient inventory and returned 0
```

## 23 Gateway 所有权回收后提取

```mermaid
sequenceDiagram
    participant C as Controller
    participant W as Gateway Worker
    participant R as Redis Activity Pool
    C->>W: mark Proxy DRAINING at epoch 13
    W->>W: stop new allocations
    W-->>C: ACK active 0 reserved 0
    C->>R: atomically clear ownership and extract
    R-->>C: committed exclusive result
```

## 24 reserveForGateway 不变量

```mermaid
flowchart TD
    Eligible[Eligible unowned count] --> Formula[extractable equals eligible minus reserve]
    Reserve[reserveForGateway] --> Formula
    Requested[requested count] --> Min[return min requested and extractable]
    Formula --> Min
    Min --> Result{fulfillment}
    Result -->|partial| Commit[Commit available quantity]
    Result -->|allOrNothing insufficient| Rollback[Return zero]
```

## 25 Redis 独占原子操作

```mermaid
flowchart TD
    Begin[Lua script or Redis Function] --> Select[Filter eligible TTL entries]
    Select --> Enough{Quantity satisfies mode?}
    Enough -->|no allOrNothing| Noop[Return zero without mutation]
    Enough -->|yes or partial| Update[Mark selected entries EXTRACTED]
    Update --> Idempotency[Optionally cache bounded idempotency result]
    Idempotency --> Return[Return proxies with expiry]
```

## 26 并发提取互斥

```mermaid
sequenceDiagram
    participant A as Extract request A
    participant R as Redis Activity Pool
    participant B as Extract request B
    A->>R: execute atomic extraction
    R-->>A: commit EXTRACTED 1 to 10
    B->>R: execute atomic extraction
    R-->>B: commit EXTRACTED 11 to 20
    Note over A,B: no Proxy returned twice
```

## 27 管理面 Outbox 一致性

```mermaid
sequenceDiagram
    participant C as Controller transaction
    participant DB as PostgreSQL
    participant P as Publisher
    participant W as Worker
    C->>DB: management state change plus outbox
    DB-->>C: atomic commit
    P->>DB: read undelivered event
    P->>W: publish versioned event
    W-->>P: idempotent ACK
    P->>DB: mark delivered
```

## 28 配置热更新

```mermaid
flowchart LR
    File[Read revision] --> Parse[Strict parse]
    Parse --> Validate[References regex and security]
    Validate --> Build[Build immutable config]
    Build --> Diff[Diff tasks and resources]
    Diff --> Swap[Atomic swap]
    Swap --> Drain[Drain removed resources]
    Validate -->|error| Keep[Keep old revision]
```

## 29 Gateway 优雅停机

```mermaid
sequenceDiagram
    participant K as Kubernetes
    participant G as Gateway
    participant LB as Load Balancer
    K->>G: SIGTERM
    G->>G: readiness false
    LB->>LB: remove endpoint
    G->>G: reject new connections
    G->>G: drain requests and tunnels
    G->>G: release active capacities
    G-->>K: exit before grace timeout
```

## 30 Controller 优雅停机

```mermaid
flowchart TD
    Term[SIGTERM] --> NotReady[Readiness false]
    NotReady --> StopWrites[Stop new Extract and Admin writes]
    StopWrites --> StopFetch[Stop new Fetch]
    StopFetch --> FinishTx[Commit or rollback current transactions]
    FinishTx --> Flush[Flush outbox and reports]
    Flush --> Lease[Release Provider leader lease]
    Lease --> Exit[Close pools and exit]
```

## 31 Kubernetes 故障域拓扑

```mermaid
flowchart TB
    LB[Load Balancer] --> ZA
    LB --> ZB
    LB --> ZC
    subgraph ZA[Zone A]
      GA1[Gateway]
      CA[Controller]
      KA[Checker]
    end
    subgraph ZB[Zone B]
      GB1[Gateway]
      CB[Controller]
      KB[Checker]
    end
    subgraph ZC[Zone C]
      GC1[Gateway]
      CC[Controller]
      KC[Checker]
    end
```

## 32 Gateway 扩缩决策

```mermaid
flowchart TD
    Metrics[QPS CPU memory connections latency] --> HPA[HPA decision]
    HPA --> Up{Above target?}
    Up -->|yes| ScaleUp[Scale up quickly]
    Up -->|no| Stable{Stable below target for 10m?}
    Stable -->|no| Hold[Hold replicas]
    Stable -->|yes| Capacity{Failure-domain headroom remains?}
    Capacity -->|no| Hold
    Capacity -->|yes| ScaleDown[Scale down at most 10 percent]
```

## 33 网络信任边界

```mermaid
flowchart LR
    Internet --> NLB[Public NLB]
    NLB --> Gateway[Gateway 8080]
    Ingress[Private Ingress] --> Distribution[Distribution 8081]
    Operator[Operator VPN] --> Admin[Admin 8082]
    Monitor[Monitoring namespace] --> Metrics[Metrics 9090]
    Gateway --> PublicTargets[Public targets only]
    Controller[Controller] --> Stores[External PG and Redis]
    Controller --> Providers[Provider APIs]
```

## 34 可观测信号流

```mermaid
flowchart LR
    Gateway -->|bounded metrics| Prom[Prometheus]
    Controller -->|bounded metrics| Prom
    Checker -->|bounded metrics| Prom
    Prom --> Grafana[Grafana dashboards]
    Prom --> Alerts[Alert rules]
    Gateway -->|sampled redacted logs| Logs[Log backend]
    Controller -->|audit events| Audit[(Audit storage)]
    Alerts --> OnCall[On-call]
```

## 35 100k QPS 验证流程

```mermaid
flowchart TD
    Baseline[Measure one Worker on production shape] --> Formula[Compute replicas at 60 percent target]
    Formula --> Warmup[Warm Snapshot and connections]
    Warmup --> Steady[Run 10k steady]
    Steady --> Ramp[Step ramp to 100k]
    Ramp --> Peak[Hold 100k peak window]
    Peak --> Failure[Remove largest failure domain]
    Failure --> Verify[Verify SLO and all invariants]
    Verify --> Evidence[Archive raw metrics config and image digest]
```