Guia de desenvolvimento de extensões

Os 10 hooks reais do Saba-chan e a especificação do manifest.json, a injeção em slots da GUI e notas de implementação das extensões incluídas.

Guia de desenvolvimento de extensões

Uma extensão (plugin) é um complemento que não está ligado a um jogo específico e, em vez disso, se encaixa globalmente no ciclo de vida do daemon, ou que injeta componentes na GUI. O daemon do Saba-chan passa o controle às extensões ativadas nos 10 pontos (hooks) a seguir. As extensões incluídas hoje são a instalação/atualização via SteamCMD (steamcmd) e o parser de INI do UE4 (ue4-ini).

O conteúdo deste documento se baseia nos arquivos manifest.json reais do repositório saba-chan-extensions e no sistema de extensões do lado do daemon (src/extension/mod.rs).


1. Estrutura de arquivos

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.jsonobrigatório. Declara hooks, dependências, camposobrigatório. Declara hooks, dependências, campos
  • __init__.pypermite que os módulos a importem como extensions.<name>permite que os módulos a importem como extensions.<name>
  • <python_modules>.pyarquivos referenciados por python_modules no manifest.jsonarquivos referenciados por python_modules no manifest.json
  • icon.pngopcionalopcional
  • gui/opcional. Código-fonte e saída de build do pacote da GUI (UMD)opcional. Código-fonte e saída de build do pacote da GUI (UMD)
  • i18n/opcional. Definido com i18n_dir no manifesto (<locale>.json)opcional. Definido com i18n_dir no manifesto (<locale>.json)
  • test_<name>.pyrecomendado. Testes com pytestrecomendado. Testes com pytest
  • O nome da pasta precisa corresponder ao id do manifesto. O id com os hifens trocados por sublinhados também é aceito (por exemplo, id ue4-ini → pasta ue4_ini). Caso contrário, o daemon não a carrega e a lista em failed no GET /api/extensions.
  • Um id só pode conter letras, dígitos, - e _.

2. Especificação do manifest.json

O manifesto real da extensão SteamCMD:

{
  "schema_version": 1,                    // com 1, chaves desconhecidas e hooks que nunca disparam são erros
  "id": "steamcmd",                       // corresponde ao nome da pasta
  "name": "SteamCMD",
  "version": "0.1.0",
  "description": "Installs and updates game servers with SteamCMD",
  "descriptions": { "ko": "SteamCMD를 사용한 게임 서버 설치 및 업데이트 자동화" },
  "author": "WareAoba",
  "min_app_version": "0.1.0",
  "dependencies": [],                     // dependências de outras extensões (array ou { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // nome lógico → caminho do arquivo
  },

  "hooks": {
    "server.check_update": {
      "module": "steamcmd",
      "function": "check_update",
      "condition": "instance.ext_data.install_method_steamcmd"
    }
  },

  "instance_fields": {
    "install_method_steamcmd": { "type": "boolean", "default": false },
    "steamcmd_app_id": { "type": "number", "optional": true },
    "steamcmd_anonymous": { "type": "boolean", "default": true },
    "steamcmd_beta": { "type": "string", "optional": true },
    "steamcmd_platform": { "type": "string", "optional": true }
  },
  "permissions": { "network": true, "spawn_process": true }
}

Resumo dos campos:

  • schema_version: Com 1, chaves desconhecidas, nomes de hook que não estão em FIRED_HOOKS e referências a python_modules inexistentes são erros. Sem ele (0), são apenas avisos.
  • id, name, version: Obrigatórios. version é usado nas comparações de atualização e de dependências.
  • description / descriptions: Descrição em inglês e descrições por idioma. A API de listagem escolhe a que corresponde ao idioma da GUI.
  • min_app_version: A extensão não pode ser ativada nem instalada em um Saba-chan mais antigo.
  • dependencies: Dependências de outras extensões (ou do saba-core). Só requisitos de versão >= são suportados. A ativação verifica se as dependências estão ativadas; ela não as ativa automaticamente.
  • python_modules: Registra, por nome lógico, os arquivos Python que os hooks e comandos referenciam. Arquivos não registrados aqui não podem ser chamados pelos hooks.
  • hooks.<nome do hook>
    • module: um nome lógico declarado em python_modules
    • function: o nome da função dentro desse arquivo
    • condition (opcional): só a forma instance.ext_data.<key> é suportada. O hook roda apenas para instâncias em que esse valor é verdadeiro, um número diferente de zero ou uma string não vazia.
  • instance_fields: Valores por instância que esta extensão usa (extension_data). Se alguma instância tiver um valor definido, desativar ou remover a extensão é recusado (in_use).
  • config_fields: Campos de configuração global da extensão. Os valores são guardados em extensions.settings.<id> no config.json.
  • gui: bundle (caminho do pacote UMD), styles (caminho do CSS). Veja a seção 5 abaixo.
  • cli: Declarações de slots da CLI (cli.slots).
  • commands: Comandos adicionados à lista de comandos da instância (name, label, risk, inputs, module, function, condition).
  • priority: Ordem quando várias extensões têm o mesmo hook (menor roda primeiro, padrão 100).
  • i18n_dir: Pasta dos arquivos de tradução.
  • permissions: Declara as capacidades de risco que o código usa (a mesma tabela do [permissions] de um módulo).

Não existe campo async nos hooks nem manifest_url no manifesto. A lista de extensões e as atualizações vêm apenas do manifesto de release assinado do Saba-chan.


3. Os 10 hooks reais

As funções de hook rodam da mesma forma que os módulos. O daemon inicia python <arquivo>.py <nome da função>, grava o JSON de contexto no stdin e lê o JSON do stdout (inteiro ou a última linha) como resultado. O código de saída precisa ser 0. A lista abaixo é a mesma de FIRED_HOOKS no código do daemon.

Nome do hookQuando é chamadoComo o resultado é usadoExecução
daemon.startupLogo após o início do daemon / logo após uma extensão ser ativada (somente essa extensão)success/message vão para o estado de inicialização (/api/extensions/init-status)Em segundo plano
daemon.shutdownLogo antes de o daemon encerrarApenas registrado em logSíncrona
server.pre_startLogo antes de um servidor iniciarhandled: true substitui o início padrão (se success não for verdadeiro nesse caso, o início falha)Síncrona
server.stopLogo antes de um servidor pararhandled: true assume a paradaSíncrona
server.statusAo consultar o status de um servidor específicohandled: true devolve esse resultado como estáSíncrona
server.list_enrichAo listar instânciashandled: true preenche status e extension_status. Tempo limite de 10 s, cache com TTL de 30 sSíncrona
server.post_createLogo após uma instância ser criadaO resultado não é usadoEm segundo plano
server.pre_deleteLogo antes de uma instância ser excluídaSe handled, espera um pouco para que os bloqueios de arquivo sejam liberadosSíncrona
server.settings_changedDepois que as configurações da instância são salvasO resultado não é usadoSíncrona
server.check_updateQuando uma verificação de atualização é pedidaO primeiro resultado bem-sucedido vira a respostaSíncrona

Nomes como server.pre_create, server.pre_install, server.post_install, server.post_start, module.parse_settings e module.write_settings não existem; usá-los em um manifesto com schema_version = 1 faz o carregamento falhar.

3.1 Contexto e ponto de entrada

