mirror of
https://github.com/fluencelabs/gitbook-docs
synced 2024-12-04 23:30:23 +00:00
GitBook: [2.0.0] 23 pages modified
This commit is contained in:
boneyard93501
gitbook-bot
parent
d5847ed716
commit
68d1d8a3fd
18
SUMMARY.md
18
SUMMARY.md
@ -5,9 +5,7 @@
|
||||
* [Concepts](concepts.md)
|
||||
* [Quick Start](quick-start.md)
|
||||
* [Aquamarine](knowledge_aquamarine/README.md)
|
||||
* [Aqua](knowledge_aquamarine/hll/README.md)
|
||||
* [Aqua VM](knowledge_aquamarine/hll/vm.md)
|
||||
* [AIR](knowledge_aquamarine/hll/knowledge_aquamarine_air.md)
|
||||
* [Aqua](knowledge_aquamarine/hll.md)
|
||||
* [Marine](knowledge_aquamarine/marine/README.md)
|
||||
* [Marine CLI](knowledge_aquamarine/marine/marine-cli.md)
|
||||
* [Marine Repl](knowledge_aquamarine/marine/marine-repl.md)
|
||||
@ -17,21 +15,11 @@
|
||||
* [Security](knowledge_security.md)
|
||||
* [Tutorials](tutorials_tutorials/README.md)
|
||||
* [Deploy A Local Fluence Node](tutorials_tutorials/tutorial_run_local_node.md)
|
||||
* [Deploy A Private Fluence Network](tutorials_tutorials/running-a-fluence-network.md)
|
||||
* [Add Your Own Builtins](tutorials_tutorials/add-your-own-builtin.md)
|
||||
* [TrustGraph In Action](tutorials_tutorials/tutorial_trustgraph.md)
|
||||
* [Securing Services](tutorials_tutorials/securing-services.md)
|
||||
* [Developing a Frontend Application with JS-SDK](tutorials_tutorials/developing-a-frontend-application-with-js-sdk.md)
|
||||
* [Building a Chat Appplication](tutorials_tutorials/building-a-chat-appplication.md)
|
||||
* [Building a Collaborative Editor](tutorials_tutorials/building-a-collaborative-editor.md)
|
||||
* [Building a Frontend with JS-SDK](tutorials_tutorials/building-a-frontend-with-js-sdk.md)
|
||||
* [Recipes](recipes_recipes/README.md)
|
||||
* [Untitled](recipes_recipes/untitled.md)
|
||||
* [Setting Up Your Environment](recipes_recipes/recipes_setting_up.md)
|
||||
* [cUrl as a Service](recipes_recipes/recipes_curl.md)
|
||||
* [Error Management and Testing Of Services](recipes_recipes/error-management-and-testing-of-services.md)
|
||||
* [Sqlite](recipes_recipes/sqlite.md)
|
||||
* [Redis](recipes_recipes/redis.md)
|
||||
* [Local Filesystem](recipes_recipes/local-filesystem.md)
|
||||
* [IPFS](recipes_recipes/ipfs.md)
|
||||
* [Data Replication](recipes_recipes/data-replication.md)
|
||||
* [Research, Papers And References](research-papers-and-references.md)
|
||||
|
||||
|
||||
6
knowledge_aquamarine/hll.md
Normal file
6
knowledge_aquamarine/hll.md
Normal file
@ -0,0 +1,6 @@
|
||||
# Aqua
|
||||
|
||||
At the core of Fluence is the open-source language **Aqua** that allows for the programming of peer-to-peer scenarios separately from the computations on peers.
|
||||
|
||||
Please see the[ Aqua book ](https://doc.fluence.dev/aqua-book/)for an introduction to the language and reference materials.
|
||||
|
||||
@ -301,7 +301,7 @@ Please not that if you want to use `curl_request` with testing, see below, the c
|
||||
let response = unsafe { curl(curl_cmd) };
|
||||
```
|
||||
|
||||
since cargo does not have access to the magic in place in the marine rs sdk to handle unsafe.
|
||||
since cargo does not access to the marine macro to handle unsafe.
|
||||
|
||||
MountedBinaryResult itself is a Marine-compatible struct containing a binary's return process code, error string and stdout and stderr as byte arrays:
|
||||
|
||||
@ -326,8 +326,6 @@ pub struct MountedBinaryResult {
|
||||
|
||||
MountedBinaryResult then can be used on a variety of match or conditional tests.
|
||||
|
||||
|
||||
|
||||
#### Testing
|
||||
|
||||
Since we are compiling to a wasm32-wasi target with `ftype` constrains, the basic `cargo test` is not all that useful or even usable for our purposes. To alleviate that limitation, Fluence has introduced the [`[marine-test]` macro ](https://github.com/fluencelabs/marine-rs-sdk/tree/master/crates/marine-test-macro)that does a lot of the heavy lifting to allow developers to use `cargo test` as intended. That is, `[marine-test]` macro generates the necessary code to call Marine, one instance per test function, based on the Wasm module and associated configuration file so that the actual test function is run against the Wasm module not the native code.
|
||||
@ -445,8 +443,6 @@ Here, an array called `TARGET_MAP` is defined and provided to a logger in the `m
|
||||
REPL also uses the log crate to print logs from Wasm modules. Log messages will be printed if`RUST_LOG` environment variable is specified.
|
||||
{% endhint %}
|
||||
|
||||
|
||||
|
||||
#### Debug
|
||||
|
||||
The application of the second feature is limited to obtaining some of the internal details of the IT execution. Normally, this feature should not be used by a backend developer. Here you can see example of such details for the greeting service compiled with the `debug` feature:
|
||||
@ -474,8 +470,6 @@ result: String("Hi, user")
|
||||
|
||||
The most important information these logs relates to the `allocate`/`deallocate` function calls. The `sdk.allocate: 4` line corresponds to passing the 4-byte `user` string to the Wasm module, with the memory allocated inside the module and the string is copied there. Whereas `sdk.deallocate: 0x110080 8` refers to passing the 8-byte resulting string `Hi, user` to the host side. Since all arguments and results are passed by value, `deallocate` is called to delete unnecessary memory inside the Wasm module.
|
||||
|
||||
|
||||
|
||||
#### Module Manifest
|
||||
|
||||
The `module_manifest!` macro embeds the Interface Type \(IT\), SDK and Rust project version as well as additional project and build information into Wasm module. For the macro to be usable, it needs to be imported and initialized in the _main.rs_ file:
|
||||
|
||||
2
recipes_recipes/untitled.md
Normal file
2
recipes_recipes/untitled.md
Normal file
@ -0,0 +1,2 @@
|
||||
# Untitled
|
||||
|
||||
242
tutorials_tutorials/building-a-frontend-with-js-sdk.md
Normal file
242
tutorials_tutorials/building-a-frontend-with-js-sdk.md
Normal file
@ -0,0 +1,242 @@
|
||||
# Building a Frontend with JS-SDK
|
||||
|
||||
Fluence provides means to connect to the network from a javascript environment. It is currently tested to work in nodejs and modern browsers.
|
||||
|
||||
To create an application you will need two main building blocks: the JS SDK itself and the aqua compiler. Both of them are provided in a form npm packages. JS SDK wraps the air interpreter and provides a connection to the network. There is low-level api for executing air scripts and registering for service calls handlers. Aqua compiler allows to write code in aqua language and compile it into typescript code which can be directly used with the SDK.
|
||||
|
||||
Even though all the logic could be programmed by hand with raw air it is strongly recommended to use aqua.
|
||||
|
||||
### Basic usage
|
||||
|
||||
As previously said you can use Fluence with any frontend or nodejs framework. JS SDK could be as any other npm library. For the purpose of the demo we will init a bare-bones nodejs package and show you the steps needed install JS SDK and aqua compiler. Feel free to use the tool most suitable for the framework used in application, the installation process should be roughly the same
|
||||
|
||||
#### 1. Start with 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 The Aqua Compiler
|
||||
|
||||
Aqua is the proffered language for the Fluence network. It can be used with javascript-based environments via npm package.
|
||||
|
||||
{% hint style="warning" %}
|
||||
**The package requires java to be installed as it calls "java -jar ... "**
|
||||
{% endhint %}
|
||||
|
||||
```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)\*\*\*\*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user