golazy.dev – golazy.dev / lazyfiles Index | Files

package lazyfiles

import "golazy.dev/lazyfiles"

Package lazyfiles catalogs stored files and routes them to named storages.

lazyfiles owns file metadata, storage locations, fallback application URLs, and migration-friendly indirection. Byte-level storage is delegated to lazystorage implementations.

Constants

const RolePrimary, RoleMirror, RoleLegacy, StatusActive

const (
	RolePrimary	= "primary"
	RoleMirror	= "mirror"
	RoleLegacy	= "legacy"
	StatusActive	= "active"
)

Types

type File

File is the catalog record for one logical stored file. 

type File struct {
	ID		string		`json:"id"`
	Filename	string		`json:"filename,omitempty"`
	ContentType	string		`json:"content_type,omitempty"`
	Size		int64		`json:"size,omitempty"`
	Checksum	string		`json:"checksum,omitempty"`
	Metadata	json.RawMessage	`json:"metadata,omitempty"`
	CreatedAt	time.Time	`json:"created_at,omitempty"`
	UpdatedAt	time.Time	`json:"updated_at,omitempty"`
	DeletedAt	time.Time	`json:"deleted_at,omitempty"`
}

type Filename

Filename sets the file's display filename. 

type Filename struct {
	Name string
}

type Files

Files coordinates a repository with named storages. 

type Files struct {
	Repository	Repository
	Storages	map[string]lazystorage.Storage
	DefaultStorage	string
	RoutePrefix	string
	SigningKey	[]byte
}
func (f *Files) Find

Find returns a file and its active location. 

func (f *Files) Find(ctx context.Context, id string, options ...any) (StoredFile, []any, error)
func (f *Files) Handler

Handler serves fallback application file URLs. 

func (f *Files) Handler(next http.Handler) http.Handler
func (f *Files) Open

Open opens a file by catalog id. 

func (f *Files) Open(ctx context.Context, id string, options ...any) (lazystorage.File, File, []any, error)
func (f *Files) Put

Put writes body to storage and records the file catalog entry. 

func (f *Files) Put(ctx context.Context, body io.Reader, options ...any) (File, []any, error)
func (f *Files) URL

URL returns a storage URL when available, otherwise an application route URL. 

func (f *Files) URL(ctx context.Context, id string, options ...any) (string, []any, error)

type Location

Location tells lazyfiles where a file's bytes live. 

type Location struct {
	FileID		string	`json:"file_id"`
	Storage		string	`json:"storage"`
	Key		string	`json:"key"`
	Role		string	`json:"role,omitempty"`
	Status		string	`json:"status,omitempty"`
	Checksum	string	`json:"checksum,omitempty"`
}

type LogRepository

LogRepository stores file metadata in an append-only JSONL log. 

type LogRepository struct {
	// contains filtered or unexported fields
}
func NewLogRepository

NewLogRepository opens or creates an append-only JSONL repository at path. 

func NewLogRepository(path string) (*LogRepository, error)
func (r *LogRepository) Delete
func (r *LogRepository) Delete(ctx context.Context, fileID string, options ...any) ([]any, error)
func (r *LogRepository) Find
func (r *LogRepository) Find(ctx context.Context, query Query, options ...any) (File, []Location, []any, error)
func (r *LogRepository) Put
func (r *LogRepository) Put(ctx context.Context, file File, location Location, options ...any) (File, []any, error)

type Metadata

Metadata sets opaque file metadata. 

type Metadata struct {
	JSON json.RawMessage
}

type ObjectKey

ObjectKey selects the storage key for a write. 

type ObjectKey struct {
	Key string
}

type Query

Query identifies a file. 

type Query struct {
	ID string
}

type Repository

Repository persists file catalog metadata. 

type Repository interface {
	Put(context.Context, File, Location, ...any) (File, []any, error)
	Find(context.Context, Query, ...any) (File, []Location, []any, error)
	Delete(context.Context, string, ...any) ([]any, error)
}