attachments

package
v0.3.0-beta.34 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// AttachmentURIPrefix identifies persisted session attachments.
	AttachmentURIPrefix = "compozy://session-attachments/"
	// KindImage marks image bytes that can carry pixel dimensions.
	KindImage = "image"
	// KindFile marks non-image attachment bytes.
	KindFile = "file"
)
View Source
const (
	MIMEImagePNG       = "image/png"
	MIMEImageJPEG      = "image/jpeg"
	MIMEImageWebP      = "image/webp"
	MIMEApplicationPDF = "application/pdf"
	MIMETextMarkdown   = "text/markdown"
	MIMETextPlain      = "text/plain"
)
View Source
const SweepInterval = time.Hour

SweepInterval is the daemon-owned periodic retention cadence.

Variables

View Source
var (
	// ErrNotFound hides missing, expired, and foreign-scope attachments behind one error.
	ErrNotFound = errors.New("attachments: attachment not found")
	// ErrCorrupt reports retained bytes that do not match their content identity.
	ErrCorrupt = errors.New("attachments: attachment is corrupt")
	// ErrPersistence reports a durable write or retention failure.
	ErrPersistence = errors.New("attachments: attachment persistence failed")
	// ErrInvalidID reports a path-unsafe workspace, session, or attachment identity.
	ErrInvalidID = errors.New("attachments: invalid attachment identity")
	// ErrTooLarge reports a single file that exceeds the configured byte ceiling.
	ErrTooLarge = errors.New("attachments: file exceeds max_file_bytes")
	// ErrUnsupportedMIME reports bytes outside the v1 allowlist.
	ErrUnsupportedMIME = errors.New("attachments: unsupported mime type")
)
View Source
var ErrAttachmentSweeperStoreRequired = errors.New("attachments: sweeper store is required")

ErrAttachmentSweeperStoreRequired reports a periodic worker without an attachment store.

Functions

func DefaultAllowedMIMEs

func DefaultAllowedMIMEs() []string

DefaultAllowedMIMEs returns the v1 sniff allowlist. Client Content-Type is ignored.

func NormalizeAllowedMIME

func NormalizeAllowedMIME(allowed []string) ([]string, error)

NormalizeAllowedMIME validates and canonicalizes the attachment MIME allowlist.

func ParseAttachmentID

func ParseAttachmentID(value string) (string, error)

ParseAttachmentID validates a persisted content-addressed attachment identity.

func ParseAttachmentURI

func ParseAttachmentURI(uri string) (string, error)

ParseAttachmentURI validates an opaque attachment URI and returns its path-safe identity.

func SniffMIME

func SniffMIME(data []byte, filename string) (string, string, int, int, error)

SniffMIME detects a v1 type from magic bytes. Filename is used only to disambiguate valid UTF-8 text as markdown versus plain text.

func ValidateSize

func ValidateSize(bytes int64, maxFileBytes int64) error

ValidateSize rejects a negative count or a payload over the configured per-file ceiling.

Types

type AttachmentReader

type AttachmentReader interface {
	Open(ctx context.Context, workspaceID string, sessionID string, id string) (io.ReadCloser, AttachmentRef, error)
	Stat(ctx context.Context, workspaceID string, sessionID string, id string) (AttachmentRef, error)
}

AttachmentReader reads retained attachments within a workspace session scope.

type AttachmentRef

type AttachmentRef struct {
	ID        string
	URI       string
	Name      string
	MIMEType  string
	Bytes     int64
	SHA256    string
	Kind      string
	Width     int
	Height    int
	CreatedAt time.Time
}

AttachmentRef is the durable identity and metadata for one stored attachment.

type AttachmentRetention

type AttachmentRetention struct {
	MaxCount int
	MaxBytes int64
	MaxAge   time.Duration
}

AttachmentRetention defines global disk bounds for session-scoped attachments.

func (AttachmentRetention) Validate

func (r AttachmentRetention) Validate() error

Validate ensures retention always establishes finite positive bounds.

type AttachmentSweeper

type AttachmentSweeper interface {
	Sweep(ctx context.Context) error
}

AttachmentSweeper applies retention to durable attachments.

type AttachmentWriter

type AttachmentWriter interface {
	Put(ctx context.Context, request PutRequest) (AttachmentRef, error)
	Delete(ctx context.Context, workspaceID string, sessionID string, id string) error
}

