tool

package
v0.1.17 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package tool defines the DML tool components and their registry. Each tool implements the Tool interface; Enabled(flags) decides whether it is registered with the MCP server (invariant I8). CostGated marks tools whose execution must pass the cost gate (invariant I4). Tools construct relalg.IR, which codegen renders; they never build SQL by hand, keeping queries inject-proof.

Index

Constants

View Source 
const (
	CodeUnauthorized        = "UNAUTHORIZED"
	CodeEntityNotFound      = "ENTITY_NOT_FOUND"
	CodeEntityUnavailable   = "ENTITY_UNAVAILABLE"
	CodeInvalidInput        = "INVALID_INPUT"
	CodeDMLToolsDisabled    = "DML_TOOLS_DISABLED"
	CodeUnsafeWrite         = "UNSAFE_WRITE"
	CodeDatabaseError       = "DATABASE_ERROR"
	CodeCostExceeded        = "COST_EXCEEDED"
	CodeBudgetExceeded      = "BUDGET_EXCEEDED"
	CodeTransactionNotFound = "TRANSACTION_NOT_FOUND"
	CodeTransactionScope    = "TRANSACTION_SCOPE"
	CodeTransactionCapacity = "TRANSACTION_CAPACITY"
	CodeTransactionStale    = "TRANSACTION_STALE"
	CodeAmbiguousFieldScope = "AMBIGUOUS_FIELD_SCOPE"
	CodeConstraintViolation = "CONSTRAINT_VIOLATION"
	CodeDatasourceForbidden = "DATASOURCE_FORBIDDEN"
	CodeAmbiguousEntity     = "AMBIGUOUS_ENTITY"
	CodeOutcomeUnknown      = "OUTCOME_UNKNOWN"
	CodeAuditUnavailable    = "AUDIT_UNAVAILABLE"
	CodeRateLimited         = "RATE_LIMITED"
	// CodeOverloaded: the process is at capacity (calls in flight, request
	// rate, execution slots); CodeDatasourceUnavailable: the datasource keeps
	// failing and calls to it are held off for a while (circuit breaker).
	CodeOverloaded            = "OVERLOADED"
	CodeDatasourceUnavailable = "DATASOURCE_UNAVAILABLE"
)

Stable machine codes for business-level rejections. Retryable means a revised request could succeed under the caller's current privileges; hints may only tighten or equivalently rewrite the request, never widen it.

View Source 
const (
	OutcomeCommitted  = "committed"
	OutcomeRolledBack = "rolledBack"
	OutcomeExpired    = "expired"
	// OutcomeUnknown is a commit whose connection broke or whose deadline
	// passed while it ran: the transaction may or may not have committed.
	OutcomeUnknown = "unknown"
)

How an explicit transaction ended, as its tombstone records it.

View Source 
const ActionSQL = "sql"

ActionSQL is the audited action of the SQL escape hatch.

Variables

View Source 
var (
	// ErrEntityNotFound is returned when the requested entity is unknown.
	ErrEntityNotFound = errors.New("tool: entity not found")
	// ErrEntityUnavailable is returned for an entity whose table or columns
	// are missing from the database.
	ErrEntityUnavailable = errors.New("tool: entity unavailable")
	// ErrCallerRateLimited is returned past the caller's own rate or calls in
	// flight (a role's or a user's limits).
	ErrCallerRateLimited = errors.New("tool: the caller's request limit is reached")
	// ErrUnauthorized is returned when the role lacks the action.
	ErrUnauthorized = errors.New("tool: unauthorized")
	// ErrInvalidInput is returned for malformed tool input.
	ErrInvalidInput = errors.New("tool: invalid input")
	// ErrDMLToolsDisabled is returned when an entity is not exposed to the
	// generic entity tools.
	ErrDMLToolsDisabled = errors.New("tool: entity DML tools disabled")
	// ErrUnsafeWrite is returned when an update/delete lacks a PK-scoped filter.
	ErrUnsafeWrite = errors.New("tool: unsafe write without primary-key filter")
	// ErrDuplicateTool is returned by NewRegistry for duplicate tool names.
	ErrDuplicateTool = errors.New("tool: duplicate name")
	// ErrDatabase identifies errors returned by the database driver.
	ErrDatabase = errors.New("tool: database error")
	// ErrConstraintViolation is a write rejected by a database constraint.
	ErrConstraintViolation = errors.New("tool: constraint violation")
	// ErrDatasourceForbidden is a statement the datasource's account may not
	// run: a missing database privilege or a read-only server.
	ErrDatasourceForbidden = errors.New("tool: the datasource connection is not permitted to do this")
)

Sentinel errors. Business errors (Unauthorized/NotFound/UnsafeWrite/Cost) are mapped by x/mcpserver to IsError results; protocol errors to JSON-RPC.

View Source 
var (
	ErrTransactionNotFound = errors.New("tool: transaction not found")
	ErrTransactionScope    = errors.New("tool: transaction scope mismatch")
	ErrTransactionCapacity = errors.New("tool: transaction capacity reached")
	// ErrTransactionStale rejects statements in a transaction whose datasource
	// a reload has since pointed at another connection: the configuration they
	// would be planned with no longer describes the database it runs on.
	ErrTransactionStale = errors.New("tool: transaction datasource was reconfigured; roll it back and begin again")
)
View Source 
var ErrAuditUnavailable = errors.New("tool: the audit log is unavailable; execute_sql is audited fail closed")

ErrAuditUnavailable is an escape hatch call refused, or its result withheld, because its audit record could not be written: the hatch is audited fail closed.

View Source 
var ErrOutcomeUnknown = errors.New("tool: the database may or may not have carried out the write")

ErrOutcomeUnknown marks a write or a commit the database may or may not have carried out: its connection broke or its deadline passed while it ran. Retrying it blindly may apply it twice.

Functions

func DecisionIDFromContext added in v0.1.5 

func DecisionIDFromContext(ctx context.Context) string

DecisionIDFromContext returns the decision ID attached by RunTool, or "".

func NewDecisionID added in v0.1.5 

func NewDecisionID() string

NewDecisionID returns a 128-bit random identifier correlating one tool call's MCP response, audit event, and trace span. crypto/rand.Read never fails (since Go 1.24 it crashes the program instead), so the identifier is never predictable.

func UsableBy added in v0.1.12 

func UsableBy(
	ctx context.Context, authz rbac.Authorizer, role string, subject map[string]any,
) func(entity.Entity) bool

UsableBy reports the entities a caller can reach for some action, as entity discovery does (see rbac.Decision.Reachable); every entity when authz is nil. The answer for each entity is kept: naming one entity among many asks about its namesakes, and listing them asks about each.

func VisibleKeys added in v0.1.11 

func VisibleKeys(e entity.Entity, visible []string) [][]string

VisibleKeys lists the entity's identity keys whose every column is among visible, the fields a caller can use to address one row.

func WithDecisionID added in v0.1.5 

func WithDecisionID(ctx context.Context, id string) context.Context

WithDecisionID attaches a decision ID to ctx for hooks and telemetry.

func WrapDBError 

func WrapDBError(err error) error

WrapDBError classifies a database driver error while preserving its cause: a refused privilege becomes ErrDatasourceForbidden, anything else ErrDatabase. Neither reports the driver message to clients.

Types

type AggregateTool 

type AggregateTool struct{}

AggregateTool runs an aggregate query (cost-gated).

func (AggregateTool) CostGated 

func (AggregateTool) CostGated()

func (AggregateTool) Enabled 

func (AggregateTool) Enabled(f config.ToolFlags) bool

func (AggregateTool) Info 

func (AggregateTool) Info() Info

func (AggregateTool) Run 

