storage

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultS3Region = "us-east-1"

Variables

This section is empty.

Functions

func AudioKey 

func AudioKey(sessionID, filename string, now time.Time) string

AudioKey builds a session-scoped key for a TTS/STT audio file. Layout: sessions/{sessionID}/artifacts/audio/{date}/{timestamp}-{filename}

func BuildArtifactKey 

func BuildArtifactKey(request ArtifactPutRequest) string

func CopyFile 

func CopyFile(ctx context.Context, srcKey, dstKey string) error

func DefaultLocalPath 

func DefaultLocalPath() string

DefaultLocalPath returns the root directory for the local artifact store. Using the runtime root directly (not a storage/ subdirectory) so that session-scoped keys (sessions/{id}/images/, sessions/{id}/tools/, …) land at the same level as plans and logs — all under ~/.config/seshat-cli/. Non-session namespaces (documents/, rag/, artifacts/web/) are unaffected.

func DeleteDocument 

func DeleteDocument(ctx context.Context, key string) error

func DeleteFile 

func DeleteFile(ctx context.Context, key string) error

func DetectContentType 

func DetectContentType(filename string) string

func DocumentKey 

func DocumentKey(filename string, now time.Time) string

func DownloadFile 

func DownloadFile(ctx context.Context, key string) ([]byte, error)

func DownloadKey 

func DownloadKey(sessionID, pageID, filename string, now time.Time) string

DownloadKey builds a session-scoped storage key for a browser download. Layout: sessions/{sessionID}/tools/{pageID}/{date}/{timestamp}-{filename}

func Exists 

func Exists(ctx context.Context, key string) (bool, error)

func GeneratedImageKey 

func GeneratedImageKey(sessionID, filename string, now time.Time) string

GeneratedImageKey builds a session-scoped key for an AI-generated image. Layout: sessions/{sessionID}/artifacts/images/{date}/{timestamp}-{filename}

func GetFileURL 

func GetFileURL(ctx context.Context, key string) (string, error)

func HealthCheck 

func HealthCheck(ctx context.Context) error

func LoadDocument 

func LoadDocument(ctx context.Context, key string) ([]byte, error)

func MoveFile 

func MoveFile(ctx context.Context, srcKey, dstKey string) error

func PDFKey 

func PDFKey(title string, now time.Time) string

func ResetProvider 

func ResetProvider()

func ScreenshotKey 

func ScreenshotKey(sessionID, pageID string, now time.Time) string

ScreenshotKey builds a session-scoped storage key for a browser screenshot. Layout: sessions/{sessionID}/artifacts/screenshots/{pageID}/{date}/{timestamp}-screenshot.png Must match the path produced by BuildArtifactKey(NamespaceBrowserScreenshots).

func SetConfig 

func SetConfig(cfg Config)

func StoreDocument 

func StoreDocument(ctx context.Context, data []byte, filename string) (string, error)

func StorePDF 

func StorePDF(ctx context.Context, data []byte, title string) (string, error)

func StoreScreenshot 

func StoreScreenshot(ctx context.Context, data []byte, sessionID, pageID string) (string, error)

func UploadFile 

func UploadFile(ctx context.Context, key string, data []byte, contentType string) error

func WebArtifactKey 

func WebArtifactKey(sessionID, filename string, now time.Time) string

WebArtifactKey builds a session-scoped key for web-fetched content. Layout: sessions/{sessionID}/artifacts/web/{date}/{timestamp}-{filename}

Types

type ArtifactMetadata 

type ArtifactMetadata struct {
	Key            string                 `json:"key"`
	Namespace      string                 `json:"namespace,omitempty"`
	Filename       string                 `json:"filename,omitempty"`
	SessionID      string                 `json:"session_id,omitempty"`
	PageID         string                 `json:"page_id,omitempty"`
	ContentType    string                 `json:"content_type,omitempty"`
	Size           int64                  `json:"size,omitempty"`
	ChecksumSHA256 string                 `json:"checksum_sha256,omitempty"`
	CreatedAt      time.Time              `json:"created_at,omitempty"`
	ModifiedAt     time.Time              `json:"modified_at,omitempty"`
	ExpiresAt      time.Time              `json:"expires_at,omitempty"`
	RetentionClass ArtifactRetentionClass `json:"retention_class,omitempty"`
}

