studio-engine 0.102.0.rc1 → 0.103.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eb8bd189cd5861c7aad2afb33f1d00ebe6bfa103e9e106dade9363d66cb91a4
-  data.tar.gz: 2381d4002f2c80cde9bb8a59243cc4836c99ce3abd90d8f97dfff50f7d89dad7
+  metadata.gz: 773214119ffedd307e2f80ba808f5413cc69a2e9cb875c2997d7f7be0f120ce8
+  data.tar.gz: 9b6c272fd88d22717b6e69020146c936d8db1d04b88f5a9b3effe5764d64ec38
 SHA512:
-  metadata.gz: 87fb049ff0f6cb9041b0c070f9cde7f6c975e9eb04b275aa1cad4f3336ca89552d7ac3962a60e4ad9d12e0e2d970f9c6103403697e7d7d12762bec1c813295e4
-  data.tar.gz: 4b96de3893bf63d4d1ce75971078972e83d1be52189e5f58ffd74e05ebe4a86888168d563b5a1966a9db90934f3fe1c74ba4e684dbdb31879062fdd3fe9d75c6
+  metadata.gz: fd521d84d03c3c7a45e0fa1113d065db78a67ef5de36a8ac66b237b28b15a9cd562f8e703436b75f6419e927243d13ca99877f9d3493a59a6bf276b3b07cb269
+  data.tar.gz: '0508739a475558e609a1efc465d75f2f37aa71fcf9c3b7477a759d3a900b4d1353628a150d8304f7a7b6bb568958cc97e1c8943382e57733a6466c8b803157f2'

data/CHANGELOG.md

@@ -4,6 +4,57 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.103.0 — 2026-10-10
+
+### Added
+
+- **Seed assets reference production.** A non-production process (laptop,
+  desk, QA app) can record an `ImageCache` row that REFERENCES an object
+  already in the production bucket instead of uploading a copy into the dev
+  bucket. New:
+  - `Studio.s3_production_public_url`: production's public host, set in
+    every environment (e.g. `https://assets.turfmonster.media`). Default nil
+    turns references off.
+  - `image_caches.stored_in` (migration `AddStoredInToImageCaches`):
+    nullable string. nil or `"own"` is the own bucket, `"production"` a
+    reference. `ImageCache#url` resolves a reference on the production host
+    off production. In production both kinds resolve on the own host, which
+    is production's.
+  - `Studio::ImageCache.reference_or_cache!`: `cache!`'s arguments and
+    answer. Off production, with the setting, it HEADs each missing variant
+    in `<prefix>-production` (read-only) and records a reference when found,
+    else uploads to the own bucket as `cache!` does. A HEAD failing for any
+    reason but not-found raises. In production, or without the setting, it
+    is `cache!`.
+  - `Studio::S3.production_bucket`, `production_references?`,
+    `production_url`, `production_head`, `production_exists?` and
+    `production_download`: reads only. `ImageCache#download` and
+    `#delete_object!` act on the bucket that holds the row's object;
+    off production `delete_object!` deletes nothing for a reference.
+
+  **Design.** A per-row marker plus one configured host, because a row must
+  say whose object it is: 11 of 12 sampled Turf headshot keys were on
+  production and one (`kenneth-walker-iii`) was only on dev, so no app-wide
+  switch is right for every row. Rejected: storing absolute URLs in `s3_key`
+  (breaks every reader that treats it as a key, the uniqueness index and the
+  key namespace); an AR enum (raises at load on a host that has not migrated);
+  an HTTP HEAD on the public host (a CDN answer is not the bucket's, and the
+  dev token's Item Read on production makes the S3 HEAD available and
+  stubbable); requiring the column in `Studio::HostSchema` (would fail boot on
+  every consumer before it installs the migration). The existing guard
+  (`guard_production_bucket!`) still refuses any delete from a `*-production`
+  bucket off production, and the dev R2 tokens cannot write production.
+
+  **Consumer adoption.** Nothing changes until an app opts in, and production
+  behaves as before. To adopt: (1) `bin/rails studio_engine:install:migrations
+  db:migrate` and commit the copy and `db/schema.rb`; (2) set
+  `config.s3_production_public_url` to the production asset host in
+  `config/initializers/studio.rb`; (3) switch seeders from
+  `Studio::ImageCache.cache!` to `reference_or_cache!`; (4) replace any
+  `Studio::S3.download(key: row.s3_key)` or `Studio::S3.delete(key:
+  row.s3_key)` on an `ImageCache` row with `row.download` /
+  `row.delete_object!`.
+
 ## 0.102.0 — 2026-10-10
 
 ### Removed

