From 7ac39321b6dfedd292897a715bbaae6dfa75e08d Mon Sep 17 00:00:00 2001 From: boneyard93501 Date: Mon, 5 Jul 2021 01:21:41 +0000 Subject: [PATCH] GitBook: [2.0.0] 21 pages modified --- SUMMARY.md | 9 +- node.md | 13 +++ tutorials_tutorials/add-your-own-builtin.md | 2 +- tutorials_tutorials/curl-as-a-service.md | 105 ++++++++++++++++++++ tutorials_tutorials/recipes_setting_up.md | 51 ++++++++++ 5 files changed, 173 insertions(+), 7 deletions(-) create mode 100644 node.md create mode 100644 tutorials_tutorials/curl-as-a-service.md create mode 100644 tutorials_tutorials/recipes_setting_up.md diff --git a/SUMMARY.md b/SUMMARY.md index e208211..ce85194 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -11,16 +11,13 @@ * [Marine Repl](knowledge_aquamarine/marine/marine-repl.md) * [Marine Rust SDK](knowledge_aquamarine/marine/marine-rs-sdk.md) * [Tools](knowledge_tools.md) -* [Node](node/README.md) - * [Builtin Services](node/knowledge_node_services.md) +* [Node](node.md) * [Security](knowledge_security.md) * [Tutorials](tutorials_tutorials/README.md) + * [Setting Up Your Environment](tutorials_tutorials/recipes_setting_up.md) * [Deploy A Local Fluence Node](tutorials_tutorials/tutorial_run_local_node.md) + * [cUrl As A Service](tutorials_tutorials/curl-as-a-service.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) -* [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) * [Research, Papers And References](research-papers-and-references.md) diff --git a/node.md b/node.md new file mode 100644 index 0000000..c8440fc --- /dev/null +++ b/node.md @@ -0,0 +1,13 @@ +# Node + +The Fluence protocol is implemented as the Fluence [reference node](https://github.com/fluencelabs/fluence) which includes the + +* Peer-to-peer communication layer +* Marine interpreter +* Aqua VM +* Builtin services + +and more. + +Builtin services are available on every Fluence peer and can be programmatically accessed and composed using Aqua. For a complete list of builtin services see the builtin.aqua file in the [Aqua Lib](https://github.com/fluencelabs/aqua-lib) repo. How to create your own builtin service, see the [Add Your Own Builtins](tutorials_tutorials/add-your-own-builtin.md) tutorial. + diff --git a/tutorials_tutorials/add-your-own-builtin.md b/tutorials_tutorials/add-your-own-builtin.md index d48c1dc..3d72786 100644 --- a/tutorials_tutorials/add-your-own-builtin.md +++ b/tutorials_tutorials/add-your-own-builtin.md @@ -1,6 +1,6 @@ # Add Your Own Builtins -As discussed in the [Node](../node/knowledge_node_services.md) section, some service functionalities have ubiquitous demand making them suitable candidates to be directly deployed to a peer node. The [Aqua distributed hash table](https://github.com/fluencelabs/fluence/tree/master/deploy/builtins/aqua-dht) \(DHT\) is an example of builtin service. The remainder of this tutorial guides you through the steps necessary to create and deploy a Builtin service. +As discussed in the [Node]() section, some service functionalities have ubiquitous demand making them suitable candidates to be directly deployed to a peer node. The [Aqua distributed hash table](https://github.com/fluencelabs/fluence/tree/master/deploy/builtins/aqua-dht) \(DHT\) is an example of builtin service. The remainder of this tutorial guides you through the steps necessary to create and deploy a Builtin service. In order to have a service available out-of-the-box with the necessary startup and scheduling scripts, we can take advantage of the Fluence [deployer feature](https://github.com/fluencelabs/fluence/tree/master/deploy) for Node native services. This feature handles the complete deployment process including diff --git a/tutorials_tutorials/curl-as-a-service.md b/tutorials_tutorials/curl-as-a-service.md new file mode 100644 index 0000000..2042557 --- /dev/null +++ b/tutorials_tutorials/curl-as-a-service.md @@ -0,0 +1,105 @@ +# cUrl As A Service + +### Overview + +[Curl](https://curl.se/) is a widely available and used command-line tool to receive or send data using URL syntax. Chances are, you probably just used it when you set up your Fluence development environment. For Fluence services to be able to interact with the world, cUrl is one option to facilitate https calls. Since Fluence modules are Wasm IT modules, cUrl cannot not be a service intrinsic. Instead, the curl command-line tool needs to be made available and accessible at the node level. And for Fluence services to be able to interact with Curl, we need to code a cUrl adapter taking care of the mounted \(cUrl\) binary. + +### Adapter Construction + +The work for the cUrl adapter has been fundamentally done and is exposed by the Fluence Rust SDK. As a developer, the task remaining is to instantiate the adapter in the context of the module and services scope. The following code [snippet](https://github.com/fluencelabs/fce/tree/master/examples/url-downloader/curl_adapter) illustrates the implementation requirement. + +```rust +use fluence::fce; + +use fluence::WasmLoggerBuilder; +use fluence::MountedBinaryResult; + +pub fn main() { + WasmLoggerBuilder::new().build().unwrap(); +} + +#[fce] +pub fn download(url: String) -> String { + log::info!("get called with url {}", url); + + let result = unsafe { curl(vec![url]) }; + String::from_utf8(result.stdout).unwrap() +} + +#[fce] +#[link(wasm_import_module = "host")] +extern "C" { + fn curl(cmd: Vec) -> MountedBinaryResult; +} +``` + +with the following dependencies necessary in the Cargo.toml: + +```rust +fluence = { version = "=0.4.2", features = ["logger"] } +log = "0.4.8" +``` + +We are basically linking the [external](https://doc.rust-lang.org/std/keyword.extern.html) cUrl binary and are exposing access to it as a FCE interface called download. + +### Code References + +* [Mounted binaries](https://github.com/fluencelabs/fce/blob/c559f3f2266b924398c203a45863ebf2fb9252ec/fluence-faas/src/host_imports/mounted_binaries.rs) +* [cUrl](https://github.com/curl/curl) + +### Service Construction + +In order to create a valid Fluence service, a service configuration is required. + +```text +modules_dir = "target/wasm32-wasi/release" + +[[module]] + name = "curl_adapter" + logger_enabled = true + + [mounted.mounted_binaries] + curl = "/usr/bin/curl" +``` + +We are specifying the location of the Wsasm file, the import name of the Wasm file, some logging housekeeping, and the mounted binary reference with the command-line call information. + +### Remote Service Creation + +```bash +cargo new curl-service +cd curl-service +# copy the above rust code into src/main +# copy the specified dependencies into Cargo.toml +# copy the above service configuration into Config.toml + +fce build --release +``` + +You should have the Fluence module curl\_adapter.wasm in `target/wasm32-wasi/release` we can test our service with `fce-repl`. + +### Service `Test` + +Running the REPL, we use the `interface` command to list all available interfaces and the `call` command to run a method. Fr our purposes, we furnish the [https://duckduckgo.com/?q=Fluence+Labs](https://duckduckgo.com/?q=Fluence+Labs) url to give the the curl adapter a workout. + +```bash +fce-repl Config.toml +Welcome to the FCE REPL (version 0.5.2) +app service was created with service id = 8ad81c3a-8c5c-4730-80d1-c54cd177725d +elapsed time 40.312376ms + +1> interface +Loaded modules interface: + +curl_adapter: + fn download(url: String) -> String + +2> call curl_adapter download ["https://duckduckgo.com/?q=Fluence+Labs"] +result: String("Fluence Labs at DuckDuckGo +ript\">DDG.index = DDG.index || {}; DDG.index.signalSummary = \"\";") + elapsed time: 334.545388ms + +3> +``` + diff --git a/tutorials_tutorials/recipes_setting_up.md b/tutorials_tutorials/recipes_setting_up.md new file mode 100644 index 0000000..4b47aac --- /dev/null +++ b/tutorials_tutorials/recipes_setting_up.md @@ -0,0 +1,51 @@ +# Setting Up Your Environment + +In order to develop within the Fluence solution, [Rust](https://www.rust-lang.org/tools/install) and small number of tools are required. + +## Rust + +Install Rust: + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +once Rust is installed, we need to expand the toolchain and include [nightly build](https://rust-lang.github.io/rustup/concepts/channels.html) and the [Wasm](https://doc.rust-lang.org/stable/nightly-rustc/rustc_target/spec/wasm32_wasi/index.html) compile target. + +```bash +rustup install nightly +rustup target add wasm32-wasi +``` + +To keep Rust and the toolchains updated: + +```bash +rustup self update +rustup update +``` + +There are a number of good Rust installation and IDE integration tutorials available. [DuckDuckGo](https://duckduckgo.com/) is your friend but if that's too much effort, have a look at [koderhq](https://www.koderhq.com/tutorial/rust/environment-setup/). + +## Fluence Tools + +Fluence provides several tools to support developers. Fluence cli, `flcli`, facilitates the compilation of modules to the necessary wasm32-wasi target. Fluence REPL, `fce-repl`, on the other hand, is a cli tool to test and experiment with FCE modules and services locally. + +```bash +cargo install fcli +cargo +nightly install frepl +``` + +In addition, Fluence provides the [proto-distributor](https://github.com/fluencelabs/proto-distributor) tool, aka `fldist`, for service lifecyle management. From deploying services to the network to executing AIR scripts, `fldist` does it all. + +```bash +npm install -g @fluencelabs/fldist +``` + +## Fluence SDK + +For frontend development, the Fluence [JS-SDK](https://github.com/fluencelabs/fluence-js) is currently the favored, and only, tool. + +```bash +npm install @fluencelabs/fluence +``` +