Documentation
¶
Overview ¶
Package substrate 是 Docker/Swarm 底座的 moby/client 适配器：把 state.DockerClient 端口翻译为 Docker Engine API 调用。第三方类型 （moby/swarm 结构体）只存在于本包内部，出口一律是核心类型 （state.SubstrateNode / state.ObjectVersion / state.SubstrateEvent）， 错误归一为端口哨兵（state.ErrObjectNotFound / ErrVersionConflict / ErrNotSwarmManager）——架构 §2.8 核心不出现第三方概念。
Index ¶
- type Client
- func (c *Client) Close() error
- func (c *Client) EnsureContainerRunning(ctx context.Context, spec build.DaemonSpec) error
- func (c *Client) EnsureImagePresent(ctx context.Context, image string) error
- func (c *Client) EnsureVolumePresent(ctx context.Context, name string) error
- func (c *Client) ImageDigest(ctx context.Context, ref string) (string, error)
- func (c *Client) InspectImage(ctx context.Context, ref string) (build.ImageInfo, error)
- func (c *Client) ListNodeObservations(ctx context.Context) ([]state.SubstrateNode, error)
- func (c *Client) LoadImage(ctx context.Context, dockerTar io.Reader) error
- func (c *Client) ManagedServiceProcesses(ctx context.Context, app string) ([]string, error)
- func (c *Client) NetworkEnsure(ctx context.Context, name string) error
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) RemoveImage(ctx context.Context, ref string) error
- func (c *Client) ResolveObjectVersion(ctx context.Context, kind state.ObjectKind, id string) (state.ObjectVersion, error)
- func (c *Client) SelfNodeID(ctx context.Context) (string, error)
- func (c *Client) ServiceCreate(ctx context.Context, spec engine.ServiceSpec) error
- func (c *Client) ServiceInspect(ctx context.Context, name string) (engine.ServiceState, error)
- func (c *Client) ServiceList(ctx context.Context, labels map[string]string) ([]engine.ServiceState, error)
- func (c *Client) ServiceRemove(ctx context.Context, name string) error
- func (c *Client) ServiceUpdate(ctx context.Context, name string, spec engine.ServiceSpec) error
- func (c *Client) StreamServiceLogs(ctx context.Context, service string, since time.Time, follow bool) (<-chan LogLine, error)
- func (c *Client) SubscribeEvents(ctx context.Context) (<-chan state.SubstrateEvent, error)
- func (c *Client) SwarmReady(ctx context.Context) error
- func (c *Client) TagImage(ctx context.Context, source, target string) error
- func (c *Client) TaskList(ctx context.Context, serviceName string) ([]engine.TaskState, error)
- func (c *Client) UpdateNodeLabel(ctx context.Context, swarmNodeID, key, value string, ...) error
- type LogLine
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client 是 state.DockerClient 的 moby/client 实现。
func NewClient ¶
NewClient 构造底座客户端。host 为空时按惯例解析：DOCKER_HOST 环境变量 优先，缺省本机套接字（linux unix socket / Windows named pipe）。API 版本协商在 moby client v0.6+ 默认开启（Engine 门禁 ≥29.8.1 由安装检查 负责，客户端侧不钉死）。
func (*Client) EnsureContainerRunning ¶
EnsureContainerRunning 实现 build.DaemonManager 端口：把容器收敛到 「存在且运行」（镜像缺失拉取 → 容器缺失创建 → 未运行启动；已在运行 no-op）。镜像钉版变化不重建既有容器（v0.1 保守：平台不偷偷替换用户宿主 上的长驻容器——升级走文档化的人工删除动作，下次 Ensure 按新镜像重建）。
func (*Client) EnsureImagePresent ¶
EnsureImagePresent 实现 build.DaemonManager 端口：确保镜像在本机存在 （缺失时拉取并排空响应流；幂等）。D2：镜像检视已含 per-call 预算 （InspectImage 内）；拉取是流式进度消费（响应体即操作本体），与 Events/Logs 同属排除面——由调用方 ctx 管理。
func (*Client) EnsureVolumePresent ¶
EnsureVolumePresent 实现 build.DaemonManager 端口：确保命名卷存在 （幂等；卷已存在即 no-op）。
func (*Client) ImageDigest ¶
ImageDigest 实现 engine.ImageChecker：返回用于 digest 钉定的不可变摘要。 优先取 RepoDigests 的清单摘要（swarm 分发解析只接受 manifest digest—— 实测钉配置 ID 会得到 "manifest schema unsupported" 任务拒绝）；本机构建 镜像（buildkit tar 装载、免 registry）无清单摘要，返回空串由引擎按引用 直用（tag 形态；镜像不被平台自动清理，builds 行留有 digest 台账）。 缺失归一为 engine.ErrImageMissing。
func (*Client) InspectImage ¶
InspectImage 实现 build.ImageSource 端口：返回本机镜像 ID（不可变配置 摘要，D9 部署引用形态）；缺失归一为 build.ErrImageNotFound。
func (*Client) ListNodeObservations ¶
ListNodeObservations 返回全量节点快照（逐字镜像底座语义，平台不加工）。
func (*Client) LoadImage ¶
LoadImage 实现 build.ImageSource 端口：把 docker-format tar 流装入本机 daemon（构建产物落本机；响应流必须排空——流未读完装载未完成）。 D2 预算口径（H6 修正）：装载是流式操作（响应体即操作本体），与镜像 拉取同属 per-call 预算的排除面——装载 goroutine 在 Solve 之前启动， docker 导出器在 solve 末尾才产流，自带的 30s per-call 预算全程消耗在 等 solve 上，>30s 的冷构建全部在完成构建工作后才失败。装载时长由 调用方 ctx 管理（构建路径 = per-build timeout_seconds，缺省 30min）。
func (*Client) ManagedServiceProcesses ¶
ManagedServiceProcesses 返回指定应用的受管服务 compose 进程名集 （label 过滤 fleetly.managed=true + fleetly.app=<app>，取 fleetly.process label；字典序稳定）。日志采集的 per-app 服务发现入口 （T2.20）；平台外同名服务不进结果。
func (*Client) NetworkEnsure ¶
NetworkEnsure 确认 overlay 网络存在（幂等：已有即 no-op；缺失创建—— 每应用专属 overlay 网络，architecture §2.4 服务命名与网络行）。
func (*Client) RemoveImage ¶
RemoveImage 按引用删除镜像（显式管理动作；平台永不自动调用—— build/imagestore.go 清理策略）。
func (*Client) ResolveObjectVersion ¶
func (c *Client) ResolveObjectVersion(ctx context.Context, kind state.ObjectKind, id string) (state.ObjectVersion, error)
ResolveObjectVersion 直读底座对象版本（node/service 两类）。
func (*Client) SelfNodeID ¶
SelfNodeID 返回本机 Swarm node ID；未启用 Swarm 返回 state.ErrNotSwarmManager。
func (*Client) ServiceCreate ¶
ServiceCreate 实现 engine.Substrate：创建服务（调用方对账保证仅缺失时 调用；已存在不覆盖——按 ErrObjectConflict 语义失败暴露竞态）。
func (*Client) ServiceInspect ¶
ServiceInspect 实现 engine.Substrate：按名取服务实况投影。
func (*Client) ServiceList ¶
func (c *Client) ServiceList(ctx context.Context, labels map[string]string) ([]engine.ServiceState, error)
ServiceList 实现 engine.Substrate：按 label 选择器返回服务投影。
func (*Client) ServiceRemove ¶
ServiceRemove 实现 engine.Substrate：删除服务（省略=删除；幂等——缺失 视为成功，对账重放的常见形态）。
func (*Client) ServiceUpdate ¶
ServiceUpdate 实现 engine.Substrate：读当前版本 → 以目标 spec 推进。 ForceUpdate 恒不递增（归位零成本，Spike B2）。并发冲突短重试。
func (*Client) StreamServiceLogs ¶
func (c *Client) StreamServiceLogs(ctx context.Context, service string, since time.Time, follow bool) (<-chan LogLine, error)
StreamServiceLogs 打开 Swarm 服务日志流（service 传 Swarm 服务名， fleetly 命名 = naming.ServiceName(app, service)）。follow=false 时读至 流自然结束（配合 since 做轮询拉取）；follow=true 持续跟随。since 非零 时只取该时刻之后的行。返回 channel 在流结束、出错或 ctx 取消时关闭 （错误语义：日志流尽力而为，故障由采集器下轮重试，不单独暴露错误通道）。 服务不存在 / 底座不可达按 state 端口哨兵归类（mapSubstrateErr）。 D2 排除面：流式调用不走 per-call 预算——生命周期由调用方 ctx 管理。
func (*Client) SubscribeEvents ¶
SubscribeEvents 订阅底座事件流：仅转发 node/service/task 类事件（观测 缓存失效信号），channel 在 ctx 取消或流结束时关闭。D2 排除面：流式 调用不走 per-call 预算——生命周期由调用方 ctx 管理。
func (*Client) SwarmReady ¶
SwarmReady 确认本机为 active swarm manager：未 init / 非 manager 返回 errors.Is(err, engine.ErrNotSwarmReady)（engine 据此映射 E_RUNTIME_UNAVAILABLE + swarm init 建议）。
func (*Client) UpdateNodeLabel ¶
func (c *Client) UpdateNodeLabel(ctx context.Context, swarmNodeID, key, value string, expected state.ObjectVersion) error
UpdateNodeLabel 以乐观令牌更新节点 label：幂等（label 已是目标值时 no-op）；令牌失效返回 state.ErrVersionConflict。
Source Files