{"id":31600256,"url":"https://github.com/fileboost/fileboost-ruby","last_synced_at":"2025-11-11T11:26:09.827Z","repository":{"id":314091076,"uuid":"1052663942","full_name":"Fileboost/fileboost-ruby","owner":"Fileboost","description":"Fileboost - Ruby on Rails SDK","archived":false,"fork":false,"pushed_at":"2025-09-18T05:29:35.000Z","size":98,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-13T12:58:14.900Z","etag":null,"topics":["active-storage","rails","ruby-on-rails"],"latest_commit_sha":null,"homepage":"https://fileboost.dev","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fileboost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-08T11:27:07.000Z","updated_at":"2025-10-08T00:08:18.000Z","dependencies_parsed_at":"2025-09-10T15:52:54.314Z","dependency_job_id":"9a493266-3306-4a9f-824b-7650bd00afcf","html_url":"https://github.com/Fileboost/fileboost-ruby","commit_stats":null,"previous_names":["bilalbudhani/fileboost-ruby","fileboost/fileboost-ruby"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Fileboost/fileboost-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fileboost%2Ffileboost-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fileboost%2Ffileboost-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fileboost%2Ffileboost-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fileboost%2Ffileboost-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fileboost","download_url":"https://codeload.github.com/Fileboost/fileboost-ruby/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fileboost%2Ffileboost-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020051,"owners_count":26086807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["active-storage","rails","ruby-on-rails"],"created_at":"2025-10-06T06:55:07.384Z","updated_at":"2025-10-14T17:49:37.655Z","avatar_url":"https://github.com/Fileboost.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fileboost\n\n[![Gem Version](https://badge.fury.io/rb/fileboost.svg)](https://badge.fury.io/rb/fileboost)\n\nFileboost 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.\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n  - [Drop-in Replacement (Recommended)](#drop-in-replacement-recommended)\n  - [Manual Helper Method](#manual-helper-method)\n  - [URL Generation](#url-generation)\n  - [Transformation Options](#transformation-options)\n  - [Parameter Aliases](#parameter-aliases)\n  - [ActiveStorage Support](#activestorage-support)\n  - [ActiveStorage Variants (NEW in v0.2.0)](#activestorage-variants-new-in-v020)\n    - [Variant Transformation Mapping](#variant-transformation-mapping)\n    - [Combining Variants with Custom Options](#combining-variants-with-custom-options)\n  - [Responsive Images](#responsive-images)\n- [Error Handling](#error-handling)\n- [Security](#security)\n- [Development](#development)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n## Features\n\n- 🚀 **Drop-in replacement** for Rails `image_tag` with zero code changes (NEW in v0.2.0)\n- 🎨 **Full ActiveStorage Variant support** with automatic transformation mapping (NEW in v0.2.0)\n- 🔒 **Secure HMAC authentication** with Fileboost.dev service\n- 📱 **ActiveStorage only** - works exclusively with ActiveStorage attachments\n- 🎛️ **Comprehensive transformations** - resize, quality, format conversion, and more\n- 🔧 **Simple configuration** - just project ID and token required\n- 🔄 **Automatic fallback** - non-ActiveStorage images work exactly as before\n\n## Requirements\n\n- Ruby 3.0+\n- Rails 7+\n- ActiveStorage\n\n## Installation\n\nRegister an account at [Fileboost.dev](https://fileboost.dev) and obtain your project ID and token.\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"fileboost\"\n```\n\nAnd then execute:\n\n```bash\n$ bundle install\n```\n\nGenerate the initializer:\n\n```bash\n$ rails generate fileboost:install\n```\n\n## Configuration\n\nSet your environment variables:\n\n```bash\nexport FILEBOOST_PROJECT_ID=\"your-project-id\"\nexport FILEBOOST_TOKEN=\"your-secret-token\"\n```\n\nOr configure directly in your initializer:\n\n```ruby\n# config/initializers/fileboost.rb\nFileboost.configure do |config|\n  config.project_id = ENV[\"FILEBOOST_PROJECT_ID\"]\n  config.token = ENV[\"FILEBOOST_TOKEN\"]\n\n  # Optional: Enable drop-in replacement for Rails image_tag (default: false)\n  config.patch_image_tag = true\nend\n```\n\n## Usage\n\n### Drop-in Replacement (Recommended)\n\n\u003e Enable `patch_image_tag` in your configuration to automatically optimize ActiveStorage images with your existing `image_tag` calls:\n\n```ruby\n# config/initializers/fileboost.rb\nFileboost.configure do |config|\n  config.project_id = ENV[\"FILEBOOST_PROJECT_ID\"]\n  config.token = ENV[\"FILEBOOST_TOKEN\"]\n  config.patch_image_tag = true  # Enable automatic optimization\nend\n```\n\nWith this enabled, your existing Rails code automatically gets Fileboost optimization:\n\n```erb\n\u003c!-- This now automatically uses Fileboost for ActiveStorage objects --\u003e\n\u003c%= image_tag user.avatar, resize: { w: 300, h: 300 }, alt: \"Avatar\" %\u003e\n\u003c%= image_tag post.featured_image, resize: { width: 800, quality: 85 }, class: \"hero\" %\u003e\n\n\u003c!-- ActiveStorage variants work seamlessly --\u003e\n\u003c%= image_tag user.avatar.variant(resize_to_limit: [100, 100]), alt: \"Thumbnail\" %\u003e\n\u003c%= image_tag post.image.variant(:thumb), alt: \"Post thumbnail\" %\u003e\n\n\u003c!-- Non-ActiveStorage images work exactly as before --\u003e\n\u003c%= image_tag \"/assets/logo.png\", alt: \"Logo\" %\u003e\n\u003c%= image_tag \"https://example.com/image.jpg\", alt: \"External\" %\u003e\n```\n\n**Benefits:**\n\n- Zero code changes required for existing ActiveStorage images\n- Full ActiveStorage variant support with automatic transformation mapping\n- Automatic fallback to Rails behavior for non-ActiveStorage assets\n- Gradual migration path - enable/disable with single configuration option\n\n### Manual Helper Method\n\nAlternatively, use `fileboost_image_tag` explicitly for ActiveStorage objects:\n\n```erb\n\u003c!-- Before (Rails) --\u003e\n\u003c%= image_tag user.avatar, width: 300, height: 300, alt: \"Avatar\" %\u003e\n\n\u003c!-- After (Fileboost) --\u003e\n\u003c%= fileboost_image_tag user.avatar, resize: { w: 300, h: 300 }, alt: \"Avatar\" %\u003e\n```\n\n**Note:** Fileboost only works with ActiveStorage objects. String paths and external URLs are not supported.\n\n### URL Generation\n\nGenerate optimized URLs directly:\n\n```erb\n\u003cdiv style=\"background-image: url(\u003c%= fileboost_url_for(banner.image, resize: { w: 1200, h: 400 }) %\u003e)\"\u003e\n  \u003c!-- content --\u003e\n\u003c/div\u003e\n```\n\n### Transformation Options\n\nFileboost supports comprehensive image transformations:\n\n```erb\n\u003c%= fileboost_image_tag post.image,\n      resize: {\n        width: 800,         # Resize width\n        height: 600,        # Resize height\n        quality: 85,        # JPEG/WebP quality (1-100)\n        format: \"jpg\",      # Force specific format (jpg, png, webp, avif)\n        blur: 5,            # Blur effect (0-100)\n        brightness: 110,    # Brightness adjustment (0-200, 100 = normal)\n        contrast: 120,      # Contrast adjustment (0-200, 100 = normal)\n        rotation: 90,       # Rotation in degrees (0-359)\n        fit: :cover         # Resize behavior (cover, contain, fill, scale-down, crop, pad)\n      },\n      class: \"hero-image\",  # Standard Rails options work too\n      alt: \"Hero image\" %\u003e\n\n\u003c!-- Short parameter names also work --\u003e\n\u003c%= fileboost_image_tag post.image,\n      resize: { w: 800, h: 600, q: 85, f: \"jpg\" },\n      class: \"hero-image\" %\u003e\n```\n\n### Parameter Aliases\n\nUse short or long parameter names within the resize parameter:\n\n```ruby\n# These are equivalent:\nfileboost_image_tag(image, resize: { w: 400, h: 300, q: 85, f: \"jpg\" })\nfileboost_image_tag(image, resize: { width: 400, height: 300, quality: 85, format: \"jpg\" })\n```\n\n**🎯 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.\n\n**⚠️ Format Parameter Usage:** The `format` parameter should only be used in non-browser-facing scenarios (API responses, webhooks, server-to-server communication, etc.). For browser-facing images, omit the format parameter to allow Fileboost to automatically serve the best format for each user's browser and connection.\n\n### ActiveStorage Support\n\nWorks seamlessly with all ActiveStorage attachment types:\n\n```erb\n\u003c!-- has_one_attached --\u003e\n\u003c%= fileboost_image_tag user.avatar, resize: { w: 150, h: 150, fit: :cover } %\u003e\n\n\u003c!-- has_many_attached --\u003e\n\u003c% post.images.each do |image| %\u003e\n  \u003c%= fileboost_image_tag image, resize: { width: 400, quality: 90 } %\u003e\n\u003c% end %\u003e\n\n\u003c!-- Direct blob access --\u003e\n\u003c%= fileboost_image_tag post.featured_image.blob, resize: { w: 800 } %\u003e\n```\n\n### ActiveStorage Variants (NEW in v0.2.0)\n\nFileboost now provides full support for ActiveStorage variants with automatic transformation mapping:\n\n```erb\n\u003c!-- Basic variants with automatic transformation mapping --\u003e\n\u003c%= image_tag user.avatar.variant(resize_to_limit: [200, 200]) %\u003e\n\u003c!-- ↓ Automatically becomes: w=200\u0026h=200\u0026fit=scale-down --\u003e\n\n\u003c%= image_tag post.image.variant(resize_to_fit: [400, 300]) %\u003e\n\u003c!-- ↓ Automatically becomes: w=400\u0026h=300\u0026fit=contain --\u003e\n\n\u003c%= image_tag hero.banner.variant(resize_to_fill: [800, 400]) %\u003e\n\u003c!-- ↓ Automatically becomes: w=800\u0026h=400\u0026fit=cover --\u003e\n\n\u003c!-- Complex variants with multiple transformations --\u003e\n\u003c%= image_tag post.image.variant(\n  resize_to_limit: [600, 400],\n  quality: 85\n) %\u003e\n\u003c!-- ↓ Automatically becomes: w=600\u0026h=400\u0026fit=scale-down\u0026q=85 --\u003e\n\n\u003c!-- Named variants work seamlessly --\u003e\n\u003c%= image_tag user.avatar.variant(:thumb) %\u003e\n\u003c!-- ↓ Uses predefined variant transformations --\u003e\n```\n\n#### Variant Transformation Mapping\n\nFileboost automatically maps ActiveStorage variant transformations to optimized URL parameters:\n\n| ActiveStorage Variant     | Fileboost Parameters     | Description                                        |\n| ------------------------- | ------------------------ | -------------------------------------------------- |\n| `resize_to_limit: [w, h]` | `w=W\u0026h=H\u0026fit=scale-down` | Resize within bounds, preserving aspect ratio      |\n| `resize_to_fit: [w, h]`   | `w=W\u0026h=H\u0026fit=contain`    | Resize to fit exactly, with letterboxing if needed |\n| `resize_to_fill: [w, h]`  | `w=W\u0026h=H\u0026fit=cover`      | Resize and crop to fill exactly                    |\n| `resize_and_pad: [w, h]`  | `w=W\u0026h=H\u0026fit=pad`        | Resize with padding                                |\n| `quality: 85`             | `q=85`                   | JPEG/WebP quality (1-100)                          |\n| `rotate: \"-90\"`           | `r=-90`                  | Rotation in degrees                                |\n\n#### Combining Variants with Custom Options\n\nYou can combine variant transformations with additional Fileboost options:\n\n```erb\n\u003c!-- Variant transformations + additional options --\u003e\n\u003c%= image_tag user.avatar.variant(resize_to_limit: [200, 200]),\n    resize: { blur: 5, brightness: 110 } %\u003e\n\u003c!-- ↓ Combines variant params with additional blur and brightness --\u003e\n\n\u003c!-- Override variant parameters --\u003e\n\u003c%= image_tag post.image.variant(resize_to_limit: [400, 300]),\n    resize: { w: 500 } %\u003e\n\u003c!-- ↓ Uses h=300\u0026fit=scale-down from variant, but overrides width to 500 --\u003e\n```\n\n### Responsive Images\n\nGenerate multiple sizes for responsive designs:\n\n```ruby\n# In your controller or helper\n@responsive_urls = fileboost_responsive_urls(hero.image, [\n  { width: 400, suffix: \"sm\" },\n  { width: 800, suffix: \"md\" },\n  { width: 1200, suffix: \"lg\" }\n], resize: { quality: 85 })\n\n# Returns: { \"sm\" =\u003e \"url1\", \"md\" =\u003e \"url2\", \"lg\" =\u003e \"url3\" }\n```\n\n```erb\n\u003c!-- In your view --\u003e\n\u003cimg src=\"\u003c%= @responsive_urls['md'] %\u003e\"\n     srcset=\"\u003c%= @responsive_urls['sm'] %\u003e 400w,\n             \u003c%= @responsive_urls['md'] %\u003e 800w,\n             \u003c%= @responsive_urls['lg'] %\u003e 1200w\"\n     sizes=\"(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px\"\n     alt=\"Responsive image\"\u003e\n```\n\n## Error Handling\n\nFileboost handles errors gracefully:\n\n- **Configuration errors**: Logs warnings about missing configuration and returns empty strings/nil\n- **Invalid assets**: Logs errors when non-ActiveStorage objects are passed and returns empty strings/nil\n- **Signature errors**: Returns nil when HMAC generation fails\n\n## Security\n\nFileboost uses HMAC-SHA256 signatures to secure your image transformations:\n\n- URLs are signed with your secret token\n- Prevents unauthorized image manipulation\n- Signatures include all transformation parameters\n- Uses secure comparison to prevent timing attacks\n\n## Development\n\nAfter checking out the repo, run:\n\n```bash\n$ bundle install\n$ bundle exec rspec\n```\n\nTo test against the dummy Rails application:\n\n```bash\n$ cd test/dummy\n$ rails server\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n$ bundle exec rspec\n```\n\nRun RuboCop:\n\n```bash\n$ bundle exec rubocop\n```\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Write tests for your changes\n4. Ensure all tests pass (`rake test`)\n5. Commit your changes (`git commit -am 'Add some feature'`)\n6. Push to the branch (`git push origin my-new-feature`)\n7. Create new Pull Request\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Support\n\n- [GitHub Issues](https://github.com/Fileboost/fileboost-ruby/issues)\n- [Documentation](https://github.com/Fileboost/fileboost-ruby/wiki)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffileboost%2Ffileboost-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffileboost%2Ffileboost-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffileboost%2Ffileboost-ruby/lists"}