Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# ADR-0050: A component call is a transaction over a snapshot, within the command's lifetime

- **Date:** 2026-10-25
- **Status:** Accepted

## Context

The same SDK module behaved differently depending on how it ran. A managed
plugin's request crosses the wire as a copy, and its result is applied only
when the RPC succeeds. An embedded matcher or analyzer received the host's own
graph, registry and target pointers, so one that changed them and then failed
-- the reachability analyzers enrich `req.Registry` in place -- left the
pipeline half-enriched. Lifetimes diverged too: embedded constructors ran
under `context.Background()` with no way to release what they acquired, and a
managed component was torn down only as a side effect of killing its process.

## Decision

- Every `Ready`, `Applicable` and `Match`/`Analyze` call receives its own
`MatchRequest.Clone` / `AnalyzeRequest.Clone`. No component holds the host's
state.
- Only a successful action is committed: a returned `Registry` wins, otherwise
`PackageUpdates` merge through `model.ApplyPackageUpdates`. A failed call, or
one that returns after the command was cancelled, commits nothing. Rollback
is per call; earlier successes stand.
- Changes a component makes to the graph or target are never committed, as
they never were for a managed plugin.
- An embedded component is constructed under the command's context and gets a
`plugin.ComponentScope`. `Registry.Close` ends every scope, newest first, in
the command's cleanup chain ahead of temp-dir cleanup. A managed component's
scope closes when go-plugin's `Kill` shuts the plugin down gracefully, and the
pool shuts plugins down concurrently, so the command waits one grace period.

## Rejected

Letting embedded components keep mutating the request, documented as a
feature, was rejected: it makes rollback depend on how a plugin is packaged.
Instead the cost of one snapshot per call is accepted, measured at under 1 ms
for 500 packages.

## Consequences

- A component that relied on mutating the graph or target to communicate must
return a registry or deltas instead.
- Snapshots cost time and memory per call. That is the price of parity, and
it is the first place to look if a very large scan slows.
- A component's cleanups run even when its constructor fails after
registering them.

Enforced by: `TestEngineMatchCommitsOnlySuccessfulCalls`,
`TestEngineAnalyzeCommitsOnlySuccessfulCalls` (embedded and simulated-wire
parity), `TestEngineMatchDiscardsWorkFinishedAfterCancellation`,
`TestRegistryComponentLifetimeIsTheCommands`, and bomly-sdk's conformance
probe of a managed cleanup on shutdown.
1 change: 1 addition & 0 deletions dev-docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ The rule itself is [ADR-0034](0034-decisions-are-recorded-as-individual-adrs.md)
| ADR-0047 | 2026-10-03 | [Release assurance is a catalog plus a per-check result contract](0047-release-assurance-is-a-catalog-and-a-result-contract.md) |
| ADR-0048 | 2026-10-19 | [OSV stays opt-in; Grype keeps its database fresh](0048-osv-stays-opt-in-and-grype-keeps-its-database-fresh.md) |
| ADR-0049 | 2026-10-19 | [A pinned origin is one VCS locator in every export](0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md) |
| ADR-0050 | 2026-10-25 | [A component call is a transaction over a snapshot, within the command's lifetime](0050-a-component-call-is-a-transaction-over-a-snapshot.md) |

## Retired

Expand Down
4 changes: 4 additions & 0 deletions docs/PLUGINS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@ Installed plugins are disabled until you enable them. Enabling a plugin is the t

A plugin is a Go binary built on Bomly's public SDK. Bomly starts each enabled plugin as a separate process and talks to it over a versioned protocol. During one command, Bomly keeps one process per enabled plugin, starts it on first use, and stops it when the command ends. If the process dies, Bomly restarts it once; a second death disables the plugin for the rest of the command with a warning. Plugin processes never outlive the Bomly command.

When the command ends, Bomly closes each plugin's connection and gives it a short grace period before stopping the process, so cleanups the plugin registered with `host.OnCleanup` run, all plugins at once. A component compiled into Bomly gets the same lifetime: it is built under the command's context and its cleanups run when the command ends.

Each matcher and analyzer call receives a copy of the dependency graph and package registry, and Bomly keeps a call's result only when it succeeds. A plugin that fails or is cancelled partway leaves the scan exactly as the previous component left it. Changes a plugin makes to the graph or the target dependency are never kept: return enrichment as a registry or as package updates.

Bomly owns installing plugin packages, validating their manifest, checking recorded checksums, storing plugins under `~/.bomly/plugins`, enabling and disabling them, and loading enabled plugins at the start of a command. Plugins have no install hooks or post-install scripts, and Bomly never runs a plugin it finds in a repository checkout.

## Install sources
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ require (
github.com/bomly-dev/bomly-plugin-pyreach-analyzer v0.4.0
github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0
github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0
github.com/bomly-dev/bomly-sdk v0.14.10
github.com/bomly-dev/bomly-sdk v0.16.0
github.com/charmbracelet/bubbles v1.0.0
github.com/charmbracelet/bubbletea v1.3.10
github.com/charmbracelet/lipgloss v1.1.0
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -263,8 +263,8 @@ github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0 h1:CB4M5/N7vR2OlMuxKs
github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0/go.mod h1:g62nlreSY249tHBl8uoECIan2FW8r+S1xNFZkbdqSBw=
github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0 h1:4U/YOzWujQx1LK+VpPhPEpt2ikwiBciDzaE0V5iNN6M=
github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0/go.mod h1:B17C01ssOWdoUGa3geCaouPSge+23QiD2ssFLao0g94=
github.com/bomly-dev/bomly-sdk v0.14.10 h1:ZFb4pXYofXeB6Zd8Rh36vj64X31u9MuD7TB5LwU11hw=
github.com/bomly-dev/bomly-sdk v0.14.10/go.mod h1:XzJZ6B9fNewalouISppzR52Fev4XGIDPElO9OjJTU5M=
github.com/bomly-dev/bomly-sdk v0.16.0 h1:czCVZRiZ2TDGMRQwy1a6jxbS+/3ypoaMYcP0/i7Boo0=
github.com/bomly-dev/bomly-sdk v0.16.0/go.mod h1:XzJZ6B9fNewalouISppzR52Fev4XGIDPElO9OjJTU5M=
github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M=
github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0=
github.com/bufbuild/protocompile v0.14.1 h1:iA73zAf/fyljNjQKwYzUHD6AD4R8KMasmwa/FBatYVw=
Expand Down
22 changes: 21 additions & 1 deletion internal/cli/opts/options.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package opts

import (
"context"
"errors"
"fmt"
"io"
"os"
Expand Down Expand Up @@ -257,7 +258,11 @@ func (o *Options) PrepareForExecutionTarget(ctx context.Context, logger *zap.Log
registryConfigs := RegistryConfigsFromResolved(resolved)
registryConfigs.HTTPClientProvider = httpProvider
scanRegistry := engine.NewRegistry(registryConfigs, *logger)
scanRegistry.Build()
scanRegistry.BuildContext(ctx)
// The registry's embedded components live as long as the command: their
// cleanups join the command cleanup chain ahead of the temp-dir cleanup
// they may still depend on, on every path out of here.
cleanup = joinCleanups(scanRegistry.Close, cleanup)

if err := o.registerInstalledPluginDescriptors(ctx, scanRegistry); err != nil {
if cleanup != nil {
Expand Down Expand Up @@ -578,6 +583,21 @@ func (o *Options) Writer(stdout io.Writer) (io.Writer, func() error, error) {
}

// Close performs any necessary cleanup for the command options.
// joinCleanups returns a cleanup that runs first, then rest, and joins
// their errors: one failing never skips the other. Either may be nil.
func joinCleanups(first, rest func() error) func() error {
return func() error {
var errs []error
if first != nil {
errs = append(errs, first())
}
if rest != nil {
errs = append(errs, rest())
}
return errors.Join(errs...)
}
}

func (o *Options) Close() error {
if o.cleanup == nil {
return nil
Expand Down
23 changes: 23 additions & 0 deletions internal/cli/opts/options_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package opts
import (
"bytes"
"context"
"errors"
"os"
"path/filepath"
"slices"
Expand Down Expand Up @@ -1089,3 +1090,25 @@ func TestDetachPluginPoolIsolatesClones(t *testing.T) {
t.Fatal("DetachPluginPool on the clone must not clear the base pool")
}
}

// TestJoinCleanupsRunsBothInOrder: the registry's component cleanups run
// before the temp-dir cleanup they may depend on, and one failing never
// skips the other.
func TestJoinCleanupsRunsBothInOrder(t *testing.T) {
var order []string
errFirst, errRest := errors.New("component cleanup"), errors.New("temp dir")
joined := joinCleanups(
func() error { order = append(order, "components"); return errFirst },
func() error { order = append(order, "temp"); return errRest },
)
err := joined()
if !slices.Equal(order, []string{"components", "temp"}) {
t.Errorf("order = %v", order)
}
if !errors.Is(err, errFirst) || !errors.Is(err, errRest) {
t.Errorf("joined error %v lost a failure", err)
}
if err := joinCleanups(nil, nil)(); err != nil {
t.Errorf("two nil cleanups = %v", err)
}
}
3 changes: 2 additions & 1 deletion internal/composition/composition_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ import (
// fakeHost is a minimal plugin.HostContext for construction tests.
type fakeHost struct{}

func (fakeHost) Logger() *zap.Logger { return zap.NewNop() }
func (fakeHost) Logger() *zap.Logger { return zap.NewNop() }
func (fakeHost) OnCleanup(func() error) {}
func (fakeHost) HTTPClient() *httpkit.ClientProvider {
provider, _ := httpkit.NewClientProvider(httpkit.ClientConfig{})
return provider
Expand Down
43 changes: 34 additions & 9 deletions internal/engine/engine.go
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@ func cloneAuditRequest(req plugin.AuditRequest) plugin.AuditRequest {
}

// Analyze runs registered analyzers against the graph and returns the
// reachability-annotated graph. Unlike Audit, Analyze does NOT error when
// reachability-annotated graph. Each call is a transaction over its own
// AnalyzeRequest.Clone, committed only on success, exactly as Match's are. Unlike Audit, Analyze does NOT error when
// zero analyzers apply — reachability is opt-in and a request with no
// applicable analyzers is a normal outcome.
func (e *Engine) Analyze(ctx context.Context, req plugin.AnalyzeRequest) (plugin.AnalyzeResult, error) {
Expand All @@ -114,11 +115,11 @@ func (e *Engine) Analyze(ctx context.Context, req plugin.AnalyzeRequest) (plugin
descriptor := analyzer.Descriptor()
name := descriptor.Name
label := descriptor.Label()
if err := analyzer.Ready(ctx, req); err != nil {
if err := analyzer.Ready(ctx, req.Clone()); err != nil {
errs = append(errs, fmt.Errorf("analyzer %s: not ready: %w", name, err))
continue
}
applicable, err := analyzer.Applicable(ctx, req)
applicable, err := analyzer.Applicable(ctx, req.Clone())
if err != nil {
errs = append(errs, fmt.Errorf("analyzer %s: applicability check failed: %w", name, err))
continue
Expand All @@ -127,8 +128,8 @@ func (e *Engine) Analyze(ctx context.Context, req plugin.AnalyzeRequest) (plugin
continue
}

result, err := analyzer.Analyze(ctx, req)
if err != nil {
result, err := analyzer.Analyze(ctx, req.Clone())
if err = committable(ctx, err); err != nil {
errs = append(errs, fmt.Errorf("analyzer %s: %w", name, err))
continue
}
Expand All @@ -155,6 +156,16 @@ func (e *Engine) Analyze(ctx context.Context, req plugin.AnalyzeRequest) (plugin
}

// Match runs registered matchers against the graph and returns the enriched graph.
//
// Each call is a transaction over a snapshot (ADR-0050): every Ready,
// Applicable and Match call receives its own MatchRequest.Clone, so a matcher
// never holds the host's graph, registry or target. Only a successful Match
// is committed -- its Registry if it returned one, otherwise its
// PackageUpdates merged into the canonical registry -- and a failed or
// cancelled one leaves the canonical state exactly as the previous matcher
// left it. Changes a matcher makes to the graph or target are never
// committed, as they never were for a managed plugin, whose request crosses
// the wire as a copy.
func (e *Engine) Match(ctx context.Context, req plugin.MatchRequest) (MatchResult, error) {
originalGraphSize := 0
if req.Graph != nil {
Expand Down Expand Up @@ -189,11 +200,11 @@ func (e *Engine) Match(ctx context.Context, req plugin.MatchRequest) (MatchResul
for _, matcher := range matcherList {
descriptor := matcher.Descriptor()
name := descriptor.Name
if err := matcher.Ready(ctx, req); err != nil {
if err := matcher.Ready(ctx, req.Clone()); err != nil {
errs = append(errs, fmt.Errorf("matcher %s: not ready: %w", name, err))
continue
}
applicable, err := matcher.Applicable(ctx, req)
applicable, err := matcher.Applicable(ctx, req.Clone())
if err != nil {
errs = append(errs, fmt.Errorf("matcher %s: applicability check failed: %w", name, err))
continue
Expand All @@ -203,8 +214,8 @@ func (e *Engine) Match(ctx context.Context, req plugin.MatchRequest) (MatchResul
continue
}

result, err := matcher.Match(ctx, req)
if err != nil {
result, err := matcher.Match(ctx, req.Clone())
if err = committable(ctx, err); err != nil {
errs = append(errs, fmt.Errorf("matcher %s: %w", name, err))
continue
}
Expand All @@ -230,6 +241,20 @@ func (e *Engine) Match(ctx context.Context, req plugin.MatchRequest) (MatchResul
return aggregated, nil
}

// committable reports whether a component call's result may be committed:
// not when the call failed, and not when the command was cancelled while it
// ran, even if the component returned without an error -- a component that
// ignored its context may have returned partial work.
func committable(ctx context.Context, err error) error {
if err != nil {
return err
}
if ctxErr := ctx.Err(); ctxErr != nil {
return fmt.Errorf("cancelled: %w", ctxErr)
}
return nil
}

func finalizeMatchResult(result *MatchResult) {
if result == nil || result.Registry == nil {
return
Expand Down
Loading
Loading