Changelog

Copy Markdown View Source

[0.2.0] - 2026-06-11

Changed — BREAKING

  • Storage backends are now named instances in a registry, replacing the single global backend pick (config :attached, :storage_backend, Module + per-module config keys like :disk/:s3):

    # Before
config :attached,
  storage_backend: Attached.StorageBackends.S3,
  s3: [bucket: "my-bucket", ...]

# After
config :attached,
  storage_backends: [
    s3_main: {Attached.StorageBackends.S3, bucket: "my-bucket", ...}
  ]

    The default instance is the only registry entry, or — with several entries — the one named by config :attached, :default_storage_backend. Old config keys (:storage_backend, :service, :disk, :s3) raise with migration instructions instead of silently falling back to Disk. This makes multiple instances of the same backend possible (e.g. two S3 buckets) and is the groundwork for the planned mirror backend and per-row dispatch.

  • Attached.StorageBackends.Behaviour callbacks take the instance's config keyword as their first argument (upload(config, key, source_path, opts), download(config, key), ...). Custom backends must be updated; backend modules no longer read global application config.

  • The storage_backend column on attached_originals records the instance name (e.g. "local", "s3_main") instead of the module name ("Attached.StorageBackends.Disk") — mirrors Active Storage's service_name. Existing rows are not migrated automatically; the column is informational only (no dispatch reads it yet).

  • Attached.Test.setup_storage!/1 now configures the registry with a single Disk instance named :local.

Added

  • Attached.StorageBackends.S3 — storage backend for Amazon S3 and S3-compatible services (MinIO, Cloudflare R2, DigitalOcean Spaces) via the optional req dependency (already included in new Phoenix apps). SigV4 signing is implemented in-house and verified against the official AWS test vectors — no AWS SDK needed. Presigned GET URLs (Attached.Web.Plug not involved), ListObjectsV2-based delete_prefixed/1 with pagination, STS session tokens, and optional response-content-type on presigned URLs resolved from the original/variant row. Path-style addressing via the :endpoint option for S3-compatibles.
  • S3 integration suite that boots a local Garage server and exercises the full backend — including acceptance of our presigned URLs by a real S3 implementation. Runs as part of mix test whenever the garage binary is available (the dev shell provides it), excluded otherwise.
  • Direct-upload groundwork: Attached.StorageBackends.direct_upload_url/2 returns a URL (plus required headers) for uploading a key straight from the browser via HTTP PUT. S3 presigns the PUT with content-md5, content-type, and content-length pinned in the signature; Disk serves a purpose-bound token handled by a new PUT /originals/:token route in Attached.Web.Plug (with optional :max_upload_size and Content-MD5 verification). Attached.Web.Signer tokens now carry a purpose, so download URLs can never be replayed as uploads.

Changed

  • Orphan purging (PurgeOrphansWorker, purge_by_owner_group/2) now skips orphans younger than config :attached, :orphan_grace_period (default 48 hours, 0 disables), so originals created ahead of their attachment — e.g. direct uploads in flight — survive the sweep. list_orphans/... and count_orphans/... still report all current orphans regardless of age.

Fixed

  • Attached.Variants.process/3 is now actually idempotent under concurrency: two simultaneous callers for the same uncached variant no longer crash the loser with Ecto.ConstraintError — it returns the winner's cached row.
  • resize_and_pad in the Vix transformer now pads to the exact target dimensions with a transparent background (it behaved like resize_to_fit), matching the ImageMagick backend.
  • path_for/1 now has an explicit nil clause, resolving an Elixir 1.20 type warning when tests pass nil to verify the security guard.
  • Logger level set to :warning in test env, suppressing debug query output.
  • All DB-touching tests migrated from ExUnit.Case + manual sandbox checkout to Attached.DataCase, eliminating sandbox ownership races.
  • ImageMagick.metadata/1 now returns %{} early for nonexistent paths via File.exists?/1, avoiding a noisy identify stderr error in tests.
  • ImageMagick metadata tests use a JPEG fixture with an embedded EXIF orientation tag, eliminating the unknown image property stderr warning.
  • VixTest now uses Code.ensure_loaded?(Vix) instead of Code.ensure_loaded?(Vix.Vips.Image) to avoid NIF load failure at compile time causing tests to be incorrectly skipped.

[0.1.1] - 2026-06-08

Fixed

  • .formatter.exs was missing from the published Hex package, preventing import_deps: [:attached] from working for consumers.

[0.1.0] - 2026-04-24

Initial release.

Added

  • attached macro for Ecto schemas — generates a belongs_to :{name}_attached_original association and expects a {name}_attached_original_id UUID FK column. Configurable per field via :foreign_key or globally via config :attached, :default_foreign_key_suffix:.

  • put_attached/3 — attach files inside a changeset via prepare_changes/2, transactional with the parent insert/update. Accepts %Plug.Upload{}, any map with :path (e.g. from Phoenix.LiveView.consume_uploaded_entries/3), an existing %Original{} (re-attach without storage I/O), or nil (no-op).

  • Attached.url/2,3 — URL to the original file or a named variant. Variant URLs trigger lazy generation on first call and return the cached URL on all subsequent calls. Raises ArgumentError if :variants is not preloaded on the original.

  • Attached.attached?/2 — boolean attachment check.

  • Attached.with_attached/2 — preloads the original and its variants in one shot. Use this instead of manual Repo.preload to avoid a second round-trip per variant URL call.

  • Attached.upload_original/2 — standalone original upload outside the changeset flow (e.g. Trix inline image uploads before an article is saved).

  • Attached.purge/2 — synchronously deletes the original record, all variant records, and all associated storage files.

  • Attached.purge_later/2 — same as purge/2 but via an Oban job. Enqueues inside the current transaction, so a rollback cancels the job too.

  • attached_originals table — stores files with key, filename, storage_backend, content_type, byte_size, checksum, owner_table, owner_field, metadata (JSON).

  • attached_variants table — cached derivations. Fields: original_id (FK, on_delete: :delete_all), name, transform_digest, content_type, byte_size, checksum, metadata. UNIQUE(original_id, transform_digest).

  • Attached.Variants context — list/1, get/2, get!/2, count/1, paginate/1, process/3, purge!/1, delete_for!/1, get_for/2, path_for/2,3, get_by_path/1, previewable?/1, preview_url/1, transforms_for/3, transform_digest/1.

  • Attached.Variants.path_for/2,3 — single source of truth for variant storage paths: "_variants/#{parent.key}-#{name}-#{digest[0..3]}". Variants live under _variants/ so originals and variants can be handled separately in listings, backups, and cleanup sweeps.

  • Attached.Variants.get_by_path/1 — reverse of path_for; used by the plug to resolve the content type of a variant URL.

  • Variant quality: option (integer 1–100) — applied to the encoder at write time. Different quality values produce distinct cached variants since quality: is included in the transform digest.

  • Variant fn: option — bypass the built-in transformer with a named function capture. The function receives (input_path, transforms, output_path) and must return :ok or {:error, reason}. Anonymous functions are not accepted (non-deterministic digests).

  • Attached.Processors.Transformers registry — transformers declare accept?/2 with (input_content_type, output_content_type) pairs. Built-in: Vix and ImageMagick (both image/* → image/*). Non-image transforms (e.g. application/pdf → text/plain) are a first-class extension point via Attached.Processors.Transformers.Behaviour.

  • Attached.Processors.ImagePreviewers — fallback stage for image-targeted variants when no direct transformer accepts the MIME pair. Built-in previewers: PDF (pdftoppm / mutool), video (ffmpeg), EPUB (gnome-epub-thumbnailer).

  • Attached.Processors.MetadataExtractors — async analysis after upload. Attached.Originals.ExtractMetadataWorker runs the first accepting extractor and merges results into original.metadata: width/height for images, width/height/duration/aspect_ratio/angle/audio/video for video, duration/bit_rate for audio.

  • Attached.Originals context — list/1, get/2, get!/2, get_by_key/2, count/1, paginate/1, create_from_upload!/2, create_from_file!/2, create_from_stream!/2, update_metadata!/2, purge!/1, purge_later/1, list_owner_groups/0, list_orphan_groups/0, list_orphans/4, count_orphans/0,2, purge_orphans_later/0, purge_by_owner_group/2, extract_metadata_later/1, get_owner/1.

  • Attached.Originals.Stats — aggregate queries for dashboards: overview/0, by_content_type/0, by_owner_group/0, by_storage_backend/0.

  • Attached.Originals.PurgeOrphansWorker — finds originals whose owner_table/owner_field no longer reference a live FK row and purges them. Schedule via Oban cron:

    config :my_app, Oban,
  plugins: [{Oban.Plugins.Cron, crontab: [
    {"0 3 * * *", Attached.Originals.PurgeOrphansWorker}
  ]}]

  • Attached.Variants.VariantTransformWorker — Oban worker for eager variant pre-warming. Args: {original_id, record_module, field, variant}. Resolves transforms from the schema at perform time, computes the digest itself — no transform serialization needed.

  • Attached.StorageBackends.Disk — local filesystem backend. Serves files via Attached.Web.Plug (forward "/storage", Attached.Web.Plug).

  • Attached.StorageBackends.Behaviour — implement to add custom backends.

  • mix attached.install — generates the initial migration (both tables). Future schema changes ship as versioned migrations: Attached.Ecto.Migration.up(version: N).

  • mix attached.gen.migration SchemaModule field — generates a per-attachment FK migration. Respects config :attached, :default_foreign_key_suffix:.

  • Attached.Ecto.Migration.rename/2 — keeps owner_table/owner_field in sync when renaming fields or tables. Call it alongside Ecto's own rename in your migration, otherwise orphan detection silently breaks.

  • .formatter.exs exports attached: 1, 2 as locals_without_parens and imports :ecto/:ecto_sql formatter configs.

  • Attached.Test — test helpers: setup_storage!/1 (configures Disk backend against a tmp dir with at_exit cleanup) and attach!/3 (bypasses the changeset flow for test fixtures).