studio-engine 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4e53e209d300c3d55aa211ae40024421ee78734929e1e1db1fd683fa84ffeb0
-  data.tar.gz: 372749c4b18ba3072cd4977ee5e2481d18b870ba14b93e44cca9863f5781c1f6
+  metadata.gz: 20b0e58f17421ce741452b329000bc657f0dba0304198d7dc1fb59cb448bfc6d
+  data.tar.gz: d4446a5bad4b0b744e54ad7d4f275cf77455a68f2cf3289d6d9c472ca1f3c548
 SHA512:
-  metadata.gz: b984b2a14f1065b8c021a87a28ea50f447870361a43b027bb26538d7c360eb5a89c75f3aa8241b0889578af54325421727b6967f8c2a3ec6e3daaf64c36c5295
-  data.tar.gz: bee489407d99c8c5b6d7beda43161b01de9e06014453eb9b80a890b9c913563c2520059c36c18b67d1aaa2dbaddbf933a047878fd4d7abffb90514d8a4ef744d
+  metadata.gz: b15b1f884815e8afbad3d9aa181589230193942970d62457075d08c47521c967a005025560e665b436ceb8a6c78f425688430f122cad9a7f21e8a4432bd4ca22
+  data.tar.gz: 5a6c6817018309298bb3a8eb686f61d7e93d9718d5b8ce5b5a8e642efc82f99695d6bf0c4f23b9421fa8c65481722e9164934c7cbe47f254e3abb482d7ea42ed

data/CHANGELOG.md

@@ -4,6 +4,45 @@ 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
+- **`Studio::Enumeral`** — a shared, DB-backed enumeration table for the whole
+  ecosystem. Every "list of fixed, labeled, colored values" (Pokémon types first;
+  statuses/tiers/roles later) is rows in ONE `studio_enumerals` table, grouped by
+  `category`: a stable machine `key`, a human `label`, a `color` hex, a display
+  `position`, a sparse `rank` (gappy 100/200/… domain ranking — e.g. most-common
+  first — distinct from display order), and `metadata` (jsonb) for
+  category-specific extras. Class helpers `catalog`, `lookup`, `color_map` (one
+  query → `{ key => color }`), `color_for(category, key, fallback:)`, and a
+  metadata-backed `emoji` reader + `emoji_map` (decorative glyphs live in
+  `metadata`, not a column); scopes `ordered` / `by_rank`; `available?` degrades
+  to empty when the table isn't installed. Shipped by the gem like `Studio::Link` /
+  `Studio::EmailDelivery` — reference migration `create_studio_enumerals`
+  installed per app (copy into `db/migrate`). No behavior is attached: a consumer
+  adopts a new category by seeding rows, no code change.
+
 ## 0.8.0 — 2026-06-21
 
 ### 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/app/models/studio/enumeral.rb

@@ -0,0 +1,85 @@
+module Studio
+  # A shared, DB-backed enumeration table for the whole ecosystem. Every "list of
+  # fixed, labeled, colored values" — Pokémon types (its first use), and later
+  # statuses, tiers, roles, … — is just rows in ONE studio_enumerals table,
+  # grouped by `category`. Each row is identity + presentation: a stable machine
+  # `key` ("fire"), a human `label` ("Fire"), a `color` hex ("#EE8130"), and a
+  # `position` for ordering within its category. `metadata` (jsonb) carries any
+  # category-specific extras off the columns.
+  #
+  # Shipped by the gem like Studio::Link / Studio::EmailDelivery: the model lives
+  # here, the table lives in each consumer app (copy the reference migration into
+  # db/migrate). No behavior is attached — it is pure reference data the apps
+  # read, so a consumer adopts a new category by seeding rows, no code change.
+  class Enumeral < ApplicationRecord
+    self.table_name = "studio_enumerals"
+
+    HEX = /\A#(?:\h{3}|\h{6})\z/
+
+    validates :category, presence: true
+    validates :key, presence: true,
+                    uniqueness: { scope: :category, case_sensitive: false }
+    validates :color, format: { with: HEX, message: "must be a hex color like #EE8130" },
+                      allow_blank: true
+
+    scope :in_category, ->(category) { where(category: category.to_s) }
+    scope :ordered,     -> { order(:position, :key) }
+    # By `rank` (a sparse 100/200/… domain ranking), nulls last — for categories
+    # ordered by something other than display position, e.g. most-common-first.
+    scope :by_rank,     -> { order(:rank) }
+
+    class << self
+      # True only when the table is actually migrated in this app's DB, so a
+      # consumer that hasn't installed the migration degrades to "empty" instead
+      # of crashing (mirrors Studio::EmailDelivery.available?).
+      def available?
+        connection.data_source_exists?(table_name)
+      rescue ActiveRecord::ActiveRecordError, NoMethodError
+        false
+      end
+
+      # The ordered list of a category's enumerals — the relation a view iterates
+      # (one query). Returns an empty relation when the table isn't installed yet,
+      # so callers can `.each` safely pre-migration.
+      def catalog(category)
+        return none unless available?
+
+        in_category(category).ordered
+      end
+
+      # The single enumeral for (category, key), or nil.
+      def lookup(category, key)
+        return nil unless available?
+
+        in_category(category).find_by(key: key.to_s)
+      end
+
+      # { key => color } for a category in ONE query — the shape a view wants:
+      # build it once, then look up each cell with no extra queries (avoids an
+      # N+1 when rendering many rows, e.g. the /pokemon type badges).
+      def color_map(category)
+        catalog(category).pluck(:key, :color).to_h
+      end
+
+      # Just the color for a single (category, key), with an optional fallback
+      # when the key is unknown or the table isn't installed yet.
+      def color_for(category, key, fallback: nil)
+        return fallback unless available?
+
+        in_category(category).where(key: key.to_s).limit(1).pick(:color) || fallback
+      end
+
+      # { key => emoji } for a category in ONE query — the metadata sibling of
+      # color_map, for decorative glyphs kept in `metadata` rather than a column.
+      def emoji_map(category)
+        catalog(category).pluck(:key, :metadata).to_h { |key, meta| [key, meta && meta["emoji"]] }
+      end
+    end
+
+    # A decorative glyph for the value, kept in `metadata` (not a column) since
+    # it's a presentation extra — e.g. a Pokémon type's emoji. Nil when unset.
+    def emoji
+      metadata && metadata["emoji"]
+    end
+  end
+end

data/db/migrate/20260623130000_create_studio_enumerals.rb

@@ -0,0 +1,30 @@
+# Reference migration for the Studio::Enumeral model. Like the engine's
+# studio_links / studio_email_deliveries migrations, each consumer app installs
+# its own copy of this into db/migrate so the table is created in the app's
+# database (the model is shipped by the gem; the table lives per app).
+class CreateStudioEnumerals < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_enumerals do |t|
+      # `category` groups a fixed set of values (e.g. "pokemon_type"); `key` is
+      # the stable machine value within it (e.g. "fire"). label/color/position
+      # are presentation; metadata (jsonb) carries any category-specific extras.
+      t.string  :category, null: false
+      t.string  :key,      null: false
+      t.string  :label
+      t.string  :color
+      t.integer :position, null: false, default: 0
+      # A sparse, gappy ordinal (100, 200, …) for a domain ranking distinct from
+      # display `position` — e.g. Pokémon types ranked most-common → least-common.
+      # The gaps leave room to insert a value between two ranks without
+      # renumbering. Nullable: not every enumeral is ranked.
+      t.integer :rank
+      t.jsonb   :metadata, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :studio_enumerals, [:category, :key], unique: true
+    add_index :studio_enumerals, [:category, :position]
+    add_index :studio_enumerals, [:category, :rank]
+  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.8.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.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-22 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,11 +196,13 @@ 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
 - app/models/session_context.rb
 - app/models/studio/email_delivery.rb
+- app/models/studio/enumeral.rb
 - app/models/studio/link.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
@@ -235,8 +264,10 @@ files:
 - db/migrate/20260614000000_create_studio_email_deliveries.rb
 - db/migrate/20260620000001_create_studio_links.rb
 - db/migrate/20260620000002_allow_null_image_cache_owner.rb
+- 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
@@ -244,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
@@ -261,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
@@ -276,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