Active Storage File Upload Behind The Scenes

Active Storage is a framework in Ruby that makes it a breeze to upload files and reference them in the cloud (or a local disk). It’s built into Ruby On Rails 6, but it’s also got a JavaScript library. In fact, that’s what I like most about Rails. It’s got your back. It delivers complete packages out of the box. Packages that work well together. Client to server — it’s got everything you need! And it’s got beautiful code. Making it a pleasure to work with.

In this post, you will see how Active Storage really works from the inside. We will track the main flow of the program, and see how it processes a file uploaded by the user through the browser with JavaScript. And then, how the file is uploaded to a local disk with Ruby. Let’s get started.


It all starts here, with autostart.This is the function that starts everything in the Active Storage world. It invokes the start() function (which we’ll look at shortly) if the ActiveStorage object is present in the browser’s window. Here it is:

Then, Active Storage uses a setTimeout function to automatically call the autostart function after one millisecond:


So what does start do? Looking at the start function, first it’s doing a check to make sure the application hasn’t already started, and if so, it makes a note of it by setting started to true. The next thing it does is to attach an event listener to the submit event with the handler didSubmitForm. That means that didSubmitForm will run every time the submit event is triggered by the user. The event will be triggered after the user has submitted the form with the file they chose to upload. That’s what it looks like:

Did Submit Form

Once a user has uploaded a file, Active Storage will run the handler didSubmitForm. Which in turn will pass the event to handleFormSubmissionEvent, and invoke (call) it.

Handle Form Submission Event

What’s the handleFormSubmissionEvent function all about? It’s creating an instance of the DirectUploadsController with the specific form the user has submitted. And it’s starting it with controller.start(). This controller’s API is such a delight!

Direct Uploads Controller

In the Direct Uploads controller Active Storage creates a new instance of the DirectUpload JavaScript model, passing it the file the user is uploading, its url, and an instance of the controller class.

Direct Upload

It’s in this model that the core of the process is taking place. It does two things: It creates a fresh new blob instance from the BlobRecord model, which saves the meta data of the file the user is uploading in the database without actually uploading the file to the disk. And then, it calls create() on the blob instance and passes it a callback. It’s in this callback that the actual file upload happens.

The way it does that is by creating a new upload instance from the BlobUpload model class passing it the blob in question.

Blob Record

The BlobRecord model actually creates an AJAX POST request to the server. From here the Rails controller in the back-end handles the request.

Direct Uploads Controller

Active Storage has its own base controller class that inherits directly from ActionController::Base. It’s called ActiveStorage::BaseController, which just keeps things clean with one root controller for the back-end of the framework.

The controller calls create_before_direct_upload which just calls create, and creates a new instance of the ActiveStorage::Blob back-end model in Ruby. Here it’s essentially writing the meta data of the file uploaded to the database. The server returns some JSON with the url and the service headers for direct upload.

Blob Upload

This is the second AJAX request it makes to the server. This time it’s a PUT request which will go directly to the DiskController in the back-end which in turn uploads the file to the service (in this case a local disk).

Disk Controller

Finally. That actual file upload to the disk happens here. The controller responds with an update action which will delegate to ActiveStorage::Blob and calls upload on the service. At this point the process is finalized and the file is present on the service.

Focusing on the main flow

Of course there’s a lot more to the Active Storage file upload process, and I simplified things a little bit. But I just wanted to get a feel of what the main flow of the program looks like. This framework is HIGHLY documented so I suggest you take it for a spin yourself. Enjoy!

For more posts, subscribe to That Weekly Tech.

Written by

Founder & CEO of Bonfire: Simple Project Management Software, I write That Weekly Tech (

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store