From 4f4e0bfc2cb2a68a08f6f4cffcb165de5e2fb8b3 Mon Sep 17 00:00:00 2001 From: Pavel Date: Thu, 30 Dec 2021 13:34:38 +0300 Subject: [PATCH] Add documentation about running AVM in the background (#30) --- fluence-js/2_basics.md | 4 ++++ fluence-js/4_run_in_browser-1.md | 21 ++++++++++++++++++++ fluence-js/5_run_in_node.md | 19 +++++++++--------- fluence-js/changelog.md | 33 ++++++++++++++++++++++++++++++++ 4 files changed, 68 insertions(+), 9 deletions(-) diff --git a/fluence-js/2_basics.md b/fluence-js/2_basics.md index eb69eda..e024264 100644 --- a/fluence-js/2_basics.md +++ b/fluence-js/2_basics.md @@ -188,3 +188,7 @@ If everything has been done correctly yuo should see `Hello, world!` in the cons The next section will cover in-depth and advanced usage of Fluence JS The code from this section is available in on [github](https://github.com/fluencelabs/examples/tree/main/fluence-js-examples/hello-world) + +## Running Fluence application in different environments + +Fluence JS instantiates Aqua Virtual Machine (AVM) from wasm file and runs it in the background thread. Different mechanism are used depending on the JS environment. In nodejs worker threads are used for background execution and wasm file is read from the filesystem. In browser-based environments web workers are used and the wasm file is being loaded from server hosting the application. Next two sections cover how to configure a fluence application depending on the environment. diff --git a/fluence-js/4_run_in_browser-1.md b/fluence-js/4_run_in_browser-1.md index 7301e6c..a1dc68a 100644 --- a/fluence-js/4_run_in_browser-1.md +++ b/fluence-js/4_run_in_browser-1.md @@ -2,6 +2,27 @@ You can use the Fluence JS with any framework (or even without it). The "fluence" part of the application is a collection of pure typescript\javascript functions which can be called withing any framework of your choosing. +## Configuring application to run in browser + +To run application in browser you need to configure the server which hosts the application to serve two additional files: + +- `avm.wasm` is the execution file of AquaVM. The file is located in `@fluencelabs/avm` package +- `runnerScript.web.js` is the web worker script responsible for running AVM in background. The file is located in `@fluencelabs/avm-runner-background` package + +Fluence JS provides a utility script named `copy-avm-public` which locates described above files and copies them into the specified directory. For example if static files are served from the `public` directory you can run `copy-avm-public public` to copy files needed to run Fluence. It is recommended to put their names into `.gitignore` and run the script on every build to prevent possible inconsistencies with file versions. This can be done using npm's `postinstall` script: + +``` + ... + "scripts": { + "postinstall": "copy-avm-public public", + "start": "...", + .. + }, + ... +``` + +## Demo applications + See the browser-example which demonstrate integrating Fluence with React: [github](https://github.com/fluencelabs/examples/tree/main/fluence-js-examples/browser-example) Also take a look at FluentPad. It is an example application written in React: [https://github.com/fluencelabs/fluent-pad](https://github.com/fluencelabs/fluent-pad) diff --git a/fluence-js/5_run_in_node.md b/fluence-js/5_run_in_node.md index 8d73254..db02c85 100644 --- a/fluence-js/5_run_in_node.md +++ b/fluence-js/5_run_in_node.md @@ -1,19 +1,21 @@ # Running app in nodejs -## Intro - It is easy to use Fluence JS in NodeJS applications. You can take full advantage of the javascript ecosystem and at the save time expose service to the Fluence Network. That makes is an excellent choice for quick prototyping of applications for Fluence Stack. +## Configuring application to run in nodejs + +`@fluencelabs/fluence` delivers AquaVM wasm file through the npm package. No additional configuration is needed. + ## Calc app example Lets implement a very simple app which simulates a desk calculator. The calculator has internal memory and implements the following set of operations: -* Add a number -* Subtract a number -* Multiply by a number -* Divide by a number -* Get the current memory state -* Reset the memory state to 0.0 +- Add a number +- Subtract a number +- Multiply by a number +- Divide by a number +- Get the current memory state +- Reset the memory state to 0.0 First, let's write the service definition in aqua: @@ -120,4 +122,3 @@ func demoCalculation() -> f32: res <- Calc.getResult() <- res ``` - diff --git a/fluence-js/changelog.md b/fluence-js/changelog.md index 3a237a8..4300d55 100644 --- a/fluence-js/changelog.md +++ b/fluence-js/changelog.md @@ -6,6 +6,39 @@ Fluence JS versioning scheme is the following: `0.BREAKING.ENHANCING` - `BREAKING` part is incremented for each breaking API change - `ENHANCING` part is incremented for every fix and update which is compatible on API level +## [0.18.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.18.0) – December 29, 2021 + +FluencePeer: Update AVM version to 0.20.0 \([\#120](https://github.com/fluencelabs/fluence-js/pull/120)\) + +## [0.17.1](https://github.com/fluencelabs/fluence-js/releases/tag/v0.17.1) – December 29, 2021 + +FluencePeer: Update AvmRunner to 0.1.2 (fix issue with incorrect baseUrl) \([\#119](https://github.com/fluencelabs/fluence-js/pull/119)\) + +## [0.17.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.17.0) – December 28, 2021 + +JS Peer does not embed AVM interpreter any more. Instead [AVM Runner](https://github.com/fluencelabs/avm-runner-background) is used to run AVM in background giving huge performance boost. This is a **breaking change**: all browser applications now not need to bundle `avm.wasm` file and the runner script. See documentation for more info. + +\([\#111](https://github.com/fluencelabs/fluence-js/pull/120)\) + +## [0.16.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.16.0) – December 22, 2021 + +FluencePeer: Update AVM version to 0.19.3 \([\#115](https://github.com/fluencelabs/fluence-js/pull/115)\) + +## [0.15.4](https://github.com/fluencelabs/fluence-js/releases/tag/v0.15.4) – December 13, 2021 + +FluencePeer: Update AVM version to 0.17.7 \([\#113](https://github.com/fluencelabs/fluence-js/pull/113)\) + +## [0.15.3](https://github.com/fluencelabs/fluence-js/releases/tag/v0.15.3) – December 10, 2021 + +**FluencePeer:** + +- Add built-in service to sign data and verify signatures \([\#110](https://github.com/fluencelabs/fluence-js/pull/110)\) +- Update AVM version to 0.17.6 \([\#112](https://github.com/fluencelabs/fluence-js/pull/112)\) + +## [0.15.2](https://github.com/fluencelabs/fluence-js/releases/tag/v0.15.2) – November 30, 2021 + +Add particleId to error message when an aqua function times out \([\#106](https://github.com/fluencelabs/fluence-js/pull/106)\) + ## [0.15.1](https://github.com/fluencelabs/fluence-js/releases/tag/v0.15.0) – November 28, 2021 **FluencePeer:**