shadowdb

type InMemoryOpener ¶

type InMemoryOpener struct {
	// contains filtered or unexported fields
}

InMemoryOpener is the reference Opener implementation. It holds a ShadowDB handle and an in-process session registry (map + sync.Mutex). Sessions are tracked by sessionID; Close / Reap consult the map, the shadow table rows are the physical state.

Scope: suitable for tests, dev harnesses, and single-process demos. Production deployments that need cross-process session visibility or crash recovery belong in platform-layer Opener implementations (e.g. a SQL-backed registry table). InMemoryOpener intentionally keeps the registry in-memory so the reference implementation has zero storage assumptions beyond the injected ShadowDB.

Thread safety: all Opener methods hold the mutex only for the registry bookkeeping window; SQL executions happen outside the lock so a slow DB does not stall concurrent Opens. The registry ensures at most one Open per sessionID.

InMemoryOpener 是 Opener 的参考实现. 持有 ShadowDB handle 与进程 内 session 注册表 (map + sync.Mutex). Session 按 sessionID 索引; Close / Reap 查 map, 影子表行是物理状态.

适用范围: 测试 / dev / 单进程 demo. 生产部署若需跨进程可见性或 崩溃恢复, 应在平台层做 Opener 实现 (例如 SQL 注册表). InMemoryOpener 刻意把注册表放内存, 参考实现对存储的假设仅限注入的 ShadowDB.

线程安全: Opener 方法仅在注册表簿记窗口持锁, SQL 执行在锁外, 避免慢 DB 阻塞并发 Open. 注册表保证同 sessionID 最多一次 Open.

func NewInMemoryOpener(db ShadowDB) *InMemoryOpener

func (o *InMemoryOpener) Len() int

func (o *InMemoryOpener) Open(ctx context.Context, sessionID string, opts Options) (*Session, error)

INSERT INTO {ShadowTable} SELECT ?, * FROM {SeedFromTable}

INSERT INTO {ShadowTable} SELECT ?, * FROM {SeedFromTable}

func (o *InMemoryOpener) Reap(ctx context.Context, olderThan time.Duration) (ReapResult, error)

type Opener ¶

type Opener interface {
	// Open creates a new shadow session tagged with sessionID. The
	// physical shadow table (opts.ShadowTable) MUST exist with a
	// session_id VARCHAR(64) NOT NULL column and a schema that
	// mirrors opts.SeedFromTable (if seeding is requested).
	//
	// Seeding: if opts.SeedFromTable is non-empty, Open executes
	// INSERT INTO shadow SELECT sessionID AS session_id, * FROM seed.
	// If empty, the session starts with an empty shadow (caller
	// writes from scratch).
	//
	// Returns ErrEmptySessionID if sessionID is "", ErrDuplicateSession
	// if sessionID is already open on this Opener, or
	// ErrInvalidIdentifier if ShadowTable / SeedFromTable fail
	// ValidateIdentifier. Any driver-level error is returned
	// verbatim, not wrapped in a shadowdb sentinel.
	//
	// Open 创建新的 shadow session 并以 sessionID 打标. 物理影子
	// 表 (opts.ShadowTable) 必须预建, 带 session_id VARCHAR(64)
	// NOT NULL 列, 且 schema 与 opts.SeedFromTable 对齐 (如要种子).
	//
	// 种子: opts.SeedFromTable 非空时, Open 执行 INSERT INTO shadow
	// SELECT sessionID AS session_id, * FROM seed. 为空则 session
	// 从空 shadow 开始 (调用方自己写).
	//
	// sessionID 为空返回 ErrEmptySessionID, 已存在返回
	// ErrDuplicateSession, ShadowTable / SeedFromTable 校验失败
	// 返回 ErrInvalidIdentifier. driver 级错误原样返回, 不包 shadowdb
	// 哨兵.
	Open(ctx context.Context, sessionID string, opts Options) (*Session, error)

	// Reap finds sessions whose CreatedAt is older than now-olderThan
	// and closes them (DELETE WHERE session_id=? for each). Intended
	// for platform-layer cron to clean up crashed / abandoned
	// sessions that missed Close. A zero olderThan reaps everything
	// currently open; callers almost always want a positive duration.
	//
	// Returns ReapResult with per-session outcomes. Per-session
	// errors accumulate in Errors rather than aborting the sweep --
	// the next session's cleanup is independent.
	//
	// Reap 找出 CreatedAt 比 now-olderThan 更早的 session 并关闭
	// (对每个 DELETE WHERE session_id=?). 给平台层 cron 清理错过
	// Close 的崩溃 / 弃置 session. olderThan 为 0 会回收所有当前
	// 打开的 session, 调用方几乎总应传正值.
	//
	// 返回 ReapResult 汇总 per-session 结果. per-session 错误累积到
	// Errors 而不中止扫描 -- 下一个 session 的清理独立进行.
	Reap(ctx context.Context, olderThan time.Duration) (ReapResult, error)
}

