storeport

package
v0.2.21 Latest Latest
Warning

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

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

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

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

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

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

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

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 表示无限)。

Jump to

Keyboard shortcuts

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