add revm dockerd docker api proxy doc

Signed-off-by: ihexon <14349453+ihexon@users.noreply.github.com>

Author: ihexon

.idea/.gitignore

@@ -0,0 +1,318 @@
+---
+title: "revm 中的 TunnelHostUnixToGuest 设计逻辑"
+summary: "从设计角度记录 revm container mode 中 TunnelHostUnixToGuest 的位置：为什么需要 host Unix socket 到 guest TCP 的代理、为什么通过 gvproxy 建 tunnel，以及为什么 CloseWrite 是流式 Docker/Podman API 的关键语义。"
+description: "从设计角度记录 revm container mode 中 TunnelHostUnixToGuest 的位置：为什么需要 host Unix socket 到 guest TCP 的代理、为什么通过 gvproxy 建 tunnel，以及为什么 CloseWrite 是流式 Docker/Podman API 的关键语义。"
+date: 2026-05-13
+draft: false
+categories:
+  - "linuxvm"
+tags:
+  - "revm"
+  - "dockerd"
+  - "gvproxy"
+  - "podman"
+  - "docker"
+  - "network"
+---
+
+`TunnelHostUnixToGuest` 是一个Podman API 代理函数，它只做一件事：
+
+把 host 上一个 Unix socket 收到的连接，通过 gvproxy tunnel 转发到 guest VM 里的 Podman API TCP 端口。
+
+这篇文章记录几个关键的设计点：host/guest 边界、CLI 兼容性、网络后端隔离、连接生命周期，以及 Docker/Podman hijack stream 里的 half-close 语义。
+
+<!--more-->
+
+## 问题背景
+
+`revm` container mode 想提供一个轻量的容器 VM：host 上运行 `docker` / `podman` CLI，真正的容器环境跑在 libkrun 启动的 Linux guest 里。
+
+从用户视角看，它应该像这样工作：
+
+```sh
+./dockerd --id dev
+
+export DOCKER_HOST=unix://$HOME/.cache/revm/dev/socks/podman-api.sock
+docker ps
+docker run --rm alpine uname -a
+```
+
+这里的 `dockerd` 是 `revm` 的 CLI 入口，不是 Docker 官方的 daemon。VM 里真正响应容器 API 的是 Podman API service。Podman 提供 Docker-compatible API，因此 Docker CLI 可以通过这个 socket 工作。
+
+这里有一个接口形态不匹配的问题：
+
+```text
+Docker/Podman CLI 习惯连接 host 上的 Unix socket
+Podman API 实际运行在 guest VM 里的 TCP 端口
+```
+
+`TunnelHostUnixToGuest` 就是在这个不匹配处做边界适配。
+
+## 核心链路
+
+container mode 下的代理链路可以概括为：
+
+{{< mermaid >}}
+flowchart LR
+    cli["docker / podman CLI"]
+    hostSock["host podman-api.sock"]
+    tunnelFn["TunnelHostUnixToGuest"]
+    gvproxySock["host gvproxy socket"]
+    gvproxy["gvproxy"]
+    guestAPI["guest Podman API<br/>192.168.127.2:port"]
+
+    cli --> hostSock
+    hostSock --> tunnelFn
+    tunnelFn --> gvproxySock
+    gvproxySock --> gvproxy
+    gvproxy --> guestAPI
+{{< /mermaid >}}
+
+这条链路里有三个重要边界：
+
+```text
+CLI 边界：host CLI 只看到 Unix socket
+VM 边界：容器 API 实际在 guest 内
+网络边界：host 进程不能直接假设 guest 网络如何实现
+```
+
+`TunnelHostUnixToGuest` 的价值在于把这三个边界收在一个很窄的地方处理。外部 CLI 不需要知道 VM，guest Podman API 不需要知道 host Unix socket，gvproxy 负责具体的 host/guest 网络穿透。
+
+## 为什么 host 上要暴露 Unix socket
+
+Docker CLI 和 Podman CLI 都天然支持 Unix socket：
+
+```sh
+export DOCKER_HOST=unix:///path/to/socket
+export CONTAINER_HOST=unix:///path/to/socket
+```
+
+因此 revm 选择在 host 上暴露一个 `podman-api.sock`，而不是要求用户连接某个随机 TCP 端口。
+
+这个选择有几个好处：
+
+```text
+符合 Docker/Podman CLI 的默认使用模型
+避免在 host 上开放额外 TCP 监听
+socket 文件可以自然跟随 session 目录管理
+权限可以用文件系统权限表达
+```
+
+也就是说，host Unix socket 是对用户友好的 API surface。它是 revm 对外承诺的接口，而不是内部实现细节。
+
+## 为什么 guest 侧是 TCP
+
+在 gvisor 网络模式下，guest 里的 Podman API 监听在一个 TCP 地址上。revm 里通常是：
+
+```text
+192.168.127.2:<podman-api-port>
+```
+
+这不是偶然的。gvproxy/gvisor-tap-vsock 本来就是在 host 和 guest 之间提供虚拟网络能力。通过它转发到 guest TCP 端口，比尝试直接暴露 guest Unix socket 更符合这套网络模型。
+
+所以最终形成了一个有意识的接口转换：
+
+```text
+host Unix socket  ->  gvproxy tunnel  ->  guest TCP port
+```
+
+`TunnelHostUnixToGuest` 的名字也正好描述了这个方向：从 host 侧 Unix socket，到 guest 里的服务。
+
+## 为什么中间需要 gvproxy tunnel
+
+host 进程不能直接 `Dial("tcp", "192.168.127.2:port")` 并假设它一定能工作。guest 的地址存在于 gvisor-tap-vsock 管理的虚拟网络里，host/guest 通信需要通过 gvproxy 的控制 socket 建立 tunnel。
+
+所以 `TunnelHostUnixToGuest` 的每条连接大致经历这些步骤：
+
+{{< mermaid >}}
+flowchart TD
+    accept["accept client connection"]
+    dial["dial gvproxy socket"]
+    request["request tunnel"]
+    note["POST /tunnel?ip=guest&port=podman"]
+    bridge["bridge two streams"]
+    finish["finish on EOF or cancellation"]
+
+    accept --> dial
+    dial --> request
+    request -.-> note
+    request --> bridge
+    bridge --> finish
+{{< /mermaid >}}
+
+这里的 `request tunnel` 对应的是 gvproxy 的 `/tunnel` 能力。revm 不需要理解 gvisor 网络栈细节，只需要告诉 gvproxy：
+
+```text
+请把这条连接转发到 guest 的 192.168.127.2:<podman-api-port>
+```
+
+这体现了一个很重要的设计原则：revm 不越过 gvproxy 直接操作 guest 网络，而是把 guest 网络穿透交给网络后端。
+
+## TunnelHostUnixToGuest 的职责边界
+
+我觉得这段代码最值得保留的设计点，是它的职责足够窄。
+
+它做：
+
+```text
+创建 host Unix listener
+accept CLI 连接
+为每条连接 dial gvproxy
+通过 gvproxy 建立到 guest IP:port 的 tunnel
+双向复制字节
+处理 context cancellation
+传播 half-close
+```
+
+它不做：
+
+```text
+不解析 Docker API
+不理解 Podman API
+不关心容器命令是什么
+不管理 guest Podman 生命周期
+不决定网络模式如何实现
+```
+
+这很重要。因为 Docker API 里既有普通 HTTP 请求，也有 attach/exec 这种 hijacked stream。如果 proxy 层开始理解上层协议，很容易把一个简单的字节隧道写成半个 Docker daemon。
+
+`TunnelHostUnixToGuest` 的设计哲学是：只做传输层适配，不进入应用层语义。
+
+## 为什么不是一个通用 TCP proxy
+
+它确实很像通用 proxy，但它不是完全通用的 TCP proxy。
+
+它服务的是一个明确场景：
+
+```text
+host Docker/Podman CLI
+通过 Unix socket
+访问 guest Podman API
+并且需要支持 Docker hijack stream
+```
+
+因此它的设计不是“抽象到可以代理世界上一切 TCP 连接”，而是“足够通用地转发字节，同时准确保留 Docker/Podman CLI 需要的连接语义”。
+
+这也是 `CloseWrite` 变得关键的原因。
+
+## CloseWrite 不是细节
+
+在普通 request/response HTTP 里，很多人会把连接生命周期想得很简单：
+
+```text
+请求发完
+响应读完
+连接关闭
+```
+
+但 Docker/Podman API 里有 hijacked stream。典型场景是：
+
+```sh
+docker attach
+docker exec -i
+docker run -it
+```
+
+这些场景里，连接是双向流：
+
+```text
+stdin 方向：CLI -> guest process
+stdout/stderr 方向：guest process -> CLI
+```
+
+这两个方向的生命周期不一定同时结束。一个非常典型的状态是：
+
+```text
+stdin 已经 EOF
+stdout/stderr 还要继续返回
+```
+
+如果 proxy 在 stdin EOF 时直接 `Close()` 整条连接，就会把 stdout/stderr 也切断。这会造成输出截断。
+
+如果 proxy 完全不传播 stdin EOF，guest 里的进程可能永远不知道输入结束。例如：
+
+```sh
+echo hello | docker exec -i container cat
+```
+
+`cat` 需要看到 stdin EOF 才能退出。如果 EOF 停在 proxy 这里，guest 进程可能继续等输入。
+
+正确语义是 half-close：
+
+```text
+stdin EOF -> CloseWrite(tunnelConn)
+stdout/stderr 方向继续保留
+```
+
+所以 `CloseWrite` 不是一个“小优化”，而是 Docker/Podman stream 能否正确结束的协议语义。
+
+## Docker CLI 也是这么想的
+
+Docker CLI 的 hijack stream 逻辑也是这个模型。
+
+它会同时启动 input 和 output copy。input copy 结束后，Docker CLI 会调用 hijacked response 的 `CloseWrite()`，向 daemon 表达：
+
+```text
+我不会再写 stdin 了
+但我还要继续读 stdout/stderr
+```
+
+之后，如果还有 output stream，Docker CLI 会继续等待 output 结束，而不是因为 input 结束就退出。
+
+也就是说，Docker CLI 本身就依赖 half-close：
+
+{{< mermaid >}}
+sequenceDiagram
+    participant CLI as Docker CLI
+    participant Proxy as revm proxy
+    participant Guest as guest Podman API
+
+    CLI->>Proxy: stdin bytes
+    Proxy->>Guest: forward stdin bytes
+    CLI-->>Proxy: stdin EOF / CloseWrite
+    Proxy-->>Guest: CloseWrite tunnel side
+    Guest->>Proxy: stdout / stderr continues
+    Proxy->>CLI: forward output
+    Guest-->>Proxy: output EOF
+    Proxy-->>CLI: CloseWrite client side
+{{< /mermaid >}}
+
+因此 revm proxy 的责任不是隐藏 half-close，而是把 half-close 正确传过去。
+
+## 设计总结
+
+`TunnelHostUnixToGuest` 的设计可以压缩成一句话：
+
+```text
+在不理解 Docker/Podman API 的前提下，把 host CLI 期望的 Unix socket 连接，可靠地映射成 guest Podman API 的 TCP stream。
+```
+
+它的几个核心取舍是：
+
+```text
+对外暴露 Unix socket，因为 CLI 生态天然支持
+对内使用 guest TCP，因为 gvisor/gvproxy 的网络模型适合这样转发
+通过 gvproxy tunnel 穿过 host/guest 网络边界
+只做字节转发，不解析 Docker API
+保留 half-close，因为 Docker hijack stream 依赖它
+用 context cancellation 统一回收连接资源
+把不支持的网络组合挡在更早的配置阶段
+```
+
+所以这段代码的重点不是“怎么 copy 两个 conn”，而是边界设计：
+
+{{< mermaid >}}
+flowchart TD
+    api["host-facing API<br/>Unix socket"]
+    adapter["TunnelHostUnixToGuest<br/>boundary adapter"]
+    backend["network backend<br/>gvproxy tunnel"]
+    guest["guest service<br/>Podman API TCP"]
+    stream["stream semantics<br/>half-close"]
+
+    api --> adapter
+    adapter --> backend
+    backend --> guest
+    stream -.-> adapter
+{{< /mermaid >}}
+
+只要这个边界保持干净，revm 的 container mode 就可以继续把复杂性压在内部，同时让外部 CLI 看到一个简单、熟悉的本地 socket。