Storage
Juno Storage is designed for app developers who need to store and serve user-generated content, such as photos or videos.
It offers a powerful and cost-effective object storage solution on the blockchain.
To use Juno Storage's features, you must install and initialize the Juno SDK in your app.
How does it work?
Each satellite you create includes a "Storage" provider, which can store assets (images, documents, videos, etc.) that are automatically made available on the internet.
Assets are stored in "collections" and you can have as many collections as you wish.
Each asset within a collection is identified by a path
-- e.g. /images/a-user-image.jpg
-- unique within all collections. Assets hold the data you want to persist on chain, along with metadata (the "owner" or creator of the asset).
Unless you use the optional token
parameter to persist an asset in your satellite and make its URL difficult to guess, any asset stored in Juno Storage will be publicly available on the internet.
Limitation
Each satellite has specific memory limits. For detailed information, please refer to the related documentation page.
There is no specific limit on the size of assets (files) that can be uploaded to Juno, unless you choose to set an optional rule to restrict it.
Collections
You can create or update a collection in the "Collections" tab in Juno's console under the storage view.
Rules
A rule is assigned to a collection to define read and write permissions, which can be configured as public
, private
, managed
, or controllers
.
Assets are publicly accessible on the Internet regardless of the permission schema. The rules are only applied when reading or writing the data through the library.
public
: everyone can read from (resp. write to) any asset in the collectionprivate
: only the owner of a asset and can read from (resp. write to) a document in the collectionmanaged
: the owner of an asset and the controllers of the satellite can read from (resp. write to) an asset in the collectioncontrollers
: only the controllers of the satellite can read from (resp. write to) any asset in the collection
- Rules can be modified at any time and changes will be applied immediately
- Any collection with read permission set as
public
,managed
orcontrollers
can be viewed in the console's storage view.
Memory
When you create a collection, it's assigned to either heap or stable memory. This assignment is permanent and cannot be changed once the collection is created. The default allocation is stable
memory.
Max size
You can also set an optional parameter that limits the size, in bytes, of assets that can be uploaded to a collection.
Upload asset
To upload an asset, use the following code:
import { uploadFile } from "@junobuild/core";
const result = await uploadFile({
data,
collection: "images",
});
The data
parameter is the file you want to upload. This is typically selected using an HTML <input type="file" />
element.
The uploadFile
function provides various options, including:
filename
: By default, Juno uses the file's filename. You can overwrite this and provide a custom filename. Example:myimage.jpg
.fullPath
: Juno will automatically compute thefullPath
, which is the unique path that is used to make the asset available on the internet. ThefullPath
is the filename encoded as a URL and prefixed with/
plus the related collection key. Example:/images/myimage.jpg
.headers
: The headers can affect how the browser handles the asset. If no headers are provided Juno will infer theContent-Type
from the file type.encoding
: The type of encoding for the file. For example,identity
(raw) orgzip
.
-
Uploading a file with the same name as an existing file will overwrite the previous file (assuming the uploader has write access to the previous file).
-
To ensure that the asset has a clean URL and is easily accessible on the internet, the library converts the
filename
to lowercase and replaces any spaces with dashes.
Protected asset
While all assets can be found on the internet, it is possible to make their URL difficult to guess so that they remain undiscoverable (as long as they are not shared) and considered "private".
Juno achieves this by using an optional token
query parameter.
import { uploadFile } from "@junobuild/core";
import { nanoid } from "nanoid";
const result = await uploadFile({
data,
collection: "images",
token: nanoid(),
});
Imagine a file "mydata.jpg" uploaded with a token. Attempting to access it through the URL "https://yoursatellite/mydata.jpg" will not work. The asset can only be retrieved if a token is provided: "https://yoursatellite/mydata.jpg?token=a-super-long-secret-id".
List assets
The "Storage" provider offers a way to list assets.
import { listAssets } from "@junobuild/core";
const myList = await listAssets({
collection: "images",
});
The listAssets
function -- in addition to specifying the collection to query -- accepts various optional parameters:
matcher
: a regex to apply to the assets'fullPath
anddescription
paginate
: an object used to query a subset of the assetsorder
: requests entries sorted in ascending or descending order
Delete asset
To delete an asset, you only need to provide its fullPath
. Unlike the datastore, there is no timestamp validation performed when deleting an asset.
import { deleteAsset } from "@junobuild/core";
await deleteAsset({
collection: "images",
storageFile: myAsset,
});
Delete multiple assets
To delete multiple assets in an atomic manner, you can use the function deleteManyAssets
:
import { deleteManyAssets } from "@junobuild/core";
await deleteManyAssets({ docs: [myAsset1, myAsset2, myAsset3] });