Documentation
¶
Overview ¶
Package attachment provides durable, content-addressed blob storage for session attachments.
Index ¶
- func DefaultBaseDir() (string, error)
- type Descriptor
- type PutMeta
- type Store
- func (s *Store) AddRef(sessionID string, d Descriptor) error
- func (s *Store) EnsureSessionViewDir(sessionID string) (string, error)
- func (s *Store) EnsureView(sessionID, attID string) (string, error)
- func (s *Store) Lookup(sessionID, attID string) (Descriptor, bool)
- func (s *Store) MaterializeMessages(sessionID string, msgs []core.Message) ([]core.Message, error)
- func (s *Store) MaterializerFor(sessionID string) func(context.Context, []core.Message) ([]core.Message, error)
- func (s *Store) Open(sessionID, attID string) (io.ReadCloser, Descriptor, error)
- func (s *Store) Put(data []byte, meta PutMeta) (Descriptor, error)
- func (s *Store) PutRef(sessionID string, data []byte, meta PutMeta) (Descriptor, error)
- func (s *Store) Reconcile(live map[string][]Descriptor) error
- func (s *Store) ReconcileExisting(liveSessionIDs map[string]bool) error
- func (s *Store) ReleaseSession(sessionID string) error
- func (s *Store) RemoveRef(sessionID, attID string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultBaseDir ¶
DefaultBaseDir resolves the production attachments root. MOA_CONFIG_DIR is honored for container and custom deployments.
Types ¶
type Descriptor ¶
type Descriptor struct {
ID string `json:"id"`
SHA256 string `json:"sha256"`
Name string `json:"name"`
Mime string `json:"mime"`
Size int64 `json:"size"`
Kind string `json:"kind"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
Descriptor is the persisted, byte-free reference to a stored blob. It is what a message/session carries instead of base64.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a durable, content-addressed attachment blob store shared across sessions. Blobs are keyed by sha256 of their bytes and reference-counted by occurrence; a blob is deleted when no session references it.
func (*Store) AddRef ¶
func (s *Store) AddRef(sessionID string, d Descriptor) error
AddRef records one attachment occurrence in a session. It is idempotent for an existing (sessionID, descriptor ID) pair.
func (*Store) EnsureSessionViewDir ¶
EnsureSessionViewDir creates and returns the durable, session-scoped parent directory for attachment views. Callers may grant this directory to a tool path policy; it never exposes blobs or another session's views.
func (*Store) EnsureView ¶
EnsureView returns a durable, session-scoped path for a session-owned attachment. Tool views are session-local read-only copies (0400), never hardlinks: the view is exposed to agent tools, and a hardlink would let a tool corrupt the shared immutable blob across sessions. A view duplicates its bytes on disk for integrity and is released with its session. An empty legacy descriptor name uses "file" plus a MIME-derived extension when available.
func (*Store) Lookup ¶
func (s *Store) Lookup(sessionID, attID string) (Descriptor, bool)
Lookup returns the descriptor for a session-owned attachment occurrence.
func (*Store) MaterializeMessages ¶
MaterializeMessages returns a copy of msgs in which referenced images become inline base64, while referenced documents become an advisory with a durable, session-scoped tool path. Messages/blocks without a reference are passed through unchanged. The input slice and its content are never mutated.
func (*Store) MaterializerFor ¶
func (s *Store) MaterializerFor(sessionID string) func(context.Context, []core.Message) ([]core.Message, error)
MaterializerFor returns a per-session materializer closure suitable for the agent's MaterializeContent hook. sessionID is baked in.
func (*Store) Open ¶
func (s *Store) Open(sessionID, attID string) (io.ReadCloser, Descriptor, error)
Open returns a read-only handle to an attachment only when the requested session owns the occurrence.
func (*Store) Put ¶
func (s *Store) Put(data []byte, meta PutMeta) (Descriptor, error)
Put stores raw bytes, deduplicating by their SHA-256 hash. It creates an occurrence descriptor but does not attach that occurrence to a session.
func (*Store) PutRef ¶
PutRef publishes data (deduplicating by hash) AND records a provisional reference from sessionID in ONE locked operation, so the blob can never be garbage-collected between publication and referencing. This is the method callers should use when the owning session is already known (the normal ingestion path). Returns the minted Descriptor (already referenced).
func (*Store) Reconcile ¶
func (s *Store) Reconcile(live map[string][]Descriptor) error
Reconcile rewrites the session ownership indexes and catalog from live descriptors, removes indexes absent from live, and garbage-collects old unreferenced blobs and stale staging files. It MUST run at startup (or in a maintenance window) with no concurrent uploads, AddRef, or PutRef for sessions absent from live: live is a snapshot and is not safe for an actively uploading store.
func (*Store) ReconcileExisting ¶
ReconcileExisting is the lightweight startup reconcile path. It trusts the store's per-session indexes and is O(sessions-with-attachments), rather than walking conversation transcripts. Indexes for sessions absent from live are released, then the catalog, orphan blobs, and stale staging are reconciled.
func (*Store) ReleaseSession ¶
ReleaseSession removes every occurrence owned by a session and unlinks blobs which are no longer referenced by any remaining session index.
Source Files