Documentation
¶
Overview ¶
Package bootstrap loads configuration and assembles the application: it resolves secret placeholders, opens the database provider, converts config entities to the core entity model, and wires the registry, authorizer, cost gate, engine, and tools. It is the only place that imports gopkg.in/yaml.v3 and x/providers.
Index ¶
- Variables
- func CapabilityWarnings(cfg *config.Config, capabilities EntityCapabilities) []string
- func CheckHotReload(old, next *config.Config) error
- func CheckPublishable(current, target revision.Revision, restartRequired bool) error
- func Load(path string) (*config.Config, error)
- func LoadBytes(data []byte) (*config.Config, error)
- func LoadRevision(rev revision.Revision) (*config.Config, error)
- func OfflineAuthorizer(cfg *config.Config) (rbac.Authorizer, error)
- func RedactDSN(driver, dsn string) string
- func RestartChanges(old, next *config.Config) []string
- func UserPrincipal(user string) string
- func ValidateFile(path string, resolver SecretResolver) error
- func ValidateStorePayload(cfg *config.Config) error
- type App
- func Assemble(cfg *config.Config) (*App, error)
- func AssembleWithConnections(cfg *config.Config, connections Connections) (*App, error)
- func AssembleWithProvider(cfg *config.Config, prov Provider) (*App, error)
- func AssembleWithProviders(cfg *config.Config, providers map[string]Provider) (*App, error)
- func AssembleWithResolver(cfg *config.Config, r SecretResolver) (*App, error)
- func (a *App) Close() error
- func (a *App) CloseContext(ctx context.Context) error
- func (a *App) Ping(ctx context.Context) error
- func (a *App) ToolContext(role string) tool.Context
- func (a *App) ToolContextForSubject(role string, subject map[string]any) tool.Context
- func (a *App) UserByName(name string) (UserIdentity, bool)
- func (a *App) UserByTokenHash(hash string) (UserIdentity, bool)
- type Capability
- type Connections
- type EntityCapabilities
- type EnvFileResolver
- type Provider
- type Runtime
- func (r *Runtime) Acquire() (*App, func(), error)
- func (r *Runtime) AppliedRevision() int64
- func (r *Runtime) Close() error
- func (r *Runtime) Current() *App
- func (r *Runtime) DatabasesReady(ctx context.Context) error
- func (r *Runtime) OnRevokedPrincipals(fn func([]string))
- func (r *Runtime) Reload(path string) error
- func (r *Runtime) ReloadWith(build func() (*App, error)) error
- func (r *Runtime) RollbackSession(session string)
- func (r *Runtime) SnapshotReady(context.Context) error
- func (r *Runtime) Stale() (StaleState, bool)
- func (r *Runtime) UserByName(name string) (UserIdentity, bool)
- func (r *Runtime) UserByTokenHash(hash string) (UserIdentity, bool)
- func (r *Runtime) Watch(ctx context.Context, path string, interval time.Duration, onError func(error)) error
- func (r *Runtime) WatchStore(ctx context.Context, store revision.Store, current int64, ...) error
- type SecretResolver
- type StaleState
- type UserIdentity
Constants ¶
This section is empty.
Variables ¶
var ErrPlaintextSecret = errors.New("store payload must not contain plaintext secrets")
ErrPlaintextSecret rejects store payloads that would persist credentials.
var ErrRestartRequired = errors.New("config change requires restart")
ErrRestartRequired marks a configuration change that cannot be applied by hot reload or publish without restarting the server.
var ErrRuntimeClosed = errors.New("bootstrap: runtime closed")
ErrRuntimeClosed is returned when a closed runtime is used.
var ErrUnsupportedDriver = providerregistry.ErrUnsupportedDriver
ErrUnsupportedDriver is returned for a driver with no provider yet.
Functions ¶
func CapabilityWarnings ¶ added in v0.1.11
func CapabilityWarnings(cfg *config.Config, capabilities EntityCapabilities) []string
CapabilityWarnings lists actions cfg grants that the routed connection cannot run, in a stable order.
func CheckHotReload ¶ added in v0.1.11
CheckHotReload reports whether next can replace old without a restart. File reload, store reload and store publish share this rule: transport, address, auth/TLS/trusted proxy, the tool set, custom procedure tools, switching users on or off, and transaction ttl/maxOpen need a restart.
func CheckPublishable ¶ added in v0.1.11
CheckPublishable verifies that target loads under the store rules and, when current is published (ID != 0), that switching to target needs no restart unless restartRequired is set. A current revision that no longer loads can only be replaced with restartRequired.
func LoadBytes ¶ added in v0.1.11
LoadBytes decodes, defaults and validates YAML configuration bytes and checks that every driver is registered, like Load does for a file.
func LoadRevision ¶ added in v0.1.11
LoadRevision verifies a revision's content hash and decodes its payload under the store-mode secret rule.
func OfflineAuthorizer ¶ added in v0.1.11
func OfflineAuthorizer(cfg *config.Config) (rbac.Authorizer, error)
OfflineAuthorizer compiles cfg's entities, roles and users into an authorizer without connecting to any database, for policy simulation.
func RedactDSN ¶
RedactDSN returns dsn with every password the driver would read replaced by ***, for logging and display.
func RestartChanges ¶ added in v0.1.11
RestartChanges lists the changes from old to next that need a restart.
func UserPrincipal ¶ added in v0.1.11
UserPrincipal returns the principal key of a configured user.
func ValidateFile ¶
func ValidateFile(path string, resolver SecretResolver) error
ValidateFile parses, defaults, validates, and resolves secrets without opening database connections.
func ValidateStorePayload ¶ added in v0.1.11
ValidateStorePayload enforces the store-mode secret rule: every non-empty DSN password must come from a ${...} placeholder and server.auth.token must be empty (configured users keep only token hashes).
Types ¶
type App ¶
type App struct {
Provider Provider
// Providers holds each datasource's read connection, which also serves
// introspection and EXPLAIN; Connections holds every connection.
Providers map[string]Provider
Connections Connections
// Capabilities are what the routed connections may do per entity action,
// as the databases reported when the App was assembled.
Capabilities EntityCapabilities
Prepared map[string]*store.PreparedDB
Sources map[string]tool.DataSource
Dialect dialect.Dialect
Registry *entity.Registry
Authorizer rbac.Authorizer
Masker mask.Masker
Gate cost.Gate
Engine *engine.Engine
Tools *tool.Registry
ToolFlags config.ToolFlags
DefaultRole string
DefaultUser string
// Users maps an enabled user name to its identity; UserTokens maps a
// tokenHash to the user name. Both follow the snapshot on reload.
Users map[string]UserIdentity
UserTokens map[string]string
Limits tool.Limits
Auditor audit.Auditor
Hooks *hook.Hooks
Cache cache.Cache[[]map[string]any]
Feedback cost.FeedbackStore
Analyze cost.AnalyzePolicy
Budget *budget.MemoryManager
Transactions *tool.TransactionManager
Writes *tool.WriteTracker
TxBeginners map[string]store.TxBeginner
// contains filtered or unexported fields
}
App is the assembled application, ready to serve.
func Assemble ¶
Assemble opens the provider and wires the application from cfg, using the default EnvFileResolver for secret placeholders.
func AssembleWithConnections ¶ added in v0.1.11
func AssembleWithConnections(cfg *config.Config, connections Connections) (*App, error)
AssembleWithConnections wires opened connections. Ownership transfers to the returned App on success. On failure the connections stay with the caller and every resource acquired here is released: configuration is checked before any resource is acquired. Each datasource's read connection serves introspection and EXPLAIN.
func AssembleWithProvider ¶
AssembleWithProvider wires the application using an injected provider (for testing with fakes).
func AssembleWithProviders ¶
AssembleWithProviders wires one provider per datasource, serving every connection the datasource configures. It is intended for tests and embedders; ownership transfers to the returned App on success.
func AssembleWithResolver ¶
func AssembleWithResolver(cfg *config.Config, r SecretResolver) (*App, error)
AssembleWithResolver resolves secrets with the given resolver, opens the provider, and wires the application. Use a custom resolver to integrate secret managers (Vault, AWS Secrets Manager, etc.) without coupling core to any specific backend.
func (*App) Close ¶
Close preserves the original unbounded close contract. Callers that need a shutdown deadline should use CloseContext.
func (*App) CloseContext ¶
CloseContext stops engine admission and drains all execution before rolling back transactions and releasing audit/provider resources.
func (*App) Ping ¶ added in v0.1.6
Ping verifies every configured database is reachable. It backs the /readyz/db readiness probe and stays off the tool execution path: it uses the provider's native connection ping when exposed and falls back to a trivial query otherwise.
func (*App) ToolContext ¶
ToolContext builds a per-request tool.Context for the given role.
func (*App) ToolContextForSubject ¶
ToolContextForSubject builds a per-request tool.Context for a role plus subject attributes (referenced by row-level ${subject.x} policies).
func (*App) UserByName ¶ added in v0.1.11
func (a *App) UserByName(name string) (UserIdentity, bool)
UserByName returns an enabled user by name.
func (*App) UserByTokenHash ¶ added in v0.1.11
func (a *App) UserByTokenHash(hash string) (UserIdentity, bool)
UserByTokenHash returns the enabled user whose tokenHash matches.
type Capability ¶ added in v0.1.11
type Capability struct {
Privilege introspect.Privilege
Connection string
// Columns lists the columns granted at column level when the table-level
// privilege is not granted.
Columns []string
Reason string
}
Capability says whether the connection an entity action routes to may run it, as far as the database reports (I-3). It informs administrators; the database decides each statement.
type Connections ¶ added in v0.1.11
Connections are opened providers by datasource and connection name.
type EntityCapabilities ¶ added in v0.1.11
type EntityCapabilities map[string]map[entity.Action]Capability
EntityCapabilities are capabilities by entity and action.
type EnvFileResolver ¶
type EnvFileResolver struct {
AllowedRoots []string
}
EnvFileResolver resolves ${ENV} (environment variables) and ${file:/path} (file contents, e.g. Kubernetes Secret volume mounts).
type Provider ¶
type Provider = coreprovider.Provider
Provider aggregates the core interfaces a database adapter must satisfy.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime owns the atomically replaceable App snapshot used by serving handlers. A successful reload publishes the new App before draining and closing the old one; a failed build leaves the current App untouched.
func NewRuntimeWithBuilder ¶
NewRuntimeWithBuilder creates a runtime with an injected reload builder. It is useful for embedders and tests that assemble providers themselves.
func (*Runtime) Acquire ¶
Acquire leases the current snapshot until the returned release function is called. It retries when racing with retirement.
func (*Runtime) AppliedRevision ¶ added in v0.1.11
AppliedRevision returns the store revision the runtime serves as tracked by WatchStore, or 0 before WatchStore starts.
func (*Runtime) Current ¶
Current returns the currently published App, or nil after Close. Handlers that execute work must use Acquire so the App cannot close during the call.
func (*Runtime) DatabasesReady ¶ added in v0.1.6
DatabasesReady pings every database of the current snapshot. It backs the /readyz/db readiness probe.
func (*Runtime) OnRevokedPrincipals ¶ added in v0.1.11
OnRevokedPrincipals registers fn to receive the principal keys of users that a successful reload removed or disabled, after the new snapshot is published. Transports use it to drop those users' sessions and roll back their transactions.
func (*Runtime) Reload ¶
Reload performs parse/default/validate/secret-resolution/assembly before atomically publishing the new App. Build failure preserves the old snapshot.
func (*Runtime) ReloadWith ¶ added in v0.1.11
ReloadWith publishes the App returned by build, with the same budget, transaction and drain handling as Reload.
func (*Runtime) RollbackSession ¶
RollbackSession rolls back transactions associated with a disconnected MCP session when the transport exposes a stable non-empty session ID.
func (*Runtime) SnapshotReady ¶ added in v0.1.6
SnapshotReady reports whether a configuration snapshot is currently published and servable. It backs the /readyz/snapshot readiness probe.
func (*Runtime) Stale ¶ added in v0.1.11
func (r *Runtime) Stale() (StaleState, bool)
Stale returns the unapplied published revision, if any.
func (*Runtime) UserByName ¶ added in v0.1.11
func (r *Runtime) UserByName(name string) (UserIdentity, bool)
UserByName resolves an enabled user against the current snapshot.
func (*Runtime) UserByTokenHash ¶ added in v0.1.11
func (r *Runtime) UserByTokenHash(hash string) (UserIdentity, bool)
UserByTokenHash resolves a tokenHash against the current snapshot.
func (*Runtime) Watch ¶
func (r *Runtime) Watch(ctx context.Context, path string, interval time.Duration, onError func(error)) error
Watch polls path for content changes and reloads it. Reload errors are reported through onError and do not stop the watcher or replace the old App.
func (*Runtime) WatchStore ¶ added in v0.1.11
func (r *Runtime) WatchStore( ctx context.Context, store revision.Store, current int64, interval time.Duration, build func(revision.Revision) (*App, error), onError func(error), ) error
WatchStore polls store for a newly published revision and reloads it with build. current is the revision the runtime already serves. Failures keep the current snapshot (fail-static) and are recorded in Stale; a later successful reload clears it.
type SecretResolver ¶
SecretResolver resolves ${...} placeholders in a string (e.g. a DSN). EnvFileResolver is the built-in implementation; custom implementations can back this by Vault, AWS Secrets Manager, GCP Secret Manager, etc., without coupling core to any specific backend.
type StaleState ¶ added in v0.1.11
type StaleState struct {
RevisionID int64
Err string
// RestartRequired reports that the revision only applies after a restart.
RestartRequired bool
}
StaleState describes a published store revision the runtime has not applied, either because building it failed or because it needs a restart.