익스텐션 개발 가이드

사바쨩 데몬의 10가지 실제 훅과 manifest.json 스펙, GUI 슬롯 주입, 그리고 기본 제공 익스텐션의 구현 포인트.

익스텐션 개발 가이드

익스텐션(Extension, 플러그인)은 특정 게임에 묶이지 않고 데몬의 수명 주기 전역에 개입하거나 GUI에 컴포넌트를 주입하는 확장입니다. 사바쨩 데몬은 다음 10개 지점(훅)에서 활성화된 익스텐션에게 제어를 넘깁니다. 현재 기본 제공 익스텐션은 SteamCMD 설치·업데이트(steamcmd)와 UE4 INI 파서(ue4-ini) 두 가지입니다.

이 문서의 내용은 saba-chan-extensions 저장소의 실제 manifest.json과 데몬 측 익스텐션 시스템(src/extension/mod.rs)을 기준으로 작성되었습니다.


1. 파일 구조

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.json필수. 훅·의존성·필드 선언필수. 훅·의존성·필드 선언
  • __init__.py모듈이 extensions.<이름> 으로 import 할 수 있게모듈이 extensions.<이름> 으로 import 할 수 있게
  • <python_modules>.pymanifest.json 의 python_modules 에서 가리키는 파일들manifest.json 의 python_modules 에서 가리키는 파일들
  • icon.png선택선택
  • gui/선택. GUI 번들(UMD) 소스와 빌드 결과선택. GUI 번들(UMD) 소스와 빌드 결과
  • i18n/선택. manifest 의 i18n_dir 로 지정 (<locale>.json)선택. manifest 의 i18n_dir 로 지정 (<locale>.json)
  • test_<name>.py권장. pytest 테스트권장. pytest 테스트
  • 폴더 이름은 manifest의 id와 같아야 합니다. id의 하이픈을 밑줄로 바꾼 이름도 허용됩니다(예: id ue4-ini → 폴더 ue4_ini). 다르면 데몬이 로드하지 않고 GET /api/extensions의 failed에 남깁니다.
  • id는 영문·숫자·-·_만 쓸 수 있습니다.

2. manifest.json 스펙

SteamCMD 익스텐션의 실제 매니페스트:

{
  "schema_version": 1,                    // 1이면 모르는 키·발화되지 않는 훅이 오류
  "id": "steamcmd",                       // 폴더명과 일치
  "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": [],                     // 다른 익스텐션 의존 (배열 또는 { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // 논리 이름 → 파일 경로
  },

  "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 }
}

필드 요약:

  • schema_version: 1이면 모르는 키, FIRED_HOOKS에 없는 훅 이름, 없는 python_modules 참조가 오류입니다. 없으면(0) 경고만 남깁니다.
  • id, name, version: 필수. version은 업데이트·의존성 비교에 쓰입니다.
  • description / descriptions: 영어 설명과 언어별 설명. 목록 API가 GUI 언어에 맞는 것을 고릅니다.
  • min_app_version: 이보다 오래된 사바쨩에서는 활성화·설치할 수 없습니다.
  • dependencies: 다른 익스텐션(또는 saba-core) 의존. 버전 조건은 >=만 지원합니다. 활성화할 때 의존 익스텐션이 켜져 있는지 검사하며, 자동으로 켜지는 않습니다.
  • python_modules: 훅·명령에서 참조할 Python 파일을 논리 이름으로 등록합니다. 여기 없는 파일은 훅이 호출할 수 없습니다.
  • hooks.<훅 이름>
    • module: python_modules에 선언된 논리 이름
    • function: 해당 파일 안의 함수 이름
    • condition (선택): instance.ext_data.<키> 형식만 지원합니다. 그 값이 true·0이 아닌 숫자·비어 있지 않은 문자열인 인스턴스에서만 실행됩니다.
  • instance_fields: 인스턴스별로 이 익스텐션이 쓰는 값(extension_data). 값이 들어 있는 인스턴스가 있으면 비활성화·삭제가 거부됩니다(in_use).
  • config_fields: 익스텐션 전역 설정 필드. 값은 config.json의 extensions.settings.<id>에 저장됩니다.
  • gui: bundle(UMD 번들 경로), styles(CSS 경로). 아래 5절 참고.
  • cli: CLI 슬롯 선언(cli.slots).
  • commands: 인스턴스 명령 목록에 더할 명령(name, label, risk, inputs, module, function, condition).
  • priority: 같은 훅을 여러 익스텐션이 가질 때의 순서(작을수록 먼저, 기본 100).
  • i18n_dir: 번역 파일 폴더.
  • permissions: 코드가 쓰는 위험한 능력 선언(모듈의 [permissions]와 같은 표).

훅의 async 필드와 manifest의 manifest_url은 없습니다. 익스텐션 목록과 업데이트는 사바쨩의 서명된 릴리스 manifest에서만 나옵니다.


3. 실제 훅 10종

훅 함수는 모듈과 같은 방식으로 실행됩니다. 데몬이 python <파일>.py <함수 이름>을 띄우고 stdin으로 컨텍스트 JSON을 넣으며, stdout의 JSON(전체 또는 마지막 줄)을 결과로 읽습니다. 종료 코드는 0이어야 합니다. 아래 목록은 데몬 코드의 FIRED_HOOKS와 같습니다.

훅 이름호출 시점결과 사용실행 방식
daemon.startup데몬 기동 직후 / 익스텐션 활성화 직후(그 익스텐션만)success·message를 초기화 상태(/api/extensions/init-status)로백그라운드
daemon.shutdown데몬 종료 직전로그만 남김동기
server.pre_start서버 시작 직전handled: true 면 기본 시작을 대신함(이때 success가 true가 아니면 시작 실패)동기
server.stop서버 정지 직전handled: true 면 정지를 대신 처리동기
server.status개별 서버 상태 조회 시handled: true 면 그 결과를 그대로 반환동기
server.list_enrich인스턴스 목록 조회 시handled: true 면 status·extension_status를 채움. 10초 타임아웃, 30초 TTL 캐시동기
server.post_create인스턴스 생성 직후결과를 쓰지 않음백그라운드
server.pre_delete인스턴스 삭제 직전handled 면 파일 잠금 해제를 위해 잠시 대기동기
server.settings_changed인스턴스 설정 저장 후결과를 쓰지 않음동기
server.check_update업데이트 확인 요청 시첫 번째 성공 결과를 응답으로동기

server.pre_create, server.pre_install, server.post_install, server.post_start, module.parse_settings, module.write_settings 같은 이름은 존재하지 않으며, schema_version = 1 manifest에 쓰면 로드가 거부됩니다.

3.1 컨텍스트와 진입점

