Phase 4: move catalog controllers and routes into WarpEngine

- update, files and the 6 /api catalog controllers now live in the engine on
  a new WarpEngine::ApiController base (same rescue/mime behavior as host)
- engine routes serve /update, /file/*path, /api/software*, /api/builds*,
  /api/image/:id, /api/download at unchanged public paths via the root mount;
  host routes keep only TTG endpoints (events, members, wiki, rss, swagger)
- /update secret comes from WarpEngine.config.update_secret and an
  unconfigured secret now rejects every request (previously an empty
  UPDATE_SECRET env accepted empty secrets)
- apipie-rails is an engine dependency (DSL in engine controllers); dummy app
  configures apipie with validation off, mirroring the host
- engine request specs: catalog controller specs moved from host plus new
  /update auth contract spec

Verified: engine suite 53 green, host suite 6 green, /api/software and
/api/builds byte-identical to baselines, /update 401/400 behavior intact,
admin and TTG endpoints OK.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app/controllers/warp_engine/api/builds_controller.rb

@@ -0,0 +1,7 @@
+module WarpEngine
+  class Api::BuildsController < ApiController
+    def index
+      render json: WarpEngine::BuildsService.new.index
+    end
+  end
+end

app/controllers/warp_engine/api/downloads_controller.rb

@@ -0,0 +1,31 @@
+module WarpEngine
+  class Api::DownloadsController < ApiController
+    resource_description do
+      short "File downloads"
+      formats [ "binary" ]
+    end
+
+    api :GET, "/api/download", "Download a file by path"
+    param :path, String, required: true, desc: "File path to download"
+    returns code: 200, desc: "File binary data"
+    error code: 400, desc: "Path is blank"
+    error code: 404, desc: "File not found"
+    def show
+      path = params[:path]
+      return render(json: { error: "Path is required" }, status: :bad_request) if path.blank?
+
+      full_path = WarpEngine::DownloadService.new.create(
+        path: path,
+        ip: request.remote_ip,
+        user_agent: request.user_agent,
+        referer: request.referer
+      )
+
+      if full_path
+        send_file full_path, disposition: "attachment", type: resolve_mime(full_path)
+      else
+        render json: { error: "Not found" }, status: :not_found
+      end
+    end
+  end
+end

app/controllers/warp_engine/api/images_controller.rb

@@ -0,0 +1,17 @@
+module WarpEngine
+  class Api::ImagesController < ApiController
+    resource_description do
+      short "Images"
+      formats [ "binary" ]
+    end
+
+    api :GET, "/api/image/:id", "Get image by ID"
+    param :id, :number, required: true, desc: "Image ID"
+    returns code: 200, desc: "Image binary data"
+    error code: 404, desc: "Image not found"
+    def show
+      image = WarpEngine::ImageService.new.show(WarpEngine::ImageShowInputDto.new(id: params[:id]))
+      send_file image.file_path, type: image.content_type, disposition: "inline"
+    end
+  end
+end

app/controllers/warp_engine/api/software_builds_controller.rb

@@ -0,0 +1,7 @@
+module WarpEngine
+  class Api::SoftwareBuildsController < ApiController
+    def show
+      render json: WarpEngine::BuildsService.new.show(params[:name])
+    end
+  end
+end

app/controllers/warp_engine/api/software_controller.rb

@@ -0,0 +1,61 @@
+module WarpEngine
+  class Api::SoftwareController < ApiController
+    resource_description do
+      short "Software catalog"
+    end
+
+    def_param_group :external_link do
+      property :ID, Integer, desc: "Link ID"
+      property :softwareId, Integer, desc: "Parent software ID"
+      property :label, String, desc: "Link label (e.g. GitHub)"
+      property :url, String, desc: "Link URL"
+    end
+
+    def_param_group :software_image do
+      property :url, String, desc: "Image URL (e.g. /api/image/123)"
+      property :isDefault, :boolean, desc: "Default image flag"
+      property :position, Integer, desc: "Display order"
+    end
+
+    def_param_group :release do
+      property :ID, Integer, desc: "Release ID"
+      property :softwareId, Integer, desc: "Parent software ID"
+      property :version, String, desc: "Version string"
+      property :cartridgePath, String, desc: "Cartridge file path"
+      property :sourcePath, String, desc: "Source file path"
+      property :htmlFolderPath, String, desc: "HTML playable folder path"
+      property :docsFolderPath, String, desc: "Documentation folder path"
+      property :downloadCount, Integer, desc: "Download count for this release"
+    end
+
+    api :GET, "/api/software", "List all software entries with releases"
+    returns code: 200, desc: "Wrapper object with softwares array" do
+      property :softwares, Array, desc: "Array of software entries" do
+        property :ID, Integer, desc: "Software ID"
+        property :name, String, desc: "Internal name"
+        property :title, String, desc: "Display title"
+        property :author, String, desc: "Author name"
+        property :desc, String, desc: "Short description"
+        property :story, String, desc: "Long description / story"
+        property :license, String, desc: "License type"
+        property :platform, String, desc: "Platform (tic80, love, ebitengine, c64, godot, bevy, phaser)"
+        property :status, String, desc: "Status (active, inactive)"
+        property :highlighted, :boolean, desc: "Currently highlighted"
+        property :imageUrl, String, desc: "Default image URL"
+        property :externalLinks, Array, desc: "External links" do
+          property :ID, Integer, desc: "Link ID"
+          property :label, String, desc: "Link label"
+          property :url, String, desc: "Link URL"
+        end
+        property :images, Array, desc: "Image gallery" do
+          property :url, String, desc: "Image URL"
+          property :isDefault, :boolean, desc: "Default image flag"
+          property :position, Integer, desc: "Display order"
+        end
+      end
+    end
+    def index
+      render json: WarpEngine::SoftwareService.new.index
+    end
+  end
+end

app/controllers/warp_engine/api/software_highlighted_controller.rb

@@ -0,0 +1,45 @@
+module WarpEngine
+  class Api::SoftwareHighlightedController < ApiController
+    resource_description do
+      short "Highlighted software"
+    end
+
+    api :GET, "/api/software/highlighted", "Get currently highlighted software entry"
+    returns code: 200, desc: "Highlighted software with releases and stats" do
+      property :software, Hash, desc: "Software entry" do
+        property :ID, Integer, desc: "Software ID"
+        property :name, String, desc: "Internal name"
+        property :title, String, desc: "Display title"
+        property :author, String, desc: "Author name"
+        property :desc, String, desc: "Short description"
+        property :story, String, desc: "Long description / story"
+        property :license, String, desc: "License type"
+        property :platform, String, desc: "Platform (tic80, love, ebitengine, c64, godot, bevy, phaser)"
+        property :status, String, desc: "Status"
+        property :highlighted, :boolean, desc: "Highlighted flag"
+        property :imageUrl, String, desc: "Default image URL"
+      end
+      property :releases, Array, desc: "All releases" do
+        property :ID, Integer, desc: "Release ID"
+        property :version, String, desc: "Version string"
+        property :cartridgePath, String, desc: "Cartridge path"
+        property :sourcePath, String, desc: "Source path"
+        property :htmlFolderPath, String, desc: "HTML folder path"
+        property :docsFolderPath, String, desc: "Docs folder path"
+        property :downloadCount, Integer, desc: "Download count"
+      end
+      property :latestRelease, Hash, desc: "Latest release object"
+      property :webPlayableRelease, Hash, desc: "Web-playable release (if any)"
+      property :totalDownloads, Integer, desc: "Total download count across all releases"
+    end
+    error code: 404, desc: "No highlighted software found"
+    def index
+      result = WarpEngine::SoftwareHighlightedService.new.index
+      if result
+        render json: result
+      else
+        render json: { error: "no highlighted software found" }, status: :not_found
+      end
+    end
+  end
+end

app/controllers/warp_engine/api_controller.rb

@@ -0,0 +1,32 @@
+module WarpEngine
+  class ApiController < ActionController::API
+    resource_description do
+      api_version "1.0"
+      formats [ "json" ]
+    end
+
+    rescue_from StandardError do |e|
+      Rails.logger.error("[#{self.class.name}] #{e.class}: #{e.message}")
+      render json: { error: "Internal server error" }, status: :internal_server_error
+    end
+
+    rescue_from ActiveRecord::RecordNotFound do |e|
+      render json: { error: "Not found" }, status: :not_found
+    end
+
+    rescue_from Errno::ENOENT do |e|
+      render json: { error: "Not found" }, status: :not_found
+    end
+
+    rescue_from ArgumentError do |e|
+      render json: { error: e.message }, status: :bad_request
+    end
+
+    private
+
+    def resolve_mime(path)
+      ext = File.extname(path.to_s).delete_prefix(".")
+      Mime::Type.lookup_by_extension(ext) || "application/octet-stream"
+    end
+  end
+end

app/controllers/warp_engine/files_controller.rb

@@ -0,0 +1,22 @@
+module WarpEngine
+  class FilesController < ApiController
+    resource_description do
+      short "Static files"
+      formats [ "binary" ]
+    end
+
+    api :GET, "/file/*path", "Serve or redirect to a file"
+    param :path, String, required: true, desc: "File path"
+    returns code: 200, desc: "File binary data"
+    returns code: 301, desc: "Redirect to file URL"
+    error code: 404, desc: "File not found"
+    def show
+      result = WarpEngine::FileService.new.show(WarpEngine::FileShowInputDto.new(path: params[:path]))
+      case result.type
+      when :redirect  then redirect_to result.url, status: :moved_permanently
+      when :file      then send_file result.path, disposition: "inline", type: resolve_mime(result.path)
+      when :not_found then head :not_found
+      end
+    end
+  end
+end

app/controllers/warp_engine/update_controller.rb

@@ -0,0 +1,49 @@
+module WarpEngine
+  class UpdateController < ApiController
+    resource_description do
+      short "Software updater"
+      formats [ "text" ]
+    end
+
+    rescue_from ArgumentError do |e|
+      render plain: e.message, status: :bad_request
+    end
+
+    rescue_from StandardError do |e|
+      Rails.logger.error("[UpdateController] #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}")
+      render plain: "Internal server error", status: :internal_server_error
+    end
+
+    api :GET, "/update", "Update software version in database"
+    param :secret, String, required: true, desc: "Authorization secret"
+    param :platform, String, required: false, desc: "Platform (tic80, love, ebitengine, c64, godot, bevy, phaser)"
+    param :name, String, required: false, desc: "Software name"
+    param :version, String, required: true, desc: "Version string"
+    returns code: 200, desc: "Plain text 'Updated'"
+    error code: 401, desc: "Invalid secret"
+    error code: 400, desc: "Version not provided or invalid arguments"
+    error code: 500, desc: "Internal server error"
+    def update
+      return render plain: "Unauthorized", status: :unauthorized unless authorized?
+      return render plain: "Version not provided", status: :bad_request if params[:version].blank?
+
+      input = WarpEngine::UpdateInputDto.new(
+        platform: params[:platform],
+        name:     params[:name],
+        version:  params[:version]
+      )
+
+      WarpEngine::UpdateService.new.update(input)
+      render plain: "Updated"
+    end
+
+    private
+
+    def authorized?
+      secret = request.headers["X-Update-Secret"].presence || params[:secret]
+      expected = WarpEngine.config.update_secret
+      # Konfigurálatlan secret esetén az endpoint zárva marad.
+      expected.present? && secret == expected
+    end
+  end
+end

config/routes.rb

@@ -1,2 +1,13 @@
 WarpEngine::Engine.routes.draw do
+  namespace :api do
+    get "software",               to: "software#index"
+    get "software/highlighted",   to: "software_highlighted#index"
+    get "image/:id",              to: "images#show"
+    get "download",               to: "downloads#show"
+    get "builds",                 to: "builds#index"
+    get "softwares/:name/builds", to: "software_builds#show"
+  end
+
+  get "update",     to: "update#update"
+  get "file/*path", to: "files#show", format: false
 end

lib/warp_engine.rb

@@ -1,4 +1,5 @@
 require "blueprinter"
+require "apipie-rails"
 
 require "warp_engine/version"
 require "warp_engine/configuration"

spec/dummy/config/initializers/apipie.rb

@@ -0,0 +1,11 @@
+Apipie.configure do |config|
+  config.app_name = "WarpEngine Dummy"
+  config.api_base_url = ""
+  config.doc_base_url = "/api/docs"
+  config.api_controllers_matcher = [
+    "#{WarpEngine::Engine.root}/app/controllers/**/*.rb"
+  ]
+  config.validate = false
+  config.translate = false
+  config.default_version = "1.0"
+end

spec/requests/builds_controller_spec.rb

@@ -0,0 +1,16 @@
+require "rails_helper"
+
+RSpec.describe "GET /api/builds", type: :request do
+  describe "GET /api/builds" do
+    it "returns the global build matrix" do
+      get "/api/builds"
+
+      expect(response).to have_http_status(:ok)
+      json = JSON.parse(response.body)
+      expect(json["platforms"]).to be_a(Hash)
+      expect(json["platforms"]["tic80"]["label"]).to eq("TIC-80")
+      expect(json["platforms"]["tic80"]["kinds"]).to include("cartridge")
+      expect(json["allKinds"]).to be_an(Array)
+    end
+  end
+end

spec/requests/downloads_controller_spec.rb

@@ -0,0 +1,21 @@
+require "rails_helper"
+
+RSpec.describe "GET /api/download", type: :request do
+  describe "GET /api/download" do
+    it "returns bad_request without path" do
+      get "/api/download"
+
+      expect(response).to have_http_status(:bad_request)
+      json = JSON.parse(response.body)
+      expect(json["error"]).to eq("Path is required")
+    end
+
+    it "returns not_found for invalid path" do
+      get "/api/download", params: { path: "nonexistent/file.tic" }
+
+      expect(response).to have_http_status(:not_found)
+      json = JSON.parse(response.body)
+      expect(json["error"]).to eq("Not found")
+    end
+  end
+end

