package dobotaiops import ( "context" "fmt" "net/url" "strings" "time" "github.com/jackc/pgx/v5" "github.com/jackc/pgx/v5/pgxpool" ) // Client 是对外部生产库的**独立只读**客户端:自己的 pool、自己的凭据、自己的超时。 // 它没有任何写方法,也不做 DDL/迁移 —— 这是本阶段的接口面本身在保证的事。 type Client struct { pool *pgxpool.Pool config Config report ACLReport safety SourceSafety } // Build 建立只读客户端: // 1. 形状校验 → 2. 从仓库外 0600 secret 读 DSN → 3. 拒绝指向治理主库 → // 4. 建独立 pool(default_transaction_read_only=on、statement_timeout、连接上限)→ // 5. Ping → 6. ACL 自检(不是最小只读就 fail closed)。 // // 任何一步失败都返回 ErrUnavailable / ErrNotReadOnly;调用方据此把功能标记为不可用, // **绝不回退到治理主库或应用写账号**。 func Build(ctx context.Context, cfg Config) (*Client, error) { cfg = cfg.withDefaults() if err := cfg.Validate(); err != nil { return nil, err } dsn, err := ReadDSNFile(cfg.DSNFile) if err != nil { return nil, err } if err := GuardGovernanceDatabase(dsn, cfg.GovernanceDatabaseURL); err != nil { return nil, err } poolConfig, err := pgxpool.ParseConfig(dsn) if err != nil { // 解析失败的原始错误可能带着 DSN,绝不上抛。 return nil, fmt.Errorf("%w: DSN could not be parsed", ErrUnavailable) } poolConfig.MaxConns = cfg.MaxConns poolConfig.MinConns = cfg.MinConns poolConfig.MaxConnLifetime = 30 * time.Minute poolConfig.MaxConnIdleTime = 5 * time.Minute poolConfig.ConnConfig.ConnectTimeout = cfg.ConnectTimeout if poolConfig.ConnConfig.RuntimeParams == nil { poolConfig.ConnConfig.RuntimeParams = map[string]string{} } // 会话级只读 + 语句超时:只读默认不是 ACL 的替代品,两层都要有。 poolConfig.ConnConfig.RuntimeParams["default_transaction_read_only"] = "on" poolConfig.ConnConfig.RuntimeParams["statement_timeout"] = fmt.Sprintf("%d", (cfg.QueryTimeout + 2*time.Second).Milliseconds()) poolConfig.ConnConfig.RuntimeParams["idle_in_transaction_session_timeout"] = "15000" poolConfig.ConnConfig.RuntimeParams["application_name"] = "kg-dobotai-ops-readonly" poolConfig.ConnConfig.RuntimeParams["search_path"] = "pg_catalog,public" if cfg.DialContext != nil { poolConfig.ConnConfig.DialFunc = cfg.DialContext } else if cfg.DialMode == "ssh" { // 拨号地址只从配置里的 DSN 派生(远端解析),不接受 pgx 传入的本机解析结果 —— // 本机 DNS 被 Fake-IP/VPN 劫持时,那个结果会是假地址(实测挂 20s 超时)。 dialAddress, addrErr := hostPortOf(dsn) if addrErr != nil { return nil, addrErr } dialer, dialErr := SSHDialer(cfg.SSHTarget, dialAddress) if dialErr != nil { return nil, dialErr } poolConfig.ConnConfig.DialFunc = dialer } connectCtx, cancelConnect := context.WithTimeout(ctx, cfg.ConnectTimeout) defer cancelConnect() pool, err := pgxpool.NewWithConfig(connectCtx, poolConfig) if err != nil { return nil, fmt.Errorf("%w: pool could not be created", ErrUnavailable) } client := &Client{pool: pool, config: cfg} pingCtx, cancelPing := context.WithTimeout(ctx, cfg.ConnectTimeout) defer cancelPing() if err := pool.Ping(pingCtx); err != nil { pool.Close() return nil, fmt.Errorf("%w: cannot reach the external read-only database", ErrUnavailable) } auditCtx, cancelAudit := context.WithTimeout(ctx, cfg.QueryTimeout) defer cancelAudit() report, err := AssertReadOnly(auditCtx, poolQuerier{pool: pool}) if err != nil { pool.Close() return nil, err } safety, err := AuditSourceSafety(auditCtx, poolQuerier{pool: pool}) if err != nil { pool.Close() return nil, err } if cfg.MaxConns > int32(safety.ConnectionLimit) { pool.Close() return nil, fmt.Errorf("%w: pool exceeds source role connection budget", ErrNotReadOnly) } client.report = report client.safety = safety return client, nil } // Close 释放独立 pool(治理主 pool 完全不受影响)。 func (c *Client) Close() { if c != nil && c.pool != nil { c.pool.Close() } } // ACL 返回启动时自检的权限报告(只含角色与 ACL,不含业务数据)。 func (c *Client) ACL() ACLReport { return c.report } // Safety preserves transport/TEMP findings without mislabelling them as fixed. func (c *Client) Safety() SourceSafety { return c.safety } // Config 返回生效后的配置,**已清掉所有连接/凭据字段**(secret 文件路径与治理库 DSN 都不外传; // 之前只清了 DSNFile,治理库连接串会跟着这个结构被复制出去)。 func (c *Client) Config() Config { cfg := c.config cfg.DSNFile = "" cfg.GovernanceDatabaseURL = "" cfg.DialContext = nil return cfg } // Available 是给健康检查/日志用的轻量探测:一次 SELECT 1,带自己的超时。 func (c *Client) Available(ctx context.Context) error { if c == nil || c.pool == nil { return ErrUnavailable } probeCtx, cancel := context.WithTimeout(ctx, c.config.ConnectTimeout) defer cancel() var one int if err := c.pool.QueryRow(probeCtx, "SELECT 1").Scan(&one); err != nil { return fmt.Errorf("%w: probe failed", ErrUnavailable) } if one != 1 { return fmt.Errorf("%w: probe returned an unexpected value", ErrUnavailable) } return nil } // poolQuerier 让 *pgxpool.Pool 适配本包的最小接口(ACL 与仓储都只用这两种方法)。 type poolQuerier struct{ pool *pgxpool.Pool } func (q poolQuerier) QueryRow(ctx context.Context, sql string, args ...any) rowScanner { return q.pool.QueryRow(ctx, sql, args...) } func (q poolQuerier) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) { return q.pool.Query(ctx, sql, args...) } // withReadOnlyTx 把一次读放进 REPEATABLE READ + READ ONLY 事务:统计口径固定在同一个 // as_of 上,且即便账号被误配成可写,这里也没有写的机会。 func (c *Client) withReadOnlyTx(ctx context.Context, fn func(ctx context.Context, querier querier) error) error { if c == nil || c.pool == nil { return ErrUnavailable } queryCtx, cancel := context.WithTimeout(ctx, c.config.QueryTimeout) defer cancel() tx, err := c.pool.BeginTx(queryCtx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly}) if err != nil { return fmt.Errorf("%w: cannot open a read-only transaction", ErrUnavailable) } defer func() { _ = tx.Rollback(context.Background()) }() if _, err := AssertReadOnly(queryCtx, txQuerier{tx: tx}); err != nil { return err } if _, err := AuditSourceSafety(queryCtx, txQuerier{tx: tx}); err != nil { return err } if err := fn(queryCtx, txQuerier{tx: tx}); err != nil { return err } if err := tx.Commit(queryCtx); err != nil { return fmt.Errorf("%w: read-only transaction failed", ErrUnavailable) } return nil } type querier interface { QueryRow(ctx context.Context, sql string, args ...any) rowScanner Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) } type txQuerier struct{ tx pgx.Tx } func (q txQuerier) QueryRow(ctx context.Context, sql string, args ...any) rowScanner { return q.tx.QueryRow(ctx, sql, args...) } func (q txQuerier) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) { return q.tx.Query(ctx, sql, args...) } // ErrUnavailableIfNil 让调用方把 nil 客户端当成"未启用"而不是 panic。 func ErrUnavailableIfNil(client *Client) error { if client == nil { return ErrUnavailable } return nil } // hostPortOf 从 DSN 取"主机:端口"(缺端口按 5432),只用于固定隧道的拨号地址。 // 只做解析,不返回任何凭据。 func hostPortOf(dsn string) (string, error) { parsed, err := url.Parse(strings.TrimSpace(dsn)) if err != nil || parsed.Hostname() == "" { return "", fmt.Errorf("%w: DSN has no host to dial", ErrUnavailable) } port := parsed.Port() if port == "" { port = "5432" } return parsed.Hostname() + ":" + port, nil }