Documentation
¶
Overview ¶
Package composition is the neutral composition root shared by the CLI and the public façade (pkg/kanonarion). It owns the migration set that defines the store schema and constructs the read-only query use cases from a store root, so the public API can build the read-consumption surface without importing internal/cli — the CLI layer must stay private.
Index ¶
- Variables
- func BackendConfigSpecs() []config.ConfigSpec
- func BackendSections() []string
- func ConfiguredBackend(cfg configdomain.Config) (string, error)
- func LoadConfigFile(ctx context.Context, path string) (configdomain.Config, error)
- func Migrations() []sqlitestore.Migration
- func NewDriverFetch(st *storage.Storage, storeRoot string, cfg configdomain.Config, ...) (*fetchapp.FetchModuleUseCase, error)
- func NewOfflineStdlibAcquirer(store stdlibports.Store, goBinary string, clk fetchports.Clock, ...) *stdlibbridge.Bridge
- func NewStalenessResolver(ledger staleports.Ledger, cfg StalenessResolverConfig) (*driver.StalenessResolver, error)
- func NewStdlibAcquirer(store stdlibports.Store, blobs fetchports.BlobStore, clk fetchports.Clock, ...) *stdlibbridge.Bridge
- func NewTinyGoReleaseAcquirer(store tinygoports.Store, clk fetchports.Clock, logger *slog.Logger, ...) *tinygobridge.Bridge
- func OpenStorage(ctx context.Context, req storage.Request) (*storage.Storage, error)
- func StalenessResolverOver(upstream staleports.LatestResolver, ledger staleports.Ledger, ...) *staleapp.Resolver
- type Driver
- type Option
- type Queries
- type StalenessResolverConfig
Constants ¶
This section is empty.
Variables ¶
var ErrStoreSchemaNewer = storage.ErrStoreSchemaNewer
ErrStoreSchemaNewer is storage.ErrStoreSchemaNewer, kept under this name so every errors.Is caller and the CLI's exit-code mapping read it unchanged.
Functions ¶
func BackendConfigSpecs ¶
func BackendConfigSpecs() []config.ConfigSpec
BackendConfigSpecs is the config.yaml section of every backend in force: the registered ones, then the SQLite backend when it was not registered.
func BackendSections ¶
func BackendSections() []string
BackendSections names the config.yaml section of every backend in force, the only top-level keys outside the schema a config file may carry.
func ConfiguredBackend ¶
func ConfiguredBackend(cfg configdomain.Config) (string, error)
ConfiguredBackend names the backend cfg selects among those in force, without opening it.
func LoadConfigFile ¶ added in v0.16.1
LoadConfigFile reads the configuration file at path; an absent file is the built-in defaults.
func Migrations ¶
func Migrations() []sqlitestore.Migration
Migrations returns every migration the binary knows about, in apply order. The SQLite backend owns the list; it is re-exported here for the callers that read it beside a composition root.
func NewDriverFetch ¶ added in v0.16.1
func NewDriverFetch(st *storage.Storage, storeRoot string, cfg configdomain.Config, clk clock.System, stopwatch clock.Monotonic, logger *slog.Logger) (*fetchapp.FetchModuleUseCase, error)
NewDriverFetch is the driver's fetch pipeline over st: the module proxy $GOPROXY names, the checksum database cached under the configured directory, git cross-verification, the storage's signer and audit sink. The call-graph child an importing application serves fetches through it too.
func NewOfflineStdlibAcquirer ¶
func NewOfflineStdlibAcquirer(store stdlibports.Store, goBinary string, clk fetchports.Clock, audit stdlibports.AuditSink, logger *slog.Logger) *stdlibbridge.Bridge
NewOfflineStdlibAcquirer wires the offline standard-library chain-of-custody acquirer used in --from-modcache runs. It anchors to the local toolchain instead of go.dev/dl: the `go env GOROOT GOVERSION` inspector locates the toolchain, the local source reader exposes $GOROOT/src and $GOROOT/LICENSE, and the same licence detector and version-keyed fact cache the online path uses classify and persist the result. No network client is wired — the offline path performs no I/O beyond the local filesystem. goBinary may be empty (PATH "go").
func NewStalenessResolver ¶
func NewStalenessResolver(ledger staleports.Ledger, cfg StalenessResolverConfig) (*driver.StalenessResolver, error)
NewStalenessResolver builds the per-module staleness resolver over ledger (nil: every lookup live and unwritten). A GONOPROXY/GOPRIVATE path is never asked of the upstream, as in `latest`.
func NewStdlibAcquirer ¶
func NewStdlibAcquirer(store stdlibports.Store, blobs fetchports.BlobStore, clk fetchports.Clock, audit stdlibports.AuditSink, logger *slog.Logger) *stdlibbridge.Bridge
NewStdlibAcquirer wires the standard-library chain-of-custody acquirer over the given custody store and blob store: the go.dev/dl manifest+tarball client, the googlesource commit resolver, the licence detector, and the version-keyed fact cache. It is returned as a walk StdlibAcquirer via the bridge so the resolver depends only on the narrow port. Both composition roots (the driver here and the CLI container) share it so stdlib custody behaves identically — including the assurance log: audit is wired here rather than at each call site so neither root can be the quieter one.
func NewTinyGoReleaseAcquirer ¶
func NewTinyGoReleaseAcquirer(store tinygoports.Store, clk fetchports.Clock, logger *slog.Logger, offline bool) *tinygobridge.Bridge
NewTinyGoReleaseAcquirer wires the TinyGo release-archive measurement over the given store. Offline it serves held measurements and wires no network client.
func OpenStorage ¶
OpenStorage opens the backend req.Config selects. The SQLite backend is in force whether or not it was registered, so a consumer that registers nothing opens the store it always did.
func StalenessResolverOver ¶
func StalenessResolverOver(upstream staleports.LatestResolver, ledger staleports.Ledger, clk staleports.Clock, ttl time.Duration, fresh bool) *staleapp.Resolver
StalenessResolverOver is the per-path resolver every staleness answer comes from, the CLI's included: the private-path rule is wired here so no caller can build one without it.
Types ¶
type Driver ¶
type Driver struct {
// FetchServe resolves a single ModuleCoordinate, fetching and verifying on a
// miss, and returns a BlobHandle for serving.
FetchServe *fetchapp.ServeModuleUseCase
// LocalWalkExtract runs a project-rooted walk over a local working tree and
// its extraction stages, returning the records. Powers the local-walking
// gRPC client (source never leaves the machine).
LocalWalkExtract *driver.LocalWalkExtractUseCase
// CoordinateAnalysis runs, for a published module version, what
// `inspect <module>@<version>` runs: walk, extraction and vulnerability scan.
CoordinateAnalysis *driver.CoordinateAnalysisUseCase
// Rescan re-scans a stored walk against a fresh or pinned advisory
// snapshot, as `vuln-scan-rescan <walk-id>` does.
Rescan *driver.RescanUseCase
// CallGraphBuild builds and stores one module version's call graph in the
// call-graph child, as `callgraph <module>@<version>` does.
CallGraphBuild *driver.CallGraphBuildUseCase
// ValidateIngest is the verified-fact boundary: it validates imported records
// against the same invariants extracted ones satisfy before persisting them
// (Ingest), and re-verifies records fail-closed on read (ReadVerified). Powers
// the consume side of the airgap bundle.
ValidateIngest *fetchapp.ValidateAndIngestUseCase
// contains filtered or unexported fields
}
Driver is the write/serving surface. It holds the individually exported write use cases — the verified single-coordinate fetch/serve driver that powers a gating module proxy, the local walk→extract driver, the coordinate analysis and rescan drivers, and the validate-and-ingest boundary. The stage use cases they compose stay behind this root, so their orchestration shape is free to change. Further drivers join this struct as additional fields.
func NewDriver ¶
NewDriver opens the store under storeRoot through the backend its config.yaml selects (SQLite unless it names another), wires the fetch pipeline (proxy, VCS, sumdb, blob store, fact store) with the OSS no-op signer, and constructs the verified fetch/serve driver. It returns the populated Driver together with a cleanup function that closes the DB. The caller MUST invoke cleanup when finished.
The store root is created if absent. The proxy resolves $GOPROXY (or proxy.golang.org); the verification path is identical to the CLI fetch — this surface only re-shapes the result, never the integrity checks. Diagnostics are discarded: a serving consumer drives its own logging around the call.
func NewDriverFrom ¶
func NewDriverFrom(st *storage.Storage, storeRoot string, opts ...Option) (*Driver, func() error, error)
NewDriverFrom builds the driver over a storage value, which it owns from here on: the returned cleanup closes it, and a refusal closes it before returning. storeRoot is where the checksum-database cache and the call-graph child's configuration live, not where records are stored. No option applies yet: the set-aside reporter travels in the backend's Request.
func (*Driver) StalenessResolver ¶
func (d *Driver) StalenessResolver(cfg StalenessResolverConfig) (*driver.StalenessResolver, error)
StalenessResolver builds the per-module staleness resolver over the driver's ledger, with the store's staleness.ttl unless cfg names one.
type Option ¶
type Option func(*options)
Option configures a composition root.
func WithSetAsideReporter ¶
func WithSetAsideReporter(r func([]recordseal.SetAsideRow)) Option
WithSetAsideReporter states where the stores a root builds name each stored record they left out because this build cannot reproduce it. Without it each is logged at warn level.
type Queries ¶
type Queries struct {
Fetch *fetchapp.QueryFetchUseCase
Walks *walkapp.QueryWalksUseCase
License *licapp.QueryLicenseUseCase
Interface *ifaceapp.QueryInterfaceUseCase
CallGraph *cgapp.QueryCallGraphUseCase
Examples *exapp.QueryExamplesUseCase
Extraction *extractapp.QueryExtractionUseCase
Vuln *vulnapp.QueryVulnUseCase
ScanRuns *vulnapp.QueryScanRunsUseCase
SBOM *sbomapp.QuerySBOMUseCase
Directives *dirapp.QueryDirectivesUseCase
GoDebug *gdapp.QueryGoDebugUseCase
Vendor *venapp.QueryVendorUseCase
FIPS *fipsapp.QueryFIPSUseCase
}
Queries is the read-only consumption surface: every Query* use case the public façade exposes. Write/extraction use cases are deliberately absent — the pipeline orchestration shape stays free to change and is driven through the CLI composition root, not this read surface.
func NewQueries ¶
NewQueries opens the store under storeRoot through the backend its config.yaml selects (SQLite unless it names another) and builds every Query* use case over it. It returns the populated Queries together with a cleanup function that closes the DB.
A store root that does not exist is refused, not created. Every use case here answers from records some other run wrote, so a root this call brought into existence could only ever answer "nothing recorded" — a true sentence about a store one millisecond old and a false one about the store the caller meant. Only read stores are wired — no proxy, VCS, extractor, or signer — so the read surface stays independent of the pipeline-construction machinery.
func NewQueriesFrom ¶
NewQueriesFrom builds every Query* use case over a storage value. It takes ownership of st: the returned cleanup closes it, and a refusal closes it before returning. Writable is not consulted, so a store the driver refuses can still be read to find out why.
type StalenessResolverConfig ¶
type StalenessResolverConfig struct {
// Upstream answers @latest per path. Nil asks the module proxy $GOPROXY
// names, behind latest's re-ask schedule.
Upstream staleports.LatestResolver
// Clock stamps lookups and measures the TTL. Nil is the system clock.
Clock fetchports.Clock
// TTL is how long a ledger row is served. Zero is the store's
// staleness.ttl, or the built-in default for a supplied ledger.
TTL time.Duration
}
StalenessResolverConfig is what a caller may supply to a staleness resolver. A zero field takes what `latest` uses.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cgchild runs the call-graph child: the process extraction and reachability start, from the running executable, to analyse one module's call graph and write it to the store.
|
Package cgchild runs the call-graph child: the process extraction and reachability start, from the running executable, to analyse one module's call graph and write it to the store. |
|
Package storage is the single value through which the composition roots reach everything the pipeline persists: every record store, the blob store, the audit sink, the attestation store and the signer.
|
Package storage is the single value through which the composition roots reach everything the pipeline persists: every record store, the blob store, the audit sink, the attestation store and the signer. |
|
sqlite
Package sqlite is the SQLite and local-filesystem storage backend: mirror.db for every record store, a content-addressed blob directory, and audit.jsonl, all under one store root.
|
Package sqlite is the SQLite and local-filesystem storage backend: mirror.db for every record store, a content-addressed blob directory, and audit.jsonl, all under one store root. |