registry

package
v0.3.0-beta.12 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 11, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// DefaultMaxDecompressedSize caps the raw decompressed TAR stream.
	DefaultMaxDecompressedSize int64 = 500 * 1024 * 1024
	// DefaultMaxFileCount caps the number of filesystem nodes materialized.
	DefaultMaxFileCount = 10000
	// DefaultMaxArchiveDepth caps the number of path components in one entry.
	DefaultMaxArchiveDepth = 64
)
View Source
const (
	// DefaultMaxArchiveSize caps the compressed archive stream before extraction.
	DefaultMaxArchiveSize int64 = 50 * 1024 * 1024
)

Variables

View Source
var (
	// ErrArchiveRootRequired reports that ExtractArchive received no acquired extraction root.
	ErrArchiveRootRequired = errors.New("archive extraction root is required")
	// ErrArchiveEntryPathRequired reports that an archive entry did not contain a usable path.
	ErrArchiveEntryPathRequired = errors.New("archive entry path is required")
	// ErrArchiveEntryMustBeRelative reports that an archive entry path was absolute.
	ErrArchiveEntryMustBeRelative = errors.New("archive entry must be relative")
	// ErrArchiveEntryEscapesRoot reports that an archive entry would escape the extraction root.
	ErrArchiveEntryEscapesRoot = errors.New("archive entry escapes the extraction root")
	// ErrUnsupportedArchiveEntryType reports an unsupported tar entry type.
	ErrUnsupportedArchiveEntryType = errors.New("unsupported archive entry type")
	// ErrArchiveDuplicateEntry reports that an archive declared the same path more than once.
	ErrArchiveDuplicateEntry = errors.New("archive contains duplicate entry")
	// ErrPathRootRequired reports that PathWithinRoot received a blank root path.
	ErrPathRootRequired = errors.New("root path is required")
	// ErrPathOutsideRoot reports that a path resolves outside the provided root.
	ErrPathOutsideRoot = errors.New("path must stay within the root directory")
	// ErrPathTraversesSymlink reports a symlink or reparse point in the staging tree.
	ErrPathTraversesSymlink = errors.New("path traverses symlink")
)
View Source
var ErrArchiveDigestMismatch = errors.New("registry: archive digest mismatch")

ErrArchiveDigestMismatch reports an archive that differs from its digest pin.

View Source
var (
	// ErrArchiveTooLargeCompressed reports a compressed archive stream above its configured limit.
	ErrArchiveTooLargeCompressed = errors.New("registry: archive exceeds max compressed size")
)
View Source
var ErrInstallPublicationBusy = errors.New("registry: install publication is busy")

ErrInstallPublicationBusy reports another live publisher for the same target.

View Source
var ErrInstallPublicationRecoveryRequired = errors.New("registry: install publication recovery required")

ErrInstallPublicationRecoveryRequired reports an interrupted replacement whose filesystem state cannot be resolved without operator inspection.

View Source
var ErrInstallTargetExists = errors.New("registry: install target already exists")

ErrInstallTargetExists reports an atomic no-replace publication collision.

View Source
var ErrNotSupported = errors.New("registry: operation not supported")

ErrNotSupported reports that a registry source does not implement an operation.

View Source
var ErrPackageNotFound = errors.New("registry: package not found")

ErrPackageNotFound reports that no registry source resolved a package slug.

Functions

func NewPackageNotFoundError

func NewPackageNotFoundError(slug string) error

NewPackageNotFoundError returns the canonical package-not-found error.

func VersionIsNewer

func VersionIsNewer(current string, latest string) bool

VersionIsNewer reports whether latest is a valid semantic version newer than current. Invalid version strings never produce an update signal.

Types

type ArchiveDigestMismatchError

type ArchiveDigestMismatchError struct {
	ExpectedSHA256 string
	ActualSHA256   string
}

ArchiveDigestMismatchError contains expected and actual archive digests.

func (*ArchiveDigestMismatchError) Error

func (*ArchiveDigestMismatchError) Is

func (e *ArchiveDigestMismatchError) Is(target error) bool

type CleanupDiagnostic

type CleanupDiagnostic struct {
	Operation CleanupOperation `json:"operation"`
}

CleanupDiagnostic reports completed-install cleanup degradation.

type CleanupOperation

type CleanupOperation string

CleanupOperation identifies a degraded best-effort cleanup step without exposing filesystem paths or underlying error text.