func (AggregateTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type AmbiguousEntityError added in v0.1.12 

type AmbiguousEntityError struct {
	Ref        string
	Candidates []string
}

AmbiguousEntityError reports an entity reference naming more than one entity the caller can use. Candidates name each of them unambiguously; entities the caller cannot use are neither counted nor listed.

func (*AmbiguousEntityError) Error added in v0.1.12 

func (e *AmbiguousEntityError) Error() string

func (*AmbiguousEntityError) Unwrap added in v0.1.12 

func (e *AmbiguousEntityError) Unwrap() error

type AmbiguousFieldScopeError added in v0.1.11 

type AmbiguousFieldScopeError struct {
	Reason      string
	FieldScopes [][]string
}

AmbiguousFieldScopeError reports that no single grant covers every field a request uses. FieldScopes are field sets the caller can already read, so exposing them is not a side channel. It unwraps to ErrUnauthorized.

func (*AmbiguousFieldScopeError) Error added in v0.1.11 

func (e *AmbiguousFieldScopeError) Error() string

func (*AmbiguousFieldScopeError) Unwrap added in v0.1.11 

func (e *AmbiguousFieldScopeError) Unwrap() error

type BeginTransactionTool 

type BeginTransactionTool struct{}

func (BeginTransactionTool) Enabled 

func (BeginTransactionTool) Enabled(f config.ToolFlags) bool

func (BeginTransactionTool) Info 

func (BeginTransactionTool) Info() Info

func (BeginTransactionTool) Run 

func (BeginTransactionTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type CacheTarget added in v0.1.11 

type CacheTarget struct {
	Physical string
	Relation string
}

CacheTarget names the cached reads a write invalidates: Relation of the physical database Physical, or all of it when Relation is empty (see cache.Cache).

type Caller added in v0.1.13 

type Caller struct {
	Session string
	Role    string
	Subject map[string]any
}

Caller is who holds a transaction: the transport session it was begun in and the authorization identity it was begun under. A statement of the transaction must come from the same caller.

type CommitTransactionTool 

type CommitTransactionTool struct{}

func (CommitTransactionTool) Enabled 

func (CommitTransactionTool) Enabled(f config.ToolFlags) bool

func (CommitTransactionTool) Info 

func (CommitTransactionTool) Info() Info

func (CommitTransactionTool) Run 

func (CommitTransactionTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type ConstraintViolationError added in v0.1.11 

type ConstraintViolationError struct {
	Kind   string
	Fields []string
}

ConstraintViolationError reports a write the database rejected for violating a constraint. Fields lists the violating columns the caller may see; the constraint name and the database message are never included.

func (*ConstraintViolationError) Error added in v0.1.11 

func (e *ConstraintViolationError) Error() string

func (*ConstraintViolationError) Unwrap added in v0.1.11 

func (e *ConstraintViolationError) Unwrap() error

type Context 

type Context struct {
	*Services
	Role       string         // principal key: a role name, or "user:<name>" for a user
	User       string         // configured user name, empty on the role path
	UserRoles  []string       // the user's roles, for audit
	Subject    map[string]any // caller attributes for row-level ${subject.x} policies
	Session    string         // MCP session ID when the transport provides one
	DecisionID string         // per-call ID correlating response, audit, and trace
	// DB, Dialect, Gate and Analyze are the entity's datasource's, once
	// routed (see routeEntity); DataSource names it.
	DB           store.DB
	Dialect      dialect.Dialect
	Gate         cost.Gate
	Analyze      cost.AnalyzePolicy
	DataSource   string
	BudgetLimits budget.Limits
	Transaction  string
	// contains filtered or unexported fields
}

Context is one call: who makes it, where it is routed, and the Services it runs on. It is passed by value and routed by copy (see routeEntity).

type CostGated 

type CostGated interface {
	Tool
	CostGated()
}

CostGated marks a tool whose execution must pass the cost gate.

type CreateTool 

type CreateTool struct{}

CreateTool inserts one record.

func (CreateTool) Enabled 

func (CreateTool) Enabled(f config.ToolFlags) bool

func (CreateTool) Info 

func (CreateTool) Info() Info

func (CreateTool) Run 

func (CreateTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type DataSource 

type DataSource struct {
	DB             store.DB
	Write          store.DB
	Execute        store.DB
	ReadTx         store.TxBeginner
	ReadAfterWrite time.Duration
	Dialect        dialect.Dialect
	Gate           cost.Gate
	Analyze        cost.AnalyzePolicy
}

DataSource is the per-entity execution route: DB is the read connection; Write and Execute, when set, serve writes and procedure calls (see connectionFor), and ReadTx begins read-only transactions.

type DeleteTool 

type DeleteTool struct{}

DeleteTool deletes records (cost-gated, off by default).

func (DeleteTool) CostGated 

func (DeleteTool) CostGated()

func (DeleteTool) Enabled 

func (DeleteTool) Enabled(f config.ToolFlags) bool

func (DeleteTool) Info 

func (DeleteTool) Info() Info

func (DeleteTool) Run 

func (DeleteTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type Denial added in v0.1.5 

type Denial struct {
	Code        string         `json:"code"`
	Reason      string         `json:"reason"`
	Retryable   bool           `json:"retryable"`
	Constraints map[string]any `json:"constraints,omitempty"`
	Hints       []string       `json:"hints,omitempty"`
	DecisionID  string         `json:"decisionId"`
}

Denial is the stable, machine-readable rejection contract returned to MCP clients for business-level errors. Field names and code values are part of the public tool contract: adding a new optional field or a new code is a compatible change; renaming or removing either is breaking.

func DenialFor added in v0.1.5 

func DenialFor(err error, decisionID string) (Denial, bool)

DenialFor maps a business-level error to the rejection contract. ok is false for internal errors, which must not be reflected to clients. A statement whose failure rolled its transaction back says so in constraints.transaction.

type DescribeTool 

type DescribeTool struct{}

DescribeTool lists entities or one entity's fields.

func (DescribeTool) Enabled 

func (DescribeTool) Enabled(f config.ToolFlags) bool

Enabled implements Tool.

func (DescribeTool) Info 

func (DescribeTool) Info() Info

Info implements Tool.

func (DescribeTool) Run 

func (DescribeTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

Run implements Tool.

type EscapeRoute added in v0.1.15 

type EscapeRoute struct {
	Connection string
	DB         store.DB
	Dialect    dialect.Dialect
	Explainer  cost.Explainer
	Threshold  cost.Threshold
}

EscapeRoute is where the SQL escape hatch (execute_sql) runs on a datasource: the connection its sqlEscape names, EXPLAIN on that same connection (nil when the provider has none) and the thresholds the estimate is scored against.

type ExecuteSQLTool added in v0.1.15 

type ExecuteSQLTool struct{}

ExecuteSQLTool is the trusted SQL escape hatch: it runs one statement as it is on a datasource admitting it, for a user holding sql:execute@<datasource>, under the governed plane's hard limits and a fail-closed audit. It has no entity: nothing is masked or filtered, and no IR, metric or extension reaches it.

func (ExecuteSQLTool) Enabled added in v0.1.15 

func (ExecuteSQLTool) Enabled(f config.ToolFlags) bool

Enabled implements Tool: the hatch is registered by tools.executeSql only.

func (ExecuteSQLTool) Info added in v0.1.15 

func (ExecuteSQLTool) Info() Info

Info implements Tool.

func (ExecuteSQLTool) Run added in v0.1.15 

func (ExecuteSQLTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

Run implements Tool.

type ExecuteTool 

type ExecuteTool struct{}

ExecuteTool calls a stored procedure.

func (ExecuteTool) CostGated 

func (ExecuteTool) CostGated()

func (ExecuteTool) Enabled 

func (ExecuteTool) Enabled(f config.ToolFlags) bool

func (ExecuteTool) Info 

func (ExecuteTool) Info() Info

func (ExecuteTool) Run 

func (ExecuteTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type Info 

type Info struct {
	Name string
	// Title is the human-readable name clients display.
	Title       string
	Description string
	InputSchema json.RawMessage
	// ReadOnly, Destructive and Idempotent are the MCP behavior hints: the
	// tool changes nothing; a change may delete or overwrite data; repeating
	// a call with the same input changes nothing more.
	ReadOnly    bool
	Destructive bool
	Idempotent  bool
	// Object says a call returns one object (Content[0]) rather than rows.
	Object bool
	// Action is the audited action; read, aggregate and execute also size the
	// budget reservation.
	Action string
}

Info is a tool's static metadata, mapped to an MCP tool definition.

type Limits added in v0.1.11 

type Limits struct {
	Timeout                    time.Duration
	MaxRows                    int64
	MaxProcedureRows           int64
	MaxReturnedBytes           int64
	MaxINListSize              int
	MaxFilterConditions        int
	MaxGroupByFields           int
	MaxAggregates              int
	MaxExpand                  int
	CacheMaxEntryRows          int
	CacheMaxEntryBytes         int64
	TransactionBeginTimeout    time.Duration
	TransactionCommitTimeout   time.Duration
	TransactionRollbackTimeout time.Duration
	// SQLEscapeEstimateRequired refuses SQL the escape hatch cannot
	// estimate (cost.sqlEscape.estimate: required).
	SQLEscapeEstimateRequired bool
	// Tightening is the caller's own stricter cost gate.
	Tightening cost.Tightening
}

Limits are the configured per-call limits; zero means unlimited (or, for the transaction timeouts, the query Timeout).

type ProcedureTool 

type ProcedureTool struct {
	Entity entity.Entity
	// Name is the tool's name among the exposed procedures (see
	// ProcedureTools); procedureToolBase when empty.
	Name string
}

ProcedureTool exposes one configured procedure as an independent MCP tool. It accepts the procedure parameters directly and delegates execution to the same implementation as execute_entity.

func FindProcedureTool added in v0.1.11 

func FindProcedureTool(reg *entity.Registry, name string) (ProcedureTool, bool)

FindProcedureTool returns the exposed procedure tool named name.

func ProcedureTools added in v0.1.11 

func ProcedureTools(reg *entity.Registry) []ProcedureTool

ProcedureTools returns the procedures exposed as their own tools: trusted procedures configured with a custom tool. Each is named procedureToolBase; procedures whose base names collide (same-named procedures of different namespaces, or names that normalize alike) add a hash of their Name.

func (ProcedureTool) CostGated 

func (ProcedureTool) CostGated()

func (ProcedureTool) Enabled 

func (ProcedureTool) Enabled(config.ToolFlags) bool

Enabled implements Tool. Procedure tools are registered independently of the generic tool flags.

func (ProcedureTool) Info 

func (t ProcedureTool) Info() Info

Info implements Tool.

func (ProcedureTool) Run 

func (t ProcedureTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

Run implements Tool.

type RawDBError added in v0.1.15 

type RawDBError struct {
	Kind  error
	Cause error
}

RawDBError is a database error of the escape hatch's statement, reported with the driver's message: the caller holds the connection's whole account, so the message adds nothing it could not see, and it is what they are after. It is its Kind (ErrDatabase or ErrDatasourceForbidden) to errors.Is and unwraps to the driver's error.

func (*RawDBError) Error added in v0.1.15 

func (e *RawDBError) Error() string

func (*RawDBError) Is added in v0.1.15 

func (e *RawDBError) Is(target error) bool

func (*RawDBError) SQLState added in v0.1.15 

func (e *RawDBError) SQLState() string

SQLState is the SQLSTATE of the driver's error when it reports one.

func (*RawDBError) Unwrap added in v0.1.15 

func (e *RawDBError) Unwrap() error

type ReadTool 

type ReadTool struct{}

ReadTool reads records (cost-gated).

func (ReadTool) CostGated 

func (ReadTool) CostGated()

func (ReadTool) Enabled 

func (ReadTool) Enabled(f config.ToolFlags) bool

func (ReadTool) Info 

func (ReadTool) Info() Info

func (ReadTool) Run 

func (ReadTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type Registry 

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

Registry holds an immutable set of tools.

func NewRegistry 

func NewRegistry(tools []Tool) (*Registry, error)

NewRegistry builds a Registry, rejecting duplicate tool names.

func (*Registry) Enabled 

func (r *Registry) Enabled(flags config.ToolFlags) []Tool

Enabled returns the tools whose Enabled(flags) is true.

func (*Registry) Get 

func (r *Registry) Get(name string) (Tool, bool)

Get returns a tool by name.

func (*Registry) Tools 

func (r *Registry) Tools() []Tool

Tools returns all registered tools.

type Result 

type Result struct {
	Content      []map[string]any
	ReturnedRows int64
	// Counted says ReturnedRows is the row count even when zero; otherwise
	// zero means the tool did not count and Content's size stands in.
	Counted              bool
	ReturnedBytes        int64
	EstimatedScannedRows int64
	// Grants lists covering grant IDs for audit; it is not sent to clients.
	Grants []string
}

Result is a tool's outcome: the rows returned to the agent plus usage for budgets and audit.

func RunTool 

func RunTool(ctx context.Context, t Tool, input json.RawMessage, tc Context) (Result, error)

RunTool executes a tool with the cross-cutting wiring that must apply to every call regardless of transport: lifecycle hooks, bounded concurrency + backpressure + circuit breaking + (for read-only tools) singleflight via the engine, and best-effort audit. Transports (x/mcpserver) call this instead of Tool.Run directly, keeping the wiring in the core where it is unit-testable. A nil Engine/Auditor/Hooks each degrade to a no-op.

type ResultMemory added in v0.1.13 

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

ResultMemory bounds the bytes of the results the process holds at once, across calls: each call's rows hold their share from when they are read until the call ends. It belongs to the process and outlives configurations. A nil ResultMemory bounds nothing.

func NewResultMemory added in v0.1.13 

func NewResultMemory(capacity int64) *ResultMemory

NewResultMemory returns a bound of capacity bytes (0: none).

func (*ResultMemory) InUse added in v0.1.13 

func (r *ResultMemory) InUse() int64

InUse returns the bytes held.

func (*ResultMemory) SetCapacity added in v0.1.13 

func (r *ResultMemory) SetCapacity(capacity int64)

SetCapacity changes the bound for the reservations that follow.

type RollbackTransactionTool 

type RollbackTransactionTool struct{}

func (RollbackTransactionTool) Enabled 

func (RollbackTransactionTool) Enabled(f config.ToolFlags) bool

func (RollbackTransactionTool) Info 

func (RollbackTransactionTool) Info() Info

func (RollbackTransactionTool) Run 

func (RollbackTransactionTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type SchemaDrift added in v0.1.17 

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

SchemaDrift is the signal that a statement found the database's schema changed under the running configuration: a table or a column it named is gone. Whoever serves the configuration assembles it again on the signal, so the entities the change broke are reported unavailable (see entity.Entity.Unavailable). The zero value is ready; a nil one drops reports.

func (*SchemaDrift) Pending added in v0.1.17 

func (d *SchemaDrift) Pending() bool

Pending reports whether the signal is raised.

func (*SchemaDrift) Report added in v0.1.17 

func (d *SchemaDrift) Report() bool

Report raises the signal; true when it was not raised already.

func (*SchemaDrift) Take added in v0.1.17 

func (d *SchemaDrift) Take() bool

Take reports whether the signal was raised since the last Take, and lowers it.

type Services added in v0.1.13 

type Services struct {
	Registry   *entity.Registry
	Authorizer rbac.Authorizer
	Masker     mask.Masker
	Cache      cache.Cache[[]map[string]any]
	// Generation is the configuration generation serving the call; cached
	// reads of different generations are kept apart.
	Generation uint64
	// WriteTargets, when set, holds what a write through each entity
	// invalidates (see BuildWriteTargets).
	WriteTargets *WriteTargets
	Engine       *engine.Engine
	Auditor      audit.Auditor
	Hooks        *hook.Hooks
	Limits
	Feedback     cost.FeedbackStore
	Sources      map[string]DataSource
	Budget       budget.Manager
	Transactions *TransactionManager
	Writes       *WriteTracker
	TxBeginners  map[string]store.TxBeginner
	// ResultMemory bounds the results the process holds at once.
	ResultMemory *ResultMemory
	// Escapes are the datasources admitting the SQL escape hatch, by name.
	Escapes map[string]EscapeRoute
	// Callers bounds the rate and the calls in flight of each caller (by
	// its principal key); nil bounds none.
	Callers *ratelimit.Keyed
	// Drift is raised when a statement finds the schema changed; nil drops
	// it.
	Drift *SchemaDrift
}

Services are what every call of one configuration shares: the entities and the policy, the cache, the engine, the audit sink and the hooks, the limits, the datasources, and the process state (transactions, budgets, write tracking, result memory) that outlives the configuration. A Context refers to them; it never copies them. A nil field degrades to a no-op where the call can go on without it.

type Tool 

type Tool interface {
	Info() Info
	Enabled(flags config.ToolFlags) bool
	Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)
}

Tool is a single DML capability.

func DefaultTools 

func DefaultTools() []Tool

DefaultTools returns the entity and explicit transaction tool instances.

type TransactionEndedError added in v0.1.13 

type TransactionEndedError struct{ Outcome string }

TransactionEndedError is ErrTransactionNotFound for a token whose transaction ended recently, saying how: a caller whose commit timed out learns whether it is worth retrying. Only the caller the transaction was bound to learns it.

func (*TransactionEndedError) Error added in v0.1.13 

func (e *TransactionEndedError) Error() string

func (*TransactionEndedError) Unwrap added in v0.1.13 

func (e *TransactionEndedError) Unwrap() error

type TransactionManager 

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

TransactionManager owns bounded, expiring explicit transaction handles. Tokens are unguessable and additionally bound to role, subject, and source.

func NewTransactionManager 

func NewTransactionManager(ttl time.Duration, maxOpen int) *TransactionManager

func (*TransactionManager) Begin 

func (m *TransactionManager) Begin(
	ctx context.Context,
	beginner store.TxBeginner,
	caller Caller,
	datasource string,
	opts *store.TxOptions,
) (string, error)

func (*TransactionManager) Close 

func (m *TransactionManager) Close()

func (*TransactionManager) Commit 

func (m *TransactionManager) Commit(ctx context.Context, token string, caller Caller) ([]CacheTarget, error)

Commit commits and returns the cache targets the transaction wrote. The list is returned only after a commit that succeeded, or may have (with an ErrOutcomeUnknown), so callers can invalidate global read caches without rollback pollution.

func (*TransactionManager) Configuration 

func (m *TransactionManager) Configuration() (time.Duration, int)

Configuration returns the limits in force.

func (*TransactionManager) DB 

func (m *TransactionManager) DB(
	ctx context.Context,
	token string,
	caller Caller,
	datasource string,
	connections []store.TxBeginner,
) (store.DB, error)

func (*TransactionManager) MarkDirty 

func (m *TransactionManager) MarkDirty(
	ctx context.Context,
	token string,
	caller Caller,
	datasource string,
	connections []store.TxBeginner,
	targets ...CacheTarget,
) error

MarkDirty records the cache targets a write inside a transaction changed; connections are as for DB.

func (*TransactionManager) Rollback 

func (m *TransactionManager) Rollback(ctx context.Context, token string, caller Caller) error

Rollback rolls back the transaction.

func (*TransactionManager) RollbackSession 

func (m *TransactionManager) RollbackSession(session string)

RollbackSession rolls back all handles owned by a disconnected non-empty transport session. Token-only transports use TTL and App.Close instead.

func (*TransactionManager) SetConnectionLimit added in v0.1.13 

func (m *TransactionManager) SetConnectionLimit(n int)

SetConnectionLimit bounds the transactions open on one connection at once (0: no bound), for every later begin.

func (*TransactionManager) SetIdleTimeout added in v0.1.17 

func (m *TransactionManager) SetIdleTimeout(d time.Duration)

SetIdleTimeout rolls back the transactions begun from now on once no statement used them for d (0: never).

func (*TransactionManager) UpdateLimits added in v0.1.12 

func (m *TransactionManager) UpdateLimits(ttl time.Duration, maxOpen int)

UpdateLimits applies new limits: ttl to the transactions begun from now on, maxOpen to every later begin.

func (*TransactionManager) UseBus added in v0.1.13 

func (m *TransactionManager) UseBus(b *bus.Bus)

UseBus runs the expiry timers as background tasks of b.

func (*TransactionManager) Validate 

func (m *TransactionManager) Validate(ctx context.Context, token string, caller Caller) error

Validate verifies a token's transport and authorization identity without exposing its transaction or datasource.

type TransactionRolledBackError added in v0.1.17 

type TransactionRolledBackError struct{ Err error }

TransactionRolledBackError is the error of a statement whose failure rolled its transaction back; its token is then not found (outcome rolledBack).

func (*TransactionRolledBackError) Error added in v0.1.17 

func (e *TransactionRolledBackError) Error() string

func (*TransactionRolledBackError) Unwrap added in v0.1.17 

func (e *TransactionRolledBackError) Unwrap() error

type UnestimableError added in v0.1.15 

type UnestimableError struct{ Cause error }

UnestimableError is a statement the escape hatch could not estimate: the datasource's EXPLAIN failed on it (DDL, SET, SHOW, a syntax error, an error raised while planning). It is refused while cost.sqlEscape.estimate is required, as cost exceeded, with the database's message first: that is what the caller has to act on.

func (*UnestimableError) Error added in v0.1.15 

func (e *UnestimableError) Error() string

func (*UnestimableError) Unwrap added in v0.1.15 

func (e *UnestimableError) Unwrap() error

Unwrap returns cost.ErrCostExceeded: an estimate the gate requires is missing.

type UpdateTool 

type UpdateTool struct{}

UpdateTool updates records (cost-gated).

func (UpdateTool) CostGated 

func (UpdateTool) CostGated()

func (UpdateTool) Enabled 

func (UpdateTool) Enabled(f config.ToolFlags) bool

func (UpdateTool) Info 

func (UpdateTool) Info() Info

func (UpdateTool) Run 

func (UpdateTool) Run(ctx context.Context, input json.RawMessage, tc Context) (Result, error)

type WriteTargets added in v0.1.12 

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

WriteTargets is what a write through each entity invalidates, worked out once per configuration (see BuildWriteTargets), and which datasources reach each physical database, whose session reads then follow the write.

func BuildWriteTargets added in v0.1.12 

func BuildWriteTargets(reg *entity.Registry) *WriteTargets

BuildWriteTargets works out what a write through each entity of reg invalidates, so writes do not walk the registry.

type WriteTracker added in v0.1.11 

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

WriteTracker remembers when each session last wrote to each datasource, so its reads can follow its writes for a datasource's readAfterWrite window. A nil tracker records nothing.

func NewWriteTracker added in v0.1.11 

func NewWriteTracker() *WriteTracker

NewWriteTracker returns an empty tracker.

func (*WriteTracker) Forget added in v0.1.11 

func (w *WriteTracker) Forget(session string)

Forget drops a closed session.

func (*WriteTracker) Recent added in v0.1.11 

func (w *WriteTracker) Recent(session, datasource string, window time.Duration) bool

Recent reports whether session wrote to datasource within window.

func (*WriteTracker) Record added in v0.1.11 

func (w *WriteTracker) Record(session, datasource string)

Record notes a write by session to datasource.

func (*WriteTracker) Wrote added in v0.1.11 

func (w *WriteTracker) Wrote(session string) bool

Wrote reports whether session wrote anything recently enough to be remembered.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.