storeport

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: MIT Imports: 6 Imported by: 0

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 投影行;
  • 只存 secret://<name> handle 名与非敏感标量,绝不存明文 secret。

Index

Constants

This section is empty.

Variables

View Source
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 NewMemory

func NewMemory() *Memory

NewMemory 构造空的进程内插件控制面存储。

func (*Memory) CountPluginInstances

func (m *Memory) CountPluginInstances(tenantID int64) (int, error)

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),审计永不被删除。

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

func (m *Memory) PluginDesiredRevision(tenantID int64, edgeID string) (uint64, error)

PluginDesiredRevision 返回 tenant/edge 当前 desired revision(无记录为 0)。

func (*Memory) SetNow

func (m *Memory) SetNow(now func() time.Time)

SetNow 注入时钟(测试可复现 stale/过期判定)。

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

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

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 才删投影。
	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 表示无限)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL