pack

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultMaxPackageSize int64 = 100 * 1024 * 1024  // 100MB
	DefaultCacheTTL             = 7 * 24 * time.Hour // 7 days
)
View Source 
const (
	Extension    = ".zip"
	ManifestFile = "manifest.toml"
	LibDir       = "lib"
	DocsDir      = "docs"
)
View Source 
const PackageLibraryName = "scriptling.package"

Variables

View Source 
var (
	ErrInvalidPackage  = errors.New("invalid package format")
	ErrMissingManifest = errors.New("missing manifest.toml")
	ErrInvalidManifest = errors.New("invalid manifest format")
	ErrModuleNotFound  = errors.New("module not found in package")
	ErrFetchFailed     = errors.New("failed to fetch package")
)
View Source 
var ErrUnknownScheme = errors.New("no plugin provides the source scheme")

ErrUnknownScheme reports a source that looks like <scheme>://… but whose scheme has no registered opener — almost always a fetcher plugin that was never loaded. Callers match on it to add context only they can supply, such as the flags or configuration that load a plugin in their environment.

Functions

func ClearCache 

func ClearCache(cacheDir string) error

ClearCache removes all cached packages from cacheDir. If cacheDir is empty, uses the OS default cache directory.

func DefaultCacheDir 

func DefaultCacheDir() (string, error)

DefaultCacheDir returns the default cache directory for packages.

func Fetch 

func Fetch(source string, insecure bool) ([]byte, error)

Fetch loads bytes from a URL or local path. For URLs, uses the cache with ETag/Last-Modified freshness checks.

func FetchFile 

func FetchFile(path string, maxSize ...int64) ([]byte, error)

FetchFile loads from local filesystem.

func FetchWithCache 

func FetchWithCache(source string, insecure bool, cacheDir string, maxSize ...int64) ([]byte, error)

FetchWithCache loads bytes from a URL or local path, using cacheDir for remote URLs. If cacheDir is empty, uses the OS default cache directory. An optional #sha256=<hex> fragment on source is stripped before fetching and used to verify the downloaded bytes; a mismatch is a fatal error. maxSize limits download size (0 = use DefaultMaxPackageSize).

func HashBytes 

func HashBytes(data []byte) string

HashBytes returns the SHA-256 hex digest of data.

func IsURL 

func IsURL(source string) bool

IsURL returns true if source starts with http:// or https://.

func NewPackageLibrary added in v0.19.0 

func NewPackageLibrary(loader *Loader) *object.Library

NewPackageLibrary builds the scriptling.package library bound to the given loader. Exposed so embedders and tests can register it on a custom registrar or inspect it directly.

func Pack 

func Pack(srcDir, dst string, force bool) (string, []string, error)

Pack creates a package from srcDir, writing to dst. Use force to overwrite an existing dst. Returns the SHA-256 hex hash of the written package and a list of warnings for skipped files.

Inclusion is manifest-driven: manifest.toml, every dir in libs, the main script file (when main names a .py file), and the convention dirs (tools/, resources/, prompts/, webroot/, docs/) when present. Dotfiles are skipped silently; anything else at the top level produces a warning.

A libs dir listed in the manifest but missing, or a main script file that does not exist, is a build error.

func PruneCache 

func PruneCache(cacheDir string, ttl time.Duration) error

PruneCache removes cache entries that have not been accessed within ttl. If cacheDir is empty, uses the OS default cache directory. If ttl is 0, uses DefaultCacheTTL. Each cache entry is a .zip/.meta pair; the .zip mod time tracks last access. Plugin-served content never appears here — it is held in memory only — so there is nothing per-file to prune. Stale .pfile pairs written by an earlier build are cleaned up too.

func RegisterPackageLibrary added in v0.18.0 

func RegisterPackageLibrary(p interface{ RegisterLibrary(*object.Library) }, loader *Loader)

RegisterPackageLibrary registers the scriptling.package library on the given Scriptling instance. Convenience wrapper around NewPackageLibrary.

func SchemeSyntax added in v0.23.0 

