Documentation
¶
Overview ¶
Package placement 是放置解析与绑定生命周期（stateful-placement 专项的 v0.1 单机切面，T2.14）：
- 概念模型三层（§2.1）：意图 = 服务 label fleetly.placement.node； 绑定 = placements 记录（平台节点 ID 为锚）；执行 = 适配器编译为 节点 label 约束（本包 ConstraintFor）。
- 不变量（§2.1）：绑定优先于 label 的缺失；有卷应用不存在「无绑定」 的合法运行态；绑定节点不可用时不迁移、不换点。
- 单机切面（§2.9）：同一字段、同一代码路径，候选集只有一项（本机）； 多节点操作一律 E_CAPABILITY_REQUIRES_MULTI_NODE，不静默成功。
本包零框架依赖；底座访问经 state.DockerClient 端口（写前直读纪律： 决策路径直读底座，禁读观测缓存，state-model §2.2）。
Index ¶
- func ConstraintFor(platformNodeID string) string
- func GuardMultiNode(nodeCount int) error
- func MultiNodeUnsupported(op string) error
- type Decision
- type Input
- type LabelInput
- type Resolver
- func (r *Resolver) Apply(ctx context.Context, in Input) (Decision, error)
- func (r *Resolver) MoveBinding(_ context.Context, _ string, _ string, _ string, _ bool) error
- func (r *Resolver) Preflight(ctx context.Context, appID string) error
- func (r *Resolver) Resolve(ctx context.Context, in Input) (Decision, error)
- func (r *Resolver) VerifyVolumesOnNode(ctx context.Context, appID, targetPlatformNodeID string) error
- type VolumeMount
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConstraintFor ¶
ConstraintFor 编译有卷服务的节点约束（执行层 = 适配器把绑定翻译为节点 label 约束，stateful-placement §2.1）：约束引用节点身份 label fleetly.node-id = 平台节点 ID。
func GuardMultiNode ¶
GuardMultiNode 是多节点操作守卫：节点数 > 1 即 v0.1 不支持（不静默成功， §2.9 多节点操作返回 E_CAPABILITY_REQUIRES_MULTI_NODE）。
func MultiNodeUnsupported ¶
MultiNodeUnsupported 是「结构性多节点操作」的静态守卫（换点 API、选点 第二候选等——单机实现直接拒绝）。
Types ¶
type Decision ¶
type Decision struct {
AppID string
// Bind 报告是否应当存在绑定（有卷应用恒真；无卷应用显式 pin 也不钉）。
Bind bool
// PlatformNodeID 是绑定锚（平台节点 ID n_<ULID>；Bind=false 时空）。
PlatformNodeID string
// Source 是绑定来源（platform=自动选点 / label=显式钉住解析成功）。
Source state.PlacementSource
// LabelRef 保留用户书写原值（可解释性；空 = 未声明）。
LabelRef string
// KeptExisting 报告既有绑定被保持（绑定优先于 label 的缺失）。
KeptExisting bool
// Constraint 是有卷服务的约束编译结果
//（`node.labels.fleetly.node-id == <平台ID>`；未钉时空）。
Constraint string
// Warnings 是计划级非阻断标注（W_PLACEMENT_STATELESS_PIN）。
Warnings []compose.Warning
}
Decision 是解析结果（意图 → 绑定 → 执行的裁决书）。
type Input ¶
type Input struct {
// AppID/AppName 是应用平台 ID（appid8/绑定锚）与 compose 名（卷命名）。
AppID string
AppName string
// Volumes 是应用整体声明的命名卷挂载（空 = 无卷应用 → 默认不钉）。
Volumes []VolumeMount
// LabelRef 是 fleetly.placement.node 字面值（空 = 未声明）。
LabelRef string
}
Input 是一次放置解析输入。
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver 是放置解析器（单机同路径）。
func NewResolver ¶
func NewResolver(store *state.Store, docker state.DockerClient) *Resolver
NewResolver 构造解析器。
func (*Resolver) Apply ¶
Apply = Resolve + 落库：绑定 upsert（首次钉住）+ 卷注册表登记 + 审计与 事件同事务（placement.bound / volume.created；系统自动动作必入审计， state-model §2.9）。既有绑定保持时不重写（幂等）；卷登记始终执行 （新卷 = 数据诞生点钉住，§2.6 漂移矩阵）。
func (*Resolver) MoveBinding ¶
MoveBinding 是显式换点（破坏性确认路径，§2.1 绑定变更四类操作之一）。 v0.1 单机无第二候选：守卫拒绝，不静默、不改状态（rebind CLI 属 v0.2）。
func (*Resolver) Preflight ¶
Preflight 执行部署前哨检查：绑定存在且节点不可用即错误。无绑定（无卷 应用自由调度）通过；blocked/unresolved 记录直接不可用（app blocked 的 派生来源，state-model §2.10）。
func (*Resolver) Resolve ¶
Resolve 解析放置（不落库）：单机同路径，候选集 = 本机（§2.9）。
已有绑定 → 保持（绑定优先） 无绑定且无卷 → 不钉（自由调度）；显式 pin 出 W_PLACEMENT_STATELESS_PIN 无绑定且有卷 → 自动绑定本机（label 引导时来源记 label） label 解析失败 → E_PLACEMENT_NODE_NOT_FOUND（422 + 候选清单）/ INVALID 拓扑非单节点 → E_CAPABILITY_REQUIRES_MULTI_NODE（v0.1 守卫，不静默）
func (*Resolver) VerifyVolumesOnNode ¶
func (r *Resolver) VerifyVolumesOnNode(ctx context.Context, appID, targetPlatformNodeID string) error
VerifyVolumesOnNode 是卷数据前哨：任一 active 卷的数据节点 ≠ 目标节点即 E_VOLUME_NODE_MISMATCH（§2.5：约束满足 ≠ 数据在位）。单机部署目标恒为 绑定节点 = 本机，短路成立但代码路径完整保留（v0.2 跨节点复用）。 无节点归属记录的卷（历史行）跳过——不猜测，登记面已可见。
type VolumeMount ¶
type VolumeMount struct {
Key string // 顶层卷 key（compose 侧标识）
Target string // 容器内挂载点（volumes.mount_path）
ReadOnly bool
}
VolumeMount 是一次命名卷挂载声明（归一化 compose 的 volumes 子集）。
Source Files