Add frontend render plugin system support

contrib/render-plugins/example/README.md

@@ -0,0 +1,35 @@
+# Example Frontend Render Plugin
+
+This directory contains a minimal render plugin that highlights `.txt` files
+with a custom color scheme. Use it as a starting point for your own plugins or
+as a quick way to validate the dynamic plugin system locally.
+
+## Files
+
+- `manifest.json` — metadata (including the required `schemaVersion`) consumed by Gitea when installing a plugin
+- `render.js` — an ES module that exports a `render(container, fileUrl)`
+ function; it downloads the source file and renders it in a styled `<pre>`
+
+By default plugins may only fetch the file that is currently being rendered.
+If your plugin needs to contact Gitea APIs or any external services, list their
+domains under the `permissions` array in `manifest.json`. Requests to hosts that
+are not declared there will be blocked by the runtime.
+
+## Build & Install
+
+1. Create a zip archive that contains both files:
+
+ ```bash
+ cd contrib/render-plugins/example
+ zip -r ../example-highlight-txt.zip manifest.json render.js
+ ```
+
+2. In the Gitea web UI, visit `Site Administration → Render Plugins`, upload
+ `example-highlight-txt.zip`, and enable it.
+
+3. Open any `.txt` file in a repository; the viewer will display the content in
+ the custom colors to confirm the plugin is active.
+
+Feel free to modify `render.js` to experiment with the API. The plugin runs in
+the browser, so only standard Web APIs are available (no bundler is required
+as long as the file stays a plain ES module).

contrib/render-plugins/example/manifest.json

@@ -0,0 +1,10 @@
+{
+ "schemaVersion": 1,
+ "id": "example-highlight-txt",
+ "name": "Example TXT Highlighter",
+ "version": "1.0.0",
+ "description": "Simple sample plugin that renders .txt files with a custom color scheme.",
+ "entry": "render.js",
+ "filePatterns": ["*.txt"],
+ "permissions": []
+}

contrib/render-plugins/example/render.js

@@ -0,0 +1,28 @@
+const TEXT_COLOR = '#f6e05e';
+const BACKGROUND_COLOR = '#1a202c';
+
+async function render(container, fileUrl) {
+ container.innerHTML = '';
+
+ const message = document.createElement('div');
+ message.className = 'ui tiny message';
+ message.textContent = 'Rendered by example-highlight-txt plugin';
+ container.append(message);
+
+ const response = await fetch(fileUrl);
+ if (!response.ok) {
+ throw new Error(`Failed to download file (${response.status})`);
+ }
+ const text = await response.text();
+
+ const pre = document.createElement('pre');
+ pre.style.backgroundColor = BACKGROUND_COLOR;
+ pre.style.color = TEXT_COLOR;
+ pre.style.padding = '1rem';
+ pre.style.borderRadius = '0.5rem';
+ pre.style.overflow = 'auto';
+ pre.textContent = text;
+ container.append(pre);
+}
+
+export default {render};

models/migrations/migrations.go

@@ -398,6 +398,7 @@ func prepareMigrationTasks() []*migration {
 // Gitea 1.25.0 ends at migration ID number 322 (database version 323)
 
 newMigration(323, "Add support for actions concurrency", v1_26.AddActionsConcurrency),
+newMigration(324, "Add frontend render plugin table", v1_26.AddRenderPluginTable),
 }
 return preparedMigrations
 }

models/migrations/v1_26/v324.go

@@ -0,0 +1,31 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package v1_26
+
+import (
+"code.gitea.io/gitea/modules/timeutil"
+
+"xorm.io/xorm"
+)
+
+// AddRenderPluginTable creates the render_plugin table used by the frontend plugin system.
+func AddRenderPluginTable(x *xorm.Engine) error {
+type RenderPlugin struct {
+ID int64 `xorm:"pk autoincr"`
+Identifier string `xorm:"UNIQUE NOT NULL"`
+Name string `xorm:"NOT NULL"`
+Version string `xorm:"NOT NULL"`
+Description string `xorm:"TEXT"`
+Source string `xorm:"TEXT"`
+Permissions []string `xorm:"JSON"`
+Entry string `xorm:"NOT NULL"`
+FilePatterns []string `xorm:"JSON"`
+FormatVersion int `xorm:"NOT NULL DEFAULT 1"`
+Enabled bool `xorm:"NOT NULL DEFAULT false"`
+CreatedUnix timeutil.TimeStamp `xorm:"created NOT NULL"`
+UpdatedUnix timeutil.TimeStamp `xorm:"updated NOT NULL"`
+}
+
+return x.Sync(new(RenderPlugin))
+}

models/render/plugin.go

@@ -0,0 +1,126 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package render
+
+import (
+"context"
+
+"code.gitea.io/gitea/models/db"
+"code.gitea.io/gitea/modules/timeutil"
+)
+
+// Plugin represents a frontend render plugin installed on the instance.
+type Plugin struct {
+ID int64 `xorm:"pk autoincr"`
+Identifier string `xorm:"UNIQUE NOT NULL"`
+Name string `xorm:"NOT NULL"`
+Version string `xorm:"NOT NULL"`
+Description string `xorm:"TEXT"`
+Source string `xorm:"TEXT"`
+Entry string `xorm:"NOT NULL"`
+FilePatterns []string `xorm:"JSON"`
+Permissions []string `xorm:"JSON"`
+FormatVersion int `xorm:"NOT NULL DEFAULT 1"`
+Enabled bool `xorm:"NOT NULL DEFAULT false"`
+CreatedUnix timeutil.TimeStamp `xorm:"created NOT NULL"`
+UpdatedUnix timeutil.TimeStamp `xorm:"updated NOT NULL"`
+}
+
+func init() {
+db.RegisterModel(new(Plugin))
+}
+
+// TableName implements xorm's table name convention.
+func (Plugin) TableName() string {
+return "render_plugin"
+}
+
+// ListPlugins returns all registered render plugins ordered by identifier.
+func ListPlugins(ctx context.Context) ([]*Plugin, error) {
+plugins := make([]*Plugin, 0, 4)
+return plugins, db.GetEngine(ctx).Asc("identifier").Find(&plugins)
+}
+
+// ListEnabledPlugins returns all enabled render plugins.
+func ListEnabledPlugins(ctx context.Context) ([]*Plugin, error) {
+plugins := make([]*Plugin, 0, 4)
+return plugins, db.GetEngine(ctx).
+Where("enabled = ?", true).
+Asc("identifier").
+Find(&plugins)
+}
+
+// GetPluginByID returns the plugin with the given primary key.
+func GetPluginByID(ctx context.Context, id int64) (*Plugin, error) {
+plug := new(Plugin)
+has, err := db.GetEngine(ctx).ID(id).Get(plug)
+if err != nil {
+return nil, err
+}
+if !has {
+return nil, db.ErrNotExist{ID: id}
+}
+return plug, nil
+}
+
+// GetPluginByIdentifier returns the plugin with the given identifier.
+func GetPluginByIdentifier(ctx context.Context, identifier string) (*Plugin, error) {
+plug := new(Plugin)
+has, err := db.GetEngine(ctx).
+Where("identifier = ?", identifier).
+Get(plug)
+if err != nil {
+return nil, err
+}
+if !has {
+return nil, db.ErrNotExist{Resource: identifier}
+}
+return plug, nil
+}
+
+// UpsertPlugin inserts or updates the plugin identified by Identifier.
+func UpsertPlugin(ctx context.Context, plug *Plugin) error {
+return db.WithTx(ctx, func(ctx context.Context) error {
+existing := new(Plugin)
+has, err := db.GetEngine(ctx).
+Where("identifier = ?", plug.Identifier).
+Get(existing)
+if err != nil {
+return err
+}
+if has {
+plug.ID = existing.ID
+plug.Enabled = existing.Enabled
+plug.CreatedUnix = existing.CreatedUnix
+_, err = db.GetEngine(ctx).
+ID(existing.ID).
+AllCols().
+Update(plug)
+return err
+}
+_, err = db.GetEngine(ctx).Insert(plug)
+return err
+})
+}
+
+// SetPluginEnabled toggles plugin enabled state.
+func SetPluginEnabled(ctx context.Context, plug *Plugin, enabled bool) error {
+if plug.Enabled == enabled {
+return nil
+}
+plug.Enabled = enabled
+_, err := db.GetEngine(ctx).
+ID(plug.ID).
+Cols("enabled").
+Update(plug)
+return err
+}
+
+// DeletePlugin removes the plugin row.
+func DeletePlugin(ctx context.Context, plug *Plugin) error {
+_, err := db.GetEngine(ctx).
+ID(plug.ID).
+Delete(new(Plugin))
+return err
+}

modules/renderplugin/manifest.go

@@ -0,0 +1,133 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package renderplugin
+
+import (
+"errors"
+"fmt"
+"os"
+"path/filepath"
+"regexp"
+"sort"
+"strings"
+
+"code.gitea.io/gitea/modules/json"
+"code.gitea.io/gitea/modules/util"
+)
+
+var identifierRegexp = regexp.MustCompile(`^[a-z0-9][a-z0-9\-_.]{1,63}$`)
+
+// Manifest describes the metadata declared by a render plugin.
+const SupportedManifestVersion = 1
+
+type Manifest struct {
+SchemaVersion int `json:"schemaVersion"`
+ID string `json:"id"`
+Name string `json:"name"`
+Version string `json:"version"`
+Description string `json:"description"`
+Entry string `json:"entry"`
+FilePatterns []string `json:"filePatterns"`
+Permissions []string `json:"permissions"`
+}
+
+// Normalize validates mandatory fields and normalizes values.
+func (m *Manifest) Normalize() error {
+if m.SchemaVersion == 0 {
+return errors.New("manifest schemaVersion is required")
+}
+if m.SchemaVersion != SupportedManifestVersion {
+return fmt.Errorf("manifest schemaVersion %d is not supported", m.SchemaVersion)
+}
+m.ID = strings.TrimSpace(strings.ToLower(m.ID))
+if !identifierRegexp.MatchString(m.ID) {
+return fmt.Errorf("manifest id %q is invalid; only lowercase letters, numbers, dash, underscore and dot are allowed", m.ID)
+}
+m.Name = strings.TrimSpace(m.Name)
+if m.Name == "" {
+return errors.New("manifest name is required")
+}
+m.Version = strings.TrimSpace(m.Version)
+if m.Version == "" {
+return errors.New("manifest version is required")
+}
+if m.Entry == "" {
+m.Entry = "render.js"
+}
+m.Entry = util.PathJoinRelX(m.Entry)
+if m.Entry == "" || strings.HasPrefix(m.Entry, "../") {
+return fmt.Errorf("manifest entry %q is invalid", m.Entry)
+}
+cleanPatterns := make([]string, 0, len(m.FilePatterns))
+for _, pattern := range m.FilePatterns {
+pattern = strings.TrimSpace(pattern)
+if pattern == "" {
+continue
+}
+cleanPatterns = append(cleanPatterns, pattern)
+}
+if len(cleanPatterns) == 0 {
+return errors.New("manifest must declare at least one file pattern")
+}
+sort.Strings(cleanPatterns)
+m.FilePatterns = cleanPatterns
+
+cleanPerms := make([]string, 0, len(m.Permissions))
+seenPerm := make(map[string]struct{}, len(m.Permissions))
+for _, perm := range m.Permissions {
+perm = strings.TrimSpace(strings.ToLower(perm))
+if perm == "" {
+continue
+}
+if !isValidPermissionHost(perm) {
+return fmt.Errorf("manifest permission %q is invalid; only plain domains optionally including a port are allowed", perm)
+}
+if _, ok := seenPerm[perm]; ok {
+continue
+}
+seenPerm[perm] = struct{}{}
+cleanPerms = append(cleanPerms, perm)
+}
+sort.Strings(cleanPerms)
+m.Permissions = cleanPerms
+return nil
+}
+
+var permissionHostRegexp = regexp.MustCompile(`^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::[0-9]{1,5})?$`)
+
+func isValidPermissionHost(value string) bool {
+return permissionHostRegexp.MatchString(value)
+}
+
+// LoadManifest reads and validates the manifest.json file located under dir.
+func LoadManifest(dir string) (*Manifest, error) {
+manifestPath := filepath.Join(dir, "manifest.json")
+f, err := os.Open(manifestPath)
+if err != nil {
+return nil, err
+}
+defer f.Close()
+var manifest Manifest
+if err := json.NewDecoder(f).Decode(&manifest); err != nil {
+return nil, fmt.Errorf("malformed manifest.json: %w", err)
+}
+if err := manifest.Normalize(); err != nil {
+return nil, err
+}
+return &manifest, nil
+}
+
+// Metadata is the public information exposed to the frontend for an enabled plugin.
+type Metadata struct {
+ID string `json:"id"`
+Name string `json:"name"`
+Version string `json:"version"`
+Description string `json:"description"`
+Entry string `json:"entry"`
+EntryURL string `json:"entryUrl"`
+AssetsBase string `json:"assetsBaseUrl"`
+FilePatterns []string `json:"filePatterns"`
+SchemaVersion int `json:"schemaVersion"`
+Permissions []string `json:"permissions"`
+}