marine/README.md

Marine

Marine is a modern general purpose Wasm runtime based on the Component model, it runs multi-module Wasm applications with interface-types and shared-nothing linking scheme. This execution model suits well for different scenarios, especially for applications based on the entity component system (ECS) pattern or architecture based on plugins.

Fluence nodes use Marine to execute Wasm services composed by compiled Aqua:\

Motivational example

The most archetypal example to meet the power of Marine is a multi-module Wasm application. Let's consider this one consists of two modules:

use marine_rs_sdk::marine;

fn main() {}

#[marine]
pub fn greeting(name: &str) -> Vec<String> {
    let donkey_greeting = donkey::greeting(name);
    let shrek_greeting = format!("Shrek: hi, {}", name);
    
    vec![shrek_greeting, donkey_greeting]
}

mod donkey {
    use super::*;

    #[marine]
    #[link(wasm_import_module = "donkey")]
    extern "C" {
        pub fn greeting(name: &str) -> String;
    }
}

use marine_rs_sdk::marine;

fn main() {}

#[marine]
pub fn greeting(name: &str) -> String {
    format!("Donkey: hi, {}", name)
}

Compile these modules (you'll need Marine tools to be installed, here is the installation guide) and run them with Marine REPL:

$ > ./build.sh
  ...
$ > mrepl Config.toml
  ...
1> interfaces
Loaded modules interface:

shrek:
  fn greeting(name: string) -> []string
donkey:
  fn greeting(name: string) -> string

2> call shrek greeting "Feona"
result: Array([String("Shrek: hi, Feona"), String("Donkey: hi, Feona")])
 elapsed time: 903.949µs

3> q

Repository structure

• REPL - REPL intended to test Marine Wasm modules
• CLI - CLI intended to build and extract some info from Marine Wasm modules
• fluence-app-service - Fluence Application Service layer provides basic API for service running
• fluence-faas - Fluence FaaS layer provides host closures, IT<->JSON conversion, logger, config handling and other
• runtime - runtime layer provides basic functionality for loading, unloading and calling modules
• web-runtime - web runtime layer aim to run Marine in browser
• examples - several Marine examples used mostly for tests
• it-generator - generator of IT
• it-interfaces - handy structure for interface types handling
• it-json-serde - crate for conversion between IT and JSON
• min-it-version - keeps minimal supported versions of IT and SDK by runtime
• module-info-parser - parser of module manifest and sdk version
• module-interface - parser of module IT
• utils - some utility functions and consts

References

• Documentation
• Examples
• Quickstart