Opener opens, closes, and reaps session-scoped shadow tables. Implementations:

• InMemoryOpener (this package): reference implementation backed by a ShadowDB handle. Suitable for tests and small in-process deployments.
• Future SQL-backed openers belong in platform-layer packages that hold a real driver (platform/internal/shadowdb/...). core ships only the interface and the reference impl.

Thread safety: all methods MUST be safe for concurrent use from multiple goroutines. A single Opener instance is expected to serve many Agent sessions.

Lifecycle ownership: core does NOT spawn goroutines. Reap is a blocking function call; the platform layer invokes it from its own cron / watchdog / worker loop. This keeps core free of runtime-infrastructure responsibilities and lets the platform layer choose scheduling granularity (per-minute cron, event-driven after Agent session ends, on-demand from admin HTTP).

Opener 负责打开 / 关闭 / 回收 session 级影子表. 实现:

• InMemoryOpener (本包): 基于 ShadowDB handle 的参考实现. 适合测试与小型进程内部署.
• 未来 SQL-backed opener 属于持有真实 driver 的平台层包 (platform/internal/shadowdb/...). core 只发接口和参考实现.

线程安全: 所有方法必须支持多 goroutine 并发. 单个 Opener 实例 预期服务多个 Agent session.

生命周期归属: core 不起 goroutine. Reap 是阻塞的函数调用, 平台 层从自己的 cron / watchdog / worker 循环触发. 这让 core 免于 运行时基础设施责任, 也让平台层自选调度粒度 (分钟级 cron / Agent session 结束事件驱动 / admin HTTP 按需触发).

type Options ¶

type Options struct {
	// ShadowTable is the physical table name that carries shadow
	// rows for this session. Required. Must pass ValidateIdentifier
	// (plain [a-zA-Z_]\w*, no quoting). The table MUST exist with
	// a session_id VARCHAR(64) NOT NULL column; core does not
	// CREATE TABLE for the caller (schema-agnostic contract).
	//
	// ShadowTable 是承载本 session 影子行的物理表名. 必填, 必须通过
	// ValidateIdentifier (纯 [a-zA-Z_]\w*, 无引号). 表必须预建, 带
	// session_id VARCHAR(64) NOT NULL 列; core 不替调用方 CREATE TABLE
	// (schema-agnostic 契约).
	ShadowTable string

	// SeedFromTable is the optional source table name for initial
	// population. If non-empty, Open issues INSERT INTO shadow
	// SELECT sessionID AS session_id, * FROM seed. If empty, the
	// session starts empty and the caller populates via subsequent
	// INSERTs. Must pass ValidateIdentifier when non-empty.
	//
	// The schema of SeedFromTable MUST match ShadowTable minus the
	// session_id column; otherwise the INSERT ... SELECT fails at
	// Open time with a driver error, surfacing the mismatch early.
	//
	// SeedFromTable 是可选的种子源表名. 非空时 Open 执行 INSERT
	// INTO shadow SELECT sessionID AS session_id, * FROM seed.
	// 为空则 session 从空开始, 调用方经后续 INSERT 自行填充. 非空
	// 时必须通过 ValidateIdentifier.
	//
	// SeedFromTable 的 schema 必须与 ShadowTable 扣去 session_id
	// 列后对齐, 否则 INSERT ... SELECT 在 Open 阶段即以 driver
	// 错误失败, 早暴露 schema 不匹配.
	SeedFromTable string

	// OnClose is invoked with the underlying error if Close fails
	// (typically a driver-level error during DELETE). Intended
	// hook-up point for platform-layer alerting / VerdictSink /
	// orphan-count metrics. nil disables the callback.
	//
	// Not called on successful Close or on Reap-initiated cleanup
	// (Reap collects its own errors in ReapResult). Keeps the
	// callback semantics "only fire on anomalous single-session
	// close" so alerting rules stay crisp.
	//
	// OnClose 在 Close 失败时被调用, 参数为底层错误 (通常 DELETE 的
	// driver 级错误). 给平台层告警 / VerdictSink / 孤儿数指标提供
	// 钩子. nil 禁用回调.
	//
	// 成功 Close 不触发, Reap 主导的清理也不触发 (Reap 在 ReapResult
	// 自收错误). 保持回调语义为 "仅单 session 异常 Close 时触发",
	// 告警规则干净.
	OnClose func(error)
}

Options configures Session construction at Open time. All fields are validated synchronously; misconfiguration surfaces as an error from Open, not as a deferred failure on first Exec.

