Documentation
¶
Overview ¶
Package installer installs, updates and removes themes from the theme directory at runtime, for the admin UI. A theme is a directory of templates and static files: install means download the release archive, check its content hash against the index, check the templates parse, and unpack it under the installed root.
Index ¶
- Constants
- Variables
- func ScreenshotPath(name string) string
- type Available
- type Installed
- type Installer
- func (i *Installer) ActivateTheme(name string) error
- func (i *Installer) AutoUpdate(ctx context.Context) []Result
- func (i *Installer) Install(ctx context.Context, name string) (Result, error)
- func (i *Installer) Refresh() error
- func (i *Installer) Status() Status
- func (i *Installer) Sweep() error
- func (i *Installer) Uninstall(name string) error
- func (i *Installer) Update(ctx context.Context, name string) (Result, error)
- type Result
- type Status
Constants ¶
const DefaultIndexURL = "https://www.goblog.live/themes/index.json"
DefaultIndexURL is the public theme directory index.
Variables ¶
var ( ErrNotFound = errors.New("this theme is not in the directory") ErrNotTheme = errors.New("this directory entry is not a theme") ErrIncompatible = errors.New("this theme requires a newer goblog") ErrChecksum = errors.New("the downloaded archive does not match the directory index; the index may be stale, refresh and try again") ErrAlreadyInstalled = errors.New("a theme with this name is already installed") ErrNotInstalled = errors.New("this theme is not installed") ErrNotManaged = errors.New("this theme was copied in by hand, not installed from the directory; remove or rename it to install the directory version") ErrBuiltin = errors.New("built-in themes cannot be installed, updated or removed") ErrActive = errors.New("the active theme cannot be removed; activate another theme first") ErrLoad = errors.New("the theme failed to load") ErrUpToDate = errors.New("theme is already at the directory's version") ErrDownload = errors.New("could not download the theme") ErrWrite = errors.New("could not write to the installed themes directory; check that it exists and goblog can write to it") )
Typed errors; the admin API maps them to 4xx responses with their text.
Functions ¶
func ScreenshotPath ¶
ScreenshotPath is the admin route that serves an on-disk theme's own screenshot (see theme.Screenshot). A theme name is letters, digits, "_" and "-" (theme.ValidName), which the escape leaves untouched; it is there so the helper stays a valid single path segment for any input.
Types ¶
type Available ¶
type Available struct {
directory.Entry
Compatible bool `json:"compatible"`
Reason string `json:"reason,omitempty"`
}
Available is a directory theme that is not installed.
type Installed ¶
type Installed struct {
Name string `json:"name"`
DisplayName string `json:"display_name"`
Version string `json:"version,omitempty"`
Builtin bool `json:"builtin"`
Active bool `json:"active"`
UpdateAvailable bool `json:"update_available"`
LatestVersion string `json:"latest_version,omitempty"`
// ScreenshotURL previews the theme: the admin route serving its own
// screenshot.png when it has one on disk (built-ins ship one), else
// the directory's screenshot when the index lists it, else empty.
ScreenshotURL string `json:"screenshot_url,omitempty"`
}
Installed is a theme goblog can activate.
type Installer ¶
type Installer struct {
Dir string // where installs go (theme.InstalledRoot())
Directory *pinstaller.Fetcher // own instance, pointed at the themes index
Version string // running goblog version
Client *http.Client // downloads; nil → 60s timeout default
IndexURL func() string // theme_directory_url setting
ActiveTheme func() string // the theme currently rendering
Activate func(name string) error // persist the setting and hot-reload
// contains filtered or unexported fields
}
Installer wires the themes index, the theme roots and the active-theme setting together.
func (*Installer) ActivateTheme ¶
ActivateTheme makes name the site's theme (built-in or installed).
func (*Installer) AutoUpdate ¶
AutoUpdate updates every installed directory theme that Status says has a compatible update. A failure is logged and leaves that theme as it was; it never stops the others.
func (*Installer) Status ¶
Status lists every theme on disk (with update info for installed ones) and the directory themes that are not installed.
func (*Installer) Sweep ¶
Sweep cleans up what a crash inside place can leave under Dir, and is meant to run once at startup, before any install. Two kinds of leftover exist:
- ".<name>.tmp-<n>": an unpack that was never renamed into place. It is removed even when it looks complete, because a crash while it was still being written leaves the same shape; the admin re-runs the install or update and gets a verified copy.
- "<name>.prev": the previous version, set aside for the swap. If "<name>" exists the swap finished and only the removal of .prev was lost, so .prev is dropped. If "<name>" is missing the crash hit between the two renames and the theme has vanished from disk; the previous version is renamed back so the site keeps the theme it had, rather than promoting a tmp directory whose completeness is unknown.
Anything else in Dir — installed themes, files, directories of another shape — is left alone. Every recoverable problem is attempted; the failures are returned together so the caller can log them, since none is worth refusing to start over.
func (*Installer) Uninstall ¶
Uninstall removes an installed theme; built-ins and the active theme are refused.
type Result ¶
type Result struct {
Name string `json:"name"`
Version string `json:"version"`
Message string `json:"message"`
}
Result reports a successful install or update.
type Status ¶
type Status struct {
Installed []Installed `json:"installed"`
Available []Available `json:"available"`
Active string `json:"active"`
DirectoryURL string `json:"directory_url"`
IndexFetchedAt string `json:"index_fetched_at,omitempty"`
IndexError string `json:"index_error,omitempty"`
DirWritable bool `json:"dir_writable"`
DirError string `json:"dir_error,omitempty"`
}
Status is everything the admin page needs in one call.