blob

Documentation

Overview

Package blob is the platform's object-storage seam: opaque bytes at string keys, behind the one interface every backend must satisfy (CLAUDE.md: backend variability lives behind an interface with one shared contract suite — internal/blob/blobtest). The first consumer is the skills registry (docs/plan/06_skills.md), which stores canonical skill-version archives at `skills/{skill_id}/{version}.zip`; the key namespace deliberately leaves room for later surfaces (the deferred Files API) to share the store.

Index

• Constants
• Variables
• func FilesKey(id string) string
• func SessionCheckpointKey(sessionID string) string
• type Store
  • func WithMetrics(s Store) Store

Constants

const (
	MetricOpDuration = "blob.op.duration"
	MetricOpBytes    = "blob.op.bytes"
)

MetricOpDuration and MetricOpBytes are platform-native names (dotted, lowercase, unit in the Unit field) recorded at the Store seam, so every backend and every consumer shares one view of object-storage health. Exported so the telemetry contract test can assert they reach a collector.

Variables

var ErrNotFound = errors.New("blob: object not found")

ErrNotFound reports a Get of a key that has no object. Implementations wrap it so callers can errors.Is across backends.

Functions

func FilesKey

func FilesKey(id string) string

FilesKey is the object-storage key for a Files-API file's bytes — the `files/{file_id}` namespace this package's doc reserves. It lives here, not in a feature package (unlike skills' own BlobKey), because it has no home package: the api registry that writes the object and the executor/worker that stream it into sandboxes all import blob, so one definition keeps the layout from drifting between the writer and its readers.

func SessionCheckpointKey

func SessionCheckpointKey(sessionID string) string

SessionCheckpointKey is the object-storage key for a session's workspace checkpoint — the `workspace/{session_id}/checkpoint.tar.gz` layout plan 24 fixes. It lives here for FilesKey's reason: the executor writes it (the idle-TTL capture), the executor's reaper and the API's session delete both remove it, and one definition keeps the writer and its removers from drifting.

Types

type Store

type Store interface {
	// Put stores exactly size bytes from r at key, overwriting any existing
	// object: a reader with fewer bytes than size is an error, and bytes
	// beyond size are never read. contentType is stored as object metadata
	// for HTTP consumers.
	Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) error

	// Get returns the object's bytes and size. A missing key is ErrNotFound
	// from Get itself, never deferred to the first Read. The caller closes
	// the reader.
	Get(ctx context.Context, key string) (io.ReadCloser, int64, error)

	// Delete removes the object at key. Deleting a missing key is not an
	// error: a crashed-and-retried delete must converge, not flap.
	Delete(ctx context.Context, key string) error
}

Store is the object-storage contract. Keys are opaque non-empty strings; "/" separators are conventional namespacing, not directories.

func WithMetrics

func WithMetrics(s Store) Store

WithMetrics wraps a Store so every operation records its duration (by op and outcome) and payload size (by op). Get's duration covers the call that opens the object, not the caller's subsequent reads.