ArtifactMetadata is the persisted control-plane record associated with a blob. It lets the runtime run GC, checks integrity, and prepare future document/RAG features without coupling this package to a specific database.

func ReadFileMetadata 

func ReadFileMetadata(ctx context.Context, key string) (ArtifactMetadata, error)

type ArtifactNamespace 

type ArtifactNamespace string

ArtifactNamespace groups stored objects by runtime-level responsibility. These prefixes are intentionally generic so the core can stay reusable while backend layers add higher-level document, RAG, or tenant semantics on top. 

const (
	NamespaceDocuments          ArtifactNamespace = "documents"
	NamespaceWebArtifacts       ArtifactNamespace = "artifacts/web"
	NamespaceBrowserScreenshots ArtifactNamespace = "artifacts/browser/screenshots"
	NamespaceBrowserDownloads   ArtifactNamespace = "artifacts/browser/downloads"
	NamespaceRAGDocuments       ArtifactNamespace = "rag/documents"
)

type ArtifactPutRequest 

type ArtifactPutRequest struct {
	Namespace      ArtifactNamespace
	Filename       string
	SessionID      string
	PageID         string
	ContentType    string
	Timestamp      time.Time
	RetentionClass ArtifactRetentionClass
	TTL            time.Duration
}

ArtifactPutRequest describes a runtime-level persisted artifact. The artifact store derives the storage key from this struct so callers do not duplicate key layout logic across browser, fetch, and future RAG layers.

type ArtifactRef 

type ArtifactRef struct {
	Key            string    `json:"key"`
	URL            string    `json:"url"`
	ContentType    string    `json:"content_type,omitempty"`
	Size           int64     `json:"size,omitempty"`
	ModifiedAt     time.Time `json:"modified_at,omitempty"`
	ChecksumSHA256 string    `json:"checksum_sha256,omitempty"`
	ExpiresAt      time.Time `json:"expires_at,omitempty"`
	Namespace      string    `json:"namespace,omitempty"`
}

ArtifactRef is the stable runtime-facing handle returned after persisting a blob. Callers should pass these refs around instead of assuming a local path or S3 URL.

func ListFiles 

func ListFiles(ctx context.Context, prefix string, limit int) ([]ArtifactRef, error)

func OpenFileReader 

func OpenFileReader(ctx context.Context, key string) (io.ReadCloser, ArtifactRef, error)

func StatFile 

func StatFile(ctx context.Context, key string) (ArtifactRef, error)

func StoreAudioRef 

func StoreAudioRef(ctx context.Context, store ArtifactStore, data []byte, sessionID, filename, contentType string) (ArtifactRef, error)

StoreAudioRef persists a TTS/STT audio file under the session's artifacts/audio/ dir.

func StoreDocumentRef 

func StoreDocumentRef(ctx context.Context, store ArtifactStore, data []byte, filename string) (ArtifactRef, error)

func StoreGeneratedImageRef 

func StoreGeneratedImageRef(ctx context.Context, store ArtifactStore, data []byte, sessionID, filename, contentType string) (ArtifactRef, error)

StoreGeneratedImageRef persists an AI-generated image under the session's artifacts/images/ dir.

func StorePDFRef 

func StorePDFRef(ctx context.Context, store ArtifactStore, data []byte, title string) (ArtifactRef, error)

func StoreRAGDocumentRef 

func StoreRAGDocumentRef(ctx context.Context, store ArtifactStore, data []byte, filename string) (ArtifactRef, error)

func StoreScreenshotRef 

func StoreScreenshotRef(ctx context.Context, store ArtifactStore, data []byte, sessionID, pageID string) (ArtifactRef, error)

func StoreWebArtifactRef 

func StoreWebArtifactRef(ctx context.Context, store ArtifactStore, data []byte, sessionID, filename, contentType string) (ArtifactRef, error)

StoreWebArtifactRef persists web-fetched content under the session's artifacts/web/ dir.

type ArtifactRetentionClass 

type ArtifactRetentionClass string

ArtifactRetentionClass controls lifecycle defaults for persisted artifacts. 

const (
	RetentionDurable   ArtifactRetentionClass = "durable"
	RetentionTemporary ArtifactRetentionClass = "temporary"
	RetentionSession   ArtifactRetentionClass = "session"
)

type ArtifactStore 

type ArtifactStore interface {
	Put(ctx context.Context, key string, body []byte, contentType string) (ArtifactRef, error)
	PutArtifact(ctx context.Context, request ArtifactPutRequest, body []byte) (ArtifactRef, error)
	Get(ctx context.Context, key string) ([]byte, error)
	OpenReader(ctx context.Context, key string) (io.ReadCloser, ArtifactRef, error)
	Stat(ctx context.Context, key string) (ArtifactRef, error)
	List(ctx context.Context, options ListOptions) ([]ArtifactRef, error)
	Metadata(ctx context.Context, key string) (ArtifactMetadata, error)
	ListMetadata(ctx context.Context, options ListOptions) ([]ArtifactMetadata, error)
	GarbageCollect(ctx context.Context, options GCOptions) (GCReport, error)
	Delete(ctx context.Context, key string) error
	Exists(ctx context.Context, key string) (bool, error)
	URL(ctx context.Context, key string) (string, error)
}

ArtifactStore is the narrow abstraction consumed by browser/fetch/document layers. It deliberately hides provider-specific details so the runtime can switch between local and object storage without leaking infra concerns into web packages.

func DefaultArtifactStore 

func DefaultArtifactStore() (ArtifactStore, error)

DefaultArtifactStore returns the process-wide artifact store backed by the configured provider.

func NewArtifactStore 

func NewArtifactStore(provider StorageProvider) ArtifactStore

NewArtifactStore adapts an existing provider into the narrower artifact interface.

func NewArtifactStoreFromConfig 

func NewArtifactStoreFromConfig(cfg Config) (ArtifactStore, error)

NewArtifactStoreFromConfig creates an artifact store from an explicit Config, bypassing the process-wide provider singleton. Use when different SDK clients need independent storage backends.

type Config 

type Config struct {
	Provider          ProviderType
	LocalPath         string
	S3Endpoint        string
	S3Bucket          string
	S3AccessKeyID     string
	S3SecretAccessKey string
	S3Region          string
	S3KeyPrefix       string
}

func GetConfigFromEnv 

func GetConfigFromEnv() Config

type FileInfo 

type FileInfo struct {
	Key    string
	Size   int64
	URL    string
	Exists bool
}

type GCOptions 

type GCOptions struct {
	Now        time.Time
	Namespaces []ArtifactNamespace
	Limit      int
	DryRun     bool
}

GCOptions controls artifact garbage collection.

type GCReport 

type GCReport struct {
	Scanned     int      `json:"scanned"`
	Deleted     int      `json:"deleted"`
	Kept        int      `json:"kept"`
	Errors      []string `json:"errors,omitempty"`
	DeletedKeys []string `json:"deleted_keys,omitempty"`
}

GCReport summarizes one garbage collection pass.

func RunGarbageCollection 

func RunGarbageCollection(ctx context.Context, options GCOptions) (GCReport, error)

type ListOptions 

type ListOptions struct {
	Prefix string
	Limit  int
}

ListOptions bounds provider-side listings so callers can enumerate namespaces without loading the full storage tree into memory.

type LocalProvider 

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

func NewLocalProvider 

func NewLocalProvider() (*LocalProvider, error)

func NewLocalProviderWithConfig 

func NewLocalProviderWithConfig(cfg Config) (*LocalProvider, error)

func (*LocalProvider) Delete 

func (p *LocalProvider) Delete(ctx context.Context, key string) error

func (*LocalProvider) Download 

func (p *LocalProvider) Download(ctx context.Context, key string) ([]byte, error)

func (*LocalProvider) Exists 

func (p *LocalProvider) Exists(ctx context.Context, key string) (bool, error)

func (*LocalProvider) GetURL 

func (p *LocalProvider) GetURL(ctx context.Context, key string) (string, error)

func (*LocalProvider) List 

