active_storage-cloud_transformations 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9ffa075ea0830d2c76a32bd0ebe9e86799859e0bc741ce3128b217b7dc25b79
-  data.tar.gz: bfcd4614b55c2cba811263826d178d661bcefb91f50d53996721ab8792ee38d6
+  metadata.gz: 438e440734f18e87ae9dd8df79b2cfecf1dc4f331a2cabbb8c124ae9a261a88b
+  data.tar.gz: c68578ee96799bbca6ff5b7372986d0856ebe54884b0c25a10d7454b1a2bc132
 SHA512:
-  metadata.gz: a2fafbe7f41f231d20303261ed9863e56ba33b7de17ba009374934e8d93fbcddd7091a58f572fad3667a1efdd189ffa608e6a68a9b8386f1cc559d635ee7906d
-  data.tar.gz: 40b5993c2cc8933c6bae0cd9f61c144aefdc3996b0356889beb882fe387e69c21d339ac5a663e00f4ebe6d4c8f308930b4e9e20c9b5849ade857d85505b72043
+  metadata.gz: f1cf577c3d076ce7cf6cbdc1e06b138c99bd3d1bd3f46307b3411857f2230100b50f4519457d61d4d184fc17fc05823b8807cfd83bef6e158ae52446f4cae97b
+  data.tar.gz: 254f1204b8439c1e7ac506d273f03339c58f5ace31b8049f0b6126bc728651e567d89a1832bda308088537fd42178bde614222dcabf9b58496c7240e75828315

data/.env.example

@@ -0,0 +1,6 @@
+# S3 credentials for testing
+AWS_S3_URI=s3://YOUR_ACCESS_KEY_ID:YOUR_SECRET_ACCESS_KEY@YOUR_REGION.amazonaws.com/YOUR_BUCKET
+
+# Optional: Crucible transformation service endpoint
+# Tests will mock the endpoint without this
+# CRUCIBLE_ENDPOINT=https://crucible.example.com/

data/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      max-parallel: 1
+      matrix:
+        gemfile: ['rails_7.2', 'rails_8.0', 'rails_8.1']
+        ruby-version: ['3.2', '3.3', '3.4']
+
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
+      AWS_S3_URI: ${{ secrets.AWS_S3_URI }}
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -5,11 +5,11 @@
 /doc/
 /pkg/
 /spec/reports/
-/spec/storage.yml
 /tmp/
 /Gemfile.lock
 /.ruby-version
 /.ruby-gemset
 /.byebug_history
 .rspec_status
-
+/.env
+/.env.local

data/Appraisals

@@ -1,8 +1,12 @@
-appraise "rails-6.1" do
-  gem "rails", "6.1"
+appraise "rails-7.2" do
+  gem "rails", "7.2"
 end
 
-appraise "rails-7.0" do
-  gem "rails", "7.0"
+appraise "rails-8.0" do
+  gem "rails", "8.0"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "8.1"
 end
 

data/CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`active_storage-cloud_transformations` is a Ruby gem that extends Rails' ActiveStorage to delegate image variant and video preview generation to external cloud services (via AWS Lambda API endpoints) rather than processing on-server. This enables more efficient handling of resource-intensive image/video transformations.
+
+**Key Components:**
+- `Variant` class: Handles image and video variant generation via cloud processing
+- `Preview` class: Generates preview images for video files via cloud service
+- Test suite uses a dummy Rails application to test the gem in a realistic environment
+
+## Development Setup
+
+**Ruby version:** 3.3.4 (specified in .ruby-version)
+
+**Install dependencies:**
+```bash
+bundle install
+bin/setup
+```
+
+## Common Commands
+
+**Run all tests:**
+```bash
+bundle exec rake spec
+```
+
+**Run a specific test file:**
+```bash
+bundle exec rspec spec/active_storage-cloud_transformations_spec.rb
+```
+
+**Run a specific test:**
+```bash
+bundle exec rspec spec/active_storage-cloud_transformations_spec.rb:5
+```
+
+**Interactive console:**
+```bash
+bin/console
+```
+
+**Install gem locally for testing:**
+```bash
+bundle exec rake install
+```
+
+**Run linter/formatter (if configured):**
+Uses RSpec configuration in `.rspec` with documentation format and color output enabled.
+
+## Architecture Notes
+
+### Cloud API Integration
+
+Both `Variant` and `Preview` classes post transformation requests to an AWS Lambda API endpoint at `https://huuabwxpqf.execute-api.us-west-2.amazonaws.com/prod/`. They expect:
+- Image variants: POST to `/image/variant`
+- Video variants: POST to `/video/variant`
+- Video previews: POST to `/video/preview`
+- Expected response: HTTP 201 (or 504 for timeouts when `ignore_timeouts: true`)
+
+### Key Processing Patterns
+
+1. **Variant Processing** (`Variant#process`):
+   - Creates an output blob with placeholder byte_size and checksum
+   - Sets `metadata[:analyzed] = true` to suppress automatic analysis
+   - Calls the cloud service via `run_crucible_job`
+   - Schedules `ActiveStorage::AnalyzeJob` for post-processing
+   - Handles race conditions with retry on `RecordNotUnique`
+
+2. **Variant Reprocessing** (`Variant#reprocess`):
+   - Reprocesses an existing variant record using the cloud service
+   - Useful when original blob changes or service needs re-execution
+
+3. **Preview Processing** (`Preview#process` and `Preview#reprocess`):
+   - Creates both a preview image blob and a variant of that image
+   - Sets `metadata[:analyzed] = true` on both blobs
+   - Calls cloud service to generate the preview
+   - Schedules analysis jobs for both generated blobs
+
+### Test Configuration & Strategy
+
+**Test Environment:**
+- Tests make real HTTP calls to the AWS Lambda API endpoint and S3
+- Requires valid AWS credentials: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_S3_BUCKET`
+- The Lambda endpoint must be accessible and functional for tests to pass
+
+**Test Fixtures & Helpers:**
+- Uses RSpec with `focus` filter enabled (set `focus: true` on examples to isolate)
+- Requires a dummy Rails application in `spec/dummy/`
+- Test storage service configurations loaded from `spec/storage.yml` (S3 service)
+- ActiveStorage verifier and current host set in `spec_helper.rb`
+- Custom matchers available in `spec/support/time_duration_matchers.rb`:
+  - `take_more_than(duration)` - asserts a block takes longer than the specified duration
+  - `take_less_than(duration)` - asserts a block completes faster than the specified duration
+
+## Important Implementation Details
+
+- Transformation parameters are extracted from `variation.transformations`, specifically `resize_to_limit`, `rotation`, and `format`
+- Output blobs are created with placeholder checksum (0) since cloud service calculates the actual value
+- The gem suppresses ActiveStorage's automatic blob analysis by pre-setting `metadata[:analyzed]`
+- HTTP requests use `Net::HTTP` directly for cloud API communication
+- The gem extends `ActiveStorage::VariantWithRecord` and `ActiveStorage::Preview`
+
+## Dependencies
+
+Key dependencies (see `Gemfile`):
+- `rails`: Rails framework with ActiveStorage
+- `rspec`: Testing framework
+- `aws-sdk-s3`: For S3 storage service support
+- `appraisal`: For testing against multiple Rails versions (see `Appraisals` file)
+- `sqlite3`: Test database
+
+## Git Workflow
+
+The main branch is `master`. Work on feature branches and create pull requests for review.

data/Gemfile

@@ -1,14 +1,3 @@
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in active_storage-cloud_transformations.gemspec
 gemspec
-
-gem "rake"
-gem "rspec", "~> 3.0"
-gem "sqlite3", "~> 1.4"
-gem "bootsnap", require: false
-gem "rails"
-gem "byebug"
-gem "aws-sdk-s3"
-gem "appraisal"
-

data/README.md

@@ -1,40 +1,184 @@
 # ActiveStorage::CloudTransformations
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/active_storage/cloud_transformations`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Rails gem that extends ActiveStorage to generate image variants and video previews via external cloud services (like AWS Lambda) instead of processing them locally on your server.
 
