updated documentation and merged with newer version

Author: morrisettathena

.github/workflows/test-and-release.yml

@@ -87,7 +87,7 @@ jobs:
         with:
           submodules: recursive
       - name: Install Buf
-        uses: bufbuild/buf-setup-action@v1.4.0
+        uses: bufbuild/buf-setup-action@v1.5.0
       - name: Install Rust
         uses: actions-rs/toolchain@v1
         with:
@@ -135,7 +135,7 @@ jobs:
         with:
           cache-on-failure: true
       - name: Run e2e tests
-        run: scripts/tests.e2e.sh 1.7.11
+        run: scripts/tests.e2e.sh 1.7.13
 
   release:
     name: Release ${{ matrix.job.target }} (${{ matrix.job.os }})

.gitignore

@@ -1,7 +1,7 @@
 # Generated by Cargo
 # will have compiled files and executables
 /mini-kvvm/target/
-/proto/target/
+crates/avalanche-proto/target/
 /target
 
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries

.gitmodules

@@ -1,6 +1,6 @@
 [submodule "proto/protos/avalanchego"]
-	path = proto/protos/avalanchego
+	path = crates/avalanche-proto/protos/avalanchego
 	url = https://github.com/ava-labs/avalanchego.git
 [submodule "proto/protos/avalanche-network-runner"]
-	path = proto/protos/avalanche-network-runner
+	path = crates/avalanche-proto/protos/avalanche-network-runner
 	url = https://github.com/ava-labs/avalanche-network-runner

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 members = [
     "mini-kvvm",
-    "proto",
+    "crates/avalanche-proto",
     "tests/e2e"
 ]

proto/Cargo.toml renamed to crates/avalanche-proto/Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "avalanche-proto"
-version = "0.0.1"
+version = "0.15.0"
 edition = "2021"
 rust-version = "1.61"
-publish = false
+publish = true
 description = "Protobuf generated client and server resources for Avalanche gRPC in rust"
 license = "BSD-3-Clause"
 homepage = "https://avax.network"
@@ -16,6 +16,7 @@ aliasreader = []
 appsender = ["google_protobuf"]
 google_api = []
 google_protobuf = []
+helloworld = []
 http = []
 http_responsewriter = ["http","google_protobuf"]
 io_prometheus_client = []
@@ -37,6 +38,14 @@ chrono = "0.4.19"
 prost = "0.10.4"
 tonic = { version = "0.7", features = ["compression"] }
 
+[dev-dependencies]
+avalanche-proto = { path = "./", features = ["helloworld"] }
+tokio = { version = "1.19.1", features = ["fs", "rt-multi-thread"] }
+tokio-stream = { version = "0.1.9", features = ["net"] }
+tonic = { version = "0.7", features = ["compression"] }
+tonic-health = "0.6"
+tonic-reflection = "0.4.0"
+
 [build-dependencies]
 protoc-gen-prost = "0.1.3"
 protoc-gen-tonic = "0.1.0"

proto/LICENSE renamed to crates/avalanche-proto/LICENSE