AttachmentWriter mutates retained attachments within a workspace session scope.

type FilesystemAttachmentStore

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

FilesystemAttachmentStore retains immutable content-addressed session attachments.

func OpenFilesystemAttachmentStore

func OpenFilesystemAttachmentStore(
	ctx context.Context,
	config FilesystemStoreConfig,
) (*FilesystemAttachmentStore, error)

OpenFilesystemAttachmentStore opens the canonical store and applies retention before use.

func (*FilesystemAttachmentStore) AcquireScopeLease

func (s *FilesystemAttachmentStore) AcquireScopeLease(
	ctx context.Context,
	workspaceID string,
	sessionID string,
) (ScopeLeaseGuard, error)

AcquireScopeLease blocks attachment mutations until the caller releases the lease. An empty session ID reserves the whole workspace; the filesystem store currently serializes all scopes through one mutex so workspace deletion cannot race a Put.

func (*FilesystemAttachmentStore) Delete

func (s *FilesystemAttachmentStore) Delete(
	ctx context.Context,
	workspaceID string,
	sessionID string,
	id string,
) error

Delete removes one retained attachment and its sidecar metadata.

func (*FilesystemAttachmentStore) Open

func (s *FilesystemAttachmentStore) Open(
	ctx context.Context,
	workspaceID string,
	sessionID string,
	id string,
) (io.ReadCloser, AttachmentRef, error)

Open returns a reader for retained bytes after enforcing workspace and session scope.

func (*FilesystemAttachmentStore) Put

Put publishes canonical bytes once and returns their opaque reference.

func (*FilesystemAttachmentStore) Stat

func (s *FilesystemAttachmentStore) Stat(
	ctx context.Context,
	workspaceID string,
	sessionID string,
	id string,
) (AttachmentRef, error)

Stat returns retained metadata after enforcing workspace and session scope.

func (*FilesystemAttachmentStore) Sweep

Sweep removes expired and over-budget attachments in deterministic creation order.

type FilesystemStoreConfig

type FilesystemStoreConfig struct {
	Root          string
	Retention     AttachmentRetention
	Limits        StoreLimits
	RetentionPins RetentionPinSource
}

FilesystemStoreConfig supplies filesystem attachment store dependencies.

type PutRequest

type PutRequest struct {
	WorkspaceID string
	SessionID   string
	Name        string
	Data        []byte
}

PutRequest supplies one attachment write and its session scope.

type RetentionPinSource

type RetentionPinSource interface {
	PinnedAttachmentIDs(ctx context.Context, sessionID string) (map[string]struct{}, error)
}

RetentionPinSource returns durable attachment IDs that retention must preserve.

type ScopeLease

type ScopeLease interface {
	AcquireScopeLease(ctx context.Context, workspaceID string, sessionID string) (ScopeLeaseGuard, error)
}

ScopeLease serializes attachment mutations with session and workspace deletion.

type ScopeLeaseGuard

type ScopeLeaseGuard interface {
	MarkDeleted()
	Release()
}

ScopeLeaseGuard owns one exclusive attachment scope until Release. MarkDeleted permanently fences new writes for that scope in this store instance.

type Store

Store persists content-addressed session attachments on a durable root.

type StoreLimits

type StoreLimits struct {
	MaxFileBytes int64
	AllowedMIME  []string
}

StoreLimits carries operator-configured admission bounds into the filesystem store.

type Sweeper

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

Sweeper applies age retention even when no attachment calls occur.

func NewSweeper

func NewSweeper(store AttachmentSweeper, interval time.Duration, onError func(error)) *Sweeper

NewSweeper builds a joined periodic retention worker.

func (*Sweeper) Shutdown

func (w *Sweeper) Shutdown(ctx context.Context) error

Shutdown cancels and joins the periodic sweep worker.

func (*Sweeper) Start

func (w *Sweeper) Start(ctx context.Context) error

Start begins periodic sweeps until shutdown or parent cancellation.

type UnsupportedMIMEError

type UnsupportedMIMEError struct {
	MIME    string
	Allowed []string
}

UnsupportedMIMEError names the sniffed type and the types the store accepts.

func (*UnsupportedMIMEError) Error

func (e *UnsupportedMIMEError) Error() string

func (*UnsupportedMIMEError) Unwrap

func (e *UnsupportedMIMEError) Unwrap() error

Jump to

Keyboard shortcuts

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