-TODO: Delete this and the text above, and describe your gem
+## Features
 
-## Installation
+- **Offload image and video processing** to cloud services, reducing server load
+- **Support for variants** - Transform images with custom dimensions, formats, and rotations
+- **Support for previews** - Generate preview images from video files
+- **Flexible configuration** - Easily point to your own cloud transformation service
+- **Per-instance endpoints** - Route different requests to different endpoints based on your model logic
+- **Presigned URLs** - Remove the need for your cloud service to have direct S3 access
+- **Non-blocking** - Processing happens asynchronously without blocking request handling
+- **Rails 7.2+** - Works with modern Rails and ActiveStorage
 
-Add this line to your application's Gemfile:
+## Why Cloud Transformations?
+
+Processing large images and videos locally consumes significant CPU resources. This gem lets you delegate that work to dedicated cloud services, allowing your Rails application to focus on what it does best. You get:
+
+- Reduced server CPU usage
+- Faster request handling
+- Scalable processing as your media grows
+
+## Configuration
+
+### Global Configuration
+
+Create an initializer at `config/initializers/active_storage_cloud_transformations.rb`:
 
 ```ruby
-gem 'active_storage-cloud_transformations'
+ActiveStorage::CloudTransformations.configure do |config|
+  # The cloud service endpoint (default: "https://huuabwxpqf.execute-api.us-west-2.amazonaws.com/prod")
+  config.crucible_endpoint = ENV.fetch("CRUCIBLE_ENDPOINT", "https://crucible.example.com/prod")
+
+  # Use presigned URLs instead of S3 paths (default: false)
+  # When enabled, your cloud service doesn't need direct S3 access
+  config.use_presigned_urls = true
+
+  # Presigned URL expiration in seconds (default: 3600)
+  config.presigned_url_expiration = 7200
+end
 ```
 
-And then execute:
+### Per-Instance Endpoint Configuration
 
-    $ bundle install
+You can configure different endpoints for different model instances by defining a `crucible_endpoint` method on your model:
 
-Or install it yourself as:
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+
+  def crucible_endpoint
+    # Route premium users to a different endpoint
+    if premium?
+      "https://premium.crucible.example.com/prod"
+    elsif region == "eu"
+      "https://eu.crucible.example.com/prod"
+    else
+      # Return nil to use the global config
+      nil
+    end
+  end
+end
+```
 
-    $ gem install active_storage-cloud_transformations
+When processing attachments, the gem will:
+1. Check if the model defines a `crucible_endpoint` method
+2. Use that endpoint if it returns a non-nil value
+3. Fall back to the global `config.crucible_endpoint` otherwise
 
 ## Usage
 
-TODO: Write usage instructions here
+### Image Variants
+
+Generate image variants just like you normally would with ActiveStorage. The cloud service will handle the transformation:
+
+```ruby
+@user = User.find(1)
+
+# Generate a variant (will be processed by cloud service)
+@user.avatar.variant(resize_to_limit: [100, 100]).processed
+```
+
+### Video Previews
+
+Generate preview images from video files:
+
+```ruby
+@video = Video.find(1)
+
+# Generate a preview image from the video
+@video.file.preview(resize_to_limit: [160, 160]).processed
+
+# Access the generated preview image
+image_url = @video.file.preview_image.url
+```
+
+### Supported Transformations
+
+The cloud service receives the following information via HTTP POST:
+
+**For image variants:**
+- `blob_url` - URL to the source image (presigned GET URL or S3 path)
+- `dimensions` - Target dimensions (e.g., "100x100")
+- `rotation` - Rotation angle in degrees
+- `variant_url` - Where to upload the processed variant (presigned PUT URL or S3 path)
+- `format` - Output format (e.g., "webp", "jpeg")
+
+**For video previews:**
+- `blob_url` - URL to the source video (presigned GET URL or S3 path)
+- `dimensions` - Dimensions for the preview image
+- `rotation` - Rotation angle in degrees
+- `preview_image_url` - Where to upload the generated preview image (presigned PUT URL or S3 path)
+- `preview_image_variant_url` - Where to upload the preview image variant (presigned PUT URL or S3 path)
+
+**Note:** When `use_presigned_urls` is enabled, all URLs include AWS signature query parameters. When disabled, URLs are S3 paths without query parameters, requiring your cloud service to have S3 credentials.
+
+## How It Works
+
+1. When you request a variant or preview, ActiveStorage creates blob records
+2. This gem intercepts the process and makes an HTTP POST request to your cloud service
+3. The request includes:
+   - Source media URL (presigned GET URL or S3 path)
+   - Destination URL for the processed file (presigned PUT URL or S3 path)
+   - Transformation parameters (dimensions, format, rotation, etc.)
+4. Your cloud service performs the transformation:
+   - **With presigned URLs:** Downloads from the GET URL, transforms, uploads to the PUT URL
+   - **Without presigned URLs:** Accesses S3 directly using its own credentials
+5. The gem receives a 201 confirmation and marks the variant as processed
+6. Future requests for the same variant are served from the cache (already in S3)
+
+### Presigned URLs vs S3 Paths
+
+**Presigned URLs (recommended):**
+- Your cloud service doesn't need S3 credentials
+- More secure - temporary, scoped access
+- Works with any HTTP client
+- Enable with `config.use_presigned_urls = true`
+
+**S3 Paths (legacy):**
+- Your cloud service needs AWS credentials with S3 access
+- URLs are simple paths like `s3://bucket/key`
+- Default behavior for backward compatibility
+
+## Storage Requirements
+
+This gem requires **S3 as the storage service** for your Rails application. It does _not_ work with the local disk service.
+
+**For your Rails application:**
+- Configure ActiveStorage to use S3
+- Needs S3 credentials to generate presigned URLs (when enabled) or direct S3 access
+
+**For your cloud transformation service:**
+- **With presigned URLs enabled:** No S3 credentials needed - the service uses presigned URLs
+- **Without presigned URLs:** Requires AWS credentials with S3 read/write access
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Running Tests Locally
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
 
-## Contributing
+2. Edit `.env` with your S3 credentials:
+   ```bash
+   AWS_S3_URI=s3://YOUR_ACCESS_KEY_ID:YOUR_SECRET_ACCESS_KEY@YOUR_REGION.amazonaws.com/YOUR_BUCKET
+   ```
+
+3. Run the tests:
+   ```bash
+   bundle exec rspec
+   ```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/active_storage-cloud_transformations.
+By default, requests are mocked in tests. Set `CRUCIBLE_ENDPOINT` in your `.env` file to point to a real service for full integration testing.
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at [https://github.com/botandrose/active_storage-cloud_transformations](https://github.com/botandrose/active_storage-cloud_transformations).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/active_storage-cloud_transformations.gemspec

@@ -9,7 +9,6 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{Generate ActiveStorage Variants and Previews via external cloud services, rather than on-server.}
   spec.homepage      = "https://github.com/botandrose/active_storage-cloud_transformations"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
 
@@ -22,5 +21,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activestorage", ">=6.1"
+  spec.add_dependency "activestorage", ">=7.2"
+
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "bootsnap"
+  spec.add_development_dependency "rails"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "aws-sdk-s3"
+  spec.add_development_dependency "appraisal"
+  spec.add_development_dependency "dotenv"
 end

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "7.2"
+
+gemspec path: "../"