feat: introduce effector template (#1)

.github/actionlint.yml

@@ -0,0 +1,3 @@
+self-hosted-runner:
+  labels:
+    - builder

.github/release-please/config.json

@@ -0,0 +1,12 @@
+{
+  "bootstrap-sha": "a5bed5fc40f29c1ea8493a6d259fb590d5b7e88e",
+  "release-type": "simple",
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": true,
+  "packages": {
+    ".": {
+        "package-name": "effector",
+        "compontent": "effector"
+    }
+  }
+}

.github/release-please/manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  FORCE_COLOR: true
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+
+    outputs:
+      version: ${{ steps.release.outputs['version'] }}
+      pr: ${{ steps.release.outputs['pr'] }}
+      tag-name: ${{ steps.release.outputs['tag_name'] }}
+      release_created: ${{ steps.release.outputs['release_created'] }}
+
+    steps:
+      - name: Release with release-please
+        id: release
+        uses: google-github-actions/release-please-action@v4
+        with:
+            token: ${{ secrets.RELEASE_TOKEN }}
+            config-file: .github/release-please/config.json
+            manifest-file: .github/release-please/manifest.json
+
+      - name: Show output from release-please
+        env:
+          RELEASE_PLEASE_OUTPUT: ${{ toJSON(steps.release.outputs) }}
+        run: echo "${RELEASE_PLEASE_OUTPUT}" | jq
+
+  bump-version:
+    if: ${{ needs.release-please.outputs.pr != null }}
+    runs-on: ubuntu-latest
+    needs:
+      - release-please
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ fromJson(needs.release-please.outputs.pr).headBranchName }}
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Setup Rust toolchain
+        uses: dsherret/rust-toolchain-file@v1
+
+      - name: Install cargo-edit
+        uses: baptiste0928/cargo-install@v3.0.0
+        with:
+          crate: cargo-edit
+
+      - name: Get version
+        id: version
+        run: |
+          version="$(jq -r '.[]' .github/release-please/manifest.json)"
+          echo "version=${version}" >> $GITHUB_OUTPUT
+
+      # Update ALL packages version if some is changed
+      - name: Set version
+        run: cargo set-version ${{ steps.version.outputs.version }}
+
+      - name: Commit version bump
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore: Bump version to ${{ steps.version.outputs.version }}"
+          branch: ${{ fromJson(needs.release-please.outputs.pr).headBranchName }}
+
+  upload-archive:
+    if: ${{ needs.release-please.outputs.release_created }}
+
+    runs-on: ubuntu-latest
+
+    needs:
+        - release-please
+
+    permissions:
+        contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup fcli
+        uses: fluencelabs/setup-fluence@v1
+        with:
+          # TODO: fluence module pack works only on main now, need to change later
+          version: main
+
+      - name: Build archive
+        run: fluence module pack ./effector --binding-crate=./imports/ --no-input -d .
+
+      - name: Upload archive
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ needs.release-please.outputs.tag-name }}
+          files: |
+            ./ls_effector.tar.gz

.github/workflows/tests.yml

@@ -0,0 +1,45 @@
+name: "tests"
+
+on:
+  pull_request:
+    paths-ignore:
+      - '**.md'
+      - '.github/**'
+      - '!.github/workflows/tests.yml'
+  push:
+    branches:
+      - "main"
+    paths-ignore:
+      - '**.md'
+      - '.github/**'
+      - '!.github/workflows/tests.yml'
+
+jobs:
+  unit-tests:
+    name: "Run unit tests"
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup IPFS CLI
+        uses: nahsi/setup-ipfs@v1
+
+      - name: Setup fcli
+        uses: fluencelabs/setup-fluence@v1
+        with:
+          # TODO: fluence module build now only in main, need to change later
+          version: main
+
+      - name: Setup Rust toolchain
+        uses: dsherret/rust-toolchain-file@v1
+
+      - name: Setup cargo-nextest
+        uses: taiki-e/install-action@nextest
+
+      - name: Build
+        run: ./build.sh
+
+      - name: Run tests
+        run: ./test.sh

.gitignore

@@ -12,3 +12,6 @@ Cargo.lock
 
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
+
+.idea
+.vscode

Cargo.toml

@@ -0,0 +1,23 @@
+[workspace]
+resolver = "2"
+members = [ "effector", "types", "cid", "imports" ]
+
+  [workspace.dependencies]
+  marine-rs-sdk-test = "0.16.1"
+  eyre = "0.6.12"
+
+    [workspace.dependencies.ls-effector-types]
+    path = "types"
+
+    [workspace.dependencies.ls-effector-imports]
+    path = "imports"
+
+    [workspace.dependencies.ls_effector]
+    path = "effector"
+
+    [workspace.dependencies.ls-effector-cid]
+    path = "cid"
+
+    [workspace.dependencies.marine-rs-sdk]
+    version = "0.14.0"
+    features = [ "logger" ]

README.md

@@ -0,0 +1,25 @@
+# Fluence Effector Template
+
+This repository provides an example of a basic effector project and serves as a template for easy effector development.
+
+## ls effector
+
+In this project, we provide an effector for the /bin/ls binary from [coreuitls](https://www.gnu.org/software/coreutils/manual/coreutils.html#ls-invocation).
+
+### Project Structure
+
+This project consists of 4 crates:
+- effector is the effector module itself. To obtain the correct WASM module, it must be be built with marine build --release ;
+- cid is a rust crate for exporting the [CID](https://docs.ipfs.tech/concepts/content-addressing/#version-1-v1) of the effector module. This crate is optional and only provides means to embed CIDs of selected effectors into your rust project, for example, [Nox](https://github.com/fluencelabs/nox);
+- types is a rust crate with the type definitions used in the API functions of the effector module (the one with the #[marine] tag). This crate helps to interact with the effector module's API in non-effector modules. However, this crate isn't supposed to be used on its own outside of the effector crate scope; it's re-exported by the imports crate below;
+- imports is a rust crate providing the type definitions (via the types crate) as well as effector module's [import definition](https://fluence.dev/docs/marine-book/marine-rust-sdk/developing/import-functions). This crate is aimed to help import the effector modules without copy-pasting the definitions manually.
+
+### How to build
+
+To build the project, you need:
+- [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) to build the rust project
+- [IPFS CLI](https://docs.ipfs.tech/install/command-line/#system-requirements) to build the cid crate
+- [Fluence CLI](https://fluence.dev/docs/build/setting-up/installing_cli) to build the effector
+
+The build.sh bash script located in the repository's root contains the commands to build the effector module and the cid crate.
+The test.sh bash script located in the repository's root contains the commands to run tests in the effector module.

build.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -o errexit -o nounset -o pipefail
+
+# set current working directory to script directory to run script from everywhere
+cd "$(dirname "$0")"
+
+# This script builds all subprojects and puts all created Wasm modules in one dir
+fluence module build ./effector --no-input
+
+cargo build --release

cid/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "ls-effector-cid"
+version = "0.1.0"
+edition = "2021"
+build = "built.rs"
+publish = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[dependencies]
+
+[build-dependencies]
+built = "0.7.0"

cid/built.rs

@@ -0,0 +1,42 @@
+use std::process::Command;
+
+fn main() {
+    if Command::new("ipfs").arg("--version").status().is_err() {
+        println!("cargo::warning=Error: 'ipfs' command not found. Make sure it is installed and available in your system's PATH.");
+        std::process::exit(1);
+    }
+
+    let out_dir = std::env::var("OUT_DIR").expect("OUT_DIR not set");
+    let target_cid_file = "cidv1";
+    let wasm_path = "../target/wasm32-wasi/release/ls_effector.wasm";
+
+    println!("cargo:rerun-if-changed={}", wasm_path);
+
+    let output = Command::new("ipfs")
+        .args(&[
+            "add",
+            "--only-hash",
+            "-Q",
+            "--cid-version",
+            "1",
+            "--hash",
+            "sha2-256",
+            "--chunker=size-262144",
+            wasm_path,
+        ])
+        .output()
+        .expect("Failed to execute IPFS command");
+
+    if output.status.success() {
+        let cid = String::from_utf8(output.stdout)
+            .unwrap_or_else(|e| format!("Failed to parse IPFS output: {e:?}"));
+        let cid = cid.trim();
+        let cid_path = format!("{}/{}", out_dir, target_cid_file);
+        println!("cargo:warning=Generated CIDv1 {}", cid);
+        std::fs::write(&cid_path, cid).expect("Failed to write CID to file");
+    } else {
+        panic!("Failed to compute CIDv1 of wasm file {wasm_path} with IPFS: {output:?}");
+    }
+
+    built::write_built_file().expect("Failed to acquire build-time information")
+}

cid/src/lib.rs

@@ -0,0 +1,16 @@
+pub use build_info::PKG_VERSION as VERSION;
+
+pub mod build_info {
+    include!(concat!(env!("OUT_DIR"), "/built.rs"));
+}
+
+pub const EFFECTOR_CID: &'static str = include_str!(concat!(env!("OUT_DIR"), "/cidv1"));
+
+#[cfg(test)]
+mod tests {
+    // TODO: check that it's correct CIDv1
+    #[test]
+    fn test_effectors_cid_empty() {
+        assert!(!crate::EFFECTOR_CID.is_empty());
+    }
+}

effector/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "ls_effector"
+version = "0.1.0"
+edition = "2018"
+publish = false
+
+[dependencies]
+eyre = { workspace = true }
+log = "0.4.20"
+marine-rs-sdk = { workspace = true }
+ls-effector-types = { workspace = true }
+
+[dev-dependencies]
+marine-rs-sdk-test = { workspace = true }
+env_logger = "0.10.0"
+test-env-helpers = "0.2.2"

effector/module.yaml

@@ -0,0 +1,10 @@
+# yaml-language-server: $schema=../.fluence/schemas/module.json
+version: 1
+
+type: rust
+
+name: ls_effector
+
+effects:
+  binaries:
+    ls: /usr/bin/ls

effector/src/import.rs

@@ -0,0 +1,9 @@
+use marine_rs_sdk::{marine, MountedBinaryResult};
+
+// Here we need to import the mounted binary in the module using `host_import`
+#[marine]
+#[host_import]
+extern "C" {
+    /// Execute provided cmd as a parameters of ls.
+    pub fn ls(cmd: Vec<String>) -> MountedBinaryResult;
+}