ruact 0.0.19 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d7fb20ee09bec81b05b4e1cafba8f511e46a77d2bee2afc7bb92ca8e026483d
-  data.tar.gz: 6111ba333bf9067854a13c62ec66f13297c78c3a6c4c419f39284d001d57d2c4
+  metadata.gz: e96181a35f53a1a25da4cd4db1ca655aeff15cdd5190f56aaafb97f1a2a19361
+  data.tar.gz: e9034d5a9f16dee7a5a319483364dbbf049a6b0aecf63073c3efcfe66ce6baa4
 SHA512:
-  metadata.gz: 1b9ed6e86719935a5494f4a847c1938e903c4440f0b026ba3c1780eb0407fe6cf2214b448b3a6e34b8c10e45f42c3e4964dd2bcbaa14c33ec35d5e71114d7bbc
-  data.tar.gz: c25217ef2564fc948c0aee0191878a4addeefaf4e3edb45986e6d0b1d8b547f17cdc72b15a366d8a9d886db378e522b3c7394fd00ba22f9e05fd11dab8e49a61
+  metadata.gz: c90a2671ac0774bd51f726af1dc22ab58ba048ee6354b1078888ad2704289214caa6b6189b8909c72ab074546a37dc80676fb49576e630d09d1629eb09ff22ba
+  data.tar.gz: e71ea90b4a5ee1450fd5c772fe7a99c9641b5febb8465ea0e7649fc1ab00db670fcdd3333b34bffbcc870bb0d719deb9b236f40769e6277097f0a3cdaa0bc115

data/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.21] - 2026-10-15
+
+### Changed
+
+- **Leaving a page whose document is still arriving stops loading it.** A page that streams keeps its document open until its last `<Suspense>`; when the router leaves the page (a link, a form) before that, it now calls `window.stop()` first, so the connection closes and the server, which asks before each block, starts no further block for a page nobody will see. Only a document that streams and still has rows to come: the server marks it. Stopping it also stops what that document was still loading — measured in Chrome: an image still loading stays broken, a `fetch` in flight fails with `TypeError`, and a module `import()` in flight fails (importing it again works). The boundaries of the page being left stay quiet, as for a navigation that replaced another: no "response ended before the whole page arrived" error is reported for them. Only while the document itself is loading — a page that has finished is not touched. `revalidate()` stays on the page and does not stop it: stopping would fail the page's other requests in flight, a server function or a `useQuery` among them. When the navigation that stopped it ends without replacing the page — the network, a 403 or a 500 to a form, a redirect that fails, or a second click that superseded the first and failed — the router fetches the page it is still on again, once, so its boundaries do not keep their fallback.
+- **A link or Back/Forward to an `#anchor` of the page on screen is left to the browser.** The client router fetched and rendered the same page again for `/posts/1#comments` while on `/posts/1`; now the browser scrolls, nothing is fetched, and a page still streaming is not stopped. A link to another page with an anchor is the router's, as before.
+- **`content_for` inside a `<Suspense>` that runs later is an error of that boundary, in development.** The layout was sent before the block ran, so what it declared never showed. Reading (`content_for?`, `yield :name`) still works.
+- **The development overlay shows every `<Suspense>` that failed**, one under the other, instead of only the last; a click closes it, and the next failure opens it again.
+- **A streamed Flight response is `Cache-Control: no-store`** (it was `no-cache`). A response the browser may store holds its cache entry while it streams, and Chrome then held a second request for the same URL — `revalidate()` on a page still streaming, the same link clicked again — until the first one ended. The streamed document keeps `no-cache`, so the page can still enter the back/forward cache.
+
+- **An action declared with `ruact_streaming` that got a request over HTTP/1.0 now says so.** Live answers HTTP/1.0 with an ordinary response, so the page is sent whole — and nginx talks HTTP/1.0 to the app unless told `proxy_http_version 1.1;`, so in production a page that should stream silently did not. The app now logs a warning the first time it happens in the process, in every environment, naming the action and the nginx line (Rack::Test, in an app's request specs, speaks HTTP/1.0 too, so it shows there once). `rails ruact:doctor` (and `--json`) adds the same hint to its streaming check when a controller declares `ruact_streaming` or includes `ActionController::Live`.
+
+- **Every script ruact writes carries the request's CSP nonce.** An app whose Content Security Policy allows scripts by nonce (`config.content_security_policy_nonce_generator`, no `'unsafe-inline'`) blocked the inline `__FLIGHT_DATA` script, the development module that loads Vite, and — on a page that streams — each `<Suspense>`'s rows: the page never mounted, or its fallbacks never resolved. The nonce is now on all of them, and on the entry `<script src>`. Without a nonce generator not a byte changes. In development React's own Flight client tries `eval()` for its debugging features and goes on without it; a policy without `'unsafe-eval'` reports that refusal in development only.
+
+- **The `AGENTS.md` that `rails generate ruact:install` writes names what a `<Suspense>` that streams cannot hold.** Besides status, redirect, cookies, session and flash: `content_for`, and the locale, tenant or database role a middleware scopes (they belong in an `around_action`); and a `cache` block goes inside a `<Suspense>`, never around one.
+
+### Fixed
+
+- **On Rack 2, a page that streams was held until its last `<Suspense>`.** Rack 2's `Rack::ETag` (in every Rails app's middleware) reads a 200 body whole to digest it, unless the response already has an `ETag` or a `Last-Modified` — `Cache-Control: no-cache` does not stop it, contrary to what ruact assumed. Rails 7.2 through 8.1 accept Rack 2.2, so an app on it got no streaming at all: no shell, no fallback, the page at the end. On Rack 2 a streamed response now carries a weak `ETag` of its own, new for every response, so no `If-None-Match` ever matches it — unless the action set its own `ETag` or `Last-Modified` (`fresh_when`), which already keeps `Rack::ETag` away and is left as it is. Measured with Rack 2.2.24. Rack 3 is unchanged.
+- **A client component or a `<Suspense>` inside a `cache` block no longer comes back as another one.** A fragment cache stores the HTML a render produced, with the markers that render gave its components and blocks; read back in another render, a marker could name one of *that* render's components (the page showed the wrong component, with its props) or another boundary's block (a `<Suspense>` showed another one's content). Every marker now carries the id of the render that wrote it. A client component read from the cache raises `Ruact::HtmlConverterError`, naming the `cache` and what to do (keep the component outside it); a `<Suspense>` read from the cache gets an error row for that boundary only, saying the same, and the rest of the page renders; the server logs it and reports it to `Rails.error` (`source: "ruact.suspense"`), whether the page streams or not. A marker cached by 0.0.20 or before, read after the upgrade, is taken for one of another render too.
+- **A `<Suspense>` that runs later sees its local variables as they were at the tag.** In an action that streams, the block ran after the rest of the template and read a local as it was then: every block of a `for` loop showed the last item, and a local reassigned below the tag showed the new value. Locals are now kept when the tag is met and given back to the block when it runs. What is kept is the variable, not a copy of its object: a list appended to below the tag shows the item appended. A local an earlier `<Suspense>` reassigns is not seen by the ones after it. Instance variables are still read when the block runs.
+- **A query still running when a `<Suspense>` passes `suspense_timeout` is cancelled (PostgreSQL).** The timeout gave the response back, but the query went on running on the server, and its connection — back in the pool — made the next query on it wait until it ended (seconds). At the limit ruact now cancels the queries in flight on the connections the block holds or just gave back (`PG::Connection#cancel`; the block's fiber under `isolation_level = :fiber`); the connection is free again at once, and the boundary gets the timeout. A query `load_async` started is not cancelled: the async executor's thread holds its connection. Other adapters are unchanged. For those queries, and with any other adapter, the database's statement timeout stays the limit.
+- **Error lines below a component tag written over several lines are right.** The preprocessor put a multi-line tag on one line, so Rails named a line too early for any error below it (an error page, a backtrace) — since component tags existed. The tag's line breaks are kept.
+- **The development overlay's backtrace names the right template lines.** React's development client reads each server frame as six fields; ruact sent four, and every frame came out at line 2.
+- **An exception raised after a streamed page was sent (an `after_action`) reaches `Rails.error`.** `ActionController::Live` only logs what is raised once the response has started, so an app's error reporting never heard of it; ruact reports it (`source: "ruact.stream"`). The page in the browser is unchanged.
+
+## [0.0.20] - 2026-10-14
+
+### Added
+
+- **`ruact_streaming` — a page sent as it renders.** In an action the controller declares (`ruact_streaming`, `ruact_streaming only: :show`, `except:`; without arguments, every ruact page of the controller), the shell and the `<Suspense>` fallbacks reach the browser first, and each `<Suspense>`'s content runs after that, one at a time, in page order (a `<Suspense>` inside one waits behind the page's others), in the view and with the template path it was written in, and arrives when it is ready — on the first load (the document stays open and pushes each boundary's rows) and on a navigation. Those actions run under `ActionController::Live`, applied per action: the controller's other actions respond as before, with their `ETag`, on the request's thread. `Controller.action(:name)` endpoints included. Over HTTP/1.0 — nginx's default to its upstream; set `proxy_http_version 1.1` — Live cannot stream, and the page renders whole, as without `ruact_streaming`.
+- **A `<Suspense>` that fails, in development, over the page.** A `<Suspense>` whose content raises gets an error row: its fallback stays, the next one runs, the response stays 200, and the error goes to `Rails.error` (`source: "ruact.suspense"`) and the log. Development shows it over the page, with the Ruby backtrace; production says only that a part failed (`ruact:suspense-error`).
+- **`ruact:doctor` checks `load_async`.** A new check, `load_async`, warns when `config.active_record.async_query_executor` is not set (`load_async` then runs its query where it is called); in development the first such `load_async` says so in the log.
+
+### Fixed
+
+- **A `<Suspense>` written as text inside ERB code stays as written.** `<%= "<Suspense>" %>` printed ruact's internal `<ruact-suspense …>` markup instead of the text (and a tag with attributes there did not compile). Tags inside `<% %>` and `<%= %>` are now left alone, as component tags already were.
+- **Error lines after a `<Suspense>` tag written over several lines are right.** The tag was rewritten onto one line, so Rails named an earlier line for any error below it.
+
+### Changed
+
+- **Every `<Suspense>` must close, in the same template and the same ERB block.** A `<Suspense>` with no `</Suspense>`, a `</Suspense>` that closes nothing, or a pair split across an ERB block (`<% if %><Suspense><% end %>…</Suspense>`) raises `Ruact::ComponentTagError` naming the template's line, as a component tag already does. Before, such a template rendered whatever the HTML parser made of it, sometimes with the content outside the boundary. This counts `<Suspense>` written as text in an attribute, a `<script>` or an HTML comment, and a pair opened in one partial and closed in another. `<Suspense fallback="…" />` is a boundary with nothing in it.
+- **A `<Suspense>`'s content is its own Ruby scope.** A local variable assigned between the tags is not visible after `</Suspense>`; instance variables and `content_for` still cross it. `break`, `next`, `redo` and `return` written between the tags outside a loop or block of their own, and `it` or `_1` outside a block of their own, would apply to the Suspense and not to the loop around it, so they raise `Ruact::ComponentTagError` with the line: name the block's parameter, or move the statement out. An `it` the template made a local before the tag (`|it|`, `it = …`) is that local. This is what lets the content be rendered later.
+- **`fallback` and `delay` take literal text.** ERB inside either now raises `Ruact::PreprocessorError` with the line. It never worked: the fallback came out empty and the page showed a stray `">`.
+- **In an action that streams, a `<Suspense>`'s content runs after the shell is sent.** Code inside it that the rest of the template depended on — an instance variable read further down, a `content_for` — now runs later. Status, redirects, headers, cookies, the session and the flash are set in the controller, before the page renders: written inside a `<Suspense>` they never reach the browser, and development makes that an error of the boundary (and logs it when an `after_action` does it).
+- **No default `delay`.** A `<Suspense>` waited 1.5 s before its content on every streamed navigation, even when the content was ready. `delay=` still waits that long, inside `suspense_timeout`.
+- **`suspense_timeout` limits real time.** It bounds how long a `<Suspense>`'s content may run (an explicit `delay` included), with a timeout a `rescue` of `StandardError` in the content does not catch (Active Record wrapping a query's error included); past it the boundary gets the timeout error and the next one runs. It does not stop a query the database is running — set the database's statement timeout for that.
+- **An error inside a `<Suspense>` no longer makes the response a 500** in an action that streams: the boundary gets the error (see Added). An exception once the response has started is reported and the response closed, without Rails' `/500.html` script.
+- **The entry script is `async`, on every ruact page.** It runs as soon as it has loaded, so a page that streams shows its fallbacks; the bootstrap waits for `#root` when a layout puts `ruact_js_assets` above it.
+- **A controller that includes `ActionController::Live` streams every page**, with the content of each `<Suspense>` rendered after the shell; `ruact_streaming` is the documented way. A controller with neither responds as before, and development says, once per response, which line makes an action with a `<Suspense>` stream.
+- **Connections a streamed action took are given back when it ends.** Under Live the action runs in a thread of its own, and a `Model.connection` there kept its connection until the thread was reused.
+- **Supported Rails is 7.2 through 8.1.** The test matrix named Rails 7.0 and 7.1 but ran 7.2 in those cells (`~> 7.0` admits every 7.x), so neither was ever tested; on them, `rails generate ruact:scaffold` fails. The matrix now runs 7.2, 8.0 and 8.1, each cell checks it loaded the Rails it names, and 7.0 and 7.1 are no longer claimed. Rails itself maintains only 8.0 and 8.1.
+- **The render path was reorganised, with no change to what a page sends.** What a template leaves for the converter, how a render hands out its rows (the shell first, then each Suspense boundary), how a response is written, and how the browser opens a page's Flight stream each live in one place now; the Flight bytes are the same, checked against the wire fixtures and in a browser. Internal classes changed shape (`Ruact::RenderContext`, `Ruact::Flight::Request`, `Ruact::Flight::Renderer`, `Ruact::RenderPipeline`); none of them is public API.
+
 ## [0.0.19] - 2026-10-08
 
 ### Fixed
@@ -490,7 +544,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.19...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.21...HEAD
+[0.0.21]: https://github.com/luizcg/ruact/releases/tag/v0.0.21
+[0.0.20]: https://github.com/luizcg/ruact/releases/tag/v0.0.20
 [0.0.19]: https://github.com/luizcg/ruact/releases/tag/v0.0.19
 [0.0.18]: https://github.com/luizcg/ruact/releases/tag/v0.0.18
 [0.0.17]: https://github.com/luizcg/ruact/releases/tag/v0.0.17

data/CONTRIBUTING.md

@@ -62,12 +62,13 @@ every pull request. Running them locally first is the difference between one rou
 
 | CI job | What it checks |
 |---|---|
-| `rspec` | the Ruby suite, on Ruby 3.2/3.3 × Rails 7.0/7.1/7.2/8.0 — eight cells |
+| `rspec` | the Ruby suite, on Ruby 3.2/3.3 × Rails 7.2/8.0/8.1 — six cells, each checking it loaded the Rails it names |
 | `rubocop` | style, plus the three custom cops below |
 | `yard` | every public method carries YARD documentation |
 | `js` | the Vite plugin's vitest suite, including its Ruby↔JS byte-parity cases, and a type-level test over the generated accessors |
 | `benchmark` | render-pipeline allocations against a recorded baseline |
 | `name-propagation` | greps the tree for names retired before v0.1.0 |
+| `browser` | the browser proof of a page that streams (`spec/browser/deferred_suspense/run`): a Rails app on Puma with the gem by path, in Chromium, in development and production, and the perturbation that must fail |
 | `gate` | that `CHANGELOG.md` gained something if this branch changed what the published gem contains, and that a version bump is one legal semver step to a version nothing has released |
 
 <!-- ci-jobs:end -->
@@ -95,8 +96,14 @@ npm test
 npm run typecheck
 ```
 
-To reproduce one matrix cell other than the default — `RAILS_VERSION` is what the eight `rspec` cells vary,
-and unset means 8.0:
+and, for the `browser` job (Node and Chromium; ports 4190 and 5199):
+
+```bash
+spec/browser/deferred_suspense/run
+```
+
+To reproduce one matrix cell other than the default — `RAILS_VERSION` is what the six `rspec` cells vary,
+and unset means 8.1:
 
 ```bash
 RAILS_VERSION=7.2 bundle install && bundle exec rspec

data/README.md

@@ -98,7 +98,7 @@ Every item below is shipped in this gem at v0.0.11:
 - **Signed record references** — `Ruact.signed_global_id(record, for:, expires_in:)` out, `Ruact.locate_signed(token, for:)` back in; a tampered token is a `400`, not a lookup. [Docs](https://ruact.dev/docs/api/server-actions)
 - **Client-side navigation** — link interception, scroll restoration and redirect-after-POST, derived from your Rails routes. [Docs](https://ruact.dev/docs/concepts/navigation)
 - **A CRUD generator** — `rails generate ruact:scaffold Post title:string body:text` delegates the model, migration and route to Rails' own `resource` generator, then adds the ruact layer. Plain semantic HTML by default; `--shadcn` opts into the Tailwind/shadcn path. It does not run migrations — `rails db:migrate` is still yours. [Docs](https://ruact.dev/docs/api/scaffold)
-- **`bin/rails ruact:doctor`** — nine checks over the manifest, Vite, the layout, the client-component CSS and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
+- **`bin/rails ruact:doctor`** — checks the manifest, Vite, the layout, the client-component CSS and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
 - **One runtime dependency** — `nokogiri`. Rails itself is not a declared dependency of this gem.
 
 ## AI tools and coding agents

data/lib/generators/ruact/install/templates/AGENTS.md.tt

@@ -1,8 +1,7 @@
 <!-- ruact:begin -->
 <!-- Managed by `rails generate ruact:install`. Re-run it with --force after a
-     gem upgrade to refresh ONLY this marked section; everything you write
-     outside the markers is preserved. Kept in sync manually with the online
-     copy at https://ruact.dev/llms.txt -->
+     gem upgrade to refresh ONLY this marked section; everything outside the
+     markers is preserved. Kept in sync by hand with https://ruact.dev/llms.txt -->
 
 # ruact — conventions for coding agents
 
@@ -61,10 +60,9 @@ import { categories, useQuery } from "@/.ruact/server-functions";
 const { data, loading, error } = useQuery(categories);
 ```
 
-Query params come from the method's keyword arguments and accept ONLY
-`string | number | boolean | null` (arrays/objects are rejected). Queries run
-the host controller's callback chain (authentication etc.) before the query
-object is instantiated.
+Query params are the method's keyword arguments, ONLY `string | number |
+boolean | null` (arrays/objects are rejected). Queries run the host
+controller's callback chain (authentication etc.) before the query object.
 
 ## Ground truth — read the generated file
 
@@ -79,13 +77,16 @@ READ IT instead of simulating the name generation. Regenerate after routes/queri
 1. **Every component tag closes.** `<Badge label={@x} />` has no children;
    `<Card title={@t}>...</Card>` passes the ERB between its tags to the
    component as `children`. An unclosed or stray tag fails LOUDLY with a
-   `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too.
+   `PreprocessorError` naming file:line. `<Suspense fallback="...">` pairs too;
+   under `ruact_streaming` its content runs AFTER the page is sent: status,
+   redirect, cookies, session, flash, `content_for` and locale/tenant/DB-role
+   scopes belong in the controller (`around_action`), not inside it or in a
+   middleware; a `cache` block goes inside a `<Suspense>`, never around one.
    In a loop of items holding components, give each item a `data-react-key`
    (the record's id): React matches them by position otherwise, silently.
 2. **`{}` props are Ruby, not JavaScript.** `<Badge label={@post.title} />`
-   evaluates `@post.title` as a Ruby expression in the ERB. No JS ternaries,
-   no `{...spread}`. A quoted value (`title="Hi"`) is a
-   plain string and a bare attribute is `true`, as in JSX.
+   evaluates `@post.title` as a Ruby expression: no JS ternaries, no `{...spread}`.
+   A quoted value (`title="Hi"`) is a plain string; a bare attribute is `true`.
 3. **One action, two response shapes.** A `Ruact::Server` non-GET action
    answers JSON — its instance variables, or `204`, or `{"$redirect": path}` —
    when the request's `Accept` header is exactly `application/json`, which is
@@ -144,8 +145,7 @@ duration, or a deliberate `expires_in: nil` for a non-expiring token.
 - `bin/rails ruact:routes -- --json` — the accessor/route table (each accessor's
   name, kind, verb, path, params) as JSON, from the same route table codegen
   reads; bare `ruact:routes` prints a compact human table.
-- Both `--json` outputs are EXPERIMENTAL — the shape may change; gate on their
-  `schema_version` field (currently `0`), do not treat it as a stable contract.
+- Both `--json` outputs are EXPERIMENTAL: gate on `schema_version` (now `0`).
 - `bin/rails ruact:server_functions:generate` — regenerates the TS module;
   exits 1 on a naming collision or an invalid name.
 - `bin/dev` — boots Rails AND Vite (both required: Vite serves the client components).

data/lib/generators/ruact/install/templates/initializer.rb.tt

@@ -41,7 +41,10 @@ Ruact.configure do |config|
   # Recommended: true in production to prevent accidental attribute exposure.
   # config.strict_serialization = Rails.env.production?
 
-  # Timeout in seconds for deferred Suspense chunks. Default: 5.0.
+  # How long a <Suspense>'s content may run, in seconds of real time, in an
+  # action declared with `ruact_streaming`; past it, its boundary shows an
+  # error and the next one runs. A backstop: it does not stop a query the
+  # database is running — the database's statement timeout does. Default: 5.0.
   # config.suspense_timeout = 5.0
 
   # Base URL of the Vite dev server. Default: "http://localhost:5173".

data/lib/ruact/cached_blocks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 19-2 — a render that renders `<Suspense>` content in place writes no
+  # block marker: one in its HTML came out of a `cache` block a render that
+  # streamed wrote. Its boundary gets an error row ({Flight::Renderer}); this
+  # says so on the server, as {DeferredRender} does for a render that streams.
+  #
+  # Internal API: not part of the public compatibility contract.
+  module CachedBlocks
+    # Only the attribute as written in a tag (`="`): text that mentions it is
+    # escaped.
+    MARKER = %( #{Markers::BLOCK_ATTR}=").freeze
+    private_constant :MARKER
+
+    # Logs and reports a block marker in +html+.
+    #
+    # @param html [String]
+    # @param logger [Logger, nil]
+    # @return [void]
+    def self.report(html, logger)
+      return unless html.include?(MARKER)
+
+      error = Ruact::Error.new(Flight::DeferredContent::STALE)
+      logger&.error("[ruact] #{error.message}")
+      Rails.error.report(error, handled: true, severity: :error, source: "ruact.suspense") if
+        defined?(Rails) && Rails.respond_to?(:error)
+    end
+  end
+end

data/lib/ruact/configuration.rb

@@ -38,7 +38,12 @@ module Ruact
     #     raise Ruact::SerializationError. Defaults to false in development, true in production.
     #
     # @!attribute [r] suspense_timeout
-    #   @return [Float] Seconds before a deferred Suspense chunk times out. Default: 5.0.
+    #   @return [Float] Seconds of real time a `<Suspense>`'s content may run in an
+    #     action that streams (`ruact_streaming`) before its boundary gets the
+    #     timeout error and the next one runs; an explicit `delay` counts inside
+    #     it. A backstop, not a limit on the database: a query the driver is
+    #     running keeps running (measured with PostgreSQL in Story 19-1) — the
+    #     database's statement timeout is what stops it. Default: 5.0.
     #
     # @!attribute [r] vite_dev_server
     #   @return [String] Base URL of the Vite dev server. Default: "http://localhost:5173".

data/lib/ruact/controller/delivery.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "document_rendering"
+
+module Ruact
+  module Controller
+    # How a rendered ruact page reaches the client: as a Flight body, or as an
+    # HTML document carrying the payload ({DocumentRendering}) — all at once,
+    # or, in an action that streams ({Streaming}), the shell first and each
+    # `<Suspense>`'s rows as its content is rendered. Also the Flight body of a
+    # redirect the client router follows itself.
+    #
+    # Everything that decides what a ruact response looks like on the wire, its
+    # headers included, is here.
+    module Delivery
+      extend ActiveSupport::Concern
+
+      include DocumentRendering
+
+      # The headers of a Flight body written row by row: not stored, and no
+      # buffering by a proxy that honours `X-Accel-Buffering` (nginx).
+      # `no-store`, not `no-cache` (Story 19-2): a response the browser may
+      # store holds its cache entry while it streams, and Chrome then holds a
+      # second request for the same URL — a `revalidate()`, the same link
+      # clicked again — until the first one ends.
+      STREAM_HEADERS = {
+        "Content-Type" => "#{RequestKind::FLIGHT_MIME}; charset=utf-8",
+        "Cache-Control" => "no-store",
+        "X-Accel-Buffering" => "no"
+      }.freeze
+
+      # The same, for a document written in parts — `no-cache`: `no-store`
+      # would keep the page out of the browser's back/forward cache, and the
+      # router stops a document it leaves while it still loads.
+      DOCUMENT_STREAM_HEADERS = {
+        "Content-Type" => "text/html; charset=utf-8",
+        "Cache-Control" => "no-cache",
+        "X-Accel-Buffering" => "no"
+      }.freeze
+
+      # What Rails itself writes once the response has started, on the request's
+      # thread, while the first block may be running: the session cookie and the
+      # session's own keys (`commit_session`, `commit_flash`, and the CSRF token
+      # Rails stores at commit since 7.1), and the headers a middleware adds on
+      # the way out. Not the block's writes.
+      RAILS_WRITES = {
+        "header" => %w[set-cookie server-timing content-security-policy
+                       content-security-policy-report-only x-runtime].freeze,
+        "session" => %w[session_id flash _csrf_token].freeze
+      }.freeze
+
+      # Where a streamed document is cut: the rows of each `<Suspense>` are
+      # pushed before it, as they are ready.
+      BODY_CLOSE = "</body>"
+
+      # Story 19-2 — written around the pushed rows of a streamed document, so
+      # the client router knows a document still loading has rows to come: it
+      # stops such a document when it leaves the page, and only such a one (a
+      # document that is still being parsed, its rows all in, is left alone).
+      STREAMING_OPEN = "(self.__FLIGHT_DATA=self.__FLIGHT_DATA||[]).streaming=true"
+      STREAMING_DONE = "self.__FLIGHT_DATA.streaming=false"
+
+      private
+
+      # Build the wire output and write it to the response. Nothing is written
+      # until the page (or, when it streams, its shell) has rendered without
+      # raising — that way a missing-component error still surfaces as a
+      # normal 500 response.
+      def emit_ruact_response(pipeline, html, render_context, streaming:)
+        # Story 15.5 (FR109) — record which page shape ruact rendered so the
+        # `Ruact::Server` dev log (`__ruact_log_response_shape!`) can name it and,
+        # crucially, stay SILENT on a plain Rails render (this flag is never set
+        # there). `@__`-prefixed → never leaks into `view_assigns`.
+        @__ruact_negotiated_page = ruact_request? ? :flight : :html_shell
+        if streaming
+          return __ruact_stream_page(DeferredRender.new(html, render_context, pipeline,
+                                                        guard: __ruact_late_write_guard))
+        end
+
+        input = { html: html, render_context: render_context }
+        if ruact_request?
+          render plain: pipeline.render(input, mode: :string), content_type: RequestKind::FLIGHT_MIME
+        else
+          render_ruact_document(pipeline.render(input, mode: :string))
+        end
+      end
+
+      # Story 19-1 — the shell, then each boundary as its block is rendered.
+      # A page that left nothing for later responds as one that does not stream.
+      def __ruact_stream_page(run)
+        shell = run.shell
+        unless run.pending?
+          return render(plain: shell, content_type: RequestKind::FLIGHT_MIME) if ruact_request?
+
+          return render_ruact_document(shell)
+        end
+        return __ruact_stream(run, STREAM_HEADERS, shell) if ruact_request?
+
+        document = ruact_document_html(shell)
+        cut = document.rindex(BODY_CLOSE) || document.length
+        open = "<script#{__ruact_nonce_attr}>"
+        __ruact_stream(run, DOCUMENT_STREAM_HEADERS, "#{document[0...cut]}#{open}#{STREAMING_OPEN}</script>",
+                       "#{open}#{STREAMING_DONE}</script>#{document[cut..]}") { |rows| __ruact_flight_push(rows, open) }
+      end
+
+      # Writes +first+, then each boundary's rows (through the block, when given),
+      # then +last+. No exception leaves here with the stream open: Live would
+      # append Rails' `/500.html` script to a page already on screen. What was
+      # not sent stays pending, for the browser's transport to label.
+      def __ruact_stream(run, headers, first, last = nil)
+        headers.each { |name, value| response.headers[name] = value }
+        Streaming.keep_unbuffered(response.headers)
+        @__ruact_streamed = true
+        stream = response.stream
+        begin
+          stream.write(first)
+          while run.pending?
+            if __ruact_client_gone?
+              __ruact_log_cut_short(run, "the client left")
+              break
+            end
+            rows = run.next_rows
+            stream.write(block_given? ? yield(rows) : rows)
+          end
+          stream.write(last) if last
+        rescue ActionController::Live::ClientDisconnected, IOError, SystemCallError => e
+          __ruact_log_cut_short(run, "the client left (#{e.class})")
+        rescue StandardError => e
+          __ruact_report_stream_error(e, run)
+        ensure
+          @__ruact_streamed_state = __ruact_response_state if Flight::Renderer.development_default
+          stream.close
+        end
+      end
+
+      # One boundary's rows, as the script a streamed document carries them in:
+      # pushed onto the queue the bootstrap reads. Written as
+      # {InlineScript.string_literal} writes it — no byte of the payload can
+      # close the `<script>`. +open+ carries the request's CSP nonce, if any.
+      def __ruact_flight_push(rows, open = "<script>")
+        "#{open}(self.__FLIGHT_DATA=self.__FLIGHT_DATA||[]).push(#{InlineScript.string_literal(rows)})</script>"
+      end
+
+      # Story 19-1 (D4) — has the client closed its end? Asked before each
+      # block: the server does not notice on its own, and a write to a client
+      # that left does not fail until the one after it (measured in 19-0).
+      # Puma hands the socket over as `puma.socket`; with another server, or
+      # none, nothing is asked.
+      def __ruact_client_gone?
+        socket = request.env["puma.socket"]
+        return false if socket.nil? || !socket.respond_to?(:wait_readable) || !socket.wait_readable(0)
+
+        # The end of the connection reads as nil or as "", depending on how the
+        # peer closed it.
+        socket.recv_nonblock(1, Socket::MSG_PEEK).to_s.empty?
+      rescue IO::WaitReadable
+        false
+      rescue SystemCallError, IOError
+        true
+      end
+
+      def __ruact_log_cut_short(run, why)
+        left = run.pending_count
+        logger&.info("[ruact] #{self.class.name}##{action_name}: #{why}; " \
+                     "#{left} <Suspense> #{left == 1 ? 'boundary was' : 'boundaries were'} not rendered")
+      end
+
+      # An exception once the response has started, outside a block (the end of
+      # the layout, the serializer): reported and logged, and the stream closed.
+      def __ruact_report_stream_error(error, run)
+        logger&.error("[ruact] #{self.class.name}##{action_name} raised while streaming, after the " \
+                      "response started: #{error.class}: #{error.message}. The response was closed; " \
+                      "#{run.pending_count} <Suspense> boundaries were not rendered.")
+        Rails.error.report(error, handled: true, severity: :error, source: "ruact.stream") if Rails.respond_to?(:error)
+      end
+
+      # Story 19-1 (D5) — in development, a block that writes a cookie, the
+      # session, the flash or a header is an error of that block: the response
+      # started before the block ran, so the write would be lost.
+      def __ruact_late_write_guard
+        return nil unless Flight::Renderer.development_default
+
+        lambda do |&evaluate|
+          before = __ruact_response_state
+          html = evaluate.call
+          changed = __ruact_state_changes(before, __ruact_response_state)
+          raise Ruact::Error, __ruact_late_write_message(changed, "a <Suspense>") unless changed.empty?
+
+          html
+        end
+      end
+
+      # Story 19-1 (D5) — the same, for what runs after the page was sent (an
+      # `after_action`): it cannot be a block's error any more, so it is logged.
+      def __ruact_check_writes_after_stream
+        before = @__ruact_streamed_state
+        return if before.nil?
+
+        @__ruact_streamed_state = nil
+        changed = __ruact_state_changes(before, __ruact_response_state)
+        return if changed.empty?
+
+        logger&.error("[ruact] #{self.class.name}##{action_name}: " \
+                      "#{__ruact_late_write_message(changed, 'code after the page was sent')}")
+      end
+
+      def __ruact_late_write_message(changed, where)
+        "#{where} wrote #{changed.join(', ')} after the response started, so the browser never gets it. " \
+          "Status, headers, cookies, the session and the flash are set in the controller, before the page " \
+          "renders."
+      end
+
+      # What a response can no longer carry once it has started. Each part is
+      # read on its own: a controller without a session has no session to read.
+      # Reading does not load what is not loaded — the session, the flash — so
+      # development behaves as production does.
+      def __ruact_response_state
+        {
+          "header" => __ruact_read_state("header") { response.headers.to_h.transform_keys(&:downcase) },
+          "cookie" => __ruact_read_state("cookie") { request.cookie_jar.to_hash.except(__ruact_session_cookie) },
+          "session" => __ruact_read_state("session") { session.loaded? ? session.to_hash : {} },
+          "flash" => __ruact_read_state("flash") { request.flash_hash&.to_hash || {} }
+        }
+      end
+
+      def __ruact_read_state(kind)
+        yield.except(*RAILS_WRITES.fetch(kind, []))
+      rescue StandardError
+        nil
+      end
+
+      # The session store's cookie: the key the app configured, or the one the
+      # store falls back to without one. Not `request.session_options[:key]`:
+      # Rack takes the key out of the options it keeps.
+      def __ruact_session_cookie
+        key = Rails.application.config.session_options[:key]
+        key ||= request.session.instance_variable_get(:@by).try(:key)
+        (key || "_session_id").to_s
+      rescue StandardError
+        "_session_id"
+      end
+
+      # `["the cookie theme", "the header X-Trace"]` — what differs.
+      def __ruact_state_changes(before, after)
+        before.flat_map do |kind, was|
+          now = after[kind]
+          next [] if was.nil? || now.nil? || was == now
+
+          (was.keys | now.keys).reject { |key| was[key] == now[key] }.map { |key| "the #{kind} #{key}" }
+        end
+      end
+
+      # The Flight body of a redirect: one row the client router reads and
+      # follows (`redirectType: "push"`), instead of a 302 the browser would.
+      def __ruact_render_flight_redirect(url)
+        render plain: "0:#{JSON.generate({ 'redirectUrl' => url, 'redirectType' => 'push' })}\n",
+               content_type: RequestKind::FLIGHT_MIME
+      end
+    end
+  end
+end

data/lib/ruact/controller/document_rendering.rb

@@ -59,6 +59,13 @@ module Ruact
       # committed: that is a configuration error, raised in development/test and
       # logged-and-degraded in production rather than served to real traffic.
       def render_ruact_document(payload)
+        render html: ruact_document_html(payload).html_safe, layout: false
+      end
+
+      # The document {#render_ruact_document} sends, as a String — what a page
+      # that streams sends up to its last `</body>` ({Delivery}). Every check
+      # above runs here, before a byte of the response is written.
+      def ruact_document_html(payload)
         __ruact_warn_turbo_form_submission if __ruact_local_env?
         # Set for EVERY branch, the shell included: besides carrying the payload
         # to a layout's zero-argument `ruact_js_assets`, it is how
@@ -67,11 +74,11 @@ module Ruact
         # through the same layout never inherits it.
         @ruact_flight_payload = payload
         layout = Ruact.config.layout
-        return render html: ruact_html_shell(payload).html_safe, layout: false if layout == false
+        return ruact_html_shell(payload) if layout == false
 
         unless ruact_layout_resolvable?(layout)
           __ruact_handle_unready_layout(layout, :missing)
-          return render html: ruact_html_shell(payload).html_safe, layout: false
+          return ruact_html_shell(payload)
         end
 
         # `@ruact_flight_payload` is copied to the view by Rails' `view_assigns`
@@ -79,13 +86,10 @@ module Ruact
         # that is how the layout's zero-argument `ruact_js_assets` reaches THIS
         # render's Flight payload.
         document = render_to_string(html: "".html_safe, layout: layout)
+        return document if ruact_document_mountable?(document)
 
-        if ruact_document_mountable?(document)
-          render html: document.html_safe, layout: false
-        else
-          __ruact_handle_unready_layout(layout, :unwired)
-          render html: ruact_html_shell(payload).html_safe, layout: false
-        end
+        __ruact_handle_unready_layout(layout, :unwired)
+        ruact_html_shell(payload)
       ensure
         remove_instance_variable(:@ruact_flight_payload) if instance_variable_defined?(:@ruact_flight_payload)
       end
@@ -219,10 +223,9 @@ module Ruact
       def ruact_html_shell(flight_payload)
         # Story 14.2 — the JS asset block (entry `<script>` tags + `__FLIGHT_DATA`)
         # is delegated to the single `Ruact::ViewHelper#ruact_js_assets`
-        # implementation. The bootstrap entry script is a deferred ES module, so it
-        # runs after the inline `__FLIGHT_DATA` classic script has populated the
-        # queue regardless of source order — emitting the whole block in `<body>`
-        # is correct.
+        # implementation, which writes the inline `__FLIGHT_DATA` script before
+        # the entry `<script>`: the entry is `async` (Story 19-1) and runs as
+        # soon as it loads, so the queue has to be there first.
         <<~HTML
           <!DOCTYPE html>
           <html lang="en">