activeblob 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89d322a2edaa8e9fe38cd46de0bbb3c95413780079b428c6024a4e1d85362708
+  data.tar.gz: 7b0d9320c5eb5311b01a60d0a1db582c01b23b635da5fbefefbb49b5fe60c78e
+SHA512:
+  metadata.gz: 6aa7e5b2bed692d80735397eba86aef9466f436964d74b9d63b661a017b19610f3fe04ce6ca110c4778693886ea4bab31d5c6f3abe7978d58e5fd2aba9707003
+  data.tar.gz: c09f2e166040761d02fca0846bae64959dacf5257545a6b15fcf66f40b319c74c3fc31f6d17cf07fa8dfa09ecc79e0e2e7ad835b9f8b846deed6edd6556aeb7e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025 Ben Ehmke
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,412 @@
+# ActiveBlob
+
+ActiveBlob is a content-addressable blob storage system for Rails applications. It provides SHA1-based deduplication, polymorphic attachments, and support for multiple storage backends (filesystem and S3).
+
+## Features
+
+- **Content-addressable storage**: Blobs are identified by SHA1 hash, preventing duplicate storage
+- **Polymorphic attachments**: Attach blobs to any model with `has_one_blob` or `has_many_blobs`
+- **Multiple storage backends**: Filesystem or S3-compatible storage
+- **Type-specific models**: Built-in support for images, videos, and PDFs with automatic metadata extraction
+- **Flexible input**: Create blobs from files, URLs, base64 data, or raw data
+- **URL generation**: Generate signed URLs for cloud storage or local paths
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activeblob'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Run the installer to generate migrations and configuration:
+
+```bash
+rails generate activeblob:install
+rails db:migrate
+```
+
+## Configuration
+
+Configure your storage backend in `config/initializers/activeblob.rb`:
+
+### Filesystem Storage (Default)
+
+```ruby
+ActiveBlob.configure do |config|
+  config.storage_config = {
+    storage: 'filesystem',
+    path: Rails.root.join('storage', 'blobs')
+  }
+end
+```
+
+### S3 Storage
+
+```ruby
+ActiveBlob.configure do |config|
+  config.storage_config = {
+    storage: 's3',
+    bucket: ENV['S3_BUCKET'],
+    access_key_id: ENV['S3_ACCESS_KEY_ID'],
+    secret_access_key: ENV['S3_SECRET_ACCESS_KEY'],
+    region: ENV['S3_REGION'] || 'us-east-1',
+    endpoint: ENV['S3_ENDPOINT'] # Optional, for S3-compatible services
+  }
+end
+```
+
+## Usage
+
+### Adding Attachments to Models
+
+#### Single Attachment
+
+```ruby
+class User < ApplicationRecord
+  has_one_blob :avatar
+end
+
+# Usage
+user = User.new
+user.avatar = params[:avatar]  # File upload
+user.save
+```
+
+#### Multiple Attachments
+
+```ruby
+class Post < ApplicationRecord
+  has_many_blobs :images
+end
+
+# Usage
+post = Post.new
+post.images = [file1, file2, file3]
+post.save
+```
+
+### Creating Blobs
+
+#### From File Upload
+
+```ruby
+blob = ActiveBlob::Blob.new(file: params[:file])
+blob.save
+```
+
+#### From URL
+
+```ruby
+blob = ActiveBlob::Blob.new(url: "https://example.com/image.jpg")
+blob.save
+```
+
+#### From Base64
+
+```ruby
+blob = ActiveBlob::Blob.new(
+  base64: base64_string,
+  content_type: "image/png",
+  filename: "image.png"
+)
+blob.save
+```
+
+#### From Raw Data
+
+```ruby
+blob = ActiveBlob::Blob.new(data: binary_data)
+blob.content_type = "image/jpeg"
+blob.save
+```
+
+### Accessing Blobs
+
+```ruby
+# Get blob URL
+user.avatar.url
+
+# Get blob URL with options
+blob.url(disposition: 'inline', filename: 'custom.jpg', expires_in: 3600)
+
+# Get blob metadata
+blob.size          # File size in bytes
+blob.content_type  # MIME type
+blob.sha1          # Binary SHA1 hash
+blob.extension     # File extension based on content type
+
+# Open blob for processing
+blob.open do |file|
+  # Process the file
+  puts file.read
+end
+```
+
+### Blob Types
+
+ActiveBlob automatically selects the appropriate blob type based on content type:
+
+#### Images (ActiveBlob::Blob::Image)
+
+Requires `ruby-vips` gem:
+
+```ruby
+gem 'ruby-vips'
+```
+
+Automatically extracts:
+- Width and height
+- Dominant color
+- Background color
+- Aspect ratio
+
+```ruby
+image = ActiveBlob::Blob.new(file: image_file)
+image.save
+
+image.width          # => 1920
+image.height         # => 1080
+image.aspect_ratio   # => 1.777...
+image.dominant_color # => "255,128,0"
+```
+
+#### Videos (ActiveBlob::Blob::Video)
+
+Requires `streamio-ffmpeg` gem:
+
+```ruby
+gem 'streamio-ffmpeg'
+```
+
+Automatically extracts:
+- Duration
+- Bitrate
+- Codec
+- Width and height
+- Frame rate
+
+```ruby
+video = ActiveBlob::Blob.new(file: video_file)
+video.save
+
+video.duration    # => 120.5 (seconds)
+video.width       # => 1920
+video.height      # => 1080
+video.codec       # => "h264"
+video.frame_rate  # => 30.0
+```
+
+#### PDFs (ActiveBlob::Blob::PDF)
+
+Requires `pdf-reader` gem:
+
+```ruby
+gem 'pdf-reader'
+```
+
+Automatically extracts:
+- Page count
+- Width and height per page
+- Aspect ratio
+
+```ruby
+pdf = ActiveBlob::Blob.new(file: pdf_file)
+pdf.save
+
+pdf.page_count    # => 10
+pdf.aspect_ratio  # => 0.707 (based on first page)
+```
+
+### Deduplication
+
+ActiveBlob automatically deduplicates blobs based on SHA1 hash:
+
+```ruby
+# Upload the same file twice
+blob1 = ActiveBlob::Blob.new(file: file)
+blob1.save
+
+blob2 = ActiveBlob::Blob.new(file: file)
+blob2.save
+
+# blob1 and blob2 reference the same record
+blob1.id == blob2.id  # => true
+```
+
+### Attachments
+
+Attachments link blobs to your records:
+
+```ruby
+# Create attachment explicitly
+attachment = ActiveBlob::Attachment.create(
+  record: user,
+  blob: blob,
+  filename: "avatar.jpg",
+  type: "avatar"
+)
+
+# Access attachment properties
+attachment.filename      # => "avatar.jpg"
+attachment.content_type  # => "image/jpeg"
+attachment.size          # => 102400
+attachment.url           # Delegates to blob.url
+```
+
+### Nested Attributes
+
+You can use nested attributes with attachments:
+
+```ruby
+class Post < ApplicationRecord
+  has_many_blobs :images
+  accepts_nested_attributes_for :images
+end
+
+# In your controller
+post.update(
+  images_attributes: [
+    { blob_id: blob.id, filename: "image1.jpg" },
+    { blob_id: blob2.id, filename: "image2.jpg" }
+  ]
+)
+```
+
+## Architecture
+
+### Models
+
+- **ActiveBlob::Blob**: Base model for all blobs
+  - `ActiveBlob::Blob::Image`: Image blobs with metadata extraction
+  - `ActiveBlob::Blob::Video`: Video blobs with metadata extraction
+  - `ActiveBlob::Blob::PDF`: PDF blobs with metadata extraction
+
+- **ActiveBlob::Attachment**: Polymorphic join model linking blobs to records
+
+### Storage Backends
+
+- **ActiveBlob::Storage::Filesystem**: Store blobs on local filesystem
+- **ActiveBlob::Storage::S3**: Store blobs on S3 or S3-compatible services
+
+### Database Schema
+
+#### Blobs Table
+
+```ruby
+create_table :blobs, id: :uuid do |t|
+  t.string :type                           # STI type
+  t.bigint :size, null: false              # File size in bytes
+  t.string :content_type, null: false      # MIME type
+  t.jsonb :metadata, default: {}           # Type-specific metadata
+  t.binary :sha1, limit: 20, null: false   # SHA1 hash for deduplication
+  t.timestamps
+end
+
+add_index :blobs, :sha1
+add_index :blobs, [:type, :sha1]
+```
+
+#### Attachments Table
+
+```ruby
+create_table :attachments, id: :uuid do |t|
+  t.string :type                    # Attachment type (e.g., "avatar", "photo")
+  t.integer :order, default: 0      # Order for has_many_blobs
+  t.string :filename                # Original filename
+  t.string :record_type             # Polymorphic record type
+  t.uuid :record_id                 # Polymorphic record ID
+  t.uuid :blob_id, null: false      # Reference to blob
+  t.timestamps
+end
+
+add_index :attachments, [:record_type, :record_id]
+add_index :attachments, :blob_id
+add_index :attachments, [:blob_id, :record_id, :record_type, :type, :filename],
+          unique: true
+```
+
+## Advanced Usage
+
+### Custom Blob Types
+
+Create custom blob types by subclassing `ActiveBlob::Blob`:
+
+```ruby
+class ActiveBlob::Blob::Audio < ActiveBlob::Blob
+  validates :content_type, format: /\Aaudio\/.*\Z/
+
+  def duration
+    metadata['duration']
+  end
+
+  def self.process(record, path)
+    # Extract audio metadata
+    # record.metadata = { 'duration' => ..., 'bitrate' => ... }
+  end
+end
+```
+
+### Storage Adapter Interface
+
+Create custom storage adapters by implementing:
+
+```ruby
+class MyStorage
+  def local?
+    # Return true if storage is local, false otherwise
+  end
+
+  def write(id, file, options = {})
+    # Write file to storage
+  end
+
+  def read(id)
+    # Read file from storage
+  end
+
+  def delete(id)
+    # Delete file from storage
+  end
+
+  def exists?(id)
+    # Check if file exists
+  end
+
+  def url(id, **options)
+    # Generate URL for file
+  end
+
+  def copy_to_tempfile(id, basename: nil, &block)
+    # Copy file to temporary location and yield to block
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+To run tests:
+
+```bash
+rails test
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bemky/activeblob.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/gem_tasks"
+
+task default: :test

