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:
- Implement source.Fetcher for the new kind in a new file (or subpackage) under pkg/source.
- 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
- func BasicAuthFromSecret(sec *manifest.Secret, owner manifest.DiagnosticIdentity, secretRef string) (string, string, error)
- func MissingSecretErr(owner manifest.DiagnosticIdentity, secretRef, reason string) error
- func NewHTTPTransport(material TransportMaterial) *http.Transport
- func OperationView(ctx context.Context, input fs.FS) (fs.FS, string, error)
- type Fetcher
- type HTTPInputs
- type HTTPRequest
- type HTTPTransportConfig
- type MissingSecretError
- type Network
- func (n *Network) AWSCredentials(ctx context.Context, provider aws.Provider) (aws.Value, error)
- func (n *Network) Close()
- func (n *Network) HTTPTransport(cfg HTTPTransportConfig) (http.RoundTripper, error)
- func (n *Network) RegistryCredentials(ctx context.Context, configPath, hostname string) (*auth.Credential, error)
- func (n *Network) RoundTrip(r *http.Request) (*http.Response, error)
- type PreparedFetch
- type SecretGetter
- type TransportInput
- type TransportMaterial
- type TypedFetcher
Constants ¶
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.
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.
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
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
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.
type PreparedFetch ¶ added in v0.7.3
type PreparedFetch struct {
Inputs []manifest.DependencyRef
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 ¶
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.
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.
Source Files
¶
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. |
|
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. |