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
- func CancelRedemption(rewardID, id string) error
- func ClearTimer(id string)
- func Debug(msg string, kv ...any)
- func Error(msg string, kv ...any)
- func Fetch(id string, r FetchRequest) error
- func FulfillRedemption(rewardID, id string) error
- func Info(msg string, kv ...any)
- func Load[T any](key string) (v T, found bool, err error)
- func Publish(topic string, v any) error
- func PublishRetained(topic string, v any) error
- func Remove(key string) error
- func Say(text string) error
- func SetHost(h func(op string, arg []byte) []byte)
- func SetTimer(id string, d time.Duration, repeat bool) error
- func Store(key string, v any) error
- func Warn(msg string, kv ...any)
- type Ctx
- type EventDecl
- type FetchRequest
- type HTTPResponse
- type Handler
- type Meta
- type NetLocalStream
- type NetLocalTarget
- type Plugin
- func (p *Plugin) Config(v any) error
- func (p *Plugin) DELETE(path string, h Handler)
- func (p *Plugin) GET(path string, h Handler)
- func (p *Plugin) OnHTTPResponse(id string, f func(HTTPResponse))
- func (p *Plugin) OnInit(f func() error)
- func (p *Plugin) OnRedemption(f func(Redemption))
- func (p *Plugin) OnTimer(id string, f func())
- func (p *Plugin) PATCH(path string, h Handler)
- func (p *Plugin) POST(path string, h Handler)
- func (p *Plugin) PUT(path string, h Handler)
- type Redemption
- type SettingOption
- type Widget
- type WidgetSetting
Constants ¶
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 ¶
CancelRedemption отменяет погашение, баллы возвращаются зрителю.
func Debug ¶
Debug/Info/Warn/Error пишут в лог приложения с пометкой плагина; kv — пары «ключ, значение».
func Fetch ¶
func Fetch(id string, r FetchRequest) error
Fetch запускает запрос и сразу возвращается; ответ придёт в OnHTTPResponse(id).
func FulfillRedemption ¶
FulfillRedemption отмечает погашение выполненным.
func Publish ¶
Publish публикует событие в топик, объявленный в Meta.Events: его получают подписчики (виджеты, аддоны, deck). Данные должны кодироваться в JSON (до 64 КБ). Частота ограничена хостом; при превышении вернётся ошибка.
func PublishRetained ¶
PublishRetained публикует событие и просит хост хранить последнее значение топика: новый подписчик получит его сразу. Подходит для состояния («сейчас играет»), а не для команд.
func Say ¶
Say пишет в чат канала стримера от имени бота. Канал и аккаунт выбирает хост, текст — до 300 символов; частота ограничена (всплеск 3 сообщения, затем одно в 3 секунды). Отправка идёт в фоне: nil означает, что хост принял сообщение, а не что оно дошло (нет аккаунта бота, нет связи с чатом — это попадёт в лог OC).
func SetHost ¶
SetHost подменяет связь с хостом (для тестов плагина на обычном `go test`). В wasm не нужен.
func SetTimer ¶
SetTimer запускает таймер хоста (50 мс … 24 ч); срабатывание придёт в OnTimer(id). Тот же id заменяет таймер.
Types ¶
type Ctx ¶
Ctx — запрос к маршруту и ответ на него.
func (*Ctx) Error ¶
Error отвечает {"error": msg} с указанным статусом. Сообщение увидит вызывающий — не кладите в него внутренние детали.
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 ¶
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 (*Plugin) Config ¶
Config разбирает настройки, которые пользователь задал для плагина (доступны с OnInit).
func (*Plugin) GET ¶
Маршруты доступны как /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 ¶
OnInit вызывается при каждом запуске экземпляра (в том числе после сбоя): здесь просят таймеры. Ошибка останавливает запуск плагина, текст попадёт в его состояние.
func (*Plugin) OnRedemption ¶
func (p *Plugin) OnRedemption(f func(Redemption))
OnRedemption принимает погашения наград. Нужны разрешение PermRedeem в Meta и его выдача пользователем.
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 ¶
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 должен совпадать со значением по умолчанию в коде виджета.