edgeway 0.1.0 → 0.3.0

data/lib/edgeway/errors.rb

@@ -28,6 +28,17 @@ module Edgeway
   # ({"error":"invalid token"}) and the challenge no description.
   class InvalidToken < Unauthorized; end
 
+  # A request over a rate limit: 429 with a fixed body. retry_after is the
+  # seconds for a Retry-After header, 0 for none.
+  class TooManyRequests < Error
+    attr_reader :retry_after
+
+    def initialize(message = "rate limit exceeded", retry_after = 0)
+      super(message)
+      @retry_after = retry_after.is_a?(Integer) && Integer(retry_after) > 0 ? retry_after : 0
+    end
+  end
+
   # A record that doesn't exist: 404.
   class RecordNotFound < Error; end
 
@@ -41,6 +52,10 @@ module Edgeway
   # details only in the log.
   class InvalidHeader < Error; end
 
+  # render named a template that was not compiled from app/views: 500, with
+  # the name only in the log, since it is a bug in the app.
+  class MissingTemplate < Error; end
+
   # A failure in the database adapter: 500.
   class DatabaseError < Error; end
 
@@ -49,6 +64,34 @@ module Edgeway
   # the log only.
   class RecordNotUnique < DatabaseError; end
 
+  # A write the database refused for a NOT NULL constraint: 500, since it is a
+  # bug in the app. The message goes to the log only.
+  class NotNullViolation < DatabaseError; end
+
+  # A write the database refused for a FOREIGN KEY constraint: 500, since it is
+  # a bug in the app. The message goes to the log only.
+  class InvalidForeignKey < DatabaseError; end
+
+  # A write the database refused for a CHECK constraint: 500, since it is a bug
+  # in the app. The message goes to the log only.
+  class CheckViolation < DatabaseError; end
+
+  # A transient database failure or overload (a lost connection, a reset object...):
+  # 503 with "Retry-After: 1" and a fixed body. The message goes to the log
+  # only. Edgeway never retries it. A write that fails this way may still have
+  # been applied, so only an idempotent request is safe to retry.
+  class DatabaseUnavailable < DatabaseError; end
+
+  module HTTP
+    # An outgoing request that failed (a network error, a URL that is refused,
+    # a response over the size limit): 500. The message goes to the log only.
+    class Error < Edgeway::Error; end
+
+    # An outgoing request that did not finish within its timeout: 500. The
+    # message goes to the log only.
+    class Timeout < Error; end
+  end
+
   # A record that failed its validations: 422 with {"errors": [...]}.
   class RecordInvalid < Error
     attr_reader :errors

data/lib/edgeway/generators/app/templates/.github/workflows/ci.yml.tt

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    # The first run builds Spinel from source; later runs use mise-action's cache.
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      # The Ruby in .ruby-version.
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0
+        with:
+          bundler-cache: true
+      # Everything in mise.toml: the WASI SDK (bin/build needs it), Spinel,
+      # Node.js, and <%= PackageManager.name %>.
+      - name: Install the tools
+        uses: jdx/mise-action@9b200bcecbfd6303e69a4a261b2e09e3757440a7 # v5.2.0
+      # `edgeway test` runs the tests on the local D1 of wrangler.
+      - name: Install wrangler
+        run: <%= PackageManager.install %>
+      - name: Run the tests
+        run: bin/test
+      - name: Build
+        run: bin/build --release

data/lib/edgeway/generators/app/templates/.ruby-version.tt

@@ -0,0 +1 @@
+<%= RUBY_VERSION %>

data/lib/edgeway/generators/app/templates/README.md.tt

@@ -9,14 +9,20 @@ bin/setup                                     # mise, bundle, <%= PackageManager
 mise install                                  # Spinel and the WASI SDK (mise.toml)
 bundle install
 <%= PackageManager.install %>