const (
	CleanupOperationStaleTemp      CleanupOperation = "remove_stale_temp"
	CleanupOperationStagingTemp    CleanupOperation = "remove_staging_temp"
	CleanupOperationExtractionRoot CleanupOperation = "close_extraction_root"
	CleanupOperationBackup         CleanupOperation = "remove_replaced_backup"
	CleanupOperationStream         CleanupOperation = "close_download_stream"
	CleanupOperationPublication    CleanupOperation = "finalize_published_install"
	CleanupOperationSourceParent   CleanupOperation = "close_install_source_parent"
	CleanupOperationTargetParent   CleanupOperation = "close_install_target_parent"
)

type Detail

type Detail struct {
	Listing
	Readme     string   `json:"readme"`
	MCPServers []string `json:"mcp_servers,omitempty"`
	Tags       []string `json:"tags"`
	License    string   `json:"license"`
	Repository string   `json:"repository"`
	Versions   []string `json:"versions"`
}

Detail is the full metadata for one registry package.

type DownloadOpts

type DownloadOpts struct {
	Version        string
	Asset          string
	MaxArchiveSize int64
	ExpectedSHA256 string
}

DownloadOpts controls version and asset selection for a download.

type DownloadResult

type DownloadResult struct {
	// Reader is transferred to the installer after Download returns successfully.
	// Close must interrupt a concurrent Read so cancellation can synchronously
	// stop archive spooling without leaving a worker behind.
	Reader         io.ReadCloser
	Slug           string
	Version        string
	ContentSize    int64
	Checksum       string
	ContentType    string
	ExpectedSHA256 string
	// contains filtered or unexported fields
}

DownloadResult is the structured download response returned by a source.

type Downloader

type Downloader interface {
	Download(ctx context.Context, slug string, opts DownloadOpts) (*DownloadResult, error)
}

Downloader is the minimal download contract required by the installer.

type HTTPArchiveDownloader

type HTTPArchiveDownloader struct {
	// contains filtered or unexported fields
}

HTTPArchiveDownloader acquires one catalog-pinned archive over HTTPS.

func NewHTTPArchiveDownloader

func NewHTTPArchiveDownloader(
	artifactURL string,
	version string,
	client *http.Client,
) (*HTTPArchiveDownloader, error)

NewHTTPArchiveDownloader constructs a downloader for one exact curated artifact.

func (*HTTPArchiveDownloader) Download

func (d *HTTPArchiveDownloader) Download(
	ctx context.Context,
	slug string,
	opts DownloadOpts,
) (*DownloadResult, error)

Download fetches the configured artifact while preserving its feed-owned version.

type InstallResult

type InstallResult struct {
	Slug                string              `json:"slug"`
	Name                string              `json:"name"`
	Version             string              `json:"version"`
	Source              string              `json:"source"`
	InstallPath         string              `json:"install_path"`
	Checksum            string              `json:"checksum"`
	ArchiveDigestSHA256 string              `json:"archive_digest_sha256"`
	DigestMatched       bool                `json:"digest_matched"`
	CleanupDiagnostics  []CleanupDiagnostic `json:"cleanup_diagnostics,omitempty"`
}

InstallResult is the outcome of a registry-backed install.

type Installer

type Installer struct {
	// contains filtered or unexported fields
}

Installer handles download, extraction, validation, verification, and the final atomic move into place.

func NewInstaller

func NewInstaller(dl Downloader, opts ...InstallerOption) *Installer

NewInstaller constructs a new domain-agnostic install pipeline.

func (*Installer) Install

func (i *Installer) Install(
	ctx context.Context,
	slug string,
	dlOpts DownloadOpts,
	targetDir string,
) (result *InstallResult, err error)

Install downloads, extracts, verifies, and atomically moves a package into its final target directory.

type InstallerOption

type InstallerOption func(*Installer)

InstallerOption customizes the installer pipeline.

func WithInstallerMaxArchiveDepth

func WithInstallerMaxArchiveDepth(depth int) InstallerOption

WithInstallerMaxArchiveDepth overrides the archive path-depth limit.

func WithInstallerMaxArchiveSize

func WithInstallerMaxArchiveSize(size int64) InstallerOption

WithInstallerMaxArchiveSize overrides the compressed archive limit.

func WithInstallerMaxDecompressedSize

func WithInstallerMaxDecompressedSize(size int64) InstallerOption

WithInstallerMaxDecompressedSize overrides the extracted payload limit.

func WithInstallerMaxFileCount

func WithInstallerMaxFileCount(count int) InstallerOption

WithInstallerMaxFileCount overrides the extracted file-count limit.

func WithInstallerNow

func WithInstallerNow(now func() time.Time) InstallerOption

