From 3d93e61cb389545e197ae05388a8f9670cbcac12 Mon Sep 17 00:00:00 2001 From: boneyard93501 Date: Fri, 11 Jun 2021 22:18:02 +0000 Subject: [PATCH] GitBook: [marine] 56 pages and 30 assets modified --- ...old_4 (1) (2) (2) (3) (3) (3) (3) (1).png} | Bin ...old_4 (1) (2) (2) (3) (3) (3) (3) (2).png} | Bin ...old_4 (1) (2) (2) (3) (3) (3) (3) (3).png} | Bin ...ir_fold_4 (1) (2) (2) (3) (3) (3) (3).png} | Bin ...ull_6 (1) (2) (2) (3) (3) (3) (3) (1).png} | Bin ...ull_6 (1) (2) (2) (3) (3) (3) (3) (2).png} | Bin ...ull_6 (1) (2) (2) (3) (3) (3) (3) (3).png} | Bin ...ir_null_6 (1) (2) (2) (3) (3) (3) (3).png} | Bin ...2 (1) (1) (1) (1) (1) (2) (3) (4) (1).png} | Bin ...2 (1) (1) (1) (1) (1) (2) (3) (4) (2).png} | Bin ...2 (1) (1) (1) (1) (1) (2) (3) (4) (3).png} | Bin ...2 (1) (1) (1) (1) (1) (2) (3) (4) (4).png} | Bin ...ial_2 (1) (1) (1) (1) (1) (2) (3) (4).png} | Bin .../{image (5).png => image (6) (1) (1).png} | Bin .../{image (6).png => image (6) (1).png} | Bin README.md | 2 +- SUMMARY.md | 12 +- .../knowledge_aquamarine/hll/README.md | 6 + .../hll/knowledge_aquamarine_air.md | 55 ++ .../knowledge_aquamarine/hll/vm.md | 2 + .../knowledge_aquamarine/marine/README.md | 16 + .../knowledge_aquamarine/marine/marine-cli.md | 31 + .../marine/marine-repl.md | 35 ++ .../marine/marine-rs-sdk.md | 541 ++++++++++++++++++ knowledge_knowledge/knowledge_concepts.md | 2 +- knowledge_knowledge/knowledge_tools.md | 21 +- ...k_start_building_from_multiple_services.md | 2 +- quick_start/quick_start_setup.md | 8 +- 28 files changed, 715 insertions(+), 18 deletions(-) rename .gitbook/assets/{air_fold_4 (1) (2) (2) (3) (3) (1).png => air_fold_4 (1) (2) (2) (3) (3) (3) (3) (1).png} (100%) rename .gitbook/assets/{air_fold_4 (1) (2) (2) (3) (3) (2).png => air_fold_4 (1) (2) (2) (3) (3) (3) (3) (2).png} (100%) rename .gitbook/assets/{air_fold_4 (1) (2) (2) (3) (3) (3).png => air_fold_4 (1) (2) (2) (3) (3) (3) (3) (3).png} (100%) rename .gitbook/assets/{air_fold_4 (1) (2) (2) (3) (3).png => air_fold_4 (1) (2) (2) (3) (3) (3) (3).png} (100%) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3) (1).png => air_null_6 (1) (2) (2) (3) (3) (3) (3) (1).png} (100%) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3) (2).png => air_null_6 (1) (2) (2) (3) (3) (3) (3) (2).png} (100%) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3) (3).png => air_null_6 (1) (2) (2) (3) (3) (3) (3) (3).png} (100%) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3).png => air_null_6 (1) (2) (2) (3) (3) (3) (3).png} (100%) rename .gitbook/assets/{air_sequential_2 (1) (1) (1) (1) (1) (2) (1).png => air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (1).png} (100%) rename .gitbook/assets/{air_sequential_2 (1) (1) (1) (1) (1) (2) (2).png => air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (2).png} (100%) rename .gitbook/assets/{air_sequential_2 (1) (1) (1) (1) (1) (2) (3).png => air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (3).png} (100%) rename .gitbook/assets/{air_sequential_2 (1) (1) (1) (1) (1) (2).png => air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (4).png} (100%) rename .gitbook/assets/{air_sequential_2 (1) (1) (1) (1).png => air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4).png} (100%) rename .gitbook/assets/{image (5).png => image (6) (1) (1).png} (100%) rename .gitbook/assets/{image (6).png => image (6) (1).png} (100%) create mode 100644 knowledge_knowledge/knowledge_aquamarine/hll/README.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/hll/vm.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/marine/README.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md diff --git a/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (1).png b/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3) (1).png similarity index 100% rename from .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (1).png rename to .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3) (1).png diff --git a/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (2).png b/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3) (2).png similarity index 100% rename from .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (2).png rename to .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3) (2).png diff --git a/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3).png b/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3) (3).png similarity index 100% rename from .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3).png rename to .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3) (3).png diff --git a/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3).png b/.gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3).png similarity index 100% rename from .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3).png rename to .gitbook/assets/air_fold_4 (1) (2) (2) (3) (3) (3) (3).png diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (1).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (1).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (1).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (1).png diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (2).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (2).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (2).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (2).png diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3).png diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3).png diff --git a/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (1).png b/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (1).png similarity index 100% rename from .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (1).png rename to .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (1).png diff --git a/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (2).png b/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (2).png similarity index 100% rename from .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (2).png rename to .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (2).png diff --git a/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3).png b/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (3).png similarity index 100% rename from .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3).png rename to .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (3).png diff --git a/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2).png b/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (4).png similarity index 100% rename from .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2).png rename to .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4) (4).png diff --git a/.gitbook/assets/air_sequential_2 (1) (1) (1) (1).png b/.gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4).png similarity index 100% rename from .gitbook/assets/air_sequential_2 (1) (1) (1) (1).png rename to .gitbook/assets/air_sequential_2 (1) (1) (1) (1) (1) (2) (3) (4).png diff --git a/.gitbook/assets/image (5).png b/.gitbook/assets/image (6) (1) (1).png similarity index 100% rename from .gitbook/assets/image (5).png rename to .gitbook/assets/image (6) (1) (1).png diff --git a/.gitbook/assets/image (6).png b/.gitbook/assets/image (6) (1).png similarity index 100% rename from .gitbook/assets/image (6).png rename to .gitbook/assets/image (6) (1).png diff --git a/README.md b/README.md index 1fafee5..03eb3ef 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Fluence Labs builds distributed networks, development tools, components and support systems to allow developers to efficiently and reliably build, operate, maintain, and monetize distributed and decentralized services and applications. An integral component of the Fluence solution is [Aquamarine](https://github.com/fluencelabs/aquamarine), a programming language enabling peer-to-peer coordination for distributed applications and backends. -Fluence is also developing the [Fluence Compute Engine](https://github.com/fluencelabs/fce) \(FCE\) -- a general purpose runtime for multi-module WebAssembly applications with WASI support and a [shared-nothing](https://en.wikipedia.org/wiki/Shared-nothing_architecture) linking scheme. FCE allows for the rapid development and deployment of portable Wasm services which can be composed and coordinated with Aquamarine into secure applications. Furthermore, Fluence has implemented innovations at the p2p [node](https://github.com/fluencelabs/fluence) level, such as [TrustGraph](https://github.com/fluencelabs/trust-graph), local development and testing tools, such as [FCE-Repl](https://github.com/fluencelabs/fce/tree/master/tools/repl), and support tooling, such as [Fluence Distributor](https://github.com/fluencelabs/proto-distributor). +Fluence is also developing [Marine](https://github.com/fluencelabs/marine) - a general purpose compute runtime for multi-module WebAssembly applications with WASI support and a [shared-nothing](https://en.wikipedia.org/wiki/Shared-nothing_architecture) linking scheme. FCE allows for the rapid development and deployment of portable Wasm services which can be composed and coordinated with Aquamarine into secure applications. Furthermore, Fluence has implemented innovations at the p2p [node](https://github.com/fluencelabs/fluence) level, such as [TrustGraph](https://github.com/fluencelabs/trust-graph), local development and testing tools, such as [Marine-Repl](https://github.com/fluencelabs/marine/tree/master/tools/repl), and support tooling, such as [Fluence Distributor](https://github.com/fluencelabs/proto-distributor). In combination, Aquamarine and the Fluence runtimes and tools allow developers to avoid the typical peer-to-peer development challenges and accelerate the development and deployment of distributed services and applications. diff --git a/SUMMARY.md b/SUMMARY.md index dc5a469..5d6e7c9 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -19,16 +19,18 @@ * [Blocks To Database](development_development/development_reward_block_app/development_persisting_blocks.md) * [Additional Concepts](development_development/development_reward_block_app/development_additional_concepts.md) * [Summary](development_development/summary.md) -* [Building A Frontend with JS SDK](building-a-frontend-with-js-sdk.md) * [Knowledgebase](knowledge_knowledge/README.md) * [Overview](knowledge_knowledge/knowledge_overview.md) * [Concepts](knowledge_knowledge/knowledge_concepts.md) * [Tools](knowledge_knowledge/knowledge_tools.md) * [Aquamarine](knowledge_knowledge/knowledge_aquamarine/README.md) - * [AIR](knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md) - * [HLL](knowledge_knowledge/knowledge_aquamarine/hll.md) - * [VM](knowledge_knowledge/knowledge_aquamarine/vm.md) - * [Fluence Compute Engine](knowledge_knowledge/fluence-compute-engine.md) + * [Aqua](knowledge_knowledge/knowledge_aquamarine/hll/README.md) + * [Aqua VM](knowledge_knowledge/knowledge_aquamarine/hll/vm.md) + * [AIR](knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md) + * [Marine](knowledge_knowledge/knowledge_aquamarine/marine/README.md) + * [Marine CLI](knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md) + * [Marine Repl](knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md) + * [Marine Rust SDK](knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md) * [Node](knowledge_knowledge/node/README.md) * [Overview](knowledge_knowledge/node/overview.md) * [Services](knowledge_knowledge/node/knowledge_node_services.md) diff --git a/knowledge_knowledge/knowledge_aquamarine/hll/README.md b/knowledge_knowledge/knowledge_aquamarine/hll/README.md new file mode 100644 index 0000000..630f2b9 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/hll/README.md @@ -0,0 +1,6 @@ +# Aqua + +## Aquamarine High Level Language + +_**Stay Tuned -- Coming Soon To A Repo Near You**_ + diff --git a/knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md b/knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md new file mode 100644 index 0000000..24d8bb8 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md @@ -0,0 +1,55 @@ +# AIR + +The Aquamarine Intermediate Representation \(AIR\) is a low level language to program both distributed networks and the services deployed on them. The language is comprised of a small number of instructions: + +* _**call**_: : execution +* _**seq**_ : sequential +* _**par** :_ parallel +* _**fold**_ : iteration +* _**xor** :_ branching & error handling +* _**null**_ : empty instruction + +which operate on _peer-id_ \(location\), _service-id_, and _service method_ over an argument list, see Figure 1. + +**Figure 1: AIR Instruction Definition** ![Execution](../../../.gitbook/assets/air_call_execution_1.png) + +## Instructions + +AIR instructions are intended to launch the execution of a service method as follows: + +1. The method is executed on the peer specified by the peer id \(location\) parameter +2. The peer is expected to have the Wasm service specified by the service id parameter +3. The service must have a callable method specified be the method parameter +4. The arguments specified by the argument list are passed to the method +5. The result of the method returned under the name output name + +**Figure 2: Sequential Instruction** ![Execution](../../../.gitbook/assets/air_sequential_2%20%281%29%20%281%29%20%281%29%20%281%29%20%281%29%20%282%29%20%283%29%20%284%29%20%282%29.png) + +The _**seq**_ instruction takes two instructions at most as its arguments and executes them sequentially, one after the other. + +**Figure 3: Parallel Instruction** ![Execution](../../../.gitbook/assets/air_par_3.png) + +The _**par**_ instruction takes two instructions at most as its arguments and particles may execute on parallel paths iff each service referenced is hosted on a different node otherwise particles execute sequentially + +TODO: add better graphic showing the disticntion of branching vs seq. + +**Figure 4: Fold Instruction** ![Execution](https://github.com/fluencelabs/gitbook-docs/tree/84e814d02d9299034c9c031adf7f081bb59898b9/.gitbook/assets/air_fold_4%20%281%29%20%282%29%20%281%29.png) + +The _**fold**_ instruction iterates over the elements of an array and workds as follows: + +* _**fold**_ instruction takes three arguments: an array, a variable and an instruction +* At each iteration, the variable is assigned an element of the array and the argument-instruction is executed +* The argument-instruction can access the variable and uses the next statement to trigger the next iteration + +Figure 5: Branching Instruction ![Execution](../../../.gitbook/assets/air_xor_5.png) + +This instruction is intended for organizing branches in the flow of execution as well as for handling errors: + +* The _**XOR**_ instruction takes two instructions as its arguments +* The first instruction is executed and if the execution is successful, then the second instruction is ignored +* If the first instruction fails, then the second one is executed. + +**Figure 6: Null Instruction** ![Execution](https://github.com/fluencelabs/gitbook-docs/tree/84e814d02d9299034c9c031adf7f081bb59898b9/.gitbook/assets/air_null_6%20%281%29%20%282%29.png) + +This is an empty instruction: it takes no arguments and does nothing. The _**null**_ instruction is useful for generating code. + diff --git a/knowledge_knowledge/knowledge_aquamarine/hll/vm.md b/knowledge_knowledge/knowledge_aquamarine/hll/vm.md new file mode 100644 index 0000000..ec6c770 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/hll/vm.md @@ -0,0 +1,2 @@ +# Aqua VM + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/README.md b/knowledge_knowledge/knowledge_aquamarine/marine/README.md new file mode 100644 index 0000000..68bc56a --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/marine/README.md @@ -0,0 +1,16 @@ +# Marine + +[Marine](https://github.com/fluencelabs/marine) is a general purpose WebAssembly runtime favoring Wasm modules based on the [ECS](https://en.wikipedia.org/wiki/Entity_component_system) pattern or plugin architecture and uses Wasm [Interface Types](https://github.com/WebAssembly/interface-types/blob/master/proposals/interface-types/Explainer.mdhttps://github.com/WebAssembly/interface-types/blob/master/proposals/interface-types/Explainer.md) \( IT\) to implement a [shared-nothing](https://en.wikipedia.org/wiki/Shared-nothing_architecture) linking scheme. Fluence [nodes](https://github.com/fluencelabs/fluence) use Marine to host the Aqua VM and execute hosted Wasm services. + +Todo: we could really do with diagram + +The [Marine Rust SDK](https://github.com/fluencelabs/marine-rs-sdk) allows to hide the IT implementation details behind a handy procedural macro `[marine]` and provides the scaffolding for unit tests. + + + + + + + + + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md new file mode 100644 index 0000000..3b4e3c8 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md @@ -0,0 +1,31 @@ +# Marine CLI + +The [Marine command line tool](https://github.com/fluencelabs/marine) + +```rust +mbp16~(:|✔) % marine --help +Fluence Marine command line tool 0.6.7 +Fluence Labs + +USAGE: + marine [SUBCOMMAND] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +SUBCOMMANDS: + aqua Shows data types of provided module in a format suitable for Aqua + build Builds provided Rust project to Wasm + help Prints this message or the help of the given subcommand(s) + info Shows manifest and sdk version of the provided Wasm file + it Shows IT of the provided Wasm file + repl Starts Fluence application service REPL + set Sets interface types and version to the provided Wasm file +mbp16~(:|✔) % +``` + + + + + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md new file mode 100644 index 0000000..ec53e09 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md @@ -0,0 +1,35 @@ +# Marine Repl + +[`mrepl`](https://crates.io/crates/mrepl) is a command line tool \(CLI\) to locally run a Marine instance to inspect, run, and test module and service configurations. + +```text +mbp16~(:|✔) % mrepl +Welcome to the Marine REPL (version 0.7.2) +Minimal supported versions + sdk: 0.6.0 + interface-types: 0.20.0 + +New version is available! 0.7.2 -> 0.7.4 +To update run: cargo +nightly install mrepl --force + +app service was created with service id = d81a4de5-55c3-4cb7-935c-3d5c6851320d +elapsed time 486.234µs + +1> help +Commands: + +n/new [config_path] create a new service (current will be removed) +l/load load a new Wasm module +u/unload unload a Wasm module +c/call [args] call function with given name from given module +i/interface print public interface of all loaded modules +e/envs print environment variables of a module +f/fs print filesystem state of a module +h/help print this message +q/quit/Ctrl-C exit + +2> +``` + + + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md new file mode 100644 index 0000000..edc193d --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md @@ -0,0 +1,541 @@ +# Marine Rust SDK + +The [marine-rs-sdk](https://github.com/fluencelabs/marine-rs-sdk) empowers developers to write services suitable for peer hosting in peer-to-peer networks using the Marine Virtual Machine by enabling the wasm32-wasi compile target for Marine. For an introduction to writing services with the marine-rs-sdk, see the [Developing Modules And Services](../../../development_development/) section. + +### API + +The procedural macros `[marine]` and `[marine_test]` are the two primary features provided by the SDK. The `[marine]` macro can be applied to a function, external block or structure. The `[marine_test]` macro, on the other hand, allows the use of the familiar `cargo test` to execute tests over the actual Wasm module generated from the service code. + +#### Function Export + +Applying the `[marine]` macro to a function results in its export, which means that it can be called from other modules or AIR scripts. For the function to be compatible with this macro, its arguments must be of the `ftype`, which is defined as follows: + +`ftype` = `bool`, `u8`, `u16`, `u32`, `u64`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`, `String` +`ftype` = `ftype` \| `Vec`<`ftype`> +`ftype` = `ftype` \| `Record`<`ftype`> + +In other words, the arguments must be one of the types listed below: + +* one of the following Rust basic types: `bool`, `u8`, `u16`, `u32`, `u64`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`, `String` +* a vector of elements of the above types +* a vector composed of vectors of the above type, where recursion is acceptable, e.g. the type `Vec>>` is permissible +* a record, where all fields are of the basic Rust types +* a record, where all fields are of any above types or other records + +The return type of a function must follow the same rules, but currently only one return type is possible. + +See the example below of an exposed function with a complex type signature and return value: + +```rust +// export TestRecord as a public data structure bound by +// the IT type constraints +#[marine] +pub struct TestRecord { + pub field_0: i32, + pub field_1: Vec>, +} + +// export foo as a public function bound by the +// IT type contraints +#[marine] # +pub fn foo(arg_1: Vec>>>, arg_2: String) -> Vec>>> { + unimplemented!() +} +``` + + + +{% hint style="info" %} +Function Export Requirements + +* wrap a target function with the `[marine]` macro +* function arguments must by of `ftype` +* the function return type also must be of `ftype` +{% endhint %} + +#### Function Import + +The `[marine]` macro can also wrap an [`extern` block](https://doc.rust-lang.org/std/keyword.extern.html). In this case, all functions declared in it are considered imported functions. If there are imported functions in some module, say, module A, then: + +* There should be another module, module B, that exports the same functions. The name of module B is indicated in the `link` macro \(see examples below\). +* Module B should be loaded to `Marine` by the moment the loading of module A starts. Module A cannot be loaded if at least one imported function is absent in `Marine`. + +See the examples below for wrapped `extern` block usage: + +{% tabs %} +{% tab title="Example 1" %} +```rust +#[marine] +pub struct TestRecord { + pub field_0: i32, + pub field_1: Vec>, +} + +// wrap the extern block with the marine macro to expose the function +// as an import to the Marine VM +#[marine] +#[link(wasm_import_module = "some_module")] +extern "C" { + pub fn foo(arg: Vec>>>, arg_2: String) -> Vec>>>; +} +``` +{% endtab %} + +{% tab title="Example 2" %} +```rust +[marine] +#[link(wasm_import_module = "some_module")] +extern "C" { + pub fn foo(arg: Vec>>>) -> Vec>>>; +} +``` +{% endtab %} +{% endtabs %} + + + +{% hint style="info" %} + + +#### Function import requirements + +* wrap an extern block with the function\(s\) to be imported with the `[marine]` macro +* all function\(s\) arguments must be of the `ftype` type +* the return type of the function\(s\) must be `ftype` +{% endhint %} + +#### + +#### Structures + +Finally, the `[marine]` macro can wrap a `struct` making possible to use it as a function argument or return type. Note that + +* only macro-wrapped structures can be used as function arguments and return types +* all fields of the wrapped structure must be public and of the `ftype`. +* it is possible to have inner records in the macro-wrapped structure and to import wrapped structs from other crates + +See the example below for wrapping `struct`: + +{% tabs %} +{% tab title="Example 1" %} +```rust +#[marine] +pub struct TestRecord0 { + pub field_0: i32, +} + +#[marine] +pub struct TestRecord1 { + pub field_0: i32, + pub field_1: String, + pub field_2: Vec, + pub test_record_0: TestRecord0, +} + +#[marine] +pub struct TestRecord2 { + pub test_record_0: TestRecord0, + pub test_record_1: TestRecord1, +} + +#[marine] +fn foo(mut test_record: TestRecord2) -> TestRecord2 { unimplemented!(); } +``` +{% endtab %} + +{% tab title="Example 2" %} +```rust +#[fce] +pub struct TestRecord0 { + pub field_0: i32, +} + +#[fce] +pub struct TestRecord1 { + pub field_0: i32, + pub field_1: String, + pub field_2: Vec, + pub test_record_0: TestRecord0, +} + +#[fce] +pub struct TestRecord2 { + pub test_record_0: TestRecord0, + pub test_record_1: TestRecord1, +} + +#[fce] +#[link(wasm_import_module = "some_module")] +extern "C" { + fn foo(mut test_record: TestRecord2) -> TestRecord2; +} +``` +{% endtab %} + +{% tab title="Example 3" %} +```rust +mod data_crate { + use fluence::marine; + #[marine] + pub struct Data { + pub name: String, + pub data: f64, + } +} + +use data_crate::Data; +use fluence::marine; + +fn main() {} + +#[marine] +fn some_function() -> Data { + Data { + name: "example".into(), + data: 1.0, + } +} + +``` +{% endtab %} +{% endtabs %} + + + +{% hint style="info" %} + + +> #### Structure passing requirements +> +> * wrap a structure with the `[marine]` macro +> * all structure fields must be of the `ftype` +> * the structure must be pointed to without preceding package import in a function signature, i.e`StructureName` but not `package_name::module_name::StructureName` +> * wrapped structs can be imported from crates +{% endhint %} + +#### + +#### Call Parameters + +There is a special API function `fluence::get_call_parameters()` that returns an instance of the [`CallParameters`](https://github.com/fluencelabs/marine-rs-sdk/blob/master/fluence/src/call_parameters.rs#L35) structure defined as follows: + +```rust +pub struct CallParameters { + /// Peer id of the AIR script initiator. + pub init_peer_id: String, + + /// Id of the current service. + pub service_id: String, + + /// Id of the service creator. + pub service_creator_peer_id: String, + + /// Id of the host which run this service. + pub host_id: String, + + /// Id of the particle which execution resulted a call this service. + pub particle_id: String, + + /// Security tetraplets which described origin of the arguments. + pub tetraplets: Vec>, +} +``` + +CallParameters are especially useful in constructing authentication services: + +```text +// auth.rs +use fluence::{marine, CallParameters}; +use::marine; + +pub fn is_owner() -> bool { + let meta = marine::get_call_parameters(); + let caller = meta.init_peer_id; + let owner = meta.service_creator_peer_id; + + caller == owner +} + +#[marine] +pub fn am_i_owner() -> bool { + is_owner() +} +``` + +#### + +#### MountedBinaryResult + +Due to the inherent limitations of Wasm modules, such as a lack of sockets, it may be necessary for a module to interact with its host to bridge such gaps, e.g. use a https transport provider like _curl_. In order for a Wasm module to use a host's _curl_ capabilities, we need to provide access to the binary, which at the code level is achieved through the Rust `extern` block: + +```rust +// Importing a linked binary, curl, to a Wasm module +#![allow(improper_ctypes)] + +use fluence::marine; +use fluence::module_manifest; +use fluence::MountedBinaryResult; + +module_manifest!(); + +pub fn main() {} + +#[marine] +pub fn curl_request(curl_cmd: Vec) -> MountedBinaryResult { + let response = curl(curl_cmd); + response +} + +#[marine] +#[link(wasm_import_module = "host")] +extern "C" { + fn curl(cmd: Vec) -> MountedBinaryResult; +} +``` + +The above code creates a "curl adapter", i.e., a Wasm module that allows other Wasm modules to use the the `curl_request` function, which calls the imported _curl_ binary in this case, to make http calls. Please note that we are wrapping the `extern` block with the `[marine]`macro and introduce a Marine-native data structure [`MountedBinaryResult`](https://github.com/fluencelabs/marine/blob/master/examples/url-downloader/curl_adapter/src/main.rs) as the linked-function return value. + +Please not that if you want to use `curl_request` with testing, see below, the curl call needs to be marked unsafe, e.g.: + +```rust + 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. + +MountedBinaryResult itself is a Marine-compatible struct containing a binary's return process code, error string and stdout and stderr as byte arrays: + +```rust +#[marine] +#[derive(Clone, PartialEq, Default, Eq, Debug, Serialize, Deserialize)] +pub struct MountedBinaryResult { + /// Return process exit code or host execution error code, where SUCCESS_CODE means success. + pub ret_code: i32, + + /// Contains the string representation of an error, if ret_code != SUCCESS_CODE. + pub error: String, + + /// The data that the process wrote to stdout. + pub stdout: Vec, + + /// The data that the process wrote to stderr. + pub stderr: Vec, +} + +``` + +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. + +Let's have a look at an implementation example: + +```rust +use fluence::marine; +use fluence::module_manifest; + +module_manifest!(); + +pub fn main() {} + +#[marine] +pub fn greeting(name: String) -> String { # 1 + format!("Hi, {}", name) +} + +#[cfg(test)] +mod tests { + use fluence_test::marine_test; # 2 + + #[marine_test(config_path = "../Config.toml", modules_dir = "../artifacts")] # 3 + fn empty_string() { + let actual = greeting.greeting(String::new()); # 4 + assert_eq!(actual, "Hi, "); + } + + #[marine_test(config_path = "../Config.toml", modules_dir = "../artifacts")] + fn non_empty_string() { + let actual = greeting.greeting("name".to_string()); + assert_eq!(actual, "Hi, name"); + } +} +``` + +1. We wrap a basic _greeting_ function with the `[marine`\] macro which results in the greeting.wasm module +2. We wrap our tests as usual with `[cfg(test)]` and import the fluence_test crate._ Do **not** import _super_ or the _local crate_. +3. Instead, we apply the `[marine_test]` to each of the test functions by providing the path to the config file, e.g., Config.toml, and the directory containing the Wasm module we obtained after compiling our project with `marine build`. It is imperative that project compilation proceeds the test runner otherwise there won't be the required Wasm file. +4. The target of our tests is the `pub fn greeting` function. Since we are calling the function from the Wasm module we must prefix the function name with the module namespace -- `greeting` in this example case. + +Now that we have our Wasm module and tests in place, we can proceed with `cargo test --release.` Note that using the `release`vastly improves the import speed of the necessary Wasm modules. + +### Features + +The SDK has two useful features: `logger` and `debug`. + +#### Logger + +Using logging is a simple way to assist in debugging without deploying the module\(s\) to a peer-to-peer network node. The `logger` feature allows you to use a special logger that is based at the top of the [log](https://crates.io/crates/log) crate. + +To enable logging please specify the `logger` feature of the Fluence SDK in `Config.toml` and add the [log](https://docs.rs/log/0.4.11/log/) crate: + +```rust +[dependencies] +log = "0.4.14" +fluence = { version = "0.6.9", features = ["logger"] } +``` + +The logger should be initialized before its usage. This can be done in the `main` function as shown in the example below. + +```rust +use fluence::marine; +use fluence::WasmLogger; + +pub fn main() { + WasmLogger::new() + // with_log_level can be skipped, + // logger will be initialized with Info level in this case. + .with_log_level(log::Level::Info) + .build() + .unwrap(); +} + +#[marine] +pub fn put(name: String, file_content: Vec) -> String { + log::info!("put called with file name {}", file_name); + unimplemented!() +} +``` + +In addition to the standard log creation features, the Fluence logger allows the so-called target map to be configured during the initialization step. This allows you to filter out logs by `logging_mask`, which can be set for each module in the service configuration. Let's consider an example: + +```rust +const TARGET_MAP: [(&str, i64); 4] = [ + ("instruction", 1 << 1), + ("data_cache", 1 << 2), + ("next_peer_pks", 1 << 3), + ("subtree_complete", 1 << 4), +]; + +pub fn main() { + use std::collections::HashMap; + use std::iter::FromIterator; + + let target_map = HashMap::from_iter(TARGET_MAP.iter().cloned()); + + fluence::WasmLogger::new() + .with_target_map(target_map) + .build() + .unwrap(); +} + +#[marine] +pub fn foo() { + log::info!(target: "instruction", "this will print if (logging_mask & 1) != 0"); + log::info!(target: "data_cache", "this will print if (logging_mask & 2) != 0"); +} +``` + +Here, an array called `TARGET_MAP` is defined and provided to a logger in the `main` function of a module. Each entry of this array contains a string \(a target\) and a number that represents the bit position in the 64-bit mask `logging_mask`. When you write a log message request `log::info!`, its target must coincide with one of the strings \(the targets\) defined in the `TARGET_MAP` array. The log will be printed if `logging_mask` for the module has the corresponding target bit set. + +{% hint style="info" %} +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: + +```bash +# running the greeting service compiled with debug feature +~ $ RUST_LOG="info" fce-repl Config.toml +Welcome to the Fluence FaaS REPL +app service's created with service id = e5cfa463-ff50-4996-98d8-4eced5ac5bb9 +elapsed time 40.694769ms + +1> call greeting greeting "user" +[greeting] sdk.allocate: 4 +[greeting] sdk.set_result_ptr: 1114240 +[greeting] sdk.set_result_size: 8 +[greeting] sdk.get_result_ptr, returns 1114240 +[greeting] sdk.get_result_size, returns 8 +[greeting] sdk.get_result_ptr, returns 1114240 +[greeting] sdk.get_result_size, returns 8 +[greeting] sdk.deallocate: 0x110080 8 + +result: String("Hi, user") + elapsed time: 222.675µs +``` + +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: + +```text +// main.rs +use fluence::marine; +use fluence::module_manifest; // import manifest macro + +module_manifest!(); // initialize macro + +fn main() {} + +#[marine] +fn some_function() {} +} +``` + +Using the Marine CLI, we can inspect a module's manifest with `marine info`: + +```rust +mbp16~/localdev/struct-exp(main|…) % marine info -i artifacts/*.wasm +it version: 0.20.1 +sdk version: 0.6.0 +authors: The Fluence Team +version: 0.1.0 +description: foo-wasm, a Marine wasi module +repository: +build time: 2021-06-11 21:08:59.855352 +00:00 UTC +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/knowledge_knowledge/knowledge_concepts.md b/knowledge_knowledge/knowledge_concepts.md index b718dac..ff360e0 100644 --- a/knowledge_knowledge/knowledge_concepts.md +++ b/knowledge_knowledge/knowledge_concepts.md @@ -28,7 +28,7 @@ Services are logical compute units derived from linking of one or more Wasm modu * Permission to resources * Maximum memory allocation -FCE uses a [shared nothing](https://en.wikipedia.org/wiki/Shared-nothing_architecture) linking scheme meaning that modules only expose functions explicitly marked to be publicly available while not sharing memeory or any other resources. It should be further noted that services can **not** call on other services directly. +FCE uses a [shared nothing](https://en.wikipedia.org/wiki/Shared-nothing_architecture) linking scheme meaning that modules only expose functions explicitly marked to be publicly available while not sharing memory or any other resources. It should be further noted that services can **not** call on other services directly. ## Blueprint diff --git a/knowledge_knowledge/knowledge_tools.md b/knowledge_knowledge/knowledge_tools.md index b76d137..b736f7c 100644 --- a/knowledge_knowledge/knowledge_tools.md +++ b/knowledge_knowledge/knowledge_tools.md @@ -1,14 +1,21 @@ # Tools -## Fluence FCE REPL +## Fluence Marine REPL -\`\`[`fce-repl`](https://crates.io/crates/frepl) is a command line tool \(CLI\) to locally inspect, run, and test module and service configurations making it an invaluable development tool. +[`mrepl`](https://crates.io/crates/mrepl) is a command line tool \(CLI\) to locally run a Marine instance to inspect, run, and test module and service configurations. ```text -mbp16~(:|✔) % fce-repl -Welcome to the FCE REPL (version 0.5.2) -app service was created with service id = 2321fc56-8cb9-497a-8abb-03d04665e1cc -elapsed time 282.52µs +mbp16~(:|✔) % mrepl +Welcome to the Marine REPL (version 0.7.2) +Minimal supported versions + sdk: 0.6.0 + interface-types: 0.20.0 + +New version is available! 0.7.2 -> 0.7.4 +To update run: cargo +nightly install mrepl --force + +app service was created with service id = d81a4de5-55c3-4cb7-935c-3d5c6851320d +elapsed time 486.234µs 1> help Commands: @@ -22,6 +29,8 @@ e/envs print environment variables of a modul f/fs print filesystem state of a module h/help print this message q/quit/Ctrl-C exit + +2> ``` ## Fluence Proto Distributor: FLDIST diff --git a/quick_start/quick_start_building_from_multiple_services.md b/quick_start/quick_start_building_from_multiple_services.md index 3954d9c..c146ead 100644 --- a/quick_start/quick_start_building_from_multiple_services.md +++ b/quick_start/quick_start_building_from_multiple_services.md @@ -43,7 +43,7 @@ Let's test the hex conversion test in isolation with the following AIR script: ``` {% hint style="info" %} -Aquamarine Intermediate Representation \(AIR\) is a low level implementation of Aquamarine to coordinate services into applications. For a detailed introduction to AIR, please refer to the [Knowledgebase](../knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md). For the remainder of this section, we will see three AIR _instructions_: _seq, xor,_ and _call._ +Aquamarine Intermediate Representation \(AIR\) is a low level implementation of Aquamarine to coordinate services into applications. For a detailed introduction to AIR, please refer to the [Knowledgebase](../knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md). For the remainder of this section, we will see three AIR _instructions_: _seq, xor,_ and _call._ _seq_ is the _sequential_ instruction that wraps arguments and executes them, you guessed it, sequentially. And yes, there is a _parallel_ instruction in the language. diff --git a/quick_start/quick_start_setup.md b/quick_start/quick_start_setup.md index 9cd78cf..76d20fb 100644 --- a/quick_start/quick_start_setup.md +++ b/quick_start/quick_start_setup.md @@ -15,11 +15,11 @@ rustup toolchain install nightly rustup target add wasm32-wasi ``` -In addition, install the Fluence REPL,`frepl`, and CLI, `fcli`, tools: +In addition, install the Marine REPL,`mrepl`, and CLI, `marine`, tools: ```bash -$ cargo install fcli --force -$ cargo install +nightly install frepl --force +$ cargo install marine --force +$ cargo +nightly install mrepl --force ``` Finally, you need [node](https://nodejs.org/en/) installed, and if you don't have it already, you may be best served by installing [NVM](https://github.com/nvm-sh/nvm): @@ -29,7 +29,7 @@ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash nvm install --lts ``` -which allows us to install the \[Fluence Service Distribution and Management too\]\([https://github.com/fluencelabs/proto-distributor](https://github.com/fluencelabs/proto-distributor)\), `fldist`. +which allows us to install the [Fluence Service Distribution and Management tool](https://github.com/fluencelabs/proto-distributor), `fldist`. ```bash npm install -g @fluencelabs/fldist