-bundle exec edgeway build                     # build/app.wasm (or bin/build)
+bundle exec edgeway build                     # build/app.wasm (or bin/build); --incremental, for development
 <%= PackageManager.exec %> wrangler d1 migrations apply <%= @name %>-db --local
 <%= PackageManager.exec %> wrangler dev                              # http://localhost:8787/health
 bundle exec edgeway routes
 ```
 
+`bin/deploy` builds with `--release`: one unit, without Spinel's `--incremental` (cached C units, no inlining across units), for deploying.
+
+Files in `public/` are served by Cloudflare before the app, for every method on their path (see Edgeway's README, "Static assets").
+
 Without mise, set `SPINEL` to the Spinel compiler and `WASI_SDK` to the WASI SDK.
 
-Tests (`test/`) run with `bundle exec edgeway test [ARGS]`. Always use it rather than `spinel_test-unit` directly: it rewrites `tmp/test_app.rb` (git-ignored) from `app/` on every run, so new files are picked up. Each test gets a fresh in-memory SQLite database with `db/migrations/*.sql` applied, so running the tests requires SQLite (sqlite3): its development library has to be installed to link (`apt install libsqlite3-dev` on Debian/Ubuntu, `dnf install sqlite-devel` on Fedora; macOS has it).
+Tests (`test/`) run with `bin/test [FILE...]` (all of `test/` when no file is given; it runs `bundle exec edgeway test`). Always use it rather than `spinel_test-unit` directly: it rewrites `tmp/test_app.rb` (git-ignored) from `app/` on every run, so new files are picked up. The tests are compiled to wasm like the app and run by node on wrangler's local D1 (in memory, so `.wrangler/state` is not touched); each test gets an emptied database with `db/migrations/*.sql` applied. This needs the tools of `bin/setup` (Spinel, the WASI SDK, Node.js and wrangler).
+
+`.github/workflows/ci.yml` runs `bin/test` and `bin/build --release` on GitHub Actions for pushes to main and pull requests.
 
 Model tests inherit `Edgeway::UnitTest` (a database, no requests), request tests `Edgeway::IntegrationTest` (a `UnitTest` that also has `get`, `post`, `json`, `assert_response`).

data/lib/edgeway/generators/app/templates/app/views/layouts/application.html.erb

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>App</title>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/lib/edgeway/generators/app/templates/bin/build.tt

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Compiles the app to build/app.wasm, like `bundle exec edgeway build`.
-# Arguments go to it (--env ENV).
+# Arguments go to it (--env ENV, --release).
 set -euo pipefail
 cd "$(dirname "$0")/.."
 

data/lib/edgeway/generators/app/templates/bin/deploy.tt

@@ -5,6 +5,6 @@
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
-bin/build
+bin/build --release
 <%= PackageManager.exec %> wrangler d1 migrations apply <%= @name %>-db --remote
 <%= PackageManager.exec %> wrangler deploy "$@"

data/lib/edgeway/generators/app/templates/bin/setup.tt

@@ -3,8 +3,7 @@
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
-# Spinel and the WASI SDK, from mise.toml. `edgeway test` also links libsqlite3
-# (libsqlite3-dev on Debian/Ubuntu; part of macOS).
+# Spinel, the WASI SDK and Node.js, from mise.toml.
 if command -v mise >/dev/null 2>&1; then
   mise trust --quiet
   mise install
@@ -15,7 +14,7 @@ fi
 
 bundle install
 
-# wrangler, from package.json.
+# wrangler, from package.json (`edgeway test` runs the tests on its local D1).
 if ! command -v <%= PackageManager.name %> >/dev/null 2>&1; then
   echo "bin/setup: <%= PackageManager.name %> is not installed; install it to get wrangler." >&2
   exit 1

data/lib/edgeway/generators/app/templates/bin/test.tt

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Runs the tests, like `bundle exec edgeway test`.
+# Arguments go to it: test files to run (all of test/ when none are given).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+exec bundle exec edgeway test "$@"

data/lib/edgeway/generators/app/templates/config/cache.yml

@@ -0,0 +1,22 @@
+# The cache store of each environment (edgeway build --env ENV), Edgeway.cache
+# (see the README's "Caching"). Without this file, or a section for the
+# environment, the store is null: it keeps nothing, so Edgeway.cache.fetch
+# always runs its block.
+#
+#   store:       kv, memory or null. kv keeps entries in a Cloudflare KV
+#                namespace; memory keeps them for the one request only.
+#   binding:     the name of a [[kv_namespaces]] binding in wrangler.toml (kv).
+#   namespace:   a prefix for every key (optional).
+#   expires_in:  the seconds an entry lives when the call gives none (optional).
+#
+# `edgeway test` always uses a null store, whatever this file says.
+#   production:
+#     store: kv
+#     binding: CACHE
+#     namespace: myapp
+#     expires_in: 3600
+development:
+  store: null
+
+production:
+  store: null

data/lib/edgeway/generators/app/templates/config/database.yml

@@ -1,7 +1,29 @@
 # The database of each environment (edgeway build --env ENV), compiled into
 # the wasm. adapter: d1 uses the D1 binding named by binding:, which must
 # match a binding in wrangler.toml (wrangler.toml says which D1 database it
-# is); memory is for tests.
+# is); memory is a database that stores nothing (as the test: adapter it
+# means native tests on SQLite instead; see the README's "Testing an app").
+#
+# `edgeway test` runs the tests on a local D1 (in memory, like `wrangler dev`)
+# with adapter: d1, each test starting from the migrations (db/migrations and
+# db/<name>/migrations).
+#
+# Another database goes under databases:, which a model picks with
+# `self.database = :analytics` (see the README's "Multiple databases").
+# It has its own binding, migrations (db/<name>/migrations) and test database.
+#   production:
+#     adapter: d1
+#     binding: DB
+#     databases:
+#       analytics:
+#         binding: ANALYTICS
+#
+# For a database with read replication, `sessions: true` next to its binding
+# (see the README's "Read replication (Sessions)").
+#   production:
+#     adapter: d1
+#     binding: DB
+#     sessions: true
 development:
   adapter: d1
   binding: DB
@@ -11,4 +33,5 @@ production:
   binding: DB
 
 test:
-  adapter: memory
+  adapter: d1
+  binding: DB

data/lib/edgeway/generators/app/templates/mise.toml.tt

@@ -14,7 +14,7 @@ spinel = "https://github.com/y-yagi/mise-spinel"
 # master, so an install (and CI's cache of it) is the Spinel that was tested.
 # depends: the wasi-sdk is installed first, so the build also makes Spinel's
 # wasm32-wasi runtime (mise-spinel does when WASI_SDK, set below, is there).
-spinel = { version = "530ba2b17", depends = ["github:WebAssembly/wasi-sdk"] }
+spinel = { version = "ec0ad13e4", depends = ["github:WebAssembly/wasi-sdk"] }
 
 # wrangler (package.json) runs on Node.js.
 node = "lts"

data/lib/edgeway/generators/app/templates/public/.assetsignore

@@ -0,0 +1 @@
+# Files in public/ not to upload as static assets (.gitignore syntax).

data/lib/edgeway/generators/app/templates/wrangler.toml.tt

@@ -2,6 +2,11 @@ name = "<%= @name %>"
 main = "src/worker.js"
 compatibility_date = "2026-10-01"
 
+# Workers Logs records what the app logs (Edgeway.logger), one entry per line,
+# with its fields indexed (see the README's "Logging").
+[observability]
+enabled = true
+
 # CORS, for a frontend on another origin (see the README's "CORS"): the
 # origins allowed, comma-separated and compared exactly (no trailing slash).
 # Unset, CORS is off. CORS_HEADERS defaults to "Authorization, Content-Type",
@@ -11,6 +16,14 @@ compatibility_date = "2026-10-01"
 # [vars]
 # CORS_ORIGINS = "http://localhost:3000, https://app.example"
 
+# Files in public/ are served as is, without starting the app, so they are
+# always public: `before_action :authenticate!` never sees them. A file takes
+# its path from the app for every method (other than GET/HEAD it is 405):
+# public/index.html answers `/`, public/todos.html `/todos`. Anything else goes
+# to the app. For an SPA, see Edgeway's README, "Static assets".
+[assets]
+directory = "./public"
+
 # Simulated locally by `wrangler dev`. Create tables with
 # `<%= PackageManager.exec %> wrangler d1 migrations apply <%= @name %>-db --local`.
 # database_id is a placeholder (all zeros): that is enough for --local and
@@ -21,3 +34,29 @@ binding = "DB"
 database_name = "<%= @name %>-db"
 database_id = "00000000-0000-0000-0000-000000000000"
 migrations_dir = "db/migrations"
+
+# A second database (config/database.yml's databases:) is another binding,
+# with an id of its own: the same id is the same local database:
+# [[d1_databases]]
+# binding = "ANALYTICS"
+# database_name = "<%= @name %>-analytics"
+# database_id = "00000000-0000-0000-0000-000000000001"
+# migrations_dir = "db/analytics/migrations"
+
+# The cache (config/cache.yml, `store: kv`; see Edgeway's README, "Caching") keeps
+# its entries in a KV namespace. Simulated locally by `wrangler dev`. Before a
+# deploy, create the namespace (`<%= PackageManager.exec %> wrangler kv namespace create CACHE`)
+# and put the id it prints here.
+# [[kv_namespaces]]
+# binding = "CACHE"
+# id = "00000000000000000000000000000000"
+
+# Rate limiting (`rate_limit "API_LIMITER"` in a controller; see Edgeway's README,
+# "Rate limiting"). The period is 10 or 60 seconds; namespace_id is a positive
+# integer, as a string, that is unique in your account. `wrangler dev` enforces it.
+# [[ratelimits]]
+# name = "API_LIMITER"
+# namespace_id = "1001"
+#   [ratelimits.simple]
+#   limit = 100
+#   period = 60

data/lib/edgeway/http/auth/stub.rb

@@ -12,9 +12,7 @@ module Edgeway
       end
 
       def reject(token, message)
-        # .dup: since matz/spinel 44119ab30 (Strings shared by reference),
-        # Spinel refuses this String as it is, or emits C that doesn't compile.
-        @answers[token] = JSON.generate({ "error" => message.dup })
+        @answers[token] = JSON.generate({ "error" => message })
       end
 
       def unavailable(token, message)

data/lib/edgeway/http/client.rb

@@ -0,0 +1,80 @@
+module Edgeway
+  module HTTP
+    DEFAULT_TIMEOUT = 10
+    MAX_TIMEOUT = 300
+
+    class ClientResponse
+      attr_reader :status, :headers, :body
+
+      def initialize(status, headers, body)
+        @status = status
+        @headers = headers
+        @body = body
+      end
+
+      def success? = @status >= 200 && @status < 300
+
+      def json = JSON.parse(@body)
+    end
+
+    class Transport
+      def request(payload)
+        JSON.generate({ "error" => "no HTTP transport is set" })
+      end
+    end
+
+    @client = Transport.new
+
+    def self.client = @client
+
+    def self.client=(client)
+      @client = client
+    end
+
+    def self.get(url, headers: {}, timeout: DEFAULT_TIMEOUT)
+      send_request("GET", url, "", headers, timeout)
+    end
+
+    def self.delete(url, headers: {}, timeout: DEFAULT_TIMEOUT)
+      send_request("DELETE", url, "", headers, timeout)
+    end
+
+    def self.post(url, body: "", headers: {}, timeout: DEFAULT_TIMEOUT)
+      send_request("POST", url, body, headers, timeout)
+    end
+
+    def self.put(url, body: "", headers: {}, timeout: DEFAULT_TIMEOUT)
+      send_request("PUT", url, body, headers, timeout)
+    end
+
+    def self.patch(url, body: "", headers: {}, timeout: DEFAULT_TIMEOUT)
+      send_request("PATCH", url, body, headers, timeout)
+    end
+
+    def self.send_request(verb, url, body, headers, timeout)
+      timeout_ms = timeout_milliseconds(timeout)
+      payload = JSON.generate({
+        "method" => verb, "url" => url, "headers" => headers, "body" => body,
+        "timeout_ms" => timeout_ms
+      })
+      parse_answer(client.request(payload))
+    end
+
+    def self.timeout_milliseconds(timeout)
+      milliseconds = timeout > MAX_TIMEOUT ? 0 : (timeout * 1000).to_i
+      raise ArgumentError, "timeout must be 0.001 to #{MAX_TIMEOUT} seconds" if milliseconds < 1
+
+      milliseconds
+    end
+
+    def self.parse_answer(text)
+      answer = JSON.parse(text)
+      raise Timeout, answer["error"] if answer.key?("timeout")
+      raise Error, answer["error"] if answer.key?("error")
+
+      body = answer["body_base64"].unpack1("m0")
+      body.force_encoding("UTF-8")
+      ClientResponse.new(answer["status"], answer["headers"], body)
+    end
+  end
+end

data/lib/edgeway/http/request.rb

@@ -25,6 +25,11 @@ module Edgeway
         ENV["HTTP_" + name.upcase.gsub("-", "_")] || ""
       end
 
+      # The client address the platform reports, "" when unknown.
+      def remote_addr
+        ENV["REMOTE_ADDR"] || ""
+      end
+
       def json?
         @content_type.start_with?("application/json")
       end
@@ -63,12 +68,12 @@ module Edgeway
         add_body_params(decode_pairs(@body, "form body"))
       end
 
-      # decode_www_form never raises on bad bytes: it turns those that aren't
+      # URI.decode_www_form never raises on bad bytes: it turns those that aren't
       # UTF-8 (%ff) into U+FFFD. That is only right when the client sent a
       # U+FFFD itself, so otherwise one in the result is a BadRequest.
       def decode_pairs(text, what)
         raise BadRequest, "#{what} is not valid UTF-8" unless text.valid_encoding?
-        pairs = decode_www_form(text)
+        pairs = URI.decode_www_form(text)
         sent = text.include?(REPLACEMENT) || text.downcase.include?("%ef%bf%bd")
         unless sent
           pairs.each do |k, v|
@@ -78,26 +83,6 @@ module Edgeway
         pairs
       end
 
-      # URI.decode_www_form, written out so that Edgeway doesn't require
-      # "uri": a send with a computed name (Dispatcher) reaches uri's
-      # find_proxy(env = ENV), which Spinel refuses since its Strings are
-      # shared by reference (matz/spinel 44119ab30). Same answers as uri's,
-      # ArgumentError for a non-ASCII input included.
-      def decode_www_form(text)
-        raise ArgumentError, "the input of URI.decode_www_form must be ASCII only string" unless text.ascii_only?
-        return [] if text.empty?
-        pieces = text.split("&", -1)
-        pieces.pop if pieces.last.empty?
-        pieces.map do |piece|
-          key, _sep, val = piece.partition("=")
-          [unescape_www(key), unescape_www(val)]
-        end
-      end
-
-      def unescape_www(s)
-        s.b.gsub(/\+|%\h\h/) { |m| m == "+" ? " " : m[1, 2].hex.chr }.force_encoding(Encoding::UTF_8).scrub
-      end
-
       def read_json
         json = JSONBody.new(@body)
         @json_body = json.value

data/lib/edgeway/http/stub_transport.rb

@@ -0,0 +1,38 @@
+require_relative "client"
+
+module Edgeway
+  module HTTP
+    class UnstubbedRequest < Edgeway::Error; end
+
+    class StubTransport < Transport
+      attr_reader :requests
+
+      def initialize
+        @answers = {}
+        @requests = []
+      end
+
+      def stub(verb, url, status, body, headers)
+        lowered = {}
+        headers.each { |name, value| lowered[name.to_s.downcase] = value.to_s }
+        @answers[key(verb, url)] = JSON.generate({ "status" => status, "headers" => lowered, "body_base64" => [body].pack("m0") })
+      end
+
+      def stub_error(verb, url, message, timeout)
+        answer = { "error" => message }
+        answer["timeout"] = true if timeout
+        @answers[key(verb, url)] = JSON.generate(answer)
+      end
+
+      def request(payload)
+        sent = JSON.parse(payload)
+        @requests << sent
+        @answers[key(sent["method"], sent["url"])] || raise(UnstubbedRequest, "no stub for #{sent["method"]} #{sent["url"]} (add stub_http to the test)")
+      end
+
+      private
+
+      def key(verb, url) = "#{verb.to_s.upcase} #{url}"
+    end
+  end
+end

data/lib/edgeway/inflector.rb

@@ -1,8 +1,21 @@
 module Edgeway
   module Inflector
+    # "admin_posts" -> "AdminPosts"
+    def self.camelize(name) = name.split("_").map(&:capitalize).join
+
+    # "admin/posts" -> "Admin::PostsController"
+    def self.controller_class_name(path)
+      path.split("/").map { |part| camelize(part) }.join("::") + "Controller"
+    end
+
     def self.singularize(name)
       n = name.to_s
       return n[0...-3] + "y" if n.end_with?("ies")
+      if n.end_with?("es")
+        stem = n[0...-2]
+        return stem if sibilant?(stem)
+      end
+      return n if n.end_with?("ss") || n.end_with?("us")
       return n[0...-1] if n.end_with?("s")
       n
     end
@@ -10,7 +23,13 @@ module Edgeway
     def self.pluralize(name)
       n = name.to_s
       return n[0...-1] + "ies" if n.end_with?("y") && n.length > 1 && !"aeiou".include?(n[-2])
+      return n + "es" if n.end_with?("s") || n.end_with?("x") || n.end_with?("sh") || n.end_with?("ch")
       n + "s"
     end
+
+    def self.sibilant?(stem)
+      stem.end_with?("ss") || (stem.end_with?("us") && !stem.end_with?("ous")) || stem.end_with?("x") ||
+        stem.end_with?("sh") || stem.end_with?("ch")
+    end
   end
 end

data/lib/edgeway/logger.rb

@@ -1,12 +1,40 @@
 module Edgeway
-  # Writes to stderr; the runtime sends it to console.error.
   class Logger
-    def info(message)
-      STDERR.puts "[edgeway] #{message}"
+    LEVELS = ["debug", "info", "warn", "error"]
+
+    def initialize(output = STDERR)
+      @output = output
+    end
+
+    def debug(message, fields = {})
+      write("debug", message, fields)
+    end
+
+    def info(message, fields = {})
+      write("info", message, fields)
+    end
+
+    def warn(message, fields = {})
+      write("warn", message, fields)
+    end
+
+    def error(message, fields = {})
+      write("error", message, fields)
+    end
+
+    private
+
+    def write(level, message, fields)
+      return if LEVELS.index(level) < threshold
+      entry = {}
+      fields.each { |name, value| entry[name.to_s] = value }
+      entry["level"] = level
+      entry["message"] = message
+      @output.puts JSON.generate(entry)
     end
 
-    def error(message)
-      STDERR.puts "[edgeway] ERROR #{message}"
+    def threshold
+      LEVELS.index(Edgeway.config("LOG_LEVEL", "info")) || LEVELS.index("info")
     end
   end