data/README.md

@@ -979,6 +979,33 @@ be a positive Integer.
 `Studio::S3.delete` moves the object to `trash/` for three days rather than
 deleting it; see [Trash and restore](#trash-and-restore).
 
+### Seed assets reference production
+
+Seed assets (NFL headshots, Pokémon sprites) live in the **production** bucket.
+A laptop, desk or QA app points at production's copy instead of uploading a
+duplicate into the dev bucket, and uploads only what production lacks. Set
+production's public host in every environment (it is not a secret):
+
+```ruby
+config.s3_production_public_url = "https://assets.turfmonster.media"
+```
+
+and have seeders call `Studio::ImageCache.reference_or_cache!` (same arguments
+and answer as `cache!`). Off production it HEADs each missing variant in
+`<prefix>-production` (read-only; the dev R2 token holds Item Read there).
+Found: an `ImageCache` row with `stored_in = "production"`, whose `#url`
+resolves on `s3_production_public_url`. Absent: an ordinary upload to the own
+bucket. A HEAD failing for any reason but not-found raises. In production, or
+with the setting unset, it is exactly `cache!`.
+
+`stored_in` arrives by the engine migration `AddStoredInToImageCaches`
+(nullable; nil and `"own"` mean the own bucket, so existing rows keep their
+URLs). Read an object's bytes with `ImageCache#download` and remove it with
+`ImageCache#delete_object!`, never `Studio::S3.download/delete(key: row.s3_key)`:
+those read and delete the OWN bucket. Off production, `delete_object!` on a
+production reference deletes nothing, and `Studio::S3` has no write, copy or
+delete that targets the production bucket.
+
 An app with **no** bucket configured does not error — `/admin/emails` renders
 read-only, showing the inherited defaults it is genuinely sending and naming the
 one setting that turns uploads on.

data/app/models/image_cache.rb

@@ -1,4 +1,20 @@
 class ImageCache < ApplicationRecord
+  # Where a row's object lives (the `stored_in` column):
+  #
+  #   nil / "own"   this process's own bucket, at Studio.s3_public_url. Every row
+  #                 written before the column existed, and every upload.
+  #   "production"  a REFERENCE to production's copy, recorded by a
+  #                 non-production seeder (Studio::ImageCache.reference_or_cache!)
+  #                 instead of uploading a duplicate. It resolves on
+  #                 Studio.s3_production_public_url.
+  #
+  # A plain string, not an AR enum: the column arrives by an engine migration a
+  # host installs on its own schedule, and an enum declared on an absent column
+  # raises at load. Without the column every row reads as "own", as before.
+  STORED_IN = %w[own production].freeze
+  OWN = "own"
+  PRODUCTION = "production"
+
   # Optional so app-GLOBAL images (no owning record) can be cached too — e.g.
   # Studio::EmailCatalog stores the admin-managed email banners owner-less. Per-
   # record images (athlete/coach headshots) still set an owner; the
@@ -8,8 +24,41 @@ class ImageCache < ApplicationRecord
   validates :purpose, :variant, :s3_key, presence: true
   validates :s3_key, uniqueness: true
   validates :variant, uniqueness: { scope: [:owner_type, :owner_id, :purpose] }
+  validates :stored_in, inclusion: { in: STORED_IN }, allow_nil: true, if: -> { has_attribute?(:stored_in) }
+
+  def self.stored_in_column?
+    table_exists? && column_names.include?("stored_in")
+  end
+
+  def production_reference?
+    has_attribute?(:stored_in) && stored_in == PRODUCTION
+  end
 
+  # In production both kinds resolve on the app's own host, which IS
+  # production's, so a production app's URLs are what they always were.
   def url
-    Studio::S3.url(key: s3_key)
+    production_reference? ? Studio::S3.production_url(key: s3_key) : Studio::S3.url(key: s3_key)
+  end
+
+  # The object's bytes, read from the bucket that holds them (read-only for a
+  # production reference). Use this, not Studio::S3.download(key: s3_key),
+  # which reads this process's own bucket.
+  def download(max_bytes: nil)
+    if production_reference?
+      Studio::S3.production_download(key: s3_key, max_bytes: max_bytes)
+    else
+      Studio::S3.download(key: s3_key, max_bytes: max_bytes)
+    end
+  end
+
+  # Removes the row's OBJECT (to trash, via Studio::S3.delete). A production
+  # reference outside production is not this process's object: nothing is
+  # deleted from either bucket (the own bucket may hold an unrelated object
+  # under the same key) and nil is returned. Destroying the row itself is
+  # always fine. In production a reference is an ordinary own object.
+  def delete_object!
+    return nil if production_reference? && !Studio::S3.production_environment?
+
+    Studio::S3.delete(key: s3_key)
   end
 end

data/db/migrate/20261010120000_add_stored_in_to_image_caches.rb

@@ -0,0 +1,25 @@
+# Adds image_caches.stored_in: where a row's object lives. nil (every existing
+# row) and "own" mean this app's own bucket; "production" marks a non-production
+# row that REFERENCES production's copy of a seed asset instead of a duplicate
+# in the dev bucket (Studio::ImageCache.reference_or_cache!, ImageCache#url).
+#
+# Nullable with no default, so the add is a catalog-only change on any table
+# size and no existing row is rewritten or changes its URL.
+#
+# image_caches is host-owned; on a host without the table this is a no-op, like
+# AllowNullImageCacheOwner. Studio::HostSchema does not require the column: a
+# host that has not installed this migration keeps working, and every row reads
+# as "own".
+class AddStoredInToImageCaches < ActiveRecord::Migration[7.2]
+  def up
+    return unless table_exists?(:image_caches)
+
+    add_column :image_caches, :stored_in, :string, if_not_exists: true
+  end
+
+  def down
+    return unless table_exists?(:image_caches)
+
+    remove_column :image_caches, :stored_in, if_exists: true
+  end
+end

data/lib/studio/image_cache.rb

@@ -46,21 +46,107 @@ module Studio
     # Idempotent: variants already present in ImageCache are skipped. If
     # nothing is missing, the source is never read.
     def self.cache!(owner:, purpose:, key_prefix:, widths:, source_url: nil, source_path: nil, content_type: "image/png")
-      raise ArgumentError, "either source_url or source_path is required" if source_url.nil? && source_path.nil?
+      ext, requested = prepare!(source_url: source_url, source_path: source_path, content_type: content_type, widths: widths)
 
-      unless ALLOWED_CONTENT_TYPES.include?(content_type)
-        raise UnsupportedContentType, "content_type #{content_type.inspect} not in allowlist (#{ALLOWED_CONTENT_TYPES.join(", ")})"
+      existing = ::ImageCache.where(owner: owner, purpose: purpose).index_by(&:variant)
+      missing  = requested - existing.keys
+      return existing if missing.empty?
+
+      upload_variants!(existing, missing, owner: owner, purpose: purpose, key_prefix: key_prefix, ext: ext,
+                                          source_url: source_url, source_path: source_path, content_type: content_type)
+    end
+
+    # ── SEED ASSETS: REFERENCE PRODUCTION, UPLOAD ONLY WHAT IS NEW ────────────
+    #
+    # cache!'s signature and answer, for SEEDERS. Seed assets live in the
+    # production bucket; a laptop, desk or QA app should point at production's
+    # copy rather than upload a duplicate into the dev bucket. So, outside
+    # production, with Studio.s3_production_public_url set, each missing variant
+    # is first looked for in production by a read-only HEAD
+    # (Studio::S3.production_head) under the key cache! would write:
+    #
+    #   found     an ImageCache row with stored_in "production" is recorded. Its
+    #             #url resolves on the production host. Nothing is uploaded.
+    #   absent    the variant is uploaded to this process's OWN bucket exactly as
+    #             cache! does (stored_in nil = own). A key production lacks
+    #             (kenneth-walker-iii, 2026-10-10) still gets an image.
+    #
+    # The source is fetched only when at least one variant has to be uploaded.
+    # A HEAD that fails for any reason but "not found" raises: a token without
+    # read on production must not quietly turn into a dev-bucket copy of
+    # everything.
+    #
+    # In production, or with s3_production_public_url unset, this IS cache!.
+    # Production never reads the knob, so production apps behave as before.
+    #
+    # Nothing here writes, copies or deletes in the production bucket.
+    def self.reference_or_cache!(owner:, purpose:, key_prefix:, widths:, source_url: nil, source_path: nil,
+                                 content_type: "image/png")
+      unless Studio::S3.production_references?
+        return cache!(owner: owner, purpose: purpose, key_prefix: key_prefix, widths: widths,
+                      source_url: source_url, source_path: source_path, content_type: content_type)
       end
 
-      validate_source_url!(source_url) if source_url
+      unless ::ImageCache.stored_in_column?
+        raise MissingStoredInColumn,
+              "image_caches.stored_in is missing: run `bin/rails studio_engine:install:migrations db:migrate` " \
+              "before referencing production seed assets"
+      end
 
-      ext = EXT_BY_TYPE[content_type]
-      requested = ["original", *widths.map(&:to_s)]
+      ext, requested = prepare!(source_url: source_url, source_path: source_path, content_type: content_type, widths: widths)
 
       existing = ::ImageCache.where(owner: owner, purpose: purpose).index_by(&:variant)
       missing  = requested - existing.keys
       return existing if missing.empty?
 
+      to_upload = missing.reject do |variant|
+        s3_key = variant_key(key_prefix, variant, ext)
+        head = Studio::S3.production_head(key: s3_key)
+        next false if head.nil?
+
+        existing[variant] = ::ImageCache.create!(
+          owner: owner,
+          purpose: purpose,
+          variant: variant,
+          s3_key: s3_key,
+          stored_in: ::ImageCache::PRODUCTION,
+          source_url: source_url,
+          bytes: head.content_length,
+          content_type: head.content_type.to_s.empty? ? content_type : head.content_type
+        )
+        true
+      end
+      return existing if to_upload.empty?
+
+      upload_variants!(existing, to_upload, owner: owner, purpose: purpose, key_prefix: key_prefix, ext: ext,
+                                            source_url: source_url, source_path: source_path, content_type: content_type)
+    end
+
+    class MissingStoredInColumn < StandardError; end
+
+    # The key every variant is written under, by cache! and looked up under by
+    # reference_or_cache!. One definition, so the two can never disagree.
+    def self.variant_key(key_prefix, variant, ext)
+      "#{key_prefix}/#{variant}.#{ext}"
+    end
+
+    def self.prepare!(source_url:, source_path:, content_type:, widths:)
+      raise ArgumentError, "either source_url or source_path is required" if source_url.nil? && source_path.nil?
+
+      unless ALLOWED_CONTENT_TYPES.include?(content_type)
+        raise UnsupportedContentType, "content_type #{content_type.inspect} not in allowlist (#{ALLOWED_CONTENT_TYPES.join(", ")})"
+      end
+
+      validate_source_url!(source_url) if source_url
+
+      [EXT_BY_TYPE[content_type], ["original", *widths.map(&:to_s)]]
+    end
+    private_class_method :prepare!
+
+    # Reads the source once and uploads each of `missing` to this process's own
+    # bucket, recording a row per variant into `existing`, which it returns.
+    def self.upload_variants!(existing, missing, owner:, purpose:, key_prefix:, ext:, source_url:, source_path:,
+                              content_type:)
       require "mini_magick"
 
       body = if source_path
@@ -72,7 +158,6 @@ module Studio
       missing.each do |variant|
         if variant == "original"
           payload = body
-          s3_key  = "#{key_prefix}/original.#{ext}"
         else
           img = MiniMagick::Image.read(body)
           # Cap ImageMagick resources per-invocation to prevent decompression-bomb DoS.
@@ -84,8 +169,8 @@ module Studio
             c.resize "#{variant}x"
           end
           payload = img.to_blob
-          s3_key  = "#{key_prefix}/#{variant}.#{ext}"
         end
+        s3_key = variant_key(key_prefix, variant, ext)
 
         Studio::S3.upload(
           key: s3_key,
@@ -107,6 +192,7 @@ module Studio
 
       existing
     end
+    private_class_method :upload_variants!
 
     # ── THE SSRF GUARD ────────────────────────────────────────────────────────
     #

data/lib/studio/s3.rb

@@ -25,13 +25,18 @@ module Studio
       # is answered as the empty string it means. Tested against a stubbed
       # client only: no live store, R2 included, has been asked.
       def download(key:, max_bytes: nil)
+        read_object(bucket, key, max_bytes)
+      end
+
+      # The GET behind download and production_download.
+      def read_object(target, key, max_bytes)
         # 0 or a negative would build "bytes=0--1", which a store may read as
         # no range at all and answer with the whole object.
         unless max_bytes.nil? || (max_bytes.is_a?(Integer) && max_bytes.positive?)
           raise ArgumentError, "max_bytes must be a positive Integer, got #{max_bytes.inspect}"
         end
 
-        opts = { bucket: bucket, key: full_key(key) }
+        opts = { bucket: target, key: full_key(key) }
         opts[:range] = "bytes=0-#{max_bytes - 1}" if max_bytes
         s3 = client
         # The rescue names an SDK constant, so it wraps only what runs after
@@ -84,10 +89,70 @@ module Studio
       end
 
       def exists?(key:)
-        client.head_object(bucket: bucket, key: full_key(key))
-        true
-      rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
-        false
+        !head(bucket, key).nil?
+      end
+
+      # ── PRODUCTION REFERENCES (read-only) ─────────────────────────────────
+      #
+      # Seed assets live in the PRODUCTION bucket, and a non-production process
+      # references them there instead of uploading its own copy (ImageCache's
+      # stored_in = "production"). Everything below READS production and
+      # nothing writes it: there is no upload, copy or delete that takes the
+      # production bucket, and delete/purge! still refuse a "*-production"
+      # bucket off production (guard_production_bucket!). The dev R2 tokens
+      # hold Item Read on production and Item Write on dev only, so the store
+      # refuses a write even if code here ever tried.
+
+      # The bucket production writes: "#{s3_bucket_prefix}-production" in every
+      # environment. In real production it is `bucket`.
+      def production_bucket
+        prefix = Studio.s3_bucket_prefix
+        raise NotConfigured, "Studio.s3_bucket_prefix not set in config/initializers/studio.rb" if prefix.nil? || prefix.empty?
+
+        "#{prefix}-production"
+      end
+
+      # Whether this process may record a production reference: it is not
+      # production itself (production's own uploads already ARE production's)
+      # and it knows production's public host (Studio.s3_production_public_url).
+      def production_references?
+        !production_environment? && !Studio.s3_production_public_url.to_s.empty?
+      end
+
+      # The public URL of production's copy of `key`. In production it is
+      # exactly url(key:). Elsewhere it is s3_production_public_url plus the
+      # key, under the same s3_key_prefix (the namespace is per app, not per
+      # environment); without that base it RAISES rather than answer with this
+      # environment's host, where the object does not exist.
+      def production_url(key:)
+        return url(key: key) if production_environment?
+
+        base = Studio.s3_production_public_url.to_s
+        if base.empty?
+          raise NotConfigured,
+                "Studio.s3_production_public_url not set: cannot resolve production's copy of #{key.inspect} " \
+                "from a #{environment} process"
+        end
+
+        "#{base.chomp("/")}/#{full_key(key)}"
+      end
+
+      # A read-only HEAD against the production bucket: the object's metadata
+      # (content_length, content_type) when production holds `key`, nil when it
+      # does not. Any other answer (403 from a token without Item Read on
+      # production, a network error) RAISES: a seeder that cannot ask must not
+      # read the silence as "absent" and quietly upload a copy.
+      def production_head(key:)
+        head(production_bucket, key)
+      end
+
+      def production_exists?(key:)
+        !production_head(key: key).nil?
+      end
+
+      # A read-only GET of production's copy, with download's max_bytes rules.
+      def production_download(key:, max_bytes: nil)
+        read_object(production_bucket, key, max_bytes)
       end
 
       # A RECOVERABLE delete: the object moves under trash/ in the same bucket
@@ -235,8 +300,22 @@ module Studio
         @client = nil
       end
 
+      private :read_object
+
       private
 
+      # HEAD of `key` in `target`: the response, or nil when the object is
+      # absent. `target` is resolved by the caller, so an unconfigured app
+      # raises NotConfigured before the rescue below names an SDK constant.
+      def head(target, key)
+        s3 = client
+        begin
+          s3.head_object(bucket: target, key: full_key(key))
+        rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+          nil
+        end
+      end
+
       # WHICH BUCKET HALF THIS APP OWNS. Rails.env alone cannot answer it: no QA app
       # sets RAILS_ENV, so every QA app boots as `production` exactly like real
       # production. QA_ENV is the signal that separates them, and it is the one

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.102.0.rc1"
+  VERSION = "0.103.0.rc1"
 end

data/lib/studio.rb

@@ -1079,6 +1079,19 @@ module Studio
   mattr_accessor :s3_secret_access_key, default: nil
   mattr_accessor :s3_public_url,        default: nil
 
+  # SEED ASSETS LIVE IN PRODUCTION. The public base of THIS app's PRODUCTION
+  # bucket (https://assets.turfmonster.media), set in every environment. A
+  # non-production process (a laptop, a desk, a QA app) whose seeders call
+  # Studio::ImageCache.reference_or_cache! records an ImageCache row that
+  # REFERENCES production's copy of an object instead of uploading its own, and
+  # that row's #url resolves on this host. Not a secret, so a literal in
+  # config/initializers/studio.rb is the expected form.
+  #
+  # nil (the default) turns references off: reference_or_cache! is then exactly
+  # cache!, and every row resolves on s3_public_url as it always has. A real
+  # production process ignores it, because its own bucket IS production.
+  mattr_accessor :s3_production_public_url, default: nil
+
   # Knowledge layer — the S3-backed document store + /admin/knowledge browser
   # (Studio::KnowledgeDoc). Routes are opt-in like every route surface.
   # knowledge_agents is the roster of agent slugs the intake UI offers

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.102.0.rc1
+  version: 0.103.0.rc1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -713,6 +713,7 @@ files:
 - db/migrate/20261006120002_ensure_theme_settings_table.rb
 - db/migrate/20261006120003_ensure_image_caches_table.rb
 - db/migrate/20261008120000_add_recording_to_studio_knowledge_docs.rb
+- db/migrate/20261010120000_add_stored_in_to_image_caches.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb