Bucket

The library is a storage library for canisters to manage Stable Memory.

As far as we know, canisters that storage data into stable memory have many advantages, such as :

• upgradable (when rts memory goes large)
• larger storage space : Stable Memory can be allocated to 8 GB as present
• no GC cost

Therefore, In order to be compatible with the existing development ecology, we develop two versions :

• Bucket
• Bucket-HTTP

You can use this as simple as using the TireMap.

Bucket

• First, you need to import Bucket in your project

  import Bucket "Bucket";

• Second, you need to declare a Bucket

  upgrade ：This means that you can upgrade your canister without discarding files stored in the stablememory. Meanwhile available stablememory will become aval_stablememory = 8G - heap memory

  let bucket = Bucket.Bucket(true); // true : upgradable, false : unupgradable

  You have a few more things to do below:

  1. you should use a stable entries to store your key-value pairs during upgrade

     stable var bucket_entries: [(Text,[(Nat64, Nat)])] = [];

  2. You also need to configure the system function preupgrade and postupgrade

         system func preupgrade(){
             bucket_entries := bucket.preupgrade();
         };
     
         system func postupgrade(){
             bucket.postupgrade(bucket_entries);
             bucket_entries := [];
         };

  nonupgradable : This means that if you upgrade your canister, you will discard files stored in the stablememory

  let bucket = Bucket.Bucket(false); // true : upgradable, false : nonupgradable

• Third,configure the dfx.json

  you should point out how much stable memory pages you want to use in dfx.json(recommendation : 131072)

  "build" :{
     "args": "--max-stable-pages=131072" // the max size is 131072 [131072 = 8G / 64KB(each page size)]
  }

more details please read the demo

API

• put ：put the value into stablememory,use key to index

  ​ if you add it again with the same key, it will overwrite the previous file

  public func put(key: Text, value : Blob): Result.Result<(), Error>

  tips: you can transform any type T to Text by using debug_show(t: T)

• append ：put the value into stablememory,use key to index

  ​ if added again with the same key, it will be merged with the previous file block

  public func append(key: Text, value : Blob): Result.Result<(), Error>

  tips: you can transform any type T to Text by using debug_show(t: T)

• get : use the key to get the value

  public func get(key: Text): Result.Result<[Blob], Error>

• preupgrade : return entries

  public func preupgrade(): [(Text, [(Nat64, Nat)])]

• postupgrade

  public func postupgrade(entries : [(Text, [(Nat64, Nat)])]): ()

Bucket-HTTP

The difference between Bucket-HTTP and Bucket is that Bucket-HTTP has built-in http_request, so people can query files through example : canisterID.raw.ic0.app/static/key

example

https://2fli5-jyaaa-aaaao-aabea-cai.raw.ic0.app/static/0

Due to the problem of IC mainnet, HTTP-StreamingCallback cannot work at present, so only files less than or equal to 3M can be accessed through http.

We will fix this deficiency as soon as possible.

The preparation is almost the same as the above, just change Bucket to Bucket-HTTP

more details please read the demo

API

• put ：put the value into stablememory,use key to index

  ​ if you add it again with the same key, it will overwrite the previous file

  public func put(key: Text, value : Blob): Result.Result<(), Error>

  tips: you can transform any type T to Text by using debug_show(t: T)

• append ：put the value into stablememory,use key to index

  ​ if added again with the same key, it will be merged with the previous file block

  public func append(key: Text, value : Blob): Result.Result<(), Error>

  tips: you can transform any type T to Text by using debug_show(t: T)

• get : use the key to get the value

  public func get(key: Text): Result.Result<[Blob], Error>

• build_http : Pass in the function that parses the key in the url,the key is used to get the value

  ATTENTION : YOU MUST SET YOUR DECODE FUNCITON OR REWRITE IT AND CALL THE BUILD FUNCTION TO ENABLE IT WHEN YOU NEED TO USE THE HTTP INTERFACE.

  public func build_http(fn_: DecodeUrl): ()

  public type DecodeUrl = (Text) -> (Text);

• http_request

  public func http_request(request: HttpRequest): HttpResponse

• preupgrade : return entries

  public func preupgrade(): [(Text, [(Nat64, Nat)])]

• postupgrade

  public func postupgrade(entries : [(Text, [(Nat64, Nat)])]): ()

Disclaimer

YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT USE OF THIS SOFTWARE IS AT YOUR SOLE RISK. AUTHORS OF THIS SOFTWARE SHALL NOT BE LIABLE FOR DAMAGES OF ANY TYPE, WHETHER DIRECT OR INDIRECT.

Contributing

We'd like to collaborate with the community to provide better data storage standard implementation for the developers on the IC, if you have some ideas you'd like to discuss, submit an issue, if you want to improve the code or you made a different implementation, make a pull request!