runtime

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 28, 2026 License: Apache-2.0 Imports: 37 Imported by: 13

Documentation

Overview

Package runtime owns registered-component lookup and small method/path dispatch into the unified handler engine. HTTP adaptation, SQL execution, artifact compilation, and component metadata live in focused packages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ComponentLoader 

type ComponentLoader interface {
	LoadComponent(context.Context, spec.Key) (*RegisteredComponent, error)
}

ComponentLoader materializes one indexed component inside the currently pinned application generation.

type Observability 

type Observability struct {
	Recorder *observability.Recorder
	// contains filtered or unexported fields
}

Observability is application-owned. Native capture is always present; the optional adapter has no request-scoped lifecycle or global SDK registration.

func NewObservability 

func NewObservability(config ObservabilityConfig) (*Observability, error)

NewObservability creates one application-scoped capture/export owner.

func (*Observability) ExportStats 

func (o *Observability) ExportStats() otel.Stats

func (*Observability) Shutdown 

func (o *Observability) Shutdown(ctx context.Context) error

Shutdown continues cleanup after a caller deadline; there is one join/drain task per owner, never a task per generation or per retry.

func (*Observability) Stop 

func (o *Observability) Stop()

Stop ends export-lifetime admission. Existing native invocations retain their behavior, and accepted invocations finish capture before export is drained.

type ObservabilityConfig 

type ObservabilityConfig struct {
	Logger      xlogger.Logger
	ReadingData observability.ReadingData
	OTel        *otel.Config
}

type Option 

type Option func(*options) error

Option configures application-scoped runtime dependencies.

func WithApplicationProviders added in v1.1.0 

func WithApplicationProviders(providers ...locator.Provider) Option

WithApplicationProviders supplies immutable application-owned capabilities to every component. Providers remain subordinate to a component's explicit provider of the same kind and are never closed by the runtime.

func WithClientProviders added in v1.1.0 

func WithClientProviders(http xhttp.Provider, mcp xmcp.Provider) Option

WithClientProviders replaces the runtime's default outbound client providers with explicit implementations of the public xdatly contracts. The caller owns their lifecycle; the runtime neither closes nor substitutes them. A nil implementation leaves that capability unavailable, so a handler requiring it fails its binding instead of receiving a hidden default.

func WithExposedPackages 

func WithExposedPackages(include, exclude []string) Option

WithExposedPackages restricts public HTTP/MCP endpoints by package import path. All supplied components remain registered for internal dependency calls.

func WithManagedObservability 

func WithManagedObservability(owner *Observability) Option

WithManagedObservability borrows an application owner. It rejects stage-local policies rather than creating an exporter per reloadable generation.

func WithObservability 

func WithObservability(config ObservabilityConfig) Option

func WithRemoteMapper added in v1.1.0 

func WithRemoteMapper(value *remotecore.Mapper) Option

WithRemoteMapper supplies the shared mapping helper for remote handlers. Without it, the runtime creates one mapper for all its components.

func WithResourceFS 

func WithResourceFS(name string, source fs.FS) Option

WithResourceFS registers a package filesystem for SQL, StructQL, codecs, and other compiled resources in a newly created store. It cannot be combined with WithResources: register files in that explicit store before compilation instead. embed.FS implements fs.FS and is retained unchanged.

func WithResources 

func WithResources(resources *resource.Store) Option

WithResources installs the shared package resource store used by binding, transcription, artifact compilation, and runtime handlers.

type RegisteredComponent 

type RegisteredComponent = rregistry.RegisteredComponent

type Runtime 

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

func NewIndexedRuntime 

func NewIndexedRuntime(components []*spec.Component, preloaded []*RegisteredComponent, loader ComponentLoader, runtimeOptions ...Option) (*Runtime, error)

NewIndexedRuntime publishes route metadata immediately and resolves each executable registration through loader on first invocation.

func NewRuntime 

func NewRuntime(components []*RegisteredComponent, runtimeOptions ...Option) (*Runtime, error)

func (*Runtime) AllowedMethodsForPath 

func (r *Runtime) AllowedMethodsForPath(path string) []string

func (*Runtime) CacheRoute added in v1.1.0 

func (r *Runtime) CacheRoute(path string) (spec.RouteRef, bool)

CacheRoute preserves the requesting route's policy even when it delegates cache administration to a reader shared by multiple public routes.

func (*Runtime) CacheRoutes added in v1.1.0 

func (r *Runtime) CacheRoutes() []*spec.Route

func (*Runtime) CacheTarget added in v1.1.0 

func (r *Runtime) CacheTarget(path string) (dexec.ComponentTarget, bool)

CacheTarget resolves a server-owned GET component, including lazy-only views.

func (*Runtime) ClientProviders added in v1.1.0 

func (r *Runtime) ClientProviders() []locator.Provider

ClientProviders reports the runtime-level client providers applied to components that do not register their own.

func (*Runtime) ComponentTargetByMethodPath 

func (r *Runtime) ComponentTargetByMethodPath(method, path string) (dexec.ComponentTarget, bool)

ComponentTargetByMethodPath resolves the exact public component target used by protocol authorization without exposing the mutable route bundle.

func (*Runtime) Components 

func (r *Runtime) Components() []*spec.Component

Components returns detached canonical metadata without invoking handlers.

func (*Runtime) ExecuteRoute 

func (r *Runtime) ExecuteRoute(ctx context.Context, method, path string, scope dexec.ProviderScope) (any, error)

ExecuteRoute resolves a component and sends its prepared invocation through the single handler engine using providers assembled by the protocol adapter.

func (*Runtime) ExposesComponent 

func (r *Runtime) ExposesComponent(key spec.Key) bool

ExposesComponent is the protocol catalog boundary. Internal invocation uses the complete registry and does not consult endpoint exposure.

func (*Runtime) ExposesMCPComponent 

func (r *Runtime) ExposesMCPComponent(key spec.Key) bool

ExposesMCPComponent applies scope visibility to an MCP catalogue entry. An explicitly MCP-exposed internal route is intentionally absent from the public HTTP bundle, but must remain discoverable by the MCP compiler.

func (*Runtime) InvalidateCache added in v1.1.0 

func (r *Runtime) InvalidateCache(ctx context.Context, target dexec.ComponentTarget, view, scope string) ([]dexec.CacheInvalidation, error)

func (*Runtime) InvokeComponent 

func (r *Runtime) InvokeComponent(ctx context.Context, request dexec.ComponentRequest) (any, error)

InvokeComponent executes one exact component target without route lookup.

func (*Runtime) LoadComponent 

func (r *Runtime) LoadComponent(ctx context.Context, key spec.Key) (*RegisteredComponent, error)

LoadComponent exposes generation-scoped lazy resolution to protocol owners.

func (*Runtime) LoadComponents 

func (r *Runtime) LoadComponents(ctx context.Context, key spec.Key) ([]*RegisteredComponent, error)

func (*Runtime) MatchPathParams 

func (r *Runtime) MatchPathParams(method, path string) (map[string]string, bool)

MatchPathParams returns router-derived path values for a protocol adapter.

func (*Runtime) NewAsyncService 

func (r *Runtime) NewAsyncService(config jobs.Config) (*jobs.Service, error)

NewAsyncService wires durable jobs over canonical component execution. Transport publication and watcher lifetime are configured explicitly.

func (*Runtime) NewWarmup 

func (r *Runtime) NewWarmup(target dexec.ComponentTarget) (*Warmup, error)

func (*Runtime) Observability 

func (r *Runtime) Observability() *Observability

func (*Runtime) OutputByRoute 

func (r *Runtime) OutputByRoute(method, path string) (*registry.OutputContract, bool)

OutputByRoute uses the same route precedence as execution and authorization.

func (*Runtime) ReadResource 

func (r *Runtime) ReadResource(reference string) ([]byte, error)

ReadResource reads a default or namespace-qualified package resource.

func (*Runtime) ResolveComponentRoute 

func (r *Runtime) ResolveComponentRoute(method, path string) (spec.Key, *spec.Route, bool)

func (*Runtime) ResolveOutputByRoute 

func (r *Runtime) ResolveOutputByRoute(ctx context.Context, method, path string) (*registry.OutputContract, error)

ResolveOutputByRoute resolves output authority through this generation's loader. HTTP must not serialize a lazy component without its output contract.

func (*Runtime) ResourceFS 

func (r *Runtime) ResourceFS(name string) (fs.FS, bool)

ResourceFS returns the original package filesystem registered under name.

func (*Runtime) Resources 

func (r *Runtime) Resources() *resource.Store

Resources returns the shared package resource store used by this runtime.

func (*Runtime) RouteByMethodPath 

func (r *Runtime) RouteByMethodPath(method, path string) (*spec.Route, bool)

func (*Runtime) Routes 

func (r *Runtime) Routes() []*spec.Route

Routes returns detached public route metadata for protocol configuration.

func (*Runtime) Shutdown 

func (r *Runtime) Shutdown(ctx context.Context) error

Shutdown releases only a standalone runtime's owned services: the default outbound client registry it created and, when not managed, observability. Managed generations borrow their application owner and must not close it on retirement; explicitly configured client providers are likewise borrowed.

func (*Runtime) Warmup 

func (r *Runtime) Warmup(ctx context.Context, target dexec.ComponentTarget) (int, error)

Warmup binds each authored root cache case through the canonical component engine before invoking the reader's native SQLX warmup operation.

func (*Runtime) WarmupRoute 

func (r *Runtime) WarmupRoute(path string) (spec.RouteRef, bool)

WarmupRoute resolves the public/requested GET route template that owns a warmup path. The returned route can differ from WarmupTarget when a handler delegates warmup execution to a private reader.

func (*Runtime) WarmupRoutes 

func (r *Runtime) WarmupRoutes() []*spec.Route

WarmupRoutes returns detached GET route metadata for operational cache warmup. Unlike Routes, this includes internal reader routes because warmup is separately administrator-authorized and does not publish the component.

func (*Runtime) WarmupTarget 

func (r *Runtime) WarmupTarget(path string) (dexec.ComponentTarget, bool)

WarmupTarget resolves exact GET warmup eligibility without requiring public HTTP visibility. Warmup is separately administrator-authorized.

type Warmup 

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

Warmup is an exact, server-selected operation. Prepare validates the selected credentials through canonical binding/query policy before retaining providers. It retains no caller context or HTTP request.

func (*Warmup) CredentialHeaders 

func (w *Warmup) CredentialHeaders() ([]string, error)

CredentialHeaders selects only canonical, verified JWT inputs for transport retention. Other input values must come from server-authored warmup cases.

func (*Warmup) PlannedCases 

func (w *Warmup) PlannedCases() (int, error)

PlannedCases returns the number of server-expanded authored cases that Run will execute. It uses the exact input contract and MaxCases policy retained by this warmup operation; callers do not supply case values.

func (*Warmup) Prepare 

func (w *Warmup) Prepare(ctx context.Context, providers ...locator.Provider) (*Warmup, error)

Prepare validates every selected authored case, including verified codecs and query predicates. Only successful preparation produces a runnable copy.

func (*Warmup) Run 

func (w *Warmup) Run(ctx context.Context) (int, error)

Source Files

View all Source files

Directories

Path Synopsis
Package auth configures the original Datly JWT verification contract for explicitly declared input codecs.
 Package auth configures the original Datly JWT verification contract for explicitly declared input codecs.
provider
Package provider composes statically linked authentication implementations.
 Package provider composes statically linked authentication implementations.
Package differ adapts native godiff comparisons to the public handler contract.
 Package differ adapts native godiff comparisons to the public handler contract.
Package handler defines invocation-facing binder and handler abstractions plus capability keys shared by the unified engine.
 Package handler defines invocation-facing binder and handler abstractions plus capability keys shared by the unified engine.
codec/structql
Package structql implements the built-in StructQL parameter codec.
 Package structql implements the built-in StructQL parameter codec.
codec/transfer
Package transfer implements the built-in transform codec from the original Datly transfer tags using the reusable datly/transform planner.
 Package transfer implements the built-in transform codec from the original Datly transfer tags using the reusable datly/transform planner.
compiler
Package compiler converts canonical component parameters and Go input types into immutable Bindly plans and codec bindings.
 Package compiler converts canonical component parameters and Go input types into immutable Bindly plans and codec bindings.
custom
Package custom adapts typed user-defined Go handlers to the shared runtime handler contract.
 Package custom adapts typed user-defined Go handlers to the shared runtime handler contract.
engine
Package engine owns the common invocation path shared by runtime handler flavors: one Bindly scope, one input plan, and one lifecycle.
 Package engine owns the common invocation path shared by runtime handler flavors: one Bindly scope, one input plan, and one lifecycle.
loaddata
Package loaddata provides an ordinary component handler for typed AFS data.
 Package loaddata provides an ordinary component handler for typed AFS data.
mutation
Package mutation adapts generated mutation programs to the canonical handler engine.
 Package mutation adapts generated mutation programs to the canonical handler engine.
provider
Package provider adapts runtime-owned values into Bindly providers.
 Package provider adapts runtime-owned values into Bindly providers.
provider/cache
Package cache adapts explicitly named caches to native Bindly injection.
 Package cache adapts explicitly named caches to native Bindly injection.
provider/clients
Package clients is the composition-root wiring for outbound client capabilities.
 Package clients is the composition-root wiring for outbound client capabilities.
proxy
Package proxy provides an ordinary custom handler for explicitly configured HTTP forwarding.
 Package proxy provides an ordinary custom handler for explicitly configured HTTP forwarding.
reader
Package reader adapts a registered read execution to the unified handler engine without owning SQL plans, connections, caches, or mutable read state.
 Package reader adapts a registered read execution to the unified handler engine without owning SQL plans, connections, caches, or mutable read state.
remote
Package remote contains an ordinary remote component handler.
 Package remote contains an ordinary remote component handler.
velty
Package velty adapts cached typed Velty programs to the shared handler engine.
 Package velty adapts cached typed Velty programs to the shared handler engine.
writer
Package writer provides the metadata-driven built-in mutation handler.
 Package writer provides the metadata-driven built-in mutation handler.
Package jobs owns durable scheduling over the original Datly DATLY_JOBS table.
 Package jobs owns durable scheduling over the original Datly DATLY_JOBS table.
Package output compiles component output encoding independently of transport and delegates wire formats to their native codec owners.
 Package output compiles component output encoding independently of transport and delegates wire formats to their native codec owners.
predicate
velty
Package velty compiles Datly predicate metadata into Velty-backed runtime evaluators exposed through the exec.PredicateEvaluator port.
 Package velty compiles Datly predicate metadata into Velty-backed runtime evaluators exposed through the exec.PredicateEvaluator port.
Package registry owns the registered-component carrier consumed by runtime lookup.
 Package registry owns the registered-component carrier consumed by runtime lookup.
Package remote supplies request/response mapping and an opt-in cache for ordinary typed custom handlers that invoke an HTTP endpoint or MCP tool.
 Package remote supplies request/response mapping and an opt-in cache for ordinary typed custom handlers that invoke an HTTP endpoint or MCP tool.
cache
Package cache coordinates callers of a borrowed xdatly byte cache.
 Package cache coordinates callers of a borrowed xdatly byte cache.
Package route owns immutable route metadata and pure method/path matching.
 Package route owns immutable route metadata and pure method/path matching.

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.