Skip to main content
API contract 3.4
Premium

Chunked uploads

Large files go straight to storage in chunks instead of travelling base64-encoded inside the create or update request.

Below a configurable threshold nothing changes — a small image is still embedded in the payload. Above it the browser uploads to S3 or a tus server, and the request carries only a reference the backend resolves on save.

Chunked uploads ship in the paid habarico-enterprise gem — see Installation. Without it every file field keeps using the base64 path and no options.upload block is emitted at all.

habarico_enterprise/uploads is an opt-in module — it is not loaded by require "habarico_enterprise" — for Eluvia::File/file_attr-backed fields. Ruby habarico assumes a single default ActiveStorage service, so provider selection is global rather than per field; see Provider selection.

Pages​

PageWhat it covers
InstallationAdding the gem, habarico_enterprise/uploads and its routes
ConfigurationThreshold, chunk size and provider settings
Provider selectionS3 multipart vs. tus, and how the single-storage assumption differs from Python
tus server setupRunning and securing a tusd service
S3 temporary file cleanupRemoving abandoned uploads
Frontend contractWhat the browser sends and when, and the content-type / size rules initiate enforces

How it fits together​

  1. The backend adds options.upload to the field schema — provider, threshold, chunk size.
  2. UploadInput reads it and picks the path per file.
  3. For the S3 provider, initiate refuses the upload up front when the claimed content type or size is not allowed for that field — see Upload validations.
  4. A chunked upload finishes with an upload_key; Eluvia::File#upload_key's finalize step (the eluvia-base extension point this module registers) turns it into an ActiveStorage attachment when the record is saved.
caution

Client-side resize and crop only apply to the base64 path. A file large enough to be chunked is uploaded untouched — see the caution on UploadInput.

See also​