studio-engine 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31ed2941026e5bf0114872ba16dd7a9b94b1a472d5407ff82ec604ba2e659962
-  data.tar.gz: 1fda4b1328315323b8afcee644a68acc8678e756762a88b289ea10e0fc46a6cf
+  metadata.gz: 20b0e58f17421ce741452b329000bc657f0dba0304198d7dc1fb59cb448bfc6d
+  data.tar.gz: d4446a5bad4b0b744e54ad7d4f275cf77455a68f2cf3289d6d9c472ca1f3c548
 SHA512:
-  metadata.gz: 6431e1dafbd0a614e1c0a6abe25004ab3888a3d1e7c263ab97d7883e10bcedde60da03f16c98b262d9926173749343b00c33d6a5580db9fc299c8b1b355a9665
-  data.tar.gz: 7513d2735c2535ed520530eab4adc0b1ce60de617488e4fa934e43beb31ef330e7e49c8837e3310aa92467559dbabf714fab43b81d86a0d52cebce8f85674e35
+  metadata.gz: b15b1f884815e8afbad3d9aa181589230193942970d62457075d08c47521c967a005025560e665b436ceb8a6c78f425688430f122cad9a7f21e8a4432bd4ca22
+  data.tar.gz: 5a6c6817018309298bb3a8eb686f61d7e93d9718d5b8ce5b5a8e642efc82f99695d6bf0c4f23b9421fa8c65481722e9164934c7cbe47f254e3abb482d7ea42ed

data/CHANGELOG.md

@@ -4,6 +4,27 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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/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.10.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

@@ -28,4 +28,9 @@ Gem::Specification.new do |spec|
   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.10.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
@@ -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