fluencelabs/gitbook-docs
1
0
Fork 0
mirror of https://github.com/fluencelabs/gitbook-docs synced 2025-04-25 16:02:17 +00:00
Code Issues Projects Releases Wiki Activity

replace "aqua-cli" command with "aqua"

Browse Source
This commit is contained in:
Pavel Murygin 2021-09-11 15:31:32 +03:00
parent 849d9bbd44
commit f2d9dc5d04
7 changed files with 72 additions and 327 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
SUMMARY.md
View File

@ -1,34 +1,32 @@
# Table of contents # Table of contents
* [Introduction](README.md) - [Introduction](README.md)
* [Thinking In Aquamarine](p2p.md) - [Thinking In Aquamarine](p2p.md)
* [Concepts](concepts.md) - [Concepts](concepts.md)
* [Quick Start](quick-start/README.md) - [Quick Start](quick-start/README.md)
* [1. Browser-to-Browser](quick-start/1.-browser-to-browser-1.md) - [1. Browser-to-Browser](quick-start/1.-browser-to-browser-1.md)
* [2. Hosted Services](quick-start/2.-hosted-services.md) - [2. Hosted Services](quick-start/2.-hosted-services.md)
* [3. Browser-to-Service](quick-start/3.-browser-to-service.md) - [3. Browser-to-Service](quick-start/3.-browser-to-service.md)
* [Aquamarine](knowledge_aquamarine/README.md) - [Aquamarine](knowledge_aquamarine/README.md)
* [Aqua](knowledge_aquamarine/hll.md) - [Aqua](knowledge_aquamarine/hll.md)
* [Marine](knowledge_aquamarine/marine/README.md) - [Marine](knowledge_aquamarine/marine/README.md)
* [Marine CLI](knowledge_aquamarine/marine/marine-cli.md) - [Marine CLI](knowledge_aquamarine/marine/marine-cli.md)
* [Marine REPL](knowledge_aquamarine/marine/marine-repl.md) - [Marine REPL](knowledge_aquamarine/marine/marine-repl.md)
* [Marine Rust SDK](knowledge_aquamarine/marine/marine-rs-sdk.md) - [Marine Rust SDK](knowledge_aquamarine/marine/marine-rs-sdk.md)
* [Tools](knowledge_tools.md) - [Tools](knowledge_tools.md)
* [Node](node.md) - [Node](node.md)
* [JS SDK](js-sdk/README.md) - [JS SDK](js-sdk/README.md)
* [Concepts](js-sdk/1_concepts.md) - [Concepts](js-sdk/1_concepts.md)
* [Basics](js-sdk/2_basics.md) - [Basics](js-sdk/2_basics.md)
* [In-depth](js-sdk/3_in_depth.md) - [In-depth](js-sdk/3_in_depth.md)
* [Running app in nodejs](js-sdk/5_run_in_node.md) - [Running app in nodejs](js-sdk/5_run_in_node.md)
* [Running app in browser](js-sdk/4_run_in_browser-1.md) - [Running app in browser](js-sdk/4_run_in_browser-1.md)
* [Api reference](js-sdk/6-reference.md) - [Api reference](js-sdk/6-reference.md)
* [Changelog](js-sdk/changelog.md) - [Changelog](js-sdk/changelog.md)
* [Security](knowledge_security.md) - [Security](knowledge_security.md)
* [Tutorials](tutorials_tutorials/README.md) - [Tutorials](tutorials_tutorials/README.md)
* [Setting Up Your Environment](tutorials_tutorials/recipes_setting_up.md) - [Setting Up Your Environment](tutorials_tutorials/recipes_setting_up.md)
* [Deploy A Local Fluence Node](tutorials_tutorials/tutorial_run_local_node.md) - [Deploy A Local Fluence Node](tutorials_tutorials/tutorial_run_local_node.md)
* [cUrl As A Service](tutorials_tutorials/curl-as-a-service.md) - [cUrl As A Service](tutorials_tutorials/curl-as-a-service.md)
* [Add Your Own Builtins](tutorials_tutorials/add-your-own-builtin.md) - [Add Your Own Builtins](tutorials_tutorials/add-your-own-builtin.md)
* [Building a Frontend with JS-SDK](tutorials_tutorials/building-a-frontend-with-js-sdk.md) - [Research, Papers And References](research-papers-and-references.md)
* [Research, Papers And References](research-papers-and-references.md)

244
building-a-frontend-with-js-sdk.md
View File

@ -1,244 +0,0 @@
---
description: WIP -- Tread Carefully
---
# Building A Frontend with JS SDK
The JS SDK provides the means to connect to a Fluence peer-to-peer network from a javascript environment and is currently available for _node.js_ and modern browsers.
To create an application two building blocks are needed: the JS SDK and the Aqua compiler. Both packages are available as _npm_ packages. The JS SDK wraps the AIR interpreter and provides a connection to the network. There is la ow-level api for executing AIR scripts and registering for service call handlers. The Aqua compiler allows to write code in Aqua language and compile it to typescript code which can be directly used with the JS SDK.
### Basic usage
To demonstrate the development of a client application, we initiate a bare-bones _node.js_ package and review the steps needed to install the JS SDK and Aqua compiler.
#### 1. Install The _npm_ Package
For the purpose of the demo we will use a very minimal _npm_ package with typescript support:
```text
src
┗ index.ts (1)
package.json (2)
tsconfig.json
```
index.ts \(1\):
```typescript
async function main() {
console.log("Hello, world!");
}
main();
```
package.json \(2\):
```javascript
{
"name": "demo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"exec": "node -r ts-node/register src/index.ts"
},
"author": "",
"license": "ISC",
"devDependencies": {
"ts-node": "^9.1.1",
"typescript": "^4.2.4"
}
}
```
Let's test if it works:
```bash
$ npm install
$ npm run exec
```
The following should be printed
```bash
$ npm run exec
> demo@1.0.0 exec C:\work\demo
> node -r ts-node/register src/index.ts
Hello, world!
$ C:\work\demo>
```
#### 2. Setting JS SDK and connecting to Fluence network
Install the dependencies, you will need these two packages.
```bash
npm install @fluencelabs/fluence @fluencelabs/fluence-network-environment
```
The first one is the SDK itself and the second is a maintained list of Fluence networks and nodes to connect to.
All of the communication with the Fluence network is done by using `FluenceClient`. You can create one with `createClient` function. The client encapsulates air interpreter and connects to the network through the relay. Currently any node in the network can be used a relay.
```typescript
import { createClient } from "@fluencelabs/fluence";
import { testNet } from "@fluencelabs/fluence-network-environment";
async function main() {
const client = await createClient(testNet[1]);
console.log("Is client connected: ", client.isConnected);
await client.disconnect();
}
main();
```
Let's try it out:
```bash
$ npm run exec
> demo@1.0.0 exec C:\work\demo
> node -r ts-node/register src/index.ts
Is client connected: true
$
```
**Note**: typically you should have a single instance`FluenceClient` per application since it represents it's identity in the network. You are free to store the instance anywhere you like.
#### 3. Setting up aqua compiler
Aqua is the proffered language for the Fluence network. It can be used with javascript-based environments via _npm_ package.
**Warning: the package requires java to be installed \(it will call "java -jar ... "\)**
```bash
npm install --save-dev @fluencelabs/aqua-cli
```
We will also need the standard library for the language
```text
npm install --save-dev @fluencelabs/aqua-lib
```
Let's add our first aqua file:
```text
aqua (1)
┗ demo.aqua (2)
node_modules
src
┣ compiled (3)
┗ index.ts
package-lock.json
package.json
tsconfig.json
```
Add two directories, one for aqua sources \(1\) and another for the typescript output \(3\)
Create a new text file called `demo.aqua` \(2\):
```text
import "@fluencelabs/aqua-lib/builtin.aqua"
func demo(nodePeerId: PeerId) -> []string:
on nodePeerId:
res <- Peer.identify()
<- res.external_addresses
```
This script will gather the list of external addresses from some node in the network. For more information about the aqua language refer to the aqua documentation.
The aqua code can now be compiled by using the compiler CLI. We suggest adding a script to the package.json file like so:
```javascript
...
"scripts": {
"exec": "node -r ts-node/register src/index.ts",
"compile-aqua": "aqua-cli -i ./aqua/ -o ./src/compiled"
},
...
```
Run the compiler:
```bash
npm run compile-aqua
```
A typescript file should be generated like so:
```text
aqua
┗ demo.aqua
node_modules
src
┣ compiled
┃ ┗ demo.ts <--
┗ index.ts
package-lock.json
package.json
tsconfig.json
```
#### 4. Consuming the compiled code
Using the code generated by the compiler is as easy as calling a function. The compiler generates all the boilerplate needed to send a particle into the network and wraps it into a single call. Note that all the type information and therefore type checking and code completion facilities are there!
Let's do it!
```typescript
import { createClient } from "@fluencelabs/fluence";
import { testNet } from "@fluencelabs/fluence-network-environment";
import { demo } from "./compiled/demo"; // import the generated file
async function main() {
const client = await createClient(testNet[1]);
console.log("Is client connected: ", client.isConnected);
const otherNode = testNet[2].peerId;
const addresses = await demo(client, otherNode); // call it like a normal function in typescript
console.log(`Node ${otherNode} is connected to: ${addresses}`);
await client.disconnect();
}
main();
```
if everything is fine you have similar result:
```text
$ npm run exec
> demo@1.0.0 exec C:\work\demo
> node -r ts-node/register src/index.ts
Is client connected: true
Node 12D3KooWHk9BjDQBUqnavciRPhAYFvqKBe4ZiPPvde7vDaqgn5er is connected to: /ip4/138.197.189.50/tcp/7001,/ip4/138.197.189.50/tcp/9001/ws
$
```
### Advanced usage
Fluence JS SDK gives options to register own handlers for aqua vm service calls
**TBD**
### References
* For the list of compiler options see: [https://github.com/fluencelabs/aqua](https://github.com/fluencelabs/aqua)
* **Repository with additional examples:** [**https://github.com/fluencelabs/aqua-playground**](https://github.com/fluencelabs/aqua-playground)\*\*\*\*
**Building A Frontend with JS SDK**

11
js-sdk/1_concepts.md
View File

@ -2,7 +2,7 @@
## Basic concepts ## Basic concepts
The main export of the `@fluencelabs/fluence` package is the `FluencePeer` class. This class implements the Fluence protocol for javascript-based environments. It provides all the necessary features to communicate with Fluence network namely: `@fluencelabs/fluence` package export the `FluencePeer` class. This class implements the Fluence protocol for javascript-based environments. It provides all the necessary features to communicate with Fluence network namely:
1. Connectivity with one or many Fluence Node which allows sending particles to and receiving from other Peers 1. Connectivity with one or many Fluence Node which allows sending particles to and receiving from other Peers
2. The Peer Id identifying the node in the network 2. The Peer Id identifying the node in the network
@ -31,10 +31,9 @@ To learn more about Aqua see [aqua book](https://doc.fluence.dev/aqua-book/)
The building block of the application are: The building block of the application are:
* Aqua code for peer-to-peer communication - Aqua code for peer-to-peer communication
* Compiler cli package for aqua to \(java\)typescript compilation - Compiler cli package for aqua to \(java\)typescript compilation
* Initialization of the `FluencePeer` - Initialization of the `FluencePeer`
* Application specific code \(java\)typescript in the framework of your choice - Application specific code \(java\)typescript in the framework of your choice
In the next section we see it in action In the next section we see it in action

9
js-sdk/2_basics.md
View File

@ -36,10 +36,8 @@ The first one is the SDK itself and the second is a maintained list of Fluence n
Aqua compiler cli has to be installed, but is not needed at runtime. Aqua compiler cli has to be installed, but is not needed at runtime.
**Warning: the package requires java to be installed \(it will call "java -jar ... "\)**
```bash ```bash
npm install --save-dev @fluencelabs/aqua-cli npm install --save-dev @fluencelabs/aqua
``` ```
Also we might want to have aqua source files automatically recompiled on every save. We will take advantage of chokidar for that: Also we might want to have aqua source files automatically recompiled on every save. We will take advantage of chokidar for that:
@ -76,7 +74,7 @@ The overall project structure looks like this:
The Aqua compiler can be run with `npm`: The Aqua compiler can be run with `npm`:
```bash ```bash
npx aqua-cli -i ./aqua/ -o ./src/_aqua npx aqua -i ./aqua/ -o ./src/_aqua
``` ```
We recommend to store this logic inside a script in `packages.json` file: We recommend to store this logic inside a script in `packages.json` file:
@ -86,7 +84,7 @@ We recommend to store this logic inside a script in `packages.json` file:
... ...
"scripts": { "scripts": {
... ...
"compile-aqua": "aqua-cli -i ./aqua/ -o ./src/_aqua", // (1) "compile-aqua": "aqua -i ./aqua/ -o ./src/_aqua", // (1)
"watch-aqua": "chokidar \"**/*.aqua\" -c \"npm run compile-aqua\"" // (2) "watch-aqua": "chokidar \"**/*.aqua\" -c \"npm run compile-aqua\"" // (2)
}, },
... ...
@ -142,4 +140,3 @@ node -r ts-node/register src/index.ts
If everything has been done correctly yuo should see `Hello, world!` in the console. If everything has been done correctly yuo should see `Hello, world!` in the console.
The next secion will cover in-depth and advanced usage JS SDK The next secion will cover in-depth and advanced usage JS SDK

25
quick-start.md
View File

@ -6,10 +6,10 @@ Fluence provides a [docker-based development environment](https://github.com/flu
Fluence's devcontainer is a ready to use dockerized development environment with VSCode integration containing the following tools: Fluence's devcontainer is a ready to use dockerized development environment with VSCode integration containing the following tools:
* [`aqua-cli`](https://www.npmjs.com/package/@fluencelabs/aqua-cli) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or Typescript - [`aqua`](https://www.npmjs.com/package/@fluencelabs/aqua) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or Typescript
* [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line - [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line
* [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target - [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target
* [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug Wasm services locally - [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug Wasm services locally
### How to install ### How to install
@ -17,21 +17,21 @@ Docker and optionally VSCode need to be available on your system. For Docker ins
With Docker and VSCode in place: With Docker and VSCode in place:
* Install Remote-Containers extension in VSCode - Install Remote-Containers extension in VSCode
![Install Remote - Containers in VSCode](.gitbook/assets/image%20%2813%29.png) ![Install Remote - Containers in VSCode](.gitbook/assets/image%20%2813%29.png)
* Run Remote-Containers: Clone Repository in Container Volume... through command palette \(F1 or Cmd-Shift-P\) - Run Remote-Containers: Clone Repository in Container Volume... through command palette \(F1 or Cmd-Shift-P\)
![Select Remote Container Clone Repository](.gitbook/assets/image%20%2814%29.png) ![Select Remote Container Clone Repository](.gitbook/assets/image%20%2814%29.png)
* Enter `fluencelabs/devcontainer` - Enter `fluencelabs/devcontainer`
![Select \`fluencelabs/devcontainer\`](.gitbook/assets/image%20%2815%29.png) ![Select `fluencelabs/devcontainer`](.gitbook/assets/image%20%2815%29.png)
* When asked for branch, press enter \(main\) - When asked for branch, press enter \(main\)
* When asked for volume, press enter \(unique\) - When asked for volume, press enter \(unique\)
* open Terminal within VSCode \(ctrl-\`\) - open Terminal within VSCode \(ctrl-\`\)
![Installed And Ready Devcontainer in VSCode](.gitbook/assets/image%20%2812%29.png) ![Installed And Ready Devcontainer in VSCode](.gitbook/assets/image%20%2812%29.png)
@ -51,7 +51,4 @@ We recommend you follow the above outlined sequence of tutorial sections startin
![Start With The Aqua Tutorial in VSCode](.gitbook/assets/image%20%2820%29.png) ![Start With The Aqua Tutorial in VSCode](.gitbook/assets/image%20%2820%29.png)
If you encounter any problems or have suggestions, please open an issue or submit a PR. You can also reach out in [Discord](https://fluence.chat) or [Telegram](https://t.me/fluence_project). For more detailed reference resources, see the [Fluence documentation](https://doc.fluence.dev/docs/) and [Aqua book](https://doc.fluence.dev/aqua-book/). If you encounter any problems or have suggestions, please open an issue or submit a PR. You can also reach out in [Discord](https://fluence.chat) or [Telegram](https://t.me/fluence_project). For more detailed reference resources, see the [Fluence documentation](https://doc.fluence.dev/docs/) and [Aqua book](https://doc.fluence.dev/aqua-book/).

23
quick-start/README.md
View File

@ -12,10 +12,10 @@ For your development convenience, Fluence provides a [docker-based development e
Fluence's devcontainer is a ready to use dockerized development environment with VSCode integration containing the following tools: Fluence's devcontainer is a ready to use dockerized development environment with VSCode integration containing the following tools:
* [`aqua`](https://www.npmjs.com/package/@fluencelabs/aqua-cli) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or wrapped in Typescript - [`aqua`](https://www.npmjs.com/package/@fluencelabs/aqua) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or wrapped in Typescript
* [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line - [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line
* [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target - [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target
* [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug WebAssembly \(Wasm\) services locally - [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug WebAssembly \(Wasm\) services locally
### How to install ### How to install
@ -23,21 +23,21 @@ Docker and optionally VSCode need to be available on your system. For Docker ins
With Docker and VSCode in place: With Docker and VSCode in place:
* Install Remote-Containers extension in VSCode - Install Remote-Containers extension in VSCode
![Install Remote - Containers in VSCode](../.gitbook/assets/image%20%2813%29.png) ![Install Remote - Containers in VSCode](../.gitbook/assets/image%20%2813%29.png)
* `Run Remote-Containers: Clone Repository in Container Volume...` via the command palette \(F1 or Cmd-Shift-P\) - `Run Remote-Containers: Clone Repository in Container Volume...` via the command palette \(F1 or Cmd-Shift-P\)
![Select Remote Container Clone Repository](../.gitbook/assets/image%20%2814%29.png) ![Select Remote Container Clone Repository](../.gitbook/assets/image%20%2814%29.png)
* Enter `fluencelabs/devcontainer` - Enter `fluencelabs/devcontainer`
![Select \`fluencelabs/devcontainer\`](../.gitbook/assets/image%20%2815%29.png) ![Select `fluencelabs/devcontainer`](../.gitbook/assets/image%20%2815%29.png)
* When asked for branch, press enter \(main\) - When asked for branch, press enter \(main\)
* When asked for volume, press enter \(unique\) - When asked for volume, press enter \(unique\)
* Open Terminal in VSCode \(ctrl-\`\) - Open Terminal in VSCode \(ctrl-\`\)
![Installed And Ready Devcontainer in VSCode](../.gitbook/assets/image%20%2818%29%20%281%29.png) ![Installed And Ready Devcontainer in VSCode](../.gitbook/assets/image%20%2818%29%20%281%29.png)
@ -48,4 +48,3 @@ Congratulations, you now have a fully functional Fluence development environment
If you encounter any problems or have suggestions, please open an issue or submit a PR. You can also reach out in [Discord](https://fluence.chat) or [Telegram](https://t.me/fluence_project). For more detailed reference resources, see the [Fluence documentation](https://doc.fluence.dev/docs/) and [Aqua book](https://doc.fluence.dev/aqua-book/). If you encounter any problems or have suggestions, please open an issue or submit a PR. You can also reach out in [Discord](https://fluence.chat) or [Telegram](https://t.me/fluence_project). For more detailed reference resources, see the [Fluence documentation](https://doc.fluence.dev/docs/) and [Aqua book](https://doc.fluence.dev/aqua-book/).
All right, now we are ready to proceed to the first application on Fluence. All right, now we are ready to proceed to the first application on Fluence.

11
tutorials_tutorials/building-a-frontend-with-js-sdk.md
View File

@ -110,7 +110,7 @@ $
**Note**: typically you should have a single instance`FluenceClient` per application since it represents it's identity in the network. You are free to store the instance anywhere you like. **Note**: typically you should have a single instance`FluenceClient` per application since it represents it's identity in the network. You are free to store the instance anywhere you like.
#### 3. Setting Up The Aqua Compiler #### 3. Setting Up The Aqua Compiler
Aqua is the proffered language for the Fluence network. It can be used with javascript-based environments via npm package. Aqua is the proffered language for the Fluence network. It can be used with javascript-based environments via npm package.
@ -119,7 +119,7 @@ Aqua is the proffered language for the Fluence network. It can be used with java
{% endhint %} {% endhint %}
```bash ```bash
npm install --save-dev @fluencelabs/aqua-cli npm install --save-dev @fluencelabs/aqua
``` ```
We will also need the standard library for the language We will also need the standard library for the language
@ -163,7 +163,7 @@ The aqua code can now be compiled by using the compiler CLI. We suggest adding a
... ...
"scripts": { "scripts": {
"exec": "node -r ts-node/register src/index.ts", "exec": "node -r ts-node/register src/index.ts",
"compile-aqua": "aqua-cli -i ./aqua/ -o ./src/compiled" "compile-aqua": "aqua -i ./aqua/ -o ./src/compiled"
}, },
... ...
``` ```
@ -237,6 +237,5 @@ Fluence JS SDK gives options to register own handlers for aqua vm service calls
### References ### References
* For the list of compiler options see: [https://github.com/fluencelabs/aqua](https://github.com/fluencelabs/aqua) - For the list of compiler options see: [https://github.com/fluencelabs/aqua](https://github.com/fluencelabs/aqua)
* Repository with additional examples: [**https://github.com/fluencelabs/aqua-playground**](https://github.com/fluencelabs/aqua-playground)\*\*\*\* - Repository with additional examples: [**https://github.com/fluencelabs/aqua-playground**](https://github.com/fluencelabs/aqua-playground)\*\*\*\*