Documentation
¶
Overview ¶
Package storeport defines the persistence port used by the server-side plugin control plane.
The package intentionally does not import internal/store. Production wiring adapts a concrete store implementation to PluginStore, while NewMemory provides an in-process implementation for tests and development.
Implementations must preserve these semantics:
- all reads and writes are tenant-scoped; an upsert must never change an existing row's tenant_id;
- Create/Update/Delete update desired state and increment the tenant/edge desired revision in the same transaction, returning the new revision; failures must not leave partial state;
- quota exhaustion fails the whole operation without writing or incrementing the revision and returns ErrQuota;
- deleting desired state does not delete audit data; purge=false preserves the observed projection and instance-private data, while purge=true removes that instance's observed projection, domain records and scheduled tasks in the same transaction;
- only secret://<name> handles and non-sensitive scalars are stored; plaintext secrets are never persisted.
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) 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 is the revision and applied projection for a tenant/edge.
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 is the authoritative desired-state row for a plugin instance. 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 is the observed-state projection reported by an edge. Its fields mirror api.PluginObservedInstanceData plus scope and timestamp coordinates; adapters map between this type and concrete store rows.
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 is the persistence port consumed by the server-side plugin control plane. A nil value means the API-only deployment; callers must handle it by degrading safely.
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 是租户保留期/配额行。字段按租户安全策略的资源清单定义; 任何 <=0 的字段表示 NULL/继承 Server 默认值(绝不用 0 表示无限)。