spec/requests/software_builds_controller_spec.rb

@@ -0,0 +1,29 @@
+require "rails_helper"
+
+RSpec.describe "GET /api/softwares/:name/builds", type: :request do
+  describe "GET /api/softwares/:name/builds" do
+    let!(:software) { create(:software, name: "test-game", platform: "love") }
+    let!(:release) { create(:release, software: software, version: "2.0.0") }
+
+    before do
+      WarpEngine::ReleaseAsset.create!(release: release, kind: "html", path: "/test/html")
+    end
+
+    it "returns per-software build info" do
+      get "/api/softwares/test-game/builds"
+
+      expect(response).to have_http_status(:ok)
+      json = JSON.parse(response.body)
+      expect(json["platform"]).to eq("love")
+      expect(json["expected"]).to include("html", "win_x64")
+      expect(json["releases"]["2.0.0"]["actual"]).to include("html")
+      expect(json["releases"]["2.0.0"]["missing"]).to include("win_x64")
+    end
+
+    it "returns 404 for unknown software" do
+      get "/api/softwares/nonexistent/builds"
+
+      expect(response).to have_http_status(:not_found)
+    end
+  end
+end

spec/requests/software_controller_spec.rb

@@ -0,0 +1,42 @@
+require "rails_helper"
+
+RSpec.describe "GET /api/software", type: :request do
+  describe "GET /api/software" do
+    it "returns all software with releases" do
+      create(:software, name: "test-game", title: "Test Game")
+
+      get "/api/software"
+
+      expect(response).to have_http_status(:ok)
+      json = JSON.parse(response.body)
+      expect(json["softwares"]).to be_an(Array)
+      expect(json["softwares"].length).to eq(1)
+    end
+
+    it "returns per-release and total download counts" do
+      software = create(:software)
+      release  = create(:release, software: software)
+      other    = create(:release, software: software)
+      create_list(:download, 3, release: release)
+      create(:download, release: other)
+
+      get "/api/software"
+
+      json = JSON.parse(response.body)
+      sw = json["softwares"].first
+      expect(sw["totalDownloads"]).to eq(4)
+      counts = sw["releases"].to_h { |r| [ r["id"], r["downloadCount"] ] }
+      expect(counts[release.id]).to eq(3)
+      expect(counts[other.id]).to eq(1)
+    end
+
+    it "excludes soft-deleted software" do
+      create(:software, deleted_at: Time.current)
+
+      get "/api/software"
+
+      json = JSON.parse(response.body)
+      expect(json["softwares"]).to be_empty
+    end
+  end
+end

spec/requests/update_controller_spec.rb

@@ -0,0 +1,46 @@
+require "rails_helper"
+
+RSpec.describe "GET /update", type: :request do
+  before do
+    allow(WarpEngine.config).to receive(:update_secret).and_return("s3cret")
+  end
+
+  it "rejects requests without a secret" do
+    get "/update", params: { platform: "tic80", name: "game", version: "1.0" }
+
+    expect(response).to have_http_status(:unauthorized)
+  end
+
+  it "rejects requests with a wrong secret" do
+    get "/update", params: { secret: "wrong", platform: "tic80", name: "game", version: "1.0" }
+
+    expect(response).to have_http_status(:unauthorized)
+  end
+
+  it "rejects every request when no secret is configured" do
+    allow(WarpEngine.config).to receive(:update_secret).and_return(nil)
+
+    get "/update", params: { secret: "", platform: "tic80", name: "game", version: "1.0" }
+
+    expect(response).to have_http_status(:unauthorized)
+  end
+
+  it "requires a version" do
+    get "/update", headers: { "X-Update-Secret" => "s3cret" }, params: { platform: "tic80", name: "game" }
+
+    expect(response).to have_http_status(:bad_request)
+    expect(response.body).to eq("Version not provided")
+  end
+
+  it "runs the updater with a valid secret" do
+    updater = instance_double(WarpEngine::SoftwareUpdater::Tic80Service)
+    allow(WarpEngine::SoftwareUpdater::Tic80Service).to receive(:new).and_return(updater)
+    expect(updater).to receive(:update).with("game", "1.0")
+
+    get "/update", headers: { "X-Update-Secret" => "s3cret" },
+                   params: { platform: "tic80", name: "game", version: "1.0" }
+
+    expect(response).to have_http_status(:ok)
+    expect(response.body).to eq("Updated")
+  end
+end

warp_engine.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rails", ">= 8.0"
   spec.add_dependency "blueprinter"
   spec.add_dependency "rubyzip", "~> 2.3"
+  spec.add_dependency "apipie-rails"
 end