dragonruby-rack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4eb445a0e6d8d213740fb5604c1dbd3794d92732a540d5157837fee9f22a4314
+  data.tar.gz: 4957d3f7413f65f43ee11f236cb8bfe892a4b7aac958493837eb8985b79219c0
+SHA512:
+  metadata.gz: fd9e975ed8ef7a749e9f67a8f14db04b4c8fe7ff621097977471197a40fc848d5317ee76656ad677f3f7c3362fd31975529189d4ad410fc76211b2d9e63d4534
+  data.tar.gz: b0763b9f6ac8f1ffe3bc16d015a8a113dcb1160d88df5d62903351d05cd3faa5ab9fb77492ba5298ce1fc233bddc7fb69ac5ad75352030a1af281ed9537a85c9

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 — 2026-08-02
+
+Extracted from https://stammer.dev website, where it had been serving
+[Underwater](https://github.com/rstammer/underwater) inside of a classical Rails app.
+
+- `DragonRuby::Rack::Game` — mountable endpoint: cross-origin isolation headers
+  on the document and every subresource, `<base>` injection so relative assets
+  resolve under any mount path, `content-length` corrected for the longer body.
+- A bare mount path (empty `PATH_INFO`, which is what `Rack::URLMap` hands a
+  mounted app) now serves the index. It used to 404 in plain Rack while working
+  under Rails, which normalizes the path first.
+- `DragonRuby::Rack::Bundle.install` and `rake dragonruby:install` — replace the
+  bundle directory from a published zip, refusing any destination that is not
+  empty and holds no `index.html`, and verifying the result has an `index.html`
+  and a `.wasm`.
+- `rails g dragonruby:mount` — writes the mount into `config/routes.rb`.
+- Railtie loads only when Rails is present; Rails is not a dependency.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Stammer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# dragonruby-rack
+
+Serve a [DragonRuby GTK](https://dragonruby.org) HTML5 export from a Rack or
+Rails app, on your own domain, without an iframe and without itch.io.
+
+```ruby
+# Gemfile
+gem "dragonruby-rack"
+
+# config/routes.rb
+mount DragonRuby::Rack::Game.new(Rails.root.join("games/underwater")) => "/underwater"
+```
+
+That is the whole thing. The game is then at `/underwater/`.
+
+Built for and running on [stammer.dev/underwater](https://stammer.dev/underwater/).
+
+## Why this is not just a static directory
+
+DragonRuby's WASM runtime allocates a `SharedArrayBuffer`, and browsers hand
+that out only to a **cross-origin isolated** document — one served with both
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Rails' static file server runs *before* the router and cannot set headers per
+path, so a bundle dropped into `public/` is served without them and the game
+never boots. Hence: keep the bundle outside `public/`, serve it through this
+endpoint, which sets the headers on the document **and on every subresource** —
+`require-corp` applies to the `.wasm` too.
+
+The second thing it does is less obvious. The export links its assets
+relatively (`game.css`, `gamedata/…`), which under a mount only resolve if the
+document URL ends in a slash — and nothing can guarantee that, since Rails
+normalizes the path away before the endpoint sees it and a redirect onto the
+slash would be a loop. So the endpoint injects a `<base href="/underwater/">`
+into the served HTML, and the assets resolve either way.
+
+## Without Rails
+
+It is a plain Rack app; Rails is not a dependency.
+
+```ruby
+# config.ru
+require "dragonruby-rack"
+run DragonRuby::Rack::Game.new("builds/underwater-html5")
+```
+
+or mounted:
+
+```ruby
+require "dragonruby-rack"
+
+app = Rack::Builder.new do
+  map("/underwater") { run DragonRuby::Rack::Game.new("builds/underwater-html5") }
+end
+```
+
+## Getting a bundle in
+
+Export the game (`dragonruby-publish --platforms=html5 --package …`) and unpack
+the zip where the mount points:
+
+```sh
+rake dragonruby:install[../underwater/builds/underwater-html5.zip,underwater]
+```
+
+The task **replaces** the directory rather than unpacking over it — a file that
+existed in the old version and not in the new one would otherwise stay behind
+and be served for good. Because that is a delete, it refuses any destination
+that is not empty and holds no `index.html`, and it checks afterwards that what
+came out has an `index.html` and a `.wasm` in it (a desktop export unzips
+perfectly well and then serves nothing). `FORCE=1` overrides the refusal.
+
+`config.dragonruby.games_root` sets where bundles live; the default is `games`.
+
+## Generator
+
+```sh
+rails g dragonruby:mount underwater
+```
+
+Creates `games/underwater/` and writes the mount into `config/routes.rb`.
+`--path=` and `--at=` override the directory and the URL. Running it twice does
+not mount the path twice.
+
+## What this gem is not
+
+It does **not** contain DragonRuby, and it does not build your game. DragonRuby
+is commercial software with its own licence; you need your own copy to produce
+the export this serves. This gem only takes the finished directory and puts it
+on the web correctly.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+## Licence
+
+MIT. See LICENSE.txt.

data/lib/dragonruby/rack/bundle.rb

@@ -0,0 +1,86 @@
+require "fileutils"
+
+module DragonRuby
+  module Rack
+    # Puts a published HTML5 export where the app can serve it.
+    #
+    # This is the step that used to be three shell lines, one of which was
+    # `rm -rf` against a path typed by hand. Replacing the directory rather than
+    # unpacking over it is not optional — a file deleted between two versions
+    # would otherwise stay behind and be served forever. So the delete has to
+    # happen, and the only useful thing to do about it is to refuse to delete
+    # anything that is not already a bundle.
+    module Bundle
+      class Error < StandardError; end
+
+      # What every DragonRuby HTML5 export has in it, and what a directory must
+      # therefore look like before this is willing to erase it.
+      MARKER = "index.html"
+
+      class << self
+        # Unpacks +zip+ into +into+, replacing whatever bundle is there.
+        #
+        # Refuses when +into+ exists but holds no index.html: that is either the
+        # wrong path or something that is not a bundle, and both are worth an
+        # error rather than a deletion. Pass force: true to say you meant it.
+        def install(zip, into, force: false)
+          zip = File.expand_path(zip.to_s)
+          into = File.expand_path(into.to_s)
+
+          raise Error, "no such zip: #{zip}" unless File.file?(zip)
+
+          guard_destination(into, force: force)
+
+          FileUtils.rm_rf(into)
+          FileUtils.mkdir_p(into)
+          unzip(zip, into)
+          verify(into)
+
+          into
+        end
+
+        private
+
+        def guard_destination(into, force:)
+          return if force
+          return unless File.exist?(into)
+
+          unless File.directory?(into)
+            raise Error, "#{into} exists and is not a directory"
+          end
+
+          return if File.exist?(File.join(into, MARKER))
+          return if Dir.children(into).empty?
+
+          raise Error, <<~MESSAGE.strip
+            #{into} is not empty and holds no #{MARKER}, so it does not look like
+            a game bundle. Refusing to delete it. Pass force: true (or
+            FORCE=1 to the rake task) if this really is the right directory.
+          MESSAGE
+        end
+
+        # Shelling out to unzip keeps rubyzip out of the dependency list for a
+        # step that runs once per release on a developer machine. If it is ever
+        # needed somewhere without unzip, that is the moment to reconsider —
+        # not before.
+        def unzip(zip, into)
+          ok = system("unzip", "-q", zip, "-d", into)
+          raise Error, "unzip failed for #{zip}" unless ok
+        end
+
+        # A zip that unpacked without error can still be the wrong zip. Both
+        # halves of a DragonRuby export have to be there or the game shows a
+        # blank page in production and nowhere else.
+        def verify(into)
+          unless File.exist?(File.join(into, MARKER))
+            raise Error, "no #{MARKER} in the unpacked bundle at #{into}"
+          end
+
+          return if Dir.glob(File.join(into, "**", "*.wasm")).any?
+
+          raise Error, "no .wasm in the unpacked bundle at #{into} — is this an HTML5 export?"
+        end
+      end
+    end
+  end
+end

data/lib/dragonruby/rack/game.rb

@@ -0,0 +1,94 @@
+require "rack"
+
+module DragonRuby
+  module Rack
+    # Serves a DragonRuby GTK HTML5 export as a self-contained, cross-origin
+    # isolated static bundle, mountable at any path in a Rack or Rails app:
+    #
+    #   mount DragonRuby::Rack::Game.new("games/underwater") => "/underwater"
+    #
+    # Why this exists: DragonRuby's WASM runtime uses SharedArrayBuffer, which
+    # the browser only hands out to a *cross-origin isolated* document — one
+    # served with both COOP and COEP. Rails' public/ file server
+    # (ActionDispatch::Static) runs before the router and cannot set these
+    # headers per path, which is why the bundle belongs outside public/ and is
+    # served exclusively through this endpoint.
+    #
+    # Everything in here refers to the real Rack as ::Rack. Inside
+    # DragonRuby::Rack, a bare `Rack::Static` resolves to
+    # DragonRuby::Rack::Static and raises NameError — the one price of naming
+    # the module after the gem.
+    class Game
+      # The two headers that put the document into cross-origin isolation.
+      # Without them the WASM runtime cannot allocate its SharedArrayBuffer and
+      # refuses to boot. Same-origin subresources (all of the bundle) satisfy
+      # require-corp without a per-file Cross-Origin-Resource-Policy header.
+      ISOLATION_HEADERS = {
+        "cross-origin-opener-policy" => "same-origin",
+        "cross-origin-embedder-policy" => "require-corp",
+      }.freeze
+
+      NOT_FOUND = ->(_env) { [404, { "content-type" => "text/plain" }, ["Not found"]] }
+
+      attr_reader :root
+
+      # A missing directory is deliberately not an error. Routes are drawn at
+      # boot, and a fresh clone has no build in it yet; raising here would stop
+      # the whole app from starting over a game that has not been exported.
+      # Requests simply 404 until the bundle is there.
+      def initialize(root, index: "index.html")
+        @root = root.to_s
+        @static = ::Rack::Static.new(
+          NOT_FOUND,
+          root: @root,
+          urls: [""],   # serve every path under this mount from the bundle
+          index: index, # directory requests ("/") resolve to index.html
+        )
+      end
+
+      def call(env)
+        env = normalize_root(env)
+        status, headers, body = @static.call(env)
+        ISOLATION_HEADERS.each { |key, value| headers[key] = value }
+        body = rebase_html(body, headers, env) if html?(headers)
+        [status, headers, body]
+      end
+
+      private
+
+      # A request for the mount point itself arrives with an empty PATH_INFO
+      # under Rack::URLMap, and Rack::Static only resolves its index for a path
+      # ending in "/". So a plain Rack mount answered the bare URL with 404
+      # while the same mount under Rails worked, because Rails normalizes the
+      # path to "/" before the endpoint sees it. Same request, same app, two
+      # answers — worth removing rather than documenting.
+      def normalize_root(env)
+        return env unless env["PATH_INFO"].to_s.empty?
+
+        env.merge("PATH_INFO" => "/")
+      end
+
+      def html?(headers)
+        headers["content-type"].to_s.include?("text/html")
+      end
+
+      # The bundle's index.html links its assets relatively (game.css, the
+      # loader, gamedata/). Mounted under a subpath, those only resolve if the
+      # document URL ends in a slash — which cannot be forced, since Rails
+      # normalizes the path away before the mount sees it, and a redirect onto
+      # the slash would be a loop. Injecting a <base> pointing at the mount root
+      # makes every relative URL resolve either way.
+      def rebase_html(body, headers, env)
+        html = +""
+        body.each { |chunk| html << chunk }
+        body.close if body.respond_to?(:close)
+        return [html] if html.empty? # HEAD carries no body — leave headers as-is
+
+        base = "#{env['SCRIPT_NAME']}/"
+        html = html.sub(/<head>/i, %(<head><base href="#{base}">))
+        headers["content-length"] = html.bytesize.to_s
+        [html]
+      end
+    end
+  end
+end

data/lib/dragonruby/rack/railtie.rb

@@ -0,0 +1,21 @@
+require "rails/railtie"
+
+module DragonRuby
+  module Rack
+    # Everything Rails-specific in the gem is here and in lib/generators. The
+    # railtie is loaded only when Rails is already in the process (see
+    # lib/dragonruby/rack.rb), so requiring this file is what makes the gem a
+    # Rails gem — nothing else in it knows about Rails at all.
+    class Railtie < ::Rails::Railtie
+      # config.dragonruby.games_root — where bundles live, relative to the app
+      # root. Only the rake task and the generator read it; the Rack app itself
+      # takes a plain path and has no configuration.
+      config.dragonruby = ActiveSupport::OrderedOptions.new
+      config.dragonruby.games_root = "games"
+
+      rake_tasks do
+        load File.expand_path("../../tasks/dragonruby.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/dragonruby/rack/version.rb

@@ -0,0 +1,5 @@
+module DragonRuby
+  module Rack
+    VERSION = "0.1.0"
+  end
+end

data/lib/dragonruby/rack.rb

@@ -0,0 +1,13 @@
+require_relative "rack/version"
+require_relative "rack/game"
+require_relative "rack/bundle"
+
+# The Rails half is optional on purpose: the gem is a Rack gem, and a Sinatra or
+# plain-Rack user should not pull a framework in behind it. Loading the railtie
+# only when Rails is already present keeps that promise.
+require_relative "rack/railtie" if defined?(::Rails::Railtie)
+
+module DragonRuby
+  module Rack
+  end
+end

data/lib/dragonruby-rack.rb

@@ -0,0 +1,3 @@
+# The gem is called dragonruby-rack, so `gem "dragonruby-rack"` in a Gemfile
+# requires this path by default. The code lives under lib/dragonruby/rack.
+require_relative "dragonruby/rack"

data/lib/generators/dragonruby/mount/mount_generator.rb

@@ -0,0 +1,82 @@
+require "rails/generators"
+
+module DragonRuby
+  module Generators
+    # rails g dragonruby:mount underwater
+    #
+    # Writes the one line that is easy to get subtly wrong: the mount has to
+    # point at a directory outside public/, and the game is linked with a
+    # trailing slash.
+    #
+    # The namespace is declared rather than derived. Rails would camelize
+    # "dragonruby" to Dragonruby and look for that constant; the gem's module is
+    # DragonRuby, so the two are spelled out separately here.
+    class MountGenerator < ::Rails::Generators::Base
+      namespace "dragonruby:mount"
+
+      argument :name, type: :string,
+               desc: "Name of the game — becomes both the directory and the URL path"
+
+      class_option :path, type: :string, default: nil,
+                   desc: "Directory holding the bundle (default: <games_root>/<name>)"
+      class_option :at, type: :string, default: nil,
+                   desc: "URL path to mount at (default: /<name>)"
+
+      def create_bundle_directory
+        empty_directory bundle_path
+        create_file File.join(bundle_path, ".keep"), "" unless File.exist?(File.join(destination_root, bundle_path, ".keep"))
+      end
+
+      def add_the_mount
+        routes = File.join(destination_root, "config/routes.rb")
+        unless File.exist?(routes)
+          say_status :skip, "config/routes.rb not found — add this yourself:\n#{mount_line}", :yellow
+          return
+        end
+
+        if File.read(routes).include?(%("#{url_path}"))
+          say_status :identical, "#{url_path} is already mounted in config/routes.rb", :blue
+          return
+        end
+
+        inject_into_file "config/routes.rb", comment + mount_line + "\n",
+                         after: /Rails\.application\.routes\.draw do\n/
+      end
+
+      def tell_them_what_is_missing
+        say_status :next, "put an HTML5 export into #{bundle_path}, e.g.:", :green
+        say "         rake dragonruby:install[path/to/#{name}-html5.zip,#{name}]"
+        say_status :link, "then the game is at #{url_path}/ (the trailing slash matters in links)", :green
+      end
+
+      private
+
+      def bundle_path
+        options[:path] || File.join(games_root, name)
+      end
+
+      def games_root
+        ::Rails.application.config.dragonruby.games_root
+      rescue StandardError
+        "games"
+      end
+
+      def url_path
+        options[:at] || "/#{name}"
+      end
+
+      def mount_line
+        %(  mount DragonRuby::Rack::Game.new(Rails.root.join("#{bundle_path}")) => "#{url_path}"\n)
+      end
+
+      def comment
+        <<~RUBY
+            # #{name} — a DragonRuby HTML5 export, served cross-origin isolated so its
+            # WASM runtime can use SharedArrayBuffer. The bundle lives outside public/
+            # on purpose: Rails' static file server runs before the router and would
+            # serve it without those headers. Link to it as #{url_path}/
+        RUBY
+      end
+    end
+  end
+end

data/lib/tasks/dragonruby.rake

@@ -0,0 +1,20 @@
+require "dragonruby/rack/bundle"
+
+namespace :dragonruby do
+  desc "Install a published HTML5 export: rake dragonruby:install[path/to/game-html5.zip,underwater]"
+  task :install, [:zip, :name] => :environment do |_task, args|
+    zip = args[:zip] or abort "usage: rake dragonruby:install[path/to/game-html5.zip,name]"
+    name = args[:name] or abort "usage: rake dragonruby:install[path/to/game-html5.zip,name]"
+
+    games_root = Rails.application.config.dragonruby.games_root
+    into = Rails.root.join(games_root, name)
+
+    path = DragonRuby::Rack::Bundle.install(zip, into, force: ENV["FORCE"] == "1")
+    size = Dir.glob(File.join(path, "**", "*")).sum { |f| File.file?(f) ? File.size(f) : 0 }
+
+    puts "Installed #{File.basename(zip)} into #{into} (#{(size / 1_048_576.0).round(1)} MB)"
+    puts "Mount it with: mount DragonRuby::Rack::Game.new(Rails.root.join(\"#{games_root}/#{name}\")) => \"/#{name}\""
+  rescue DragonRuby::Rack::Bundle::Error => e
+    abort "dragonruby:install — #{e.message}"
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: dragonruby-rack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robin Stammer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: |-
+  A mountable Rack endpoint that serves a DragonRuby GTK HTML5 export with the
+  cross-origin isolation headers its WASM runtime needs, and rebases the
+  bundle's relative asset links so it works under any mount path. Ships an
+  optional Rails generator and rake task; the Rack app itself needs no Rails.
+email:
+- robin.stammer@posteo.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/dragonruby-rack.rb
+- lib/dragonruby/rack.rb
+- lib/dragonruby/rack/bundle.rb
+- lib/dragonruby/rack/game.rb
+- lib/dragonruby/rack/railtie.rb
+- lib/dragonruby/rack/version.rb
+- lib/generators/dragonruby/mount/mount_generator.rb
+- lib/tasks/dragonruby.rake
+homepage: https://github.com/rstammer/dragonruby-rack
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rstammer/dragonruby-rack
+  changelog_uri: https://github.com/rstammer/dragonruby-rack/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Serve a DragonRuby GTK HTML5 export from a Rack or Rails app
+test_files: []