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

package lazymedia ¶

import "golazy.dev/lazymedia"

Package lazymedia manages generated representations of stored files.

A media variant is a derived file, not the original upload. Examples include thumbnails, Open Graph images, compressed previews, transcript sidecars, or a browser-friendly conversion of an uploaded document. The source file and the generated output are both regular files identified by file IDs; lazymedia only records that source file X has variant key Y whose output file is Z.

The package deliberately does not own byte storage or the durable catalog for original files. Media uses FileStore to open a source file, save a generated output file, and return a URL for that output. Applications commonly satisfy FileStore with golazy.dev/lazyfiles, which in turn stores object bytes through golazy.dev/lazystorage backends such as the local filesystem, S3-compatible storage, or golazy.dev/pg/pgstorage. The lazymedia.Repository stores only the variant relationship and status; PostgreSQL applications can use golazy.dev/pg/pgmedia for that repository while using golazy.dev/pg/pgfiles for file metadata.

Media.Variant first asks Repository for an existing ready variant. If one exists, Media opens the output file through FileStore and returns its file metadata without running the processor again. If no ready variant exists, or Regenerate is passed, Media opens the source file, calls Processor.Process, stores the returned body through FileStore.Put, and saves a ready Variant that points back to the new output file ID. Media.URL builds on Variant and then delegates URL generation to FileStore.URL.

VariantKey is the stable name of the requested representation, such as "thumb", "preview", or "og". Spec carries opaque application-defined JSON that a processor can use for dimensions, codecs, quality settings, or any other generation input. lazymedia stores the spec on the Variant record but does not interpret it.

Options follow the same pass-through convention used by lazystorage and lazyfiles: each layer consumes the options it understands and returns the rest. lazymedia consumes VariantKey, Spec, and Regenerate; generated file metadata is forwarded to FileStore.Put, including lazystorage.ContentType from Result.ContentType and OutputFilename from Result.Filename.

lazymedia is useful outside a GoLazy app. A command-line importer can combine Media with a small JSONL repository and a filesystem-backed file service to generate previews locally, while a server can swap in lazyfiles plus PostgreSQL repositories without changing processors.

The append-only JSONL repository implementation lives in the golazy.dev/lazymedia/jsonl subpackage. It is intended for local tools, tests, and simple single-process applications. Shared production deployments should use a database-backed Repository such as golazy.dev/pg/pgmedia.

Constants ¶

const StatusReady, StatusGenerating, StatusFailed ¶

const (
	StatusReady		= "ready"
	StatusGenerating	= "generating"
	StatusFailed		= "failed"
)

const LazyDevMediaDownloadPath ¶

const LazyDevMediaDownloadPath = "/media/download"

const LazyDevMediaFileDeletePath ¶

const LazyDevMediaFileDeletePath = "/media/file/delete"

const LazyDevMediaFileUploadPath ¶

const LazyDevMediaFileUploadPath = "/media/file/upload"

const LazyDevMediaPath ¶

const LazyDevMediaPath = "/media"

const LazyDevMediaStorageDeletePath ¶

const LazyDevMediaStorageDeletePath = "/media/storage/delete"

const LazyDevMediaStorageUploadPath ¶

const LazyDevMediaStorageUploadPath = "/media/storage/upload"

const LazyDevMediaVariantDeletePath ¶

const LazyDevMediaVariantDeletePath = "/media/variant/delete"

Functions ¶

func RegisterLazyDevHandlers ¶

RegisterLazyDevHandlers registers media, file, and storage inspector endpoints for the development panel.

func RegisterLazyDevHandlers(controlPlane *lazycontrolplane.ControlPlane, inspector *LazyDevInspector)

Types ¶

type File ¶

File is the minimal file metadata lazymedia needs from a file service.

type File struct {
	ID		string
	Filename	string
	ContentType	string
	Size		int64
	Metadata	json.RawMessage
}

type FileStore ¶

FileStore is the minimal file service lazymedia needs.

type FileStore interface {
	Open(context.Context, string, ...any) (io.ReadCloser, File, []any, error)
	Put(context.Context, io.Reader, ...any) (File, []any, error)
	URL(context.Context, string, ...any) (string, []any, error)
}

type LazyDevFileCatalog ¶

LazyDevFileCatalog is the file-service shape used by the development panel.

type LazyDevFileCatalog interface {
	ListFiles(context.Context, LazyDevFileListQuery) ([]LazyDevFileSnapshot, error)
	PutFile(context.Context, io.Reader, LazyDevPutFileOptions) (LazyDevFileSnapshot, error)
	OpenFile(context.Context, string) (io.ReadCloser, LazyDevFileSnapshot, error)
	FileURL(context.Context, string) (string, error)
	DeleteFile(context.Context, string) error
}

type LazyDevFileListQuery ¶

LazyDevFileListQuery filters development file catalog listings.

type LazyDevFileListQuery struct {
	Storage		string
	KeyPrefix	string
}

type LazyDevFileLocation ¶

LazyDevFileLocation describes where a cataloged file's bytes live.

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

type LazyDevFileSnapshot ¶

LazyDevFileSnapshot describes one cataloged file.

type LazyDevFileSnapshot 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"`
	Location	LazyDevFileLocation		`json:"location,omitempty"`
	Locations	[]LazyDevFileLocation		`json:"locations,omitempty"`
	URL		string				`json:"url,omitempty"`
	URLError	string				`json:"url_error,omitempty"`
	Variants	[]LazyDevVariantSnapshot	`json:"variants,omitempty"`
}

type LazyDevInspector ¶

LazyDevInspector describes the media, file, and storage services exposed to the development panel.

type LazyDevInspector struct {
	Storages	map[string]lazystorage.Storage
	DefaultStorage	string
	Files		LazyDevFileCatalog
	Media		*Media
}

type LazyDevPutFileOptions ¶

LazyDevPutFileOptions configures development file uploads.

type LazyDevPutFileOptions struct {
	Storage		string
	Key		string
	Filename	string
	ContentType	string
}

type LazyDevSnapshot ¶

LazyDevSnapshot is the JSON payload consumed by the development panel.

type LazyDevSnapshot struct {
	Storages		[]LazyDevStorageSnapshot	`json:"storages"`
	SelectedStorage		string				`json:"selected_storage,omitempty"`
	StoragePrefix		string				`json:"storage_prefix,omitempty"`
	StorageObjects		[]LazyDevStorageObject		`json:"storage_objects,omitempty"`
	StorageObjectsError	string				`json:"storage_objects_error,omitempty"`
	StorageObjectsTruncated	bool				`json:"storage_objects_truncated,omitempty"`
	Files			[]LazyDevFileSnapshot		`json:"files,omitempty"`
	FilesError		string				`json:"files_error,omitempty"`
	Variants		[]LazyDevVariantSnapshot	`json:"variants,omitempty"`
	VariantsError		string				`json:"variants_error,omitempty"`
}

type LazyDevStorageObject ¶

LazyDevStorageObject is one object listed from a selected storage backend.

type LazyDevStorageObject struct {
	Key		string		`json:"key"`
	ContentType	string		`json:"content_type,omitempty"`
	Size		int64		`json:"size,omitempty"`
	Checksum	string		`json:"checksum,omitempty"`
	ModifiedAt	time.Time	`json:"modified_at,omitempty"`
	URL		string		`json:"url,omitempty"`
	URLError	string		`json:"url_error,omitempty"`
}

type LazyDevStorageSnapshot ¶

LazyDevStorageSnapshot describes one configured storage backend.

type LazyDevStorageSnapshot struct {
	Name		string	`json:"name"`
	Default		bool	`json:"default,omitempty"`
	Readable	bool	`json:"readable"`
	Writable	bool	`json:"writable"`
	Deletable	bool	`json:"deletable"`
	Listable	bool	`json:"listable"`
	URLable		bool	`json:"urlable"`
}

type LazyDevVariantSnapshot ¶

LazyDevVariantSnapshot describes one generated media variant.

