plugin

package
v1.14.17 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: GPL-3.0 Imports: 32 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var AllowedPermissions = map[Permission]bool{
	PermHTTPRoutes:    true,
	PermMiddleware:    true,
	PermDatabaseRead:  true,
	PermDatabaseWrite: true,
	PermRedis:         true,
	PermLogging:       true,
	PermConfigRead:    true,
	PermEvents:        true,
	PermHTTPClient:    true,
	PermScheduler:     true,
	PermQueue:         true,
}

AllowedPermissions 定义所有合法权限的集合

Functions

func CallGuestFn 

func CallGuestFn[T, R proto.Message](
	ctx context.Context,
	mod api.Module,
	exportName string,
	req T,
	newR func() R,
) (R, error)

CallGuestFn 调用 guest WASM 模块的导出函数

自动完成: proto.Marshal → allocate + 写入 WASM 内存 → 调用 guest fn → 读内存 → proto.Unmarshal

参数:

  • exportName: guest 导出的函数名（如 "init", "handle_get_stats"）
  • req: 请求 protobuf 消息
  • newR: 创建响应类型的工厂函数

func CallGuestStart 

func CallGuestStart(ctx context.Context, mod api.Module) error

CallGuestStart 调用 guest 的 start 函数（可选）

func CallGuestStop 

func CallGuestStop(ctx context.Context, mod api.Module) error

CallGuestStop 调用 guest 的 stop 函数（可选）

func CloseModule 

func CloseModule(ctx context.Context, mod api.Module) error

CloseModule 安全关闭模块

func CompilePlugin 

func CompilePlugin(ctx context.Context, rt wazero.Runtime, pluginPath, wasmFile string) (wazero.CompiledModule, error)

CompilePlugin 从文件编译 WASM 模块

func MakeHostFunc 

func MakeHostFunc[T, R proto.Message](
	pluginName string,
	fn HostFunc[T, R],
	newT func() T,
) api.GoModuleFunc

MakeHostFunc 创建一个 wazero host function（GoModuleFunc）。

WASM 函数签名: (i32, i32) -> i64

  • param 0 (i32): 指向 protobuf 请求数据的指针
  • param 1 (i32): 请求数据长度
  • return (i64): 打包的 (result_ptr << 32) | result_len

内部自动完成： 

读内存 → proto.Unmarshal → 业务逻辑 → proto.Marshal → allocate + 写内存 → 返回打包指针

func NewModuleConfig 

func NewModuleConfig(pluginName string) wazero.ModuleConfig

NewModuleConfig 创建模块配置

func ResolvePluginFile 

func ResolvePluginFile(pluginPath, file string) (string, error)

ResolvePluginFile 解析插件目录内的文件路径，拒绝绝对路径和路径穿越。

func ValidatePluginName 

func ValidatePluginName(name string) error

ValidatePluginName 校验管理 API 传入的插件名称，避免路径穿越。

Types

type EventBus 

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

EventBus 提供插件间的事件发布/订阅

func NewEventBus 

func NewEventBus(handler EventHandler) *EventBus

NewEventBus 创建事件总线

func (*EventBus) Publish 

func (eb *EventBus) Publish(event string, payload *structpb.Struct)

Publish 发布事件给所有订阅者（异步分发）

func (*EventBus) Subscribe 

func (eb *EventBus) Subscribe(sub EventSubscription)

Subscribe 订阅事件

func (*EventBus) Subscriptions 

func (eb *EventBus) Subscriptions(pluginName string) []EventSubscription

Subscriptions 返回指定插件的事件订阅快照。pluginName 为空时返回全部订阅。

func (*EventBus) Unsubscribe 

func (eb *EventBus) Unsubscribe(pluginName string)

Unsubscribe 取消订阅

type EventHandler 

type EventHandler func(sub EventSubscription, event string, payload *structpb.Struct)

EventHandler 是事件处理函数的签名

type EventSubscription 

type EventSubscription struct {
	PluginName string // 订阅者插件名
	Event      string // 事件名
	Handler    string // WASM 导出函数名，如 "on_order_paid"
}

EventSubscription 事件订阅

type HostEnv 

type HostEnv struct {
	Config config.Config
	Redis  RedisClient
	Store  StoreClient
	Queue  QueueClient
}

HostEnv 封装宿主提供给插件的所有依赖 在 cmd/run.go 中由 ServiceContext 构建

type HostFunc 

type HostFunc[T proto.Message, R proto.Message] func(
	ctx context.Context,
	pluginName string,
	req T,
) (R, error)

HostFunc 是宿主函数的业务逻辑签名

type HostFuncDef 

type HostFuncDef struct {
	Name       string      // WASM 导入函数名
	Fn         interface{} // api.GoModuleFunc
	Permission Permission  // 所需权限
}

HostFuncDef 定义宿主函数的元数据

type InstancePool 

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

InstancePool 管理 WASM 模块实例池

func InstantiateWithHostFuncs 

func InstantiateWithHostFuncs(
	ctx context.Context,
	rt wazero.Runtime,
	compiled wazero.CompiledModule,
	pluginName string,
	hostFuncs map[string]api.GoModuleFunc,
	poolSize int,
) (*InstancePool, error)

InstantiateWithHostFuncs 注册宿主函数并实例化 WASM 模块

hostFuncs: 宿主函数名 → api.GoModuleFunc 的映射

func NewInstancePool 

func NewInstancePool(size int) *InstancePool

NewInstancePool 创建一个新的实例池

func (*InstancePool) Close 

func (p *InstancePool) Close(ctx context.Context)

Close 关闭池中所有实例

func (*InstancePool) Get 

func (p *InstancePool) Get(ctx context.Context) (api.Module, error)

Get 获取一个空闲的 WASM 实例

func (*InstancePool) Put 

func (p *InstancePool) Put(mod api.Module)

Put 归还 WASM 实例

func (*InstancePool) Size 

func (p *InstancePool) Size() int

Size 返回池的大小

type Manager 

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

Manager 插件管理器，实现 service.Service 接口

func NewManager 

func NewManager(hostEnv *HostEnv) *Manager

NewManager 创建插件管理器

func (*Manager) CallPlugin 

func (m *Manager) CallPlugin(ctx context.Context, pluginName, exportName string, req *pluginv1.HandleRequest) (*pluginv1.HandleResponse, error)

CallPlugin 调用插件的导出函数（用于路由处理）。 内部持有 WASM 互斥锁，阻塞型宿主函数安全。

func (*Manager) CallPluginMiddleware 

func (m *Manager) CallPluginMiddleware(ctx context.Context, pluginName, exportName string, req *pluginv1.HandleRequest) (*pluginv1.MiddlewareResponse, error)

CallPluginMiddleware 调用插件中间件

func (*Manager) DisablePlugin 

func (m *Manager) DisablePlugin(name string) error

DisablePlugin 禁用插件（停止并卸载）

func (*Manager) EnablePlugin 

func (m *Manager) EnablePlugin(name string) error

EnablePlugin 启用插件（加载并启动）

func (*Manager) EventBus 

func (m *Manager) EventBus() *EventBus

EventBus 返回事件总线

func (*Manager) FindMiddleware 

func (m *Manager) FindMiddleware(pluginName, name string) (MiddlewareRegistration, bool)

FindMiddleware 查找插件中间件。优先使用同插件注册的中间件，兼容旧的全局名称引用。

func (*Manager) FindRoute 

func (m *Manager) FindRoute(pluginName, method, path string) (RouteRegistration, bool)

FindRoute 查找当前已注册的插件路由。用于固定 catch-all HTTP 路由动态分发。

func (*Manager) GetConfigValue 

func (m *Manager) GetConfigValue(key string) string

GetConfigValue 通过 dot-notation key 读取配置值

func (*Manager) GetInstalledManifest 

func (m *Manager) GetInstalledManifest(name string) (*PluginManifest, error)

GetInstalledManifest 返回运行中或已安装插件的 manifest。

func (*Manager) GetInstalledPluginInfo 

func (m *Manager) GetInstalledPluginInfo(name string) (PluginInfo, bool)

GetInstalledPluginInfo 返回运行中或已安装插件的信息。

func (*Manager) GetPlugin 

func (m *Manager) GetPlugin(name string) *PluginInstance

GetPlugin 根据名称获取插件实例

func (*Manager) GetPluginHealth 

func (m *Manager) GetPluginHealth(name string) (PluginHealth, bool)

GetPluginHealth 返回指定插件运行时健康状态。

func (*Manager) GetRedis 

func (m *Manager) GetRedis() RedisClient

GetRedis 返回 Redis 客户端

func (*Manager) GetStore 

func (m *Manager) GetStore() StoreClient

GetStore 返回数据库 Store

func (*Manager) HasPermission 

func (m *Manager) HasPermission(pluginName string, perm Permission) bool

HasPermission 检查插件是否有特定权限

func (*Manager) InstallPluginArchive 

func (m *Manager) InstallPluginArchive(ctx context.Context, r io.Reader, opts PluginInstallOptions) (PluginInstallResult, error)

InstallPluginArchive installs a zip package that contains plugin.yaml and the WASM module.

func (*Manager) ListInstalledPlugins 

func (m *Manager) ListInstalledPlugins() []PluginInfo

ListInstalledPlugins 扫描插件目录，并合并当前运行时状态。

func (*Manager) ListPluginEvents 

func (m *Manager) ListPluginEvents(name string) []EventSubscription

ListPluginEvents 返回指定插件当前订阅的事件。

func (*Manager) ListPluginMiddleware 

func (m *Manager) ListPluginMiddleware(name string) []MiddlewareRegistration

ListPluginMiddleware 返回指定插件当前注册的 WASM 中间件。

func (*Manager) ListPluginRoutes 

func (m *Manager) ListPluginRoutes(name string) []RouteRegistration

ListPluginRoutes 返回指定插件当前注册的路由。

func (*Manager) ListPlugins 

func (m *Manager) ListPlugins() []PluginInfo

ListPlugins 返回所有已加载插件信息

func (*Manager) PendingMiddleware 

func (m *Manager) PendingMiddleware() []MiddlewareRegistration

PendingMiddleware 返回待注册的中间件列表

func (*Manager) PendingRoutes 

func (m *Manager) PendingRoutes() []RouteRegistration

PendingRoutes 返回待注册的路由列表

func (*Manager) PluginDirectory 

func (m *Manager) PluginDirectory() string

PluginDirectory 返回当前插件目录。

func (*Manager) RegisterMiddleware 

func (m *Manager) RegisterMiddleware(mw MiddlewareRegistration) error

RegisterMiddleware 注册插件中间件（供 host_register_middleware 调用）

func (*Manager) RegisterRoute 

func (m *Manager) RegisterRoute(route RouteRegistration) error

RegisterRoute 注册插件的 HTTP 路由（供 host_register_route 调用）

func (*Manager) ReloadAllPlugins 

func (m *Manager) ReloadAllPlugins(ctx context.Context) []PluginInfo

ReloadAllPlugins 停止当前运行时状态并重新扫描插件目录。

func (*Manager) ReloadPlugin 

func (m *Manager) ReloadPlugin(name string) error

ReloadPlugin 重载指定插件（停止→重新加载→启动）

func (*Manager) RequestTimeout 

func (m *Manager) RequestTimeout() time.Duration

RequestTimeout 返回插件请求/初始化默认超时。

func (*Manager) ScheduleTask 

func (m *Manager) ScheduleTask(pluginName, taskName, cronExpr, handler string) error

ScheduleTask 注册定时任务

func (*Manager) Start 

func (m *Manager) Start()

Start 启动插件管理器（实现 service.Service）

func (*Manager) Stop 

func (m *Manager) Stop()

Stop 停止插件管理器（实现 service.Service）

func (*Manager) SubscribeEvent 

func (m *Manager) SubscribeEvent(pluginName, event, handler string) error

SubscribeEvent 订阅宿主事件（供 host_subscribe_event 调用）

func (*Manager) ValidateInstalledPlugin 

func (m *Manager) ValidateInstalledPlugin(name string) PluginValidation

ValidateInstalledPlugin 校验插件目录、manifest、权限和 WASM 文件可访问性。

func (*Manager) WaitReady 

func (m *Manager) WaitReady(ctx context.Context) error

WaitReady 阻塞直到插件管理器加载完成

type ManagerStatus 

type ManagerStatus int

ManagerStatus 管理器状态 

const (
	ManagerUninitialized ManagerStatus = iota
	ManagerLoading
	ManagerRunning
	ManagerStopping
	ManagerStopped
)

type MiddlewareRegistration 

type MiddlewareRegistration struct {
	PluginName string // 插件名
	Name       string // 中间件名（用于路由引用）
	Handler    string // WASM 导出函数名，如 "mw_rate_limit"
}

MiddlewareRegistration 插件注册的中间件

type Permission 

type Permission string

Permission 定义插件可以请求的能力 

const (
	PermHTTPRoutes    Permission = "http_routes"
	PermMiddleware    Permission = "middleware"
	PermDatabaseRead  Permission = "database_read"
	PermDatabaseWrite Permission = "database_write"
	PermRedis         Permission = "redis"
	PermLogging       Permission = "logging"
	PermConfigRead    Permission = "config_read"
	PermEvents        Permission = "events"
	PermHTTPClient    Permission = "http_client"
	PermScheduler     Permission = "scheduler"
	PermQueue         Permission = "queue"
)

type PluginHealth 

type PluginHealth struct {
	Name            string       `json:"name"`
	Status          PluginStatus `json:"status"`
	Ready           bool         `json:"ready"`
	PoolSize        int          `json:"pool_size"`
	AsyncInFlight   int          `json:"async_in_flight"`
	AsyncLimit      int          `json:"async_limit"`
	RegisteredRoute int          `json:"registered_route"`
	Error           string       `json:"error,omitempty"`
}

PluginHealth 描述插件运行时健康状态（用于管理 API）。

type PluginInfo 

type PluginInfo struct {
	Name        string       `json:"name"`
	Version     string       `json:"version"`
	Description string       `json:"description"`
	Author      string       `json:"author"`
	Status      PluginStatus `json:"status"`
	Permissions []string     `json:"permissions"`
	Routes      []string     `json:"routes"` // 已注册的路由路径列表
	Error       string       `json:"error,omitempty"`
}

PluginInfo 对外暴露的插件信息（用于管理 API）

type PluginInstallOptions 

type PluginInstallOptions struct {
	Replace bool `json:"replace"`
	Enable  bool `json:"enable"`
}

PluginInstallOptions controls how an uploaded plugin package is installed.

type PluginInstallResult 

type PluginInstallResult struct {
	Name       string           `json:"name"`
	Replaced   bool             `json:"replaced"`
	Enabled    bool             `json:"enabled"`
	Status     PluginStatus     `json:"status"`
	Plugin     PluginInfo       `json:"plugin"`
	Validation PluginValidation `json:"validation"`
}

PluginInstallResult describes the result of installing an uploaded plugin.

type PluginInstance 

type PluginInstance struct {
	Name        string
	Version     string
	Description string
	Author      string
	Status      PluginStatus
	Manifest    *PluginManifest
	Routes      []RouteRegistration
	Error       string

	// Pool 管理该插件的 WASM 模块实例
	Pool *InstancePool

	// Runtime 是该插件独立的 wazero runtime，避免 env host module 跨插件冲突
	Runtime wazero.Runtime

	// AsyncNotify 异步任务完成通知
	AsyncNotify chan uint64

	// AsyncSem 限制该插件未完成的异步任务数
	AsyncSem chan struct{}
	// contains filtered or unexported fields
}

PluginInstance 代表一个已加载的插件实例

func (*PluginInstance) AddRoute 

func (p *PluginInstance) AddRoute(route RouteRegistration)

AddRoute 安全添加路由

func (*PluginInstance) GetRoutes 

func (p *PluginInstance) GetRoutes() []RouteRegistration

GetRoutes 安全获取路由列表

func (*PluginInstance) GetStatus 

func (p *PluginInstance) GetStatus() PluginStatus

GetStatus 安全获取插件状态

func (*PluginInstance) SetError 

func (p *PluginInstance) SetError(err string)

SetError 安全设置错误信息

func (*PluginInstance) SetStatus 

func (p *PluginInstance) SetStatus(s PluginStatus)

SetStatus 安全设置插件状态

func (*PluginInstance) ToInfo 

func (p *PluginInstance) ToInfo() PluginInfo

ToInfo 转换为对外暴露的 PluginInfo

type PluginManifest 

type PluginManifest struct {
	Name        string                 `yaml:"name"`
	Version     string                 `yaml:"version"`
	Description string                 `yaml:"description"`
	Author      string                 `yaml:"author"`
	Main        string                 `yaml:"main"` // .wasm 文件路径，相对于插件目录
	Permissions []string               `yaml:"permissions"`
	Config      map[string]interface{} `yaml:"config"`
}

PluginManifest 是插件描述文件 plugin.yaml 的结构

func ParseManifest 

func ParseManifest(pluginDir string) (*PluginManifest, error)

ParseManifest 从插件目录解析 plugin.yaml 并校验

func (*PluginManifest) HasPermission 

func (m *PluginManifest) HasPermission(perm Permission) bool

HasPermission 检查插件是否声明了某个权限

func (*PluginManifest) Validate 

func (m *PluginManifest) Validate() error

Validate 校验清单的必填字段和权限合法性

type PluginStatus 

type PluginStatus string

PluginStatus 表示插件的当前状态 

const (
	StatusUnloaded    PluginStatus = "unloaded"
	StatusLoaded      PluginStatus = "loaded"
	StatusInitialized PluginStatus = "initialized"
	StatusRunning     PluginStatus = "running"
	StatusStopped     PluginStatus = "stopped"
	StatusError       PluginStatus = "error"
)

type PluginValidation 

type PluginValidation struct {
	Name     string                  `json:"name"`
	Valid    bool                    `json:"valid"`
	Manifest *PluginManifest         `json:"manifest,omitempty"`
	Checks   []PluginValidationCheck `json:"checks"`
	Error    string                  `json:"error,omitempty"`
}

PluginValidation 表示插件安装包/目录的校验结果。

type PluginValidationCheck 

type PluginValidationCheck struct {
	Name    string `json:"name"`
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

PluginValidationCheck 表示插件安装校验中的单项结果。

type QueueAdapter 

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

QueueAdapter 将 *asynq.Client 适配为 QueueClient 接口

func NewQueueAdapter 

func NewQueueAdapter(client *asynq.Client) *QueueAdapter

NewQueueAdapter 创建 Queue 适配器

func (*QueueAdapter) Enqueue 

func (a *QueueAdapter) Enqueue(taskName string, payload map[string]interface{}) error

Enqueue 将任务入队

type QueueClient 

type QueueClient interface {
	Enqueue(taskName string, payload map[string]interface{}) error
}

QueueClient 是插件访问任务队列的接口

type RedisAdapter 

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

RedisAdapter 将 *redis.Client 适配为 RedisClient 接口

func NewRedisAdapter 

func NewRedisAdapter(client *redis.Client) *RedisAdapter

NewRedisAdapter 创建 Redis 适配器

func (*RedisAdapter) Del 

func (a *RedisAdapter) Del(keys ...string) error

func (*RedisAdapter) Get 

func (a *RedisAdapter) Get(key string) (string, error)

func (*RedisAdapter) Set 

func (a *RedisAdapter) Set(key string, value string, ttlSeconds int64) error

type RedisClient 

type RedisClient interface {
	Get(key string) (string, error)
	Set(key string, value string, ttlSeconds int64) error
	Del(keys ...string) error
}

RedisClient 是插件访问 Redis 的接口

type RouteRegistration 

type RouteRegistration struct {
	PluginName string   // 插件名
	Method     string   // GET, POST, PUT, DELETE
	Path       string   // 插件自定义路径，如 "/stats"
	Handler    string   // WASM 导出函数名
	Middleware []string // "auth", "device"
}

RouteRegistration 插件注册的路由

type StoreAdapter 

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

StoreAdapter 将 *gorm.DB 适配为 StoreClient 接口

func NewStoreAdapter 

func NewStoreAdapter(db *gorm.DB) *StoreAdapter

NewStoreAdapter 创建数据库 Store 适配器

func (*StoreAdapter) Query 

func (a *StoreAdapter) Query(
	model string,
	operation string,
	conditions map[string]interface{},
	fields []string,
	limit, offset int32,
) ([]map[string]interface{}, int64, error)

Query 执行数据库查询（安全：仅白名单表 + 白名单操作）

type StoreClient 

type StoreClient interface {
	Query(model string, operation string, conditions map[string]interface{}, fields []string, limit, offset int32) ([]map[string]interface{}, int64, error)
}

StoreClient 是插件访问数据库的接口

Source Files

View all Source files

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.