ruby_wasm_ic_rack 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5723c6f1d158956c8dede6d1ddc98b5b5f048ec51931df4d1eadd8531d59aea4
+  data.tar.gz: '0119fd70d66b909e5185bd0b17f6570b60550ff99de4d8338a496382882825bc'
+SHA512:
+  metadata.gz: d02430595e7709b5d26efedab2b78f0693e9c6788479942eafd53ef2d2ee1215f86cd50893f9e0a0582dbbe5dbc5f9e4f945d32113da497f604862fd212a94f7
+  data.tar.gz: 4528b16357279759bb9195f15dc668923e8826c2edadc68b9cbe198eda50ddea7c49b437f9e13243ed3e5cd76ef219678ff7d1d3cd149447c555a59e92f48911

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the ruby_wasm_builder authors
+
+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,115 @@
+# ruby_wasm_ic_rack
+
+Serve a [Rack](https://github.com/rack/rack) app from a Ruby canister on the
+Internet Computer, through the IC HTTP gateway. For canisters packed by
+[ruby_wasm_builder](https://gitlab.com/phrug/ruby_wasm_builder) from 0.7.0.
+
+Pure Ruby, no dependencies. It works the same on the `minimal` and `full`
+Builds: it names no standard library, no C extension and no `Encoding`
+constant.
+
+## Carrying it
+
+A canister has no `bundle install`. Carry the gem's files in your Application,
+as you carry Rack:
+
+```bash
+gem fetch ruby_wasm_ic_rack && gem unpack ruby_wasm_ic_rack-*.gem
+cp -r ruby_wasm_ic_rack-*/lib my_app/vendor/ruby_wasm_ic_rack
+```
+
+```ruby
+# app.rb
+$LOAD_PATH.unshift(File.join(__dir__, "vendor/ruby_wasm_ic_rack"))
+require "ruby_wasm_ic_rack"
+```
+
+To move to a newer version, unpack it and copy its `lib/` again.
+
+## Declaring and serving the gateway's methods
+
+From ruby_wasm_builder 0.8.0, one word in `ic-interface.rb` declares the
+gateway's types and both methods:
+
+```ruby
+# ic-interface.rb
+http_gateway
+```
+
+On 0.7.0, write them out (this is what the word declares):
+
+```ruby
+type :HeaderField, Tuple[Text, Text]
+type :HttpRequest, record(method: Text, url: Text, headers: Vec[:HeaderField], body: Blob,
+                          certificate_version: Opt[Nat16])
+type :HttpUpdateRequest, record(method: Text, url: Text, headers: Vec[:HeaderField], body: Blob)
+type :HttpResponse, record(status_code: Nat16, headers: Vec[:HeaderField], body: Blob, upgrade: Opt[Bool])
+
+query  :http_request,        takes: [:HttpRequest],       returns: :HttpResponse
+update :http_request_update, takes: [:HttpUpdateRequest], returns: :HttpResponse
+```
+
+Then hand both to your app:
+
+```ruby
+# app.rb
+APP = ->(env) { [200, { "content-type" => "text/plain" }, ["hello from #{env['PATH_INFO']}"]] }
+
+def http_request(req) = RubyWasmIcRack.query(APP, req)
+def http_request_update(req) = RubyWasmIcRack.update(APP, req)
+```
+
+## What it does
+
+- **The env:** `REQUEST_METHOD`, `PATH_INFO`, `QUERY_STRING`, `SERVER_NAME`
+  (from `host`), `SERVER_PORT` 443, `rack.url_scheme` `https`, every header as
+  `HTTP_*` (`CONTENT_TYPE` and `CONTENT_LENGTH` as Rack names them), a repeated
+  header joined with `, `, and `rack.input` over the body.
+- **The response:** a header whose value is an Array, or lines joined by
+  `"\n"` (Rack 3), goes out as one header each, so two `set-cookie` headers
+  arrive as two. The body is joined and closed.
+- **Upgrades.** The gateway calls `http_request` as a query, and a query keeps
+  nothing it writes. So `RubyWasmIcRack.query` answers only `GET`, `HEAD` and `OPTIONS`
+  and asks the gateway to upgrade everything else, which then calls
+  `http_request_update` through consensus. A `GET` that writes says so with the
+  response header `x-ic-upgrade` (any value); the query upgrades it, and the
+  header is never sent on.
+- **`rack.input`** is a small reader of its own (`read`, `gets`, `each`,
+  `rewind`). For a `StringIO`, as Rack's own servers give, redefine
+  `RubyWasmIcRack.input`:
+
+  ```ruby
+  module RubyWasmIcRack
+    def self.input(bytes) = StringIO.new(bytes.b)
+  end
+  ```
+
+## On the `minimal` Build
+
+Rack and Roda need four libraries `minimal` lacks: `Encoding::UTF_8` and its
+two siblings, `date` (only because `time` requires it), `strscan` and
+`stringio`. The [`ic_minimal`](../ic_minimal) gem carries pure-Ruby stand-ins
+for them, for a `minimal` canister only. `ruby_wasm_ic_rack` itself needs none of them.
+
+Carry only the files of Rack your routes load, and check every carried file's
+magic comment: `minimal` knows only `utf-8`, `us-ascii` and `ascii-8bit` by
+those names, and Rack 3.1's `rack/utils.rb` says `# encoding: binary`, which
+traps the install. Change that word to `ascii-8bit`.
+
+## Not yet
+
+- **Certified responses.** Until the canister certifies its replies, the
+  gateway refuses a plain query's reply on the certified domain
+  (`<id>.icp0.io`) and serves it on `<id>.raw.icp0.io`. An upgraded request is
+  served on either. So a public page is served raw, or by upgrading every
+  `GET` (one update per page view).
+- File uploads (Tempfile) and streaming responses.
+
+## Development
+
+The gem lives in the ruby_wasm_builder repository, `gems/ruby_wasm_ic_rack/`. Its specs
+are in that repository's `spec/gems/`, and run with the builder's suite
+(`bundle exec rspec`), including the 0.7.0 `rack_adapter` and `roda_on_minimal`
+Scripts played with this gem's files in place of the Challenges' own copies.
+
+MIT licensed.

data/lib/ruby_wasm_ic_rack/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyWasmIcRack
+  VERSION = "0.1.1"
+end

data/lib/ruby_wasm_ic_rack.rb

@@ -0,0 +1,120 @@
+# ruby_wasm_ic_rack: serves a Rack app (anything answering call(env) with
+# [status, headers, body]) from the IC HTTP gateway's two methods, in a Ruby
+# canister packed by ruby_wasm_builder. Pure Ruby with no dependency, the same
+# on the `minimal` and `full` Builds: it names no standard library, no C
+# extension and no Encoding constant. rack.input is a small reader of its own
+# unless the Application redefines RubyWasmIcRack.input (a StringIO, say).
+#
+# Taken from the builder's 0.7.0 Challenges (rack_adapter, roda_on_minimal),
+# which keep their own copies; this gem moves on its own versions.
+#
+# A query can't keep a write, so http_request answers only the safe methods
+# (GET, HEAD, OPTIONS) and asks the gateway to upgrade everything else to
+# http_request_update. An app whose GET writes says so with the response
+# header `x-ic-upgrade`, and the query upgrades that too; the header is never
+# sent on.
+require_relative "ruby_wasm_ic_rack/version"
+
+module RubyWasmIcRack
+  SAFE = %w[GET HEAD OPTIONS].freeze
+  UPGRADE = "x-ic-upgrade"
+
+  # rack.input over the body's bytes: what Rack 3 asks of an input stream.
+  class Input
+    def initialize(bytes)
+      @bytes = bytes.b
+      @pos = 0
+    end
+
+    def read(length = nil, buffer = nil)
+      rest = @bytes.byteslice(@pos, @bytes.bytesize - @pos) || "".b
+      chunk = length ? rest.byteslice(0, length) : rest
+      @pos += chunk.bytesize
+      return nil if length && length.positive? && chunk.empty?
+
+      buffer ? buffer.replace(chunk) : chunk
+    end
+
+    def gets
+      return nil if @pos >= @bytes.bytesize
+
+      stop = @bytes.index("\n", @pos)
+      line = @bytes.byteslice(@pos, (stop ? stop + 1 : @bytes.bytesize) - @pos)
+      @pos += line.bytesize
+      line
+    end
+
+    def each
+      while (line = gets)
+        yield line
+      end
+    end
+
+    def rewind = @pos = 0
+    def close = nil
+  end
+
+  module_function
+
+  # rack.input over the body. An Application may redefine it (roda_on_minimal
+  # gives a StringIO).
+  def input(bytes) = Input.new(bytes)
+
+  def env(req)
+    path, query = req[:url].split("?", 2)
+    host = header(req, "host").to_s
+    env = {
+      "REQUEST_METHOD" => req[:method],
+      "SCRIPT_NAME" => "",
+      "PATH_INFO" => path.to_s.empty? ? "/" : path,
+      "QUERY_STRING" => query.to_s,
+      "SERVER_NAME" => host.split(":").first.to_s,
+      "SERVER_PORT" => "443",
+      "SERVER_PROTOCOL" => "HTTP/1.1",
+      "rack.url_scheme" => "https",
+      "rack.input" => input(req[:body]),
+      "rack.errors" => $stderr
+    }
+    req[:headers].each do |name, value|
+      key = name.upcase.tr("-", "_")
+      key = "HTTP_#{key}" unless %w[CONTENT_TYPE CONTENT_LENGTH].include?(key)
+      env[key] = env.key?(key) ? "#{env[key]}, #{value}" : value
+    end
+    env
+  end
+
+  def header(req, name) = req[:headers].find { |n, _| n.downcase == name }&.last
+
+  # The gateway's response record from a Rack response. A header's value may
+  # be an Array, or lines joined by "\n" (Rack 3): one header each.
+  def response(status, headers, body)
+    pairs = headers.flat_map do |name, value|
+      Array(value).flat_map { |v| v.to_s.split("\n") }.map { |v| [name.to_s.downcase, v] }
+    end
+    bytes = +"".b
+    body.each { |part| bytes << part.b }
+    { status_code: Integer(status), headers: pairs, body: bytes, upgrade: nil }
+  ensure
+    body.close if body.respond_to?(:close)
+  end
+
+  def upgrade = { status_code: 200, headers: [], body: "".b, upgrade: true }
+
+  # http_request: the query.
+  def query(app, req)
+    return upgrade unless SAFE.include?(req[:method])
+
+    status, headers, body = app.call(env(req))
+    if headers.keys.any? { |k| k.to_s.downcase == UPGRADE }
+      body.close if body.respond_to?(:close)
+      return upgrade
+    end
+    response(status, headers, body)
+  end
+
+  # http_request_update: the update, after an upgrade.
+  def update(app, req)
+    status, headers, body = app.call(env(req))
+    response(status, headers.reject { |k, _| k.to_s.downcase == UPGRADE }, body)
+  end
+end

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: ruby_wasm_ic_rack
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- graial
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Use this gem to run rack and roda on the ruby.wasm build for Internet
+  Computer.
+email:
+- graial@paglalayag.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ruby_wasm_ic_rack.rb
+- lib/ruby_wasm_ic_rack/version.rb
+homepage: https://github.com/graial/ruby_wasm_ic_rack
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Run rack and roda on the ruby.wasm build for IC!
+test_files: []