func (p *LocalProvider) List(ctx context.Context, options ListOptions) ([]ObjectInfo, error)

func (*LocalProvider) OpenReader 

func (p *LocalProvider) OpenReader(ctx context.Context, key string) (io.ReadCloser, ObjectInfo, error)

func (*LocalProvider) Stat 

func (p *LocalProvider) Stat(ctx context.Context, key string) (ObjectInfo, error)

func (*LocalProvider) Upload 

func (p *LocalProvider) Upload(ctx context.Context, key string, data []byte, contentType string) error

type ObjectInfo 

type ObjectInfo struct {
	Key         string    `json:"key"`
	URL         string    `json:"url,omitempty"`
	ContentType string    `json:"content_type,omitempty"`
	Size        int64     `json:"size,omitempty"`
	ModifiedAt  time.Time `json:"modified_at,omitempty"`
	ETag        string    `json:"etag,omitempty"`
}

ObjectInfo is the provider-level description of a stored object.

type ProviderType 

type ProviderType string
const (
	ProviderLocal ProviderType = "local"
	ProviderS3    ProviderType = "s3"
)

func GetProviderType 

func GetProviderType() ProviderType

type Reaper 

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

Reaper runs periodic storage GC for expiring artifact namespaces. It stays in internal/storage so hosts can reuse the same logic without duplicating timers or expiry policies across CLI, API, and SDK layers.

func NewReaper 

func NewReaper(store ArtifactStore, config ReaperConfig) *Reaper

func (*Reaper) RunOnce 

func (r *Reaper) RunOnce(ctx context.Context) (GCReport, error)

func (*Reaper) Start 

func (r *Reaper) Start(parent context.Context)

func (*Reaper) Stop 

func (r *Reaper) Stop()

type ReaperConfig 

type ReaperConfig struct {
	Interval   time.Duration
	Namespaces []ArtifactNamespace
	Limit      int
}

ReaperConfig controls background garbage collection for expiring artifacts.

func DefaultReaperConfig 

func DefaultReaperConfig() ReaperConfig

type S3Provider 

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

func NewS3Provider 

func NewS3Provider() (*S3Provider, error)

func NewS3ProviderWithConfig 

func NewS3ProviderWithConfig(cfg Config) (*S3Provider, error)

func (*S3Provider) Delete 

func (p *S3Provider) Delete(ctx context.Context, key string) error

func (*S3Provider) Download 

func (p *S3Provider) Download(ctx context.Context, key string) ([]byte, error)

func (*S3Provider) Exists 

func (p *S3Provider) Exists(ctx context.Context, key string) (bool, error)

func (*S3Provider) GetURL 

func (p *S3Provider) GetURL(ctx context.Context, key string) (string, error)

func (*S3Provider) List 

func (p *S3Provider) List(ctx context.Context, options ListOptions) ([]ObjectInfo, error)

func (*S3Provider) OpenReader 

func (p *S3Provider) OpenReader(ctx context.Context, key string) (io.ReadCloser, ObjectInfo, error)

func (*S3Provider) Stat 

func (p *S3Provider) Stat(ctx context.Context, key string) (ObjectInfo, error)

func (*S3Provider) Upload 

func (p *S3Provider) Upload(ctx context.Context, key string, data []byte, contentType string) error

type StorageProvider 

type StorageProvider interface {
	Upload(ctx context.Context, key string, data []byte, contentType string) error
	Download(ctx context.Context, key string) ([]byte, error)
	OpenReader(ctx context.Context, key string) (io.ReadCloser, ObjectInfo, error)
	Stat(ctx context.Context, key string) (ObjectInfo, error)
	List(ctx context.Context, options ListOptions) ([]ObjectInfo, error)
	Delete(ctx context.Context, key string) error
	GetURL(ctx context.Context, key string) (string, error)
	Exists(ctx context.Context, key string) (bool, error)
}

func GetProvider 

func GetProvider() (StorageProvider, error)

func NewProviderFromConfig 

func NewProviderFromConfig(cfg Config) (StorageProvider, error)

NewProviderFromConfig creates a StorageProvider from an explicit Config without touching the process-wide singleton. Use this when you need per-instance storage.

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.