Add elfuse-oci pull into a local image store by henrybear327 · Pull Request #341 · sysprog21/elfuse

henrybear327 · 2026-08-29T01:12:29Z

Summary by cubic

Adds elfuse-oci, a Go CLI that pulls OCI images into a local store, keeping elfuse an OCI-agnostic runtime.

New Features

pull fetches an image via go-containerregistry into an OCI layout, pins it in index.json by canonical ref and platform, and refuses a legacy refs.json store.
A single flock serializes layout init and pin-table updates; the pin table is rewritten via a synced temp file and rename, so a crash can't publish a truncated table.
--timeout bounds the whole pull including the lock wait; a lock freed after the deadline is released, not used. --platform only accepts linux/arm64 and linux/amd64.
A bare manifest or index child that states no platform is pinned only when its config's platform matches; a child that is itself an index is refused.
Credentials come from Docker config inline auths or helpers, with the pull anonymous when no entry matches.
mk/oci.mk adds elfuse-oci, oci-test, and oci-lint targets; CI runs race tests and lint on Linux.
Documents the store, pull flow, and validation in docs/oci-images.md and the user guide.

^{Written for commit 1b858e2. Summary will update on new commits.}

henrybear327 · 2026-08-29T23:56:59Z

Final switch of the open source library after trying out different projects and attempting to make it maintainable in the long run

jserv · 2026-08-31T13:03:48Z

Use shorter and still meaningful paths. e.g., cmd/oci/.

jserv

Checked and found sound, recording them so they do not get re-raised: --timeout really does bound the lock wait plus the whole transfer, because the deadline context is built before withLock and remote.Get threads it into the descriptor; authn.DefaultKeychain propagates config-load and helper errors instead of silently going anonymous, so the anonymous path only triggers on a genuinely absent entry; and v1.Hash.parse rejects any non-hex body and any algorithm other than sha256, so no reference or digest can walk out of filepath.Join.

The store design itself reads well. The pin table as a nested index annotated with org.opencontainers.image.ref.name is the right data structure, and it keeps elfuse itself free of OCI knowledge.

jserv · 2026-08-31T13:07:07Z

+		if err != nil {
+			return v1.Descriptor{}, err
+		}
+		r, err := layer.Compressed()


A pull that fails partway leaves every layer already written in the store with nothing referencing it, and no subcommand removes it. Retry against a moved tag and the previous layers stay behind too, so the store grows without bound.

Either record what publishImage wrote and unwind on error, or land a prune subcommand and say so in docs/oci-images.md.

As we have agreed in the previous iteration that we would not be handling OCI image lifecycle, this is intentionally left to the clean command to deal with (it's in the subsequent PR). WDYT?

henrybear327 · 2026-08-31T19:45:29Z

Use shorter and still meaningful paths. e.g., cmd/oci/.

Renamed.

Publish canonical references and per-platform manifests through standard OCI indexes so layout readers can resolve the stored image. Use go-containerregistry for reference parsing and registry access.

Describe the OCI store, reference normalization, platform selection, credentials, timeouts, and pull validation. Add the command and environment surface to the user guide.

henrybear327 requested a review from jserv August 29, 2026 01:12

henrybear327 self-assigned this Aug 29, 2026