Documentation
¶
Overview ¶
Package oci wraps oras-go for agentfile use: authenticated remote repositories, manifest/index resolution, blob fetching, and a Puller abstraction that extracts a bin layer from an image.
Index ¶
- Constants
- func AgentFetcher(opts ...RemoteRepositoryOption) func(ctx context.Context, ref spec.Reference) (*spec.Agentfile, error)
- func FetchBlobBytes(ctx context.Context, fetcher content.Fetcher, desc v1.Descriptor) ([]byte, error)
- func HostPlatform() v1.Platform
- func LinuxPlatform() v1.Platform
- func LoadAgentFromSource(ctx context.Context, src oras.ReadOnlyTarget, ref spec.Reference) (*spec.Agentfile, error)
- func NewRemoteRepository(ref spec.Reference, opts ...RemoteRepositoryOption) (*remote.Repository, error)
- func ParseTag(ref spec.Reference) string
- func ResolveManifest(ctx context.Context, fetcher content.Fetcher, desc v1.Descriptor, ...) (*v1.Manifest, error)
- func WithPlainHTTP(repo *remote.Repository)
- type Puller
- type RemoteRepositoryOption
- type UsageFetcher
Constants ¶
const DefaultRetryMaxElapsedTime = 30 * time.Second
DefaultRetryMaxElapsedTime caps the total wall-clock time the retry transport will spend on a single HTTP request, including all backoff sleeps. 30 s comfortably covers the GHCR "first-push" 500 race (typically 1–5 s) without making bad-credential errors feel sluggish — the auth path 401s fast and 4xx isn't retried.
Variables ¶
This section is empty.
Functions ¶
func AgentFetcher ¶
func AgentFetcher( opts ...RemoteRepositoryOption, ) func(ctx context.Context, ref spec.Reference) (*spec.Agentfile, error)
AgentFetcher returns a resolve.Fetcher that pulls agent artifacts from a remote OCI registry.
func FetchBlobBytes ¶
func FetchBlobBytes(ctx context.Context, fetcher content.Fetcher, desc v1.Descriptor) ([]byte, error)
FetchBlobBytes reads the blob identified by desc from fetcher into memory. Accepts any content.Fetcher so it can be exercised against in-memory stores in tests as well as remote repositories.
func HostPlatform ¶
HostPlatform is the platform of the process itself — what the system executor runs binaries as.
func LinuxPlatform ¶
LinuxPlatform is linux on the host's architecture — what the docker executor needs, since binaries run inside Linux containers regardless of the host OS.
func LoadAgentFromSource ¶
func LoadAgentFromSource( ctx context.Context, src oras.ReadOnlyTarget, ref spec.Reference, ) (*spec.Agentfile, error)
LoadAgentFromSource copies the manifest at ref out of src into a fresh in-memory oras store and returns the hydrated Agentfile.
Exposed (vs. inlined into AgentFetcher) so callers can test the fetch logic against an in-memory source — no httptest registry, no daemon — and so non-remote sources (e.g. an embedded local registry) can reuse the same load path.
func NewRemoteRepository ¶
func NewRemoteRepository(ref spec.Reference, opts ...RemoteRepositoryOption) (*remote.Repository, error)
NewRemoteRepository constructs an oras remote.Repository bound to ref, wired up with Docker credential resolution and a retrying transport that tolerates transient 5xx + transport errors. The retry is what lets the first-ever push of a brand-new GHCR package succeed: GHCR provisions backend storage on the first manifest PUT and the request can race the provisioning step.
func ResolveManifest ¶
func ResolveManifest( ctx context.Context, fetcher content.Fetcher, desc v1.Descriptor, platform v1.Platform, ) (*v1.Manifest, error)
ResolveManifest fetches the blob at desc and parses it as a v1.Manifest. If the blob is a v1.Index, the child manifest matching platform is selected and resolved recursively. Resolution fails closed: an index with no manifest for the requested platform is an error, never a silent arbitrary pick.
func WithPlainHTTP ¶
func WithPlainHTTP(repo *remote.Repository)
WithPlainHTTP configures the repository to use HTTP instead of HTTPS. Suitable for local/dev registries only.
Types ¶
type Puller ¶
func NoopPuller ¶
func NoopPuller() Puller
func RemotePuller ¶
func RemotePuller(platform v1.Platform, opts ...RemoteRepositoryOption) Puller
RemotePuller pulls a bin/runtime binary from a registry, resolving multi-arch indexes against platform — the platform the binary will EXECUTE on (host for the system executor, linux/<arch> for docker), which is why the caller supplies it rather than this package assuming runtime.GOOS.
type RemoteRepositoryOption ¶
type RemoteRepositoryOption func(*remote.Repository)
RemoteRepositoryOption mutates a remote repository at construction time.
type UsageFetcher ¶
UsageFetcher fetches the USAGE.md body declared by a BIN image at ref. Returns the empty string with a nil error when the image carries no `io.openotters.bin.usage` annotation (or the annotation references a layer that isn't present). Errors are reserved for network / authentication / parse failures, so callers can treat an absent doc as a no-op without distinguishing it from a real failure path.
Parallel in shape to Puller: a function value the consumer wires into the executor pipeline — `RemoteUsageFetcher` for production, or nil to skip usage fetching entirely (tests / offline mode; the materialiser treats a nil fetcher as "no usage docs").
func RemoteUsageFetcher ¶
func RemoteUsageFetcher(platform v1.Platform, opts ...RemoteRepositoryOption) UsageFetcher
RemoteUsageFetcher mirrors RemotePuller for the documentation layer: resolves ref against a real registry, parses the manifest, and returns the body of the layer pointed at by the `io.openotters.bin.usage` annotation. The annotation defaults to `/USAGE.md` (see spec.DefaultUsagePath) but producers may pick a different path; this fetcher honours whatever the producer wrote.