WithInstallerNow overrides the clock used for stale-temp cleanup.

func WithInstallerTempDirMaxAge

func WithInstallerTempDirMaxAge(age time.Duration) InstallerOption

WithInstallerTempDirMaxAge overrides the stale-temp cleanup threshold.

type Listing

type Listing struct {
	Slug        string      `json:"slug"`
	Name        string      `json:"name"`
	Description string      `json:"description"`
	Author      string      `json:"author"`
	Version     string      `json:"version"`
	Downloads   int         `json:"downloads"`
	Source      string      `json:"source"`
	Type        PackageType `json:"type"`
}

Listing is one registry search result.

type MoveInstalledDirResult

type MoveInstalledDirResult struct {
	Committed          bool                `json:"committed"`
	CleanupDiagnostics []CleanupDiagnostic `json:"cleanup_diagnostics,omitempty"`
}

MoveInstalledDirResult reports a successful directory publication and any best-effort cleanup or durability degradation observed after commit.

func MoveInstalledDir

func MoveInstalledDir(
	extractedDir string,
	targetDir string,
	replaceExisting bool,
) (result *MoveInstalledDirResult, err error)

MoveInstalledDir moves an extracted package directory into its final location. It never creates the target parent. A committed publication remains success even when a subsequent durability or cleanup step reports a diagnostic.

type MultiRegistry

type MultiRegistry struct {
	// contains filtered or unexported fields
}

MultiRegistry aggregates multiple registry sources.

Sources are ordered from lowest priority to highest priority. Higher-priority sources override lower-priority search results when the same slug appears more than once.

func NewMultiRegistry

func NewMultiRegistry(logger *slog.Logger, sources ...Source) *MultiRegistry

NewMultiRegistry constructs a registry aggregator over one or more sources.

func (*MultiRegistry) CheckUpdate

func (m *MultiRegistry) CheckUpdate(ctx context.Context, slug string, currentVersion string) (*UpdateInfo, error)

CheckUpdate compares the local version against the latest version available from the resolved source.

func (*MultiRegistry) Close

func (m *MultiRegistry) Close() error

Close closes every underlying source and joins any close errors.

func (*MultiRegistry) Download

func (m *MultiRegistry) Download(ctx context.Context, slug string, opts DownloadOpts) (*DownloadResult, error)

Download delegates the archive fetch to the highest-priority source that can resolve the requested slug.

func (*MultiRegistry) Info

func (m *MultiRegistry) Info(ctx context.Context, slug string) (*Detail, error)

Info resolves package detail from the highest-priority source that has the requested slug.

func (*MultiRegistry) Search

func (m *MultiRegistry) Search(ctx context.Context, query string, opts SearchOpts) ([]Listing, error)

Search queries every searchable registry source concurrently and merges the results using source priority.

func (*MultiRegistry) SourceNamed

func (m *MultiRegistry) SourceNamed(name string) Source

SourceNamed returns the highest-priority source with the requested name.

type PackageNotFoundError

type PackageNotFoundError struct {
	Slug string
}

PackageNotFoundError carries the missing package slug.

func (PackageNotFoundError) Error

func (e PackageNotFoundError) Error() string

func (PackageNotFoundError) Is

func (e PackageNotFoundError) Is(target error) bool

type PackageType

type PackageType string

PackageType distinguishes skills from extensions in registry results.

const (
	PackageTypeSkill     PackageType = "skill"
	PackageTypeExtension PackageType = "extension"
	PackageTypeAll       PackageType = ""
)

type SearchOpts

type SearchOpts struct {
	Limit  int         `json:"limit"`
	Offset int         `json:"offset"`
	Type   PackageType `json:"type"`
}

SearchOpts controls search pagination and package filtering.

type Source

type Source interface {
	Name() string
	Capabilities() SourceCaps
	Search(ctx context.Context, query string, opts SearchOpts) ([]Listing, error)
	Info(ctx context.Context, slug string) (*Detail, error)
	Download(ctx context.Context, slug string, opts DownloadOpts) (*DownloadResult, error)
	Close() error
}

Source abstracts one registry backend.

type SourceCaps

type SourceCaps struct {
	Search bool
}

SourceCaps declares which operations one registry source supports.

type UpdateInfo

type UpdateInfo struct {
	Slug           string `json:"slug"`
	CurrentVersion string `json:"current_version"`
	LatestVersion  string `json:"latest_version"`
	HasUpdate      bool   `json:"has_update"`
	Source         string `json:"source"`
}

UpdateInfo is the result of a local-vs-remote update check.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL