studio-engine 0.84.0 → 0.86.0

data/lib/studio/s3/trash.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "time"
+require "erb"
+require "uri"
+require_relative "../s3" unless defined?(Studio::S3::Error)
+
+module Studio
+  module S3
+    # THE GRACE PERIOD ON A DELETE. R2 has no object versioning, so a delete is
+    # forever the moment it lands: a replaced profile picture, a purged
+    # attachment, a banner swapped in /admin/emails. Trash turns that delete into
+    # a MOVE inside the same bucket:
+    #
+    #   avatars/abc.png  ->  trash/2026-10-01/1759302000123/avatars/abc.png
+    #
+    # and the bucket's lifecycle rule (set on the bucket, not here) expires
+    # everything under trash/ after three days. Until then the object can be put
+    # back with `rake studio:trash:restore[TRASH_KEY]`.
+    #
+    # THE ORDER IS THE SAFETY. Copy first, delete second, and a copy that fails
+    # RAISES before the delete is ever sent. A failure anywhere leaves the
+    # original where it was: a leaked object costs storage, a lost one costs a
+    # user's photo.
+    #
+    # Everything here works on REAL object keys (any Studio.s3_key_prefix
+    # already applied) and an explicit client + bucket, so Studio::S3 and the
+    # Active Storage service (ActiveStorage::Service::StudioTrashS3Service) share
+    # one implementation. trash/ always sits at the bucket ROOT, even for an app
+    # that lives under a key prefix in a shared bucket, so ONE lifecycle rule and
+    # ONE Cloudflare block cover every app in the bucket.
+    module Trash
+      PREFIX = "trash/"
+
+      # A single CopyObject copies at most 5 GiB (S3 and R2 alike). Larger
+      # objects need a multipart copy, which this does not do: it refuses
+      # instead, and leaves the object in place. Nothing in the fleet is near
+      # it (moms-app's audio is ~650 MB).
+      MAX_COPY_BYTES = 5 * 1024**3
+
+      # The metadata trash! writes. restore! strips exactly these back off, so a
+      # restored object carries the metadata it was uploaded with and no more.
+      TRASH_METADATA_KEYS = %w[
+        original-key deleted-at deleted-env
+        blob-content-type blob-byte-size blob-checksum blob-filename
+      ].freeze
+
+      # Header fields a REPLACE copy would otherwise drop.
+      CARRIED_HEADERS = %i[content_type cache_control content_disposition content_encoding content_language].freeze
+
+      class TooLarge < Studio::S3::Error; end
+      class ProductionBucketRefused < Studio::S3::Error; end
+      class NotTrash < Studio::S3::Error; end
+      class RestoreConflict < Studio::S3::Error; end
+
+      TRASH_KEY = %r{\Atrash/(\d{4}-\d{2}-\d{2})/(\d+)/(.+)\z}m
+
+      class << self
+        # Move bucket/key under trash/ and return the trash key. Returns nil,
+        # sending no copy and no delete, when the object is already gone: an
+        # S3 delete of a missing key succeeds, and so does this.
+        def trash!(client:, bucket:, key:, env:, now: Time.now.utc)
+          head = head(client, bucket, key)
+          return nil unless head
+
+          size = head.content_length.to_i
+          if size > MAX_COPY_BYTES
+            raise TooLarge, "#{bucket}/#{key} is #{size} bytes; a single CopyObject moves at most " \
+                            "#{MAX_COPY_BYTES} (5 GiB), so it was NOT trashed and NOT deleted. " \
+                            "Delete it with Studio::S3.purge! if you mean it, or copy it aside by hand first."
+          end
+
+          trash_key = key_for(key, now: now)
+          client.copy_object(
+            bucket: bucket,
+            copy_source: copy_source(bucket, key),
+            key: trash_key,
+            metadata_directive: "REPLACE",
+            metadata: trash_metadata(head, key: key, env: env, now: now),
+            **carried_headers(head)
+          )
+          # Reached only when the copy returned. A raise above never deletes.
+          client.delete_object(bucket: bucket, key: key)
+          trash_key
+        end
+
+        # trash/<UTC date>/<epoch ms>/<original key>. The date makes a day's
+        # deletes easy to browse; the milliseconds keep two deletes of the same
+        # key (a profile picture replaced twice in a day) from colliding.
+        def key_for(key, now: Time.now.utc)
+          now = now.utc
+          "#{PREFIX}#{now.strftime('%Y-%m-%d')}/#{(now.to_r * 1000).floor}/#{key}"
+        end
+
+        # The original key a trash key was moved from. It is read from the trash
+        # key's own path, not from metadata, so it answers even for an object
+        # whose metadata a hand copy dropped.
+        def original_key(trash_key)
+          match = TRASH_KEY.match(trash_key.to_s)
+          raise NotTrash, "#{trash_key.inspect} is not a trash key (trash/<date>/<ms>/<key>)" unless match
+
+          match[3]
+        end
+
+        def trash_key?(key)
+          key.to_s.start_with?(PREFIX)
+        end
+
+        # Every trash key whose original key is `key` (any key when nil),
+        # oldest first. Pages through the whole trash/ prefix: it is three
+        # days deep, so it stays small.
+        def list(client:, bucket:, key: nil)
+          keys = []
+          token = nil
+          loop do
+            params = { bucket: bucket, prefix: PREFIX }
+            params[:continuation_token] = token if token
+            resp = client.list_objects_v2(**params)
+            resp.contents.each do |object|
+              next unless TRASH_KEY.match?(object.key)
+              next if key && original_key(object.key) != key
+
+              keys << object
+            end
+            break unless resp.is_truncated
+
+            token = resp.next_continuation_token
+          end
+          keys.sort_by(&:key)
+        end
+
+        # Copy a trashed object back to its original key and return that key.
+        # The trash copy is left alone (the lifecycle rule expires it), so a
+        # restore can be repeated. Refuses to overwrite a live object unless
+        # overwrite: true, because the original key may already hold a newer
+        # upload. Restores the BYTES only: an Active Storage blob row is gone
+        # by the time its object is trashed; see blob_attributes.
+        def restore!(client:, bucket:, trash_key:, overwrite: false)
+          original = original_key(trash_key)
+          head = head(client, bucket, trash_key)
+          raise NotTrash, "#{bucket}/#{trash_key} does not exist (expired, or never trashed)" unless head
+          if !overwrite && head(client, bucket, original)
+            raise RestoreConflict, "#{bucket}/#{original} already exists; pass overwrite (FORCE=1) to replace it"
+          end
+
+          client.copy_object(
+            bucket: bucket,
+            copy_source: copy_source(bucket, trash_key),
+            key: original,
+            metadata_directive: "REPLACE",
+            metadata: (head.metadata || {}).reject { |name, _| TRASH_METADATA_KEYS.include?(name) },
+            **carried_headers(head)
+          )
+          original
+        end
+
+        # What an Active Storage blob row needs to be rebuilt around a restored
+        # key, as far as the trash copy can say. filename is nil unless the
+        # upload carried a Content-Disposition (Active Storage only sends one
+        # for attachment-disposition blobs); the caller supplies it otherwise.
+        def blob_attributes(client:, bucket:, trash_key:)
+          head = head(client, bucket, trash_key)
+          raise NotTrash, "#{bucket}/#{trash_key} does not exist" unless head
+
+          meta = head.metadata || {}
+          {
+            key: original_key(trash_key),
+            filename: decode(meta["blob-filename"]),
+            content_type: meta["blob-content-type"] || head.content_type,
+            byte_size: (meta["blob-byte-size"] || head.content_length).to_i,
+            checksum: meta["blob-checksum"]
+          }
+        end
+
+        # CopySource is "<bucket>/<url-encoded key>"; each path segment is
+        # escaped and the slashes kept, the form S3 and R2 both accept.
+        def copy_source(bucket, key)
+          require "aws-sdk-s3"
+          "#{bucket}/#{Seahorse::Util.uri_path_escape(key)}"
+        end
+
+        private
+
+        def head(client, bucket, key)
+          client.head_object(bucket: bucket, key: key)
+        rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+          nil
+        end
+
+        def carried_headers(head)
+          CARRIED_HEADERS.each_with_object({}) do |name, out|
+            value = head.public_send(name)
+            out[name] = value unless value.nil? || value.to_s.empty?
+          end
+        end
+
+        # The original object's own metadata first, then the trash record, so a
+        # stale "original-key" from an earlier round trip can never win.
+        def trash_metadata(head, key:, env:, now:)
+          meta = (head.metadata || {}).to_h.dup
+          meta["original-key"] = encode(key)
+          meta["deleted-at"] = now.utc.iso8601
+          meta["deleted-env"] = env.to_s
+          meta["blob-content-type"] = head.content_type.to_s unless head.content_type.to_s.empty?
+          meta["blob-byte-size"] = head.content_length.to_i.to_s
+          checksum = checksum_from_etag(head.etag)
+          meta["blob-checksum"] = checksum if checksum
+          filename = filename_from_disposition(head.content_disposition)
+          meta["blob-filename"] = encode(filename) if filename
+          meta
+        end
+
+        # A single-part upload's ETag is the hex MD5 of its bytes, and Active
+        # Storage's blob checksum is that MD5 in base64. A multipart ETag
+        # ("<hex>-<parts>") is not an MD5 of the object, so it yields nothing.
+        def checksum_from_etag(etag)
+          hex = etag.to_s.delete('"')
+          return nil unless hex.match?(/\A\h{32}\z/)
+
+          [[hex].pack("H*")].pack("m0")
+        end
+
+        def filename_from_disposition(disposition)
+          value = disposition.to_s
+          if (match = value.match(/filename\*=UTF-8''([^;]+)/i))
+            return URI.decode_uri_component(match[1])
+          end
+          match = value.match(/filename="([^"]*)"/i) || value.match(/filename=([^;]+)/i)
+          match && !match[1].strip.empty? ? match[1].strip : nil
+        end
+
+        # S3 metadata travels as HTTP headers, so a value must be ASCII. A key
+        # or filename that is not is stored percent-encoded behind "url:".
+        def encode(value)
+          value = value.to_s
+          value.ascii_only? ? value : "url:#{ERB::Util.url_encode(value)}"
+        end
+
+        def decode(value)
+          return nil if value.nil?
+          return URI.decode_uri_component(value.delete_prefix("url:")) if value.start_with?("url:")
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/studio/s3.rb

@@ -55,15 +55,66 @@ module Studio
         false
       end
 
+      # A RECOVERABLE delete: the object moves under trash/ in the same bucket
+      # (Studio::S3::Trash) and the bucket's lifecycle rule expires it after
+      # three days. Returns the trash key, or nil when there was nothing to
+      # move. Refused outright when a non-production process is pointed at a
+      # production bucket. purge! is the delete that cannot be undone.
       def delete(key:)
-        client.delete_object(bucket: bucket, key: full_key(key))
+        target = bucket
+        guard_production_bucket!(target)
+        Trash.trash!(client: client, bucket: target, key: full_key(key), env: deletion_environment)
+      end
+
+      # The HARD delete, gone at once with no trash copy. For objects with no
+      # value after deletion (regenerable derivatives, a trash copy itself).
+      # The same production-bucket guard as delete.
+      def purge!(key:)
+        target = bucket
+        guard_production_bucket!(target)
+        client.delete_object(bucket: target, key: full_key(key))
       end
 
       # Returns LOGICAL keys (the app's key namespace stripped back off), so a
       # caller can feed any result straight back into download/delete/url.
-      def list(prefix: nil, max: 1000)
+      # Trashed objects are deleted objects, so trash/ keys are left out unless
+      # include_trash: true. The filter runs after S3's max_keys, so a listing
+      # with trash in range can return fewer than max keys.
+      def list(prefix: nil, max: 1000, include_trash: false)
         resp = client.list_objects_v2(bucket: bucket, prefix: full_key(prefix), max_keys: max)
-        resp.contents.map { |object| logical_key(object.key) }
+        keys = resp.contents.map(&:key)
+        keys = keys.reject { |key| Trash.trash_key?(key) } unless include_trash
+        keys.map { |key| logical_key(key) }
+      end
+
+      # Whether this process is real production, by the SAME resolution that
+      # picks the bucket half (QA_ENV first, then Rails.env). Public because the
+      # Active Storage trash service guards on it too.
+      def production_environment?
+        environment == "production"
+      end
+
+      # A non-production process (a laptop, a QA app, CI) may never delete from
+      # a bucket named "*-production", whoever handed it the bucket name or the
+      # key. Studio::S3 derives its bucket from the same environment, so here it
+      # is a backstop; for an Active Storage service, whose bucket comes from
+      # storage.yml, it is the guard.
+      def guard_production_bucket!(bucket_name)
+        return unless bucket_name.to_s.end_with?("-production")
+        return if production_environment?
+
+        raise Trash::ProductionBucketRefused,
+              "refusing to delete from #{bucket_name}: this process resolves to a non-production " \
+              "environment (#{deletion_environment}); only production deletes production objects"
+      end
+
+      # The environment a trash copy records in its deleted-env metadata:
+      # "qa" for a QA app (which runs Rails as production), else Rails.env.
+      def deletion_environment
+        return "qa" if EnvironmentBanner.qa_environment?
+        return Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+        "unknown"
       end
 
       def bucket
@@ -190,3 +241,5 @@ module Studio
     end
   end
 end
+
+require_relative "s3/trash"

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.84.0"
+  VERSION = "0.86.0"
 end

data/lib/studio.rb

@@ -1,3 +1,16 @@
+# What this file and lib/studio/* call at REQUIRE time, required here rather
+# than left to the host. `15.minutes` and `24.hours` below are evaluated the
+# moment `require "studio"` runs, which is Bundler.require in the host's
+# config/application.rb, BEFORE Rails' :load_active_support initializer pulls in
+# any core extension. A host on `rails/all` happens to have them already (the
+# ActiveRecord and ActiveJob railties load them); a host with no ActiveRecord
+# does not, and its boot died on `Integer#minutes` until it required
+# active_support/core_ext/integer/time itself. A gem requires what it uses.
+# test/integration/footer_only_consumer_test.rb boots that host.
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/integer/time"
 require "studio/version"
 require "studio/log_rotation"
 require "studio/ip_locations"
@@ -17,6 +30,7 @@ require "studio/site_footer"
 require "studio/booking"
 require "studio/navbar_links"
 require "studio/navbar_identity"
+require "studio/auth_labels"
 require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
@@ -201,6 +215,7 @@ module Studio
   # The name the signed-in user nav prints, and the signed-out button's label.
   # Both defaults render the navbar byte-identical to before. The engine has no
   # I18n catalogue, so the label is plain config rather than a locale key.
+  # The label also words the engine's auth pages (lib/studio/auth_labels.rb).
   # Rules: lib/studio/navbar_identity.rb.
   #
   #   config.navbar_user_name = :player_name                          # a method on the user
@@ -950,6 +965,25 @@ module Studio
   # that intentionally break the contract).
   mattr_accessor :validate_user_contract, default: true
 
+  # Does the host load ActiveRecord at all? True for every app that requires
+  # `rails/all` or `active_record/railtie` (all the engine's database-backed
+  # consumers); false for a FOOTER-ONLY consumer, an app with no database that
+  # takes the engine for its site footer and nothing else (docs/SITE_FOOTER.md,
+  # "An app with no database").
+  #
+  # The RAILTIE, not ActiveRecord::Base: the railtie is what an app chooses in
+  # config/application.rb, it is defined at require time (before any engine
+  # initializer runs), and asking for it autoloads nothing.
+  #
+  # Three things key off it, each only when it reads false (Studio::Engine):
+  # the user-contract check is skipped, the engine's ActiveRecord-dependent
+  # app/ roots are kept out of eager loading, and
+  # `studio_engine:install:migrations` is a no-op that exits 0. An app WITH
+  # ActiveRecord sees none of them change.
+  def self.active_record?
+    defined?(::ActiveRecord::Railtie) ? true : false
+  end
+
   # Only methods that consumers must explicitly define are checked here.
   # Column accessors (#email, #name, #role) are NOT validated because
   # ActiveRecord defines them lazily — they don't appear on `.instance_methods`

data/lib/tasks/studio_trash.rake

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Find and restore objects Studio::S3.delete or the StudioTrashS3 Active Storage
+# service moved under trash/. The bucket's lifecycle rule expires trash/ after
+# three days; after that there is nothing to restore.
+#
+#   bin/rails "studio:trash:list"                       # everything in trash
+#   bin/rails "studio:trash:list[avatars/abc.png]"      # one key's trash copies
+#   bin/rails "studio:trash:restore[trash/2026-10-01/1759302000123/avatars/abc.png]"
+#
+# The bucket is Studio::S3's. SERVICE=<storage.yml service name> reads an Active
+# Storage service's bucket instead (e.g. SERVICE=r2_production). FORCE=1 lets a
+# restore overwrite an object that already sits at the original key.
+#
+# Logic lives in Studio::S3::Trash (unit-tested); these tasks only resolve the
+# bucket and print.
+# Guarded like studio_email.rake and studio_ses.rake: an app that also loads
+# this file must not register a second copy of each action.
+unless Rake::Task.task_defined?("studio:trash:restore")
+  namespace :studio do
+    namespace :trash do
+      def studio_trash_target
+        name = ENV["SERVICE"].to_s.strip
+        if name.empty?
+          { client: Studio::S3.client, bucket: Studio::S3.bucket, key_prefix: Studio::S3.key_prefix }
+        else
+          service = ActiveStorage::Blob.services.fetch(name.to_sym)
+          { client: service.client.client, bucket: service.bucket.name, key_prefix: "" }
+        end
+      end
+
+      desc "List trashed objects, optionally only those deleted from KEY"
+      task :list, [:key] => :environment do |_task, args|
+        target = studio_trash_target
+        key = args[:key].to_s.strip
+        # A Studio::S3 caller thinks in LOGICAL keys; the trash records the real
+        # one. Match either, so the key you passed to delete finds its copy.
+        wanted = key.empty? ? nil : [key, "#{target[:key_prefix]}#{key}"].uniq
+        objects = Studio::S3::Trash.list(client: target[:client], bucket: target[:bucket])
+        objects = objects.select { |object| wanted.include?(Studio::S3::Trash.original_key(object.key)) } if wanted
+
+        puts "#{objects.size} trashed object(s) in #{target[:bucket]}#{" for #{key}" if wanted}"
+        objects.each do |object|
+          puts "#{object.key}  #{object.size} bytes  #{object.last_modified&.utc&.iso8601}"
+        end
+      end
+
+      desc "Copy TRASH_KEY back to its original key (FORCE=1 overwrites)"
+      task :restore, [:trash_key] => :environment do |_task, args|
+        trash_key = args[:trash_key].to_s.strip
+        abort "usage: studio:trash:restore[trash/<date>/<ms>/<key>]" if trash_key.empty?
+
+        target = studio_trash_target
+        overwrite = %w[1 true yes].include?(ENV["FORCE"].to_s.downcase)
+        begin
+          original = Studio::S3::Trash.restore!(client: target[:client], bucket: target[:bucket],
+                                                trash_key: trash_key, overwrite: overwrite)
+          attributes = Studio::S3::Trash.blob_attributes(client: target[:client], bucket: target[:bucket],
+                                                         trash_key: trash_key)
+        rescue Studio::S3::Error => error
+          abort "studio:trash:restore: #{error.message}"
+        end
+
+        puts "Restored #{target[:bucket]}/#{original}"
+        puts
+        puts "If this was an Active Storage object, its blob row is gone. Recreate it and re-attach:"
+        puts
+        puts "  blob = ActiveStorage::Blob.create!("
+        puts "    key: #{attributes[:key].inspect},"
+        puts "    filename: #{(attributes[:filename] || 'FILENAME').inspect},"
+        puts "    content_type: #{attributes[:content_type].inspect},"
+        puts "    byte_size: #{attributes[:byte_size]},"
+        puts "    checksum: #{attributes[:checksum].inspect},"
+        puts "    service_name: #{(ENV['SERVICE'].to_s.strip.empty? ? 'SERVICE_NAME' : ENV['SERVICE'].strip).inspect}"
+        puts "  )"
+        puts "  record.photo.attach(blob)   # the record and attachment it belonged to"
+        puts
+        puts "A nil checksum means a multipart upload, whose ETag is not an MD5. Compute it"
+        puts "from the restored bytes: Digest::MD5.base64digest(<downloaded bytes>)."
+      end
+    end
+  end
+end

data/studio-engine.gemspec

@@ -22,7 +22,14 @@ Gem::Specification.new do |spec|
   # read by bin/e2e-executed-set-check and test/lib/e2e_lane_contract_test.rb. It is
   # the only thing under config/, and it has no meaning in a consuming app, so it is
   # excluded rather than shipped. (e2e/, bin/ and test/ were never in this list.)
-  spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "db/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE"] - ["config/e2e_lane.yml"]
+  #
+  # docs/SITE_FOOTER.md and docs/BOOKING.md ship because consumers cite them from
+  # their own initializers ("docs/SITE_FOOTER.md is the contract"), and a
+  # citation should resolve in the installed gem, not only on GitHub. The rest of
+  # docs/ is the engine's own operating material. Guarded by
+  # test/lib/gemspec_ships_footer_docs_test.rb.
+  spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "db/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE",
+                   "docs/SITE_FOOTER.md", "docs/BOOKING.md"] - ["config/e2e_lane.yml"]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "rails", ">= 7.2", "< 8.2"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.84.0
+  version: 0.86.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -541,6 +541,7 @@ files:
 - app/views/studio/site_footer/_footer.html.erb
 - app/views/studio/site_footer/_link.html.erb
 - app/views/studio/site_footer/_map.html.erb
+- app/views/studio/site_footer/_map_assets.html.erb
 - app/views/studio/site_footer/_social_icon.html.erb
 - app/views/studio/site_identities/edit.html.erb
 - app/views/style/_host.html.erb
@@ -584,9 +585,13 @@ files:
 - db/migrate/20260902000001_create_studio_knowledge_expectations.rb
 - db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb
 - db/migrate/20260930120000_create_studio_site_identities.rb
+- docs/BOOKING.md
+- docs/SITE_FOOTER.md
+- lib/active_storage/service/studio_trash_s3_service.rb
 - lib/generators/studio/site_identity/site_identity_generator.rb
 - lib/studio-engine.rb
 - lib/studio.rb
+- lib/studio/auth_labels.rb
 - lib/studio/booking.rb
 - lib/studio/cable.rb
 - lib/studio/color_scale.rb
@@ -617,6 +622,7 @@ files:
 - lib/studio/public_user.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb
+- lib/studio/s3/trash.rb
 - lib/studio/session_fingerprint.rb
 - lib/studio/session_state.rb
 - lib/studio/sidebar_sections.rb
@@ -627,6 +633,7 @@ files:
 - lib/studio/version.rb
 - lib/tasks/studio_email.rake
 - lib/tasks/studio_ses.rake
+- lib/tasks/studio_trash.rake
 - studio-engine.gemspec
 - tailwind/studio.tailwind.config.js
 homepage: https://github.com/McRitchie-Studio/studio-engine