plugin

package
v4.0.1 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2026 License: MIT Imports: 7 Imported by: 0

README

GWC | Plugin Library

GoWebComponents (GWC)

High-Level Overview

The plugin library defines the public, app-owned companion extension host for integrating application-specific behavior into GWC.

This package is not the deep framework plugin kernel. The new kernel lives under internal/pluginruntime and is reserved for framework-owned services and trusted internal plugins such as kernel-backed devtools contributions.

Public APIs

github.com/monstercameron/GoWebComponents/plugin (package plugin)
  • Functions: AddBootstrapProvider, AddCacheKeyDecorator, AddDevtoolsActionProvider, AddDevtoolsSectionProvider, AddFormValidator, AddHeadProvider, AddNavigationObserver, AddPanelProvider, AddRequestObserver, AddRouteGuard, AddSubmitObserver, Allow, Block, BootstrapData, Capabilities, Close, DecorateCacheKey, Define, DevtoolsActions, DevtoolsSections, EvaluateRoute, HeadNodes, Manifest, NewHost, NotifyNavigation, NotifyRequest, NotifySubmit, Panels, Plugins, Redirect, Register, SetValue, Setup, ValidateForm, Value
  • Types: BootstrapPayload, BootstrapProvider, CacheKeyDecorator, Capability, CleanupFunc, DefineFunc, DevtoolsAction, DevtoolsActionContext, DevtoolsActionProvider, DevtoolsSection, DevtoolsSectionProvider, FormSubmission, FormValidator, GuardDecision, GuardOutcome, HeadProvider, Host, HostOptions, Manifest, NavigationEvent, NavigationObserver, Panel, PanelProvider, Plugin, RequestEvent, RequestObserver, RouteGuard, RouteRequest, SubmitObserver, Tier, ValidationIssue
  • Variables: none
  • Constants: CapabilityAsyncData, CapabilityDevtools, CapabilityForms, CapabilityRouter, CapabilitySSR, GuardAllow, GuardBlock, GuardRedirect, TierExperimental, TierInternal, TierStable, TierSupportedCompanion

Subfiles And Purpose

  • doc.go - Package-level Go documentation
  • plugin.go - Core implementation for plugin
  • plugin_additional_test.go - Tests for plugin_additional behavior
  • plugin_rollback_test.go - Tests for plugin_rollback behavior
  • plugin_test.go - Tests for plugin behavior

File Map

plugin/
|-- doc.go
|-- plugin.go
|-- plugin_additional_test.go
|-- plugin_rollback_test.go
\-- plugin_test.go

Documentation

Overview

Package plugin provides an explicit, application-owned plugin host for companion packages and example integrations.

The package is a supported companion API. It does not grant privileged runtime access, and it does not replace the internal framework-owned plugin kernel used for deep devtools and service interposition. Companion plugins remain app-owned integrations over a Host instance.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BootstrapPayload 

type BootstrapPayload struct {
	Namespace string
	Data      map[string]any
}

type BootstrapProvider 

type BootstrapProvider func() BootstrapPayload

type CacheKeyDecorator 

type CacheKeyDecorator func(string) string

type Capability 

type Capability string
const (
	CapabilityRouter    Capability = "router"
	CapabilityAsyncData Capability = "async-data"
	CapabilityDevtools  Capability = "devtools"
	CapabilitySSR       Capability = "ssr"
	CapabilityForms     Capability = "forms"
)

type CleanupFunc 

type CleanupFunc func() error

type DefineFunc 

type DefineFunc func(*Host) (CleanupFunc, error)

type DevtoolsAction 

type DevtoolsAction struct {
	Label        string
	MatchCodes   []string
	MatchSources []string
	Run          func(DevtoolsActionContext)
}

type DevtoolsActionContext 

type DevtoolsActionContext struct {
	Host          *Host
	IssueCode     string
	IssueSource   string
	IssuePath     string
	IssueMessage  string
	IssueDocs     string
	IssueTopFrame string
}

type DevtoolsActionProvider 

type DevtoolsActionProvider func() []DevtoolsAction

type DevtoolsSection 

type DevtoolsSection struct {
	Name    string
	Summary map[string]string
	Lines   []string
}

type DevtoolsSectionProvider 

type DevtoolsSectionProvider func() DevtoolsSection

type FormSubmission 

type FormSubmission struct {
	ID     string
	Intent string
	Values map[string]string
}

type FormValidator 

type FormValidator func(FormSubmission) []ValidationIssue

type GuardDecision 

type GuardDecision struct {
	Outcome  GuardOutcome
	Reason   string
	Redirect string
}

func Allow 

func Allow(parseReason string) GuardDecision

Allow creates a GuardDecision that permits navigation with an optional reason.

func Block 

func Block(parseReason string) GuardDecision

Block creates a GuardDecision that blocks navigation with a reason.

func Redirect 

func Redirect(parsePath, parseReason string) GuardDecision

Redirect creates a GuardDecision that redirects navigation to the given path.

type GuardOutcome 

type GuardOutcome string
const (
	GuardAllow    GuardOutcome = "allow"
	GuardBlock    GuardOutcome = "block"
	GuardRedirect GuardOutcome = "redirect"
)

type HeadProvider 

type HeadProvider func() ui.Node

type Host 

type Host struct {
	// contains filtered or unexported fields
}

func NewHost 

func NewHost(parseOptions HostOptions) *Host

NewHost creates a Host with the given capabilities configuration.

func (*Host) AddBootstrapProvider 

func (parseHost *Host) AddBootstrapProvider(parseProvider BootstrapProvider) error

AddBootstrapProvider registers a provider that contributes SSR bootstrap data.

func (*Host) AddCacheKeyDecorator 

func (parseHost *Host) AddCacheKeyDecorator(parseDecorator CacheKeyDecorator) error

AddCacheKeyDecorator registers a function that transforms fetch cache keys.

func (*Host) AddDevtoolsActionProvider 

func (parseHost *Host) AddDevtoolsActionProvider(parseProvider DevtoolsActionProvider) error

AddDevtoolsActionProvider registers a provider that contributes one or more error-overlay recovery actions.

func (*Host) AddDevtoolsSectionProvider 

func (parseHost *Host) AddDevtoolsSectionProvider(parseProvider DevtoolsSectionProvider) error

AddDevtoolsSectionProvider registers a provider that contributes one devtools extension section.

func (*Host) AddFormValidator 

func (parseHost *Host) AddFormValidator(parseValidator FormValidator) error

AddFormValidator registers a function that validates form submissions.

func (*Host) AddHeadProvider 

func (parseHost *Host) AddHeadProvider(parseProvider HeadProvider) error

AddHeadProvider registers a provider that contributes ui.Node elements to the document head.

func (*Host) AddNavigationObserver 

func (parseHost *Host) AddNavigationObserver(parseObserver NavigationObserver) error

AddNavigationObserver registers a callback invoked after each navigation event.

func (*Host) AddPanelProvider 

func (parseHost *Host) AddPanelProvider(parseProvider PanelProvider) error

AddPanelProvider registers a devtools panel provider that returns panel metadata.

func (*Host) AddRequestObserver 

func (parseHost *Host) AddRequestObserver(parseObserver RequestObserver) error

AddRequestObserver registers a callback invoked for fetch request lifecycle events.

func (*Host) AddRouteGuard 

func (parseHost *Host) AddRouteGuard(parseGuard RouteGuard) error

AddRouteGuard registers a route guard evaluated before navigation decisions.

func (*Host) AddSubmitObserver 

func (parseHost *Host) AddSubmitObserver(parseObserver SubmitObserver) error

AddSubmitObserver registers a callback invoked after each form submission.

func (*Host) BootstrapData 

func (parseHost *Host) BootstrapData() map[string]map[string]any

BootstrapData collects and merges bootstrap payloads from all registered providers.

func (*Host) Capabilities 

func (parseHost *Host) Capabilities() []Capability

Capabilities returns the sorted list of capabilities the host was configured with.

func (*Host) Close 

func (parseHost *Host) Close() error

Close runs all registered cleanup functions in reverse registration order.

func (*Host) DecorateCacheKey 

func (parseHost *Host) DecorateCacheKey(parseKey string) string

DecorateCacheKey applies all registered cache-key decorators in order and returns the result.

func (*Host) DevtoolsActions 

func (parseHost *Host) DevtoolsActions() []DevtoolsAction

DevtoolsActions collects and returns all valid devtools recovery actions from registered providers.

func (*Host) DevtoolsSections 

func (parseHost *Host) DevtoolsSections() []DevtoolsSection

DevtoolsSections collects and returns all valid devtools extension sections from registered providers.

func (*Host) EvaluateRoute 

func (parseHost *Host) EvaluateRoute(parseRequest RouteRequest) GuardDecision

EvaluateRoute runs all registered route guards and returns the first non-allow decision.

func (*Host) HeadNodes 

func (parseHost *Host) HeadNodes() []ui.Node

HeadNodes collects and returns all head nodes from registered head providers.

func (*Host) NotifyNavigation 

func (parseHost *Host) NotifyNavigation(parseEvent NavigationEvent)

NotifyNavigation delivers a navigation event to all registered observers.

func (*Host) NotifyRequest 

func (parseHost *Host) NotifyRequest(parseEvent RequestEvent)

NotifyRequest delivers a request event to all registered request observers.

func (*Host) NotifySubmit 

func (parseHost *Host) NotifySubmit(parseSubmission FormSubmission)

NotifySubmit delivers a form submission event to all registered submit observers.

func (*Host) Panels 

func (parseHost *Host) Panels() []Panel

Panels collects and returns all panels from registered panel providers.

func (*Host) Plugins 

func (parseHost *Host) Plugins() []Manifest

Plugins returns a snapshot of the manifests of all registered plugins.

func (*Host) Register 

func (parseHost *Host) Register(parsePlugin Plugin) error

Register installs a plugin on the host after validating its manifest and capabilities.

func (*Host) SetValue 

func (parseHost *Host) SetValue(parseKey string, parseValue any)

SetValue stores a named value on the host for inter-plugin communication.

func (*Host) ValidateForm 

func (parseHost *Host) ValidateForm(parseSubmission FormSubmission) []ValidationIssue

ValidateForm runs all registered form validators and returns the combined issues.

func (*Host) Value 

func (parseHost *Host) Value(parseKey string) (any, bool)

Value retrieves a named value stored on the host.

type HostOptions 

type HostOptions struct {
	Capabilities []Capability
}

type Manifest 

type Manifest struct {
	ID          string
	Version     string
	Description string
	Tier        Tier
	Requires    []Capability
}
type NavigationEvent struct {
	Path   string
	Source string
}
type NavigationObserver func(NavigationEvent)

type Panel 

type Panel struct {
	ID      string
	Title   string
	Summary string
}

type PanelProvider 

type PanelProvider func() Panel

type Plugin 

type Plugin interface {
	Manifest() Manifest
	Setup(*Host) (CleanupFunc, error)
}

func Define 

func Define(parseManifest Manifest, parseSetup DefineFunc) Plugin

Define creates a Plugin from a manifest and a setup function.

type RequestEvent 

type RequestEvent struct {
	Key    string
	Phase  string
	Source string
}

type RequestObserver 

type RequestObserver func(RequestEvent)

type RouteGuard 

type RouteGuard func(RouteRequest) GuardDecision

type RouteRequest 

type RouteRequest struct {
	Path string
	Tags []string
}

type SubmitObserver 

type SubmitObserver func(FormSubmission)

type Tier 

type Tier string
const (
	TierStable             Tier = "stable"
	TierSupportedCompanion Tier = "supported-companion"
	TierExperimental       Tier = "experimental"
	TierInternal           Tier = "internal"
)

type ValidationIssue 

type ValidationIssue struct {
	Field   string
	Message string
}

Source Files

View all Source files

Directories

Path Synopsis
Package conformance provides a Plugin API conformance suite that third-party plugin authors can run against their plugin to prove it meets the host contract defined by the plugin package.
 Package conformance provides a Plugin API conformance suite that third-party plugin authors can run against their plugin to prove it meets the host contract defined by the plugin package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.