source

package
v0.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 36 Imported by: 0

Documentation

Overview

Package source defines SDK contracts and shared helpers for Flux sources. Per-kind fetchers acquire immutable artifacts through pkg/source/cache.

Adding a new source kind:

  1. Implement source.Fetcher for the new kind in a new file (or subpackage) under pkg/source.
  2. Register the fetcher with the orchestrator at construction time.

The source controller (pkg/controllers/source) does not know about individual kinds — it dispatches via the Fetchers map keyed by id.Kind, so adding a new kind is one registration call.

Index

Constants

View Source
const (
	// OCICopiedLayerFilename is the unextracted OCI layer in an artifact FS.
	OCICopiedLayerFilename = "layer.tar.gz"
	// HelmChartArchiveFilename is the HTTP chart archive in an artifact FS.
	HelmChartArchiveFilename = "chart.tgz"
)

Artifact filenames are shared by source fetchers and chart loaders.

View Source
const (
	// TransportCert selects required TLS material from certSecretRef.
	TransportCert transportUse = iota
	// TransportSecret selects TLS material from Git's auth secretRef.
	TransportSecret
	// TransportProxy selects routing material from proxySecretRef.
	TransportProxy
)

Variables

This section is empty.

Functions

func BasicAuthFromSecret added in v0.4.0

func BasicAuthFromSecret(
	sec *manifest.Secret,
	owner manifest.DiagnosticIdentity,
	secretRef string,
) (string, string, error)

BasicAuthFromSecret rejects malformed credentials and reports absent credentials through MissingSecretError.

func MissingSecretErr

func MissingSecretErr(owner manifest.DiagnosticIdentity, secretRef, reason string) error

MissingSecretErr captures unavailable material with raw and display identities.

func NewHTTPTransport

func NewHTTPTransport(material TransportMaterial) *http.Transport

NewHTTPTransport builds the concrete guarded kernel required by HTTP libraries.

func OperationView added in v0.7.3

func OperationView(ctx context.Context, input fs.FS) (fs.FS, string, error)

OperationView refreshes admitted mutable observations and retains cache acquisition identity.

Types

type Fetcher

type Fetcher interface {
	Fetch(
		ctx context.Context,
		obj manifest.BaseManifest,
		reads *store.ReadSet,
		policy *sourcecache.Policy,
	) (PreparedFetch, error)
}

Fetcher resolves a single source CR into an on-disk artifact. The source controller stores Fetchers in a map keyed by Kind and dispatches via this untyped interface. Concrete implementations satisfy it through Wrap[T] — see TypedFetcher.

func Wrap

func Wrap[T manifest.BaseManifest](kindLabel string, f TypedFetcher[T]) Fetcher

Wrap converts a TypedFetcher into the untyped Fetcher interface used by the source-controller dispatcher map. The single type-assertion site is here — a mismatched payload returns ErrInput rather than panicking. Embeds the Kind label so the error message names the responsible fetcher.

type HTTPInputs added in v0.7.3

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

HTTPInputs owns one run's shared HTTP acquisitions and borrows its dependencies. It MUST NOT be copied after use; Close joins workers before backing is released.

func NewHTTPInputs added in v0.7.3

func NewHTTPInputs(owner *cache.Cache, network *Network, tasks *task.Service) HTTPInputs

NewHTTPInputs borrows the nonnil storage owner, Network and task service.

func (*HTTPInputs) Acquire added in v0.7.3

func (h *HTTPInputs) Acquire(ctx context.Context, requestValue *HTTPRequest) (fs.FS, error)

Acquire returns an immutable filesystem containing content and shares complete acquisitions with equal policies. Successes and definitive client errors remain available for this owner's lifetime. Shared work outlives individual waiters. Only Close guarantees worker cleanup; an Acquire return does not join the owner. heldSlot is the borrowed service when the caller holds its slot, or nil.

func (*HTTPInputs) Close added in v0.7.3

func (h *HTTPInputs) Close()

Close freezes remote admission, cancels shared work and joins its complete acquisition and cleanup. It is terminal, idempotent and safe for concurrent callers. Callers MUST separately join renders and finish acquired readers before releasing backing storage. Close does not aggregate fetch errors.

type HTTPRequest added in v0.7.3

type HTTPRequest struct {
	URL      string
	Retry    cache.RetryConfig
	HeldSlot *task.Service
	Work     manifest.WorkScope
}

HTTPRequest carries one remote input and its caller's execution facts.

type HTTPTransportConfig added in v0.7.3

type HTTPTransportConfig struct {
	Material           TransportMaterial
	Insecure           bool
	Credentials        any
	DisableCompression bool
}

HTTPTransportConfig specifies immutable effective transport material. Zero Material captures environment policy at selection time. Credentials separate source security boundaries and remain client-bound. Compatible OCI clients share upstream auth tokens through the selected transport.

type MissingSecretError added in v0.3.4

type MissingSecretError struct {
	// Owner is the source requiring unavailable material.
	Owner manifest.NamedResource
	// Subject is captured before unavailable material can be reported.
	Subject manifest.DiagnosticIdentity
	// Secret identifies the unavailable Secret; zero denotes source-only material.
	Secret manifest.NamedResource
	// Detail is the human reason ("not found", "missing username/password").
	Detail string
	// AnonymousDenied records a typed registry denial after no credential was selected.
	AnonymousDenied bool
	// Cause preserves the acquisition owner's typed failure.
	Cause error
	// RetryAmbient attempts the acquisition owner's eligible ambient credentials.
	RetryAmbient func(context.Context) (PreparedFetch, error)
}

MissingSecretError retains unavailable source material and an optional Secret identity. Acquisition owners supply the ambient continuation.

func (*MissingSecretError) Error added in v0.3.4

func (e *MissingSecretError) Error() string

Error identifies unavailable material.

func (*MissingSecretError) ProducerBacked added in v0.7.3

func (e *MissingSecretError) ProducerBacked(reads *store.ReadSet) bool

ProducerBacked reports whether captured declarations can supply the missing Secret.

func (*MissingSecretError) RetryMachine added in v0.7.3

func (e *MissingSecretError) RetryMachine(ctx context.Context, reads *store.ReadSet) (PreparedFetch, error)

RetryMachine runs the acquisition owner's continuation when no producer can supply material.

func (*MissingSecretError) Unwrap added in v0.3.4

func (e *MissingSecretError) Unwrap() error

Unwrap keeps errors.Is(err, manifest.ErrMissingSecret) working.

type Network added in v0.7.3

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

Network owns compatible HTTP transports and first connection timeouts for one invocation. Its zero value is usable; independent invocations MUST NOT share it through a cache owner.

func (*Network) AWSCredentials added in v0.7.3

func (n *Network) AWSCredentials(ctx context.Context, provider aws.Provider) (aws.Value, error)

AWSCredentials retrieves machine credentials through the run's transport. IAM discovery outlives caller cancellation and MUST be joined by Close.

func (*Network) Close added in v0.7.3

func (n *Network) Close()

Close cancels shared discovery and releases idle HTTP connections after all users have joined. Borrowers MUST leave cleanup to the invocation owner.

func (*Network) HTTPTransport added in v0.7.3

func (n *Network) HTTPTransport(cfg HTTPTransportConfig) (http.RoundTripper, error)

HTTPTransport selects a fully configured, guarded transport for this invocation. The Network MUST be non-nil and outlive every borrower.

func (*Network) RegistryCredentials added in v0.7.3

func (n *Network) RegistryCredentials(ctx context.Context, configPath, hostname string) (*auth.Credential, error)

RegistryCredentials resolves a host through the run's read-only native stores. Configuration MUST be identical for every borrower of the Network.

func (*Network) RoundTrip added in v0.7.3

func (n *Network) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip sends a request through the lazily selected default transport.

type PreparedFetch added in v0.7.3

type PreparedFetch struct {
	Inputs           []manifest.DependencyRef
	LocalUnavailable *MissingSecretError
	Fetch            func(context.Context, *store.SourceArtifact) (*store.SourceArtifact, error)
	// Close MUST run after consumption or discard, including preparation failures.
	Close func()
}

PreparedFetch settles prerequisites and credentials before content authority is resolved.

func AcquireMachine added in v0.7.3

func AcquireMachine(
	ctx context.Context,
	policyValue *cache.Policy,
	prepare func(context.Context) error,
	acquire func(context.Context, *cache.Policy, *store.SourceArtifact) (*store.SourceArtifact, error),
) (PreparedFetch, error)

AcquireMachine bounds preparation independently of deferred content acquisition.

type SecretGetter

