Escribir plugins
Un plugin es un fichero WebAssembly con un manifiesto JSON dentro. Hay SDK para C (sdk/c, con los 18 plugins oficiales como ejemplo y el ayudante xbnc_util.h) y para Rust (sdk/rust). Cualquier lenguaje que compile a WebAssembly sin WASI sirve si cumple la interfaz.
Manifiesto
| Campo | Obligatorio | Qué es |
|---|---|---|
id | sí | 1–32 caracteres a-z 0-9 _ -, empezando por letra. No puede ser status, notes, watch, events, xbnc, bnc, plugin ni plugins. Es el nombre de su servicio (*id). |
name | sí | Nombre visible, 1–60 caracteres. |
version | sí | Versión, 1–20 caracteres. |
description | no | Qué hace. |
usage | no | Cómo se usa (hasta 1000 caracteres). El panel lo muestra en «Cómo se usa» y xBNC lo responde si el plugin no contesta a un comando. |
author | no | Autor. |
homepage | no | Página del plugin (https://). |
abi | no | Versión de la interfaz (1). |
permissions | no | Lista de send, raw, timer, presence y http. |
http_domains | con http | De 1 a 10 dominios a los que pide permiso para conectarse. |
timer_secs | no | Con timer: recibir el temporizador cada 5–60 segundos en lugar de cada minuto. |
settings | no | Hasta 20 ajustes: {key, type (bool, int, text o lines), label, help, default, min, max}. El panel los muestra como formulario. |
translations | no | Por código de idioma (es, pt, fr…): name, description, usage y, por ajuste, label y help. Los textos de la raíz del manifiesto son la base, en inglés. |
{
"id": "hola",
"name": "Hello",
"version": "1.0.0",
"description": "Answers !hola.",
"usage": "In a channel: !hola",
"author": "tu-nombre",
"permissions": ["send"],
"settings": [
{ "key": "greeting", "type": "text", "label": "Greeting", "default": "Hello!" },
{ "key": "lang", "type": "text", "label": "Language", "help": "Empty: your xBNC language.", "default": "" }
],
"translations": {
"es": {
"name": "Hola",
"description": "Responde a !hola.",
"usage": "En un canal: !hola",
"settings": { "greeting": { "label": "Saludo" } }
}
}
}
Interfaz (ABI 1)
El módulo exporta:
| Export | Firma | Qué hace |
|---|---|---|
memory | memoria | Memoria lineal del plugin. |
xbnc_alloc | (len: i32) -> i32 | Reserva len bytes para el evento y devuelve su dirección. |
xbnc_on_event | (ptr: i32, len: i32) -> i64 | Recibe el evento (JSON UTF-8) y devuelve (dirección << 32) | longitud de la respuesta (JSON), o 0 si no responde. |
Y solo puede importar del módulo xbnc (ni WASI ni nada más):
| Import | Qué hace |
|---|---|
log(ptr, len) | Escribe una línea en el registro (máximo 10 por evento y 500 caracteres). |
now_ms() -> i64 | Milisegundos desde 1970. |
kv_get, kv_set, kv_del, kv_list | Almacén clave-valor propio del plugin en esa red: claves de hasta 200 bytes, valores de hasta 64 KB, 16 MB y 200 000 claves en total, hasta 2 000 escrituras por evento (se guardan juntas). |
Eventos
{
"event": "message",
"network": "ejemplo", "nick": "y2k", "connected": true, "clients": 1, "lang": "es",
"config": { "trigger": "!dado" },
"state": null,
"command": "PRIVMSG", "conversation": "#xbnc", "channel": true,
"from": "bob", "from_mask": "bob!b@host", "text": "!dado 2d6",
"action": false, "outgoing": false
}
| Evento | Cuándo | Campos propios |
|---|---|---|
load | El plugin arranca en la red (al activarlo o al iniciar xBNC). | — |
connected | xBNC termina de conectar a la red. | — |
message | Un mensaje o aviso en un canal o privado, también los tuyos. | command, conversation, channel, from, from_mask, text, action, outgoing |
command | Alguien escribe /msg *id texto. | text |
timer | Cada minuto, o cada timer_secs (permiso timer). | — |
join, part, kick, quit, nick, names | Movimientos en los canales (permiso presence). | los datos de cada movimiento |
http | La respuesta a una petición web (permiso http). | id, status, body, error |
Campos comunes: network, nick (tu nick actual), connected, clients (clientes conectados), lang (tu idioma), config (sus ajustes) y state (lo que guardó).
Respuesta
{
"actions": [
{ "reply": "texto en la misma conversación" },
{ "tell": "texto solo para ti, como *id" },
{ "privmsg": { "target": "#canal", "text": "..." } },
{ "notice": { "target": "nick", "text": "..." } },
{ "raw": "MODE #canal +o bob" },
{ "http": { "id": "tiempo", "method": "GET", "url": "https://api.open-meteo.com/..." } }
],
"state": { "lo que quieras guardar": 1 }
}
- Textos de una sola línea. Las acciones sin permiso o mal formadas se descartan y quedan en el registro.
statesustituye el estado guardado del plugin en esa red; llega en cada evento y sobrevive a los reinicios. La instancia se mantiene entre eventos mientras la red sigue activa.rawnunca puede enviar QUIT, PASS, USER, NICK, CAP, AUTHENTICATE, OPER, SERVER ni SQUIT.http:('id', 'url', 'method', 'body'). Solo https, a dominios aprobados; métodos GET, POST, PUT y DELETE; cuerpo de hasta 16 KB (texto o JSON); hasta 3 peticiones a la vez y 30 por minuto por plugin y red. La respuesta llega como eventohttpconid,status,body(hasta 256 KB) y, si falló,error.
Límites
| Límite | Valor |
|---|---|
| Tamaño del fichero | 4 MB |
| Memoria | 16 MB |
| CPU por evento | unos 20 millones de instrucciones (50 millones al arrancar) |
| Respuesta | 64 KB y 20 acciones; 5 mensajes por evento |
| Estado guardado | 64 KB |
| Almacén clave-valor | 16 MB y 200 000 claves por plugin y red |
| Fallos seguidos antes de detenerse en una red | 5 |
SDK de C
sdk/c/xbnc_plugin.h resuelve la interfaz. Funciones principales:
| Función | Qué hace |
|---|---|
void on_event(const xbnc_event *ev) | La función que escribes tú: recibe cada evento. |
xbnc_get(ev, "campo", buf, max) | Lee un campo de texto del evento. |
xbnc_is(ev, "campo") | Lee un campo sí/no. |
xbnc_config(ev, "clave", buf, max), xbnc_config_int, xbnc_config_bool | Lee un ajuste. |
xbnc_get_state(ev) | El estado guardado (JSON). |
xbnc_reply(texto), xbnc_tell(texto) | Responder en la conversación o solo a ti. |
xbnc_privmsg(destino, texto), xbnc_notice(destino, texto) | Mensaje o aviso a quien quieras. |
xbnc_raw(línea) | Comando IRC (permiso raw). |
xbnc_http_get(id, url), xbnc_http_post_json(id, url, json) | Peticiones web (permiso http). |
xbnc_state(json) | Guardar el estado. |
xbnc_kv_get, xbnc_kv_set, xbnc_kv_del, xbnc_kv_list (y las variantes _str) | Almacén clave-valor. |
xbnc_log(texto) | Escribir en el registro. |
sdk/c/xbnc_util.h añade lo que usan los plugins oficiales: idioma de la respuesta (u_lang), lectura de comandos con alias (u_command), recorrido del almacén (u_next_key), fechas, zonas horarias con horario de verano europeo y construcción de textos.
#include "xbnc_plugin.h"
void on_event(const xbnc_event *ev) {
static char kind[16], text[256], greeting[128];
xbnc_get(ev, "event", kind, sizeof kind);
if (!xbnc_streq(kind, xbnc_strlen(kind), "message")) return;
xbnc_get(ev, "text", text, sizeof text);
if (!xbnc_streq(text, xbnc_strlen(text), "!hola")) return;
xbnc_config(ev, "greeting", greeting, sizeof greeting);
xbnc_reply(greeting[0] ? greeting : "¡Hola!");
}
cd sdk/c
clang --target=wasm32 -O2 -nostdlib -fno-builtin -I. \
-Wl,--no-entry -Wl,--export-dynamic -Wl,--strip-debug -Wl,-z,stack-size=65536 \
-o hola.raw.wasm hola.c
xbncd plugin pack hola.raw.wasm hola.json -o hola.wasm
xbncd plugin check hola.wasm
sudo -u xbnc xbncd plugin install hola.wasm
# Los ejemplos oficiales: make (o make bundle para copiarlos al catálogo)
Necesita clang y wasm-ld (LLVM 15 o posterior) y llvm-objcopy (o xbncd plugin pack).
SDK de Rust
El crate xbnc-plugin (sdk/rust) da el trait Plugin, el tipo Event (con kind(), text(), conversation(), is_channel(), outgoing(), config_str(), state()…), Response (con reply(), tell(), state()…) y la macro plugin!. Ejemplo incluido (sdk/rust/examples/stats.rs):
//! Example plugin: counts messages per channel and answers "!stats".
//! The counts survive restarts thanks to the persisted state.
//!
//! Build: cargo build -p xbnc-plugin --release --target wasm32-unknown-unknown --example stats
//! then: xbncd plugin pack target/wasm32-unknown-unknown/release/examples/stats.wasm \
//! sdk/rust/examples/stats.json -o stats.wasm
use xbnc_plugin::{plugin, Event, Plugin, Response};
#[derive(Default)]
struct Stats;
impl Plugin for Stats {
fn on_event(&mut self, ev: &Event) -> Response {
let mut r = Response::new();
let mut counts = ev.state().as_object().cloned().unwrap_or_default();
match ev.kind() {
"message" if ev.is_channel() && !ev.outgoing() => {
let chan = ev.conversation().to_lowercase();
let n = counts.get(&chan).and_then(|v| v.as_u64()).unwrap_or(0) + 1;
counts.insert(chan, n.into());
if ev.text().trim() == ev.config_str("trigger") {
r.reply(format!("{} messages counted in {}", n, ev.conversation()));
}
r.state(counts.into());
}
"command" => {
if counts.is_empty() {
r.tell("Nothing counted yet.");
}
let mut v: Vec<_> = counts.iter().collect();
v.sort_by_key(|e| std::cmp::Reverse(e.1.as_u64()));
for (chan, n) in v.into_iter().take(10) {
r.tell(format!("{chan}: {n}"));
}
}
_ => {}
}
r
}
}
plugin!(Stats);
Modo desarrollo
En Plugins → Desarrollo (superadministradores): con el modo activo, xBNC vigila /var/lib/xbnc/plugins/dev/. Un .wasm guardado ahí se comprueba e instala en cuanto cambia y todas las redes lo recargan. Si pones nombre.json junto a nombre.wasm, lo empaqueta solo (no hace falta xbncd plugin pack). Un plugin nuevo se activa en las redes de quien activó el modo. Los resultados y lo que escribe el plugin se ven en el registro en directo de la página.
sudo cp hola.wasm hola.json /var/lib/xbnc/plugins/dev/
Publicar un catálogo propio
Además de los oficiales, xBNC puede ofrecer los plugins de un catálogo remoto firmado ([catalog] en xbnc.toml). El índice es un JSON {"plugins": [{"id", "version", "url", "sha256", "size", "manifest"}]} y su firma Ed25519 en base64 se publica en índice.sig. Cada plugin se comprueba contra el SHA-256 firmado antes de instalarlo.
xbncd plugin catalog-keygen -o catalogo.key # una vez; la pública va en [catalog] public_key
xbncd plugin catalog-entry hola.wasm https://plugins.ejemplo.org/hola.wasm # entrada para el índice
xbncd plugin catalog-sign --key catalogo.key index.json # escribe index.json.sig
Traducir xBNC
xBNC puede hablar cualquier idioma. Todos sus textos están en un fichero por idioma: el panel web, la pantalla de entrada y todo lo que dice por IRC (*status, su ayuda, los avisos y los mensajes de los módulos). Se traduce un fichero y el idioma aparece en todos los selectores de idioma de xBNC, sin programar ni compilar nada.
Los ficheros
| Fichero | Qué es |
|---|---|
locales/en.json | Inglés. Es la base: tiene todos los textos de xBNC. |
locales/es.json | Español. |
locales/<código>.json | Cualquier otro idioma: pt.json, fr.json, pt-BR.json… |
El inglés y el español van dentro del programa. Los demás idiomas, y las correcciones, se ponen en /etc/xbnc/locales/ (locales_dir en xbnc.toml, o la variable XBNC_LOCALES_DIR). xBNC los lee al arrancar y al recargar (sudo systemctl reload xbnc o /msg *status rehash).
{
"language": {
"code": "pt",
"name": "Português",
"english_name": "Portuguese",
"locale": "pt-PT",
"translators": ["Tu nombre o nick"]
},
"irc": {
"connected_to": "Ligado a {0} como {1}.",
"help.group.channels": "Canais"
},
"panel": {
"Joined": "Dentro",
"Delete {username}": "Apagar {username}"
},
"installer": {
"finding_the_program": "A procurar o programa",
"installing_the_binary_to": "A instalar o programa em {0}"
}
}
| Parte | Qué es |
|---|---|
language | code: código del idioma (dos o tres letras, con región si hace falta: pt, pt-BR); el fichero se llama igual. name: nombre del idioma en ese idioma, como sale en los selectores. locale: para fechas y números. translators: sale en xbncd locales list. |
irc | Lo que xBNC dice por IRC. La clave de la izquierda es un nombre; solo se traduce el texto de la derecha. |
panel | El panel web. La clave de la izquierda es el texto en inglés; solo se traduce el texto de la derecha. |
installer | El instalador y los scripts que usa. La clave de la izquierda es un nombre; solo se traduce el texto de la derecha. Un fichero de idioma en locales/ del código fuente aparece en el menú de idiomas del instalador; el instalador lo instala y lo deja como idioma predeterminado de xBNC. |
Paso a paso
- Copia
en.jsoncomo<código>.json(por ejemplo,pt.json). - Cambia la parte
language: código, nombre, nombre en inglés, locale y tu nombre. - Traduce los textos de la derecha. No cambies nunca las claves de la izquierda.
- Comprueba el fichero:
xbncd locales check pt.json(añade--missingpara ver lo que falta). - Prueba el instalador en tu idioma: pon el fichero en
locales/del código fuente y ejecutasudo ./scripts/install.sh --language pt, o elígelo en el menú. - Pruébalo en un servidor ya instalado: cópialo en
/etc/xbnc/locales/y recarga xBNC. Aparece al momento en la pantalla de entrada, en Tu cuenta, en Ajustes y con/msg *status language pt. - Envíalo al proyecto para incluirlo en la siguiente versión.
Reglas de los textos
| En el texto en inglés | Qué hacer |
|---|---|
{0}, {1}… (IRC) | Valores que pone xBNC (un nick, un número…). Mantenlos todos; puedes moverlos dentro de la frase. |
{name}, {count}… (panel) | Igual: mantenlos con el mismo nombre exacto. |
<b>…</b>, <u>…</u> (IRC) | Negrita y subrayado en el cliente IRC. Mantenlos alrededor de las mismas palabras, cada <b> con su </b>. |
Comandos y ajustes (/msg *status help, set away delay 60) | No se traducen: es lo que la gente escribe. |
$1, $nick | Variables del módulo de alias: se dejan tal cual. |
Disabled|network state (clave del panel) | Lo que va tras la | es una pista de dónde sale el texto (para el género, por ejemplo). Se traduce solo el texto, sin la pista. |
| Plurales | Los textos terminados en .one se usan con 1 y los terminados en .other con cualquier otro número (unit.network.one = «{{0}} red»). |
| Saltos de línea | No se admiten en los textos de IRC ni del instalador. |
Un texto que no cumple estas reglas se ignora y sale en inglés; xbncd locales check lo indica como problema. Esto impide también que un fichero de idioma pueda meter comandos IRC (los saltos de línea están prohibidos).
Corregir un idioma incluido
Un fichero de un idioma que ya existe (por ejemplo, es.json en /etc/xbnc/locales/) solo necesita los textos que quieras cambiar: el resto se queda como está.
Lo que no se traduce con un fichero
- Las respuestas de los plugins. Su nombre, descripción y ajustes se traducen en su manifiesto (
translations). Lo que un plugin responde en un canal está escrito en el propio plugin; en un idioma que no incluye, responde en inglés. Los plugins oficiales hablan inglés y español. - El registro del servidor está en inglés.
Traducir esta wiki
La wiki es un proyecto propio, aparte de la app (xbnc-wiki), para que cualquiera pueda leerla sin instalar xBNC. Se genera con build.py a partir de un fichero de contenido por idioma (content/en.py es la base) y del código fuente de xBNC. Para traducirla, copia en.py como <código>.py y traduce los textos entre comillas sin tocar las etiquetas HTML ni las llamadas como code(…). Las tablas de módulos, plugins y comandos se traducen solas con los ficheros de idioma de xBNC. Al generar la wiki, cada idioma aparece en el selector de la cabecera.
Para desarrolladores
- En el panel, los textos se escriben en inglés dentro de
t("…"),tk("…")otx("…").npm run i18n:check(enweb/) lista lo que falta enen.json, ynode scripts/i18n-check.mjs --synclo añade. - En el servidor, el texto se añade a la sección
ircdelocales/en.jsony se usa conself.t("clave", &[]),tr!(self, "clave", arg1, arg2)oi18n::tr(lang, "clave", &[…]). Los tests comprueban que cada clave usada existe y quees.jsonlas traduce todas con los mismos marcadores.
La guía completa, en inglés, está en TRANSLATING.md, en el código fuente; esta sección es su versión en español.