Documentation
¶
Overview ¶
Package fetch provides streaming artifact downloading with retry, circuit breaking, and URL resolution for package registries.
Index ¶
- Variables
- type Artifact
- type ArtifactInfo
- type CircuitBreakerFetcher
- func (cbf *CircuitBreakerFetcher) Fetch(ctx context.Context, fetchURL string) (*Artifact, error)
- func (cbf *CircuitBreakerFetcher) FetchObserved(ctx context.Context, fetchURL string) (*ObservedArtifact, error)
- func (cbf *CircuitBreakerFetcher) FetchObservedWithHeaders(ctx context.Context, fetchURL string, headers http.Header) (*ObservedArtifact, error)
- func (cbf *CircuitBreakerFetcher) FetchWithHeaders(ctx context.Context, fetchURL string, headers http.Header) (*Artifact, error)
- func (cbf *CircuitBreakerFetcher) GetBreakerState() map[string]string
- func (cbf *CircuitBreakerFetcher) Head(ctx context.Context, headURL string) (size int64, contentType string, err error)
- type FetchObservation
- type Fetcher
- func (f *Fetcher) Close() error
- func (f *Fetcher) Fetch(ctx context.Context, url string) (*Artifact, error)
- func (f *Fetcher) FetchObserved(ctx context.Context, url string) (*ObservedArtifact, error)
- func (f *Fetcher) FetchObservedWithHeaders(ctx context.Context, url string, headers http.Header) (*ObservedArtifact, error)
- func (f *Fetcher) FetchWithHeaders(ctx context.Context, url string, headers http.Header) (*Artifact, error)
- func (f *Fetcher) Head(ctx context.Context, url string) (size int64, contentType string, err error)
- type FetcherInterface
- type ObservedArtifact
- type Option
- type Registry
- type ResolveOptions
- type Resolver
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Artifact ¶
type Artifact struct {
Body io.ReadCloser
Size int64 // -1 if unknown
ContentType string
ETag string
}
Artifact contains the response from fetching an upstream artifact.
type ArtifactInfo ¶
type ArtifactInfo struct {
URL string
Filename string
Integrity string // sha256-... or sha512-...
Size int64 // Zero when the registry does not publish a size.
}
ArtifactInfo contains information about a downloadable artifact.
type CircuitBreakerFetcher ¶
type CircuitBreakerFetcher struct {
// contains filtered or unexported fields
}
CircuitBreakerFetcher wraps a Fetcher with per-registry circuit breakers.
func NewCircuitBreakerFetcher ¶
func NewCircuitBreakerFetcher(f *Fetcher) *CircuitBreakerFetcher
NewCircuitBreakerFetcher creates a new circuit breaker wrapper for a fetcher.
func (*CircuitBreakerFetcher) Fetch ¶
Fetch wraps the underlying fetcher's Fetch with circuit breaker logic.
func (*CircuitBreakerFetcher) FetchObserved ¶
func (cbf *CircuitBreakerFetcher) FetchObserved(ctx context.Context, fetchURL string) (*ObservedArtifact, error)
FetchObserved wraps the underlying fetcher's FetchObserved with circuit breaker logic.
func (*CircuitBreakerFetcher) FetchObservedWithHeaders ¶
func (cbf *CircuitBreakerFetcher) FetchObservedWithHeaders(ctx context.Context, fetchURL string, headers http.Header) (*ObservedArtifact, error)
FetchObservedWithHeaders wraps the underlying fetcher's FetchObservedWithHeaders with circuit breaker logic.
func (*CircuitBreakerFetcher) FetchWithHeaders ¶
func (cbf *CircuitBreakerFetcher) FetchWithHeaders(ctx context.Context, fetchURL string, headers http.Header) (*Artifact, error)
FetchWithHeaders wraps the underlying fetcher's FetchWithHeaders with circuit breaker logic.
func (*CircuitBreakerFetcher) GetBreakerState ¶
func (cbf *CircuitBreakerFetcher) GetBreakerState() map[string]string
GetBreakerState returns the current state of circuit breakers (for health checks).
type FetchObservation ¶
type FetchObservation struct {
RequestedURL string
FinalURL string
ResponseTime time.Duration // Time until the final response headers arrived.
StatusCode int
Headers http.Header // Allow-listed response headers only.
DeclaredSize int64
MediaType string
ByteCount int64
Digests map[string]string
Complete bool
}
FetchObservation contains metadata about a successful artifact response. ByteCount and Digests are populated, and Complete is set to true, only after the response body reaches EOF.
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher downloads artifacts from upstream registries.
func NewFetcher ¶
NewFetcher creates a new Fetcher with the given options. Callers should invoke Close when done to release the DNS refresh goroutine. Under TinyGo, requests require WithHTTPClient.
func (*Fetcher) Close ¶
Close stops the Fetcher's background DNS refresh goroutine. It is safe to call Close more than once.
func (*Fetcher) Fetch ¶
Fetch downloads an artifact from the given URL. The caller must close the returned Artifact.Body when done.
func (*Fetcher) FetchObserved ¶
FetchObserved downloads an artifact and records metadata about the response. The caller must read the body to EOF before treating the observation as complete.
func (*Fetcher) FetchObservedWithHeaders ¶
func (f *Fetcher) FetchObservedWithHeaders(ctx context.Context, url string, headers http.Header) (*ObservedArtifact, error)
FetchObservedWithHeaders downloads an artifact with additional HTTP headers and records metadata about the response. Request headers are not copied into the observation.
type FetcherInterface ¶
type FetcherInterface interface {
Fetch(ctx context.Context, url string) (*Artifact, error)
FetchWithHeaders(ctx context.Context, url string, headers http.Header) (*Artifact, error)
Head(ctx context.Context, url string) (size int64, contentType string, err error)
}
FetcherInterface defines the interface for artifact fetchers.
type ObservedArtifact ¶
type ObservedArtifact struct {
*Artifact
Observation *FetchObservation
}
ObservedArtifact contains an artifact and its fetch observation.
type Option ¶
type Option func(*Fetcher)
Option configures a Fetcher.
func WithAllowPrivateHosts ¶
WithAllowPrivateHosts permits the named hosts to resolve to private IP addresses. Loopback and link-local addresses remain blocked.
func WithAuthFunc ¶
WithAuthFunc sets a function that returns auth headers for a given URL. The function receives the request URL and returns a header name and value. Return empty strings to skip authentication for that URL.
func WithBaseDelay ¶
WithBaseDelay sets the base delay for exponential backoff.
func WithHTTPClient ¶
WithHTTPClient sets a custom HTTP client. To allow private hosts with a custom client, construct it with safehttp.New and the desired options before applying transport wrappers and passing it here.
func WithMaxRetries ¶
WithMaxRetries sets the maximum retry attempts.
type Registry ¶
type Registry interface {
Ecosystem() string
FetchVersions(ctx context.Context, name string) ([]registries.Version, error)
URLs() client.URLBuilder
}
Registry provides package metadata and URL information for artifact resolution. This interface is satisfied by registries.Registry implementations.
type ResolveOptions ¶
ResolveOptions narrows versions that publish several artifact files.
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver determines download URLs for package artifacts.
func (*Resolver) RegisterRegistry ¶
RegisterRegistry adds a registry for URL resolution.
func (*Resolver) Resolve ¶
func (r *Resolver) Resolve(ctx context.Context, ecosystem, name, version string) (*ArtifactInfo, error)
Resolve returns the download URL and filename for a package artifact.
func (*Resolver) ResolveWithOptions ¶
func (r *Resolver) ResolveWithOptions( ctx context.Context, ecosystem string, name string, version string, options ResolveOptions, ) (*ArtifactInfo, error)
ResolveWithOptions returns the download metadata matching filename and registry-native integrity constraints when they are populated.