storj/satellite/console/wasm
Jessica Grebenschikov 3cc98de3ee satellite/console/wasm: reduce size to <9MB
Make changes so that we only import the necessary files from the console package so that the generated wasm code is as small as possible.

This change gets the compiled wasm code down to 8.6MB uncompressed and 2MB when compressed with `gzip --best`.

https://review.dev.storj.io/c/storj/storj/+/3396

Change-Id: Ifdd4be285810757b46bbbe43327c0d0139e5f8f7
2020-12-14 16:41:39 +00:00
..
main.go satellite/console/wasm: reduce size to <9MB 2020-12-14 16:41:39 +00:00
README.md build: add wasm bits to Dockerfile and bump to go v1.15.6 (#3992) 2020-12-11 02:23:39 +01:00

Using WebAssembly in Storj

In order to use the uplink library from the browser, we can compile the uplink library to WebAssembly (wasm).

Setup

To generate wasm code that can create access grants in the web browser, run the following from the storj/wasm directory:

$ GOOS=js GOARCH=wasm go build -o access.wasm storj.io/storj/satellite/console/wasm

The access.wasm code can then be loaded into the browser in a script tag in an html page. Also needed is a JavaScript support file which ships with golang.

To copy the JavaScript support file, run:

$ cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .

Ref: Golang WebAssembly docs

The HTML file should include the following:

<script type="text/javascript" src="/path/to/wasm_exec.js"></script>
<script>
    const go = new Go();
    WebAssembly.instantiateStreaming(
        fetch("/path/to/access.wasm"), go.importObject).then(
        (result) => {
            go.run(result.instance);
    });
</script>

Additionally, the HTTP Content-Security-Policy (CSP) script-src directive will need to be modified to allow wasm code to be executed.

See: WebAssembly Content Security Policy docs

Usage

function newPermission

function newPermission()
  • Returns:

    {
        value: {
                AllowDownload: false,
                AllowUpload: false,
                AllowDelete: false,
                AllowList: false,
                NotBefore: "0001-01-01T00:00:00Z",
                NotAfter: "0001-01-01T00:00:00Z",
               },
        error: ""
    }
    
  • Usage:

    newPermission creates a new Permission object with all available permission settings set to default value.

  • Example:

        var permission = newPermission().value;
        permission.AllowedDownload = true;
    

function setAPIKeyPermission

function setAPIKeyPermission(apiKey, buckets, permission)

  • Arguments Accepts three arguments: apiKey, buckets and permission

    • apiKey

      • Type: String
      • Details: This parameter is required
    • buckets

      • Type: Array
      • Details: An array of bucket names that restrict the api key to only contain enough information to allow access to just those buckets. If no bucket names are provided, meaning an empty array, then all buckets are allowed. This parameter is required.
    • permission

      • Type: Object
      • Details: An object that defines what actions can be used for a given api key. It should be constructed by calling newPermission See also: b8e0f0a906/access.go (L46) This parameter is required.
  • Returns

    {
        value: "restricted-api-key",
        error: ""
    }
    
    • if an error message is returned, value will be set to an empty string.
  • Usage Creates a new api key with specific permissions.

  • Example

        var apiKey = "super-secret-key";
        var buckets = ["test-bucket"];
        var permission = newPermission().value
        permission.allowUpload = true
        var restrictedAPIKey = setAPIKeyPermission(apiKey, buckets, permission)
    

function generateAccessGrant

function generateAccessGrant(satelliteNodeURL, apiKey, encryptionPassphrase, projectID)

  • Arguments Accepts four arguments: satelliteNodeURL, apiKey, encryptionPassphrase and projectID

    • satelliteNodeURL

      • Type: String
      • Details: A string that contains satellite node id and satellite address. Example: 12tDhBcuMevundiuZPQJd613iW5vCdFtkRDBjBEfjdVtv1hbfCL@127.0.0.1:10000 This parameter is required
    • apiKey

      • Type: String
      • Details: This parameter is required
    • encryptionPassphrase

      • Type: String
      • Details: A string that's used for encryption. This parameter is required.
    • projectID

      • Type: String
      • Details: A project-based salt for determinitic key derivation. Currently it's referring to a project ID. However, it might change in the future to have more randomness. This parameter is required.
  • Returns

    {
        value: "access-grant",
        error: ""
    }
    
    • if an error message is returned, value will be set to an empty string.
  • Usage Creates a new api key with specific permissions.

  • Example

        var satelliteNodeURL = "12tDhBcuMevundiuZPQJd613iW5vCdFtkRDBjBEfjdVtv1hbfCL@127.0.0.1:10000"
        var apiKey = "super-secret-key";
        var passphrase = "123";
        var projectID = "project-id"
        var result = generateAccessGrant(satelliteNodeURL, apiKey, passphrase, projectID);
        if (result.err != "") {
            // something went wrong
        }
        var access = result.value