훅 함수는 컨텍스트 딕셔너리 하나를 받아 딕셔너리를 돌려줍니다. 컨텍스트에는 훅마다 instance_id, instance_name, module, instance_dir, extension_data 등이 들어가고, 모든 훅에 익스텐션 전역 설정 extension_config가 더해집니다. Python 파일은 __main__에서 함수 이름과 stdin을 직접 처리해야 합니다. steamcmd.py의 구조를 줄인 예:

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    ctx 예 (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "내 팰월드",
        "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)      # 로그는 stderr 로
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # 실패도 JSON + 종료 코드 0

3.2 handled와 실행 순서

  • 같은 훅을 가진 익스텐션은 priority, 그다음 id 순으로 하나씩 실행됩니다.
  • 결과에 handled: true가 있으면 나머지 익스텐션은 건너뜁니다. 그 훅의 기본 동작을 대신하지 않을 때는 handled를 넣지 마세요.
  • 한 익스텐션이 실패해도 기록만 하고 다음 익스텐션으로 넘어갑니다.
  • 기본 제한 시간은 120초입니다. 훅 경로에는 진행률(PROGRESS:) 표시가 없습니다.

3.3 server.list_enrich의 TTL 캐시

이 훅은 인스턴스 목록을 조회할 때마다 extension_data가 있는 인스턴스마다 차례로 호출될 수 있으므로, 데몬이 성공 결과를 30초 동안 캐시합니다. 캐시가 유효하면 Python 프로세스를 띄우지 않고 직전 결과를 재사용합니다. 각 호출에는 10초 타임아웃이 걸려 있으므로 빠르게 끝나도록 설계하세요. 결과의 status_line은 짧은 한 줄 상태로 디스코드 상태 표시에 쓰이므로, 경로나 비밀값을 넣지 마세요.


4. 기본 제공 익스텐션 3종

steamcmd

  • id: steamcmd
  • Python: steamcmd.py (SteamCMD 클래스: 포터블 SteamCMD 설치, 게임 서버 설치·업데이트, 업데이트 확인)
  • 훅: server.check_update 하나 (condition: instance.ext_data.install_method_steamcmd).
  • 실제 설치는 모듈의 install_server가 from extensions.steamcmd import SteamCMD로 직접 수행합니다.
  • instance_fields: install_method_steamcmd, steamcmd_app_id, steamcmd_anonymous, steamcmd_beta, steamcmd_platform. 데몬이 모듈의 [install] 섹션을 보고 범용 규칙(install_method_<방식>, <방식>_<필드>)으로 채웁니다.
  • GUI 없음.

ue4-ini

  • id: ue4-ini (폴더명 ue4_ini)
  • Python: ue4_ini.py (parse_option_settings, write_option_settings)
  • 용도: Palworld 등 UE4 게임의 INI OptionSettings=(...)를 읽고 쓰는 유틸을 모듈에 제공합니다.
  • 훅을 선언하지 않는 순수 라이브러리이며, 모듈이 extensions.ue4_ini로 import 해서 씁니다.

xna

  • id: xna
  • Python: xna.py (install, present, XnaError)
  • 용도: Microsoft XNA Framework 4.0 Refresh 고정 판을 PC에 설치하지 않고 게임 서버 폴더 옆에 둡니다. Terraria의 Windows 서버가 씁니다. 공식 배포 MSI를 한 번 받아 고정한 SHA-256으로 확인한 뒤 필요한 파일만 꺼냅니다.
  • 훅을 선언하지 않는 순수 라이브러리이며, 모듈이 from extensions.xna import install, present로 씁니다.

비활성화된 익스텐션은 모듈이 import 할 수 없습니다. 데몬의 import 가드가 SABA_ENABLED_EXTENSIONS에 없는 extensions.<이름> import를 막습니다.


5. GUI 번들 (슬롯 주입)

manifest.json에 gui.bundle을 선언하면 GUI가 그 파일을 GET /api/extensions/:id/gui로 받아 실행합니다(gui.styles가 있으면 CSS도 넣습니다).

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // 경로는 예시
  • 번들은 UMD 형식으로, 전역 window.SabaExt<PascalCase id>를 만들어야 합니다. id의 -·_를 지우고 다음 글자를 대문자로 바꿉니다(예: steamcmd → window.SabaExtSteamcmd, ue4-ini → window.SabaExtUe4Ini).
  • 그 전역의 **registerSlots()**가 { 슬롯 id: 컴포넌트 | 컴포넌트[] }를 돌려주면 GUI가 해당 슬롯에 끼웁니다.
  • React는 호스트의 window.React를 external로 참조합니다. 컴포넌트는 슬롯이 넘기는 props만으로 동작해야 합니다.
  • 번역은 GET /api/extensions/:id/i18n/:locale로 로드되어 ext_<id> 네임스페이스에 들어갑니다.
슬롯 id위치props
ServerCard.badge서버 카드 뱃지server
ServerCard.headerGauge서버 카드 헤더 게이지server
ServerCard.provision프로비저닝 진행 중인 서버 카드server, provisionProgress, onDismiss, t
ServerCard.expandedStats펼친 서버 카드 통계server, t
ServerSettings.tab서버 설정 탭server, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.options서버 추가 옵션t

server는 /api/servers의 서버 정보이며, 컴포넌트는 extension_data와 extension_status[<extension_id>](server.list_enrich 결과)를 읽을 수 있습니다.


6. REST API에서 익스텐션 다루기

GET    /api/extensions                   설치 목록 (+ 로드 실패 목록)
GET    /api/extensions/init-status       daemon.startup 결과
POST   /api/extensions/rescan            폴더 다시 읽기
GET    /api/extensions/manifest          원격 카탈로그 (서명된 릴리즈 manifest)
GET    /api/extensions/updates           업데이트 목록
POST   /api/extensions/:id/install       설치 (카탈로그에서, sha256 확인)
POST   /api/extensions/:id/enable        활성화 → 그 익스텐션의 daemon.startup 실행
POST   /api/extensions/:id/disable       비활성화
POST   /api/extensions/:id/mount         메모리에 등록
POST   /api/extensions/:id/unmount       메모리에서 해제
DELETE /api/extensions/:id               제거
GET    /api/extensions/:id/config        config_fields 값
PUT    /api/extensions/:id/config        값 갱신
GET    /api/extensions/:id/gui           GUI 번들 (JS)
GET    /api/extensions/:id/gui/styles    GUI 스타일 (CSS)
GET    /api/extensions/:id/icon          아이콘
GET    /api/extensions/:id/audit         코드가 쓰는 능력과 permissions 대조
GET    /api/extensions/:id/i18n/:locale  로케일 JSON

활성 목록은 config.json의 extensions.enabled, 전역 설정값은 extensions.settings에 저장됩니다.


7. 개발 규칙

  • 익스텐션도 데몬 코드에 의존하면 안 됩니다. 데몬이 넘겨주는 컨텍스트와 환경변수만 사용하세요.
  • 경로는 os.path.join으로 만들고 하드코딩하지 않습니다.
  • 훅 함수의 실패도 JSON(success: false와 이유) + 종료 코드 0으로 답하고, 로그와 traceback은 stderr로 보냅니다.
  • condition은 instance.ext_data.<키> 형식만 씁니다. 다른 형식은 항상 거짓으로 처리됩니다.
  • Python 의존성은 데몬의 공용 환경을 씁니다. 익스텐션별 requirements 선언은 없습니다.
  • 확인되지 않은 익스텐션: 서명된 카탈로그에서 받지 않았거나 받은 뒤 바뀐 익스텐션은 모듈과 같이 격리된 환경(Windows AppContainer, 리눅스 bubblewrap)에서 실행됩니다. 백신 검사는 하지 않습니다. 아래는 Windows 기준입니다. 루프백(데몬 API 등)에 접근할 수 없고 SABA_TOKEN_PATH가 주어지지 않으며, 인스턴스 폴더는 읽기만 할 수 있습니다. 쓸 데이터는 환경변수 SABA_EXTENSION_DATA_DIR이 가리키는 전용 폴더에 둡니다.
  • 테스트는 저장소 루트에서 pytest로 실행합니다.