type SecretGetter func(namespace, name string) *manifest.Secret

SecretGetter resolves a Secret CR by namespace + name. Fetchers that read authentication, TLS, or proxy material from a Flux spec.*SecretRef accept one of these so they don't need a back-reference to the Store. Today: GitRepository (auth + TLS), OCIRepository (auth + TLS), Bucket (auth + TLS). The orchestrator wires it to the core Secret store lookup at construction time.

func SecretLookup added in v0.7.3

func SecretLookup(reads *store.ReadSet) SecretGetter

SecretLookup binds credential reads to one execution's captured inputs.

type TransportInput added in v0.7.3

type TransportInput struct {
	Reference *manifest.LocalObjectReference
	Use       transportUse
	// OptionalTLS permits Git's absent or auth-only secretRef to supply no TLS.
	OptionalTLS bool
	// CAFallback enables Git's caFile key, with ca.crt taking precedence.
	CAFallback bool
}

TransportInput selects an ordered TLS or proxy Secret reference.

type TransportMaterial added in v0.7.3

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

TransportMaterial captures immutable TLS, certificate identity and proxy policy.

func ResolveTransport added in v0.7.3

func ResolveTransport(
	secrets SecretGetter,
	owner manifest.DiagnosticIdentity,
	inputs []TransportInput,
) (TransportMaterial, error)

ResolveTransport resolves ordered inputs using one operation's Secret snapshot.

func (TransportMaterial) Certificate added in v0.7.3

func (m TransportMaterial) Certificate() [3]string

Certificate returns the validated client certificate, key and CA bytes.

func (TransportMaterial) Identity added in v0.7.3

func (m TransportMaterial) Identity(credentials any) any

Identity combines protocol credentials with full certificate and proxy acquisition material. Returned Secret maps remain read-only.

func (TransportMaterial) ProxyComponents added in v0.7.3

func (m TransportMaterial) ProxyComponents() [3]string

ProxyComponents returns explicit proxy address, username and password for Git.

func (TransportMaterial) ProxyURL added in v0.7.3

func (m TransportMaterial) ProxyURL(target *url.URL) (*url.URL, error)

ProxyURL selects the captured route for an actual request or redirect URL.

type TypedFetcher

type TypedFetcher[T manifest.BaseManifest] interface {
	Fetch(ctx context.Context, obj T, reads *store.ReadSet, policy *sourcecache.Policy) (PreparedFetch, error)
}

TypedFetcher acquires artifacts of one manifest type with explicit freshness and retries.

Directories

Path Synopsis
Package bucket implements the source.Fetcher for KindBucket (S3-compatible object storage via minio-go).
Package bucket implements the source.Fetcher for KindBucket (S3-compatible object storage via minio-go).
Package cache acquires verified source bytes into immutable memory or OCI-backed filesystems.
Package cache acquires verified source bytes into immutable memory or OCI-backed filesystems.
Package external reports standalone ExternalArtifacts without accepted content.
Package external reports standalone ExternalArtifacts without accepted content.
git
Package git implements the source.Fetcher for KindGitRepository.
Package git implements the source.Fetcher for KindGitRepository.
internal/gittransport
Package gittransport installs go-git's bounded HTTPS client at initialization.
Package gittransport installs go-git's bounded HTTPS client at initialization.
Package gitrepo selects and opens local Git working trees through go-git.
Package gitrepo selects and opens local Git working trees through go-git.
Package gittree admits direct inputs and lazy Git tree views.
Package gittree admits direct inputs and lazy Git tree views.
Package helmchart resolves HelmRepository charts through the shared acquisition cache.
Package helmchart resolves HelmRepository charts through the shared acquisition cache.
Package oci fetches verified OCI source layers through the shared acquisition cache.
Package oci fetches verified OCI source layers through the shared acquisition cache.
Package safepath validates archive names and confines disk paths to a root.
Package safepath validates archive names and confines disk paths to a root.
Package sourceignore builds Flux artifact-exclusion policy from in-tree .sourceignore files and caller-supplied spec.ignore patterns.
Package sourceignore builds Flux artifact-exclusion policy from in-tree .sourceignore files and caller-supplied spec.ignore patterns.
Package ssrfguard is an opt-in SSRF egress guard for flate's outbound source fetches.
Package ssrfguard is an opt-in SSRF egress guard for flate's outbound source fetches.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL