ocplugin

package module
v0.0.0-...-e7d21fb Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 6 Imported by: 0

README

ocplugin — SDK автономных (standalone) wasm-плагинов на Go

Отдельный модуль без зависимостей (только stdlib): go get github.com/compico/overlaycomposer/pkg/ocplugin не тянет за собой код приложения и не требует его версии Go (нужен Go 1.24+ для //go:wasmexport).

package main

import "github.com/compico/overlaycomposer/pkg/ocplugin"

func init() {
	p := ocplugin.New(ocplugin.Meta{
		ID: "hello", Name: "Hello", Version: "0.1.0",
		Permissions: []string{ocplugin.PermStorage},
	})
	p.GET("/greet", func(c *ocplugin.Ctx) error {
		n, _, _ := ocplugin.Load[int]("count")
		_ = ocplugin.Store("count", n+1)
		return c.JSON(200, map[string]any{"hello": c.Query("name"), "count": n + 1})
	})
}

func main() {} // обязателен для сборки reactor, остаётся пустым
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o hello.wasm .

Положите hello.wasm в папку плагинов (рядом с обычными плагинами-виджетами). Маршрут: /plugins/hello/api/greet?name=oc.

API

New(Meta) создать плагин (один раз, из init())
p.GET/POST/PUT/PATCH/DELETE(path, func(*Ctx) error) маршруты /plugins/<id>/api<path>
Ctx: Query, Bind(&v), JSON(status, v), NoContent(), Error(status, msg) запрос и ответ
p.OnInit, p.Config(&v) запуск экземпляра и настройки пользователя
p.OnRedemption, p.OnTimer(id, f), p.OnHTTPResponse(id, f) события хоста
Load[T], Store, Remove хранилище (PermStorage)
SetTimer, ClearTimer таймеры хоста (PermTimer)
Fetch(id, FetchRequest) HTTP-запрос хоста, ответ — в OnHTTPResponse (PermNetHTTP; к программе на этом компьютере, например tosu, — PermNetLocal и Meta.NetLocal)
FulfillRedemption, CancelRedemption статус погашения награды (PermRedeem)
Debug/Info/Warn/Error(msg, kv...) лог приложения с пометкой плагина

Что важно знать

  • Плагин пассивен. В wasip1 нет потоков: горутины идут только внутри вызова хоста, фоновое ожидание не работает. Фоновая работа — таймеры хоста и Fetch. Обработчик маршрута отвечает сразу.
  • OnInit может выполняться несколько раз (после сбоя, после выдачи прав, после смены настроек). До выдачи прав операции хоста возвращают ошибку permission denied — в OnInit это не повод возвращать ошибку (ошибка = плагин в failed).
  • Состояние — в Store/Load, не в переменных: экземпляр пересоздаётся после сбоя.
  • Паника в обработчике не роняет плагин: SDK отвечает 500 (подробности только в лог плагина) и продолжает работу. Сбой процесса wasm хост лечит перезапуском экземпляра.
  • Метаданные собираются сами (маршруты, подписка на награды); разрешения перечисляются в Meta явно — пользователь их выдаёт.
  • Размер: Go-плагин ≈ 3 МБ (рантайм Go). Rust-плагин на том же ABI — около 100 КБ.
  • Тесты на обычном go test: ocplugin.SetHost(func(op string, arg []byte) []byte {…}) подменяет хост; обработчики вызываются как обычные функции. Слой ABI собирается только под wasip1.

Подробности ABI — docs/WASM_PLUGINS.md.

Documentation

Overview

Package ocplugin — SDK для автономных (standalone) wasm-плагинов Overlay Composer на Go.

Он прячет ABI (alloc/dealloc, упаковку указателей, JSON-обёртки): плагин регистрирует маршруты и обработчики событий, а SDK собирает метаданные для oc_meta и вызывает нужный обработчик.

func init() {
	p := ocplugin.New(ocplugin.Meta{ID: "hello", Name: "Hello", Version: "0.1.0", Permissions: []string{ocplugin.PermStorage}})
	p.GET("/greet", func(c *ocplugin.Ctx) error {
		return c.JSON(200, map[string]string{"hello": c.Query("name")})
	})
}

func main() {} // обязателен для сборки reactor, остаётся пустым

Сборка: GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o hello.wasm .

Плагин пассивен: в wasip1 нет потоков, горутины идут только внутри вызова хоста. Фоновая работа — через таймеры (SetTimer + OnTimer) и сетевые запросы хоста (Fetch + OnHTTPResponse). Состояние храните в Store/Load, а не в переменных: экземпляр может быть пересоздан после сбоя.

Index

Constants

View Source
const (
	PermStorage = "storage"
	PermNetHTTP = "net.http"
	// PermNetLocal — Fetch к программе на этом компьютере по адресу из Meta.NetLocal (например, к tosu).
	PermNetLocal = "net.local"
	PermRedeem   = "twitch.redemption"
	PermTimer    = "timer"
	PermPublish  = "events.publish"
	PermChat     = "chat.send" // писать в чат канала от имени бота
)

Разрешения (плагин запрашивает, пользователь выдаёт).

Variables

This section is empty.

Functions

func CancelRedemption

func CancelRedemption(rewardID, id string) error

CancelRedemption отменяет погашение, баллы возвращаются зрителю.

func ClearTimer

func ClearTimer(id string)

ClearTimer останавливает таймер.

func Debug

func Debug(msg string, kv ...any)

Debug/Info/Warn/Error пишут в лог приложения с пометкой плагина; kv — пары «ключ, значение».

func Error

func Error(msg string, kv ...any)

func Fetch

func Fetch(id string, r FetchRequest) error

Fetch запускает запрос и сразу возвращается; ответ придёт в OnHTTPResponse(id).

func FulfillRedemption

func FulfillRedemption(rewardID, id string) error

FulfillRedemption отмечает погашение выполненным.

func Info

func Info(msg string, kv ...any)

func Load

func Load[T any](key string) (v T, found bool, err error)

Load читает значение по ключу. found == false — ключа нет.

func Publish

func Publish(topic string, v any) error

Publish публикует событие в топик, объявленный в Meta.Events: его получают подписчики (виджеты, аддоны, deck). Данные должны кодироваться в JSON (до 64 КБ). Частота ограничена хостом; при превышении вернётся ошибка.

func PublishRetained

func PublishRetained(topic string, v any) error

PublishRetained публикует событие и просит хост хранить последнее значение топика: новый подписчик получит его сразу. Подходит для состояния («сейчас играет»), а не для команд.

func Remove

func Remove(key string) error

Remove удаляет ключ.

func Say

func Say(text string) error

Say пишет в чат канала стримера от имени бота. Канал и аккаунт выбирает хост, текст — до 300 символов; частота ограничена (всплеск 3 сообщения, затем одно в 3 секунды). Отправка идёт в фоне: nil означает, что хост принял сообщение, а не что оно дошло (нет аккаунта бота, нет связи с чатом — это попадёт в лог OC).

func SetHost

func SetHost(h func(op string, arg []byte) []byte)

SetHost подменяет связь с хостом (для тестов плагина на обычном `go test`). В wasm не нужен.

func SetTimer

func SetTimer(id string, d time.Duration, repeat bool) error

SetTimer запускает таймер хоста (50 мс … 24 ч); срабатывание придёт в OnTimer(id). Тот же id заменяет таймер.

func Store

func Store(key string, v any) error

Store записывает значение (оно должно кодироваться в JSON).

func Warn

func Warn(msg string, kv ...any)

Types

type Ctx

type Ctx struct {
	Method string
	Path   string
	// contains filtered or unexported fields
}

Ctx — запрос к маршруту и ответ на него.

func (*Ctx) Bind

func (c *Ctx) Bind(v any) error

Bind разбирает JSON-тело запроса в v. Пустое тело — ошибка.

func (*Ctx) Error

func (c *Ctx) Error(status int, msg string) error

Error отвечает {"error": msg} с указанным статусом. Сообщение увидит вызывающий — не кладите в него внутренние детали.

func (*Ctx) JSON

func (c *Ctx) JSON(status int, v any) error

JSON отвечает значением v как JSON-телом с указанным статусом.

func (*Ctx) NoContent

func (c *Ctx) NoContent() error

NoContent отвечает 204 без тела.

func (*Ctx) Query

func (c *Ctx) Query(key string) string

Query возвращает параметр строки запроса ("" — нет такого).

type EventDecl

type EventDecl struct {
	ID          string `json:"id"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
}

EventDecl — объявление публикуемого топика: id (`a-z0-9._-`, до 64 символов), название и описание для редакторов.

type FetchRequest

type FetchRequest struct {
	Method string `json:"method,omitempty"` // по умолчанию GET
	URL    string `json:"url"`
	Body   string `json:"body,omitempty"`
}

FetchRequest — исходящий HTTP-запрос. В локальную сеть ходить нельзя.

type HTTPResponse

type HTTPResponse struct {
	ID     string `json:"id"`
	Status int    `json:"status"`
	Body   string `json:"body"`
	Error  string `json:"error"`
}

HTTPResponse — ответ на Fetch. Error непустой, если запрос не удался (тогда Status == 0).

type Handler

type Handler func(c *Ctx) error

Handler обрабатывает запрос к маршруту. Возвращённая ошибка — это 500 без подробностей наружу (подробности — в лог плагина).

type Meta

type Meta struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Version     string   `json:"version"`
	Description string   `json:"description,omitempty"`
	Author      string   `json:"author,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	// NetLocal — программы на этом компьютере, к которым плагин ходит через Fetch (нужно PermNetLocal).
	NetLocal []NetLocalTarget `json:"netLocal,omitempty"`
	// ConfigSchema — описание настроек для формы в интерфейсе (хост его не толкует).
	ConfigSchema map[string]any `json:"configSchema,omitempty"`
	// Widgets — виджеты плагина: HTML лежит в статике (секция oc.assets, её добавляет утилита ocpack), Entry — путь к нему.
	Widgets []Widget `json:"widgets,omitempty"`
	// Settings — путь HTML-страницы настроек в статике (секция oc.assets). Редактор показывает её в окне «Plugins → Settings».
	Settings string `json:"settings,omitempty"`
	// Events — топики, которые плагин публикует через Publish. Публиковать можно только объявленные.
	Events []EventDecl `json:"events,omitempty"`
}

Meta — описание плагина для oc_meta. Маршруты и подписки SDK добавляет сам по зарегистрированным обработчикам.

type NetLocalStream

type NetLocalStream struct {
	Path          string            `json:"path"`
	Topic         string            `json:"topic"`
	Fields        map[string]string `json:"fields"`
	MinIntervalMs int               `json:"minIntervalMs,omitempty"`
}

NetLocalStream — websocket-поток: пока у топика есть подписчики, хост сам подключается к ws://<Target><Path> (без Origin), берёт из каждого JSON-кадра поля Fields (имя → путь «a.b.c»), и публикует объект из них в топик Topic (объявите его в Meta.Events). MinIntervalMs — не чаще (100..60000, по умолчанию 250): лишние кадры отбрасываются без разбора. Нужно PermNetLocal.

type NetLocalTarget

type NetLocalTarget struct {
	Target  string   `json:"target"`
	Setting string   `json:"setting,omitempty"`
	Paths   []string `json:"paths,omitempty"`
	// Streams — websocket-потоки программы, которые хост ретранслирует в события плагина (wasm не вызывается).
	Streams []NetLocalStream `json:"streams,omitempty"`
}

NetLocalTarget — адрес программы на этом компьютере: Target — host:port (127.0.0.1, localhost или [::1]). Setting — имя строковой настройки, которой пользователь заменяет адрес; Paths — допустимые префиксы пути (пусто — любой). Fetch на объявленный адрес идёт по http, без редиректов, ответ до 8 МиБ.

type Plugin

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

Plugin — регистрация маршрутов и обработчиков. В одном .wasm один плагин.

func New

func New(m Meta) *Plugin

New создаёт плагин и делает его текущим. Вызывать один раз, из init().

func (*Plugin) Config

func (p *Plugin) Config(v any) error

Config разбирает настройки, которые пользователь задал для плагина (доступны с OnInit).

func (*Plugin) DELETE

func (p *Plugin) DELETE(path string, h Handler)

func (*Plugin) GET

func (p *Plugin) GET(path string, h Handler)

Маршруты доступны как /plugins/<id>/api<path>. Обработчик должен отвечать сразу: долгая работа — через события.

func (*Plugin) OnHTTPResponse

func (p *Plugin) OnHTTPResponse(id string, f func(HTTPResponse))

OnHTTPResponse принимает ответ на Fetch с этим id. Нужно разрешение PermNetHTTP (или PermNetLocal для адреса из Meta.NetLocal).

func (*Plugin) OnInit

func (p *Plugin) OnInit(f func() error)

OnInit вызывается при каждом запуске экземпляра (в том числе после сбоя): здесь просят таймеры. Ошибка останавливает запуск плагина, текст попадёт в его состояние.

func (*Plugin) OnRedemption

func (p *Plugin) OnRedemption(f func(Redemption))

OnRedemption принимает погашения наград. Нужны разрешение PermRedeem в Meta и его выдача пользователем.

func (*Plugin) OnTimer

func (p *Plugin) OnTimer(id string, f func())

OnTimer вызывается, когда сработал таймер с этим id (см. SetTimer). Нужно разрешение PermTimer.

func (*Plugin) PATCH

func (p *Plugin) PATCH(path string, h Handler)

func (*Plugin) POST

func (p *Plugin) POST(path string, h Handler)

func (*Plugin) PUT

func (p *Plugin) PUT(path string, h Handler)

type Redemption

type Redemption struct {
	ID          string `json:"id"`
	RewardID    string `json:"rewardId"`
	RewardTitle string `json:"rewardTitle"`
	UserID      string `json:"userId"`
	UserLogin   string `json:"userLogin"`
	UserName    string `json:"userName"`
	Input       string `json:"input"` // текст зрителя: недоверенный
	Status      string `json:"status"`
	RedeemedAt  string `json:"redeemedAt"`
}

Redemption — погашение награды за баллы канала.

type SettingOption

type SettingOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

SettingOption — вариант списка (Type select).

type Widget

type Widget struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Entry  string `json:"entry"`
	Width  int    `json:"width,omitempty"`
	Height int    `json:"height,omitempty"`
	// Settings — настройки источника на сцене: редактор рисует по ним форму, значения приходят виджету как ?key=value (oc.param).
	Settings []WidgetSetting `json:"settings,omitempty"`
}

Widget — виджет плагина, который пользователь добавляет на сцену. Width/Height — размер по умолчанию (0 — 400×300).

type WidgetSetting

type WidgetSetting struct {
	Key     string          `json:"key"`
	Label   string          `json:"label"`
	Type    string          `json:"type"`
	Group   string          `json:"group,omitempty"`
	Help    string          `json:"help,omitempty"`
	Default any             `json:"default,omitempty"`
	Options []SettingOption `json:"options,omitempty"`
	Min     *float64        `json:"min,omitempty"`
	Max     *float64        `json:"max,omitempty"`
	Step    *float64        `json:"step,omitempty"`
}

WidgetSetting — одна настройка виджета (как в plugin.json HTML-плагинов). Type: string, text, number, range, bool, color, font, select (нужны Options). Default должен совпадать со значением по умолчанию в коде виджета.

Jump to

Keyboard shortcuts

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