Wiki de xBNC — La nueva generación de bouncers IRC Wiki v1.0.0

Wiki Desarrollar

Desarrollar

Escribir plugins en C, Rust o cualquier lenguaje que compile a WebAssembly, y traducir xBNC a tu idioma.

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

CampoObligatorioQué es
idsí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).
namesíNombre visible, 1–60 caracteres.
versionsíVersión, 1–20 caracteres.
descriptionnoQué hace.
usagenoCó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.
authornoAutor.
homepagenoPágina del plugin (https://).
abinoVersión de la interfaz (1).
permissionsnoLista de send, raw, timer, presence y http.
http_domainscon httpDe 1 a 10 dominios a los que pide permiso para conectarse.
timer_secsnoCon timer: recibir el temporizador cada 5–60 segundos en lugar de cada minuto.
settingsnoHasta 20 ajustes: {key, type (bool, int, text o lines), label, help, default, min, max}. El panel los muestra como formulario.
translationsnoPor 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:

ExportFirmaQué hace
memorymemoriaMemoria lineal del plugin.
xbnc_alloc(len: i32) -> i32Reserva len bytes para el evento y devuelve su dirección.
xbnc_on_event(ptr: i32, len: i32) -> i64Recibe 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):

ImportQué hace
log(ptr, len)Escribe una línea en el registro (máximo 10 por evento y 500 caracteres).
now_ms() -> i64Milisegundos desde 1970.
kv_get, kv_set, kv_del, kv_listAlmacé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
}
EventoCuándoCampos propios
loadEl plugin arranca en la red (al activarlo o al iniciar xBNC).—
connectedxBNC termina de conectar a la red.—
messageUn mensaje o aviso en un canal o privado, también los tuyos.command, conversation, channel, from, from_mask, text, action, outgoing
commandAlguien escribe /msg *id texto.text
timerCada minuto, o cada timer_secs (permiso timer).—
join, part, kick, quit, nick, namesMovimientos en los canales (permiso presence).los datos de cada movimiento
httpLa 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.
  • state sustituye 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.
  • raw nunca 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 evento http con id, status, body (hasta 256 KB) y, si falló, error.

Límites

LímiteValor
Tamaño del fichero4 MB
Memoria16 MB
CPU por eventounos 20 millones de instrucciones (50 millones al arrancar)
Respuesta64 KB y 20 acciones; 5 mensajes por evento
Estado guardado64 KB
Almacén clave-valor16 MB y 200 000 claves por plugin y red
Fallos seguidos antes de detenerse en una red5

SDK de C

sdk/c/xbnc_plugin.h resuelve la interfaz. Funciones principales:

FunciónQué 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_boolLee 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

FicheroQué es
locales/en.jsonInglés. Es la base: tiene todos los textos de xBNC.
locales/es.jsonEspañol.
locales/<código>.jsonCualquier 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}"
  }
}
ParteQué es
languagecode: 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.
ircLo que xBNC dice por IRC. La clave de la izquierda es un nombre; solo se traduce el texto de la derecha.
panelEl panel web. La clave de la izquierda es el texto en inglés; solo se traduce el texto de la derecha.
installerEl 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

  1. Copia en.json como <código>.json (por ejemplo, pt.json).
  2. Cambia la parte language: código, nombre, nombre en inglés, locale y tu nombre.
  3. Traduce los textos de la derecha. No cambies nunca las claves de la izquierda.
  4. Comprueba el fichero: xbncd locales check pt.json (añade --missing para ver lo que falta).
  5. Prueba el instalador en tu idioma: pon el fichero en locales/ del código fuente y ejecuta sudo ./scripts/install.sh --language pt, o elígelo en el menú.
  6. 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.
  7. Envíalo al proyecto para incluirlo en la siguiente versión.

Reglas de los textos

En el texto en inglésQué 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, $nickVariables 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.
PluralesLos 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íneaNo 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("…") o tx("…"). npm run i18n:check (en web/) lista lo que falta en en.json, y node scripts/i18n-check.mjs --sync lo añade.
  • En el servidor, el texto se añade a la sección irc de locales/en.json y se usa con self.t("clave", &[]), tr!(self, "clave", arg1, arg2) o i18n::tr(lang, "clave", &[…]). Los tests comprueban que cada clave usada existe y que es.json las 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.