Documentation
¶
Overview ¶
Package registry validates goblog plugin repositories and builds the directory's index and detail documents. It is what the goblogplatform/ plugins registry tool used to do in CI; goblog.live now does it itself from the directory plugin.
Index ¶
- Constants
- Variables
- func ContentHash(files map[string][]byte) string
- func DetectKind(ctx context.Context, src Source, repo string) (string, error)
- func KnownLicenses() []string
- func LatestVersion(ctx context.Context, src Source, repo string) (string, error)
- func ParseArchive(zipBytes []byte) (map[string][]byte, error)
- func Sum(b []byte) string
- type Asset
- type DetailDoc
- type FakeThemeValidator
- type FakeValidator
- type GitHubSource
- func (g *GitHubSource) File(ctx context.Context, owner, repo, ref, path string) ([]byte, error)
- func (g *GitHubSource) FileURL(owner, repo, ref, path string) string
- func (g *GitHubSource) ReleaseAsset(ctx context.Context, owner, repo string, assetID int64) ([]byte, error)
- func (g *GitHubSource) Releases(ctx context.Context, owner, repo string) ([]Release, error)
- func (g *GitHubSource) RenderMarkdown(ctx context.Context, ownerRepo, markdown string) (string, error)
- func (g *GitHubSource) RepoStars(ctx context.Context, owner, repo string) (int, error)
- func (g *GitHubSource) SetUserAgent(ua string)
- func (g *GitHubSource) Zipball(ctx context.Context, owner, repo, ref string) ([]byte, error)
- type IndexEntry
- type Manifest
- type Release
- type ReleaseDoc
- type Source
- type ThemeManifest
- type ThemeValidator
- type Validated
- type ValidatedTheme
- type Validator
- type WasmValidator
Constants ¶
const ( KindPlugin = "plugin" KindTheme = "theme" )
Kinds of entry the directory publishes.
const MaxArchiveEntries = 2000
MaxArchiveEntries bounds a theme archive; a theme is a few dozen files.
const MaxAssetBytes = 16 << 20
MaxAssetBytes is the largest release asset the registry will download and validate (16 MiB); goblog's installer applies the same cap.
const MaxRenderedBytes = 1 << 20
MaxRenderedBytes caps the README, changelog and per-release notes HTML BuildRepo will accept from GitHub's markdown API — a detail doc is stored whole in directory_builds.doc and served on every page view, so an oversized render (an author's README with an embedded base64 image, say) must be refused at build time rather than silently ballooning the database and every response.
const MaxScreenshotBytes = 1 << 20
MaxScreenshotBytes caps screenshot.png/.jpg. GitHub's contents API only returns files up to 1 MiB inline, so a larger screenshot could not be checked anyway.
const MaxTemplateBytes = 256 << 10
MaxTemplateBytes caps one templates/* entry in a theme archive. registry must not import theme (layering), so this is kept equal to theme.MaxTemplateBytes by hand; the installer applies that one when it re-validates the files it downloads.
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound is returned by Source.File when the ref or path does not exist.
var NamePattern = regexp.MustCompile(`^[a-z0-9-]+$`)
NamePattern is the rule for plugin names; the directory routes on it.
var TagPattern = regexp.MustCompile(`^v\d+\.\d+\.\d+$`)
TagPattern is the release tag rule: vX.Y.Z, nothing else.
Functions ¶
func ContentHash ¶
ContentHash is the index's sha256 for a theme: a hash of the extracted files rather than the archive bytes, because GitHub does not promise that a tag's zipball is byte-stable. Each file contributes its path, its length and its bytes, in path order.
func DetectKind ¶
DetectKind tells a plugin repository from a theme one by which manifest its latest release carries, so submitters need not say. Exactly one of goblog-plugin.json / goblog-theme.json must be present at the tag.
func KnownLicenses ¶
func KnownLicenses() []string
KnownLicenses returns the accepted SPDX identifiers, sorted; the docs tests check the published lists against it.
func LatestVersion ¶
LatestVersion is the version ValidateEntry would publish for repo, found without downloading anything. The scheduled rebuild uses it to skip repos whose latest release is already built.
func ParseArchive ¶
ParseArchive reads a theme archive (GitHub's tag zipball, or any zip with the same layout) into memory, keeping only templates/** and static/**. GitHub wraps everything in one "<repo>-<tag>/" folder, which is stripped when every entry shares it. Symlinks and paths that escape the archive are refused; the entry count and total size are bounded.
Types ¶
type DetailDoc ¶
type DetailDoc struct {
IndexEntry
ReadmeHTML template.HTML `json:"readme_html"`
ChangelogHTML template.HTML `json:"changelog_html"`
Releases []ReleaseDoc `json:"releases"`
}
DetailDoc is /plugins/<name>.json: the index entry plus rendered README, changelog and release history. The *_html fields come from GitHub's markdown API, which sanitizes them; they are the only fields pages insert unescaped.
func BuildRepo ¶
func BuildRepo(ctx context.Context, src Source, val Validator, repo, baseURL string) (DetailDoc, error)
BuildRepo validates repo end to end and returns the document the directory publishes for it. baseURL is the site's URL ("" makes detail_url relative).
func BuildTheme ¶
func BuildTheme(ctx context.Context, src Source, tv ThemeValidator, repo, baseURL string) (DetailDoc, error)
BuildTheme validates repo and returns the document the directory publishes for it under /themes.
type FakeThemeValidator ¶
type FakeThemeValidator struct{ Err error }
FakeThemeValidator accepts everything unless Err is set.
type FakeValidator ¶
FakeValidator answers by the sha256 of the module bytes it is given. It is exported so the directory package's tests can use it.
type GitHubSource ¶
type GitHubSource struct {
// contains filtered or unexported fields
}
GitHubSource implements Source with the GitHub REST API over net/http. It is deliberately dependency-free: five endpoints do not justify a client library in goblog's module graph.
func NewGitHubSource ¶
func NewGitHubSource(token, baseURL string) *GitHubSource
NewGitHubSource returns a Source for api.github.com (baseURL "") or a test server. token may be empty for unauthenticated access (60 requests per hour instead of 5000).
func (*GitHubSource) FileURL ¶
func (g *GitHubSource) FileURL(owner, repo, ref, path string) string
FileURL points at raw.githubusercontent.com, which serves repository files publicly without API quota.
func (*GitHubSource) ReleaseAsset ¶
func (*GitHubSource) RenderMarkdown ¶
func (*GitHubSource) SetUserAgent ¶
func (g *GitHubSource) SetUserAgent(ua string)
SetUserAgent sets the User-Agent sent to GitHub (which requires one).
type IndexEntry ¶
type IndexEntry struct {
Name string `json:"name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Version string `json:"version"`
Author string `json:"author"`
License string `json:"license"`
SourceURL string `json:"source_url"`
DownloadURL string `json:"download_url"`
SHA256 string `json:"sha256"`
MinGoblogVersion string `json:"min_goblog_version"`
InstallType string `json:"install_type"` // "wasm"
Runtime string `json:"runtime"` // "wasm"
AllowedHosts []string `json:"allowed_hosts"` // never null: [] when the plugin uses no network
ReleasedAt string `json:"released_at"` // RFC 3339
DetailURL string `json:"detail_url"`
Stars int `json:"stars"`
Kind string `json:"kind"` // "plugin" or "theme"
ScreenshotURL string `json:"screenshot_url,omitempty"` // themes only
}
IndexEntry is one element of index.json: the latest release of a plugin. Field names are the contract consumed by goblog's directory plugin and the admin installer; do not rename them.
type Manifest ¶
type Manifest struct {
Name string `json:"name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Author string `json:"author"`
License string `json:"license"`
Runtime string `json:"runtime"`
Entry string `json:"entry"`
AllowedHosts []string `json:"allowed_hosts"`
MinGoblogVersion string `json:"min_goblog_version"`
Homepage string `json:"homepage"`
}
Manifest is goblog-plugin.json at the root of a plugin repository.
func ParseManifest ¶
ParseManifest decodes and validates a manifest. Entry defaults to plugin.wasm; AllowedHosts is never nil on success so the index serialises it as [] rather than null.
type Release ¶
type Release struct {
Tag string
Name string
Body string // release notes, markdown
URL string
PublishedAt time.Time
Draft bool
Prerelease bool
Assets []Asset
}
Release is one GitHub release of a plugin repository.
type ReleaseDoc ¶
type ReleaseDoc struct {
Version string `json:"version"`
ReleasedAt string `json:"released_at"`
NotesHTML template.HTML `json:"notes_html"` // rendered and sanitized by GitHub's markdown API
URL string `json:"url"`
}
ReleaseDoc is one release in a plugin's history.
type Source ¶
type Source interface {
// Releases lists all releases, newest first as GitHub returns them,
// including drafts and pre-releases (callers filter).
Releases(ctx context.Context, owner, repo string) ([]Release, error)
// File returns the contents of path at ref; ErrNotFound when absent.
File(ctx context.Context, owner, repo, ref, path string) ([]byte, error)
// ReleaseAsset downloads a release asset by id (at most MaxAssetBytes).
ReleaseAsset(ctx context.Context, owner, repo string, assetID int64) ([]byte, error)
// RenderMarkdown renders GitHub-flavoured markdown to sanitized HTML in
// the context of ownerRepo (so `#123` and `@user` references resolve;
// relative links and images are left as-is).
RenderMarkdown(ctx context.Context, ownerRepo, markdown string) (string, error)
// RepoStars returns the repository's GitHub stargazer count (the
// directory's "top plugins" ordering).
RepoStars(ctx context.Context, owner, repo string) (stars int, err error)
// Zipball downloads the archive of ref (a tag) — at most MaxAssetBytes.
Zipball(ctx context.Context, owner, repo, ref string) ([]byte, error)
// FileURL is the public raw URL of path at ref (for hot-linked
// screenshots); no request is made.
FileURL(owner, repo, ref, path string) string
}
Source is what the registry needs from GitHub. It is an interface so the validator and builder are tested against an httptest fake.
type ThemeManifest ¶
type ThemeManifest struct {
Name string `json:"name"`
DisplayName string `json:"display_name"`
Description string `json:"description"`
Author string `json:"author"`
License string `json:"license"`
MinGoblogVersion string `json:"min_goblog_version"`
Homepage string `json:"homepage"`
}
ThemeManifest is goblog-theme.json at the root of a theme repository.
func ParseThemeManifest ¶
func ParseThemeManifest(b []byte) (ThemeManifest, error)
ParseThemeManifest decodes and validates a theme manifest.
type ThemeValidator ¶
ThemeValidator checks a theme's files the way goblog would load them. The real one (theme.ValidateFiles, wrapped by the directory plugin) parses the templates on top of the shared and default sets; tests use FakeThemeValidator.
type Validated ¶
type Validated struct {
Repo string // owner/name
Owner string
Name string // repository name (not the plugin name)
Manifest Manifest
Release Release // the latest published, non-prerelease release
Version string // Release.Tag without the leading v
Releases []Release // all published, non-prerelease releases, newest first
Readme []byte // README.md at Release.Tag, kept so the builder need not fetch it again
Asset Asset // the release asset named by Manifest.Entry
Entry []byte // the asset's bytes (the WebAssembly module)
SHA256 string // hex sha256 of Entry
}
Validated is a plugin repository that passed every check, with everything the index builder needs from it.
func ValidateEntry ¶
ValidateEntry checks one registry entry end to end: a published release tagged vX.Y.Z, a valid manifest and README at that tag, a release asset named by the manifest's entry that loads in goblog as a WebAssembly plugin, and an identity that matches the manifest and the tag.
type ValidatedTheme ¶
type ValidatedTheme struct {
Repo, Owner, Name string
Manifest ThemeManifest
Release Release
Version string
Releases []Release
Readme []byte // README.md at Release.Tag, kept so BuildTheme need not fetch it again
Files map[string][]byte // templates/** and static/**
SHA256 string // ContentHash(Files)
ScreenshotURL string
}
ValidatedTheme is a theme repository that passed every check.
func ValidateThemeEntry ¶
func ValidateThemeEntry(ctx context.Context, src Source, tv ThemeValidator, repo string) (*ValidatedTheme, error)
ValidateThemeEntry checks a theme repository end to end: a vX.Y.Z release, manifest, README and screenshot at that tag, and an archive whose templates load.
type Validator ¶
Validator loads a plugin module the way goblog would and reports its identity. The real one instantiates the module in-process; tests use FakeValidator.
type WasmValidator ¶
type WasmValidator struct{}
WasmValidator instantiates the module with goblog's own runtime — no store, no allowed hosts, the runtime's memory cap and call timeouts — and reads its identity export. That is the same sandbox an installed plugin runs in, so validating a submission is no more exposure than a site installing it.