monkrb 0.22.2 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4e809c375ae56d6ec8e0831623b9fb588550bc329e68a3c722cc81910e6bcc8
-  data.tar.gz: 542338ca1dd6750276d91fedce501c02e06d68506f6bbf6ffaafea64a9485611
+  metadata.gz: b284b12a8bb2491dd6d50c14d0d1db8cb0f2bf2d62a19dc525fc6ecbec81fb30
+  data.tar.gz: 6251d1fe25530d954df4a65f6d22a2b339cb55b87b97a8587259f8b16dbbbb24
 SHA512:
-  metadata.gz: aa576c261a4aaa57a117b163202a9c2b0b4865eb20fec828bebf39c9ef8e76bb868e809913c216773843cc69264b04471457b54c0124005db85cfc87d49b585b
-  data.tar.gz: 3844bc6db9d0b2edf4cc4cdeed5ac5dbe8e3035ac6634c7f30e525cbf6705e140ca0dcc2e30993e92ece55cb8aecb259d0dfdd5cca73232886875f8ab01e859b
+  metadata.gz: 586f9d0355b353a5e18f638059e0636f447c4aa104ceff395efa7dc81b05529019c9fdabbeb10c489eb360ecbc6d9d5d864ef4b5b48323769c3796c7757f3b4c
+  data.tar.gz: b03b5885c324e698b2b10946ea9289e61bbf89253fa225ab96c89d8039a8553e991c3f3158ad7f2caacc8c072c518bd752cb75e33fe6c45e645a9eecd0c2fda3

data/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to this project are documented here. Format is loosely
 [Keep a Changelog](https://keepachangelog.com/); versions are as released
 in `lib/monk/version.rb`.
 
+## 0.23.0 - 2026-10-26
+
+### Added
+
+- **File storage, `Monk::Storage`** (`require "monk/storage"`, ADR 0018,
+  `docs/guides/storage.md`). Files are stored by key in any S3-compatible
+  bucket (Hetzner, Cloudflare R2, Backblaze B2, AWS, MinIO), chosen by
+  one `STORAGE_URL`, and on the local disk in development and test.
+  `put`, `get` (with `range:`), `head`, `delete`, `copy`, signed download
+  links (`url`, the same URL within an hour so browsers cache it) and
+  browser uploads (`presigned_put`, with the type and length inside the
+  signature), all from any worker Ractor. SigV4 is Monk's own, with no
+  gem. Uploads go from the browser straight to the bucket and downloads
+  redirect to it, so no worker Ractor waits on the bytes. The file
+  backend behaves like a bucket, signed links and refusals included, at
+  `/_monk/storage`. `Monk::Storage::Sniff` tells PNG, JPEG, GIF, WebP,
+  Ogg/Opus and PDF from a file's first 64 bytes, and refuses SVG.
+  Checked on Hetzner Object Storage: the signed upload limits, CORS for
+  browser uploads, the lifecycle rule that expires `tmp/`, and `copy`
+  with both addressing styles (`bin/storage_check`).
+- **`monk add storage`**: `config/storage.rb`, the upload, confirm and
+  download flow as commented examples in `app/routes/storage.rb` (driven
+  with `curl`), and a test. No migration and no JavaScript: the guide
+  has an uploads table and the browser code to copy. An existing app
+  gets it the same way (`docs/guides/upgrading.md`, 0.23).
+- **`bin/storage_check`**, in the monk repository: checks a real bucket's
+  CORS rule for browser uploads and its `tmp/` lifecycle rule, then
+  removes both.
+
+### Changed
+
+- **A new app runs as production in its Docker image.** The scaffolded
+  `Dockerfile` sets `MONK_ENV=production`, which a platform's env can
+  override (`staging`). Unset, `MONK_ENV` means development, and a deploy
+  that forgot it ran that way without an error: mail printed instead of
+  sent, magic links logged, auth cookies without `Secure`, demo routes on,
+  storage links signed with a public value. `bin/server` now warns when it
+  listens beyond the machine (`--bind 0.0.0.0`) with `MONK_ENV` unset,
+  `monk new` lists `MONK_ENV` among the values to set before production,
+  and `docs/guides/deploying.md` sets it in every platform's example
+  (Render's start command is now `bin/server`, so the warning applies
+  there too). The deploy guide also gains storage's row.
+- **A new app's `Gemfile` asks for `monkrb ~> 0.23`.**
+- `docs/framework-comparison.md` is recomputed for 0.23.0, and
+  `docs/roadmap.md` moves storage up to 0.23 (it was planned as 0.26).
+
 ## 0.22.2 - 2026-10-22
 
 ### Fixed

data/README.md

@@ -21,7 +21,7 @@ bin/server           # -> http://localhost:9292/hello
 monk add --list      # the modules you can add: postgres, auth, jobs, live...
 ```
 
-`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.22", require: "monk"`.
+`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.23", require: "monk"`.
 
 `monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `public/`, its tests, a `SETUP.md` and an `AGENTS.md` for coding agents), with the app's own code under `app/`: `app/app.rb` and `app/routes/` for routes, `app/views/`, and one directory per role (`models/`, `presenters/`, `helpers/`, `mailers/`, `broadcasts/`, `jobs/`). `monk add` adds Postgres, Redis, email, auth, background jobs, WebSocket and live updates, to a new app or an old one, each with its wiring, commented examples of how to use it, and a test (`monk new my_app --with auth,jobs` does both at once): see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md), which also says where each kind of code goes.
 
@@ -65,6 +65,7 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
 | Background jobs | `Monk::Jobs`: a queue in Postgres, run by `bin/jobs` on worker Ractors; retries with backoff, scheduled jobs, recurring jobs on a cron schedule (UTC), enqueue inside the app's own transaction, `drain!` for tests | `require "monk/jobs"` (+ `require "monk/jobs/runtime"` in the job process); needs the `pg` gem and a registered Postgres connection | [`jobs.md`](docs/guides/jobs.md) |
 | WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis or Postgres fan-out | `require "monk/websocket"`; fan-out: `require "monk/websocket/redis_fanout"` (+ the `redis` gem) or `require "monk/websocket/pg_fanout"` (+ the `pg` gem) | [`websocket.md`](docs/guides/websocket.md) |
 | Live updates | `Monk::Live`: server-rendered HTML patches pushed to open tabs | `require "monk/live"`; needs the WebSocket server and, across processes, Redis or Postgres | [`live.md`](docs/guides/live.md) |
+| File storage | `Monk::Storage`: files by key in any S3-compatible bucket (Hetzner, R2, B2, AWS), local files in development and test; browser uploads and downloads through signed links, never through a worker Ractor | `require "monk/storage"`; no gem needed | [`storage.md`](docs/guides/storage.md) |
 | Scaffolding | `monk new` and `monk add`: one generator per module, for a new app or an existing one; text or `--json` output | — (the `monk` command: `monk new NAME --with ...`, `monk add MODULE`, `monk add --list`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
 
 ## More documentation
@@ -88,6 +89,6 @@ More (server modes, Docker) in [`docs/development.md`](docs/development.md).
 
 ## Status
 
-Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). Features to add are listed in [`docs/roadmap.md`](docs/roadmap.md). Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`). In 0.20 (2026-10-05): Monk recovers from a dropped database connection (a Postgres restart, a failover) without a process restart. `checkout` reconnects a dead connection before running its block, never retrying the block itself; both fanouts' listeners reconnect and then make every open page resync; and a route that raises logs why (`docs/history/plan-pg-reconnect.md`). Also new: connection pools for Ractors that shouldn't each hold a connection (`Monk::Persistence::Pg.pool`). The WebSocket server's session checks, Live's subscribe rules and `PgFanout`'s publisher can run through one, so open pages share a few connections instead of holding one each: 1,000 open sockets on 4 connections (`docs/guides/persistence.md`, "Pools"; `docs/history/plan-pg-pool.md`). In 0.21 (2026-10-09): scaffolding by module. `monk new` makes the core app, and `monk add` adds a module (Postgres, Redis, mail, auth, jobs, WebSocket, Live) to any app, new or existing, with its wiring, commented examples, a test, and its sections of `SETUP.md` and an `AGENTS.md` for coding agents; `--json` for agents and scripts. Redis and WebSocket become modules of their own, the WebSocket transport is chosen once per app, and `monk new`'s module flags are gone (ADR 0017, `docs/guides/scaffolding.md`, `docs/history/plan-scaffold.md`). In 0.22 (2026-10-13): recurring jobs on a cron schedule, `Monk::Jobs.recurring` in `config/recurring.rb`, enqueued once per occurrence however many `bin/jobs` run (ADR 0016, `docs/guides/jobs.md`); auth housekeeping, with a login-email rate limit in the database, an index on `sessions (subject)` and a nightly cleanup job (`docs/guides/auth.md`); and an upgrade guide for apps made with an earlier Monk (`docs/guides/upgrading.md`). In 0.22.1 (2026-10-20): the WebSocket server queues a connect burst instead of collapsing under it, refuses a handshake it can't check with a `503`, and takes more connects a second with thousands of sockets open: fewer allocations a connect, GC settings in `bin/websocket_server`, and `WS_PROCESSES` for several server processes on one port (`docs/guides/websocket.md`, `docs/plan-ws-connect-ceiling.md`). In 0.22.2 (2026-10-22): a fix for a handshake that could die when two connections were the first after boot (`docs/plan-digest-preload.md`).
+Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). Features to add are listed in [`docs/roadmap.md`](docs/roadmap.md). Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`). In 0.20 (2026-10-05): Monk recovers from a dropped database connection (a Postgres restart, a failover) without a process restart. `checkout` reconnects a dead connection before running its block, never retrying the block itself; both fanouts' listeners reconnect and then make every open page resync; and a route that raises logs why (`docs/history/plan-pg-reconnect.md`). Also new: connection pools for Ractors that shouldn't each hold a connection (`Monk::Persistence::Pg.pool`). The WebSocket server's session checks, Live's subscribe rules and `PgFanout`'s publisher can run through one, so open pages share a few connections instead of holding one each: 1,000 open sockets on 4 connections (`docs/guides/persistence.md`, "Pools"; `docs/history/plan-pg-pool.md`). In 0.21 (2026-10-09): scaffolding by module. `monk new` makes the core app, and `monk add` adds a module (Postgres, Redis, mail, auth, jobs, WebSocket, Live) to any app, new or existing, with its wiring, commented examples, a test, and its sections of `SETUP.md` and an `AGENTS.md` for coding agents; `--json` for agents and scripts. Redis and WebSocket become modules of their own, the WebSocket transport is chosen once per app, and `monk new`'s module flags are gone (ADR 0017, `docs/guides/scaffolding.md`, `docs/history/plan-scaffold.md`). In 0.22 (2026-10-13): recurring jobs on a cron schedule, `Monk::Jobs.recurring` in `config/recurring.rb`, enqueued once per occurrence however many `bin/jobs` run (ADR 0016, `docs/guides/jobs.md`); auth housekeeping, with a login-email rate limit in the database, an index on `sessions (subject)` and a nightly cleanup job (`docs/guides/auth.md`); and an upgrade guide for apps made with an earlier Monk (`docs/guides/upgrading.md`). In 0.22.1 (2026-10-20): the WebSocket server queues a connect burst instead of collapsing under it, refuses a handshake it can't check with a `503`, and takes more connects a second with thousands of sockets open: fewer allocations a connect, GC settings in `bin/websocket_server`, and `WS_PROCESSES` for several server processes on one port (`docs/guides/websocket.md`, `docs/plan-ws-connect-ceiling.md`). In 0.22.2 (2026-10-22): a fix for a handshake that could die when two connections were the first after boot (`docs/plan-digest-preload.md`). In 0.23 (2026-10-26): file storage, `Monk::Storage`, in any S3-compatible bucket (Hetzner, R2, B2, AWS) through Monk's own SigV4 signer, with local files in development and test that behave like a bucket. Browsers upload straight to the bucket and download through a redirect to a signed link, so no worker Ractor waits on the bytes, and `monk add storage` scaffolds the flow (ADR 0018, `docs/guides/storage.md`, `docs/history/plan-storage.md`).
 
 [Made with Love ❤️, Ruby 💎 and AI 🤖](docs/ai_usage_disclaimer.md)

data/lib/monk/base.rb

@@ -156,6 +156,11 @@ module Monk
         asset = Monk::Assets.response(env)
         return asset if asset
 
+        # The file storage backend's signed links (docs/history/plan-storage.md
+        # decision 7), only when the app requires monk/storage.
+        stored = Monk::Storage.response(env) if defined?(Monk::Storage)
+        return stored if stored
+
         route, path_params = find_route(env["REQUEST_METHOD"], env["PATH_INFO"])
         return not_found_response(env) unless route
 

data/lib/monk/generators/base.rb

@@ -15,5 +15,6 @@ Monk::Generator.define(:base) do
 
   setup_section "base/setup.md"
   agents_section "base/agents.md"
+  set_before_production "MONK_ENV", "production or staging; unset = development (the Dockerfile sets production)"
   next_step "bin/server", note: "http://localhost:9292"
 end

data/lib/monk/generators/storage.rb

@@ -0,0 +1,28 @@
+# Files users send (Monk::Storage): local files in development and test,
+# an S3-compatible bucket in production. No service to start, no migration
+# and no JS: the upload flow comes as commented routes driven with curl,
+# and the guide carries the uploads table and browser code
+# (docs/history/plan-storage.md Phase 8).
+Monk::Generator.define(:storage) do
+  summary "File storage (local files in development, an S3 bucket in production)"
+  installed_if "config/storage.rb"
+
+  copy "config/storage.rb", role: :wiring
+  copy "app/routes/storage.rb", role: :example
+  copy "test/storage_test.rb", role: :test
+
+  # Unset STORAGE_URL is file://storage/<env> in development and test, so
+  # neither .env file needs a line, and tests never touch development's
+  # files.
+  env :example, { "STORAGE_URL" => "s3://KEY:SECRET@bucket?endpoint=fsn1.your-objectstorage.com&region=fsn1",
+                  "STORAGE_SECRET" => "only-with-file-urls-a-random-hex-value", }, commented: true
+  ignore "/storage/"
+
+  setup_section "storage/setup.md"
+  agents_section "storage/agents.md"
+  set_before_production "STORAGE_URL", "an S3 bucket; file:// only on one server with a persistent volume"
+  set_before_production "STORAGE_SECRET", "only with file://: signs its links"
+  example "storage-upload", todo: "uncomment, and set the types and sizes this app accepts"
+  example "storage-confirm", todo: "uncomment, and save a record of each file in the app's own table"
+  example "storage-download", todo: "uncomment, then replace with a record lookup and an access check"
+end

data/lib/monk/generators.rb

@@ -2,6 +2,6 @@ require_relative "generator"
 
 # Monk's own modules, one generator each (docs/adr/0017), in dependency
 # order only for readability: the registry resolves dependencies itself.
-%w[base postgres redis mail auth jobs websocket live].each do |name|
+%w[base postgres redis mail auth jobs websocket live storage].each do |name|
   require_relative "generators/#{name}"
 end

data/lib/monk/storage/backends/file.rb

@@ -0,0 +1,242 @@
+require "digest"
+# Loaded here, at boot: left to Digest.const_missing it loads on the first
+# put, and a worker Ractor storing another in parallel can catch it
+# half-defined (test/digest_preload_test.rb).
+require "digest/md5"
+require "fileutils"
+require "json"
+require "securerandom"
+
+module Monk
+  module Storage
+    module Backends
+      # Local disk, the development and test default (file://storage/<env>)
+      # and an explicit choice for one server with a persistent volume.
+      # root is absolute, expanded at configure, so a worker Ractor never
+      # depends on the current directory. secret signs the links of the
+      # /_monk/storage routes (docs/adr/0018-storage-s3-compatible-direct-upload.md).
+      #
+      # It behaves like a bucket: an object's bytes are in
+      # <root>/objects/<key>~ and its metadata (content type, size, MD5) in
+      # <root>/meta/<key>~.json. The "~", which no key contains, keeps a
+      # key's file apart from the directory of a longer key ("a" and
+      # "a/b" both exist in a bucket). Writes go to a temporary file then
+      # File.rename, so a reader never sees half an object. An object
+      # exists once its metadata does.
+      #
+      # Inside this block a bare File is this class: the disk is ::File.
+      File = Data.define(:root, :secret) do
+        # Returns the key. body is a String, or an IO that responds to size,
+        # read and rewind (File, Tempfile, StringIO).
+        def put(key, body, content_type: Input::DEFAULT_CONTENT_TYPE)
+          Input.content_type!(content_type)
+          Input.body!(body)
+          object = path_for("objects", key, "~")
+          meta = path_for("meta", key, "~.json")
+
+          md5, size = write_atomically(object) { |out| copy_body(body, out) }
+          write_atomically(meta) do |out|
+            out.write(JSON.generate(content_type: content_type, byte_size: size, etag: md5))
+          end
+          key
+        rescue SystemCallError, IOError => e
+          raise RequestError, "file storage put #{key} failed: #{e.class}: #{e.message}"
+        end
+
+        # The bytes, as a frozen binary String. range: is a Range of byte
+        # offsets (0..15 for the first 16 bytes); a range past the end gives
+        # what's left, possibly "". A missing key raises NotFoundError.
+        def get(key, range: nil)
+          span = Input.byte_span(range) if range
+          path = path_for("objects", key, "~")
+          meta = read_meta(key) or raise NotFoundError, "no stored object #{key.inspect}"
+          bytes = span ? read_span(path, span, meta[:byte_size]) : ::File.binread(path)
+          bytes.freeze
+        rescue Errno::ENOENT
+          raise NotFoundError, "no stored object #{key.inspect}"
+        rescue SystemCallError, IOError => e
+          raise RequestError, "file storage get #{key} failed: #{e.class}: #{e.message}"
+        end
+
+        # A Storage::Object, or nil when the key is missing.
+        def head(key)
+          meta = read_meta(key) or return nil
+          Storage::Object.new(key: key, byte_size: meta[:byte_size], content_type: meta[:content_type],
+            etag: meta[:etag],)
+        rescue SystemCallError, IOError => e
+          raise RequestError, "file storage head #{key} failed: #{e.class}: #{e.message}"
+        end
+
+        # Idempotent, like S3: deleting a missing key is not an error.
+        def delete(key)
+          meta = path_for("meta", key, "~.json")
+          object = path_for("objects", key, "~")
+          ::FileUtils.rm_f(meta)
+          ::FileUtils.rm_f(object)
+          nil
+        rescue SystemCallError, IOError => e
+          raise RequestError, "file storage delete #{key} failed: #{e.class}: #{e.message}"
+        end
+
+        # Returns to. A missing from raises NotFoundError.
+        def copy(from, to)
+          source = path_for("objects", from, "~")
+          target = path_for("objects", to, "~")
+          target_meta = path_for("meta", to, "~.json")
+          meta = read_meta(from) or raise NotFoundError, "no stored object #{from.inspect}"
+          return to if source == target
+
+          write_atomically(target) { |out| ::File.open(source, "rb") { |input| ::IO.copy_stream(input, out) } }
+          write_atomically(target_meta) { |out| out.write(JSON.generate(meta)) }
+          to
+        rescue Errno::ENOENT
+          raise NotFoundError, "no stored object #{from.inspect}"
+        rescue SystemCallError, IOError => e
+          raise RequestError, "file storage copy #{from} -> #{to} failed: #{e.class}: #{e.message}"
+        end
+
+        # A signed download link, the same for every call within one
+        # cache_window, so the browser's cache works: valid until the end
+        # of the window plus expires_in (docs/history/plan-storage.md decision 9).
+        def url(key, expires_in:, cache_window:, now: Time.now.to_i)
+          Key.validate!(key)
+          Input.link_times!(expires_in: expires_in, cache_window: cache_window)
+          window_start = now - (now % cache_window)
+          link({ m: "GET", k: key, e: window_start + cache_window + expires_in })
+        end
+
+        # A signed upload link for a browser, with the length and content
+        # type inside it.
+        def presigned_put(key, content_type:, byte_size:, expires_in:, now: Time.now.to_i)
+          Key.validate!(key)
+          Input.content_type!(content_type)
+          Input.byte_size!(byte_size)
+          Input.link_times!(expires_in: expires_in, cache_window: 1)
+          url = link({ m: "PUT", k: key, e: now + expires_in, l: byte_size, t: content_type })
+          Upload.new(url: url, headers: { "Content-Type" => content_type, "Content-Length" => byte_size.to_s }.freeze)
+        end
+
+        # The /_monk/storage PUT: stores input (rack.input, read once) as
+        # key, if it holds exactly byte_size bytes. Returns the MD5, or nil
+        # when the length is wrong, and then stores nothing.
+        def receive(key, input, content_type:, byte_size:)
+          object = path_for("objects", key, "~")
+          meta = path_for("meta", key, "~.json")
+
+          md5 = write_atomically(object) do |out|
+            digest, size = copy_at_most(input, out, byte_size)
+            return nil unless size == byte_size
+
+            digest
+          end
+          write_atomically(meta) do |out|
+            out.write(JSON.generate(content_type: content_type, byte_size: byte_size, etag: md5))
+          end
+          md5
+        rescue SystemCallError, IOError => e
+          raise RequestError, "file storage upload #{key} failed: #{e.class}: #{e.message}"
+        end
+
+        # Never print the secret -- a backend ends up in logs and exception
+        # messages more easily than anyone intends (same as Mail's SMTP).
+        def inspect
+          "#<#{self.class.name} file://#{root}>"
+        end
+        alias_method :to_s, :inspect
+
+        private
+
+        # The key is validated first, then the path is checked to stay under
+        # root -- the Assets#disk_entry containment check -- and to go
+        # through no symbolic link below root, which could point anywhere.
+        def path_for(area, key, suffix)
+          Key.validate!(key)
+          base = ::File.join(root, area)
+          full = ::File.expand_path("#{key}#{suffix}", base)
+          unless full.start_with?("#{base}/")
+            raise InvalidKeyError,
+              "storage key #{key.inspect} resolves outside #{base}"
+          end
+
+          refuse_symlinks!(key, base, full)
+          full
+        end
+
+        def refuse_symlinks!(key, base, full)
+          path = base
+          [nil, *full.delete_prefix("#{base}/").split("/")].each do |segment|
+            path = ::File.join(path, segment) if segment
+            next unless ::File.symlink?(path)
+
+            raise InvalidKeyError, "storage key #{key.inspect} goes through a symbolic link (#{path})"
+          end
+        end
+
+        def read_meta(key)
+          JSON.parse(::File.read(path_for("meta", key, "~.json")), symbolize_names: true)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def read_span(path, span, size)
+          first, last = span
+          last = size - 1 if last.nil? || last >= size
+          return "".b if first >= size
+
+          ::File.open(path, "rb") do |file|
+            file.seek(first)
+            file.read(last - first + 1) || "".b
+          end
+        end
+
+        # Yields a binary IO on a temporary file next to path, then renames
+        # it into place. Returns the block's result.
+        def write_atomically(path, &)
+          ::FileUtils.mkdir_p(::File.dirname(path))
+          temporary = "#{path}#{SecureRandom.hex(8)}.tmp"
+          result = ::File.open(temporary, "wb", &)
+          ::File.rename(temporary, path)
+          result
+        ensure
+          ::FileUtils.rm_f(temporary) if temporary && ::File.exist?(temporary)
+        end
+
+        def link(payload)
+          "#{ROUTE_PREFIX}#{Token.sign(payload, secret)}"
+        end
+
+        # Reads at most limit + 1 bytes, enough to tell a body that's too
+        # long. Returns [md5 hex, bytes read].
+        def copy_at_most(input, out, limit)
+          md5 = Digest::MD5.new
+          size = 0
+          while size <= limit && (chunk = input.read([Input::CHUNK_BYTES, limit + 1 - size].min))
+            out.write(chunk)
+            md5 << chunk
+            size += chunk.bytesize
+          end
+          [md5.hexdigest, size]
+        end
+
+        # Returns [md5 hex, bytes written].
+        def copy_body(body, out)
+          md5 = Digest::MD5.new
+          if body.is_a?(String)
+            out.write(body)
+            md5 << body
+            return [md5.hexdigest, body.bytesize]
+          end
+
+          body.rewind
+          size = 0
+          while (chunk = body.read(Input::CHUNK_BYTES))
+            out.write(chunk)
+            md5 << chunk
+            size += chunk.bytesize
+          end
+          [md5.hexdigest, size]
+        end
+      end
+    end
+  end
+end

data/lib/monk/storage/backends/s3.rb

@@ -0,0 +1,197 @@
+require "net/http"
+
+module Monk
+  module Storage
+    module Backends
+      # Any S3-compatible service (Hetzner, R2, B2, AWS, MinIO): Monk names
+      # no provider, only an endpoint and a region. A frozen value holding
+      # settings only; the HTTP client is built for each call, inside the
+      # Ractor making it, like Mail's SMTP and PG::Connection
+      # (docs/adr/0018-storage-s3-compatible-direct-upload.md).
+      #
+      # endpoint is host[:port]. tls: false only for a local server
+      # (endpoint=http://..., refused in staging and production).
+      # path_style: true puts the bucket in the path instead of the host
+      # name, which local servers need.
+      S3 = Data.define(:bucket, :endpoint, :region, :access_key, :secret_key, :path_style, :tls,
+        :open_timeout, :read_timeout,) do
+        def initialize(bucket:, endpoint:, region:, access_key:, secret_key:, path_style: false, tls: true,
+                       open_timeout: 5, read_timeout: 30)
+          super
+        end
+
+        # Returns the key. body is a String, or an IO that responds to size,
+        # read and rewind: its SHA-256 is computed first and signed, then it
+        # is rewound and streamed, so it's read twice but never held in
+        # memory (docs/history/plan-storage.md decision 11).
+        def put(key, body, content_type: Input::DEFAULT_CONTENT_TYPE)
+          Key.validate!(key)
+          Input.content_type!(content_type)
+          Input.body!(body)
+
+          response = request("PUT", key, body: body, headers: { "content-type" => content_type })
+          return key if response.is_a?(Net::HTTPSuccess)
+
+          fail!("put", key, response)
+        end
+
+        # The bytes, as a frozen binary String. range: is a Range of byte
+        # offsets; one that starts past the end gives "" (S3's 416).
+        def get(key, range: nil)
+          Key.validate!(key)
+          headers = {}
+          if range
+            first, last = Input.byte_span(range)
+            headers["range"] = "bytes=#{first}-#{last}"
+          end
+
+          response = request("GET", key, headers: headers)
+          case response
+          when Net::HTTPSuccess then response.body.to_s.b.freeze
+          when Net::HTTPNotFound then raise NotFoundError, "no stored object #{key.inspect}"
+          when Net::HTTPRangeNotSatisfiable then "".b.freeze
+          else fail!("get", key, response)
+          end
+        end
+
+        # A Storage::Object, or nil when the key is missing. A bucket that
+        # doesn't grant ListBucket answers 403, not 404, for a missing key:
+        # that's a RequestError here, as the credentials need fixing.
+        def head(key)
+          Key.validate!(key)
+          response = request("HEAD", key)
+          return nil if response.is_a?(Net::HTTPNotFound)
+
+          fail!("head", key, response) unless response.is_a?(Net::HTTPSuccess)
+
+          Storage::Object.new(key: key, byte_size: response["content-length"].to_i,
+            content_type: response["content-type"], etag: response["etag"].to_s.delete('"'),)
+        end
+
+        # Idempotent: S3 answers 204 for a missing key too.
+        def delete(key)
+          Key.validate!(key)
+          response = request("DELETE", key)
+          return nil if response.is_a?(Net::HTTPSuccess)
+
+          fail!("delete", key, response)
+        end
+
+        # Returns to. The content type is copied with the bytes. S3 can
+        # answer 200 to a copy that failed, with an <Error> in the body, so
+        # the body is checked too.
+        def copy(from, to)
+          Key.validate!(from)
+          Key.validate!(to)
+          source = SigV4.encode_path("/#{bucket}/#{from}")
+
+          response = request("PUT", to, headers: { "x-amz-copy-source" => source })
+          raise NotFoundError, "no stored object #{from.inspect}" if response.is_a?(Net::HTTPNotFound)
+          return to if response.is_a?(Net::HTTPSuccess) && !response.body.to_s.include?("<Error>")
+
+          fail!("copy #{from} ->", to, response)
+        end
+
+        # A signed GET link, the same for every call within one
+        # cache_window: signed at the window's start, valid for the window
+        # plus expires_in (docs/history/plan-storage.md decision 9).
+        def url(key, expires_in:, cache_window:, now: Time.now.to_i)
+          Key.validate!(key)
+          Input.link_times!(expires_in: expires_in, cache_window: cache_window)
+          query = SigV4.presign(method: "GET", path: path_for(key), headers: { "host" => host },
+            expires_in: cache_window + expires_in, credentials: credentials, now: now - (now % cache_window),)
+          "#{base_url}#{SigV4.encode_path(path_for(key))}?#{query}"
+        end
+
+        # A signed PUT link for a browser, with Content-Type and
+        # Content-Length among its signed headers: the bucket refuses a
+        # body of another length or type.
+        def presigned_put(key, content_type:, byte_size:, expires_in:, now: Time.now.to_i)
+          Key.validate!(key)
+          Input.content_type!(content_type)
+          Input.byte_size!(byte_size)
+          headers = { "host" => host, "content-type" => content_type, "content-length" => byte_size.to_s }
+          query = SigV4.presign(method: "PUT", path: path_for(key), headers: headers, expires_in: expires_in,
+            credentials: credentials, now: now,)
+
+          Upload.new(url: "#{base_url}#{SigV4.encode_path(path_for(key))}?#{query}",
+            headers: { "Content-Type" => content_type, "Content-Length" => byte_size.to_s }.freeze,)
+        end
+
+        # Never print the secret key -- a backend ends up in logs and
+        # exception messages more easily than anyone intends.
+        def inspect
+          "#<#{self.class.name} s3://#{access_key}:***@#{bucket} #{tls ? "https" : "http"}://#{endpoint} " \
+            "region=#{region}#{" path_style" if path_style}>"
+        end
+        alias_method :to_s, :inspect
+
+        private
+
+        def credentials
+          { access_key: access_key, secret_key: secret_key, region: region }
+        end
+
+        # Virtual-hosted (bucket.endpoint/key) unless path_style
+        # (endpoint/bucket/key).
+        def host
+          path_style ? endpoint : "#{bucket}.#{endpoint}"
+        end
+
+        def path_for(key)
+          path_style ? "/#{bucket}/#{key}" : "/#{key}"
+        end
+
+        def base_url
+          "#{tls ? "https" : "http"}://#{host}"
+        end
+
+        # One signed request, on a connection opened for it in the calling
+        # Ractor. Network and TLS failures become a RequestError, the
+        # original as its #cause.
+        def request(method, key, body: nil, headers: {})
+          payload_hash = body ? Input.sha256(body) : SigV4::EMPTY_PAYLOAD
+          signed = headers.merge("host" => host, "x-amz-content-sha256" => payload_hash)
+          signed["content-length"] = body.size.to_s if body
+          path = path_for(key)
+          authorization = SigV4.sign_headers(method: method, path: path, headers: signed,
+            payload_hash: payload_hash, credentials: credentials, now: Time.now.to_i,)
+
+          http_request = Net::HTTPGenericRequest.new(method, !body.nil?, method != "HEAD", SigV4.encode_path(path),
+            signed.merge(authorization).merge("accept-encoding" => "identity"),)
+          attach(http_request, body) if body
+          connection.start { |http| http.request(http_request) }
+        rescue IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse,
+               Net::ProtocolError => e
+          raise RequestError, "S3 #{method} #{key} via #{host} failed: #{e.class}: #{e.message}"
+        end
+
+        def attach(http_request, body)
+          if body.is_a?(String)
+            http_request.body = body
+          else
+            body.rewind
+            http_request.body_stream = body
+          end
+        end
+
+        def connection
+          http = Net::HTTP.new(host.sub(/:\d+\z/, ""), endpoint[/:(\d+)\z/, 1]&.to_i || (tls ? 443 : 80))
+          http.use_ssl = tls
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+          http.write_timeout = read_timeout
+          http
+        end
+
+        def fail!(operation, key, response)
+          code = response.body.to_s[%r{<Code>([^<]*)</Code>}, 1]
+          message = response.body.to_s[%r{<Message>([^<]*)</Message>}, 1]
+          detail = [code, message].compact.join(": ")
+          raise RequestError,
+            "S3 #{operation} #{key} via #{host} failed: HTTP #{response.code}#{" #{detail}" unless detail.empty?}"
+        end
+      end
+    end
+  end
+end

data/lib/monk/storage/errors.rb

@@ -0,0 +1,34 @@
+module Monk
+  module Storage
+    class NotConfiguredError < StandardError
+    end
+
+    class InvalidStorageUrlError < StandardError
+    end
+
+    class MissingStorageUrlError < StandardError
+    end
+
+    class MissingStorageSecretError < StandardError
+    end
+
+    # An ArgumentError: a key is always the caller's input.
+    class InvalidKeyError < ArgumentError
+    end
+
+    # get or copy of a key that isn't there.
+    class NotFoundError < StandardError
+    end
+
+    # A call that failed on the way to or from the backend -- network, TLS,
+    # the disk, or the bucket refusing it. The original exception is the
+    # #cause, the way Monk::Mail::DeliveryError works.
+    class RequestError < StandardError
+    end
+
+    # Bytes that must never be served as uploaded (SVG, which can carry
+    # scripts).
+    class UnsafeContentError < StandardError
+    end
+  end
+end