Read, download files

general considerations

• The client SDK enforces access-rules. Some functions allow the user to save a bearer URL which bypasses the security rules (one-off access control).
• Download workflows are influenced by the browser requirements and restrictions.

get a HTTP URL on the client

We may request a read URL. Access control is performed when requesting the URL.

The returned URL is a bearer URL, which is not subject to access-control. We consume it outside the realm of the Storage SDK, as a regular URL.

Note: the URL remains valid unless manually revoked at the file level in the Firebase Console.

getDownloadURL(fileRef).then(url => ...)

consume a cross-origin HTTP URL on the client.

The URL is cross-origin. The challenges and patterns to consume a cross-origin URL are not specific to Firebase.

Buckets do not have permissive CORS headers by default, but we may add them on demand. As a reminder, CORS headers may whitelist one, several or all domains. We use gsutil or gcloud to whitelist our domain, if necessary (see the dedicated chapter).

The way we consume the URL determines if CORS headers are necessary.

• The browser allows cross-origin URLs in media elements' src attribute (hot linking), with no CORS headers required.
• The browser allows navigating to cross-origin URLs (basic browser behavior). For example, we navigate to an image in a new tab.
• The browser doesn't allow background fetch of cross-origin resources unless explicit CORS headers are present on the server. This applies to fetch() and functions that rely on it.

download a Blob with the client SDK

A blob is an opaque object that we can transform to a local URL. When downloading a Blob with the SDK's getBlob():

• access rules are enforced
• CORS headers are required (it uses fetch() under the hood)

When we create a local (same-origin) URL out of the blob, we avoid the browser restrictions related to cross-origin URLs. It restores the ability to download content through a single click, without navigating to a different URL (see below).

getBlob(fileRef).then((blob) => {
    // create a local URL and trigger download imperatively
})

URLs in anchor tags and the download attribute

The download attribute on an anchor tag (<a href="" download>) aims to offer one-click downloads. The pattern only works for same-origin URLs or local URLs.

For cross-origin URLs, clicking the anchor tag triggers standard browser navigation instead: the browser navigates to the resource and shows its full URL.

create a local URL out of a blob (browser specific)

This examples creates a local URL, triggers download programmatically and revokes the local URL for clean up.

// 3. Create a local URL for the blob
const objectURL = URL.createObjectURL(blob)

// 4. Use the local URL to trigger the download
const link = document.createElement("a")
link.href = objectURL
link.download = img.id + ".png"
document.body.appendChild(link)
link.click()
document.body.removeChild(link)

// 5. Clean up by revoking the local URL
URL.revokeObjectURL(objectURL)