Documentation
¶
Overview ¶
Package uses provides a cache+clients for storing and retrieving remote workflows.
Index ¶
- Constants
- Variables
- func AvailablePolicies() []string
- func ParseIndex(r io.Reader) (map[string]Descriptor, error)
- func ResolvePkgAlias(pURL packageurl.PackageURL, aliases v1.AliasMap) (packageurl.PackageURL, bool)
- func ResolveRelative(prev *url.URL, u string, pkgAliases v1.AliasMap) (*url.URL, error)
- type Descriptor
- type FetchPolicy
- type Fetcher
- type FetcherService
- type FetcherServiceOption
- type GitHubClient
- type GitLabClient
- type HTTPClient
- type LocalFetcher
- type LocalStore
- type OCIClient
- type Storage
- type StoreFetcher
Constants ¶
const DefaultFileName = "tasks.yaml"
DefaultFileName is the default file name to use when a path resolves to "."
const DefaultVersion = "main"
DefaultVersion is the default version to use when a version is not specified
const IndexFileName = "index.txt"
IndexFileName is the name of the index file.
const OCIQueryParamInsecureSkipTLSVerify = "insecure-skip-tls-verify"
OCIQueryParamInsecureSkipTLSVerify is the query param for the OCI client to allow for an insecure HTTPS connection
const OCIQueryParamPlainHTTP = "plain-http"
OCIQueryParamPlainHTTP is the query param for the OCI client to use plain HTTP
const QualifierBaseURL = "base-url"
QualifierBaseURL is the qualifier for the base URL to use when fetching a package
const QualifierTask = "task"
QualifierTask is the qualifier for the task to use when fetching a package
const QualifierTokenFromEnv = "token-from-env"
QualifierTokenFromEnv is the qualifier for the token to use when fetching a package
Variables ¶
var DigestPattern = regexp.MustCompile(`^h1:([a-fA-F0-9]{64})$`)
DigestPattern is the regexp for a digest entry in an index
Functions ¶
func AvailablePolicies ¶
func AvailablePolicies() []string
AvailablePolicies returns a list of available fetch policies
func ParseIndex ¶
func ParseIndex(r io.Reader) (map[string]Descriptor, error)
ParseIndex reads and validates cache index entries
Each line format: <url> h1:<sha256-hex> <size-bytes> Returns a map of URLs to their descriptors for cache lookups
func ResolvePkgAlias ¶ added in v0.5.0
func ResolvePkgAlias(pURL packageurl.PackageURL, aliases v1.AliasMap) (packageurl.PackageURL, bool)
ResolvePkgAlias transforms package URLs using configured aliases
Maps short package URL types to full package URLs with authentication and base URL configuration. Returns the resolved package URL and whether an alias was expanded
func ResolveRelative ¶
ResolveRelative resolves workflow references relative to the current context
Handles multiple URL schemes (file, http, https, pkg, oci) with proper path resolution. Supports package URL aliases, task parameters, and cross-scheme transitions. Returns resolved URL ready for fetching
Types ¶
type Descriptor ¶
Descriptor describes a file to use for caching.
type FetchPolicy ¶
type FetchPolicy string
FetchPolicy defines the fetching behavior for the fetcher service
const ( // FetchPolicyAlways will always fetch from source, then cache the result, overriding any existing cache entry FetchPolicyAlways FetchPolicy = "always" // FetchPolicyIfNotPresent will use the cache if available, otherwise fetch from source FetchPolicyIfNotPresent FetchPolicy = "if-not-present" // FetchPolicyNever will never fetch from source, only using the cache (which must exist) FetchPolicyNever FetchPolicy = "never" // DefaultFetchPolicy is the default fetch policy used when none is specified DefaultFetchPolicy FetchPolicy = FetchPolicyIfNotPresent )
func (FetchPolicy) JSONSchemaExtend ¶
func (FetchPolicy) JSONSchemaExtend(schema *jsonschema.Schema)
JSONSchemaExtend extends the JSON schema for FetchPolicy
func (*FetchPolicy) Set ¶
func (f *FetchPolicy) Set(value string) error
Set implements the pflag.Value interface
func (*FetchPolicy) String ¶
func (f *FetchPolicy) String() string
String implements the pflag.Value and fmt.Stringer interfaces
func (*FetchPolicy) Type ¶
func (f *FetchPolicy) Type() string
Type implements the pflag.Value interface
type FetcherService ¶
type FetcherService struct {
// contains filtered or unexported fields
}
FetcherService creates and manages fetchers
func NewFetcherService ¶
func NewFetcherService(opts ...FetcherServiceOption) (*FetcherService, error)
NewFetcherService creates a configured service for fetching remote workflows
Supports GitHub, GitLab, OCI, HTTP sources with caching, custom storage, and fetch policies
func (*FetcherService) GetFetcher ¶
func (s *FetcherService) GetFetcher(uri *url.URL) (Fetcher, error)
GetFetcher returns a fetcher for the given URL
Fetchers are cached using the full URI string as the ID to avoid unnecessary recreates
type FetcherServiceOption ¶
type FetcherServiceOption func(*FetcherService)
FetcherServiceOption is a function that configures a FetcherService
func WithClient ¶
func WithClient(client *http.Client) FetcherServiceOption
WithClient sets the HTTP client to be used by the fetcher service
func WithFS ¶
func WithFS(fsys afero.Fs) FetcherServiceOption
WithFS sets the filesystem to be used by the fetcher service
func WithFetchPolicy ¶
func WithFetchPolicy(policy FetchPolicy) FetcherServiceOption
WithFetchPolicy sets the fetch policy to be used by the fetcher service
func WithStorage ¶
func WithStorage(store Storage) FetcherServiceOption
WithStorage sets the store to be used by the fetcher service
type GitHubClient ¶
type GitHubClient struct {
// contains filtered or unexported fields
}
GitHubClient is a client for fetching files from GitHub
func NewGitHubClient ¶
NewGitHubClient creates a new GitHub client
Uses auth token from tokenEnv > GITHUB_ENV > no auth token
func (*GitHubClient) Fetch ¶
func (g *GitHubClient) Fetch(ctx context.Context, uri *url.URL) (io.ReadCloser, error)
Fetch downloads a file from GitHub
type GitLabClient ¶
type GitLabClient struct {
// contains filtered or unexported fields
}
GitLabClient is a client for fetching files from GitLab
func NewGitLabClient ¶
NewGitLabClient creates a new GitLab client
Uses auth token from tokenEnv > GITLAB_ENV > no auth token, uses https://gitlab.com as the base URL if none is provided
func (*GitLabClient) Fetch ¶
func (g *GitLabClient) Fetch(ctx context.Context, uri *url.URL) (io.ReadCloser, error)
Fetch downloads a file from GitLab
type HTTPClient ¶
type HTTPClient struct {
// contains filtered or unexported fields
}
HTTPClient fetches a file from a remote HTTP server
func NewHTTPClient ¶
func NewHTTPClient(client *http.Client) *HTTPClient
NewHTTPClient creates a client for fetching workflows over HTTP/HTTPS
Provides a simple HTTP fetcher with proper user agent and context support
func (*HTTPClient) Fetch ¶
func (f *HTTPClient) Fetch(ctx context.Context, uri *url.URL) (io.ReadCloser, error)
Fetch downloads workflow content from HTTP/HTTPS URLs
Sets a maru2 user agent and handles standard HTTP error responses. Returns the response body as a ReadCloser for streaming
type LocalFetcher ¶
type LocalFetcher struct {
// contains filtered or unexported fields
}
LocalFetcher fetches a file from the local filesystem.
func NewLocalFetcher ¶
func NewLocalFetcher(fsys afero.Fs) *LocalFetcher
NewLocalFetcher creates a new local fetcher
func (*LocalFetcher) Fetch ¶
func (f *LocalFetcher) Fetch(ctx context.Context, uri *url.URL) (io.ReadCloser, error)
Fetch opens a file handle at the given location
type LocalStore ¶
type LocalStore struct {
// contains filtered or unexported fields
}
LocalStore is a cache for storing and retrieving cached remote workflows from a filesystem.
func NewLocalStore ¶
func NewLocalStore(fsys afero.Fs) (*LocalStore, error)
NewLocalStore creates a filesystem-based workflow cache
Initializes or loads an existing cache with integrity checking. The index.txt file tracks cached workflows with SHA256 digests
func (*LocalStore) Exists ¶
func (s *LocalStore) Exists(uri *url.URL) (bool, error)
Exists checks if a workflow exists in the store.
func (*LocalStore) Fetch ¶
func (s *LocalStore) Fetch(_ context.Context, uri *url.URL) (io.ReadCloser, error)
Fetch retrieves a workflow from the store
func (*LocalStore) GC ¶
func (s *LocalStore) GC() error
GC performs garbage collection on the store.
func (*LocalStore) List ¶
func (s *LocalStore) List() iter.Seq2[string, Descriptor]
List returns a Go 1.23+ iterator to loop over all of the stored workflows
ok but does this really need to be an iterator, no ill prob move it to a regular map access w/ maps.Copy, but this was still fun
type OCIClient ¶
type OCIClient struct {
// contains filtered or unexported fields
}
OCIClient fetches workflows from OCI repositories
type Storage ¶
type Storage interface {
Fetcher
Exists(uri *url.URL) (bool, error)
Store(r io.Reader, uri *url.URL) error
List() iter.Seq2[string, Descriptor]
}
Storage interface for storing and retrieving cached remote workflows.
type StoreFetcher ¶
type StoreFetcher struct {
Source Fetcher
Store Storage
Policy FetchPolicy
}
StoreFetcher is a fetcher that wraps another fetcher and caches the results in a store according to the cache policy.
func (*StoreFetcher) Fetch ¶
func (f *StoreFetcher) Fetch(ctx context.Context, uri *url.URL) (io.ReadCloser, error)
Fetch implements the Fetcher interface
This is one of my favorite functions
Source Files