ORAS Client for Pony and Ponyup Integration

[SeanTAllen]

This is a pretty significant undertaking with two distinct pieces: the ORAS client library itself, and the ponyup integration. Here's what each involves.

ORAS Client Library

ORAS is built on the OCI Distribution Spec, which is an HTTP API. The core operations ponyup would need are pull-side only — push would be handled by CI.

HTTP API surface to implement

• Token auth flow — registries return 401 with a WWW-Authenticate header pointing to a token endpoint. You request a token (anonymous for public repos), then retry with Authorization: Bearer <token>. This is the fiddliest part — every registry has slightly different behavior around token scopes and expiry.
• Tag listing — GET /v2/<name>/tags/list — needed for version/channel resolution (replaces Cloudsmith queries)
• Manifest pull — GET /v2/<name>/manifests/<reference> — returns either an Image Index (multi-platform) or an Image Manifest. Need to send the right Accept headers.
• Blob pull — GET /v2/<name>/blobs/<digest> — the actual artifact bytes. Registries often return 307 redirects to CDN URLs.

Types to model

• OCI Descriptor — (mediaType, digest, size, annotations) — the universal building block
• OCI Image Index — list of platform-specific manifest descriptors, each tagged with (os, architecture). This is how multi-platform works — you resolve the current platform to the right child manifest.
• OCI Image Manifest — config descriptor + layer descriptors. For ORAS artifacts, the layers contain your actual files.
• ORAS-specific media types — ORAS uses custom media types on layers to distinguish artifact kinds (e.g., application/vnd.unknown.layer.v1+tar+gzip or something project-specific)

Crypto dependency

OCI digests are sha256:<hex>. Every blob and manifest must be verified against its digest after download. Pony stdlib doesn't have SHA256, but since ponyup already links OpenSSL, you could FFI to EVP_Digest or the SHA256() convenience function. Alternatively, this could be a standalone ponylang/crypto or similar lib.

Existing building blocks in Pony ecosystem

• courier — HTTP client (already a ponyup dep)
• stdlib json — manifest/response parsing
• SSL — already linked

What doesn't exist and would need to be built from scratch

• SHA256 digest computation and verification
• The OCI type model and manifest parsing
• The auth/token negotiation flow
• Blob streaming with digest verification
• Redirect following for blob downloads (need to check if courier handles 307s)

Ponyup Integration

What changes

• Cloudsmith primitive gets replaced (or supplemented) by an OCI registry backend
• Version resolution changes from Cloudsmith API queries to tag listing + manifest resolution
• Platform resolution moves from Cloudsmith metadata to OCI Image Index platform descriptors — the mapping from ponyup's (CPU, OS, Distro) to OCI's (os, architecture) is straightforward for os/arch but distro variants would need to go in annotations or tag conventions
• Download flow changes: resolve tag → pull index → match platform → pull manifest → pull blob(s) → verify digest → extract
• Checksum verification is "free" — OCI has digests built in, unlike Cloudsmith where it's a separate API field

What stays the same

• CLI interface
• LockFile / selection system
• Archive extraction (still tar.gz at the end)
• The Ponyup actor orchestration shape (query → download → verify → extract → update lockfile)

CI/infrastructure side (not Pony code, but required)

• Artifacts need to be pushed to an OCI registry. GHCR (ghcr.io) is the natural choice since ponylang is already on GitHub. CI would use the oras CLI or docker push equivalent.
• Tag naming convention needs design — encoding version, channel (release/nightly), and possibly distro into tags or manifest annotations
• All the existing ponylang tools (ponyc, corral, changelog-tool, etc.) would need their CI updated

Sizing

The ORAS client library is the bulk of the work. The OCI Distribution Spec is well-documented but has enough registry-specific quirks (especially around auth) that testing against real registries matters. The manifest/type model is straightforward. The digest verification needs the SHA256 FFI work.

The library is a medium-sized project and the ponyup integration is smaller — mostly swapping out the Cloudsmith backend while keeping the same overall flow.

The biggest open question is probably where the SHA256 implementation lives — inline FFI in the ORAS lib, or a separate reusable crypto package.