Files
knowledge-governance/internal/dobotaiops/pool.go
T

226 lines
7.9 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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
}