fileboost 0.2.0.pre → 0.2.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e41eb33a273bb73c63284223566b994fca3583c8e72c82c0dde3ffc6c19b9adc
-  data.tar.gz: 21a0c4088aea9ac6eeb3bb82310d850b99fa718155c0b253798aa5343da46caa
+  metadata.gz: b09c6f264244d950aef3d870c4e102e3766449f24b724834de3d58c08e9eecd8
+  data.tar.gz: beaf90aa5f6a0b579fd54298b108fe9fa427356d3fce5f6bffe570d828cbc0ac
 SHA512:
-  metadata.gz: 11b1349683d425b709d351ca165394f86f6ce7db6e71af7359d8c10a8532d2f31843464fa82b4a7da4a98ba792601b97cfa86fa02d08a36e8fe5528defe8622f
-  data.tar.gz: df922239b99ecbd4e87e6272908bc85f1ecf6e303faa704e5f5843a991ad783df29f2b6eeccd961a140342b1c7ab6e560ed93eca3222d9a4ae89c3fd690553e6
+  metadata.gz: 143c252e1134fef6790e18ac6d9ea6b85995fb90bd7755475cbdc8411ab85aefa9ae1d80c7362ebc8fadc53500109449ffef66818ebdb641dd302129e5a9bd1e
+  data.tar.gz: d90e35602b8be26133a51ca1ff25d65db41080ebdadff3988e81888b90c9b69e2843c2d84c58f67c8e5bcc8075d705782f575ac9b9f44d15e7725bc9e1ec549a

data/README.md

@@ -4,13 +4,39 @@
 
 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)
+- [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
 
 ## Installation
 
@@ -43,11 +69,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)
+
+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
+```
 
-Replace `image_tag` with `fileboost_image_tag` for ActiveStorage objects:
+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 +178,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 +197,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 +302,7 @@ After checking out the repo, run:
 
 ```bash
 $ bundle install
-$ rake test
+$ bundle exec rspec
 ```
 
 To test against the dummy Rails application:
@@ -186,7 +317,7 @@ $ rails server
 Run the test suite:
 
 ```bash
-$ rake test
+$ bundle exec rspec
 ```
 
 Run RuboCop:

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.pre2"
 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fileboost
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre
+  version: 0.2.0.pre2
 platform: ruby
 authors:
 - bilal
@@ -141,6 +141,7 @@ 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