func SchemeSyntax(source string) (string, bool)

SchemeSyntax reports whether source looks like a custom <scheme>://rest source, regardless of whether any opener is registered for it. It returns ("", false) for http(s) URLs (owned by FetchBundle), local paths, and malformed sources. Callers use it to tell a missing plugin apart from a missing file.

func Unpack 

func Unpack(src string, opts UnpackOptions) error

Unpack extracts a package from a local path or URL.

func UnpackRemove 

func UnpackRemove(src string, insecure bool, destDir string) error

UnpackRemove removes the files that would be extracted from a package.

Types

type Bundle added in v0.18.0 

type Bundle struct {
	Manifest Manifest
	// contains filtered or unexported fields
}

Bundle is an application bundle: a manifest plus an fs.FS over the bundle contents. Two equivalent backends exist — a development folder on disk (os.DirFS) and a built .zip artifact (zipFS). Both read entirely on demand; no file content is held in memory between calls except the manifest.

func FetchBundle added in v0.18.0 

func FetchBundle(source string, insecure bool, cacheDir string) (*Bundle, error)

FetchBundle opens a bundle from a local directory, a local .zip, a remote .zip URL (fetched with caching; source may include a #sha256=<hex> fragment), or a custom <scheme>:// source routed through the process-wide default scheme registry (see RegisterScheme — typically a fetcher plugin serving files on demand). A scheme-shaped source whose scheme has no opener is an error naming the missing plugin, not a missing-file error.

Hosts with their own SchemeRegistry call SchemeRegistry.FetchBundle instead.

func OpenBundle added in v0.18.0 

func OpenBundle(fsys fs.FS, source string) (*Bundle, error)

OpenBundle wraps an existing fs.FS as a bundle, reading and validating its manifest.

func OpenBundleDir added in v0.18.0 

func OpenBundleDir(dir string) (*Bundle, error)

OpenBundleDir opens a development folder (containing manifest.toml) as a bundle.

func OpenBundleZip added in v0.18.0 

func OpenBundleZip(r io.ReaderAt, size int64, source string) (*Bundle, error)

OpenBundleZip opens a built .zip artifact as a bundle. File content is read on demand from the zip — nothing is decompressed into memory at open time except the manifest.

func VirtualBundle added in v0.23.0 

func VirtualBundle(name, version string, fsys fs.FS, source string) *Bundle

VirtualBundle wraps an fs.FS as a bundle with an explicitly supplied manifest — for sources with no manifest.toml of their own, such as a fetcher plugin's library (the host synthesizes the standard layout).

func (*Bundle) FS added in v0.18.0 

func (b *Bundle) FS() fs.FS

FS returns the bundle's file system.

func (*Bundle) ReadFile added in v0.18.0 

func (b *Bundle) ReadFile(name string) ([]byte, error)

ReadFile reads a file from the bundle by slash path.

func (*Bundle) Source added in v0.18.0 

func (b *Bundle) Source() string

Source returns a display name for the bundle origin.

func (*Bundle) Sub added in v0.18.0 

func (b *Bundle) Sub(dir string) (fs.FS, bool)

Sub returns the fs.FS rooted at dir within the bundle, and whether that dir exists.

type DirDocReader 

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

DirDocReader reads docs from an unpacked package directory.

func NewDirDocReader 

func NewDirDocReader(dir string) *DirDocReader

NewDirDocReader creates a DocReader for an unpacked package directory.

func (*DirDocReader) ListDocs 

func (r *DirDocReader) ListDocs() []string

func (*DirDocReader) Name 

func (r *DirDocReader) Name() string

func (*DirDocReader) ReadDoc 

func (r *DirDocReader) ReadDoc(name string) ([]byte, error)

type DocReader 

type DocReader interface {
	// Name returns a display name for this source.
	Name() string
	// ListDocs returns all doc file paths relative to docs/ (e.g. "guide.md").
	ListDocs() []string
	// ReadDoc reads a doc file by its relative path.
	ReadDoc(name string) ([]byte, error)
}

DocReader provides access to docs/ content from a package source.

type Loader 

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

Loader implements libloader.LibraryLoader over a set of bundles. Bundles are searched in reverse order (last added = highest priority); within a bundle, each manifest libs dir is searched in declared order.

func NewLoader 

func NewLoader() *Loader

NewLoader creates a new Loader.

func (*Loader) AddBundle added in v0.18.0 

func (l *Loader) AddBundle(b *Bundle) error

AddBundle adds a bundle to the loader. Returns an error if a bundle with the same manifest name is already loaded.

func (*Loader) AddFromPath 

func (l *Loader) AddFromPath(source string, insecure bool) error

AddFromPath loads a bundle from a local directory, a local .zip, or a URL. source may include a #sha256=<hex> fragment for integrity verification.

func (*Loader) BundleByName added in v0.18.0 

func (l *Loader) BundleByName(name string) *Bundle

BundleByName returns the bundle with the given manifest name, or nil.

func (*Loader) BundleNames added in v0.18.0 

func (l *Loader) BundleNames() []string

BundleNames returns the manifest names of all loaded bundles.

func (*Loader) Bundles added in v0.18.0 

func (l *Loader) Bundles() []*Bundle

Bundles returns the bundles added to the loader, in add order.

func (*Loader) Description 

func (l *Loader) Description() string

Description implements libloader.LibraryLoader.

func (*Loader) Load 

func (l *Loader) Load(name string) (string, bool, error)

Load implements libloader.LibraryLoader. Searches bundles in reverse order (last = highest priority), then fallback. A bundle whose storage fails (a fetcher plugin that cannot be reached, say) aborts the search with that error — only a plain not-found continues past a bundle, so an unreachable source is reported instead of silently skipping its modules.

func (*Loader) LoadWithContext added in v0.23.0 

func (l *Loader) LoadWithContext(ctx context.Context, name string) (string, bool, error)

LoadWithContext preserves caller context through context-aware fallbacks and observes cancellation between bundle probes. Bundle storage uses fs.FS, whose ReadFile contract has no per-call context.

func (*Loader) ResolveMain added in v0.18.0 

func (l *Loader) ResolveMain() (entry MainEntry, found bool, err error)

ResolveMain determines the main entry point of the last bundle that declares one, using lookup-order resolution: a main ending in .py that exists as a file in the bundle is a script; otherwise main is treated as module.function. found is false when no bundle declares main; an error is returned when main is declared but unresolvable.

func (*Loader) SetCacheDir 

func (l *Loader) SetCacheDir(dir string)

SetCacheDir overrides the default OS cache directory for remote packages.

func (*Loader) SetFallback 

func (l *Loader) SetFallback(fallback libloader.LibraryLoader)

SetFallback sets the fallback loader used when no bundle provides the module.

type MainEntry added in v0.18.0 

type MainEntry struct {
	// Script is the content of a .py file within the bundle, run as top-level
	// code. Set when main ends in .py and the file exists.
	Script []byte
	// ScriptName is the slash path of the script within the bundle (for error
	// messages).
	ScriptName string
	// Module and Function name the module.function entry point, used when
	// Script is nil.
	Module   string
	Function string
}

MainEntry describes a bundle's resolved main entry point.

type Manifest 

type Manifest struct {
	Name            string   `toml:"name"`
	Version         string   `toml:"version"`
	Description     string   `toml:"description,omitempty"`
	Main            string   `toml:"main,omitempty"`             // module.function entry point, or a .py script path within the bundle
	Libs            []string `toml:"libs,omitempty"`             // module search dirs inside the bundle (default ["lib"])
	Serve           []string `toml:"serve,omitempty"`            // protocols to start: "http", "mcp", "json-rpc"
	AdditionalFiles []string `toml:"additional_files,omitempty"` // extra files/dirs to include (dir ends with /)
}

Manifest describes package metadata.

func ReadManifestFromDir 

func ReadManifestFromDir(dir string) (Manifest, error)

ReadManifestFromDir reads manifest.toml from a source directory.

func (Manifest) LibDirs added in v0.18.0 

func (m Manifest) LibDirs() []string

LibDirs returns the manifest's module search dirs, defaulting to ["lib"].

type Package 

type Package struct {
	Manifest Manifest
	// contains filtered or unexported fields
}

Package represents a loaded package. All file contents are decompressed into memory at Open time. docs/ entries are intentionally excluded; use ZipDocReader for those.

func Open 

func Open(r io.ReaderAt, size int64) (*Package, error)

func OpenFile 

func OpenFile(path string) (*Package, error)

OpenFile opens a package from a local file path.

func OpenURL 

func OpenURL(url string, insecure bool) (*Package, error)

OpenURL opens a package from a URL.

func (*Package) HasDocs 

func (p *Package) HasDocs() bool

HasDocs returns true if the package contains a docs folder. Since docs/ is not loaded into p.files, we track this separately.

func (*Package) List 

func (p *Package) List(dir string) []string

List returns file names under a directory prefix within the package.

func (*Package) ReadFile 

func (p *Package) ReadFile(name string) ([]byte, error)

ReadFile reads a file from the package by path.

type SchemeOpener added in v0.23.0 

type SchemeOpener func(source string, insecure bool, cacheDir string) (*Bundle, error)

SchemeOpener opens a bundle from a source using the registered scheme. The signature matches FetchBundle so openers compose with every existing caller. Openers that need a context capture one at registration; see pluginpack.Bridge.

type SchemeRegistry added in v0.23.0 

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

SchemeRegistry maps custom source schemes to bundle openers. It is safe for concurrent use. The zero value is not usable; call NewSchemeRegistry.

func DefaultSchemeRegistry added in v0.23.0 

func DefaultSchemeRegistry() *SchemeRegistry

DefaultSchemeRegistry returns the process-wide registry that FetchBundle and the package-level Register/Unregister functions use.

func NewSchemeRegistry added in v0.23.0 

func NewSchemeRegistry() *SchemeRegistry

NewSchemeRegistry returns an empty scheme registry.

func (*SchemeRegistry) FetchBundle added in v0.23.0 

func (r *SchemeRegistry) FetchBundle(source string, insecure bool, cacheDir string) (*Bundle, error)

FetchBundle opens source through this registry's openers, falling back to the built-in directory / zip / URL handling for non-scheme sources.

func (*SchemeRegistry) Lookup added in v0.23.0 

func (r *SchemeRegistry) Lookup(scheme string) SchemeOpener

Lookup returns the opener for a scheme, or nil when it is not registered.

func (*SchemeRegistry) Register added in v0.23.0 

func (r *SchemeRegistry) Register(scheme string, opener SchemeOpener) error

Register routes sources with the given scheme to opener. Registering a scheme twice, or a built-in (http, https, file), is an error — one scheme has one owner. Use Unregister to release it first.

func (*SchemeRegistry) Registered added in v0.23.0 

func (r *SchemeRegistry) Registered() []string

Registered returns the registered custom schemes in sorted order.

func (*SchemeRegistry) Unregister added in v0.23.0 

func (r *SchemeRegistry) Unregister(scheme string) bool

Unregister releases a scheme so it can be claimed again, and reports whether it was registered. Hosts that reload plugins call this on teardown.

type UnpackOptions 

type UnpackOptions struct {
	DestDir  string
	Force    bool
	List     bool
	Insecure bool
}

UnpackOptions configures extraction behaviour.

type ZipDocReader 

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

ZipDocReader reads docs from a zip package file.

func NewZipDocReader 

func NewZipDocReader(src string, insecure bool) (*ZipDocReader, error)

NewZipDocReader opens a zip and extracts only the docs/ entries.

func (*ZipDocReader) ListDocs 

func (r *ZipDocReader) ListDocs() []string

func (*ZipDocReader) Name 

func (r *ZipDocReader) Name() string

func (*ZipDocReader) ReadDoc 

func (r *ZipDocReader) ReadDoc(name string) ([]byte, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.