feat: add Inspect() method to fetch archive metadata without data blob

[jmgilman]

Summary

• Adds Client.Inspect() to fetch manifest and file index without downloading the data blob
• Enables archive introspection with minimal network transfer (manifest + small index blob only)
• Provides lazy access to referrers (signatures, attestations) via InspectResult.Referrers()

New Types

InspectResult

Contains manifest, index, and computed statistics:

• Manifest(), Index(), Digest(), Created()
• FileCount(), DataBlobSize(), IndexBlobSize()
• TotalUncompressedSize(), TotalCompressedSize(), CompressionRatio() (computed lazily)
• Referrers(ctx, artifactType) for fetching signatures/attestations

IndexView

Read-only access to file metadata without the data blob:

• Len(), Version(), DataHash(), DataSize()
• Entry(path), Entries(), EntriesWithPrefix(prefix)

Referrer

Describes referrer artifacts:

• Digest, Size, MediaType, ArtifactType, Annotations

Options

• InspectWithSkipCache() - Bypass all caches
• InspectWithMaxIndexSize(size) - Limit index blob size

Example Usage

result, err := c.Inspect(ctx, "ghcr.io/myorg/myarchive:v1.0.0")
if err != nil {
    return err
}

fmt.Printf("Files: %d\n", result.FileCount())
fmt.Printf("Compression ratio: %.2f\n", result.CompressionRatio())

// List files without downloading data
for entry := range result.Index().Entries() {
    fmt.Printf("  %s (%d bytes)\n", entry.Path(), entry.OriginalSize())
}

// Fetch signatures (lazy, on-demand)
referrers, _ := result.Referrers(ctx, "")

Files Changed

New files:

• inspect.go - Public InspectResult and Client.Inspect()
• referrer.go - Referrer type
• core/index_view.go - IndexView type
• registry/inspect.go - Registry-layer implementation
• registry/inspect_opts.go - Inspect options
• registry/inspect_test.go - Registry layer tests
• registry/testing.go - Test helpers
• inspect_test.go - Blob layer tests

Modified files:

• types.go - Added IndexView re-export
• core/testutil/index.go - Added MakeMinimalIndex() helper

Documentation:

• docs/docs/reference/api.md - Added Inspect, InspectResult, IndexView, Referrer
• docs/docs/getting-started.md - Added Step 4: Inspect Archive Metadata
• docs/docs/guides/oci-client.md - Added Inspect Operations section

Test plan

• All existing tests pass (just ci)
• New unit tests for registry layer (registry/inspect_test.go)
• New unit tests for blob layer (inspect_test.go)
• Manual testing with a real registry

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	blob	309f474	Commit Preview URL Branch Preview URL	Jan 20 2026, 03:51 AM