Documentation
¶
Overview ¶
Package storeport 是 Server lane 对插件控制面持久化的本地端口(依赖倒置接缝)。
契约来源:.local/plan/v0.1-completion.md §3(Store lane 在 internal/store 提供同签名方法)。 merge 时由 Captain 用一个薄适配器把 *store.Store 接到本接口:现成适配器见 adapter_sqlite.go(默认被 build tag 排除,Store v7/v8 合并后删掉 tag 行即可编译)。
本包刻意**不 import internal/store**:STORE 与 SERVER 两条 lane 并行开发时, Server 侧必须能独立编译与测试。测试与开发态用 NewMemory() 的进程内实现。
接线指引(Captain,唯一一处) ¶
Store v7/v8 合并后,在 cmd/cloudpath-server/main.go 的 server.New(server.Config{...}) 里加一行 `PluginStore: <adapter>`,adapter 是 internal/store → 本接口的薄映射: 逐个方法转发,并把 store 的行类型与本包行类型互转(字段一一同名,见下), 同时把 store 的配额/冲突/未找到错误映射到本包的 ErrQuota / ErrConflict / ErrNotFound / ErrTenantMismatch(Server 据 errors.Is 产出 api.PluginErr* 稳定码)。 未接线时 Server 行为是安全降级:插件写 API 503、WS plugin_* 按旧协议忽略、读面真实为空。
实现方必须满足的语义不变量:
- 所有读写按 tenantID 作用域;任何 upsert 不得修改既有行的 tenant_id;
- Create/Update/Delete 在同一写事务内更新期望态并把 tenant/edge desired revision +1, 返回新 revision;失败不得留下半状态;
- 配额超限必须整体失败(不写入、不增 revision),返回 ErrQuota;
- 删除期望态不删除审计;purge=false 时必须保留 observed 投影与实例私有数据; purge=true 时同一事务清除该实例 observed 投影、领域记录和定时任务;
- 只存 secret://<name> handle 名与非敏感标量,绝不存明文 secret。
Index ¶
- Variables
- type Memory
- func (m *Memory) CountPluginInstances(tenantID int64) (int, error)
- func (m *Memory) CreatePluginInstance(row PluginInstanceRow) (uint64, error)
- func (m *Memory) DeletePluginInstance(tenantID int64, edgeID, instanceID string, purge bool) (uint64, error)
- func (m *Memory) GetPluginEdgeRevision(tenantID int64, edgeID string) (PluginEdgeRevisionRow, error)
- func (m *Memory) GetPluginInstance(tenantID int64, edgeID, instanceID string) (PluginInstanceRow, bool, error)
- func (m *Memory) GetTenantPolicy(tenantID int64) (TenantPolicyRow, error)
- func (m *Memory) ListPluginInstallationsTenant(tenantID int64) ([]PluginInstallationRow, error)
- func (m *Memory) ListPluginInstancesTenant(tenantID int64) ([]PluginInstanceRow, error)
- func (m *Memory) ListPluginObservationsTenant(tenantID int64) ([]PluginObservationRow, error)
- func (m *Memory) PluginDesiredRevision(tenantID int64, edgeID string) (uint64, error)
- func (m *Memory) SetNow(now func() time.Time)
- func (m *Memory) SetPluginEdgeApplied(tenantID int64, edgeID, bootID string, seq, appliedRevision uint64, at int64) error
- func (m *Memory) SetPluginEdgeReport(tenantID int64, edgeID, bootID string, seq uint64, at int64) error
- func (m *Memory) SetTenantPolicy(tenantID int64, p TenantPolicyRow) error
- func (m *Memory) UpdatePluginInstance(row PluginInstanceRow) (uint64, error)
- func (m *Memory) UpsertPluginInstallations(tenantID int64, edgeID string, rows []api.PluginInstallationStatusData) error
- func (m *Memory) UpsertPluginObservations(tenantID int64, edgeID string, rows []api.PluginObservedInstanceData, ...) error
- type PluginEdgeRevisionRow
- type PluginInstallationRow
- type PluginInstanceRow
- type PluginObservationRow
- type PluginStore
- type TenantPolicyRow
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound 表示目标期望态行不存在(Update/Delete 命中空)。 ErrNotFound = errors.New("storeport: plugin instance not found") // ErrConflict 表示 (tenant, edge, instance) 已存在或身份冲突。 ErrConflict = errors.New("storeport: plugin instance conflict") // ErrQuota 表示租户插件实例配额已满:不得写入、不得增加 revision。 ErrQuota = errors.New("storeport: plugin instance quota exceeded") // ErrTenantMismatch 表示既有行属于其他租户(fail-closed,绝不改写归属)。 ErrTenantMismatch = errors.New("storeport: row owned by another tenant") )
端口级稳定哨兵错误。适配器必须把底层实现的等价失败映射到这些值, Server 侧据 errors.Is 映射为 api.PluginErr* 稳定错误码(前端按码呈现)。
Functions ¶
This section is empty.
Types ¶
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory 是 PluginStore 的进程内实现:Server lane 的测试替身,也是 Store v7/v8 接线前的显式降级形态(**不持久化**,进程退出即丢;生产必须由 SQLite 适配器替换)。
它完整实现端口语义不变量:租户作用域、revision 单调、失败不写入不增 revision、 配额原子拒绝、purge 语义、绝不改写既有行 tenant_id。
func (*Memory) CountPluginInstances ¶
CountPluginInstances 返回租户期望态实例数(配额判定用)。
func (*Memory) CreatePluginInstance ¶
func (m *Memory) CreatePluginInstance(row PluginInstanceRow) (uint64, error)
CreatePluginInstance 写入新期望态行并在同一临界区内把 desired revision +1。 已存在返回 ErrConflict;配额已满返回 ErrQuota(不写入、不增 revision)。
func (*Memory) DeletePluginInstance ¶
func (m *Memory) DeletePluginInstance(tenantID int64, edgeID, instanceID string, purge bool) (uint64, error)
DeletePluginInstance 删除期望态行并 +1 revision。purge=true 才连带删除该实例的 observed 投影;purge=false 保留投影(读面标 stale),审计永不被删除。 Memory 端口只承载 observed 投影;领域记录与定时任务由持久化 Store 在 purge 时同事务清除。
func (*Memory) GetPluginEdgeRevision ¶
func (m *Memory) GetPluginEdgeRevision(tenantID int64, edgeID string) (PluginEdgeRevisionRow, error)
GetPluginEdgeRevision 返回 tenant/edge 的 revision/applied/boot/sequence 投影。
func (*Memory) GetPluginInstance ¶
func (m *Memory) GetPluginInstance(tenantID int64, edgeID, instanceID string) (PluginInstanceRow, bool, error)
GetPluginInstance 返回单个期望态行;不存在返回 ok=false(跨租户天然不可见)。
func (*Memory) GetTenantPolicy ¶
func (m *Memory) GetTenantPolicy(tenantID int64) (TenantPolicyRow, error)
GetTenantPolicy 返回租户策略行;未设置返回零值行(调用方按「继承默认」解释)。
func (*Memory) ListPluginInstallationsTenant ¶
func (m *Memory) ListPluginInstallationsTenant(tenantID int64) ([]PluginInstallationRow, error)
ListPluginInstallationsTenant 返回租户全部安装物投影行(稳定排序)。
func (*Memory) ListPluginInstancesTenant ¶
func (m *Memory) ListPluginInstancesTenant(tenantID int64) ([]PluginInstanceRow, error)
ListPluginInstancesTenant 返回租户全部期望态行(按 edge/instance 排序,稳定输出)。
func (*Memory) ListPluginObservationsTenant ¶
func (m *Memory) ListPluginObservationsTenant(tenantID int64) ([]PluginObservationRow, error)
ListPluginObservationsTenant 返回租户全部 observed 投影行(稳定排序)。
func (*Memory) PluginDesiredRevision ¶
PluginDesiredRevision 返回 tenant/edge 当前 desired revision(无记录为 0)。
func (*Memory) SetPluginEdgeApplied ¶
func (m *Memory) SetPluginEdgeApplied(tenantID int64, edgeID, bootID string, seq, appliedRevision uint64, at int64) error
SetPluginEdgeApplied 记录 Edge 已成功应用的 revision(只有 applied ack 才调用)。
func (*Memory) SetPluginEdgeReport ¶
func (m *Memory) SetPluginEdgeReport(tenantID int64, edgeID, bootID string, seq uint64, at int64) error
SetPluginEdgeReport 记录一次 observed 上报(boot/sequence/时间),不改 applied。
func (*Memory) SetTenantPolicy ¶
func (m *Memory) SetTenantPolicy(tenantID int64, p TenantPolicyRow) error
SetTenantPolicy 保存租户策略行。
func (*Memory) UpdatePluginInstance ¶
func (m *Memory) UpdatePluginInstance(row PluginInstanceRow) (uint64, error)
UpdatePluginInstance 覆盖既有期望态行并 +1 revision。缺行返回 ErrNotFound; 行归属其他租户返回 ErrTenantMismatch(fail-closed,绝不改写归属)。
func (*Memory) UpsertPluginInstallations ¶
func (m *Memory) UpsertPluginInstallations(tenantID int64, edgeID string, rows []api.PluginInstallationStatusData) error
UpsertPluginInstallations 用 Edge 上报的安装物集合整体替换 tenant/edge 投影。
func (*Memory) UpsertPluginObservations ¶
func (m *Memory) UpsertPluginObservations(tenantID int64, edgeID string, rows []api.PluginObservedInstanceData, reportedAt int64) error
UpsertPluginObservations 用 Edge 上报的实例实际态集合整体替换 tenant/edge 投影。
type PluginEdgeRevisionRow ¶
type PluginEdgeRevisionRow struct {
TenantID int64
EdgeID string
DesiredRevision uint64
AppliedRevision uint64
BootID string
LastSequence uint64
LastReportAt int64
LastAckAt int64
}
PluginEdgeRevisionRow 是每个 tenant/edge 的 revision 与 applied 投影(§3 逐字对齐)。
type PluginInstallationRow ¶
type PluginInstallationRow struct {
TenantID int64
EdgeID string
PluginID string
Version string
Kind string
Protocol int
Digest string
TrustMode string
Verified bool
VerifiedPublisher string
PermissionsJSON string
ContributionsJSON string
CapabilitiesJSON string
ReportedAt int64
}
PluginInstallationRow 是 Edge 上报的安装物投影行(只含公开 manifest 事实)。 Permissions/Contributions/Capabilities 以 JSON 文本承载,对应 api 的公开 DTO。
func NewInstallationRow ¶
func NewInstallationRow(tenantID int64, edgeID string, in api.PluginInstallationStatusData, reportedAt int64) PluginInstallationRow
NewInstallationRow 把 api 安装物 DTO 投影为存储行(适配器/测试共用映射)。
func (PluginInstallationRow) Status ¶
func (r PluginInstallationRow) Status() api.PluginInstallationStatusData
Status 把安装物投影行还原为 api 公开 DTO(读面/目录用)。 任何字段解析失败都按空值处理,绝不让损坏投影变成 500。
type PluginInstanceRow ¶
type PluginInstanceRow struct {
TenantID int64
EdgeID string
InstanceID string
PluginID string
Version string
Enabled bool
Isolation string
ConfigJSON string
SecretRefs string
Revision uint64
CreatedAt int64
UpdatedAt int64
}
PluginInstanceRow 是 Server 权威期望态行(§3 逐字对齐)。 ConfigJSON 是 map[string]string 的 JSON,值只含非敏感标量或 secret://<name> handle; SecretRefs 是 JSON []string,只含 handle 名。
type PluginObservationRow ¶
type PluginObservationRow struct {
TenantID int64
EdgeID string
InstanceID string
PluginID string
Version string
HostOnline bool
State string
Health string
Detail string
RestartCount int
LastHealthy int64
MessageRate float64
ReportedAt int64
}
PluginObservationRow 是 Edge 上报的实例实际态投影行。 §3 只给了方法名未展开字段:本包按 api.PluginObservedInstanceData + 作用域/时间定义, 适配器负责与 store 行互映射。
func NewObservationRow ¶
func NewObservationRow(tenantID int64, edgeID string, o api.PluginObservedInstanceData, reportedAt int64) PluginObservationRow
NewObservationRow 把 api 实例实际态 DTO 投影为存储行(适配器/测试共用映射)。
func (PluginObservationRow) Observed ¶
func (r PluginObservationRow) Observed() api.PluginObservedInstanceData
Observed 把实例实际态投影行还原为 api 公开 DTO。
type PluginStore ¶
type PluginStore interface {
// ---- 插件期望态(Server 权威)----
ListPluginInstancesTenant(tenantID int64) ([]PluginInstanceRow, error)
GetPluginInstance(tenantID int64, edgeID, instanceID string) (PluginInstanceRow, bool, error)
CreatePluginInstance(row PluginInstanceRow) (uint64, error)
UpdatePluginInstance(row PluginInstanceRow) (uint64, error)
// DeletePluginInstance 删除期望态并 +1 revision(Edge 需要收敛「实例已移除」)。
// purge=false 必须保留该实例的 observed 投影、领域记录、定时任务与全部审计;
// purge=true 才在同一事务中清除该实例的 observed 投影、领域记录和定时任务。
DeletePluginInstance(tenantID int64, edgeID, instanceID string, purge bool) (uint64, error)
PluginDesiredRevision(tenantID int64, edgeID string) (uint64, error)
// ---- Edge revision / applied 投影 ----
GetPluginEdgeRevision(tenantID int64, edgeID string) (PluginEdgeRevisionRow, error)
// SetPluginEdgeApplied 写入 applied_revision 与 ack 时间。rejected/failed 的 ack
// 也会调用它,但传入的是**未变化的** appliedRevision(只刷新 LastAckAt)。
SetPluginEdgeApplied(tenantID int64, edgeID, bootID string, seq, appliedRevision uint64, at int64) error
SetPluginEdgeReport(tenantID int64, edgeID, bootID string, seq uint64, at int64) error
// ---- Edge 上报的只读投影 ----
UpsertPluginInstallations(tenantID int64, edgeID string, rows []api.PluginInstallationStatusData) error
UpsertPluginObservations(tenantID int64, edgeID string, rows []api.PluginObservedInstanceData, reportedAt int64) error
ListPluginObservationsTenant(tenantID int64) ([]PluginObservationRow, error)
ListPluginInstallationsTenant(tenantID int64) ([]PluginInstallationRow, error)
// ---- 租户策略 / 配额 / 保留期 ----
GetTenantPolicy(tenantID int64) (TenantPolicyRow, error)
SetTenantPolicy(tenantID int64, p TenantPolicyRow) error
CountPluginInstances(tenantID int64) (int, error)
}
PluginStore 是 Server lane 消费的插件控制面持久化端口(§3 全部方法,签名逐字对齐)。 *store.Store 经适配器满足本接口;nil 表示 API-only 形态,调用方必须判空降级。
type TenantPolicyRow ¶
type TenantPolicyRow struct {
TenantID int64
RetentionEvents int
RetentionCommands int
RetentionAudit int
RetentionTokens int
RetentionObservations int
QuotaDevices int
QuotaEdges int
QuotaBrowserWS int
QuotaTokens int
QuotaUsers int
QuotaEventsPerMinute int
QuotaPluginInstances int
UpdatedAt int64
}
TenantPolicyRow 是租户保留期/配额行。§3 未展开字段:本包按 docs/architecture/tenant-security-policy.md §3/§4 的资源清单定义。 任何 <=0 的字段表示 NULL/继承 Server 默认值(绝不用 0 表示无限)。