Documentation
¶
Overview ¶
Package weights orchestrates managed-weight operations: populating the local content-addressed store from a registry (Pull) and assembling per-invocation mount dirs (Prepare).
The Manager is the single entry point. CLI commands construct one and call it; no CLI surface constructs stores, fetches layers, or walks tars directly.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckDrift ¶ added in v0.19.3
func CheckDrift(projectDir string, weights []config.WeightSource) error
CheckDrift loads the lockfile from projectDir and compares it against the config's weight declarations. It returns a user-facing error if any drift is detected, telling the user to run "cog weights import".
Returns nil when weights is empty, when config and lockfile agree, or when the lockfile is missing and there are no config weights.
Types ¶
type Manager ¶ added in v0.19.3
type Manager struct {
// contains filtered or unexported fields
}
Manager orchestrates managed-weight operations against a local content-addressed store and a remote OCI registry.
func NewFromSource ¶ added in v0.19.3
NewFromSource constructs a Manager from a model.Source and an already-parsed repository string. Callers (typically CLI commands) are responsible for parsing their `--image` flag / `cog.yaml image:` value into a bare repo before calling.
repo may be empty for models that declare no weights — the returned Manager is a valid no-op in that case, so CLI callers can construct one unconditionally and let Pull/Prepare decide if there's anything to do.
Missing lockfiles error out with an actionable message pointing at `cog weights import` when the model actually has weights.
func NewManager ¶ added in v0.19.3
func NewManager(opts ManagerOptions) (*Manager, error)
func (*Manager) Prepare ¶ added in v0.19.3
Prepare assembles per-invocation mount directories for every weight in the lockfile. Each weight gets its own directory populated by hardlinking blobs from the local store.
If any file is missing from the store, Prepare returns an error directing the user at `cog weights pull`. v1 does NOT auto-pull.
Hardlinks require the store and project dir to share a filesystem. On EXDEV, Prepare returns a clear error pointing at COG_CACHE_DIR; silent copy/symlink fallbacks would defeat the zero-duplication property.
On any failure the partially-assembled invocation dir is removed before returning.
func (*Manager) ProjectDir ¶ added in v0.19.3
ProjectDir returns the project directory configured on the Manager. Primarily useful for tests and for CLI code that wants to log where mounts will live.
func (*Manager) Pull ¶ added in v0.19.3
func (m *Manager) Pull(ctx context.Context, names []string, onEvent func(PullEvent)) ([]PullResult, error)
Pull populates the local store with every file referenced by the lockfile for the named weights. Empty names means "all weights".
Behavior:
- Files already present locally are skipped (no registry I/O).
- A layer is fetched only if at least one of its files is missing. The whole layer must be streamed to reach any one file, so we store every expected file the layer contains — PutFile is idempotent so pre-cached files drain through without rewrites.
- Registry is authoritative. v1 does not fall back to the source URI; re-run `cog weights import` if the registry is missing a layer.
- Every file path in the tar must be in the lockfile. Unexpected paths error out.
onEvent, if non-nil, is called synchronously with each PullEvent.
type ManagerOptions ¶ added in v0.19.3
type ManagerOptions struct {
Store store.Store
Registry registry.Client
Repo string
Lock *lockfile.WeightsLock
ProjectDir string
}
ManagerOptions is the argument struct for NewManager.
Store and Registry are always required. Lock, Repo, and ProjectDir are required only if the model has weights — a Manager constructed with a nil or empty Lock is a valid no-op, so callers don't need to branch on "does cog.yaml declare weights?" before constructing one.
type MountSpec ¶ added in v0.19.3
MountSpec describes one bind mount from host to container. Managed- weight mounts are always read-only; callers set ReadOnly on their container runtime's volume type unconditionally.
type Mounts ¶ added in v0.19.3
type Mounts struct {
Specs []MountSpec
// contains filtered or unexported fields
}
Mounts is the handle returned from Prepare. It owns a per-invocation scratch directory under <projectDir>/.cog/mounts and MUST be released — either via Release or by the caller noticing the context was canceled.
type PullEvent ¶ added in v0.19.3
type PullEvent struct {
// Kind identifies which fields below are populated.
Kind PullEventKind
// Weight is set on every event.
Weight string
// WeightStart: summary of what's about to happen for the weight.
// ManifestRef is set only when MissingFiles > 0 (fully-cached
// weights need no registry round trip).
Target string
TotalFiles int
MissingFiles int
ManifestRef string
// LayerStart / LayerDone / FileStored: layer context.
// LayerSize is 0 when the backing layer does not expose a size
// (in-memory test layers).
LayerDigest string
LayerSize int64
// FileStored: per-file detail for a file just written to the store.
FilePath string
FileDigest string
FileSize int64
// WeightDone: cumulative totals for the weight. FullyCached is
// true when no registry I/O happened.
BytesFetched int64
FilesFetched int
LayersFetched int
FullyCached bool
}
PullEvent is emitted during Pull to drive progress output. Delivered on the calling goroutine in order; handlers MUST NOT block.
Fields are populated per Kind — see each kind's comment.
type PullEventKind ¶ added in v0.19.3
type PullEventKind int
const ( // PullEventUnknown is the zero value so that a freshly-constructed // PullEvent{} is distinguishable from a legitimate event. PullEventUnknown PullEventKind = iota PullEventWeightStart PullEventLayerStart PullEventFileStored PullEventLayerDone PullEventWeightDone )
type PullResult ¶ added in v0.19.3
type PullResult struct {
Name string
FullyCached bool
FilesFetched int
BytesFetched int64
LayersFetched int
}
PullResult summarizes what happened for a single weight during Pull. Returned in the same order as the input names (or lockfile order when names is empty).
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package lockfile defines the on-disk weights.lock format and operations on it: parsing, loading, canonical serialization, and entry-level equality checks.
|
Package lockfile defines the on-disk weights.lock format and operations on it: parsing, loading, canonical serialization, and entry-level equality checks. |
|
Package store defines a narrow, content-addressed interface for storing individual weight files on the local machine.
|
Package store defines a narrow, content-addressed interface for storing individual weight files on the local machine. |