imageasset

Documentation

Overview

Package imageasset validates and privately stores image inputs before they cross into UI or provider-specific message code.

Stored objects are addressed by their complete SHA-256 digest. References deliberately retain only bounded display metadata and never the source path.

Index

• Variables
• type Limits
  • func DefaultLimits() Limits
• type Ref
  • func (r Ref) Handle() string
  • func (r Ref) Validate() error
• type Store
  • func NewStore(root string, limits Limits) (*Store, error)
  • func (s *Store) AdmitBytes(ctx context.Context, displayName string, data []byte) (Ref, error)
  • func (s *Store) AdmitBytesChecked(ctx context.Context, displayName string, data []byte, check func(Ref) error) (Ref, error)
  • func (s *Store) AdmitFile(ctx context.Context, path string) (Ref, error)
  • func (s *Store) AdmitFileChecked(ctx context.Context, path string, check func(Ref) error) (Ref, error)
  • func (s *Store) Load(ctx context.Context, ref Ref) ([]byte, error)

Variables

var (
	ErrUnsupportedFormat = errors.New("unsupported image format")
	ErrInvalidDimensions = errors.New("invalid image dimensions")
	ErrIntegrity         = errors.New("image object integrity check failed")
	ErrInvalidReference  = errors.New("invalid image object reference")
)

Types

type Limits

type Limits struct {
	MaxBytes  int64
	MaxWidth  int
	MaxHeight int
	MaxPixels uint64
}

Limits bounds image admission before any provider sees the image. Pixel count is checked separately from each dimension to reject decompression-bomb shaped inputs with otherwise plausible headers.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns conservative limits suitable for interactive image attachments. Callers may provide stricter limits for a specific provider.

type Ref

type Ref struct {
	Digest    string `json:"sha256"`
	MIMEType  string `json:"mime_type"`
	Name      string `json:"name"`
	SizeBytes int64  `json:"size_bytes"`
	Width     int    `json:"width"`
	Height    int    `json:"height"`
}

Ref is safe to persist with a session. Digest is the complete lowercase SHA-256 digest, while Handle is a compact presentation identifier derived from it. Name contains only a sanitized basename, never the source path.

func (Ref) Handle

func (r Ref) Handle() string

Handle returns a short display-only identifier. Durable lookup and integrity checks must always use the complete Digest.

func (Ref) Validate

func (r Ref) Validate() error

Validate verifies that a persisted reference is canonical and within the global image-admission bounds. It does not access the object store or trust the reference's metadata as evidence about stored bytes; Load re-derives and compares that metadata after this structural check.

type Store

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

Store owns a private content-addressed image object directory.

func NewStore

func NewStore(root string, limits Limits) (*Store, error)

NewStore opens or creates a private image object store at root.

func (*Store) AdmitBytes

func (s *Store) AdmitBytes(ctx context.Context, displayName string, data []byte) (Ref, error)

AdmitBytes validates an in-memory image (for example, a future native clipboard adapter), stores it privately, and returns a durable reference.

func (*Store) AdmitBytesChecked

func (s *Store) AdmitBytesChecked(ctx context.Context, displayName string, data []byte, check func(Ref) error) (Ref, error)

AdmitBytesChecked validates in-memory image bytes and invokes check with the path-free reference before publication. A rejected check leaves no new object behind.

func (*Store) AdmitFile

func (s *Store) AdmitFile(ctx context.Context, path string) (Ref, error)

AdmitFile validates an explicitly selected regular file, copies it into the private content-addressed store, and returns a path-free reference. Explicit file selection follows a source symlink; the opened descriptor is still validated as a regular file by safeio.

func (*Store) AdmitFileChecked

func (s *Store) AdmitFileChecked(ctx context.Context, path string, check func(Ref) error) (Ref, error)

AdmitFileChecked validates an explicitly selected image and invokes check with its path-free reference before publishing bytes to the private object store. A rejected check leaves no new object behind. The check must be deterministic and must not retain the reference beyond the call.

func (*Store) Load

func (s *Store) Load(ctx context.Context, ref Ref) ([]byte, error)

Load reads an admitted object without following symlinks and verifies its complete digest and image metadata before returning bytes to a trusted provider adapter.