registry

Documentation

Index

• Constants
• type Config
• type ExecuteResult
  • func (r *ExecuteResult) GetValue() any
• type FunctionLoader
• type Registry
  • func New(config Config) *Registry
  • func (r *Registry) Execute(ctx context.Context, fullName string, args map[string]any) (*ExecuteResult, error)
  • func (r *Registry) ExecuteInline(ctx context.Context, source string, args map[string]any) (*ExecuteResult, error)
  • func (r *Registry) GetBuiltins() map[string]*executor.BuiltinFunc
  • func (r *Registry) GetCompiled(ctx context.Context, name string) (*executor.CompiledFunction, bool)
  • func (r *Registry) Invalidate(fullName string)
  • func (r *Registry) ListCompiled() []string
  • func (r *Registry) ListFunctionNames() []string
  • func (r *Registry) Register(fullName, source string) error
  • func (r *Registry) RegisterBuiltin(name string, bf *executor.BuiltinFunc)
  • func (r *Registry) ResolveFunction(name string) (int, bool)
  • func (r *Registry) SetLoader(loader FunctionLoader)
  • func (r *Registry) Validate(source string) *ValidateResult
  • func (r *Registry) ValidateWithLookup(source string, lookup func(string) (int, bool)) *ValidateResult
• type ValidateResult

Constants

const DefaultMaxCallDepth = 1000

DefaultMaxCallDepth bounds user-function call depth when Config.MaxCallDepth is left at zero.

This default is not a tuning choice, it is a safety one. Exhausting the goroutine stack raises `fatal error: stack overflow`, which — unlike a panic — cannot be recovered and takes the whole host process down with it. A registry built from a zero-value Config is the documented way to embed DTL, so that path must not be the unbounded one.

1000 frames is far below the depth at which the stack is at risk and well above any plausible transformation, so legitimate work never meets it.

Types

type Config

type Config struct {
	// DefaultTimeout bounds wall-clock time for a single execution.
	// Zero means no timeout; it is not defaulted, because a limit that aborts
	// a legitimately slow transformation is a policy only the host can set.
	DefaultTimeout time.Duration

	// MaxCallDepth bounds nested user-function calls. Zero selects
	// DefaultMaxCallDepth. A negative value disables the limit entirely and
	// re-exposes the host process to an unrecoverable stack overflow — only
	// set it for trusted input you control.
	MaxCallDepth int
}

Config holds registry configuration.

type ExecuteResult

type ExecuteResult struct {
	Value any                   `json:"result"`
	Logs  []executor.DebugEntry `json:"logs,omitempty"`
}

ExecuteResult holds the execution result along with any debug output.

func (*ExecuteResult) GetValue

func (r *ExecuteResult) GetValue() any

GetValue returns the execution result value. Implements the DTLExecuteResult interface used by the formula extension.

type FunctionLoader

type FunctionLoader func(ctx context.Context, fullName string) (string, error)

FunctionLoader loads a function's source from external storage (e.g. database) by its fully-qualified name. The context carries workspace scope.

type Registry

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

Registry is the in-memory compiled function cache and execution engine. It owns the compiler, executor, and built-in function table.

func New

func New(config Config) *Registry

New creates a registry with stdlib loaded and ready for function registration.

func (*Registry) Execute

func (r *Registry) Execute(ctx context.Context, fullName string, args map[string]any) (*ExecuteResult, error)

Execute runs a named function with the given argument map.

func (*Registry) ExecuteInline

func (r *Registry) ExecuteInline(ctx context.Context, source string, args map[string]any) (*ExecuteResult, error)

ExecuteInline parses, compiles, and executes a DTL source string without caching.

func (*Registry) GetBuiltins

func (r *Registry) GetBuiltins() map[string]*executor.BuiltinFunc

GetBuiltins returns the built-in function table (read-only use).

The result is a fresh map combining the shared standard library with this registry's own registrations, so mutating it affects nothing. It is built per call — this is an introspection accessor, not an execution path; the executor resolves builtins without materialising a combined table.

func (*Registry) GetCompiled

func (r *Registry) GetCompiled(ctx context.Context, name string) (*executor.CompiledFunction, bool)

GetCompiled returns a compiled user-defined function by full name. If not found in the in-memory cache, it falls back to the loader (if set) to fetch and register the function from the database.

func (*Registry) Invalidate

func (r *Registry) Invalidate(fullName string)

Invalidate removes a compiled function from the cache.

func (*Registry) ListCompiled

func (r *Registry) ListCompiled() []string

ListCompiled returns all currently compiled function names.

func (*Registry) ListFunctionNames

func (r *Registry) ListFunctionNames() []string

ListFunctionNames returns all known function names (built-in and user-defined). Implements compiler.FunctionLister for "did you mean?" suggestions.

func (*Registry) Register

func (r *Registry) Register(fullName, source string) error

Register parses, compiles, and caches a function from its source. Uses a loader-backed resolver when available so that cross-namespace dependencies are correctly tracked even for functions not yet in cache.

func (*Registry) RegisterBuiltin

func (r *Registry) RegisterBuiltin(name string, bf *executor.BuiltinFunc)

RegisterBuiltin adds a Go-implemented function, visible to this registry only. A name already in the standard library is shadowed rather than replaced, so other registries in the process are unaffected.

Not safe against concurrent execution: call it during setup, before the registry is used. That was already the contract when this wrote straight into the builtin map.

func (*Registry) ResolveFunction

func (r *Registry) ResolveFunction(name string) (int, bool)

ResolveFunction checks if a function name is known (built-in or user-defined).

func (*Registry) SetLoader

func (r *Registry) SetLoader(loader FunctionLoader)

SetLoader sets an optional function loader that is called when GetCompiled misses the in-memory cache. The loader typically queries the database.

func (*Registry) Validate

func (r *Registry) Validate(source string) *ValidateResult

Validate parses and compiles source, returning validation errors.

func (*Registry) ValidateWithLookup

func (r *Registry) ValidateWithLookup(source string, lookup func(string) (int, bool)) *ValidateResult

ValidateWithLookup parses and compiles source, using an optional lookup function to resolve functions not found in the in-memory registry (e.g. from the database).

type ValidateResult

type ValidateResult struct {
	Valid  bool                    `json:"valid"`
	Errors []compiler.CompileError `json:"errors,omitempty"`
	AST    *ast.FnAST              `json:"-"`
}

ValidateResult contains the result of source validation.