source

Documentation

Overview

Package source fetches a tree from a remote or local origin and copies it into a destination directory. It is the transport seam shared by `txco init --from <source>` and the package commands (`txco install`, `txco inspect`): a single `Source` interface with interchangeable implementations behind one `Parse`.

Schemes:

github:owner/repo[@ref][/subpath]   public GitHub repo, fetched as a tar.gz
dir:./path                          a local directory tree
file:./path                         alias for dir:

The interface is deliberately transport-agnostic: the Package System that consumes it never imports a transport's concrete types. A future `oci://` scheme drops in here as another Source (and is the only one that would pull in an OCI client) without changing any call site.

The convention for `txco init`: a source is a *flat tree* meant to slot directly under `OPS/<stack>/` in the user's workspace. So given:

github:loremlabs/txco-templates/support-basic

where the repo's `support-basic/` directory contains:

support-basic/
  100/resonator.txcl
  200/resonator.txcl
  triage/100/resonator.txcl

running `txco init support --from github:loremlabs/txco-templates/support-basic` produces:

<cwd>/OPS/support/100/resonator.txcl
<cwd>/OPS/support/200/resonator.txcl
<cwd>/OPS/support/triage/100/resonator.txcl

Package commands instead fetch a whole package tree (a `txco.package.yaml` at the root plus an `OPS/`-shaped subtree). No variable substitution.

Index

• Constants
• func Fetch(ctx context.Context, spec, destDir string) (int, error)
• func FetchSignature(ctx context.Context, ref ParsedRef, sigTag string) (manifestBytes, layerBytes []byte, ann map[string]string, found bool, err error)
• func Publish(ctx context.Context, dir string, ref ParsedRef) (string, error)
• func PushSignature(ctx context.Context, ref ParsedRef, ...) error
• func SetCodeloadBaseURL(u string) string
• func SetPushRepositoryFactory(fn func(string) (oras.Target, error)) func(string) (oras.Target, error)
• func SetRepositoryFactory(fn func(string) (oras.ReadOnlyTarget, error)) func(string) (oras.ReadOnlyTarget, error)
• type ParsedRef
  • func ParseRef(s string) (ParsedRef, error)
  • func (r ParsedRef) Reference() string
  • func (r ParsedRef) Repository() string
  • func (r ParsedRef) TagOrDigest() string
  • func (r ParsedRef) WithDigest(digest string) string
• type Provenance
• type Resolver
• type Source
  • func Parse(spec string) (Source, error)

Constants

const (
	MediaTypePackageConfig = "application/vnd.thanks.computer.package.manifest.v1alpha1+yaml"
	MediaTypePackageLayer  = "application/vnd.thanks.computer.package.layer.v1alpha1.tar+gzip"
	ArtifactTypePackage    = "application/vnd.thanks.computer.package.v1alpha1"
)

TxCo package OCI media types (config = the verbatim manifest bytes; layer = one gzip(tar(tree))). artifactType is a distinct identity string.

Functions

func Fetch

func Fetch(ctx context.Context, spec, destDir string) (int, error)

Fetch is the one-shot entry point most callers want.

func FetchSignature

func FetchSignature(ctx context.Context, ref ParsedRef, sigTag string) (manifestBytes, layerBytes []byte, ann map[string]string, found bool, err error)

FetchSignature pulls the signature artifact at sigTag from ref's repository. A missing tag yields found=false with nil error (the package is simply unsigned); a transport failure yields a non-nil error. Returns the manifest bytes, the single payload layer's bytes, and the merged manifest+layer annotations (manifest wins on conflict).

func Publish

func Publish(ctx context.Context, dir string, ref ParsedRef) (string, error)

Publish packs the package tree at dir into a single-layer OCI artifact (config = the verbatim txco.package.yaml bytes; layer = gzip(tar(tree))) and pushes it to ref, returning the resolved manifest digest (sha256:...).

func PushSignature

func PushSignature(ctx context.Context, ref ParsedRef, build func(dst oras.Target) (string, error)) error

PushSignature uploads a signature artifact to ref's repository. `build` packs the artifact into an in-memory store and returns the tag it was given (sha256-<hex>.sig); that exact tag is copied to the remote.

func SetCodeloadBaseURL

func SetCodeloadBaseURL(u string) string

SetCodeloadBaseURL lets tests point the GitHub fetcher at an httptest server. Returns the previous value so callers can restore in t.Cleanup.

func SetPushRepositoryFactory

func SetPushRepositoryFactory(fn func(string) (oras.Target, error)) func(string) (oras.Target, error)

SetPushRepositoryFactory swaps the push-target constructor (tests only).

func SetRepositoryFactory

func SetRepositoryFactory(fn func(string) (oras.ReadOnlyTarget, error)) func(string) (oras.ReadOnlyTarget, error)

SetRepositoryFactory swaps the repository constructor (for tests). Returns the previous value so callers can restore it in t.Cleanup. TESTS ONLY — nothing in production should call the real factory with an in-process store.

Types

type ParsedRef

type ParsedRef struct {
	Registry  string // host[:port]
	Namespace string // path between host and the final segment (may be multi-segment or "")
	Name      string // final path segment (the repository name)
	Tag       string // tag label (empty when pinned by digest)
	Digest    string // "sha256:..." (empty when referenced by tag)
}

ParsedRef is a decomposed OCI package reference.

func ParseRef

func ParseRef(s string) (ParsedRef, error)

ParseRef decomposes an OCI reference. Accepts an optional `oci://` (or `oci:`) scheme prefix. Forms:

host/ns/name:tag
host/ns/name@sha256:...
host/name:tag
localhost:5000/ns/name:tag      (host port preserved)
host/ns/sub/name:tag            (multi-segment namespace)

A reference with neither tag nor digest defaults to tag "latest".

func (ParsedRef) Reference

func (r ParsedRef) Reference() string

Reference is the full canonical reference (repository plus :tag or @digest).

func (ParsedRef) Repository

func (r ParsedRef) Repository() string

Repository is the host/namespace/name string (no tag/digest) — what remote.NewRepository takes.

func (ParsedRef) TagOrDigest

func (r ParsedRef) TagOrDigest() string

TagOrDigest is the reference label to resolve within the repository (the srcRef for oras.Copy).

func (ParsedRef) WithDigest

func (r ParsedRef) WithDigest(digest string) string

WithDigest returns the repository pinned to a resolved digest.

type Provenance

type Provenance struct {
	Registry  string // host[:port]
	Namespace string
	Name      string // the repository name in the ref (not necessarily manifest.Name)
	Tag       string
	Digest    string // sha256:... — the manifest digest the pull resolved
	Reference string // oci://host/ns/name@sha256:...
}

Provenance is what a resolvable source reports after Fetch so callers (install) can record where bytes actually came from. dir/github sources do not implement Resolver, so their provenance stays blank.

type Resolver

type Resolver interface {
	Resolved() Provenance
}

Resolver is OPTIONAL; only ociSource implements it. Callers type-assert.

type Source

type Source interface {
	Spec() string
	Fetch(ctx context.Context, destDir string) (filesCopied int, err error)
}

Source is anything that knows how to populate destDir with a fetched tree. Implementations: githubSource, dirSource (and, later, ociSource — the only one that imports an OCI client).

func Parse

func Parse(spec string) (Source, error)

Parse turns a spec into a Source. Returns an error for unknown schemes or malformed specs so the caller can surface a clean message before any I/O.