library

Documentation

Index

• Constants
• func ImageDimensions(root *os.Root, name string) (w, h int)
• func IsSyncedName(name string) bool
• func SyncedFilename(a Asset) string
• func ValidImageName(name string) bool
• type Advancer
• type AspectStore
  • func LoadAspectStore(log *slog.Logger, root *os.Root) (*AspectStore, error)
  • func (s *AspectStore) BackfillMissing(ctx context.Context, lib *Library) bool
  • func (s *AspectStore) Delete(name string)
  • func (s *AspectStore) Flush() error
  • func (s *AspectStore) Missing(names []string) []string
  • func (s *AspectStore) Ratio(name string) (ratio float64, ok bool)
  • func (s *AspectStore) Set(name string, w, h int)
• type Asset
• type Image
• type Library
  • func New(images []Image, randomize bool, opts ...Option) *Library
  • func (l *Library) Add(name string)
  • func (l *Library) Cycle() []Image
  • func (l *Library) Has(name string) bool
  • func (l *Library) Len() int
  • func (l *Library) List() []Image
  • func (l *Library) Randomized() bool
  • func (l *Library) Remove(name string) bool
  • func (l *Library) Reshuffle() []Image
  • func (l *Library) SetOrder(names []string) []string
  • func (l *Library) SetRandomize(enabled bool) bool
• type Option
  • func WithTestRNG(rng *rand.Rand) Option
• type OrderStore
  • func LoadOrderStore(log *slog.Logger, root *os.Root) (*OrderStore, []string, error)
  • func (s *OrderStore) Save(names []string) error
• type RemoteAlbum
• type Status
• type Syncer
  • func NewSyncer(log *slog.Logger, remote RemoteAlbum, lib *Library, root *os.Root, ...) *Syncer
  • func (s *Syncer) Run(ctx context.Context)
  • func (s *Syncer) Status() Status
  • func (s *Syncer) Trigger()
• type SyncerOption
  • func WithAspectStore(a *AspectStore) SyncerOption
• type SyncerStatus

Constants

const ImageNamePattern = `^[a-zA-Z0-9_.~-]+\.(jpe?g|png)$`

ImageNamePattern is the canonical image filename rule; the HTTP routes embed it as a huma `pattern` tag (a test keeps them in sync).

Functions

func ImageDimensions

func ImageDimensions(root *os.Root, name string) (w, h int)

ImageDimensions reads an image's pixel size from its header only (no full decode); returns 0,0 on any error.

func IsSyncedName

func IsSyncedName(name string) bool

IsSyncedName reports whether name matches the synced-file pattern.

func SyncedFilename

func SyncedFilename(a Asset) string

SyncedFilename returns the canonical local name for an asset. Panics on an empty Version, which would produce an unparseable name and loop in the diff.

func ValidImageName

func ValidImageName(name string) bool

ValidImageName reports whether name is servable by the /img/{name} route.

Types

type Advancer

type Advancer interface {
	Next()
}

Advancer is poked when the syncer brings an empty library to non-empty.

type AspectStore

type AspectStore struct {
	// contains filtered or unexported fields
}

AspectStore caches per-image aspect ratios as a JSON sidecar in the images directory, captured once at upload/sync so reads never decode. Safe for concurrent use.

func LoadAspectStore

func LoadAspectStore(log *slog.Logger, root *os.Root) (*AspectStore, error)

LoadAspectStore reads the sidecar index from root (empty when absent).

func (*AspectStore) BackfillMissing

func (s *AspectStore) BackfillMissing(ctx context.Context, lib *Library) bool

BackfillMissing decodes and stores dimensions for any library image absent from the index, then persists once. Meant to run in the background at startup. It reports whether it recorded anything, so the caller can rebuild a plan that was built before the ratios were available.

func (*AspectStore) Delete

func (s *AspectStore) Delete(name string)

Delete drops name in memory; call Flush to persist.

func (*AspectStore) Flush

func (s *AspectStore) Flush() error

Flush writes the index atomically (tmp + rename) through the images root.

func (*AspectStore) Missing

func (s *AspectStore) Missing(names []string) []string

Missing returns the subset of names with no cached dimensions.

func (*AspectStore) Ratio

func (s *AspectStore) Ratio(name string) (ratio float64, ok bool)

Ratio returns the cached width/height for name; ok is false when the name is absent or has no usable height.

func (*AspectStore) Set

func (s *AspectStore) Set(name string, w, h int)

Set records dimensions for name in memory; call Flush to persist.

type Asset

type Asset struct {
	ID      string // stable identity; used as the filename stem
	Version string // opaque change token; a new value means re-download
}

Asset is one image in a RemoteAlbum.

type Image

type Image struct {
	Name string // filename only, e.g. "1716038400000.jpg"
}

Image represents a stored image file.

type Library

type Library struct {
	// contains filtered or unexported fields
}

Library maintains the canonical image order (admin source of truth) plus the current playback cycle, a shuffled copy when randomized. Safe for concurrent use.

func New

func New(images []Image, randomize bool, opts ...Option) *Library

New creates a Library with the given canonical order and an initial cycle.

func (*Library) Add

func (l *Library) Add(name string)

Add appends a new image to the canonical order and the current cycle so it shows without waiting for a reshuffle.

func (*Library) Cycle

func (l *Library) Cycle() []Image

Cycle returns a copy of the current playback order.

func (*Library) Has

func (l *Library) Has(name string) bool

Has reports whether an image with the given name is present.

func (*Library) Len

func (l *Library) Len() int

Len returns the number of images.

func (*Library) List

func (l *Library) List() []Image

List returns a copy of the canonical order (what the admin UI shows/edits).

func (*Library) Randomized

func (l *Library) Randomized() bool

Randomized reports whether playback is shuffled.

func (*Library) Remove

func (l *Library) Remove(name string) bool

Remove deletes the first image with name from both slices; false if absent from the canonical order.

func (*Library) Reshuffle

func (l *Library) Reshuffle() []Image

Reshuffle starts a new playback cycle from the canonical order and returns a copy. Randomized cycles avoid repeating the previous cycle's last image first.

func (*Library) SetOrder

func (l *Library) SetOrder(names []string) []string

SetOrder reorders the canonical order to match names: unknown names are ignored and ones missing from names keep their relative order at the end (so a stale payload never drops a file). Returns the resulting names to persist.

func (*Library) SetRandomize

func (l *Library) SetRandomize(enabled bool) bool

SetRandomize toggles random playback and reports whether the value changed.

type Option

type Option func(*Library)

Option defines a functional configuration for the Library.

func WithTestRNG

func WithTestRNG(rng *rand.Rand) Option

WithTestRNG injects a deterministic random number generator for unit tests.

type OrderStore

type OrderStore struct {
	// contains filtered or unexported fields
}

OrderStore persists the canonical image order as a JSON array sidecar in the images directory. Safe for concurrent use.

func LoadOrderStore

func LoadOrderStore(log *slog.Logger, root *os.Root) (*OrderStore, []string, error)

LoadOrderStore reads the saved order from root; returns nil names when absent or corrupt.

func (*OrderStore) Save

func (s *OrderStore) Save(names []string) error

Save writes the order atomically (tmp + rename) through the images root.

type RemoteAlbum

type RemoteAlbum interface {
	List(ctx context.Context) ([]Asset, error)
	Fetch(ctx context.Context, id string) (io.ReadCloser, error)
}

RemoteAlbum is a read-only view of an album in a remote photo service.

type Status

type Status struct {
	LastSync   time.Time
	AssetCount int
	LastError  string
}

Status reports the latest sync outcome for the admin UI.

type Syncer

type Syncer struct {
	// contains filtered or unexported fields
}

Syncer reconciles a RemoteAlbum with a local directory and Library on a tick. Files are named "<asset-id>-<version>.jpg" so an edit upstream (new version) becomes a new local file: old version deleted, new version downloaded.

func NewSyncer

func NewSyncer(log *slog.Logger, remote RemoteAlbum, lib *Library, root *os.Root, interval time.Duration, advance Advancer, opts ...SyncerOption) *Syncer

func (*Syncer) Run

func (s *Syncer) Run(ctx context.Context)

Run syncs immediately then on each interval (or on Trigger) until ctx is cancelled.

func (*Syncer) Status

func (s *Syncer) Status() Status

Status returns the latest sync outcome. Safe from any goroutine.

func (*Syncer) Trigger

func (s *Syncer) Trigger()

Trigger requests an out-of-band sync. Non-blocking; coalesces if one is queued.

type SyncerOption

type SyncerOption func(*Syncer)

SyncerOption configures optional Syncer collaborators.

func WithAspectStore

func WithAspectStore(a *AspectStore) SyncerOption

WithAspectStore records downloaded dimensions and clears them on removal.

type SyncerStatus

type SyncerStatus interface {
	Status() Status
	Trigger()
}

SyncerStatus is the read-and-trigger surface over a Syncer. Callers that may hold no syncer (the fs backend) keep it behind this interface so a nil syncer reads as a nil interface rather than a typed-nil.