studio-engine 0.76.3 → 0.77.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c352381b0778909cd1798ba2d81abf435f1c2e668198ac38fdae33310d65d8c
-  data.tar.gz: 6a80ed76a9748b246df94016572aa1b1b470360c8938390acaef92342a4d1350
+  metadata.gz: 0c579a6d057a79eb540fee2347d6000c6c5af80273e61efdbd2e1d8eda173214
+  data.tar.gz: 726c8217e6f23e277af7f3fcc215885d7bfed504ee2a215b574aa5775986ffad
 SHA512:
-  metadata.gz: b57498e85f26bfe1ba051381c0411f0f5161513726ed9fbd6aa4769e0bd3767ec962d0f007ac09ad2326e9a97fb05d73e17e122ef5b779f6cc8e48dd923c3c24
-  data.tar.gz: 0a17dcfaa72bd771c57cacb04ee9f2f3b82baf5839bc9b739216bc1d6fc1e96b456bc68b645b0865bca9569d64b1abd5327a4e779ff74c6af4cf740776f8f14e
+  metadata.gz: 72b688c3d92118f08ea7ba2263db3973fedeec0d16d07d9f45296c9c68fc581e6f5d56f30eb6d3375f0dedff9d1330de6ed992f5080995ddb44aa0ec6b79eae1
+  data.tar.gz: cf4ed66373933628dccd7eeb8e59164da68cfcc25f3407befff234ebd18ce2793a2d60bfb71daae219ec8980f5f7ada6b3b34f092697d4dbcb8894f451acd162

data/CHANGELOG.md

@@ -4,6 +4,21 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.77.0 — 2026-09-26
+
+### Added
+
+- **`Studio::S3` runs on Cloudflare R2, or any S3-compatible endpoint.** Four new
+  settings, all nil by default: `s3_endpoint`, `s3_access_key_id` +
+  `s3_secret_access_key` (passed to the client as a pair, so an app can hold its
+  R2 keys beside the `AWS_*` ones during a cutover; half a pair raises), and
+  `s3_public_url`, the base public objects are served from. Unset, every app gets
+  the same client and the same amazonaws.com URLs as before. On an endpoint with
+  no public base, `url` raises `NotConfigured` instead of building a URL R2 would
+  refuse, and `upload` still writes but returns `nil`. Proven live against an R2
+  bucket: upload, download, exists, list, signed URL (200) and delete, with the
+  anonymous endpoint read refused.
+
 ## 0.76.3 — 2026-09-23
 
 ### Fixed

data/README.md

@@ -838,6 +838,24 @@ config.s3_key_prefix    = "mcritchie-industries/"
 logical keys and never see it. Unset (the default) leaves keys byte-identical to
 what every already-shipped app wrote.
 
+### S3-compatible storage (Cloudflare R2)
+
+`Studio::S3` talks to any S3-compatible endpoint. The McRitchie fleet is moving
+to R2 (one account, McRitchie Studio's); an app switches in its initializer:
+
+```ruby
+config.s3_endpoint          = ENV["R2_ENDPOINT"]   # https://<account>.r2.cloudflarestorage.com
+config.s3_region            = "auto"
+config.s3_access_key_id     = ENV["R2_ACCESS_KEY_ID"]
+config.s3_secret_access_key = ENV["R2_SECRET_ACCESS_KEY"]
+config.s3_public_url        = ENV["R2_PUBLIC_URL"] # custom domain on this env's bucket
+```
+
+All four are nil by default, and nil is AWS exactly as before. The keys must be
+set as a pair. R2 serves nothing anonymously from its S3 endpoint, so with an
+endpoint and no `s3_public_url`, `Studio::S3.url` raises `NotConfigured` and
+`upload` writes but returns `nil`; serve private objects with `signed_url`.
+
 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/lib/studio/s3.rb

@@ -15,17 +15,34 @@ module Studio
         opts[:content_type] = content_type if content_type
         opts[:cache_control] = cache_control if cache_control
         client.put_object(**opts)
-        url(key: key)
+        public_url? ? url(key: key) : nil
       end
 
       def download(key:)
         client.get_object(bucket: bucket, key: full_key(key)).body.read
       end
 
+      # The PUBLIC URL of an object. On AWS (no endpoint) it is the bucket's
+      # virtual-hosted amazonaws.com URL, byte-identical to every version before
+      # endpoints existed. On an S3-compatible endpoint it is Studio.s3_public_url
+      # plus the key, and without that base it RAISES: R2's S3 endpoint answers no
+      # anonymous request, so any URL built from it would be a broken image in an
+      # inbox, not an error anyone sees. Private objects want signed_url.
       def url(key:)
+        base = Studio.s3_public_url.to_s
+        return "#{base.chomp("/")}/#{full_key(key)}" unless base.empty?
+        raise NotConfigured, "Studio.s3_public_url not set: #{endpoint} serves no public URL (use signed_url for private objects)" if endpoint
+
         "https://#{bucket}.s3.#{region}.amazonaws.com/#{full_key(key)}"
       end
 
+      # Whether url can answer. upload asks this so an app with only private
+      # objects (a data room on R2 with no public domain) can still write:
+      # upload returns nil there instead of raising AFTER the object landed.
+      def public_url?
+        endpoint.nil? || !Studio.s3_public_url.to_s.empty?
+      end
+
       def signed_url(key:, expires_in: 3600)
         require "aws-sdk-s3"
         Aws::S3::Presigner.new(client: client).presigned_url(:get_object, bucket: bucket, key: full_key(key), expires_in: expires_in)
@@ -93,11 +110,39 @@ module Studio
         Studio.s3_region
       end
 
+      # The S3-compatible endpoint (R2: https://<account>.r2.cloudflarestorage.com),
+      # or nil for AWS. Blank reads as unset, so an empty ENV var cannot point the
+      # client at "".
+      def endpoint
+        value = Studio.s3_endpoint.to_s
+        value.empty? ? nil : value
+      end
+
       def client
         @client ||= begin
           require "aws-sdk-s3"
-          Aws::S3::Client.new(region: region)
+          Aws::S3::Client.new(**client_options)
+        end
+      end
+
+      # Only what is configured is passed, so an unconfigured app builds exactly
+      # the client it always did: region alone, the SDK's default credential chain.
+      # Keys are passed as a PAIR or not at all; half a pair is a configuration
+      # error, and falling back to the default chain would silently write with
+      # whatever AWS_* key the dyno happens to hold.
+      def client_options
+        opts = { region: region }
+        opts[:endpoint] = endpoint if endpoint
+        id = Studio.s3_access_key_id.to_s
+        secret = Studio.s3_secret_access_key.to_s
+        if id.empty? != secret.empty?
+          raise NotConfigured, "Studio.s3_access_key_id and s3_secret_access_key must be set together"
+        end
+        unless id.empty?
+          opts[:access_key_id] = id
+          opts[:secret_access_key] = secret
         end
+        opts
       end
 
       def reset!

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.76.3"
+  VERSION = "0.77.0"
 end

data/lib/studio.rb

@@ -616,6 +616,30 @@ module Studio
   # A trailing slash is added if you leave it off.
   mattr_accessor :s3_key_prefix, default: nil
 
+  # S3-COMPATIBLE STORAGE (Cloudflare R2). All four default nil, and nil means
+  # AWS exactly as before: the SDK's own endpoint, its default credential chain
+  # (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY), and the virtual-hosted
+  # amazonaws.com URL. An app moves to R2 by setting them, typically from ENV:
+  #
+  #   config.s3_endpoint          = ENV["R2_ENDPOINT"]   # https://<account>.r2.cloudflarestorage.com
+  #   config.s3_region            = "auto"               # R2's only region
+  #   config.s3_access_key_id     = ENV["R2_ACCESS_KEY_ID"]
+  #   config.s3_secret_access_key = ENV["R2_SECRET_ACCESS_KEY"]
+  #   config.s3_public_url        = ENV["R2_PUBLIC_URL"] # https://assets.example.com
+  #
+  # Explicit keys exist so an app can hold its R2 pair BESIDE its AWS pair
+  # during a cutover (Active Storage may still mirror to S3) without the two
+  # fighting over the same AWS_* variables.
+  #
+  # s3_public_url is the base public objects are served from — a custom domain
+  # or r2.dev URL attached to THIS environment's bucket. R2's S3 endpoint
+  # serves nothing anonymously, so with an endpoint and no public base there is
+  # no public URL to give, and Studio::S3.url says so rather than inventing one.
+  mattr_accessor :s3_endpoint,          default: nil
+  mattr_accessor :s3_access_key_id,     default: nil
+  mattr_accessor :s3_secret_access_key, default: nil
+  mattr_accessor :s3_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.76.3
+  version: 0.77.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails