marcoallegretti/karapace
1
0
Fork 0
mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
karapace/docs/protocol-v1.md
Marco Allegretti 5306963cce docs: comprehensive public documentation 
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 18:38:41 +01:00

3.3 KiB
Raw Blame History

Karapace Remote Protocol v1 (Draft)

Status: v1-draft — This protocol is subject to change before 1.1.

Overview

The Karapace remote protocol defines how environments are transferred between local stores and a remote HTTP backend. It is a content-addressable blob store with an optional registry index for named references.

Blob Types

Kind Key Content
Object blake3 hex hash Raw object data (tar layers, manifests)
Layer layer hash JSON LayerManifest
Metadata env_id JSON EnvMetadata

HTTP Routes

All routes are relative to the remote base URL.

Blobs

Method Route Description
PUT /blobs/{kind}/{key} Upload a blob
GET /blobs/{kind}/{key} Download a blob
HEAD /blobs/{kind}/{key} Check if blob exists
GET /blobs/{kind} List blob keys

Registry

Method Route Description
PUT /registry Upload registry index
GET /registry Download registry index

Push Protocol

  1. Read local EnvMetadata for the target env_id.
  2. Collect layer hashes: base_layer + dependency_layers.
  3. For each layer, collect object_refs.
  4. Upload objects (skip if HEAD returns 200).
  5. Upload layer manifests (skip if HEAD returns 200).
  6. Upload metadata blob.
  7. If a registry tag is provided, download current registry, merge entry, upload updated registry.

Pull Protocol

  1. Download Metadata blob for the target env_id.
  2. Collect layer hashes from metadata.
  3. Download layer manifests (skip if local store has them).
  4. Collect object_refs from all layers.
  5. Download objects (skip if local store has them).
  6. Verify integrity: compute blake3 hash of each downloaded object; reject if hash does not match key.
  7. Store metadata locally.

Registry Format

{
  "entries": {
    "my-env@latest": {
      "env_id": "abc123...",
      "short_id": "abc123def456",
      "name": "my-env",
      "pushed_at": "2026-01-15T12:00:00Z"
    }
  }
}

Reference Resolution

References follow the format name@tag (default tag: latest). Resolution:

  1. Parse reference into (name, tag).
  2. Look up {name}@{tag} in the registry.
  3. Return the associated env_id.

Integrity

  • All objects are keyed by their blake3 hash.
  • On pull, every downloaded object is re-hashed and compared to its key.
  • Mismatches produce RemoteError::IntegrityFailure.
  • Layer manifests and metadata are JSON — no hash verification (they are keyed by logical identifiers, not content hashes).

Headers

Header Value When
Content-Type application/octet-stream Blob uploads/downloads
Content-Type application/json Registry uploads/downloads

Version Negotiation

Not yet implemented. The protocol version will be negotiated via a X-Karapace-Protocol header in 1.1.

Error Responses

Status Meaning
200 Success
404 Blob or registry not found
500 Server error

Security Considerations

  • No authentication in v1-draft. Authentication headers will be added in 1.1.
  • HTTPS is strongly recommended for all remote URLs.
  • Object integrity is verified client-side via blake3.