directory

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

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

View Source
const (
	StatusPending  = "pending"
	StatusApproved = "approved"
	StatusRejected = "rejected"
)

Submission states of a repository in the directory.

View Source
const (
	KindPlugin = registry.KindPlugin
	KindTheme  = registry.KindTheme
)

Kinds of entry the directory curates; aliases of the registry's.

View Source
const KindAuto = ""

KindAuto asks the service to tell a plugin from a theme by the manifest the repository's latest release carries.

View Source
const PageType = "plugin-directory"

PageType is the page type this plugin owns.

View Source
const ThemePageType = "theme-directory"

ThemePageType is the page type of /themes.

Variables

View Source
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.

View Source
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

func Migrate(db *gorm.DB) error

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.

func ParseRepo

func ParseRepo(input string) (string, error)

ParseRepo turns what a person typed into the canonical "owner/repo" key (lower-case, so the same repository cannot be submitted twice under different capitalisation).

func ValidName

func ValidName(name string) bool

ValidName reports whether name follows the registry's plugin name rule (lowercase letters, digits and hyphens). Callers that pass a plugin name to the filesystem (the installer, when it derives a file path) must check this before doing so.

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.

func (*Build) Detail

func (b *Build) Detail() (registry.DetailDoc, error)

Detail decodes the stored document.

func (*Build) SetDoc

func (b *Build) SetDoc(d registry.DetailDoc) error

SetDoc stores d as this build: the indexed columns, the JSON, the build time, and a cleared error.

func (Build) TableName

func (Build) TableName() string

type Detail

type Detail = registry.DetailDoc

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 New

func New() *Plugin

New creates the directory plugin.

func (*Plugin) DisplayName

func (p *Plugin) DisplayName() string

func (*Plugin) Hosted

func (p *Plugin) Hosted() bool

Hosted reports whether this site runs a directory: initialised and enabled.

func (*Plugin) Name

func (p *Plugin) Name() string

func (*Plugin) OnInit

func (p *Plugin) OnInit(db *gorm.DB) error

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

func (p *Plugin) RenderPage(ctx *gplugin.HookContext, pageType string) (string, gin.H)

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) Service

func (p *Plugin) Service() *Service

Service is the registry behind the pages; nil until OnInit has run.

func (*Plugin) SetSource

func (p *Plugin) SetSource(f func(token string) registry.Source)

SetSource replaces the GitHub client factory (tests, or a mirror).

func (*Plugin) SetThemeValidator

func (p *Plugin) SetThemeValidator(v registry.ThemeValidator)

SetThemeValidator replaces the theme validator (tests).

func (*Plugin) SetUserAgent

func (p *Plugin) SetUserAgent(ua string)

SetUserAgent sets the User-Agent sent to GitHub.

func (*Plugin) SetValidator

func (p *Plugin) SetValidator(v registry.Validator)

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.

func (*Plugin) Token

func (p *Plugin) Token() string

Token is the configured github_token ("" for anonymous access).

func (*Plugin) Version

func (p *Plugin) Version() string

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.

func (Repo) TableName

func (Repo) TableName() string

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) Add

func (s *Service) Add(ctx context.Context, kind, input, token string) (*Repo, error)

Add is the admin path: same validation, no rate limit, listed at once.

func (*Service) Approve

func (s *Service) Approve(id uint) error

Approve lists a pending or rejected repository.

func (*Service) Delist

func (s *Service) Delist(id uint) error

Delist forgets a repository entirely; it can be submitted again later.

func (*Service) Detail

func (s *Service) Detail(kind, name string) (registry.DetailDoc, bool)

Detail returns the document of an approved entry of kind by name.

func (*Service) Get

func (s *Service) Get(id uint) (RepoView, registry.DetailDoc, error)

Get returns one repository with its full document (README and all).

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

func (s *Service) LastRefresh() time.Time

LastRefresh is when RefreshAll last ran (zero if never).

func (*Service) List

func (s *Service) List(status string) ([]RepoView, error)

List returns repositories (newest submission first), optionally filtered by status.

func (*Service) Rebuild

func (s *Service) Rebuild(ctx context.Context, id uint, token string) error

Rebuild re-validates one repository now (admin action).

func (*Service) RefreshAll

func (s *Service) RefreshAll(ctx context.Context, token string) error

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.

func (*Service) Reject

func (s *Service) Reject(id uint, reason string) error

Reject takes a repository off the directory (or keeps it off) with a reason only the admin sees.

func (*Service) Submit

func (s *Service) Submit(ctx context.Context, kind, input, ip, token string) (*Repo, error)

Submit is the public path: parse, refuse duplicates, rate-limit, validate and build synchronously, then queue the repository for review.

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

Directories

Path Synopsis
Package registry validates goblog plugin repositories and builds the directory's index and detail documents.
Package registry validates goblog plugin repositories and builds the directory's index and detail documents.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL