Safe for Direct Uploads in js Libraries or Frameworks

activestorage/CHANGELOG.md

@@ -145,4 +145,12 @@
 
     *Luke Lau*
 
+*   Safe for direct upload on Libraries or Frameworks
+
+    Enable the use of custom headers during direct uploads, which allows for
+    the inclusion of Authorization bearer tokens or other forms of authorization
+    tokens through headers.
+
+    *Radamés Roriz*
+
 Please check [7-0-stable](https://github.com/rails/rails/blob/7-0-stable/activestorage/CHANGELOG.md) for previous changes.

activestorage/app/assets/javascripts/activestorage.esm.js

@@ -508,7 +508,7 @@ function toArray(value) {
 }
 
 class BlobRecord {
-  constructor(file, checksum, url) {
+  constructor(file, checksum, url, customHeaders = {}) {
     this.file = file;
     this.attributes = {
       filename: file.name,
@@ -522,6 +522,9 @@ class BlobRecord {
     this.xhr.setRequestHeader("Content-Type", "application/json");
     this.xhr.setRequestHeader("Accept", "application/json");
     this.xhr.setRequestHeader("X-Requested-With", "XMLHttpRequest");
+    Object.keys(customHeaders).forEach((headerKey => {
+      this.xhr.setRequestHeader(headerKey, customHeaders[headerKey]);
+    }));
     const csrfToken = getMetaValue("csrf-token");
     if (csrfToken != undefined) {
       this.xhr.setRequestHeader("X-CSRF-Token", csrfToken);
@@ -604,19 +607,20 @@ class BlobUpload {
 let id = 0;
 
 class DirectUpload {
-  constructor(file, url, delegate) {
+  constructor(file, url, delegate, customHeaders = {}) {
     this.id = ++id;
     this.file = file;
     this.url = url;
     this.delegate = delegate;
+    this.customHeaders = customHeaders;
   }
   create(callback) {
     FileChecksum.create(this.file, ((error, checksum) => {
       if (error) {
         callback(error);
         return;
       }
-      const blob = new BlobRecord(this.file, checksum, this.url);
+      const blob = new BlobRecord(this.file, checksum, this.url, this.customHeaders);
       notify(this.delegate, "directUploadWillCreateBlobWithXHR", blob.xhr);
       blob.create((error => {
         if (error) {

activestorage/app/javascript/activestorage/blob_record.js

@@ -1,7 +1,7 @@
 import { getMetaValue } from "./helpers"
 
 export class BlobRecord {
-  constructor(file, checksum, url) {
+  constructor(file, checksum, url, customHeaders = {}) {
     this.file = file
 
     this.attributes = {
@@ -17,6 +17,9 @@ export class BlobRecord {
     this.xhr.setRequestHeader("Content-Type", "application/json")
     this.xhr.setRequestHeader("Accept", "application/json")
     this.xhr.setRequestHeader("X-Requested-With", "XMLHttpRequest")
+    Object.keys(customHeaders).forEach((headerKey) => {
+      this.xhr.setRequestHeader(headerKey, customHeaders[headerKey])
+    })
 
     const csrfToken = getMetaValue("csrf-token")
     if (csrfToken != undefined) {

activestorage/app/javascript/activestorage/direct_upload.js

@@ -5,11 +5,12 @@ import { BlobUpload } from "./blob_upload"
 let id = 0
 
 export class DirectUpload {
-  constructor(file, url, delegate) {
+  constructor(file, url, delegate, customHeaders = {}) {
     this.id = ++id
     this.file = file
     this.url = url
     this.delegate = delegate
+    this.customHeaders = customHeaders
   }
 
   create(callback) {
@@ -19,7 +20,7 @@ export class DirectUpload {
         return
       }
 
-      const blob = new BlobRecord(this.file, checksum, this.url)
+      const blob = new BlobRecord(this.file, checksum, this.url, this.customHeaders)
       notify(this.delegate, "directUploadWillCreateBlobWithXHR", blob.xhr)
 
       blob.create(error => {

guides/source/active_storage_overview.md

@@ -1162,11 +1162,8 @@ input[type=file][data-direct-upload-url][disabled] {
 }
 ```
 
-### Integrating with Libraries or Frameworks
-
-If you want to use the Direct Upload feature from a JavaScript framework, or
-you want to integrate custom drag and drop solutions, you can use the
-`DirectUpload` class for this purpose. Upon receiving a file from your library
+### Custom drag and drop solutions
+you can use the `DirectUpload` class for this purpose. Upon receiving a file from your library
 of choice, instantiate a DirectUpload and call its create method. Create takes
 a callback to invoke when the upload completes.
 
@@ -1213,10 +1210,11 @@ const uploadFile = (file) => {
 }
 ```
 
-If you need to track the progress of the file upload, you can pass a third
-parameter to the `DirectUpload` constructor. During the upload, DirectUpload
-will call the object's `directUploadWillStoreFileWithXHR` method. You can then
-bind your own progress handler on the XHR.
+### Track the progress of the file upload
+When using the `DirectUpload` constructor, it is possible to include a third parameter.
+This will allow the `DirectUpload` object to invoke the `directUploadWillStoreFileWithXHR` 
+method during the upload process. 
+You can then attach your own progress handler to the XHR to suit your needs.
 
 ```js
 import { DirectUpload } from "@rails/activestorage"
@@ -1248,6 +1246,59 @@ class Uploader {
 }
 ```
 
+### Integrating with Libraries or Frameworks
+Once you receive a file from the library you have selected, you need to create
+a `DirectUpload` instance and use its "create" method to initiate the upload process, 
+adding any required additional headers as necessary. The "create" method also requires 
+a callback function to be provided that will be triggered once the upload has finished.
+
+```js
+import { DirectUpload } from "@rails/activestorage"
+
+class Uploader {
+  constructor(file, url, token) {
+    const headers = { 'Authentication': `Bearer ${token}` }
+    // INFO: Sending headers is an optional parameter. If you choose not to send headers,
+    //       authentication will be performed using cookies or session data.
+    this.upload = new DirectUpload(this.file, this.url, this, headers)
+  }
+
+  upload(file) {
+    this.upload.create((error, blob) => {
+      if (error) {
+        // Handle the error
+      } else {
+        // Use the with blob.signed_id as a file reference in next request
+      }
+    })
+  }
+
+  directUploadWillStoreFileWithXHR(request) {
+    request.upload.addEventListener("progress",
+      event => this.directUploadDidProgress(event))
+  }
+
+  directUploadDidProgress(event) {
+    // Use event.loaded and event.total to update the progress bar
+  }
+}
+```
+
+To implement customized authentication, a new controller must be created on
+the backend server, similar to the following:
+```ruby
+class DirectUploadsController < ActiveStorage::DirectUploadsController
+  skip_before_action :verify_authenticity_token
+  before_action :authenticate!
+
+  def authenticate!
+    @token = request.headers['Authorization']&.split&.last
+
+    return head :unauthorized unless valid_token?(@token)
+  end
+end
+```
+
 NOTE: Using [Direct Uploads](#direct-uploads) can sometimes result in a file that uploads, but never attaches to a record. Consider [purging unattached uploads](#purging-unattached-uploads).
 
 Testing