Merge pull request #1 from massalabs/feature/add-rust-bindings

.github/workflows/ci-cd.yaml

@@ -0,0 +1,43 @@
+name: CI/CD
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+  repository_dispatch:
+    types: [remote-build]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: full
+  RUSTFLAGS: "--deny warnings"
+  RUST_TOOLCHAIN: nightly-2023-02-27
+  RUST_WORKING_DIRECTORY: ./rust
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rust-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: "recursive"
+          ref: ${{ github.event.client_payload.ref }}
+      - run: echo ${{ github.event.client_payload.sha }}
+      - uses: arduino/setup-protoc@v2
+        with:
+          version: "23.2"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "rust-build"
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - run: cargo build --release --all-features
+        working-directory: ${{ env.RUST_WORKING_DIRECTORY }}

.gitignore

@@ -0,0 +1,7 @@
+.direnv
+.DS_Store
+.envrc
+.idea
+.vscode
+.fleet
+/gen

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "massa-proto"]
+	path = massa-proto
+	url = https://github.com/massalabs/massa-proto.git

README.md

@@ -1,2 +1,54 @@
-# massa-proto-bindings
+# MASSA PROTO BINDINGS
+
 Generated source code from protobuf files for Massa blockchain.
+
+Requirements
+------------
+
+Make sure you have the following latest versions of the required tools:
+
+- [protoc](https://grpc.io/docs/protoc-installation/): `3.21.12+`. 
+
+Please ensure that you have the required versions or newer to guarantee compatibility and access to the latest features.
+
+Project build
+-------------
+
+You can generate source code from protobuf files by running: 
+```bash
+./build.sh
+```
+
+For Windows users run:
+```powershell
+./build.bat
+```
+
+Postman integration
+-------------------
+You can easily import APIs collections from [Massa's Postman workspace](https://www.postman.com/massalabs) and start testing and exploring the provided functionalities by Massa API's.
+
+VSCode settings
+------------------
+
+1- Install [vscode-proto3](https://marketplace.visualstudio.com/items?itemName=zxh404.vscode-proto3) extension.
+
+2- The following settings contain a `protoc` configuration block with Java generation output:
+
+```json
+{
+    "protoc": {  // Specifies the configuration for the protoc plugin.
+        "path": "/PATH/TO/PROTOC",  // Sets the path to the protoc binary that will be used to compile the protobuf files.
+        "compile_on_save": true,  // Enables automatic compilation of protobuf files when they are saved.
+        "options": [  // Specifies the command line options that will be passed to protoc.
+            "{workspaceRoot}/massa-proto/proto/**/*.proto",  // Specifies the path to the protobuf files that should be compiled.
+            "--proto_path=${workspaceRoot}/massa-proto/proto/",  // Specifies the directory to search for imported protobuf files.
+            "--proto_path=${workspaceRoot}/massa-proto/proto/commons",  // Specifies the directory to search for imported common protobuf files.
+            "--proto_path=${workspaceRoot}/massa-proto/proto/third_party",  // Specifies the directory to search for imported third_party protobuf files.
+            "--java_out=${workspaceRoot}/massa-proto/gen/",  // Generates Java code from the protobuf files.
+        ]
+    }
+}
+```
+
+3- Add the snippet above to `.vscode/settings.json`.

build.bat

@@ -0,0 +1,10 @@
+@echo off
+echo Building Massa proto bindings...
+
+rem Generate ABI documentation
+echo Generating RUST bindings...
+cd ./rust
+cargo build --release
+echo RUST bindings generated successfully.
+
+echo Massa proto bindings build finished!

build.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+echo "Building Massa proto bindings..."
+
+# Generate ABI documentation
+echo "Generating RUST bindings..."
+cd ./rust && cargo build --release
+echo "RUST bindings generated successfully."
+
+echo "Massa proto bindings build finished!"

rust/.gitignore

@@ -0,0 +1,13 @@
+.direnv
+.DS_Store
+.envrc
+.idea
+.vscode
+.fleet
+*.swp*
+**/Cargo.lock
+**/target
+lcov.info
+shell.nix
+docs/_build
+massa-proto-bindings.iml

rust/Cargo.toml

@@ -0,0 +1,23 @@
+# Copyright (c) 2023 MASSA LABS <info@massa.net>
+
+[package]
+name = "massa_proto_bindings"
+version = "0.1.0"
+edition = "2021"
+description = "Protobuf rust bindings for the Massa blockchain"
+repository = "https://github.com/massalabs/massa-proto-bindings/"
+homepage = "https://massa.net"
+documentation = "https://docs.massa.net/"
+
+[lib]
+name = "massa_proto_bindings"
+
+[dependencies]
+prost = "=0.11.9"
+prost-types = "=0.11.9"
+tonic = "=0.9.2"
+
+[build-dependencies]
+glob = "0.3.1"
+prost-build = "=0.11.9"
+tonic-build = "=0.9.2"

rust/build.rs

@@ -0,0 +1,82 @@
+// Copyright (c) 2023 MASSA LABS <info@massa.net>
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tonic::build()?;
+
+    Ok(())
+}
+
+mod tonic {
+    use glob::glob;
+    use std::{
+        env,
+        path::{Path, PathBuf},
+    };
+
+    /// This function is responsible for building the Massa protobuf
+    pub fn build() -> Result<(), Box<dyn std::error::Error>> {
+        let current_dir = env::current_dir()?;
+        let parent_dir = current_dir.parent().ok_or("no parent directory found")?;
+
+        // Generate ABI bindings
+        let protos_path = parent_dir.join("massa-proto/proto/abis");
+        let protos = find_protos(protos_path)?;
+        let proto_include_paths = [
+            parent_dir.join("massa-proto/proto/abis"),
+            parent_dir.join("massa-proto/proto/commons"),
+            parent_dir.join("massa-proto/proto/third_party"),
+        ];
+
+        tonic_build::configure()
+            .build_server(false)
+            .build_transport(false)
+            .build_client(false)
+            .include_file("_abi_includes.rs")
+            .out_dir("src/")
+            .compile(&protos, &proto_include_paths)
+            .map_err(|e| format!("ABI protobuf compilation error: {:?}", e))?;
+
+        // Generate API bindings
+        let protos_path = parent_dir.join("massa-proto/proto/apis");
+        let protos = find_protos(protos_path)?;
+        let proto_include_paths = [
+            parent_dir.join("massa-proto/proto/apis"),
+            parent_dir.join("massa-proto/proto/commons"),
+            parent_dir.join("massa-proto/proto/third_party"),
+        ];
+
+        tonic_build::configure()
+            .build_server(true)
+            .build_transport(true)
+            .build_client(true)
+            .type_attribute(
+                ".google.api.HttpRule",
+                "#[cfg(not(doctest))]\n\
+                 #[allow(dead_code)]\n\
+                 pub struct HttpRuleComment{}\n\
+                 /// HACK: see docs in [`HttpRuleComment`] ignored in doctest pass",
+            )
+            .include_file("_api_includes.rs")
+            .file_descriptor_set_path("src/api.bin")
+            .out_dir("src/")
+            .compile(&protos, &proto_include_paths)
+            .map_err(|e| format!("API protobuf compilation error: {:?}", e))?;
+
+        Ok(())
+    }
+
+    fn find_protos(dir_path: impl AsRef<Path>) -> Result<Vec<PathBuf>, Box<dyn std::error::Error>> {
+        let glob_pattern = format!("{}/**/*.proto", dir_path.as_ref().display());
+        let paths: Vec<_> = glob(&glob_pattern)?.filter_map(Result::ok).collect();
+
+        if paths.is_empty() {
+            return Err(format!(
+                "no .proto files found in the specified directory: {}",
+                dir_path.as_ref().display()
+            )
+            .into());
+        }
+
+        Ok(paths)
+    }
+}

rust/src/_abi_includes.rs

@@ -0,0 +1,7 @@
+pub mod massa {
+    pub mod abi {
+        pub mod v1 {
+            include!("massa.abi.v1.rs");
+        }
+    }
+}

rust/src/_api_includes.rs

@@ -0,0 +1,20 @@
+pub mod google {
+    pub mod api {
+        include!("google.api.rs");
+    }
+    pub mod rpc {
+        include!("google.rpc.rs");
+    }
+}
+pub mod massa {
+    pub mod api {
+        pub mod v1 {
+            include!("massa.api.v1.rs");
+        }
+    }
+    pub mod model {
+        pub mod v1 {
+            include!("massa.model.v1.rs");
+        }
+    }
+}