Uma função de hook recebe um dicionário de contexto e devolve um dicionário. Dependendo do hook, o contexto contém instance_id, instance_name, module, instance_dir, extension_data e assim por diante, e todo hook também recebe as configurações globais das extensões como extension_config. O arquivo Python precisa tratar sozinho o nome da função e o stdin no __main__. Um exemplo resumido da estrutura do steamcmd.py:

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    exemplo de ctx (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "My Palworld",
        "module": "palworld",
        "instance_dir": "…",
        "install_dir": "…",
        "app_id": 2394010,
        "extension_data": {"install_method_steamcmd": true, ...},
        "extension_config": {...}
      }
    """
    ...
    return {"success": True, "update_available": False}

FUNCTIONS = {"check_update": check_update}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else ""
    try:
        raw = sys.stdin.read()
        ctx = json.loads(raw) if raw.strip() else {}
        result = FUNCTIONS[name](ctx) if name in FUNCTIONS else \
            {"success": False, "message": f"Unknown function: {name}"}
    except Exception as e:
        traceback.print_exc(file=sys.stderr)      # os logs vão para o stderr
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # falhas também são JSON + código de saída 0

3.2 handled e ordem de execução

  • Extensões com o mesmo hook rodam uma de cada vez, ordenadas por priority e depois por id.
  • Se um resultado contiver handled: true, as extensões restantes são puladas. Deixe handled de fora, a menos que você esteja substituindo o comportamento padrão daquele hook.
  • Se uma extensão falhar, o erro é registrado e a próxima extensão roda.
  • O tempo limite padrão é de 120 segundos. O caminho dos hooks não tem exibição de progresso (PROGRESS:).

3.3 Cache com TTL do server.list_enrich

Este hook pode ser chamado, um após o outro, para cada instância que tenha extension_data, a cada vez que a lista de instâncias é pedida, então o daemon guarda em cache os resultados bem-sucedidos por 30 segundos. Enquanto o cache é válido, ele reaproveita o resultado anterior sem iniciar um processo Python. Cada chamada tem um tempo limite de 10 segundos, então projete-a para terminar rápido. O status_line do resultado é um status curto de uma linha mostrado na exibição de status do Discord, então não coloque caminhos nem segredos nele.


4. As 3 extensões incluídas

steamcmd

  • id: steamcmd
  • Python: steamcmd.py (classe SteamCMD: instalação portátil do SteamCMD, instalação/atualização de servidores de jogo, verificação de atualizações)
  • Hook: apenas server.check_update (condition: instance.ext_data.install_method_steamcmd).
  • A instalação de fato é feita diretamente pelo install_server do módulo via from extensions.steamcmd import SteamCMD.
  • instance_fields: install_method_steamcmd, steamcmd_app_id, steamcmd_anonymous, steamcmd_beta, steamcmd_platform. O daemon os preenche a partir da seção [install] do módulo usando uma regra genérica (install_method_<method>, <method>_<field>).
  • Sem GUI.

ue4-ini

  • id: ue4-ini (nome da pasta ue4_ini)
  • Python: ue4_ini.py (parse_option_settings, write_option_settings)
  • Finalidade: fornece aos módulos utilitários para ler e gravar o OptionSettings=(...) do INI de jogos UE4, como o Palworld.
  • É uma biblioteca pura que não declara hooks; os módulos a importam como extensions.ue4_ini.

xna

  • id: xna
  • Python: xna.py (install, present, XnaError)
  • Finalidade: mantém uma versão fixa do Microsoft XNA Framework 4.0 Refresh ao lado da pasta do servidor de jogo, sem instalá-la no PC. É usada pelo servidor Windows do Terraria. Baixa uma vez o MSI de distribuição oficial, confere com um SHA-256 fixo e extrai só os arquivos necessários.
  • É uma biblioteca pura que não declara hooks; os módulos a usam com from extensions.xna import install, present.

Os módulos não podem importar extensões desativadas. A proteção de import do daemon bloqueia a importação de qualquer extensions.<name> que não esteja em SABA_ENABLED_EXTENSIONS.


5. Pacote da GUI (injeção em slots)

Se o manifest.json declarar gui.bundle, a GUI busca esse arquivo por GET /api/extensions/:id/gui e o executa (e também injeta o CSS se gui.styles estiver definido).

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // caminhos de exemplo
  • O pacote está no formato UMD e precisa criar o global window.SabaExt<id em PascalCase>. Remova - e _ do id e deixe em maiúscula a letra seguinte (por exemplo, steamcmd → window.SabaExtSteamcmd, ue4-ini → window.SabaExtUe4Ini).
  • Quando o registerSlots() desse global devolve { slotId: Component | Component[] }, a GUI os monta nesses slots.
  • O React é referenciado como externo a partir do window.React do host. Os componentes precisam funcionar usando apenas as props que o slot passa.
  • As traduções são carregadas por GET /api/extensions/:id/i18n/:locale no namespace ext_<id>.
Id do slotLocalprops
ServerCard.badgeSelo do cartão do servidorserver
ServerCard.headerGaugeMedidor no cabeçalho do cartão do servidorserver
ServerCard.provisionCartão do servidor durante o provisionamentoserver, provisionProgress, onDismiss, t
ServerCard.expandedStatsEstatísticas do cartão do servidor expandidoserver, t
ServerSettings.tabAba das configurações do servidorserver, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.optionsOpções de adicionar servidort

server são as informações do servidor vindas de /api/servers; os componentes podem ler extension_data e extension_status[<extension_id>] (o resultado do server.list_enrich).


6. Gerenciando extensões pela REST API

GET    /api/extensions                   Lista de instaladas (+ falhas de carregamento)
GET    /api/extensions/init-status       Resultados do daemon.startup
POST   /api/extensions/rescan            Relê a pasta
GET    /api/extensions/manifest          Catálogo remoto (manifesto de release assinado)
GET    /api/extensions/updates           Lista de atualizações
POST   /api/extensions/:id/install       Instala (a partir do catálogo, sha256 conferido)
POST   /api/extensions/:id/enable        Ativa → executa o daemon.startup dessa extensão
POST   /api/extensions/:id/disable       Desativa
POST   /api/extensions/:id/mount         Registra na memória
POST   /api/extensions/:id/unmount       Remove o registro da memória
DELETE /api/extensions/:id               Remove
GET    /api/extensions/:id/config        Valores de config_fields
PUT    /api/extensions/:id/config        Atualiza os valores
GET    /api/extensions/:id/gui           Pacote da GUI (JS)
GET    /api/extensions/:id/gui/styles    Estilos da GUI (CSS)
GET    /api/extensions/:id/icon          Ícone
GET    /api/extensions/:id/audit         Compara as capacidades usadas pelo código com as permissions
GET    /api/extensions/:id/i18n/:locale  JSON de idioma

A lista de ativadas é guardada em extensions.enabled no config.json, e os valores de configuração global em extensions.settings.


7. Regras de desenvolvimento

  • As extensões também não podem depender do código do daemon. Use apenas o contexto e as variáveis de ambiente que o daemon passa.
  • Monte caminhos com os.path.join; não os deixe fixos no código.
  • As funções de hook também respondem às falhas com JSON (success: false e um motivo) e código de saída 0, e enviam logs e tracebacks para o stderr.
  • Use apenas a forma instance.ext_data.<key> em condition. Qualquer outra forma sempre é avaliada como falsa.
  • As dependências Python usam o ambiente compartilhado do daemon. Não há declaração de requirements por extensão.
  • Extensões não verificadas: extensões que não foram baixadas do catálogo assinado, ou que foram alteradas depois do download, rodam no mesmo ambiente isolado dos módulos (AppContainer no Windows, bubblewrap no Linux). Não há verificação por antivírus. O que segue vale para o Windows. Elas não alcançam o loopback (como a API do daemon), não recebem SABA_TOKEN_PATH e só podem ler as pastas das instâncias. Coloque os dados que precisar gravar na pasta dedicada indicada pela variável de ambiente SABA_EXTENSION_DATA_DIR.
  • Execute os testes com pytest a partir da raiz do repositório.