phlex-reactive 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 913a7629041138c8daf5a4538e694a557f77aeffd137fe7320ce1654efff6aae
+  data.tar.gz: ea6dc93c905242537e00b05d651b98cbea3933a9188e0ae0e10594c87b997504
+SHA512:
+  metadata.gz: 49f1fbd3b2caa40817f91968e4c39658e8fb02a6ab11850ef8a5a5ba7c5f901b4910e7196642b670c61b74060242f550740937b60c71a8fee3af31c5a080f270
+  data.tar.gz: e1fcfbbc3f8c2cb3e22b0929830f7191f59d440b3b1b023a14222547c74fef509face1fdfed4d3a19b3ef13df33f7d4584a1545cc67970cce9ad8de637daf6bf

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `Phlex::Reactive::Streamable` — class methods (`replace`, `update`, `append`,
+  `prepend`, `remove`) and broadcast methods (`broadcast_replace_to`, ...) that
+  render a Phlex component as an auto-targeted Turbo Stream by its stable `id`.
+- `Phlex::Reactive::Component` — declare client-invokable `action`s with a param
+  schema; `reactive_record` (record-backed, GlobalID identity) and
+  `reactive_state` (record-less, signed state); `reactive_attrs` and `on(...)`
+  view helpers.
+- `Phlex::Reactive::ActionsController` — one signed-identity endpoint behind all
+  reactive components; default-deny actions, schema-coerced params,
+  transactional action execution.
+- Generic `reactive` Stimulus controller — per-component request serialization,
+  synchronous token threading, auto field collection; no per-feature controllers.
+- Rails engine — mounts the action endpoint, registers and auto-pins the client
+  runtime for importmap apps.
+
+[Unreleased]: https://github.com/mhenrixon/phlex-reactive/commits/main

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,421 @@
+# phlex-reactive
+
+**Reactive [Phlex](https://www.phlex.fun) components for Rails — Livewire-style
+actions and live cross-tab updates, without writing Stimulus controllers or
+hand-picking Turbo Stream targets.**
+
+```ruby
+class Counter < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  reactive_state :count
+  action :increment
+  action :decrement
+
+  def initialize(count: 0) = @count = count
+  def id = "counter"
+
+  def increment = @count += 1
+  def decrement = @count -= 1
+
+  def view_template
+    div(id:, **reactive_attrs) do
+      button(**on(:decrement)) { "−" }
+      span { @count }
+      button(**on(:increment)) { "+" }
+    end
+  end
+end
+```
+
+That's the whole counter. **No Stimulus controller. No `.turbo_stream.erb`. No
+route. No hand-picked target.** Click `+` and the count updates in place.
+
+---
+
+## Why
+
+Stimulus + Turbo are powerful but tedious. A single interactive widget means a
+Stimulus controller, a `data-*` soup, a `.turbo_stream.erb` view, a controller
+action, and a hand-picked `dom_id` target — repeated for every feature. The
+mental model is "wire everything by hand."
+
+phlex-reactive borrows the **mental model** that makes Livewire and Phoenix
+LiveView pleasant — *a component has state and actions; change state and the UI
+follows* — and implements it the Rails way:
+
+- **Actions are Ruby methods.** Declare `action :increment`; the client calls it.
+- **Re-render is auto-targeted.** A component owns a stable `id`; the response is
+  a `<turbo-stream>` that replaces it. You never pick a target.
+- **The same unit re-renders for clicks AND broadcasts.** A click and a
+  background broadcast both produce "replace the component by its id," so live
+  cross-tab updates are the same mechanism as local interactivity.
+- **State lives in your database, not the browser.** The DOM carries only a
+  *signed identity* (a record's GlobalID), not a snapshot of state — so there's
+  no mass-assignment surface and no re-signing protocol.
+- **One tiny client runtime.** A single generic Stimulus controller, registered
+  once, handles every reactive component. You don't write per-feature JS.
+
+Pair it with [**pgbus**](https://github.com/mhenrixon/pgbus) and your live
+updates become *transactional* (no broadcast for a rolled-back change) and
+*reconnect-safe* (missed messages replay) over Postgres SSE — **no Action Cable,
+no Redis.**
+
+---
+
+## Installation
+
+```ruby
+# Gemfile
+gem "phlex-reactive"
+```
+
+```bash
+bundle install
+```
+
+That's it for **importmap** apps — the engine mounts the action endpoint at
+`/reactive/actions` and auto-pins (and preloads) the client runtime. Register
+the controller eagerly so a click immediately after load is never missed:
+
+```js
+// app/javascript/controllers/index.js
+import { application } from "controllers/application"
+import ReactiveController from "phlex/reactive/reactive_controller"
+application.register("reactive", ReactiveController)
+```
+
+<details>
+<summary>esbuild / webpack / bun</summary>
+
+Import and register it from your controllers entrypoint:
+
+```js
+import { application } from "./application"
+import ReactiveController from "phlex-reactive/reactive_controller"
+application.register("reactive", ReactiveController)
+```
+
+The JS ships at `app/javascript/phlex/reactive/reactive_controller.js` in the
+gem; point your bundler at the gem path or copy it in. See
+[docs/installation.md](docs/installation.md).
+</details>
+
+**Requirements:** Rails 7.1+, Phlex 2 (`phlex-rails`), Turbo 8+ (for morphing),
+and a Phlex `ApplicationComponent` base class. pgbus is optional but recommended
+for broadcasting.
+
+---
+
+## The mental model in one picture
+
+```
+   ┌── click / input ──────────────────────────────────────────┐
+   │                                                            ▼
+[ button(**on(:increment)) ]          POST /reactive/actions { token, act, params }
+   ▲                                                            │
+   │                                          verify signed token (no state trusted)
+   │                                          rebuild component (record from DB)
+   │                                          run the whitelisted action
+   │                                          re-render → <turbo-stream replace id>
+   └──────── Turbo morphs it in ◀───────────────────────────────┘
+
+   ...and for OTHER tabs/users:
+   model change → Component.broadcast_replace_to(stream) → pgbus SSE → same morph
+```
+
+Client actions and server broadcasts **converge on one re-render unit**: the
+component, targeted by its `id`.
+
+---
+
+## Quickstart: a live, cross-tab counter
+
+```ruby
+# app/components/counter.rb  — see the top of this README for the full class
+render Counter.new(count: 0)
+```
+
+Open the page in two tabs, click `+` — done. To make it update across tabs when
+the underlying record changes, use a record-backed component (below).
+
+---
+
+## Two kinds of reactive component
+
+### 1. Record-backed (the common case)
+
+State lives in an ActiveRecord row. The signed identity is the record's
+GlobalID; the server re-finds it on each action. **Always prefer this.**
+
+```ruby
+class Todos::Item < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  reactive_record :todo
+  action :toggle
+  action :rename, params: { title: :string }
+
+  def initialize(todo:) = @todo = todo
+  def id = dom_id(@todo)            # stable per-record DOM id == Turbo target
+
+  def toggle
+    authorize! @todo, :update?      # YOU authorize — the token only proves identity
+    @todo.toggle!(:done)
+  end
+
+  def rename(title:)
+    authorize! @todo, :update?
+    @todo.update!(title:)
+  end
+
+  def view_template
+    li(id:, **reactive_attrs, class: ("done" if @todo.done?)) do
+      button(**on(:toggle)) { @todo.done? ? "✓" : "○" }
+      span { @todo.title }
+    end
+  end
+end
+```
+
+### 2. State-backed (record-less widgets)
+
+No database row — e.g. a counter or a wizard step. The listed instance vars are
+signed into the token. Keep state small and JSON-serializable.
+
+```ruby
+reactive_state :count, :step       # signed; rebuilt on each action
+```
+
+---
+
+## Concrete examples
+
+| Example | What it shows |
+|---|---|
+| [Counter](docs/examples/counter.md) | State-backed, the smallest reactive component |
+| [Cross-tab chat](docs/examples/chat.md) | Record-backed action **+ pgbus broadcast** → live sync across tabs/browsers |
+| [Live todo list](docs/examples/todo_list.md) | Per-row components, add/toggle/rename/delete, broadcast on change |
+| [Inline edit](docs/examples/inline_edit.md) | Show ↔ edit mode toggle, replacing a Stimulus controller + 3 routes |
+| [Notifications / badges](docs/examples/notifications.md) | Pure broadcast (no client action) — a job pushes a re-render |
+
+The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
+[docs/examples/chat.md](docs/examples/chat.md).
+
+---
+
+## API reference
+
+### `Phlex::Reactive::Streamable`
+
+| Method | Use |
+|---|---|
+| `#id` (you implement) | Stable DOM id == Turbo Stream target. Must match the root element's `id`. |
+| `.replace(model = nil, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component |
+| `.update` / `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
+| `.broadcast_replace_to(*streamables, model:)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable) |
+| `.broadcast_append_to(*streamables, target:, model:)` / `_update_` / `_prepend_` / `_remove_` | The broadcast variants |
+| `#to_stream_replace` / `#to_stream_update` | Stream the *already-built* instance (used internally after an action) |
+
+Use in controllers: `render turbo_stream: Counter.replace(counter)`.
+
+### `Phlex::Reactive::Component`
+
+| Macro / helper | Use |
+|---|---|
+| `reactive_record :name` | Record-backed identity (GlobalID). State = the DB. |
+| `reactive_state :a, :b` | State-backed identity (signed instance vars). Record-less only. |
+| `action :name, params: { x: :integer }` | Declare a client-invokable action + its param schema. **Default-deny.** |
+| `reactive_attrs` | Spread onto the root element: marks it reactive + carries the signed token. |
+| `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
+
+Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
+in the schema is dropped before reaching your method.
+
+### Configuration (`config/initializers/phlex_reactive.rb`)
+
+```ruby
+Phlex::Reactive.configure do |c| end if false # (plain accessors below)
+
+# Inherit auth/CSRF/Current from your app on the action endpoint:
+Phlex::Reactive.base_controller_name = "ApplicationController"
+
+# Render your authorization library's error as 403:
+Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]
+# or: [ActionPolicy::Unauthorized]
+
+# Use your ApplicationController to render components (app helpers / Current):
+Phlex::Reactive.renderer = ApplicationController
+
+# Sign tokens with a dedicated key instead of secret_key_base:
+Phlex::Reactive.verifier = ActiveSupport::MessageVerifier.new(ENV["REACTIVE_KEY"])
+
+# Change the endpoint path (default "/reactive/actions"):
+Phlex::Reactive.action_path = "/_r/actions"
+```
+
+If you set a custom `action_path`, expose it to the client:
+
+```erb
+<meta name="phlex-reactive-action-path" content="<%= Phlex::Reactive.action_path %>">
+```
+
+---
+
+## Security
+
+phlex-reactive is built so the easy path is the safe path — but the boundary is
+real, so read this once.
+
+- **State is never trusted from the client.** The DOM holds a `MessageVerifier`-
+  signed identity (`{component, gid}` or `{component, state}`), not raw state. A
+  tampered class, record, or state value fails signature verification → 400.
+- **Actions are default-deny.** Only methods declared with `action :name` are
+  invokable. A public method without `action` is unreachable.
+- **You must authorize.** The signature proves the *token is yours*, not that
+  *this user may act on this record*. Call your authorizer inside the action
+  (`authorize! @todo, :update?`) and register its error in
+  `Phlex::Reactive.authorization_errors`.
+- **Params are schema-coerced.** Only declared params reach your method, each
+  cast to its declared type. No raw mass assignment.
+- **CSRF + auth are the host app's.** The endpoint inherits from your configured
+  `base_controller_name`. Inherit `ApplicationController` to get CSRF and auth —
+  but if you have *public* reactive components, ensure the action path isn't
+  force-redirected to a login page for logged-out users.
+
+See [docs/security.md](docs/security.md) for the threat model and a checklist.
+
+---
+
+## How it beats Stimulus + Turbo (same feature, less code)
+
+A counter, today vs. with phlex-reactive:
+
+<table>
+<tr><th>Stimulus + Turbo</th><th>phlex-reactive</th></tr>
+<tr><td>
+
+```js
+// counter_controller.js
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  static values = { url: String }
+  increment() { this.#post("increment") }
+  decrement() { this.#post("decrement") }
+  #post(op) {
+    fetch(`${this.urlValue}/${op}`, {
+      method: "POST",
+      headers: { "X-CSRF-Token": token() },
+    })
+  }
+}
+```
+```erb
+<%# _counter.html.erb %>
+<div id="<%= dom_id(@counter) %>"
+     data-controller="counter"
+     data-counter-url-value="<%= counter_path(@counter) %>">
+  <button data-action="counter#decrement">−</button>
+  <span><%= @counter.value %></span>
+  <button data-action="counter#increment">+</button>
+</div>
+```
+```ruby
+# routes + controller
+resources :counters do
+  member { post :increment; post :decrement }
+end
+def increment
+  @counter.increment!(:value)
+  render turbo_stream: turbo_stream.replace(
+    dom_id(@counter), partial: "counter",
+    locals: { counter: @counter })
+end
+```
+
+</td><td>
+
+```ruby
+class Counter < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  reactive_record :counter
+  action :increment
+  action :decrement
+
+  def initialize(counter:) = @counter = counter
+  def id = dom_id(@counter)
+
+  def increment = @counter.increment!(:value)
+  def decrement = @counter.decrement!(:value)
+
+  def view_template
+    div(id:, **reactive_attrs) do
+      button(**on(:decrement)) { "−" }
+      span { @counter.value }
+      button(**on(:increment)) { "+" }
+    end
+  end
+end
+```
+
+*One file. No JS. No routes. No partial. No hand-picked target.*
+
+</td></tr>
+</table>
+
+---
+
+## Live updates with pgbus (recommended)
+
+[pgbus](https://github.com/mhenrixon/pgbus) replaces Action Cable's transport
+with Postgres SSE and fixes its reliability gaps. With it installed,
+`broadcast_*_to` and `turbo_stream_from` route over pgbus automatically:
+
+```ruby
+class Message < ApplicationRecord
+  broadcasts_to ->(m) { [m.room, :messages] }, durable: true
+end
+```
+
+- **Transactional**: a broadcast inside a transaction that rolls back never
+  fires — *and* the DB change is undone. No "ghost" UI updates.
+- **Reconnect-safe**: a tab that dropped replays missed messages on reconnect
+  (`Last-Event-ID` + PGMQ archive).
+- **No race on subscribe**: messages broadcast between render and subscribe are
+  replayed, not lost.
+- **No Redis, no Action Cable.**
+
+See [docs/broadcasting.md](docs/broadcasting.md) and
+[docs/transport-pgbus.md](docs/transport-pgbus.md).
+
+---
+
+## Documentation
+
+- [Installation & bundler setups](docs/installation.md)
+- [Mental model & architecture](docs/architecture.md)
+- [Security & threat model](docs/security.md)
+- [Broadcasting & live updates](docs/broadcasting.md)
+- [Transport: pgbus vs Action Cable](docs/transport-pgbus.md)
+- [Testing reactive components](docs/testing.md)
+- Examples: [counter](docs/examples/counter.md) ·
+  [chat](docs/examples/chat.md) · [todo list](docs/examples/todo_list.md) ·
+  [inline edit](docs/examples/inline_edit.md) ·
+  [notifications](docs/examples/notifications.md)
+
+## Credits & prior art
+
+The mental model is stolen, gratefully, from
+[Laravel Livewire](https://livewire.laravel.com) (public method = action) and
+[Phoenix LiveView](https://www.phoenixframework.org) (a component is a re-render
+unit). The transport and reliability come from
+[pgbus](https://github.com/mhenrixon/pgbus). The rendering is all
+[Phlex](https://www.phlex.fun).
+
+## License
+
+[MIT](LICENSE.txt).

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The single endpoint behind every reactive component. The generic
+    # `reactive` Stimulus controller POSTs here with a signed identity token,
+    # an action name, and params. We verify the token, rebuild the component
+    # (re-finding the record from the DB for record-backed components), run the
+    # whitelisted action, and return an auto-targeted Turbo Stream the client
+    # morphs in.
+    #
+    # Customizing in your app:
+    #   * Authentication — by default this inherits from
+    #     Phlex::Reactive.base_controller (ActionController::Base). Set it to
+    #     your ApplicationController to get current_user/Current/CSRF, but make
+    #     sure the action path isn't force-redirected for logged-out users if
+    #     you have public reactive components.
+    #   * Authorization — DO IT IN THE COMPONENT ACTION. The token proves the
+    #     identity is ours, not that this user may act. Raise from the action
+    #     (e.g. authorize!), and configure Phlex::Reactive.authorization_errors
+    #     so it's rendered as 403 here.
+    class ActionsController < Phlex::Reactive.base_controller
+      # Our JSON body uses keys that collide with Rails' reserved routing
+      # params (action/controller) and would be wrapped by wrap_parameters.
+      # Disable wrapping so the body lands flat; the action name travels as
+      # `act` (not `action`, which is reserved and resolves to "create").
+      wrap_parameters false if respond_to?(:wrap_parameters)
+
+      def create
+        payload = verified_payload
+        component_class = resolve_component(payload["c"])
+        action_def = component_class.reactive_action(reactive_action_name)
+
+        return head(:forbidden) unless action_def # default-deny
+
+        component = component_class.from_identity(payload)
+        coerced = coerce_params(action_def.params)
+
+        run_action(component, action_def, coerced)
+
+        render turbo_stream: component.to_stream_replace
+      rescue Phlex::Reactive::InvalidToken
+        head :bad_request
+      rescue ActiveRecord::RecordNotFound
+        head :not_found
+      rescue *authorization_errors
+        head :forbidden
+      end
+
+      private
+
+      # Run the action inside a transaction so transactional broadcasts (pgbus
+      # broadcasts_to ... durable:) defer to after_commit and never fire for a
+      # rolled-back change. Override to add per-request instrumentation.
+      def run_action(component, action_def, coerced)
+        transaction_wrapper do
+          if coerced.any?
+            component.public_send(action_def.name, **coerced)
+          else
+            component.public_send(action_def.name)
+          end
+        end
+      end
+
+      def transaction_wrapper(&block)
+        if defined?(::ActiveRecord::Base)
+          ::ActiveRecord::Base.transaction(&block)
+        else
+          yield
+        end
+      end
+
+      def verified_payload
+        token = params.require(:token)
+        Phlex::Reactive.verify(token) || raise(Phlex::Reactive::InvalidToken)
+      end
+
+      # NB: must NOT be named `action_name` — that's reserved by
+      # ActionController dispatch and overriding it recurses fatally.
+      def reactive_action_name
+        params.require(:act).to_sym
+      end
+
+      # Coerce client params against the action's declared schema. Anything not
+      # in the schema is dropped — no raw mass assignment reaches the component.
+      def coerce_params(schema)
+        return {} if schema.blank?
+
+        raw = params.fetch(:params, {})
+        schema.each_with_object({}) do |(key, type), out|
+          next unless raw.key?(key.to_s)
+
+          out[key.to_sym] = coerce(raw[key.to_s], type)
+        end
+      end
+
+      def coerce(value, type)
+        case type
+        when :integer then value.to_i
+        when :float   then value.to_f
+        when :boolean then ActiveModel::Type::Boolean.new.cast(value)
+        else value.to_s
+        end
+      end
+
+      # Only components that opt into Reactive may be resolved. The signature
+      # already gates this; defense in depth against constant injection.
+      def resolve_component(name)
+        klass = name.to_s.safe_constantize
+        unless klass && klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
+          raise Phlex::Reactive::InvalidToken
+        end
+
+        klass
+      end
+
+      def authorization_errors
+        Phlex::Reactive.authorization_errors
+      end
+    end
+  end
+end