fileboost 0.2.0.pre → 0.2.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e41eb33a273bb73c63284223566b994fca3583c8e72c82c0dde3ffc6c19b9adc
-  data.tar.gz: 21a0c4088aea9ac6eeb3bb82310d850b99fa718155c0b253798aa5343da46caa
+  metadata.gz: fd68355a3cdd26c34422cd082cb8795b10e609a8edbda257982974173a338170
+  data.tar.gz: 9f29b3da4b48d17b58bb2f70565e383ad184758269b8ba51245fb99ebeaa53f7
 SHA512:
-  metadata.gz: 11b1349683d425b709d351ca165394f86f6ce7db6e71af7359d8c10a8532d2f31843464fa82b4a7da4a98ba792601b97cfa86fa02d08a36e8fe5528defe8622f
-  data.tar.gz: df922239b99ecbd4e87e6272908bc85f1ecf6e303faa704e5f5843a991ad783df29f2b6eeccd961a140342b1c7ab6e560ed93eca3222d9a4ae89c3fd690553e6
+  metadata.gz: 50349d3d91cc8e16b077654a290320cc61d5588f8d070a2b9dab5a91cb2201b55b011ea675e2c1485276db30b12e5a89252d5454911d1e5b5ea3695ea56b8801
+  data.tar.gz: 6ec42cf3b8ef2c80b8fb2b24908c83b219056016f1a1cbf588c9cb9dfed96ed2965cf37a99c108343fb38bb79776b6bf903347802e31a2212ef8a214c040093d

data/README.md

@@ -4,13 +4,46 @@
 
 Fileboost is a Rails gem that provides seamless integration with the Fileboost.dev image optimization service. It offers drop-in replacement helpers for Rails' native image helpers with automatic optimization, HMAC authentication, and comprehensive transformation support for ActiveStorage objects.
 
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Drop-in Replacement (Recommended)](#drop-in-replacement-recommended)
+  - [Manual Helper Method](#manual-helper-method)
+  - [URL Generation](#url-generation)
+  - [Transformation Options](#transformation-options)
+  - [Parameter Aliases](#parameter-aliases)
+  - [ActiveStorage Support](#activestorage-support)
+  - [ActiveStorage Variants (NEW in v0.2.0)](#activestorage-variants-new-in-v020)
+    - [Variant Transformation Mapping](#variant-transformation-mapping)
+    - [Combining Variants with Custom Options](#combining-variants-with-custom-options)
+  - [Responsive Images](#responsive-images)
+- [Error Handling](#error-handling)
+- [Security](#security)
+- [Development](#development)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
 ## Features
 
-- 🚀 **Drop-in replacement** for Rails `image_tag` and `url_for` helpers
+- 🚀 **Drop-in replacement** for Rails `image_tag` with zero code changes (NEW in v0.2.0)
+- 🎨 **Full ActiveStorage Variant support** with automatic transformation mapping (NEW in v0.2.0)
 - 🔒 **Secure HMAC authentication** with Fileboost.dev service
 - 📱 **ActiveStorage only** - works exclusively with ActiveStorage attachments
 - 🎛️ **Comprehensive transformations** - resize, quality, format conversion, and more
 - 🔧 **Simple configuration** - just project ID and token required
+- 🔄 **Automatic fallback** - non-ActiveStorage images work exactly as before
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 7.1+
+- ActiveStorage
 
 ## Installation
 
@@ -43,11 +76,59 @@ export FILEBOOST_PROJECT_ID="your-project-id"
 export FILEBOOST_TOKEN="your-secret-token"
 ```
 
+Or configure directly in your initializer:
+
+```ruby
+# config/initializers/fileboost.rb
+Fileboost.configure do |config|
+  config.project_id = ENV["FILEBOOST_PROJECT_ID"]
+  config.token = ENV["FILEBOOST_TOKEN"]
+  
+  # Optional: Enable drop-in replacement for Rails image_tag (default: false)
+  config.patch_image_tag = true
+end
+```
+
 ## Usage
 
-### Basic Image Tag
+### Drop-in Replacement (Recommended)
 
-Replace `image_tag` with `fileboost_image_tag` for ActiveStorage objects:
+Enable `patch_image_tag` in your configuration to automatically optimize ActiveStorage images with your existing `image_tag` calls:
+
+```ruby
+# config/initializers/fileboost.rb
+Fileboost.configure do |config|
+  config.project_id = ENV["FILEBOOST_PROJECT_ID"]
+  config.token = ENV["FILEBOOST_TOKEN"]
+  config.patch_image_tag = true  # Enable automatic optimization
+end
+```
+
+With this enabled, your existing Rails code automatically gets Fileboost optimization:
+
+```erb
+<!-- This now automatically uses Fileboost for ActiveStorage objects -->
+<%= image_tag user.avatar, resize: { w: 300, h: 300 }, alt: "Avatar" %>
+<%= image_tag post.featured_image, resize: { width: 800, quality: 85 }, class: "hero" %>
+
+<!-- ActiveStorage variants work seamlessly -->
+<%= image_tag user.avatar.variant(resize_to_limit: [100, 100]), alt: "Thumbnail" %>
+<%= image_tag post.image.variant(:thumb), alt: "Post thumbnail" %>
+
+<!-- Non-ActiveStorage images work exactly as before -->
+<%= image_tag "/assets/logo.png", alt: "Logo" %>
+<%= image_tag "https://example.com/image.jpg", alt: "External" %>
+```
+
+**Benefits:**
+- Zero code changes required for existing ActiveStorage images
+- Full ActiveStorage variant support with automatic transformation mapping
+- Automatic fallback to Rails behavior for non-ActiveStorage assets
+- Gradual migration path - enable/disable with single configuration option
+
+### Manual Helper Method
+
+Alternatively, use `fileboost_image_tag` explicitly for ActiveStorage objects:
 
 ```erb
 <!-- Before (Rails) -->
@@ -104,7 +185,7 @@ fileboost_image_tag(image, resize: { w: 400, h: 300, q: 85 })
 fileboost_image_tag(image, resize: { width: 400, height: 300, quality: 85 })
 ```
 
-**Note:** Avoid using the `format` parameter. Fileboost automatically selects the optimal image format (WebP, AVIF, JPEG, etc.) based on browser headers and capabilities for the best performance and compatibility.
+**🎯 Smart Optimization:** Fileboost's CDN automatically detects and delivers the optimal image format (WebP, AVIF, JPEG, etc.) based on browser capabilities, device type, and connection speed for maximum performance.
 
 ### ActiveStorage Support
 
@@ -123,6 +204,63 @@ Works seamlessly with all ActiveStorage attachment types:
 <%= fileboost_image_tag post.featured_image.blob, resize: { w: 800 } %>
 ```
 
+### ActiveStorage Variants (NEW in v0.2.0)
+
+Fileboost now provides full support for ActiveStorage variants with automatic transformation mapping:
+
+```erb
+<!-- Basic variants with automatic transformation mapping -->
+<%= image_tag user.avatar.variant(resize_to_limit: [200, 200]) %>
+<!-- ↓ Automatically becomes: w=200&h=200&fit=scale-down -->
+
+<%= image_tag post.image.variant(resize_to_fit: [400, 300]) %>
+<!-- ↓ Automatically becomes: w=400&h=300&fit=contain -->
+
+<%= image_tag hero.banner.variant(resize_to_fill: [800, 400]) %>
+<!-- ↓ Automatically becomes: w=800&h=400&fit=cover -->
+
+<!-- Complex variants with multiple transformations -->
+<%= image_tag post.image.variant(
+  resize_to_limit: [600, 400],
+  quality: 85
+) %>
+<!-- ↓ Automatically becomes: w=600&h=400&fit=scale-down&q=85 -->
+
+<!-- Named variants work seamlessly -->
+<%= image_tag user.avatar.variant(:thumb) %>
+<!-- ↓ Uses predefined variant transformations -->
+```
+
+#### Variant Transformation Mapping
+
+Fileboost automatically maps ActiveStorage variant transformations to optimized URL parameters:
+
+| ActiveStorage Variant | Fileboost Parameters | Description |
+|----------------------|---------------------|-------------|
+| `resize_to_limit: [w, h]` | `w=W&h=H&fit=scale-down` | Resize within bounds, preserving aspect ratio |
+| `resize_to_fit: [w, h]` | `w=W&h=H&fit=contain` | Resize to fit exactly, with letterboxing if needed |
+| `resize_to_fill: [w, h]` | `w=W&h=H&fit=cover` | Resize and crop to fill exactly |
+| `resize_and_pad: [w, h]` | `w=W&h=H&fit=pad` | Resize with padding |
+| `quality: 85` | `q=85` | JPEG/WebP quality (1-100) |
+| `rotate: "-90"` | `r=-90` | Rotation in degrees |
+
+
+#### Combining Variants with Custom Options
+
+You can combine variant transformations with additional Fileboost options:
+
+```erb
+<!-- Variant transformations + additional options -->
+<%= image_tag user.avatar.variant(resize_to_limit: [200, 200]), 
+    resize: { blur: 5, brightness: 110 } %>
+<!-- ↓ Combines variant params with additional blur and brightness -->
+
+<!-- Override variant parameters -->
+<%= image_tag post.image.variant(resize_to_limit: [400, 300]),
+    resize: { w: 500 } %>  
+<!-- ↓ Uses h=300&fit=scale-down from variant, but overrides width to 500 -->
+```
+
 ### Responsive Images
 
 Generate multiple sizes for responsive designs:
@@ -171,7 +309,7 @@ After checking out the repo, run:
 
 ```bash
 $ bundle install
-$ rake test
+$ bundle exec rspec
 ```
 
 To test against the dummy Rails application:
@@ -186,7 +324,7 @@ $ rails server
 Run the test suite:
 
 ```bash
-$ rake test
+$ bundle exec rspec
 ```
 
 Run RuboCop:
@@ -211,5 +349,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Support
 
-- [GitHub Issues](https://github.com/bilalbudhani/fileboost/issues)
-- [Documentation](https://github.com/bilalbudhani/fileboost/wiki)
+- [GitHub Issues](https://github.com/Fileboost/fileboost-ruby/issues)
+- [Documentation](https://github.com/Fileboost/fileboost-ruby/wiki)

data/Rakefile

@@ -2,6 +2,26 @@ require "bundler/setup"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+begin
+  require "appraisal"
+rescue LoadError
+  # Appraisal not available
+end
+
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+namespace :test do
+  desc "Run tests against all Rails versions"
+  task :all do
+    sh "bundle exec appraisal install"
+    sh "bundle exec appraisal rspec"
+  end
+
+  desc "Run tests against specific Rails version (e.g. rake test:rails[7-1])"
+  task :rails, [ :version ] do |t, args|
+    version = args[:version] || "7-2"
+    sh "bundle exec appraisal rails-#{version} rspec"
+  end
+end

data/lib/fileboost/url_builder.rb

@@ -43,7 +43,7 @@ module Fileboost
       full_path = "/#{project_id}#{asset_path}"
 
       # Extract and normalize transformation parameters
-      transformation_params = extract_transformation_params(options)
+      transformation_params = extract_transformation_params(asset, options)
 
       # Generate HMAC signature for secure authentication
       signature = Fileboost::SignatureGenerator.generate(
@@ -89,10 +89,16 @@ module Fileboost
       end
     end
 
-    def self.extract_transformation_params(options)
+    def self.extract_transformation_params(asset, options)
       params = {}
 
-      # Only handle nested resize parameter
+      # First, extract variant transformations if this is a variant
+      if asset.is_a?(ActiveStorage::VariantWithRecord)
+        variant_params = Fileboost::VariantTransformer.transform_variant_params(asset)
+        params.merge!(variant_params)
+      end
+
+      # Then handle explicit resize parameter (this can override variant params)
       if options[:resize].is_a?(Hash)
         resize_options = options[:resize]
         resize_options.each do |key, value|
@@ -117,9 +123,13 @@ module Fileboost
 
     def self.normalize_param_value(key, value)
       case key
-      when "w", "h", "q", "b", "br", "c", "r"
+      when "w", "h", "b", "br", "c", "r"
         # Numeric parameters
         value.to_i.to_s if value.to_i > 0
+      when "q"
+        # Quality parameter - validate range 1-100
+        q = value.to_i
+        (q > 0 && q <= 100) ? q.to_s : nil
       when "f"
         # Format parameter - validate against common formats
         valid_formats = %w[webp jpeg jpg png gif avif]

data/lib/fileboost/variant_transformer.rb

@@ -0,0 +1,130 @@
+module Fileboost
+  # Maps ActiveStorage variant transformations to Fileboost URL parameters
+  class VariantTransformer
+    # Maps ActiveStorage transformation operations to Fileboost parameters
+    TRANSFORMATION_MAPPING = {
+      # Resize operations
+      resize_to_limit: { fit: "scale-down" },
+      resize_to_fit: { fit: "contain" },
+      resize_to_fill: { fit: "cover" },
+      resize_and_pad: { fit: "pad" },
+
+      # Quality settings
+      quality: { param: "q" },
+
+      # Format settings
+      format: { param: "f" },
+
+      # Rotation
+      rotate: { param: "r" },
+
+      # Crop operations - need special handling
+      crop: { special: :crop_handler }
+    }.freeze
+
+    # Convert ActiveStorage variant transformations to Fileboost parameters
+    def self.transform_variant_params(variant)
+      return {} unless variant.respond_to?(:variation)
+
+      transformations = variant.variation.transformations
+      params = {}
+
+      transformations.each do |operation, value|
+        case operation
+        when :resize_to_limit, :resize_to_fit, :resize_to_fill, :resize_and_pad
+          resize_params = handle_resize_operation(operation, value)
+          params.merge!(resize_params)
+
+        when :quality
+          params["q"] = normalize_quality(value)
+
+        when :format
+          params["f"] = normalize_format(value)
+
+        when :rotate
+          params["r"] = normalize_rotation(value)
+
+        when :crop
+          crop_params = handle_crop_operation(value)
+          params.merge!(crop_params) if crop_params
+
+          # Add more transformations as needed
+        end
+      end
+
+      params
+    end
+
+    private
+
+    # Handle resize operations (resize_to_limit, resize_to_fit, etc.)
+    def self.handle_resize_operation(operation, dimensions)
+      return {} unless dimensions.is_a?(Array) && dimensions.length >= 2
+
+      width, height = dimensions[0], dimensions[1]
+      params = {}
+
+      # Set dimensions
+      params["w"] = width.to_s if width && width > 0
+      params["h"] = height.to_s if height && height > 0
+
+      # Set fit parameter based on resize operation
+      fit_mapping = TRANSFORMATION_MAPPING[operation]
+      params["fit"] = fit_mapping[:fit] if fit_mapping && fit_mapping[:fit]
+
+      params
+    end
+
+    # Handle crop operations
+    def self.handle_crop_operation(crop_params)
+      # Crop can be in different formats depending on the processor
+      # For now, we'll handle simple array format: [x, y, width, height]
+      if crop_params.is_a?(Array) && crop_params.length == 4
+        x, y, w, h = crop_params
+        return { "crop" => "#{x},#{y},#{w},#{h}" }
+      end
+
+      # Could extend this for other crop formats
+      nil
+    end
+
+    # Normalize quality value (0-100)
+    def self.normalize_quality(quality)
+      q = quality.to_i
+      return nil if q <= 0 || q > 100
+      q.to_s
+    end
+
+    # Normalize format value
+    def self.normalize_format(format)
+      # Convert to string and lowercase
+      format_str = format.to_s.downcase
+
+      # Map common format variations
+      case format_str
+      when "jpg", "jpeg"
+        "jpg"
+      when "png"
+        "png"
+      when "webp"
+        "webp"
+      when "avif"
+        "avif"
+      when "gif"
+        "gif"
+      else
+        # If it's already a recognized format, use it
+        valid_formats = %w[webp jpeg jpg png gif avif]
+        valid_formats.include?(format_str) ? format_str : nil
+      end
+    end
+
+    # Normalize rotation value
+    def self.normalize_rotation(rotation)
+      # Rotation should be a number (degrees)
+      r = rotation.to_s.gsub(/[^\d\-]/, "") # Remove non-numeric chars except minus
+      return nil if r.empty?
+      r
+    end
+  end
+end

data/lib/fileboost/version.rb

@@ -1,3 +1,3 @@
 module Fileboost
-  VERSION = "0.2.0.pre"
+  VERSION = "0.2.0.pre3"
 end

data/lib/fileboost.rb

@@ -2,6 +2,7 @@ require "fileboost/version"
 require "fileboost/config"
 require "fileboost/error_handler"
 require "fileboost/signature_generator"
+require "fileboost/variant_transformer"
 require "fileboost/url_builder"
 require "fileboost/helpers"
 require "fileboost/image_tag_patch"

data/lib/generators/fileboost/templates/INSTALL.md

@@ -9,33 +9,24 @@ config/initializers/fileboost.rb
 
 Next steps:
 
-1. Set your environment variables:
+1. Register an account at: https://fileboost.dev
+   Get your project ID and secret token
+
+2. Set your environment variables:
    export FILEBOOST_PROJECT_ID="your-project-id"
    export FILEBOOST_TOKEN="your-secret-token"
 
-2. Or configure directly in the initializer file:
-   Edit config/initializers/fileboost.rb with your credentials
-
-3. Start using Fileboost helpers in your views:
-
-   <!-- Replace image_tag with fileboost_image_tag -->
-
-   <%= fileboost_image_tag user.avatar, alt: "Avatar", resize: {width: 100, height: 100, fit: "cover"} %>
-
-   <!-- Generate optimized URLs -->
+3. Enable drop-in replacement (recommended):
+   Edit config/initializers/fileboost.rb and set:
+   config.patch_image_tag = true
 
-   <%= fileboost_url_for post.image %>
+4. Your existing image_tag calls now work with ActiveStorage images:
+   <%= image_tag user.avatar %>
+   <%= image_tag post.image.variant(resize_to_limit: [300, 200]) %>
 
-4. Supported transformation options:
-   - width, height (or w, h)
-   - quality (or q): 1-100
-   - format (or f): webp, jpeg, png, gif, avif
-   - blur (or b): 0-100
-   - brightness (or br): 0-200
-   - contrast (or c): 0-200
-   - rotation (or r): 0-359
-   - fit: cover, contain, fill, scale-down, crop, pad
+5. Or use explicit helpers:
+   <%= fileboost_image_tag user.avatar, resize: {w: 300, h: 200, fit: "cover"} %>
 
-For more information, visit: https://fileboost.dev
+For documentation, visit: https://github.com/Fileboost/fileboost-ruby
 
 ===============================================================================

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: fileboost
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre
+  version: 0.2.0.pre3
 platform: ruby
 authors:
-- bilal
+- bilal budhani
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -15,28 +15,48 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: appraisal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '2.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: combustion
   requirement: !ruby/object:Gem::Requirement
@@ -69,16 +89,16 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: '7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -141,17 +161,18 @@ files:
 - lib/fileboost/image_tag_patch.rb
 - lib/fileboost/signature_generator.rb
 - lib/fileboost/url_builder.rb
+- lib/fileboost/variant_transformer.rb
 - lib/fileboost/version.rb
 - lib/generators/fileboost/install_generator.rb
 - lib/generators/fileboost/templates/INSTALL.md
 - lib/generators/fileboost/templates/fileboost.rb
-homepage: https://github.com/bilalbudhani/fileboost-ruby
+homepage: https://github.com/Fileboost/fileboost-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/bilalbudhani/fileboost-ruby
-  source_code_uri: https://github.com/bilalbudhani/fileboost-ruby
-  changelog_uri: https://github.com/bilalbudhani/fileboost-ruby/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/Fileboost/fileboost-ruby
+  source_code_uri: https://github.com/Fileboost/fileboost-ruby
+  changelog_uri: https://github.com/Fileboost/fileboost-ruby/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib