registry

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

View Source
const (
	KindPlugin = "plugin"
	KindTheme  = "theme"
)

Kinds of entry the directory publishes.

View Source
const MaxArchiveEntries = 2000

MaxArchiveEntries bounds a theme archive; a theme is a few dozen files.

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

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

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

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

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is returned by Source.File when the ref or path does not exist.

View Source
var NamePattern = regexp.MustCompile(`^[a-z0-9-]+$`)

NamePattern is the rule for plugin names; the directory routes on it.

View Source
var TagPattern = regexp.MustCompile(`^v\d+\.\d+\.\d+$`)

TagPattern is the release tag rule: vX.Y.Z, nothing else.

Functions

func ContentHash

func ContentHash(files map[string][]byte) string

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

func DetectKind(ctx context.Context, src Source, repo string) (string, error)

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

func LatestVersion(ctx context.Context, src Source, repo string) (string, error)

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

func ParseArchive(zipBytes []byte) (map[string][]byte, error)

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.

func Sum

func Sum(b []byte) string

Sum is the hex sha256 of b — the index's sha256 field and the key FakeValidator answers by.

Types

type Asset

type Asset struct {
	ID          int64
	Name        string
	Size        int
	DownloadURL string // browser_download_url
}

Asset is a file attached to a GitHub release.

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.

func (*FakeThemeValidator) Validate

func (f *FakeThemeValidator) Validate(context.Context, map[string][]byte) error

type FakeValidator

type FakeValidator struct {
	Infos map[string]plugin.Info
	Err   error
}

FakeValidator answers by the sha256 of the module bytes it is given. It is exported so the directory package's tests can use it.

func (*FakeValidator) Validate

func (f *FakeValidator) Validate(_ context.Context, module []byte) (plugin.Info, error)

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

func (g *GitHubSource) File(ctx context.Context, owner, repo, ref, path string) ([]byte, error)

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 (g *GitHubSource) ReleaseAsset(ctx context.Context, owner, repo string, assetID int64) ([]byte, error)

func (*GitHubSource) Releases

func (g *GitHubSource) Releases(ctx context.Context, owner, repo string) ([]Release, error)

func (*GitHubSource) RenderMarkdown

func (g *GitHubSource) RenderMarkdown(ctx context.Context, ownerRepo, markdown string) (string, error)

func (*GitHubSource) RepoStars

func (g *GitHubSource) RepoStars(ctx context.Context, owner, repo string) (int, error)

func (*GitHubSource) SetUserAgent

func (g *GitHubSource) SetUserAgent(ua string)

SetUserAgent sets the User-Agent sent to GitHub (which requires one).

func (*GitHubSource) Zipball

func (g *GitHubSource) Zipball(ctx context.Context, owner, repo, ref string) ([]byte, error)

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

func ParseManifest(b []byte) (Manifest, error)

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

type ThemeValidator interface {
	Validate(ctx context.Context, files map[string][]byte) error
}

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

func ValidateEntry(ctx context.Context, src Source, val Validator, repo string) (*Validated, error)

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

type Validator interface {
	Validate(ctx context.Context, module []byte) (plugin.Info, error)
}

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.

func (WasmValidator) Validate

func (WasmValidator) Validate(ctx context.Context, module []byte) (plugin.Info, error)

Jump to

Keyboard shortcuts

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