Documentation
¶
Overview ¶
Package provenance answers, at the moment an asset is written, which calls produced it.
It reads the audit log rather than keeping a buffer of its own. The audit log is already the platform's record of every call: it survives a restart, it is shared by every replica, and it holds what a buffer never did — the call's identifier, its stated purpose, how long it took, and whether it succeeded. A per-process map could answer none of that, and answered nothing at all for a session whose calls were served by another replica (issue #1320).
A capture is scoped to the caller: the default window is the caller's own session, and an explicitly cited source is resolved only among the caller's own calls. Nothing here can put another person's query into an asset.
Index ¶
Constants ¶
const ( // MaxCalls bounds how many calls one capture records. A capture is a // snapshot stored on the asset row, not a copy of the session. MaxCalls = 100 )
Variables ¶
This section is empty.
Functions ¶
func APIRequestText ¶ added in v1.124.1
func APIRequestText(call *portal.ProvenanceCall, params map[string]any) string
APIRequestText renders what an api call asked for, from the addressing it resolved to and the arguments it carried. It is exported for an export's record of the call it made itself, which is built outside a capture (there is no audit row for it yet) and has to read the same way as the calls captured around it (#1423).
func KindFor ¶
KindFor returns the provenance call kind for a toolkit kind, or "" when calls to that toolkit are not asset sources.
func SourceToolkitKinds ¶
func SourceToolkitKinds() []string
SourceToolkitKinds returns the toolkit kinds whose calls can be an asset's source. The call-reference middleware stamps exactly these calls with their own id, so what an agent can cite and what the platform captures by default are one rule rather than two lists that drift.
Types ¶
type APIOperationResolver ¶ added in v1.124.1
type APIOperationResolver interface {
ResolveOperationRequest(
ctx context.Context, connection, operationID, spec string, pathParams map[string]string,
) (method, path string, ok bool)
}
APIOperationResolver rebuilds the request behind an api call that was addressed by operation id. The audit row holds the operation and the values the caller passed; the path template they were substituted into lives in the connection's API catalog, which only the toolkit serving that connection holds. The api gateway toolkit implements this (issue #1423).
type Capturer ¶
type Capturer struct {
// contains filtered or unexported fields
}
Capturer builds an asset write's provenance capture from the audit log.
func New ¶
func New(events EventReader, flush Flusher, opts ...Option) *Capturer
New builds a Capturer over the audit log. A nil reader yields a Capturer that records only what the caller states about itself, which is what a deployment with audit disabled gets. The flusher is optional: a synchronous audit writer has nothing to wait for. WithToolkits supplies the registry an api call's operation id is resolved against.
func (*Capturer) Capture ¶
func (c *Capturer) Capture(ctx context.Context, req portal.ProvenanceRequest) portal.ProvenanceCapture
Capture resolves the calls behind one asset write.
It never fails the write: an unreadable audit log yields a capture holding only what the caller stated about itself, because an asset that records less provenance is better than an asset that could not be saved.
type EventReader ¶
type EventReader interface {
Query(ctx context.Context, filter audit.QueryFilter) ([]audit.Event, error)
}
EventReader reads recorded calls back out of the audit log.
type Flusher ¶
Flusher waits for already-enqueued audit events to reach the store. The platform's audit writer is asynchronous, so without this the call that most obviously produced the asset — the one that just finished — is the one most likely to be missing when the capture reads.
type Option ¶ added in v1.124.1
type Option func(*Capturer)
Option configures a Capturer.
func WithToolkits ¶ added in v1.124.1
func WithToolkits(toolkits ToolkitLister) Option
WithToolkits gives the capturer the toolkit registry it resolves an api call's operation id against. Without it a call addressed by operation id records the operation and the values it passed, but not the path they resolve to.
type ToolkitLister ¶ added in v1.124.1
ToolkitLister is the live toolkit registry. A capture asks it for the resolver above at the moment it renders a call, rather than holding a toolkit resolved at assembly: connections are added, reloaded and removed while the platform runs, and a capture must read the catalog as it stands.
Source Files