feature: storage-disk abstraction (local + S3 adapters, signed URLs) — attachments phase 1 #3157

Activity

1. wheels-bot commented on Jun 12, 2026

   

   wheels-botBot

   on Jun 12, 2026

   Contributor

   More actions

   Wheels Bot — Triage

   Classified as framework-design (API/feature design question).
   Cross-framework research will follow shortly — Rails, Laravel, Django,
   and other modern frameworks will be consulted before any path forward
   is proposed.

   <!-- wheels-bot:triage:3157 -->
   <!-- wheels-bot:triage-class:framework-design -->
2. wheels-bot commented on Jun 12, 2026

   

   wheels-botBot

   on Jun 12, 2026

   Contributor

   More actions

   Wheels Bot — Cross-Framework Research

   Question

   #3157 (child of #2962, Phase 1) wants a storage-disk abstraction under vendor/wheels/storage/: a pluggable disk interface with local + S3 adapters covering put/get/exists/delete and signed, expiring URLs, where S3 is accessed via plain cfhttp request signing (no SDK, no JARs). The hasOneAttached model macro + polymorphic blob tables are out of scope (Phase 2). Narrow question: what should the disk interface and its config look like?

   How other frameworks handle this

   Framework	Naming	Surface	Trade-offs	Edge cases
   Rails (ActiveStorage)	Service→DiskService/S3Service; opaque key	upload/download/delete/exist?/url; one url() dispatches public-vs-private	~10-method abstract class; zero model knowledge	checksum integrity; Disk needs routed DiskController to serve local; S3Service depends on aws-sdk to sign
   Laravel (Filesystem)	named disk + driver (local/s3); Flysystem	put/get/exists/delete/copy/move/url/temporaryUrl/visibility	local↔s3 = config-only; cloud caps runtime-probed	temporaryUrl throws on local unless serve=true; visibility: public/private
   Django (Storage)	Storage→FileSystemStorage/S3Storage; STORAGES named backends	save/open/delete/exists/size/url; _save/_open template-method	lowest-common-denominator; unsupported caps raise NotImplementedError	url() public-vs-signed toggled by querystring_auth; querystring_expire TTL
   Spring (Resource/S3Template)	Resource/ResourceLoader (file:/s3:); S3Template	Resource has no delete/sign; S3Template: upload/download/deleteObject/objectExists/createSignedGetURL	protocol-prefix resolution elegant; signing only in S3 layer	presign expiry is Duration; exists() = real HEAD on S3
   Phoenix/Elixir (Waffle+ExAws) (no built-in)	Waffle.Storage.Local/.S3 behaviour	triad put/url/delete; ExAws.S3.presigned_url(:get,…,expires_in:)	single-knob swap; no built-in disk — pure library choice	local served via Plug.Static; presign offline; R2 needs PUT not POST
   AdonisJS Drive/FlyDrive (+1)	Disk wraps Driver/DriverContract; services.fs/services.s3	put/get/exists/delete/copy/move/getUrl/getSignedUrl/streams/visibility	purpose-built; I/O uniform but URL/visibility leak the backend	fs has no native signed-URL — needs app route (serveFiles:true); signed-URL contentType/contentDisposition map to S3 response headers

   +1 = AdonisJS Drive/FlyDrive: modern, actively-maintained lib that solved exactly this (one DriverContract over fs+S3+GCS with expiresIn signed URLs); surfaces the sharpest lesson — a local backend has no native signed URL, so the framework must serve files via its own route.

   Dominant pattern

   Strong convergence: the two purpose-built disk abstractions (Laravel, AdonisJS) and Rails all use named disks, each parameterized by a driver string, behind one small uniform interface (put/get/exists/delete/url + a separate signedUrl for expiry), selected by name with a default. Django/Spring agree on the abstraction but are weaker on portable signing. The single universal divergence is signed URLs for the local driver — every framework treats S3 presigning as native and local signing as a separate problem needing an app-served route (Rails DiskController, Laravel serve, AdonisJS serveFiles, Phoenix Plug.Static). Naming consensus for a new abstraction is Laravel/AdonisJS's disk + driver.

   Recommended path for Wheels

   Adopt named-disk + driver: a thin StorageManager lazily resolving disks from config, plus a storage() helper mixed onto controllers/models (mirroring service()/model()). Ship LocalDisk + S3Disk. S3 presigning is from-scratch SigV4 — de-risked: vendor/wheels/auth/JwtService.cfc:275 already runs the exact primitives (HMac(msg,key,"HMACSHA256") + BinaryDecode/BinaryEncode) green on Lucee/Adobe/BoxLang, which is all SigV4 needs (SHA-256 hex canonical hash + HMAC key-derivation chain). Local signedUrl follows the universal pattern: an HMAC token over key+expires to a built-in serving route.

   // config/settings.cfm
   set(storage = {
       default = "local",
       disks = {
           local = { driver="local", root="/storage/uploads", urlPrefix="/uploads" },
           s3    = { driver="s3", bucket="myapp-prod", region="us-east-1",
                     accessKeyId=get("AWS_ACCESS_KEY_ID"),
                     secretAccessKey=get("AWS_SECRET_ACCESS_KEY"), visibility="private" }
       }
   });
   
   // vendor/wheels/interfaces/StorageDiskInterface.cfc
   interface {
       public any     function put(required string key, required any content, string contentType, string visibility);
       public any     function get(required string key);
       public boolean function exists(required string key);
       public boolean function delete(required string key);
       public string  function url(required string key);
       public string  function signedUrl(required string key, numeric expiresIn=300, string contentDisposition);
   }
   
   // usage — same surface on any backend; all-named args when passing options
   storage().put(key="avatars/123.png", content=fileData, contentType="image/png");
   if (storage("s3").exists(key="avatars/1.png")) local.u = storage("s3").url(key="avatars/1.png");
   local.tmp = storage("s3").signedUrl(key="reports/q3.pdf", expiresIn=300,
                                       contentDisposition="attachment; filename=q3.pdf");

   Lives in: vendor/wheels/storage/StorageManager.cfc, .../drivers/LocalDisk.cfc, .../drivers/S3Disk.cfc, .../S3Signer.cfc; interface in vendor/wheels/interfaces/StorageDiskInterface.cfc; storage() helper on the controller/model mixin surface; one built-in route + Public-handler for signed local files.
   Composes with: the DI container (register StorageManager as a singleton in config/services.cfm; resolve via service("storage") / storage()), the set() config convention, and get(env) for creds. Drivers are standalone services (not $integrateComponents-mixed), so plain private helpers are fine.

   Cross-engine notes

   Riskiest piece is proven prior art: SigV4 = Hash(canonical,"SHA-256") hex + chained HMac(...,"HMACSHA256") with BinaryDecode/BinaryEncode — identical to JwtService.cfc, green on all engines. Guards: (1) local dirs via CreateObject("java","java.io.File").init(path).mkdirs(), not Lucee-only DirectoryCreate(path,true); (2) FileReadBinary()/multipart bytes are byte[] on Lucee7/Adobe but int-array on BoxLang/Lucee6 — pass to cfhttp/JDBC without an IsArray guard; (3) the S3 cfhttp wrapper must build a plain struct of headers (never attributeCollection=arguments — Adobe 2023/2025 reject it). No closures-as-constructor-args, no obj.map(), no reserved-scope params.

   Open questions

   • Local serving route is the one genuinely new infra piece (built-in route + handler verifying an HMAC token before streaming). Always-on, opt-in per-disk (serve=true), or only when a local disk declares urlPrefix?
   • Credentials: get()/env only for Phase 1, or also instance-profile/~/.aws later?
   • visibility on local: map to file-mode bits or ignore and rely on the serving route (suggest the latter for Phase 1)?
   • Ship the 6-method core or also copy/move/size/putStream/getStream now?

   Confidence: medium

   API shape has strong cross-framework consensus and respects every Wheels convention + cross-engine invariant (SigV4 de-risked by JwtService prior art), but it introduces a built-in local-file-serving route + handler and a from-scratch SigV4 signer — genuinely new infrastructure (the auto-downgrade-to-low trigger). Held at medium not low because the issue author already pre-decided that infra direction in the body (vendor/wheels/storage/, local+S3, cfhttp signing, signed URLs), so the "should we build this" discussion the low-rule guards is settled; what remains is API ergonomics, where the frameworks converge.

   Sources

   • https://guides.rubyonrails.org/active_storage_overview.html · https://github.com/rails/rails/blob/main/activestorage/lib/active_storage/service/s3_service.rb
   • https://laravel.com/docs/filesystem · https://github.com/laravel/framework/blob/12.x/src/Illuminate/Filesystem/FilesystemAdapter.php
   • https://docs.djangoproject.com/en/5.1/ref/files/storage/ · https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html
   • https://docs.spring.io/spring-framework/reference/core/resources.html · https://docs.awspring.io/spring-cloud-aws/docs/3.1.1/apidocs/io/awspring/cloud/s3/S3Template.html
   • https://waffle.hexdocs.pm/Waffle.Storage.S3.html · https://ex-aws-s3.hexdocs.pm/ExAws.S3.html
   • https://flydrive.dev/docs/disk_api · https://docs.adonisjs.com/guides/digging-deeper/drive
3. bpamiri

   added

   enhancement

   roadmapRoadmap / tracking issue grouping scheduled workRoadmap / tracking issue grouping scheduled work

   on Jun 13, 2026
4. bpamiri

   added a commit that references this issue on Jun 24, 2026

   feat(storage): add storage-disk abstraction with local and S3 drivers (…

   ...

   d2bb78a
5. bpamiri

   closed this as completedin #3248on Jun 24, 2026