Documentation
¶
Index ¶
- Constants
- Variables
- func NewPackageNotFoundError(slug string) error
- func VersionIsNewer(current string, latest string) bool
- type ArchiveDigestMismatchError
- type CleanupDiagnostic
- type CleanupOperation
- type Detail
- type DownloadOpts
- type DownloadResult
- type Downloader
- type HTTPArchiveDownloader
- type InstallResult
- type Installer
- type InstallerOption
- func WithInstallerMaxArchiveDepth(depth int) InstallerOption
- func WithInstallerMaxArchiveSize(size int64) InstallerOption
- func WithInstallerMaxDecompressedSize(size int64) InstallerOption
- func WithInstallerMaxFileCount(count int) InstallerOption
- func WithInstallerNow(now func() time.Time) InstallerOption
- func WithInstallerTempDirMaxAge(age time.Duration) InstallerOption
- type Listing
- type MoveInstalledDirResult
- type MultiRegistry
- func (m *MultiRegistry) CheckUpdate(ctx context.Context, slug string, currentVersion string) (*UpdateInfo, error)
- func (m *MultiRegistry) Close() error
- func (m *MultiRegistry) Download(ctx context.Context, slug string, opts DownloadOpts) (*DownloadResult, error)
- func (m *MultiRegistry) Info(ctx context.Context, slug string) (*Detail, error)
- func (m *MultiRegistry) Search(ctx context.Context, query string, opts SearchOpts) ([]Listing, error)
- func (m *MultiRegistry) SourceNamed(name string) Source
- type PackageNotFoundError
- type PackageType
- type SearchOpts
- type Source
- type SourceCaps
- type UpdateInfo
Constants ¶
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 )
const ( // DefaultMaxArchiveSize caps the compressed archive stream before extraction. DefaultMaxArchiveSize int64 = 50 * 1024 * 1024 )
Variables ¶
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") )
var ErrArchiveDigestMismatch = errors.New("registry: archive digest mismatch")
ErrArchiveDigestMismatch reports an archive that differs from its digest pin.
var ( // ErrArchiveTooLargeCompressed reports a compressed archive stream above its configured limit. ErrArchiveTooLargeCompressed = errors.New("registry: archive exceeds max compressed size") )
var ErrInstallPublicationBusy = errors.New("registry: install publication is busy")
ErrInstallPublicationBusy reports another live publisher for the same target.
var ErrInstallPublicationRecoveryRequired = errors.New("registry: install publication recovery required")
ErrInstallPublicationRecoveryRequired reports an interrupted replacement whose filesystem state cannot be resolved without operator inspection.
var ErrInstallTargetExists = errors.New("registry: install target already exists")
ErrInstallTargetExists reports an atomic no-replace publication collision.
var ErrNotSupported = errors.New("registry: operation not supported")
ErrNotSupported reports that a registry source does not implement an operation.
var ErrPackageNotFound = errors.New("registry: package not found")
ErrPackageNotFound reports that no registry source resolved a package slug.
Functions ¶
func NewPackageNotFoundError ¶
NewPackageNotFoundError returns the canonical package-not-found error.
func VersionIsNewer ¶
VersionIsNewer reports whether latest is a valid semantic version newer than current. Invalid version strings never produce an update signal.
Types ¶
type ArchiveDigestMismatchError ¶
ArchiveDigestMismatchError contains expected and actual archive digests.
func (*ArchiveDigestMismatchError) Error ¶
func (e *ArchiveDigestMismatchError) Error() string
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 ¶
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 ¶
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.
Source Files
¶
- extract.go
- extract_context.go
- extract_directory.go
- extract_limits.go
- extract_path.go
- http_archive.go
- installer.go
- installer_archive.go
- installer_checksum.go
- installer_cleanup.go
- installer_flow.go
- installer_io.go
- installer_metadata.go
- installer_publication.go
- installer_publication_journal.go
- installer_publication_lock.go
- installer_publication_recovery.go
- installer_publication_replace.go
- installer_result.go
- installer_staging.go
- installer_staging_lease.go
- installer_staging_lease_unix.go
- installer_stream.go
- multi.go
- multi_clone.go
- source.go
- types.go
- version.go