Documentation
¶
Overview ¶
Package bootstrap owns package-authority component discovery and artifact composition. It scans Go packages for tagged xdatly component holders and resolves them into canonical component metadata without registration, HTTP exposure, or dynamic type loading.
Package bootstrap discovers package-authored component route holders. It is the primary package-authority entrypoint and remains separate from transcribe's authored DQL source processing.
Index ¶
- func CanonicalCodecName(name string, scope *typecatalog.ResolutionContext) (string, error)
- func CodecReferences(component *spec.Component, scope *typecatalog.ResolutionContext, ...) ([]string, error)
- func LinkedCodecType(name string) (reflect.Type, error)
- func LinkedHolder(holders []any, packagePath, holderName string) any
- func LinkedPackagePaths(holders []any) []string
- func LinkedResources(holders []any, packagePath string) map[string]*embed.FS
- func NormalizeCodecReferences(component *spec.Component, scope *typecatalog.ResolutionContext) ([]string, error)
- func ResolveQuerySelectorViews(component *spec.Component, strict bool) error
- type Artifact
- func (a *Artifact) NewViewProvider(config ViewRuntimeConfig) (locator.Provider, error)
- func (a *Artifact) ReaderCompilation() *CompiledReader
- func (a *Artifact) Registration(runtime registry.RegisteredComponent) (*registry.RegisteredComponent, error)
- func (a *Artifact) ReportSourceComponent() *spec.Component
- type ArtifactBuilder
- type ArtifactInput
- type CompiledReader
- type ContractResolver
- type EmbeddedResource
- type Embedder
- type JobStoreConfig
- type OutputColumn
- type PackageComponentSource
- type PackageDiscovery
- type ReaderRuntimeConfig
- type ReflectedPackages
- type RouteSource
- type ViewProjection
- type ViewRuntimeConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanonicalCodecName ¶ added in v1.1.0
func CanonicalCodecName(name string, scope *typecatalog.ResolutionContext) (string, error)
CanonicalCodecName resolves only explicit type references. Short factory names are deliberately not qualified using the component package or import basenames.
func CodecReferences ¶ added in v1.1.0
func CodecReferences(component *spec.Component, scope *typecatalog.ResolutionContext, contracts ...reflect.Type) ([]string, error)
CodecReferences includes linked contract tags, because child and summary row columns may not have been materialized into the spec graph yet.
func LinkedCodecType ¶ added in v1.1.0
LinkedCodecType follows one canonical reference without registering unrelated package types. Existing catalog authority is checked by its caller first.
func LinkedHolder ¶
LinkedHolder returns the compiled holder matching one source declaration.
func LinkedPackagePaths ¶
LinkedPackagePaths derives package scan roots from ordinary linked holders.
func LinkedResources ¶
LinkedResources returns embedded resources exposed by compiled holders in a selected package. It performs no registration and invokes no init side effect.
func NormalizeCodecReferences ¶ added in v1.1.0
func NormalizeCodecReferences(component *spec.Component, scope *typecatalog.ResolutionContext) ([]string, error)
NormalizeCodecReferences updates compiler-owned metadata and returns only explicitly qualified dependencies. It never constructs a codec.
func ResolveQuerySelectorViews ¶ added in v1.1.0
ResolveQuerySelectorViews binds each parameter's query selector to the canonical name of the view it targets in the component's spec view graph. A unique SQL alias, view key, namespace or the component name resolves to that view's canonical name; an alias matching several views, or a canonical name shared by several views, is always rejected.
With strict=false a target absent from the graph is left exactly as authored. Transcription uses this mode because nested views contributed by a linked Go output type do not exist until artifact bootstrap assembles them. With strict=true an unknown target is rejected; bootstrap uses this mode for handler-owned outputs, whose spec graph is final and never reaches the reader compiler's completed view index.
Shared selector metadata is never mutated: a resolved binding is written as a fresh QuerySelectorBinding on the parameter.
Types ¶
type Artifact ¶
type Artifact struct {
Documentation *documentation.Snapshot
Handler rhandler.TypedHandler
Component *spec.Component
Input *runtimeRegistry.InputContract
Output *runtimeRegistry.OutputContract
Reader *sqlreader.Plan
ViewDependencies []*sqlreader.ViewDependency
// contains filtered or unexported fields
}
Artifact is bootstrap's compiled output before runtime registration binds a concrete SQL reader execution to its connections and caches.
func BuildArtifact ¶
func BuildArtifact(input ArtifactInput) (*Artifact, error)
BuildArtifact composes the handler-input and reader-plan compilers. Registry receives the completed artifact and performs no compilation.
func (*Artifact) NewViewProvider ¶
func (a *Artifact) NewViewProvider(config ViewRuntimeConfig) (locator.Provider, error)
NewViewProvider attaches execution dependencies to the artifact's compiled independent reads without exposing their plans to composition callers.
func (*Artifact) ReaderCompilation ¶
func (a *Artifact) ReaderCompilation() *CompiledReader
ReaderCompilation returns the compiled reader products, if the component declares views.
func (*Artifact) Registration ¶
func (a *Artifact) Registration(runtime registry.RegisteredComponent) (*registry.RegisteredComponent, error)
Registration combines artifact-owned metadata/named handler selection with explicit application capabilities. It never resolves factories again.
func (*Artifact) ReportSourceComponent ¶
ReportSourceComponent returns detached projection metadata for report derivation. Relation tags are resolved by the reader compiler, not necessarily present in the authored spec. This snapshot does not replace execution plans.
type ArtifactBuilder ¶
type ArtifactBuilder struct {
// contains filtered or unexported fields
}
ArtifactBuilder owns one detached native registry snapshot for a complete compilation stage. Reuse it for every component in that stage; later export registrations cannot change its selected types or compiled factories.
func NewArtifactBuilder ¶
func NewArtifactBuilder(registry *x.Registry) (*ArtifactBuilder, error)
func (*ArtifactBuilder) Build ¶
func (b *ArtifactBuilder) Build(input ArtifactInput) (*Artifact, error)
func (*ArtifactBuilder) Catalog ¶
func (b *ArtifactBuilder) Catalog(source *typecatalog.Catalog) (*typecatalog.Catalog, error)
Catalog returns detached type authority including linked registry types from this same snapshot, for publication alongside the completed artifacts.
type ArtifactInput ¶
type ArtifactInput struct {
Const *constant.Values
Documentation xdocs.Source
Component *spec.Component
InputType reflect.Type
OutputType reflect.Type
Handler rhandler.TypedHandler
CodecFactory xcodec.Factory
Types *typecatalog.Catalog
// HandlerOwnedOutput preserves the output type/schema without importing its
// reader declarations into a component whose handler produces that output.
// Enabled reports resolve those declarations into separate metadata only.
HandlerOwnedOutput bool
DirectViewField string
// Resources is the same Bindly store supplied to runtime composition. SQL,
// reader, and codec compilers consume it only through the fs.FS contract.
Resources *resource.Store
}
ArtifactInput is resolved bootstrap input. Authored DQL parsing belongs to transcribe; this stage only compiles runtime plans from spec and Go types.
type CompiledReader ¶
type CompiledReader struct {
// contains filtered or unexported fields
}
CompiledReader exposes the immutable reader products needed to attach a concrete reader execution without exposing the containing bootstrap artifact.
func (*CompiledReader) NewExecution ¶
func (c *CompiledReader) NewExecution(config ReaderRuntimeConfig) (exec.Reader, error)
NewExecution attaches concrete runtime dependencies and returns only the unified reader capability.
type ContractResolver ¶
type ContractResolver struct {
Component *spec.Component
InputType *x.Type
OutputType *x.Type
Types *typecatalog.Resolver
}
ContractResolver projects canonical linked or synthetic contract types into one component. Existing component metadata retains authority.
type EmbeddedResource ¶
EmbeddedResource identifies the namespace of an embedded package filesystem. The filesystem itself is obtained through Embedder, matching the established Datly input/component resource contract.
type JobStoreConfig ¶
type JobStoreConfig struct {
SQL *dsql.SQLComponent
Connector string
Table string
Dataset string
// DisableTableCreation requires a pre-provisioned original job table.
// The default mirrors original job-service initialization.
DisableTableCreation bool
}
JobStoreConfig resolves job persistence through the same configured connector owner used by registered SQL components. Jobs retain only the selected native database/dialect pair, not application SQL execution or a connector registry.
type OutputColumn ¶
OutputColumn pairs canonical role/type metadata with proven selection and SQL names. A discovered Go name is never selector alias authority.
type PackageComponentSource ¶
type PackageComponentSource struct {
Routes []*RouteSource
InputType *x.Type
OutputType *x.Type
Handler func() (rhandler.TypedHandler, error)
// contains filtered or unexported fields
}
PackageComponentSource groups the ordered route holders that declare one package-authoritative component contract.
func GroupPackageComponentSources ¶
func GroupPackageComponentSources(routes []*RouteSource, types *typecatalog.Resolver) ([]*PackageComponentSource, error)
GroupPackageComponentSources resolves exact contract identities and groups route holders without relying on field names, file order heuristics, or dynamic registration.
func (*PackageComponentSource) ComponentName ¶
func (s *PackageComponentSource) ComponentName() string
ComponentName returns the canonical component name shared by this source's route holders.
func (*PackageComponentSource) ResolveDescriptors ¶
func (s *PackageComponentSource) ResolveDescriptors(types *typecatalog.Resolver) (*spec.Component, error)
ResolveDescriptors reconstructs one canonical component from all grouped route holders. Component-wide metadata must agree exactly across routes.
type PackageDiscovery ¶
type PackageDiscovery struct {
BaseDir string
ModuleDirs []string
Include, Exclude []string
Workspace *xmodule.Workspace
Holders []any
RequireLinked bool
}
PackageDiscovery selects package source roots independently of runtime exposure. ModuleDirs adds explicit local modules; imports are loaded separately as types.
func (PackageDiscovery) Discover ¶
func (d PackageDiscovery) Discover(ctx context.Context) ([]*RouteSource, error)
func (PackageDiscovery) DiscoverFiles ¶
func (d PackageDiscovery) DiscoverFiles(files []xmodule.File) ([]*RouteSource, error)
DiscoverFiles scans an already selected workspace file set. Bootstrap index builders use it to share one package walk with source fingerprinting.
type ReaderRuntimeConfig ¶
type ReaderRuntimeConfig struct {
// CacheIdentity identifies concrete connector configuration without credentials.
CacheIdentity string
// Aerospike is a caller-owned native client pool, shared across compiled readers.
Aerospike *aerospike.Pool
SQL *dsql.SQLComponent
ReadCaches map[string]cache.Cache
CacheSettings map[string]*spec.CacheSettings
RelationFetchConcurrency int
}
ReaderRuntimeConfig supplies concrete execution dependencies without exposing compiled reader metadata to composition callers.
type ReflectedPackages ¶
type ReflectedPackages struct {
Components []*RouteSource
Types *typecatalog.Catalog
Packages []string
}
ReflectedPackages is the runtime-only authority discovered from linked Go packages. It intentionally reads no Go source and performs no AST work.
func ReflectPackages ¶
func ReflectPackages(includes []string) (*ReflectedPackages, error)
ReflectPackages discovers every linked named type in the selected packages and identifies tagged xdatly.Component holders from their runtime shape. It is the instance-bootstrap counterpart to AST-based transcribe discovery.
type RouteSource ¶
type RouteSource struct {
// HolderType is the struct type declaring the component field.
HolderType string
// FieldName is the tagged holder field name — the component identity anchor.
FieldName string
// PackageName is the declaring file's package clause name.
PackageName string
// PackagePath is the module-qualified import path of the holder's package.
PackagePath string
// Dir is the absolute directory of the holder's package.
Dir string
// SourceFile is the absolute path of the declaring source file.
SourceFile string
// Tag is the complete typed component metadata from the holder field.
Tag dtag.Component
// InputType is the component input contract type name, rendered from the
// first Component generic argument.
InputType string
// OutputType is the component output contract type name, rendered from the
// second Component generic argument.
OutputType string
// Imports contains file-local aliases referenced by the input or output
// contract expressions. Unrelated holder-file imports are not retained.
Imports []spec.ImportSpec
LinkedInputType reflect.Type
LinkedOutputType reflect.Type
LinkedHandler func() (rhandler.TypedHandler, error)
// contains filtered or unexported fields
}
RouteSource describes one discovered Component[I, O] holder field and carries the package-authority metadata needed to resolve its canonical component.
func DiscoverComponentsFromPackages ¶
func DiscoverComponentsFromPackages(ctx context.Context, baseDir string, include []string, exclude []string) ([]*RouteSource, error)
DiscoverComponentsFromPackages is the default package-authority bootstrap discovery: it scans the Go packages under baseDir whose module-qualified import paths match the include patterns (and no exclude pattern) and returns one RouteSource per tagged Component[I, O] holder field.
Patterns are matched against import paths: a pattern ending in "..." matches its prefix recursively (e.g. "example.com/app/svc/..."), any other pattern must match the import path exactly (path.Match wildcards permitted). Include patterns are required — an empty include is an error rather than a silent repo-wide scan. _test.go files and vendor/testdata/hidden directories are skipped. A component-tagged field that is malformed, incomplete, or not a Component[I, O] holder is a hard error.
func (*RouteSource) Resolve ¶
Resolve creates canonical component metadata from one discovered package holder and its linked input contract.
func (*RouteSource) ValidateContractTypes ¶
func (s *RouteSource) ValidateContractTypes(inputType, outputType reflect.Type) error
ValidateContractTypes verifies that linked types are the exact contracts declared by this holder's Component[I,O] arguments.
type ViewProjection ¶
ViewProjection resolves canonical column metadata against reader SQL outputs. It compiles names only; row binding and invocation execution stay reader-owned.
func (ViewProjection) Columns ¶
func (p ViewProjection) Columns() ([]OutputColumn, error)
type ViewRuntimeConfig ¶
type ViewRuntimeConfig struct {
SQL *dsql.SQLComponent
}
ViewRuntimeConfig supplies the connection registry for independent reads.
Source Files
¶
- artifact.go
- artifact_builder.go
- codec.go
- codec_types.go
- component.go
- component_columns.go
- component_descriptor.go
- component_predicates.go
- component_sources.go
- component_types.go
- contract.go
- discover.go
- doc.go
- handler_linker.go
- holder.go
- jobs.go
- linked_packages.go
- predicate_types.go
- reader.go
- reflect_packages.go
- registration.go
- report_source.go
- selector_views.go
- view_projection.go
- view_provider.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cacheconfig creates native SQLX cache services from authored settings.
|
Package cacheconfig creates native SQLX cache services from authored settings. |
|
Package connector composes explicitly configured database/sql connections.
|
Package connector composes explicitly configured database/sql connections. |
|
Package index owns the immutable bootstrap map from protocol identities to authored component sources.
|
Package index owns the immutable bootstrap map from protocol identities to authored component sources. |
|
Package resources loads Go-declared package assets into the shared Bindly filesystem authority used by compilation and invocation.
|
Package resources loads Go-declared package assets into the shared Bindly filesystem authority used by compilation and invocation. |
|
Package routes compiles canonical URI activation and protocol exposure metadata shared by DQL transcription and Go-package bootstrap.
|
Package routes compiles canonical URI activation and protocol exposure metadata shared by DQL transcription and Go-package bootstrap. |