Options 在 Open 时配置 Session 构造. 所有字段同步校验, 配置错误 经 Open 即时暴露, 不推迟到首次 Exec 炸出.

type ReapResult ¶

type ReapResult struct {
	// Swept is the number of sessions this Reap call closed
	// successfully (Close returned nil).
	//
	// Swept 是本次 Reap 成功关闭的 session 数 (Close 返回 nil).
	Swept int

	// Errors holds the per-session errors encountered during the
	// sweep. Empty slice means clean sweep. Errors are wrapped with
	// the sessionID in %w context so callers can identify which
	// session failed without the Opener re-emitting logs.
	//
	// Errors 承载扫描中遇到的 per-session 错误. 空 slice 表示干净
	// 扫描. 错误以 %w 附带 sessionID 上下文包装, 调用方可据此识别
	// 哪个 session 失败, Opener 不必再打日志.
	Errors []error
}

ReapResult aggregates Reap outcomes across swept sessions. Callers typically log (Swept, Errors) for observability and alert when len(Errors) > 0 or Swept > some threshold.

ReapResult 汇总 Reap 扫过所有 session 的结果. 调用方通常以 (Swept, Errors) 打日志做观测, len(Errors) > 0 或 Swept 超阈值 时告警.

type Session ¶

type Session struct {
	ID          string
	CreatedAt   time.Time
	ShadowTable string
	DB          ShadowDB
	// contains filtered or unexported fields
}

Session is one session-scoped shadow-table handle. Opener.Open returns an opaque *Session; callers invoke Close to delete the session's tagged rows. Exec/Query go through the DB field, but the session_id filter must be appended to every WHERE (see ShadowExecTool decorator for automatic injection).

Field semantics:

• ID is the session_id value used in the physical shadow table. Treated as opaque by shadowdb; callers pass it through their SQL as the session_id filter value.
• CreatedAt is set by Opener.Open to time.Now().UTC() at open time. Reap compares against this field to identify orphans that missed Close.
• ShadowTable is the physical table name carried on the Session so a decorator or tool can retrieve it without threading Options through the call chain.
• DB is the ShadowDB handle bound to this session. Callers issue SQL through DB.QueryContext / DB.ExecContext; none of that goes through Session methods.

Session is a value-identity type: two *Session with the same ID and owner Opener are functionally interchangeable. Close is idempotent at the Opener level (second call returns ErrSessionNotFound, a distinct error so callers can separate "already closed" from wire errors).

Session 是一次 session 级影子表 handle. Opener.Open 返回不透明 的 *Session; 调用方调 Close 以删除 session 标记的行. Exec/Query 经 DB 字段发出, 但每个 WHERE 必须追加 session_id filter (自动 注入见 ShadowExecTool 装饰器).

字段语义:

• ID 是物理影子表中的 session_id 值. shadowdb 视作不透明, 调用方 在 SQL 中按 session_id filter 值传入.
• CreatedAt 由 Opener.Open 在开启时设为 time.Now().UTC(). Reap 比较此字段判定错过 Close 的孤儿.
• ShadowTable 把物理表名挂在 Session 上, 装饰器 / 工具不用再把 Options 层层透传也能取到.
• DB 是绑定到本 session 的 ShadowDB handle. 调用方经 DB.QueryContext / DB.ExecContext 发 SQL, 不走 Session 方法.

Session 为值语义类型: 同 ID 同 Opener 的两个 *Session 功能等价. Close 在 Opener 层幂等 (二次调用返回 ErrSessionNotFound, 独立错误 使调用方区分 "已 Close" 与接线错).

func (s *Session) Close(ctx context.Context) error

type ShadowDB ¶

type ShadowDB struct {
	*sql.DB
}

ShadowDB wraps *sql.DB at the API boundary to signal that the handle targets a physical shadow table rather than production OLTP. Analogous to StagingDB in tools/builtin/sql_cas.go -- an intent marker, not a sandbox. It does not defend against ShadowDB{prodDB} lies, but turns the shadow-scope claim from a godoc note into a type signature every call site must write explicitly.

Embedding *sql.DB means method promotion keeps the ergonomic API (shadowdb.ShadowDB{db}.QueryRow works without manual unwrap).

ShadowDB 在 API 边界包装 *sql.DB, 表明该 handle 指向物理影子表 而非生产 OLTP. 与 tools/builtin/sql_cas.go 的 StagingDB 同族 -- 意图标记而非沙盒. 无法防 ShadowDB{prodDB} 撒谎, 但把 "shadow 作用域" 从 godoc 注释升格为类型签名, 每个调用点必须显式写出.

内嵌 *sql.DB 经 method promotion 保留人体工学 (shadowdb.ShadowDB{db}.QueryRow 可直接用, 无需手工 unwrap).