studio-engine 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31ed2941026e5bf0114872ba16dd7a9b94b1a472d5407ff82ec604ba2e659962
-  data.tar.gz: 1fda4b1328315323b8afcee644a68acc8678e756762a88b289ea10e0fc46a6cf
+  metadata.gz: 4d4a633071c04010dadfb92d3beef1a7e075a90c94e55ab5761a03a114f48f40
+  data.tar.gz: fc17d48b30cfcbde79e4c3bdc5bf618789a7765dbc359a134b28800cc772429e
 SHA512:
-  metadata.gz: 6431e1dafbd0a614e1c0a6abe25004ab3888a3d1e7c263ab97d7883e10bcedde60da03f16c98b262d9926173749343b00c33d6a5580db9fc299c8b1b355a9665
-  data.tar.gz: 7513d2735c2535ed520530eab4adc0b1ce60de617488e4fa934e43beb31ef330e7e49c8837e3310aa92467559dbabf714fab43b81d86a0d52cebce8f85674e35
+  metadata.gz: e32e14a996202c61dd230a4084927539618341c0343bbafad1066280394da6d84976222a5621000157d6e84df83452c6a5f234f36ca11e18c408e340757a0b49
+  data.tar.gz: 8592453e2efdbad7c3df75bfb13274a6abfa080f9de9e6188a70d90e935d2dfa1446c788f15d55eab467207bcfa9cef129bf9b0abf3fbb001e846a11a6c31f3f

data/CHANGELOG.md

@@ -4,6 +4,53 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.11.0 — 2026-06-24
+
+### Changed
+- **Rails 8.1 support** — widened the gemspec `rails` bound from
+  `">= 7.0", "< 8.0"` to `">= 7.2", "< 8.2"`, so consuming apps can migrate to
+  Rails 8.1 independently (the engine no longer pins the ecosystem to Rails 7).
+  This release is the gate for the McRitchie Rails 8.1 train — `mcritchie-studio`
+  and `turf-monster` can bundle Rails 8.1 only once this version is published.
+  The lower bound moves to 7.2 (the oldest Rails the apps actually run) since
+  Rails 8 requires Ruby >= 3.2 and the ecosystem is already on Ruby 3.3.11.
+
+### Added
+- **`test/dummy` Rails app + `test/integration/engine_rails_8_1_boot_test.rb`** —
+  boots the engine inside a real Rails app and exercises its Rails-version-
+  sensitive surfaces (the Railtie registration, Zeitwerk autoload wiring, the
+  `Studio.routes` DSL, and the `ErrorLog` / `ThemeSetting` / `Sluggable`
+  ActiveRecord models). Re-run this against any new Rails line before widening
+  the bound again. The engine's full unit suite + this boot test are green
+  against Rails 8.1.3 (ActiveSupport/ActiveRecord 8.1, Zeitwerk 2.8, minitest 6).
+
+### Fixed
+- `bin/release-check` now prefers the `ruby@3.3` toolchain (was pinned to the
+  retired `ruby@3.1`, which cannot resolve Rails 8.1) and runs the full test
+  list, including the new Rails 8.1 boot test and the previously-omitted
+  `link_token` / sticky-header / admin-models-table tests.
+
+## 0.10.0 — 2026-06-24
+
+### Added
+- **Shared websocket / Redis primitive** (`docs/CABLE.md`) — one place for the
+  setup every host app's realtime needs, extracted after a SEV-1 (a host app
+  shipped an ActionCable channel with no `redis` gem and no TLS cable config; the
+  broadcast raised `Gem::LoadError` — a `ScriptError`, not a `StandardError` — which
+  escaped a `rescue StandardError` and 500'd every task write).
+  - **`redis` is now an engine dependency** (plus `turbo-rails`), so a consuming app
+    can never hit that `Gem::LoadError` again.
+  - **`Studio::Redis`** — the single source of Redis connection truth for `cable.yml`,
+    the `cache_store`, and Sidekiq: `.url`, `.tls?`, and `.options(**extra)`, which
+    auto-applies `ssl_params: { verify_mode: VERIFY_NONE }` for Heroku's `rediss://`
+    self-signed TLS (the gotcha that silently drops every broadcast).
+  - **`Studio::Cable.safe_broadcast { … }`** — best-effort broadcast guard that
+    catches `StandardError` **and** `ScriptError`, so a cable failure never breaks
+    the caller (the exact hole that caused the SEV-1).
+  - **`Studio::Broadcastable`** — model concern with safe Turbo-Streams wrappers
+    (`safe_broadcast_replace_to`, `_append_to`, `_prepend_to`, `_update_to`,
+    `_remove_to`) every app should broadcast through.
+
 ## 0.9.0 — 2026-06-23
 
 ### Added

data/Gemfile

@@ -2,17 +2,19 @@ source "https://rubygems.org"
 
 gemspec
 
-# nokogiri 1.18.10 has 3 CVEs (1 HIGH regex-backtracking + 2 MEDIUM
-# in XSLT / xmlC14NExecute). Fix is `>= 1.19.3` but nokogiri 1.19.x
-# requires Ruby 3.2+. The ecosystem currently runs on Ruby 3.1.7;
-# bumping Ruby is a separate effort (across both Rails apps).
-#
-# **Important**: this gem does NOT declare nokogiri as a runtime
-# dependency in its gemspec — nokogiri comes into the consuming
-# Rails app via Rails itself. Consumers running Rails on a Ruby
-# version that supports nokogiri 1.19.x will resolve it. The
-# studio-engine gem's own Gemfile.lock (this repo's dev env) is the
-# only place still on 1.18.10.
-#
-# Tracked in SECURITY-AUDIT-2026-05-17.md. When the ecosystem bumps
-# to Ruby 3.2+, add: gem "nokogiri", ">= 1.19.3", group: :development
+# nokogiri: historically pinned to 1.18.10 here while the ecosystem was on
+# Ruby 3.1.7 (nokogiri >= 1.19.x requires Ruby 3.2+). The ecosystem is now on
+# Ruby 3.3.11, so a plain `bundle update` resolves the patched nokogiri
+# (>= 1.19.3, the line that fixed 3 CVEs: 1 HIGH regex-backtracking + 2 MEDIUM
+# XSLT / xmlC14NExecute). This gem still does NOT declare nokogiri as a runtime
+# dependency — it arrives via Rails in the consuming app. Tracked in
+# SECURITY-AUDIT-2026-05-17.md.
+
+group :development, :test do
+  # SQLite drives the test/dummy Rails app's in-memory database (see
+  # test/integration/engine_rails_8_1_boot_test.rb), which boots the engine
+  # against a real Rails app so we catch Rails-version incompatibilities in the
+  # engine's ActiveRecord/Railtie surfaces. Not a runtime dependency — the
+  # consuming apps bring their own database adapter. Rails 8.1 needs sqlite3 ~> 2.1.
+  gem "sqlite3", ">= 2.1"
+end

data/app/models/concerns/studio/broadcastable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Studio
+  # Mixin for ActiveRecord models that broadcast Turbo Streams. It wraps
+  # turbo-rails' broadcast_*_to methods in Studio::Cable.safe_broadcast, so a cable
+  # failure (a Redis hiccup, a missing/misconfigured adapter) can NEVER break the
+  # model save / after_commit that triggered the broadcast — the SEV-1 guard, in
+  # one place. The host model already has the raw broadcast_*_to methods (turbo-rails
+  # includes Turbo::Broadcastable into ActiveRecord::Base); these are the SAFE
+  # variants every app should broadcast through.
+  #
+  #   class Task < ApplicationRecord
+  #     include Studio::Broadcastable
+  #     after_create_commit { safe_broadcast_replace_to [:board], target: "card_#{id}",
+  #                                                       partial: "tasks/card", locals: { task: self } }
+  #   end
+  module Broadcastable
+    extend ActiveSupport::Concern
+
+    def safe_broadcast_replace_to(*args, **kwargs, &block)
+      Studio::Cable.safe_broadcast { broadcast_replace_to(*args, **kwargs, &block) }
+    end
+
+    def safe_broadcast_update_to(*args, **kwargs, &block)
+      Studio::Cable.safe_broadcast { broadcast_update_to(*args, **kwargs, &block) }
+    end
+
+    def safe_broadcast_append_to(*args, **kwargs, &block)
+      Studio::Cable.safe_broadcast { broadcast_append_to(*args, **kwargs, &block) }
+    end
+
+    def safe_broadcast_prepend_to(*args, **kwargs, &block)
+      Studio::Cable.safe_broadcast { broadcast_prepend_to(*args, **kwargs, &block) }
+    end
+
+    def safe_broadcast_remove_to(*args, **kwargs, &block)
+      Studio::Cable.safe_broadcast { broadcast_remove_to(*args, **kwargs, &block) }
+    end
+  end
+end

data/lib/studio/cable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "redis"
+
+module Studio
+  # Shared ActionCable / Turbo-Streams helpers for host apps.
+  module Cable
+    # Run a broadcast best-effort: a cable failure must NEVER break the caller (the
+    # model save / task write that triggered it). ScriptError is caught ON PURPOSE —
+    # a missing or misconfigured cable adapter raises Gem::LoadError, which is a
+    # ScriptError, NOT a StandardError. A plain `rescue StandardError` let exactly
+    # that escape an after_commit and 500 every task write in production (the SEV-1
+    # this primitive exists to prevent). Failures are captured to ErrorLog when the
+    # host defines it, else logged. Returns nil on failure.
+    #
+    # The never-raise guarantee is ABSOLUTE: even logging the failure must not break
+    # the caller. ErrorLog.capture! writes to the DB and can itself raise (e.g.
+    # ActiveRecord::NoDatabaseError when the DB is down), so the logging is wrapped
+    # in its own rescue — the guard cannot be defeated by its own error path.
+    def self.safe_broadcast
+      yield
+    rescue StandardError, ScriptError => e
+      begin
+        if defined?(ErrorLog) && ErrorLog.respond_to?(:capture!)
+          ErrorLog.capture!(e)
+        elsif defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.warn("[studio-cable] broadcast failed (non-fatal): #{e.class}: #{e.message}")
+        end
+      rescue StandardError, ScriptError
+        nil # logging is best-effort too — the never-raise guarantee is absolute
+      end
+      nil
+    end
+  end
+end

data/lib/studio/redis.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Studio
+  # Single source of Redis connection truth for EVERY Redis client in a host app —
+  # ActionCable (config/cable.yml), the Rails cache_store, and Sidekiq. It bakes in
+  # the Heroku gotcha so no app re-hits it:
+  #
+  #   Heroku Redis serves rediss:// (TLS) with a SELF-SIGNED cert. redis-client
+  #   verifies peer certs by default, so the connection is silently REJECTED — and
+  #   because ActionCable's pubsub failure is silent (the /cable socket still
+  #   upgrades to 101), broadcasts simply never reach subscribers; the cache no-ops.
+  #   The fix is ssl_params verify_mode VERIFY_NONE, applied automatically here for
+  #   any rediss:// URL.
+  #
+  # Usage:
+  #   cable.yml   ->  Studio::Redis.options                     (url + ssl_params)
+  #   cache_store ->  Studio::Redis.options(namespace: "x", expires_in: 90.minutes)
+  #   sidekiq     ->  Studio::Redis.options
+  module Redis
+    # The Redis URL from the environment, with a local-dev fallback.
+    def self.url(default = "redis://localhost:6379/1")
+      ENV.fetch("REDIS_URL", default)
+    end
+
+    # True when the endpoint is TLS (Heroku Redis), i.e. a rediss:// URL.
+    def self.tls?(redis_url = url)
+      redis_url.to_s.start_with?("rediss://")
+    end
+
+    # Connection options for a Redis client: the url, plus — for a TLS endpoint —
+    # the self-signed-cert handling Heroku requires. Caller extras (namespace,
+    # reconnect_attempts, error_handler, …) merge through untouched.
+    def self.options(redis_url: url, **extra)
+      opts = { url: redis_url }.merge(extra)
+      opts[:ssl_params] = { verify_mode: OpenSSL::SSL::VERIFY_NONE } if tls?(redis_url)
+      opts
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.9.0"
+  VERSION = "0.11.0"
 end

data/lib/studio.rb

@@ -10,6 +10,8 @@ require "studio/link_token"
 require "studio/email"
 require "studio/email_smoke"
 require "studio/mail_transport"
+require "studio/redis"
+require "studio/cable"
 
 module Studio
   mattr_accessor :app_name,            default: "Studio"

data/studio-engine.gemspec

@@ -21,11 +21,16 @@ Gem::Specification.new do |spec|
   spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "db/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rails", ">= 7.0", "< 8.0"
+  spec.add_dependency "rails", ">= 7.2", "< 8.2"
   spec.add_dependency "tailwindcss-rails", "~> 4.5"
   spec.add_dependency "faker", ">= 2.0", "< 4.0"
   spec.add_dependency "solid_queue", ">= 1.0", "< 2.0"
   spec.add_dependency "aws-sdk-s3", "~> 1.218"
   spec.add_dependency "mini_magick", "~> 5.0"
   spec.add_dependency "resend", "~> 1.1"
+  # Realtime: the redis cable/cache/Sidekiq adapter (Studio::Redis) + Turbo Streams
+  # broadcasting (Studio::Broadcastable). `redis` is the dependency whose ABSENCE
+  # 500'd a host app's task board — declaring it here makes that impossible to repeat.
+  spec.add_dependency "redis", ">= 4.0.1"
+  spec.add_dependency "turbo-rails", ">= 1.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,20 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.2'
 - !ruby/object:Gem::Dependency
   name: tailwindcss-rails
   requirement: !ruby/object:Gem::Requirement
@@ -126,6 +125,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: Studio Engine is a non-isolated Rails engine that ships an opinionated
   authentication + SSO contract, a polymorphic ErrorLog model, a Sluggable concern,
   a 7-role dynamic theme system with CSS-custom-property generation, and an S3-backed
@@ -169,6 +196,7 @@ files:
 - app/mailers/application_mailer.rb
 - app/mailers/user_mailer.rb
 - app/models/concerns/sluggable.rb
+- app/models/concerns/studio/broadcastable.rb
 - app/models/current.rb
 - app/models/error_log.rb
 - app/models/image_cache.rb
@@ -239,6 +267,7 @@ files:
 - db/migrate/20260623130000_create_studio_enumerals.rb
 - lib/studio-engine.rb
 - lib/studio.rb
+- lib/studio/cable.rb
 - lib/studio/color_scale.rb
 - lib/studio/email.rb
 - lib/studio/email_smoke.rb
@@ -246,6 +275,7 @@ files:
 - lib/studio/image_cache.rb
 - lib/studio/link_token.rb
 - lib/studio/mail_transport.rb
+- lib/studio/redis.rb
 - lib/studio/s3.rb
 - lib/studio/theme_resolver.rb
 - lib/studio/ui_primitives.rb
@@ -263,7 +293,6 @@ metadata:
   source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
   bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
   changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -278,8 +307,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching