attachment

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Upload admission matches attachment/admission: base64 must round-trip to the identical encoding so alternate representations cannot bypass validation.

Package attachment implements durable image references (M29), matching packages/attachment/attachment. Producers supply validated encoded bytes; an immutable, content-addressed AttachmentID is published only after storage.

Session events and model-visible ImageBlocks contain references and metadata, never browser object URLs, temporary host paths, provider URLs, or base64 data. AttachmentID is opaque: consumers must use Store.ReadImage rather than parse the ID or derive a filesystem path from it. The store is retention-neutral, so resumed and forked sessions can share objects across compaction.

The attachment-local/compression-limiter contract uses a per-instance FIFO limit on concurrent native image transformations; excess work waits for a slot.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidBase64 = errors.New("attachment: image upload is not canonical base64")

ErrInvalidBase64 indicates an empty or noncanonical base64 payload.

Functions

func DecodeCanonicalBase64

func DecodeCanonicalBase64(data string) ([]byte, error)

DecodeCanonicalBase64 decodes canonical base64 or returns ErrInvalidBase64.

Types

type AttachmentID

type AttachmentID = brand.AttachmentID

AttachmentID is an opaque durable identifier aliased from pkg/brand.

type FileBackedStore

type FileBackedStore struct {
	// contains filtered or unexported fields
}

FileBackedStore implements content-addressed attachment storage. The primary map stores IDs and bytes; an optional directory also persists objects at <dir>/<digest> for cross-session, resume, and fork resolution. IDs use sha256:<hex(digest)> and reads recompute the digest to detect drift. Image dimensions are not forcibly parsed; admission checks media signatures.

func NewStore

func NewStore(dir string) *FileBackedStore

NewStore creates storage, enabling the host file backend when dir is nonempty.

func (*FileBackedStore) ImageHostPath

func (s *FileBackedStore) ImageHostPath(ref ImageAttachmentRef) (string, bool)

ImageHostPath returns the host object path in directory mode, or false.

func (*FileBackedStore) ReadImage

ReadImage reads bytes and verifies that they match the recorded reference.

func (*FileBackedStore) SaveImage

SaveImage validates and persists an image, returning its content-addressed reference.

type ImageAttachmentRef

type ImageAttachmentRef struct {
	// AttachmentID is the content-addressed ID (sha256:<digest>).
	AttachmentID AttachmentID `json:"attachmentId"`
	// MediaType is verified against the stored bytes.
	MediaType ImageMediaType `json:"mediaType"`
	// Bytes is the exact encoded byte length.
	Bytes int `json:"bytes"`
	// Width is the encoded width in pixels.
	Width int `json:"width,omitempty"`
	// Height is the encoded height in pixels.
	Height int `json:"height,omitempty"`
	// Name is an optional display name with local path information removed.
	Name string `json:"name,omitempty"`
}

ImageAttachmentRef is a durable, serializable reference to an immutable normalized image. It is an opaque storage identifier, never a path or URL.

type ImageMediaType

type ImageMediaType string

ImageMediaType identifies an image format accepted by v1 attachments.

const (
	MediaPNG  ImageMediaType = "image/png"
	MediaJPEG ImageMediaType = "image/jpeg"
	MediaWebP ImageMediaType = "image/webp"
	MediaGIF  ImageMediaType = "image/gif"
)

Supported image media types.

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

Limiter is a FIFO concurrency limiter.

func NewLimiter

func NewLimiter(concurrency int) *Limiter

NewLimiter creates a limiter; nonpositive concurrency defaults to one.

func (*Limiter) Acquire

func (l *Limiter) Acquire()

Acquire waits for a slot, which must be returned with Release.

func (*Limiter) Active

func (l *Limiter) Active() int

Active returns the number of occupied slots.

func (*Limiter) Release

func (l *Limiter) Release()

Release returns a slot.

func (*Limiter) Run

func (l *Limiter) Run(task func())

Run acquires a slot and releases it after task completes, including on failure.

func (*Limiter) TryAcquire

func (l *Limiter) TryAcquire() bool

TryAcquire attempts to acquire a slot without blocking.

type SaveImageAttachment

type SaveImageAttachment struct {
	// Data contains encoded image bytes.
	Data []byte
	// MediaType is the caller-declared type checked against the decoded bytes.
	MediaType ImageMediaType
	// Name is an optional display name, never interpreted as a path.
	Name string
	// Width and Height are optional intrinsic dimensions; zero means unspecified.
	Width  int
	Height int
}

SaveImageAttachment describes an image submission.

type Store

type Store interface {
	// SaveImage validates and persists an image, returning a content-addressed reference.
	SaveImage(input SaveImageAttachment) (ImageAttachmentRef, error)
	// ReadImage reads an image and verifies that its bytes still match the reference.
	ReadImage(ref ImageAttachmentRef) (StoredImageAttachment, error)
	// ImageHostPath returns the provider-owned host path, or false without a file backend.
	ImageHostPath(ref ImageAttachmentRef) (string, bool)
}

Store provides immutable binary attachments (ctx.attachments).

type StoredImageAttachment

type StoredImageAttachment struct {
	Ref  ImageAttachmentRef `json:"ref"`
	Data []byte             `json:"data"`
}

StoredImageAttachment contains bytes and a reference verified by digest.

func ResolveFileBacked

func ResolveFileBacked(dir string, ref ImageAttachmentRef) (StoredImageAttachment, error)

ResolveFileBacked reads <dir>/<digest> when only a host directory is available.

func ResolveReference

func ResolveReference(store Store, ref ImageAttachmentRef) (StoredImageAttachment, error)

ResolveReference resolves authoritative bytes from a session attachment reference. It uses Store.ReadImage and digest verification when a store is supplied, otherwise the host file backend; unavailable resolution returns an error. Content-addressed references remain valid across compaction and sessions as long as the object remains in the store or host backend.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL