active_storage.cr

A 1:1 Crystal port of activestorage 8.1.4 (the Rails engine) under the same ActiveStorage namespace: has_one_attached/has_many_attached on ActiveRecord models, Disk and S3/MinIO services, image variants (via the vips CLI), and Rails-compatible signed_id tokens (urlsafe_b64_nopad(...) + "--" + hmac_sha256-hex, byte-for-byte against the Rails 8.1 verifier). The S3 client is AWS SigV4 on OpenSSL + HTTP::Client — no SDK. Suite: 95/95 specs replaying 27 + 19 + 16 + 37 oracle cases recorded from the real gem.

⚠️ EXPERIMENTAL FRAMEWORK, DO NOT USE IN PRODUCTION YET.

Installation

dependencies:
  active_storage_cr:
    github: OrelSokolov/active_storage.cr

shards install

Depends on active_support.cr and active_record.cr; the direct-upload HTTP layer additionally needs action_pack.cr (opt-in require, not pulled in by the umbrella active_storage_cr). Variants need the vips binary in PATH.

Usage

require "active_storage_cr"

ActiveStorage.service = ActiveStorage::DiskService.new("/srv/storage")

class User < ActiveRecord::Base
  has_one_attached :avatar
  has_many_attached :photos
end

user.avatar.attach(File.read("/tmp/avatar.png"), "avatar.png", "image/png")
user.avatar.attached?      # => true
user.avatar.download       # => png bytes
user.avatar.variant(resize_to_limit: [100, 100], format: "webp").url

# has_many_attached: io triplets, existing blobs, or direct-upload signed ids
user.photos.attach(File.read("/tmp/1.jpg"), "1.jpg", "image/jpeg")
user.photos.attach([blob, other_blob])
user.photos.attach(blob.signed_id)

ActiveStorage::Blob.find_signed!(signed_id)  # raises on bad signature

# S3/MinIO (path-style, header signing, presigned GET/PUT):
ActiveStorage.service = ActiveStorage::S3Service.new(
  endpoint: "http://127.0.0.1:9000", bucket: "photos",
  access_key_id: "minioadmin", secret_access_key: "minioadmin")

# Direct upload controllers (opt-in; pulls action_pack):
require "active_storage_cr/controllers"

Feature comparison vs activestorage 8.1.4

DSL & attachables

Blobs, signed ids & services

Variants & representations

Direct upload & HTTP routes

Deviations & Crystal-specific notes

• Single global ActiveStorage.service instead of the gem's per-blob service registry (storage.yml + config.active_storage.service are not implemented).
• Disk URLs are relative; the base comes from ActiveStorage.disk_url_base (Rails builds absolute URLs from ActiveStorage::Current.url_options).
• The verifier secret is CRAILS_SECRET_KEY_BASE with a fixed development fallback (Rails uses secret_key_base).
• Variation key is SHA256 of canonical JSON, not Rails' signed HMAC+SHA256 (Rails-internal); key shape is identical.
• Direct-upload controllers are an opt-in require so the shard doesn't pull action_pack transitively; namespace-compatible dispatch ("active_storage/disk") works.
• The AR port writes created_at/updated_at unconditionally, so the blobs/attachments tables carry updated_at (Rails' tables don't).
• Attachables are typed as unions/overloads (String io, Blob, signed_id); io: is a String of bytes, not an IO object.

Full list with rationale: PLAN.md (Russian).

Testing

crystal spec   # 95/95 — needs local PostgreSQL (db crails_as_test)

The S3 group additionally needs MinIO on 127.0.0.1:9000 (buckets as-oracle, as-crystal); without it those specs skip with a notice. Oracle cases recorded from activestorage 8.1.4: 27 core (oracle/cases.rb), 19 has_many_attached (cases_many.rb), 16 signed_id (cases_signed_id.rb), 37 S3/direct-upload against live MinIO (cases_s3.rb) — replayed 1:1 in spec/.

Related

• CRails siblings: active_record.cr, active_support.cr, action_pack.cr — this shard is the ActiveStorage piece of the stack.