xxdk-WASM

This repository contains the WebAssembly bindings for xxDK. It also includes examples and a test server to serve the compiled WebAssembly module.

Building

The repository can only be compiled to a WebAssembly binary using GOOS=js and GOARCH=wasm.

$ GOOS=js GOARCH=wasm go build -o xxdk.wasm

Running Unit Tests

Because the bindings use syscall/js, tests cannot only be run in a browser. To automate this process first get wasmbrowsertest and follow their installation instructions. Then, tests can be run using the following command.

$ GOOS=js GOARCH=wasm go test ./...

Note, this will fail because utils/utils_js.s contains commands only recognized by the Go WebAssembly compiler and for some reason are not recognized by the test runner. To get tests to run, temporarily delete the body of utils/utils_js.s during testing.

Testing and Examples

The example directory contains various directories each containing a different example. Each example contains one or more cMix clients running in javascript. It also contains a server directory, which runs a simple Go HTTP server to deliver the webpages. The assets directory contains files used by all the examples.

To run the server, first compile the bindings and save them to the assets directory. Then run the server

$ GOOS=js GOARCH=wasm go build -o examples/xxdk.wasm
$ cd examples/server/
$ go run main.go

Navigate to http://localhost:9090 to see a list of files in the server and navigate to a .html file in any of the examples to open a client.

wasm_exec.js

wasm_exec.js is provided by Go and is used to import the WebAssembly module in the browser. It can be retrieved from Go using the following command.

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

Note that this repository makes edits to wasm_exec.js and you must either use the one in this repository or add the following lines in the go importObject on global.Go.

global.Go = class {
    constructor() {
        // ...
        this.importObject = {
            go: {
                // ...
                // func Throw(exception string, message string)
                'gitlab.com/elixxir/xxdk-wasm/utils.throw': (sp) => {
                    const exception = loadString(sp + 8)
                    const message = loadString(sp + 24)
                    throw globalThis[exception](message)
                },
            }
        }
    }
}