@@ -0,0 +1,46 @@
+
+# avalanche-proto
+
+Protobuf generated client and server resources for Avalanche gRPC in rust.
+The generated stubs use the upstream [avalanchego/proto](https://github.com/ava-labs/avalanchego-internal/tree/dev/proto)
+definitions as the source of truth and versioning will align with avalanchego releases.
+
+## versions
+
+Support for avalanchego protocol version 15+
+
+The release version will align with the [protocol version](https://github.com/ava-labs/avalanchego/blob/v1.7.13/vms/rpcchainvm/vm.go#L21)
+for avalanchego. In our example linked above avalanchego is currently on protocol version 15.
+This aligns with the minor version of the avalanche-proto release. Patches to minor releases
+could include improvements and even features for protos not releated to avalanchego.
+
+```bash
+avalanche-types = { version = "0.15", features = [] } // supports avalanchego protocol version 15
+```
+
+## usage
+
+```rust
+use avalanche_proto::{
+    http::{
+        http_server::Http,
+        HttpRequest, HandleSimpleHttpResponse, HandleSimpleHttpRequest
+    },
+    google::protobuf::Empty,
+};
+```
+
+```rust
+    use avalanche_proto::grpcutil;
+
+    grpcutil::default_server()
+        .add_service(VmServer::new(vm))
+        .serve_with_incoming(TcpListenerStream::new(listener))
+        .await
+        .map_err(|e| {
+            Error::new(
+                ErrorKind::Other,
+                format!("failed to serve vm service: {}", e),
+            )
+        })
+```

crates/avalanche-proto/README.md

@@ -0,0 +1,13 @@
+use avalanche_proto::helloworld::{greeter_client::GreeterClient, HelloRequest};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut client = GreeterClient::connect("http://[::1]:50051").await?;
+    let request = tonic::Request::new(HelloRequest {
+        name: "Avalanche Rustaceans!".into(),
+    });
+    let response = client.say_hello(request).await?;
+
+    println!("response: {:?}", response);
+    Ok(())
+}

proto/buf.gen.yaml renamed to crates/avalanche-proto/buf.gen.yaml

@@ -0,0 +1,49 @@
+use avalanche_proto::{
+    grpcutil,
+    helloworld::{
+        self,
+        greeter_server::{Greeter, GreeterServer},
+        HelloReply, HelloRequest,
+    },
+};
+use tokio::runtime::Runtime;
+use tonic::{Request, Response, Status};
+
+#[derive(Default)]
+struct MyGreeter;
+
+#[tonic::async_trait]
+impl Greeter for MyGreeter {
+    async fn say_hello(
+        &self,
+        request: Request<HelloRequest>,
+    ) -> Result<Response<HelloReply>, Status> {
+        println!("Got a request from {:?}", request.remote_addr());
+
+        let reply = HelloReply {
+            message: format!("Hello {}!", request.into_inner().name),
+        };
+        Ok(Response::new(reply))
+    }
+}
+
+fn main() {
+    let addr = "[::1]:50051".parse().unwrap();
+    println!("Server listening on {}", addr);
+
+    // ref. https://github.com/hyperium/tonic/blob/v0.7.2/examples/src/reflection/server.rs
+    let reflection_service = tonic_reflection::server::Builder::configure()
+        .register_encoded_file_descriptor_set(helloworld::FILE_DESCRIPTOR_SET)
+        .build()
+        .expect("failed to create gRPC reflection service");
+    let greeter = MyGreeter::default();
+
+    let runtime = Runtime::new().expect("failed to create runtime");
+
+    let server = grpcutil::default_server()
+        .add_service(reflection_service)
+        .add_service(GreeterServer::new(greeter))
+        .serve(addr);
+
+    runtime.block_on(server).expect("runtime failed");
+}

proto/buf.lock renamed to crates/avalanche-proto/buf.lock

@@ -0,0 +1,33 @@
+// Copyright 2015 gRPC authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package helloworld;
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}

proto/buf.work.yaml renamed to crates/avalanche-proto/buf.work.yaml

@@ -0,0 +1,15 @@
+
+#!/usr/bin/env bash
+set -xue
+
+if ! [[ "$0" =~ ./scripts/examples.sh ]]; then
+  echo "must be run from repository root"
+  exit 255
+fi
+
+# cleanup port
+fuser -k 50051/tcp || true
+
+cargo run --example server &
+sleep 1
+cargo run --example client

proto/buf.yaml renamed to crates/avalanche-proto/buf.yaml

@@ -0,0 +1,93 @@
+// @generated
+/// The request message containing the user's name.
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct HelloRequest {
+    #[prost(string, tag="1")]
+    pub name: ::prost::alloc::string::String,
+}
+/// The response message containing the greetings
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct HelloReply {
+    #[prost(string, tag="1")]
+    pub message: ::prost::alloc::string::String,
+}
+/// Encoded file descriptor set for the `helloworld` package
+pub const FILE_DESCRIPTOR_SET: &[u8] = &[
+    0x0a, 0xa8, 0x09, 0x0a, 0x1b, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x2f,
+    0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f,
+    0x12, 0x0a, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x22, 0x22, 0x0a, 0x0c,
+    0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x12, 0x12, 0x0a, 0x04,
+    0x6e, 0x61, 0x6d, 0x65, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x6e, 0x61, 0x6d, 0x65,
+    0x22, 0x26, 0x0a, 0x0a, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x52, 0x65, 0x70, 0x6c, 0x79, 0x12, 0x18,
+    0x0a, 0x07, 0x6d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52,
+    0x07, 0x6d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x32, 0x49, 0x0a, 0x07, 0x47, 0x72, 0x65, 0x65,
+    0x74, 0x65, 0x72, 0x12, 0x3e, 0x0a, 0x08, 0x53, 0x61, 0x79, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x12,
+    0x18, 0x2e, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x2e, 0x48, 0x65, 0x6c,
+    0x6c, 0x6f, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x16, 0x2e, 0x68, 0x65, 0x6c, 0x6c,
+    0x6f, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x2e, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x52, 0x65, 0x70, 0x6c,
+    0x79, 0x22, 0x00, 0x4a, 0xdd, 0x07, 0x0a, 0x06, 0x12, 0x04, 0x0e, 0x00, 0x20, 0x01, 0x0a, 0xbf,
+    0x04, 0x0a, 0x01, 0x0c, 0x12, 0x03, 0x0e, 0x00, 0x12, 0x32, 0xb4, 0x04, 0x20, 0x43, 0x6f, 0x70,
+    0x79, 0x72, 0x69, 0x67, 0x68, 0x74, 0x20, 0x32, 0x30, 0x31, 0x35, 0x20, 0x67, 0x52, 0x50, 0x43,
+    0x20, 0x61, 0x75, 0x74, 0x68, 0x6f, 0x72, 0x73, 0x2e, 0x0a, 0x0a, 0x20, 0x4c, 0x69, 0x63, 0x65,
+    0x6e, 0x73, 0x65, 0x64, 0x20, 0x75, 0x6e, 0x64, 0x65, 0x72, 0x20, 0x74, 0x68, 0x65, 0x20, 0x41,
+    0x70, 0x61, 0x63, 0x68, 0x65, 0x20, 0x4c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x2c, 0x20, 0x56,
+    0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x20, 0x32, 0x2e, 0x30, 0x20, 0x28, 0x74, 0x68, 0x65, 0x20,
+    0x22, 0x4c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x22, 0x29, 0x3b, 0x0a, 0x20, 0x79, 0x6f, 0x75,
+    0x20, 0x6d, 0x61, 0x79, 0x20, 0x6e, 0x6f, 0x74, 0x20, 0x75, 0x73, 0x65, 0x20, 0x74, 0x68, 0x69,
+    0x73, 0x20, 0x66, 0x69, 0x6c, 0x65, 0x20, 0x65, 0x78, 0x63, 0x65, 0x70, 0x74, 0x20, 0x69, 0x6e,
+    0x20, 0x63, 0x6f, 0x6d, 0x70, 0x6c, 0x69, 0x61, 0x6e, 0x63, 0x65, 0x20, 0x77, 0x69, 0x74, 0x68,
+    0x20, 0x74, 0x68, 0x65, 0x20, 0x4c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x2e, 0x0a, 0x20, 0x59,
+    0x6f, 0x75, 0x20, 0x6d, 0x61, 0x79, 0x20, 0x6f, 0x62, 0x74, 0x61, 0x69, 0x6e, 0x20, 0x61, 0x20,
+    0x63, 0x6f, 0x70, 0x79, 0x20, 0x6f, 0x66, 0x20, 0x74, 0x68, 0x65, 0x20, 0x4c, 0x69, 0x63, 0x65,
+    0x6e, 0x73, 0x65, 0x20, 0x61, 0x74, 0x0a, 0x0a, 0x20, 0x20, 0x20, 0x20, 0x20, 0x68, 0x74, 0x74,
+    0x70, 0x3a, 0x2f, 0x2f, 0x77, 0x77, 0x77, 0x2e, 0x61, 0x70, 0x61, 0x63, 0x68, 0x65, 0x2e, 0x6f,
+    0x72, 0x67, 0x2f, 0x6c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x73, 0x2f, 0x4c, 0x49, 0x43, 0x45,
+    0x4e, 0x53, 0x45, 0x2d, 0x32, 0x2e, 0x30, 0x0a, 0x0a, 0x20, 0x55, 0x6e, 0x6c, 0x65, 0x73, 0x73,
+    0x20, 0x72, 0x65, 0x71, 0x75, 0x69, 0x72, 0x65, 0x64, 0x20, 0x62, 0x79, 0x20, 0x61, 0x70, 0x70,
+    0x6c, 0x69, 0x63, 0x61, 0x62, 0x6c, 0x65, 0x20, 0x6c, 0x61, 0x77, 0x20, 0x6f, 0x72, 0x20, 0x61,
+    0x67, 0x72, 0x65, 0x65, 0x64, 0x20, 0x74, 0x6f, 0x20, 0x69, 0x6e, 0x20, 0x77, 0x72, 0x69, 0x74,
+    0x69, 0x6e, 0x67, 0x2c, 0x20, 0x73, 0x6f, 0x66, 0x74, 0x77, 0x61, 0x72, 0x65, 0x0a, 0x20, 0x64,
+    0x69, 0x73, 0x74, 0x72, 0x69, 0x62, 0x75, 0x74, 0x65, 0x64, 0x20, 0x75, 0x6e, 0x64, 0x65, 0x72,
+    0x20, 0x74, 0x68, 0x65, 0x20, 0x4c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x20, 0x69, 0x73, 0x20,
+    0x64, 0x69, 0x73, 0x74, 0x72, 0x69, 0x62, 0x75, 0x74, 0x65, 0x64, 0x20, 0x6f, 0x6e, 0x20, 0x61,
+    0x6e, 0x20, 0x22, 0x41, 0x53, 0x20, 0x49, 0x53, 0x22, 0x20, 0x42, 0x41, 0x53, 0x49, 0x53, 0x2c,
+    0x0a, 0x20, 0x57, 0x49, 0x54, 0x48, 0x4f, 0x55, 0x54, 0x20, 0x57, 0x41, 0x52, 0x52, 0x41, 0x4e,
+    0x54, 0x49, 0x45, 0x53, 0x20, 0x4f, 0x52, 0x20, 0x43, 0x4f, 0x4e, 0x44, 0x49, 0x54, 0x49, 0x4f,
+    0x4e, 0x53, 0x20, 0x4f, 0x46, 0x20, 0x41, 0x4e, 0x59, 0x20, 0x4b, 0x49, 0x4e, 0x44, 0x2c, 0x20,
+    0x65, 0x69, 0x74, 0x68, 0x65, 0x72, 0x20, 0x65, 0x78, 0x70, 0x72, 0x65, 0x73, 0x73, 0x20, 0x6f,
+    0x72, 0x20, 0x69, 0x6d, 0x70, 0x6c, 0x69, 0x65, 0x64, 0x2e, 0x0a, 0x20, 0x53, 0x65, 0x65, 0x20,
+    0x74, 0x68, 0x65, 0x20, 0x4c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x20,
+    0x74, 0x68, 0x65, 0x20, 0x73, 0x70, 0x65, 0x63, 0x69, 0x66, 0x69, 0x63, 0x20, 0x6c, 0x61, 0x6e,
+    0x67, 0x75, 0x61, 0x67, 0x65, 0x20, 0x67, 0x6f, 0x76, 0x65, 0x72, 0x6e, 0x69, 0x6e, 0x67, 0x20,
+    0x70, 0x65, 0x72, 0x6d, 0x69, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x73, 0x20, 0x61, 0x6e, 0x64, 0x0a,
+    0x20, 0x6c, 0x69, 0x6d, 0x69, 0x74, 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x73, 0x20, 0x75, 0x6e, 0x64,
+    0x65, 0x72, 0x20, 0x74, 0x68, 0x65, 0x20, 0x4c, 0x69, 0x63, 0x65, 0x6e, 0x73, 0x65, 0x2e, 0x0a,
+    0x0a, 0x08, 0x0a, 0x01, 0x02, 0x12, 0x03, 0x10, 0x00, 0x13, 0x0a, 0x2e, 0x0a, 0x02, 0x06, 0x00,
+    0x12, 0x04, 0x13, 0x00, 0x16, 0x01, 0x1a, 0x22, 0x20, 0x54, 0x68, 0x65, 0x20, 0x67, 0x72, 0x65,
+    0x65, 0x74, 0x69, 0x6e, 0x67, 0x20, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x20, 0x64, 0x65,
+    0x66, 0x69, 0x6e, 0x69, 0x74, 0x69, 0x6f, 0x6e, 0x2e, 0x0a, 0x0a, 0x0a, 0x0a, 0x03, 0x06, 0x00,
+    0x01, 0x12, 0x03, 0x13, 0x08, 0x0f, 0x0a, 0x1f, 0x0a, 0x04, 0x06, 0x00, 0x02, 0x00, 0x12, 0x03,
+    0x15, 0x02, 0x35, 0x1a, 0x12, 0x20, 0x53, 0x65, 0x6e, 0x64, 0x73, 0x20, 0x61, 0x20, 0x67, 0x72,
+    0x65, 0x65, 0x74, 0x69, 0x6e, 0x67, 0x0a, 0x0a, 0x0c, 0x0a, 0x05, 0x06, 0x00, 0x02, 0x00, 0x01,
+    0x12, 0x03, 0x15, 0x06, 0x0e, 0x0a, 0x0c, 0x0a, 0x05, 0x06, 0x00, 0x02, 0x00, 0x02, 0x12, 0x03,
+    0x15, 0x10, 0x1c, 0x0a, 0x0c, 0x0a, 0x05, 0x06, 0x00, 0x02, 0x00, 0x03, 0x12, 0x03, 0x15, 0x27,
+    0x31, 0x0a, 0x3d, 0x0a, 0x02, 0x04, 0x00, 0x12, 0x04, 0x19, 0x00, 0x1b, 0x01, 0x1a, 0x31, 0x20,
+    0x54, 0x68, 0x65, 0x20, 0x72, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x20, 0x6d, 0x65, 0x73, 0x73,
+    0x61, 0x67, 0x65, 0x20, 0x63, 0x6f, 0x6e, 0x74, 0x61, 0x69, 0x6e, 0x69, 0x6e, 0x67, 0x20, 0x74,
+    0x68, 0x65, 0x20, 0x75, 0x73, 0x65, 0x72, 0x27, 0x73, 0x20, 0x6e, 0x61, 0x6d, 0x65, 0x2e, 0x0a,
+    0x0a, 0x0a, 0x0a, 0x03, 0x04, 0x00, 0x01, 0x12, 0x03, 0x19, 0x08, 0x14, 0x0a, 0x0b, 0x0a, 0x04,
+    0x04, 0x00, 0x02, 0x00, 0x12, 0x03, 0x1a, 0x02, 0x12, 0x0a, 0x0c, 0x0a, 0x05, 0x04, 0x00, 0x02,
+    0x00, 0x05, 0x12, 0x03, 0x1a, 0x02, 0x08, 0x0a, 0x0c, 0x0a, 0x05, 0x04, 0x00, 0x02, 0x00, 0x01,
+    0x12, 0x03, 0x1a, 0x09, 0x0d, 0x0a, 0x0c, 0x0a, 0x05, 0x04, 0x00, 0x02, 0x00, 0x03, 0x12, 0x03,
+    0x1a, 0x10, 0x11, 0x0a, 0x3b, 0x0a, 0x02, 0x04, 0x01, 0x12, 0x04, 0x1e, 0x00, 0x20, 0x01, 0x1a,
+    0x2f, 0x20, 0x54, 0x68, 0x65, 0x20, 0x72, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x20, 0x6d,
+    0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x20, 0x63, 0x6f, 0x6e, 0x74, 0x61, 0x69, 0x6e, 0x69, 0x6e,
+    0x67, 0x20, 0x74, 0x68, 0x65, 0x20, 0x67, 0x72, 0x65, 0x65, 0x74, 0x69, 0x6e, 0x67, 0x73, 0x0a,
+    0x0a, 0x0a, 0x0a, 0x03, 0x04, 0x01, 0x01, 0x12, 0x03, 0x1e, 0x08, 0x12, 0x0a, 0x0b, 0x0a, 0x04,
+    0x04, 0x01, 0x02, 0x00, 0x12, 0x03, 0x1f, 0x02, 0x15, 0x0a, 0x0c, 0x0a, 0x05, 0x04, 0x01, 0x02,
+    0x00, 0x05, 0x12, 0x03, 0x1f, 0x02, 0x08, 0x0a, 0x0c, 0x0a, 0x05, 0x04, 0x01, 0x02, 0x00, 0x01,
+    0x12, 0x03, 0x1f, 0x09, 0x10, 0x0a, 0x0c, 0x0a, 0x05, 0x04, 0x01, 0x02, 0x00, 0x03, 0x12, 0x03,
+    0x1f, 0x13, 0x14, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33,
+];
+include!("helloworld.tonic.rs");
+// @@protoc_insertion_point(module)