Documentation
¶
Overview ¶
Package directory is the plugin directory: the registry behind goblog.live/plugins. Repositories are submitted at /plugins/submit, validated and built here, approved in Admin → Plugins, and served as the listing, per-plugin pages and the machine-readable /plugins/index.json that every goblog's installer reads. It is compiled in and disabled by default; any goblog can host a directory by enabling it.
Index ¶
- Constants
- Variables
- func Migrate(db *gorm.DB) error
- func ParseRepo(input string) (string, error)
- func ValidName(name string) bool
- type Build
- type Detail
- type Entry
- type Plugin
- func (p *Plugin) DisplayName() string
- func (p *Plugin) Hosted() bool
- func (p *Plugin) Name() string
- func (p *Plugin) OnInit(db *gorm.DB) error
- func (p *Plugin) Pages() []gplugin.PageDefinition
- func (p *Plugin) RenderPage(ctx *gplugin.HookContext, pageType string) (string, gin.H)
- func (p *Plugin) ScheduledJobs() []gplugin.ScheduledJob
- func (p *Plugin) Search(ctx *gplugin.HookContext, query string) []gplugin.SearchResult
- func (p *Plugin) Service() *Service
- func (p *Plugin) SetSource(f func(token string) registry.Source)
- func (p *Plugin) SetThemeValidator(v registry.ThemeValidator)
- func (p *Plugin) SetUserAgent(ua string)
- func (p *Plugin) SetValidator(v registry.Validator)
- func (p *Plugin) Settings() []gplugin.SettingDefinition
- func (p *Plugin) Sitemap(ctx *gplugin.HookContext) []gplugin.SitemapURL
- func (p *Plugin) Token() string
- func (p *Plugin) Version() string
- type Release
- type Repo
- type RepoView
- type Service
- func (s *Service) Add(ctx context.Context, kind, input, token string) (*Repo, error)
- func (s *Service) Approve(id uint) error
- func (s *Service) Delist(id uint) error
- func (s *Service) Detail(kind, name string) (registry.DetailDoc, bool)
- func (s *Service) Get(id uint) (RepoView, registry.DetailDoc, error)
- func (s *Service) Index(kind string) ([]byte, []registry.IndexEntry)
- func (s *Service) LastRefresh() time.Time
- func (s *Service) List(status string) ([]RepoView, error)
- func (s *Service) Rebuild(ctx context.Context, id uint, token string) error
- func (s *Service) RefreshAll(ctx context.Context, token string) error
- func (s *Service) Reject(id uint, reason string) error
- func (s *Service) Submit(ctx context.Context, kind, input, ip, token string) (*Repo, error)
- type ValidationError
Constants ¶
const ( StatusPending = "pending" StatusApproved = "approved" StatusRejected = "rejected" )
Submission states of a repository in the directory.
const ( KindPlugin = registry.KindPlugin KindTheme = registry.KindTheme )
Kinds of entry the directory curates; aliases of the registry's.
const KindAuto = ""
KindAuto asks the service to tell a plugin from a theme by the manifest the repository's latest release carries.
const PageType = "plugin-directory"
PageType is the page type this plugin owns.
const ThemePageType = "theme-directory"
ThemePageType is the page type of /themes.
Variables ¶
var ( ErrAlreadyListed = errors.New("this repository is already listed in the directory") ErrUnderReview = errors.New("this repository is already under review") ErrNameTaken = errors.New("a different repository already publishes an entry with this name") ErrRateLimited = errors.New("too many submissions from your address; try again in an hour") ErrBusy = errors.New("another submission is being checked; try again in a minute") ErrQueueFull = errors.New("the review queue is full; try again in a few days") ErrNotFound = errors.New("no such repository") ErrBadKind = errors.New("kind must be plugin or theme") )
Errors the submit page and the admin API turn into messages and status codes. Their text is shown to submitters as-is.
var ErrBadRepo = errors.New("enter a GitHub repository URL like https://github.com/owner/repo, or just owner/repo")
ErrBadRepo is the message shown when the submitted text is not a GitHub repository.
Functions ¶
func Migrate ¶
Migrate creates or updates the directory's tables. Rows from before themes existed carry no kind and are plugins; the pre-kind unique index on name alone is dropped so a theme and a plugin may share a name.
Types ¶
type Build ¶
type Build struct {
ID uint `gorm:"primaryKey"`
RepoID uint `gorm:"uniqueIndex"`
Kind string `gorm:"uniqueIndex:idx_directory_builds_kind_name;size:16"`
Name string `gorm:"uniqueIndex:idx_directory_builds_kind_name;size:128"` // routes /plugins/<name> or /themes/<name>
Version string `gorm:"size:32"`
Stars int
// No type tag: gorm's default column for a Go string is already
// unbounded (longtext on MySQL, text on sqlite/postgres). A fixed
// "text" tag would cap this at MySQL's 64 KiB text limit, which a
// detail doc (README + changelog + per-release notes HTML) can exceed.
Doc string // registry.DetailDoc as JSON
BuiltAt time.Time
LastAttemptAt *time.Time
LastError string
}
Build is the last successful build of a repository: the detail document as JSON plus the columns the directory sorts and routes on. A failed rebuild leaves Doc alone and records LastError, so one broken release never takes a plugin off the directory.
type Detail ¶
Entry, Detail and Release are the wire types of index.json and /plugins/<name>.json. The registry package builds them; the installer (in every goblog) decodes them. They are aliases so both sides share one definition.
type Entry ¶
type Entry = registry.IndexEntry
Entry, Detail and Release are the wire types of index.json and /plugins/<name>.json. The registry package builds them; the installer (in every goblog) decodes them. They are aliases so both sides share one definition.
type Plugin ¶
type Plugin struct {
gplugin.BasePlugin
// contains filtered or unexported fields
}
Plugin is the directory plugin. Its Service exists once OnInit has run.
func (*Plugin) DisplayName ¶
func (*Plugin) OnInit ¶
OnInit migrates the registry tables, creates the Service and ensures the directory page exists. The registry's ensurePages already creates the page for every plugin before OnInit runs, so this normally finds the row in place and is kept as a fallback. The admin can rename or reorder it.
blog.Page.Slug has a unique index, so if some other page already uses the "plugins" slug (a different page type), creating our page would fail; a post type on that slug would be shadowed by our page. Neither must abort plugin.Registry.Init, so we log a warning and leave it to the operator instead of returning an error.
func (*Plugin) Pages ¶
func (p *Plugin) Pages() []gplugin.PageDefinition
func (*Plugin) RenderPage ¶
RenderPage serves the listing (""), the raw index ("index.json"), the submission page ("submit"), one plugin's page ("<name>") and its JSON ("<name>.json"). Anything else — including plugins that are not approved — is declined, which blog turns into a 404.
func (*Plugin) ScheduledJobs ¶
func (p *Plugin) ScheduledJobs() []gplugin.ScheduledJob
ScheduledJobs ticks every minute and refreshes every listed plugin once the last refresh is older than refresh_minutes, so the setting takes effect without a restart.
func (*Plugin) Search ¶
func (p *Plugin) Search(ctx *gplugin.HookContext, query string) []gplugin.SearchResult
Search answers the site search (plugin.Searcher) with matching plugins, then matching themes, linking to their pages under whatever slug the admin gave each page.
func (*Plugin) SetThemeValidator ¶
func (p *Plugin) SetThemeValidator(v registry.ThemeValidator)
SetThemeValidator replaces the theme validator (tests).
func (*Plugin) SetUserAgent ¶
SetUserAgent sets the User-Agent sent to GitHub.
func (*Plugin) SetValidator ¶
SetValidator replaces the module validator (tests).
func (*Plugin) Settings ¶
func (p *Plugin) Settings() []gplugin.SettingDefinition
func (*Plugin) Sitemap ¶
func (p *Plugin) Sitemap(ctx *gplugin.HookContext) []gplugin.SitemapURL
Sitemap lists every approved plugin and theme page (plugin.Sitemapper), under whatever slug the admin gave each directory page, with the entry's release date as its last change.
type Release ¶
type Release = registry.ReleaseDoc
Entry, Detail and Release are the wire types of index.json and /plugins/<name>.json. The registry package builds them; the installer (in every goblog) decodes them. They are aliases so both sides share one definition.
type Repo ¶
type Repo struct {
ID uint `gorm:"primaryKey" json:"id"`
Repo string `gorm:"uniqueIndex;size:255" json:"repo"` // owner/name, lower-case; a repo is one kind
Kind string `gorm:"index;size:16" json:"kind"` // plugin or theme
Status string `gorm:"index;size:16" json:"status"`
SubmittedAt time.Time `json:"submitted_at"`
DecidedAt *time.Time `json:"decided_at"`
RejectReason string `json:"reject_reason"`
// SubmitterIP is kept for the admin's benefit and blanked by the
// scheduled job after 7 days.
SubmitterIP string `gorm:"size:64" json:"-"`
}
Repo is one GitHub repository that was ever submitted to this directory: the curation record. Its build (what gets published) is a separate row because the two change on different schedules.
type RepoView ¶
type RepoView struct {
ID uint `json:"id"`
Repo string `json:"repo"`
Status string `json:"status"`
Kind string `json:"kind"`
SubmittedAt time.Time `json:"submitted_at"`
DecidedAt *time.Time `json:"decided_at"`
RejectReason string `json:"reject_reason"`
Name string `json:"name"`
DisplayName string `json:"display_name"`
Version string `json:"version"`
Author string `json:"author"`
License string `json:"license"`
Stars int `json:"stars"`
AllowedHosts []string `json:"allowed_hosts"`
MinGoblogVersion string `json:"min_goblog_version"`
SourceURL string `json:"source_url"`
ScreenshotURL string `json:"screenshot_url,omitempty"`
BuiltAt time.Time `json:"built_at"`
LastAttemptAt *time.Time `json:"last_attempt_at"`
LastError string `json:"last_error"`
}
RepoView is a curation record with its build summarised: what the admin list shows.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the registry: it validates and builds repositories, keeps the curation state in the database and serves the current index from memory.
func NewService ¶
func NewService(db *gorm.DB, newSource func(token string) registry.Source, val registry.Validator, tv registry.ThemeValidator, siteURL func() string) *Service
NewService wires a Service. newSource is called per operation with the current github_token setting so a token change needs no restart.
func (*Service) Index ¶
func (s *Service) Index(kind string) ([]byte, []registry.IndexEntry)
Index returns the current index.json bytes and entries for kind, generating them on first use.
func (*Service) LastRefresh ¶
LastRefresh is when RefreshAll last ran (zero if never).
func (*Service) List ¶
List returns repositories (newest submission first), optionally filtered by status.
func (*Service) RefreshAll ¶
RefreshAll is the scheduled rebuild of every approved repository. One failure does not stop the others; all are returned joined. It also blanks submitter addresses older than ipRetention.
type ValidationError ¶
type ValidationError struct{ Msg string }
ValidationError is a submission that failed the plugin contract. Msg is the registry's error text, the same message CI used to give.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string