data/app/models/activeblob/attachment.rb

@@ -0,0 +1,41 @@
+module ActiveBlob
+  class Attachment < ActiveRecord::Base
+    self.table_name = 'attachments'
+    self.inheritance_column = nil
+
+    belongs_to :blob, class_name: 'ActiveBlob::Blob'
+    belongs_to :record, polymorphic: true
+
+    before_validation { self.order ||= 0 }
+    before_save :default_filename
+
+    validates_uniqueness_of :blob_id, scope: [:record_id, :record_type, :type, :filename], message: " already attached", if: :record_id
+
+    delegate :size, :content_type, :sha1, :extension, to: :blob
+
+    def url(**options)
+      options[:filename] ||= filename
+      blob.url(**options)
+    end
+
+    def file=(file)
+      self.filename ||= ActiveBlob::BlobHelpers.filename_from_file(file)
+      self.blob = ActiveBlob::Blob.new(file: file)
+    end
+
+    def url=(url)
+      file = ActiveBlob::Blob.download_url(url)
+      self.filename = file.original_filename
+      self.blob = ActiveBlob::Blob.create!(file: file)
+    end
+
+    def default_filename
+      self.filename ||= [self.type, SecureRandom.hex(10)].join("-")
+    end
+
+    def open(basename: nil, &block)
+      basename ||= [File.basename(filename), File.extname(filename)]
+      blob.open(basename: basename, &block)
+    end
+  end
+end

data/app/models/activeblob/blob/image.rb

@@ -0,0 +1,38 @@
+module ActiveBlob
+  class Blob::Image < Blob
+    validates :content_type, presence: true, format: /\Aimage\/\w+\Z/
+
+    def width
+      metadata['width']
+    end
+
+    def height
+      metadata['height']
+    end
+
+    def dominant_color
+      metadata['dominant_color']
+    end
+
+    def background_color
+      metadata['background_color']
+    end
+
+    def aspect_ratio
+      return nil unless self.width && self.height
+      self.width.to_f / self.height.to_f
+    end
+
+    def self.process(record, path)
+      require 'vips' unless defined?(Vips)
+
+      vips = Vips::Image.new_from_file(path)
+      record.metadata = {
+        'width' =>      vips.width,
+        'height' =>     vips.height,
+        'dominant_color' => vips.thumbnail_image(1).getpoint(0, 0).join(","),
+        'background_color' => vips.getpoint(0,0).join(",")
+      }
+    end
+  end
+end

data/app/models/activeblob/blob/pdf.rb

@@ -0,0 +1,31 @@
+module ActiveBlob
+  class Blob::PDF < Blob
+    validates :content_type, presence: true, format: /\Aapplication\/pdf\Z/
+
+    def page_count
+      metadata['pages']&.size || 0
+    end
+
+    def aspect_ratio
+      first_page = metadata['pages']&.first
+      return nil unless first_page
+
+      width = first_page['width'].to_f
+      height = first_page['height'].to_f
+
+      return nil if height.zero?
+
+      width / height
+    end
+
+    def self.process(record, path)
+      require 'pdf-reader' unless defined?(PDF::Reader)
+
+      record.metadata = {
+        'pages' => PDF::Reader.new(path).pages.map { |page|
+          { 'width' => page.width, 'height' => page.height }
+        }
+      }
+    end
+  end
+end

data/app/models/activeblob/blob/video.rb

@@ -0,0 +1,44 @@
+module ActiveBlob
+  class Blob::Video < Blob
+    validates :content_type, presence: true, format: /\Avideo\/.*\Z/
+
+    def width
+      metadata['width']
+    end
+
+    def height
+      metadata['height']
+    end
+
+    def duration
+      metadata['duration']
+    end
+
+    def bitrate
+      metadata['bitrate']
+    end
+
+    def codec
+      metadata['codec']
+    end
+
+    def frame_rate
+      metadata['frame_rate']
+    end
+
+    def self.process(record, path)
+      require 'streamio-ffmpeg' unless defined?(FFMPEG)
+
+      video = FFMPEG::Movie.new(path)
+
+      record.metadata = {
+        'duration' =>   video.duration,
+        'bitrate' =>    video.bitrate,
+        'codec' =>      video.video_codec,
+        'width' =>      video.width,
+        'height' =>     video.height,
+        'frame_rate' => video.frame_rate
+      }
+    end
+  end
+end