attachment

package
v1.0.8 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: GPL-3.0 Imports: 28 Imported by: 0

Documentation

Overview

Package attachment owns bounded, immutable user attachment imports.

Attachments are untrusted model input. A Manifest is safe metadata for transcripts and presentation, but it is not filesystem authority. Only a Store can resolve its opaque StorageID to bytes.

Index

Constants

View Source 
const (
	// ProtocolVersion is the first provider-neutral attachment import
	// protocol understood by the native runtime.
	ProtocolVersion = 1

	MIMEPNG  = "image/png"
	MIMEJPEG = "image/jpeg"
	MIMEPDF  = "application/pdf"

	DefaultMaxAttachmentsPerMessage       = 8
	DefaultMaxConcurrentUploads           = 8
	DefaultMaxUploadsPerSession           = 100_000
	DefaultMaxItemBytes             int64 = 20 << 20
	DefaultMaxAggregateBytes        int64 = 40 << 20
	DefaultMaxStorageBytes          int64 = 512 << 20
	DefaultMaxModelMediaBytes       int64 = 40 << 20
	DefaultMaxChunkBytes                  = 256 << 10
	DefaultMaxDisplayNameBytes            = 255
	DefaultMaxMIMETypeBytes               = 64
	DefaultMaxImageDimension              = 8192
	DefaultMaxImagePixels           int64 = 20_000_000
	DefaultMaxPDFPages                    = 100
	DefaultUploadTimeout                  = 2 * time.Minute
)
View Source 
const (
	SourceScopeInitialCLI = "initial_cli"
	SourceScopePerTurn    = "per_turn"
)

Variables

View Source 
var (
	ErrInvalidID         = errors.New("invalid attachment identity")
	ErrInvalidName       = errors.New("invalid attachment display name")
	ErrUnsupportedMedia  = errors.New("unsupported attachment media")
	ErrMediaMismatch     = errors.New("attachment MIME claim does not match content")
	ErrMalformedMedia    = errors.New("malformed attachment media")
	ErrResourceLimit     = errors.New("attachment resource limit exceeded")
	ErrUnsafeSource      = errors.New("selected attachment source is unsafe")
	ErrDuplicate         = errors.New("duplicate attachment identity")
	ErrNotCommitted      = errors.New("attachment is not committed")
	ErrTampered          = errors.New("attachment content is missing or tampered")
	ErrClosed            = errors.New("attachment store is closed")
	ErrUploadState       = errors.New("invalid attachment upload state")
	ErrUploadTerminal    = errors.New("attachment upload is already terminal")
	ErrUploadExpired     = errors.New("attachment upload expired")
	ErrSequence          = errors.New("attachment chunk sequence is invalid")
	ErrBase64            = errors.New("attachment chunk is not strict base64")
	ErrDigestMismatch    = errors.New("attachment digest does not match")
	ErrSizeMismatch      = errors.New("attachment size does not match")
	ErrStoreUnsafe       = errors.New("attachment store is unavailable or unsafe")
	ErrStorageIdentity   = errors.New("invalid attachment storage identity")
	ErrInvalidCapability = errors.New("invalid attachment capability limits")
	ErrInvalidManifest   = errors.New("invalid attachment manifest")
)

Functions

func DecodeStrictBase64Chunk 

func DecodeStrictBase64Chunk(encoded string, limits Limits) ([]byte, error)

DecodeStrictBase64Chunk validates the physical chunk alphabet, padding, and decoded bounds. encoding/base64 intentionally ignores CR/LF even in Strict mode, so the explicit alphabet pass is required for a no-whitespace wire contract.

func ValidateAttachmentID 

func ValidateAttachmentID(id ID) error

ValidateAttachmentID validates the closed stable reference syntax.

func ValidateUploadID 

func ValidateUploadID(id UploadID) error

ValidateUploadID validates the closed upload correlation syntax.

func VerifyResolved 

func VerifyResolved(manifest Manifest, data []byte, limits Limits) error

VerifyResolved performs the complete provider-bound validation without filesystem access. It is suitable for adapters consuming an AttachmentSource fake as well as for Store.Resolve.

Types

type AbortReason 

type AbortReason string

AbortReason is closed so untrusted text cannot be reflected through acknowledgements or diagnostics. 

const (
	AbortCaller         AbortReason = "caller_abort"
	AbortCancellation   AbortReason = "cancelled"
	AbortEOF            AbortReason = "eof"
	AbortProcessFailure AbortReason = "process_failure"
	AbortShutdown       AbortReason = "shutdown"
)

type BeginUpload 

type BeginUpload struct {
	UploadID     UploadID
	AttachmentID ID
	Name         string
	SizeBytes    int64
	MIMEType     string
	SHA256       string
}

BeginUpload declares all bounded state before any chunk is admitted.

type Capability 

type Capability struct {
	ProtocolVersion int                `json:"protocol_version"`
	Sources         []SourceCapability `json:"sources"`
	MediaTypes      []MediaCapability  `json:"media_types"`
	Limits          Limits             `json:"limits"`
}

Capability is safe to advertise during runtime initialization.

func CapabilityFor 

func CapabilityFor(limits Limits) (Capability, error)

CapabilityFor returns a defensive copy of the exact store contract.

type CleanupResult 

type CleanupResult struct {
	ManifestsRemoved int   `json:"manifests_removed"`
	BlobsRemoved     int   `json:"blobs_removed"`
	BytesRemoved     int64 `json:"bytes_removed"`
}

CleanupResult reports only counts and bytes, never store paths.

type FileImport 

type FileImport struct {
	AttachmentID ID
	Path         string
	Name         string
	MIMEType     string
}

FileImport describes one explicit caller-selected source path. Path is consumed only for the duration of ImportFile and is never retained.

type ID 

type ID string

ID is a stable attachment reference. It does not encode a path.

func NewAttachmentID 

func NewAttachmentID() (ID, error)

NewAttachmentID creates a cryptographically random stable reference.

type Kind 

type Kind string

Kind is the closed provider-neutral media family. 

const (
	KindImage    Kind = "image"
	KindDocument Kind = "document"
)

type Limits 

type Limits struct {
	MaxAttachmentsPerMessage  int           `json:"max_attachments_per_message"`
	MaxConcurrentUploads      int           `json:"max_concurrent_uploads"`
	MaxUploadsPerSession      int           `json:"max_uploads_per_session"`
	MaxItemBytes              int64         `json:"max_item_bytes"`
	MaxAggregateBytes         int64         `json:"max_aggregate_bytes"`
	MaxStorageBytes           int64         `json:"max_storage_bytes"`
	MaxModelRequestMediaBytes int64         `json:"max_model_request_media_bytes"`
	MaxChunkDecodedBytes      int           `json:"max_chunk_decoded_bytes"`
	MaxChunkEncodedBytes      int           `json:"max_chunk_encoded_bytes"`
	MaxDisplayNameBytes       int           `json:"max_display_name_bytes"`
	MaxMIMETypeBytes          int           `json:"max_mime_type_bytes"`
	MaxImageDimension         int           `json:"max_image_dimension"`
	MaxImagePixels            int64         `json:"max_image_pixels"`
	MaxPDFPages               int           `json:"max_pdf_pages"`
	UploadTimeout             time.Duration `json:"-"`
	UploadTimeoutMillis       int64         `json:"upload_timeout_ms"`
}

Limits is both the enforcing configuration and the advertised contract. MaxUploadsPerSession caps live durable manifests and, independently, the terminal upload-attempt ledger. Zero values select the defaults.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns the exact first-version runtime limits.

type Manifest 

type Manifest struct {
	AttachmentID ID     `json:"attachment_id"`
	Kind         Kind   `json:"kind"`
	Name         string `json:"name"`
	MIMEType     string `json:"mime_type"`
	SizeBytes    int64  `json:"size_bytes"`
	SHA256       string `json:"sha256"`
	StorageID    string `json:"storage_id"`
}

Manifest is the complete safe, provider-neutral attachment reference.

func (Manifest) Validate 

func (manifest Manifest) Validate(limits Limits) error

Validate confirms that metadata is complete and internally consistent.

type MediaCapability 

type MediaCapability struct {
	Kind            Kind   `json:"kind"`
	MIMEType        string `json:"mime_type"`
	MaxBytes        int64  `json:"max_bytes"`
	MaxDimension    int    `json:"max_dimension,omitempty"`
	MaxPixels       int64  `json:"max_pixels,omitempty"`
	MaxPages        int    `json:"max_pages,omitempty"`
	TransformPolicy string `json:"transform_policy"`
}

MediaCapability describes one exact accepted MIME and its transformations.

type Options 

type Options struct {
	Limits Limits
	Random io.Reader
	Now    func() time.Time
}

Options configures one session-associated store.

type Resolved 

type Resolved struct {
	Manifest Manifest
	Bytes    []byte
}

Resolved contains provider-bound bytes and their safe manifest.

type Source 

type Source string

Source names a caller-controlled import mechanism. 

const (
	SourceFilePath   Source = "file_path"
	SourceStreamJSON Source = "stream_json_v1"
)

type SourceCapability 

type SourceCapability struct {
	Source Source `json:"source"`
	Scope  string `json:"scope"`
}

SourceCapability gives an import source its exact user-surface scope.

type Store 

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

Store owns one session's immutable attachment manifests and blobs.

func OpenStore 

func OpenStore(directory string, options Options) (*Store, error)

OpenStore creates or reacquires a private store rooted at directory. Existing manifests are strictly decoded and every referenced blob is verified before the store is returned.

func (*Store) Abort 

func (store *Store) Abort(
	ctx context.Context,
	uploadID UploadID,
) (UploadAcknowledgement, error)

Abort settles one active upload and removes its temporary bytes.

func (*Store) AbortAll 

func (store *Store) AbortAll(reason AbortReason) []UploadAcknowledgement

AbortAll settles cancellation, EOF, process failure, or shutdown for every active non-committing upload in stable upload-ID order.

func (*Store) Begin 

func (store *Store) Begin(ctx context.Context, request BeginUpload) (UploadAcknowledgement, error)

Begin reserves count, aggregate bytes, storage, and attachment identity before accepting a single chunk.

func (*Store) Capability 

func (store *Store) Capability() Capability

Capability returns a defensive copy of this store's advertised contract.

func (*Store) Chunk 

func (store *Store) Chunk(
	ctx context.Context,
	uploadID UploadID,
	sequence uint64,
	encoded string,
) error

Chunk accepts one strict padded-base64 chunk at the exact next sequence, beginning at sequence zero. A correlated chunk protocol violation is terminal; callers obtain its acknowledgement with UploadOutcome.

func (*Store) Close 

func (store *Store) Close() error

Close aborts every in-flight upload, removes its temporary file, and makes future operations fail. Committed manifests and blobs remain durable.

func (*Store) Collect 

func (store *Store) Collect(ctx context.Context, referenced []ID) (CleanupResult, error)

Collect removes committed manifests not named by the authoritative durable reference set, then removes only blobs whose logical reference count reaches zero. All retained references are verified before the first mutation.

func (*Store) Commit 

func (store *Store) Commit(
	ctx context.Context,
	uploadID UploadID,
) (UploadAcknowledgement, error)

Commit verifies the exact declared byte count and raw digest, normalizes the media, publishes the immutable blob and manifest, and returns the upload's sole terminal acknowledgement.

func (*Store) CopyTo 

func (store *Store) CopyTo(ctx context.Context, destination *Store, ids []ID) error

CopyTo verifies and safely copies a complete ordered set into another session store. Storage identities remain content-addressed and source paths are never involved.

func (*Store) DiscardUnreferenced 

func (store *Store) DiscardUnreferenced(ctx context.Context, id ID) error

DiscardUnreferenced removes one committed import that has not crossed durable user-message admission. Callers must never use it for an attachment referenced by transcript history; retained history is reconciled through Collect instead.

func (*Store) Expire 

func (store *Store) Expire(now time.Time) []UploadAcknowledgement

Expire settles all deadlines at or before now and returns their sole terminal acknowledgements in stable upload-ID order.

func (*Store) ImportFile 

func (store *Store) ImportFile(ctx context.Context, request FileImport) (Manifest, error)

ImportFile snapshots one explicit caller-selected regular file. The source path is discarded before the immutable store commit.

func (*Store) Limits 

func (store *Store) Limits() Limits

Limits returns this store's immutable normalized bounds.

func (*Store) Resolve 

func (store *Store) Resolve(ctx context.Context, id ID) (Manifest, []byte, error)

Resolve returns a verified immutable copy of one attachment's bytes.

func (*Store) ResolveMany 

func (store *Store) ResolveMany(ctx context.Context, ids []ID) ([]Resolved, error)

ResolveMany atomically validates the complete ordered set before returning any provider-bound data. Duplicate references are rejected.

func (*Store) UploadNotifications 

func (store *Store) UploadNotifications() <-chan UploadAcknowledgement

UploadNotifications carries automatic timeout acknowledgements. Explicit commit, abort, AbortAll, and Expire outcomes are returned directly and are not duplicated on this channel. The channel closes with Store.Close.

func (*Store) UploadOutcome 

func (store *Store) UploadOutcome(uploadID UploadID) (UploadAcknowledgement, bool)

UploadOutcome returns a defensive terminal acknowledgement, if one exists.

func (*Store) Verify 

func (store *Store) Verify(ctx context.Context, manifest Manifest) error

Verify proves that a transcript manifest still matches the store mapping and immutable bytes.

type UploadAcknowledgement 

type UploadAcknowledgement struct {
	UploadID     UploadID     `json:"upload_id"`
	AttachmentID ID           `json:"attachment_id"`
	Status       UploadStatus `json:"status"`
	Terminal     bool         `json:"terminal"`
	Manifest     *Manifest    `json:"manifest,omitempty"`
	Reason       string       `json:"reason,omitempty"`
}

UploadAcknowledgement correlates the one terminal upload outcome.

type UploadID 

type UploadID string

UploadID correlates one bounded begin/chunk/commit/abort state machine.

func NewUploadID 

func NewUploadID() (UploadID, error)

NewUploadID creates a cryptographically random upload correlation.

type UploadStatus 

type UploadStatus string

UploadStatus is a closed import lifecycle. 

const (
	UploadAccepted  UploadStatus = "accepted"
	UploadCommitted UploadStatus = "committed"
	UploadAborted   UploadStatus = "aborted"
	UploadExpired   UploadStatus = "expired"
	UploadFailed    UploadStatus = "failed"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.