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

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.

The append-only JSONL repository implementation lives in the golazy.dev/lazyfiles/jsonl subpackage.

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

type StorageName ¶

StorageName selects a named lazystorage backend.

type StorageName struct {
	Name string
}

type StoredFile ¶

StoredFile combines a file record with its chosen location.

type StoredFile struct {
	File		File
	Location	Location
	Locations	[]Location
}

Directories ¶

Path	Synopsis
lazyfiles/jsonl	Package jsonl stores lazyfiles repository records in an append-only JSONL file.