type LazyDevVariantSnapshot struct {
	SourceFileID	string		`json:"source_file_id"`
	VariantKey	string		`json:"variant_key"`
	Spec		json.RawMessage	`json:"spec,omitempty"`
	OutputFileID	string		`json:"output_file_id,omitempty"`
	OutputURL	string		`json:"output_url,omitempty"`
	OutputURLError	string		`json:"output_url_error,omitempty"`
	Status		string		`json:"status,omitempty"`
	Error		string		`json:"error,omitempty"`
	CreatedAt	time.Time	`json:"created_at,omitempty"`
	UpdatedAt	time.Time	`json:"updated_at,omitempty"`
}

type Media ¶

Media resolves and generates file representations.

type Media struct {
	Files		FileStore
	Repository	Repository
	Processor	Processor
}

func (m *Media) ListVariants ¶

ListVariants returns repository variants when the repository supports enumeration.

func (m *Media) ListVariants(ctx context.Context, query VariantListQuery, options ...any) ([]Variant, []any, error)

func (m *Media) URL ¶

URL returns the URL for a ready or generated variant.

func (m *Media) URL(ctx context.Context, request Request, options ...any) (string, []any, error)

func (m *Media) Variant ¶

Variant returns a ready variant, generating it when missing or requested.

func (m *Media) Variant(ctx context.Context, request Request, options ...any) (File, []any, error)

type OutputFilename ¶

OutputFilename requests a filename for the generated file.

type OutputFilename struct {
	Name string
}

type Processor ¶

Processor generates a representation for a source file.

type Processor interface {
	Process(context.Context, Source, Request, ...any) (Result, []any, error)
}

type ProcessorFunc ¶

ProcessorFunc adapts a function to Processor.

type ProcessorFunc func(context.Context, Source, Request, ...any) (Result, []any, error)

func (fn ProcessorFunc) Process ¶

func (fn ProcessorFunc) Process(ctx context.Context, source Source, request Request, options ...any) (Result, []any, error)

type Regenerate ¶

Regenerate bypasses an existing ready variant and generates it again.

type Regenerate struct{}

type Repository ¶

Repository stores variant relationships.

type Repository interface {
	FindVariant(context.Context, string, string, ...any) (Variant, []any, error)
	SaveVariant(context.Context, Variant, ...any) (Variant, []any, error)
	DeleteVariant(context.Context, string, string, ...any) ([]any, error)
}

type Request ¶

Request asks for a generated representation.

type Request struct {
	SourceFileID	string
	VariantKey	string
	Spec		json.RawMessage
}

type Result ¶

Result is the generated file body and metadata returned by processors.

type Result struct {
	Body		io.Reader
	ContentType	string
	Filename	string
	Options		[]any
}

type Source ¶

Source is an opened source file passed to processors.

type Source struct {
	File	File
	Body	io.ReadCloser
}

type Spec ¶

Spec supplies opaque app-defined JSON for the requested representation.

type Spec struct {
	JSON json.RawMessage
}

type Variant ¶

Variant identifies a generated representation of a source file.

type Variant struct {
	SourceFileID	string		`json:"source_file_id"`
	VariantKey	string		`json:"variant_key"`
	Spec		json.RawMessage	`json:"spec,omitempty"`
	OutputFileID	string		`json:"output_file_id,omitempty"`
	Status		string		`json:"status,omitempty"`
	Error		string		`json:"error,omitempty"`
	CreatedAt	time.Time	`json:"created_at,omitempty"`
	UpdatedAt	time.Time	`json:"updated_at,omitempty"`
}

type VariantKey ¶

VariantKey selects a named representation.

type VariantKey struct {
	Key string
}

type VariantListQuery ¶

VariantListQuery filters repository variant listings.

type VariantListQuery struct {
	SourceFileID	string
	VariantKey	string
	Status		string
}

type VariantLister ¶

VariantLister is implemented by repositories that can enumerate variants.

type VariantLister interface {
	ListVariants(context.Context, VariantListQuery, ...any) ([]Variant, []any, error)
}

Directories ¶

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