golazy.dev
–
golazy.dev
/
lazyfiles
Index
|
Files
|
Directories
package lazyfiles ¶
import "golazy.dev/lazyfiles"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.Handlerfunc (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. |
Package lazyfiles catalogs stored files and routes file IDs to named lazystorage backends.
The package separates file metadata from object bytes. A File is the durable catalog record for one logical upload or generated file: its ID, display filename, content type, size, checksum, opaque application metadata, and timestamps. A Location says where the bytes for that file currently live: the named storage backend, object key, role, status, and location checksum. Files coordinates the two pieces by writing bytes through a lazystorage.Writer and then recording the resulting File and primary active Location in a Repository.
This indirection is useful when an application needs stable file IDs while moving bytes between storage systems, mirroring objects, or replacing a legacy backend. The catalog can keep multiple locations for a file; lookup chooses a primary active location first, then any active location, then an unmarked location. Byte-level storage remains owned by lazystorage implementations such as lazystorage.NewFilesystem or lazystorage/s3.
URL asks the chosen storage for a direct URL when that storage implements lazystorage.URLer. If the storage cannot provide one, URL returns an application route under RoutePrefix, defaulting to "/_lazy/files". Handler serves those fallback routes for GET and HEAD requests by verifying the path token, opening the cataloged file, and streaming the stored bytes. When SigningKey is set, fallback route tokens are HMAC-signed and can honor lazystorage.ExpiresIn or lazystorage.ExpiresAt; without a signing key the raw file ID is used as the token.
lazyfiles is not tied to a GoLazy application. Use it directly when a service needs a small catalog around one or more object stores. In a larger GoLazy stack, lazymedia can build derived media records on top of lazyfiles without owning original storage. PostgreSQL-backed applications can pair this package with golazy.dev/pg/pgfiles for catalog metadata and golazy.dev/pg/pgstorage for object bytes; golazy.dev/pg/pgmedia provides the matching repository for lazymedia derivatives.
The append-only JSONL repository implementation lives in the golazy.dev/lazyfiles/jsonl subpackage. It is useful for local tools, tests, and simple single-process applications. Production applications that need shared concurrency or database transactions should use a database-backed Repository such as golazy.dev/pg/pgfiles.