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.

Applications can use it as the durable file catalog behind uploads, imported assets, or generated media. lazymedia can then build representations on top of the catalog without taking ownership of storage itself.

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)
}