WarpEngine

A WarpEngine mountolható Rails engine, amely bármelyik Rails-appból retró szoftverkatalógust csinál. Egy játékrepó egyetlen soros .woodpecker.yaml jelölőt visz, a motor kiszolgálja a teljes CI-pipeline-t, a buildek HTTP-n töltődnek fel, egy publikálási hívás pedig upserteli a katalógust. Publikus, read-only JSON API és opcionális ActiveAdmin resource-ok is járnak hozzá.

Amit kapsz

• Katalógus domain — Software, Release, ReleaseAsset, ExternalLink, PlatformLink, SoftwareImage, Download. Mind soft delete-tel, download tracking-gel.
• CI-pipeline-szerver — Woodpecker configuration extension. A játékrepókban csak egy platform marker van. A builder image-ek szerver oldalon élnek, így egy image bump egyszerre ér el minden repót.
• Pluggable CI — 0.7-től minden CI-funkció egyetlen adapteren megy át. A Woodpecker az engine-nel érkezik WarpEngine::CI::Woodpecker néven, és ez a default; a :none kikapcsolja a CI-t, más szerver pedig a hoszt által adott objektum.
• Build endpoint-ok — POST /build/upload és POST /build/publish, shared secret-tel vagy adatbázisbeli application token-ekkel hitelesítve.
• Publikus JSON API — katalógus, kiemelt cím, platformonkénti build mátrix, download tracking, statikus fájlszerver a webes buildekhez.
• A hoszt képtára — 0.6-tól az Image modell, a fájljai, az /api/image/:id endpoint-ja és az admin oldala a hosztban él; az engine egy szoftvert egy képhez köt, és adapteren keresztül publikálja az URL-t. Ugyanaz a tábla ezután avatarokat vagy bármi mást is kiszolgálhat, ami a site-nak kell.
• Pluggable access — a hoszt ad egy policy-t, a katalógus pedig árakat, jogosultságokat és gated download-okat kap, és ezt az API-ban is közli, így egy kliens a fizetős címet fizetősként tudja mutatni ahelyett, hogy letöltéskor bukna el. Default: a nyílt katalógus.
• Client sign-in — RFC 8628 device authorization grant a hoszt user modelljén, böngésző nélküli klienseknek. Konfig nélkül kikapcsolva.
• Opcionális admin — ActiveAdmin resource-ok (katalógusszerkesztő, fájlkezelő, download statisztika, application token-ek). ActiveAdmin nélkül az engine headless módban fut.
• CI-kezelés — API token-nel az admin vezérli a CI-szervert: repo sync, pipeline history kézi trigger-rel, CI secret-ként kiosztott application token-ek.
• Asset-ellenőrzőlista — 0.8-tól a rake warp_engine:builds:check szoftverenként és kiadásonként kiírja, mely assetek vannak meg, és melyeket tudná még a platform pipeline-ja leszállítani. Lásd: Mely assetek hiányoznak.

Támogatott platformok

Platformonként két lista, és a különbség számít. Az elfogadott assetek az, amit a frissítő befogad egy kiadás publikálásakor (WarpEngine::Platform#expected_kinds). A pipeline ezeket építi az, amit a Woodpecker-sablonok ténylegesen elő is állítanak. Ahol eltérnek, ott a maradék kézi feltöltés.

Az Ebitengine az egyetlen hiányosság: egy macOS-bináris osxcrosst igényel, amit a linuxos builder image nem visz, így a mac_x64 és a mac_arm64 mindig csak kézzel érkezik.

Mely assetek hiányoznak

Egy kiadás akkor teljes, ha minden olyan asset-típust visz, amit a platformja pipeline-ja elő tud állítani — és semmi nem kényszeríti ki. Elbukik egy buildlépés, egy platform új célt kap, egy címet laptopról publikálnak, és a katalógus hét assetből hárommal szolgál ki egy kiadást. A motor ellenőrzőlistát szállít hozzá:

$ bin/rails warp_engine:builds:check

WarpEngine release asset coverage — latest release per software
expected: the kinds a platform's updater registers · [ ] the CI builds it · [-] the CI does not, upload it by hand

rabbitroller  ebitengine  v1.1.1  3/7
  [x] html
  [x] win_x64
  [x] linux_x64
  [ ] win_x86
  [ ] linux_arm64
  [-] mac_x64
  [-] mac_arm64

The CI can build these and the release does not have them:
  rabbitroller v1.1.1 (ebitengine): win_x86, linux_arm64

12 softwares, 12 releases, 61/78 assets present, 11 missing from CI-built kinds
4 softwares are missing an asset the CI builds
2 assets are expected but this CI does not build them

A beállítások környezeti változók, így shellből komponálhatók:

A „legfrissebb" a legfrissebb nem dev- verzió — ugyanaz a szabály, amit a katalógus API is használ, amikor megnevezi egy cím legutóbbi kiadását. A számok is objektumok: a WarpEngine::AssetCoverage a #rows, #missing_rows és #totals metódusokra válaszol, a WarpEngine::AssetCoverageChecklist pedig kirendereli őket.

Mindkét hoszton elérhető: a nyilvános oldalon és a Teletype Orbitban.

Végpontok

Nyilvános API

Minden olvasó végpont elfogad egy opcionális Authorization: Bearer … fejlécet; egyik sem követeli meg. A token csak azt változtatja meg, amit a hozzáférési szabályzattól kérdezünk. Az anonim hívó támogatott hívó.

Minden válasz visz egy WarpEngine-Version fejlécet, amely az akció lefutása előtt kerül rá — így a hibaválaszokon is rajta van, és egy kliens plusz kérés nélkül tud a motorverzió szerint ágazni.

$ curl -sI https://teletypegames.org/api/software | grep -i warpengine
WarpEngine-Version: 0.5.0

A hosztalkalmazás saját végpontjai (például az áruház-nyilvántartás) nem viszik — azok nem részei a motornak.

Build / CI

Hozzáférés és identitás

Két seam került be a 0.5.0-ban, mindkettő a storage adapter mintájára: dokumentált contract, a régi viselkedéssel azonos default, és egyetlen config kulcs a cseréjéhez. Ha egyiket sem állítod be, semmi nem változik.

Ki mit láthat és tölthet le

c.access_policy = MyStore::AccessPolicy.new   # :open (alapérték) = a katalógus, ahogy volt

A szabályzat három kérdésre válaszol:

Az authorize_download kérdést az /api/download és a /file/* is felteszi, mielőtt bármit kiszolgálna, így egy hosztnak már nem kell árnyékolnia ezeket az útvonalakat.

Minden katalógusbejegyzés visz egy access blokkot, a nyílt szabályzat alatt is — egy kliensnek soha nem kell találgatnia, hogy a katalógus hallgat-e, vagy a cím egyszerűen nincs kapuzva:

"access": { "gated": true, "entitled": false,
            "price": { "amountCents": 1490, "currency": "EUR" },
            "purchaseUrl": "https://shop.example/games/slug",
            "webUrl": "https://shop.example/play/slug" }

A mezőnevek szándékosan általánosak, mert egy kliens több katalógust olvas.

Ha a policy exception-t dob, az elutasításnak számít: üres katalógus, megtagadott letöltés, logolva. Egy artifactot soha nem szabad azért kiszolgálni, mert a gatekeeper crashelt.

Client sign-in

Egy desktop kliensnek nincs cookie jar-ja és nincs böngésző session-je, ezért az engine login form helyett a device authorization grant-et (RFC 8628) használja.

c.access_token_owner_class  = "User"      # nil (alapérték): sehol nincs belépés
c.identity_verification_url = "/devices"  # a te oldalad, ahol valaki beírja a kódot
c.subject_resolver = ->(request) { request.env["warden"]&.user }   # böngésző felismerése

1. a kliens POST-ol az /api/auth/device végpontra, és megmutatja a userCode értéket;
2. az ember megnyitja az ellenőrzőoldalt, és beírja azt a kódot;
3. a hoszt oldala meghívja a WarpEngine::DeviceGrantService#approve(user_code:, subject:) metódust — a jóváhagyáshoz session és HTML kell, ami nem az engine dolga;
4. a kliens következő lekérdezése elviszi a tokent. Pontosan egyszer adjuk át.

A token egy WarpEngine::ApplicationToken a catalog scope-pal, így a publish és a kliens credential-ök egyetlen táblában is szétválaszthatók maradnak. A subject_resolver fedi le a másik esetet: egy böngésző session-t visz, nem bearer token-t, és enélkül egy gated áruház a saját bejelentkezett látogatóit utasítaná vissza.

Ha az access_token_owner_class nincs beállítva, az /api/auth/* 404-et ad, az /api/service pedig auth: null-t jelent, így a kliens nem kínál sign-in-t.

A képtár

A kép nem katalógusfogalom — ugyanaz a képtár szolgálja ki a borítókat, a képernyőképeket és az avatarokat —, ezért a 0.6.0-tól a motoré csak a kapcsolat (SoftwareImage: sorrendezett, egy alapértelmezett), miközben a modell, a fájlok, a végpont és az adminoldal a hoszté. A rails g warp_engine:install kiír egy működő készletet (app/models/image.rb, app/controllers/api/images_controller.rb, egy create_images migrációt), a motor pedig adapteren keresztül éri el:

c.image_class_name = "Image"          # alapérték
c.image_adapter    = MyLibrary.new    # vagy cseréld le teljesen az adaptert

Az alapértelmezett adapter az /api/image/<id> címet publikálja — azt, amit a kliensek mindig is használtak —, ezért a generált útvonal pontosan ezt szolgálja ki. Az images tábla nem költözött: a motor egyszerűen abbahagyta a létrehozását, és a software_images.image_id továbbra is ugyanazokra a sorokra mutat.

A Woodpecker használata a WarpEngine-nel

Egy játékrepónak nincs saját pipeline-ja. A Woodpecker minden pipeline-indításkor POST-olja az egysoros jelölőt a /build/config végpontra, és visszakapja a teljes YAML-t.

1. A Woodpecker úgy van beállítva, hogy a WarpEngine a konfigurációs kiterjesztése.
2. A repó .woodpecker.yaml fájljában csak a platform: van (és a name:, ha a szoftvernév eltér a repó nevétől).
3. Egy push elküldi a jelölőt a POST /build/config végpontra.
4. A CI-adapter rendereli a lib/warp_engine/ci/woodpecker/platforms/<platform>/pipeline.yaml.erb sablont a beállított builder image-dzsel — a YAML-nyelvjárás a szolgáltatóé, tehát az adapterrel együtt él.
5. A pipeline lefut: verzió → build → feltöltés → publikálás.

Egy repó úgy lép ki ebből, hogy valódi pipeline-YAML-t commitol: a nem jelölő konfiguráció 204 No Content választ kap, és változatlanul fut.

Egy játékrepó beállítása

# .woodpecker.yaml
platform: godot
name: mygame     # opcionális, alapból a repó neve

// metadata.json — a TIC-80-on kívül minden platformon ugyanez
{
  "name": "mygame",
  "version": "1.0.0",
  "title": "My Godot Game",
  "author": "You",
  "desc": "A cool game",
  "license": "MIT"
}

A TIC-80-nak nem kell metadata.json — a metaadat a Lua-fejléc:

-- title: My TIC Game
-- name: mygame
-- author: You
-- desc: A TIC-80 game
-- version: 1.0.0
function TIC() end

A jelölő beállításai

Pipeline előnézete

curl "https://your-host/build/config?platform=godot"

Titkok és verziók

Minden generált pipeline egyetlen Woodpecker-secretet vár, az application_token értéket, amelyet X-Update-Secret fejlécként küld a /build/upload és a /build/publish végpontokra.

A verziózás mindenhol ugyanaz: a main/master ágon a verzió a metadata.json fájlból jön (TIC-80 esetén a -- version: sorból); más ágakon előtagot kap, pl. dev-1.0.0-my-feature.

CI-kezelés (Woodpecker API)

Csak ott aktív, ahol az adapternek van url és api_token értéke (WarpEngine.ci.configured?). Addig az adminoldalak elrejtik magukat.

• Repószinkron — Admin → Pipelines → Sync from Woodpecker (a gomb az adapter nevét viseli). Tükrözi a repólistát Pipeline rekordokba, név alapján párosítja az egyes repókat egy Software rekorddal, és örökli annak platformját. A Woodpeckerből eltűnt repók deaktiválódnak. A linkek kézzel szerkeszthetők maradnak.
• Pipeline-ok — minden bejegyzés felsorolja a legutóbbi futásait (státusz, ág, üzenet, idő) egy kézi Trigger gombbal. A legfrissebb futás frissíti a listaoldalon gyorsítótárazott státuszt. Egy szoftver adminoldala hivatkozik a pipeline-jaira.
• Secret-kiosztás — egy token létrehozása kiosztja az application_token secretet a tulajdonos repóira (korlátozás nélküli tokenek esetén minden aktív repóra); a törlés eltávolítja; a Rotate létrehoz egy cserét, mindenhova kiosztja, és egy lépésben visszavonja a régit.

A PAT-nak Woodpecker-példányadminhoz kell tartoznia — a repók listázása csak admin által hívható végpont, minden más 403 User not authorized választ ad. Vedd fel a felhasználót a WOODPECKER_ADMIN listába, majd lépj ki és vissza: az adminjelző a bejelentkezéskor íródik, a szerver újraindítása nem elég.

Buildhitelesítés

Az X-Update-Secret kétféle hitelesítő adat egyikét viszi, amit az application_token_source választ ki. A módok kizárják egymást.

Cutover warning: a :database módra váltás azonnal érvényteleníti a shared secret-et. Előbb hozd létre a token-eket.

Telepítés egy hosztba

# Gemfile — gitből:
gem "warp_engine", git: "https://git.teletypegames.org/engines/warp_engine.git"

# ...vagy a Forgejo rubygems-regiszteréből (taggelt kiadások):
source "https://git.teletypegames.org/api/packages/engines/rubygems" do
  gem "warp_engine"
end

rails g warp_engine:install   # initializer, képtár, migrációk
rails db:migrate

# config/routes.rb
namespace :api do
  get "image/:id", to: "images#show"   # a képtár a tiéd (lásd lentebb)
end

# a mount maradjon az utolsó, hogy a hoszt saját útvonalai nyerjenek
mount WarpEngine::Engine => "/"

A generátor kiírja a config/initializers/warp_engine.rb fájlt:

Rails.application.config.to_prepare do
  WarpEngine.configure do |c|
    c.file_container_path = ENV.fetch("FILE_CONTAINER_PATH", "/softwares")

    # The image library is the host's; "Image" is the adapter's default.
    # c.image_class_name = "Media::Picture"
    # c.image_adapter    = MyImageLibrary.new

    c.update_secret = ENV["UPDATE_SECRET"]

    # c.application_token_source = :database
    # c.application_token_owner_class = "AdminUser"

    # One adapter carries the whole CI side: server, recipes, signing key.
    c.ci_adapter = WarpEngine::CI::Woodpecker::Adapter.new(
      url:            ENV["WOODPECKER_URL"],
      api_token:      ENV["WOODPECKER_API_TOKEN"],
      repo_owner:     ENV["WOODPECKER_REPO_OWNER"],
      public_key_url: "https://ci.example.org/api/signature/public-key",
      update_server:  "https://catalog.example.org",
      platforms: {
        "godot"      => { builder: "registry.example/godot-builder:4.6" },
        "tic80"      => { builder: "registry.example/tic80-builder:1.0",
                          exporter: "registry.example/tic80pro:1.0" },
        "bevy"       => { builder: "registry.example/bevy-builder:1.0" },
        "love"       => { builder: "registry.example/love-builder:1.0" },
        "ebitengine" => { builder: "registry.example/ebitengine-builder:1.0" },
        "phaser"     => { builder: "registry.example/phaser-builder:1.0" },
        "c64"        => { builder: "registry.example/c64-builder:1.0" }
      }
    )

    # c.max_upload_size = 500 * 1024 * 1024
    # c.enforce_software_ownership = true
  end
end

Adminintegráció

Az ActiveAdmin-példány a hoszté (hitelesítés, téma, útvonalak); a WarpEngine hozzáfűzi az erőforrásait az ActiveAdmin.application.load_paths listához. Egy új hosztnak két dolog kell:

• a fájlválasztó JS a kiadási assetek útvonalmezőihez (iframe → /admin/files?picker=1&field=<dom_id>) az active_admin.js fájljában;
• apipie-dokumentáció esetén a "#{WarpEngine::Engine.root}/app/controllers/**/*.rb" bejegyzés az api_controllers_matcher beállításban.

Viselkedési megjegyzések

• Minden modell soft delete-tel dolgozik (default_scope { where(deleted_at: nil) }).
• A JSON shape stabil, és bug-compatible a korábbi Go backenddel: Go-féle nulla timestamp-ek, camelCase kulcsok, legacy flat path field-ek.
• Model extension point-ok: ActiveSupport.on_load(:warp_engine_<model>).

Tesztelés

bundle install
bundle exec rake app:db:prepare RAILS_ENV=test
bundle exec rspec