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 ¶
var ErrInvalidBase64 = errors.New("attachment: image upload is not canonical base64")
ErrInvalidBase64 indicates an empty or noncanonical base64 payload.
Functions ¶
func DecodeCanonicalBase64 ¶
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 ¶
func (s *FileBackedStore) ReadImage(ref ImageAttachmentRef) (StoredImageAttachment, error)
ReadImage reads bytes and verifies that they match the recorded reference.
func (*FileBackedStore) SaveImage ¶
func (s *FileBackedStore) SaveImage(input SaveImageAttachment) (ImageAttachmentRef, error)
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 ¶
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) Run ¶
func (l *Limiter) Run(task func())
Run acquires a slot and releases it after task completes, including on failure.
func (*Limiter) TryAcquire ¶
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.