starpc 0.42.0 → 0.44.0

package/README.md

@@ -1,6 +1,7 @@
 # starpc
 
 [![npm](https://img.shields.io/npm/v/starpc?style=flat-square)](https://www.npmjs.com/package/starpc)
+[![crates.io](https://img.shields.io/crates/v/starpc.svg?style=flat-square)](https://crates.io/crates/starpc)
 [![Build status](https://img.shields.io/github/actions/workflow/status/aperturerobotics/starpc/tests.yml?style=flat-square&branch=master)](https://github.com/aperturerobotics/starpc/actions)
 [![GoDoc Widget]][GoDoc] [![Go Report Card Widget]][Go Report Card]
 
@@ -14,32 +15,43 @@
 ## Table of Contents
 
 - [Features](#features)
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Examples](#examples)
   - [Protobuf Definition](#protobuf)
   - [Go Implementation](#go)
   - [TypeScript Implementation](#typescript)
+  - [Rust Implementation](#rust)
 - [Debugging](#debugging)
 - [Development Setup](#development-setup)
 - [Support](#support)
 
 ## Features
 
-- Full [Proto3 services] support for TypeScript and Go
+- Full [Proto3 services] support for TypeScript, Go, and Rust
 - Bidirectional streaming in browsers via WebSocket or WebRTC
 - Built on libp2p streams with [@chainsafe/libp2p-yamux]
 - Efficient multiplexing of RPCs over single connections
 - Zero-reflection Go via [protobuf-go-lite]
 - Lightweight TypeScript via [protobuf-es-lite]
+- Async Rust via [prost] and [tokio]
 - Sub-stream support via [rpcstream]
 
 [Proto3 services]: https://developers.google.com/protocol-buffers/docs/proto3#services
 [@chainsafe/libp2p-yamux]: https://github.com/ChainSafe/js-libp2p-yamux
 [protobuf-go-lite]: https://github.com/aperturerobotics/protobuf-go-lite
 [protobuf-es-lite]: https://github.com/aperturerobotics/protobuf-es-lite
+[prost]: https://github.com/tokio-rs/prost
+[tokio]: https://github.com/tokio-rs/tokio
 [rpcstream]: ./rpcstream
 
+## Documentation
+
+- [Getting Started with TypeScript](./GET_STARTED_TYPESCRIPT.md)
+- [Getting Started with Go](./GET_STARTED_GO.md)
+- [Getting Started with Rust](./GET_STARTED_RUST.md)
+
 ## Installation
 
 ```bash
@@ -47,11 +59,10 @@
 git clone -b starpc https://github.com/aperturerobotics/protobuf-project
 cd protobuf-project
 
-# Install dependencies
+# Install dependencies (any of these work)
+bun install
 npm install
-yarn install
 pnpm install
-bun install
 
 # Generate TypeScript and Go code
 bun run gen
@@ -134,6 +145,84 @@ For TypeScript <-> TypeScript, see the [e2e] test.
 [e2e]: ./e2e/e2e.ts
 [integration]: ./integration/integration.ts
 
+### Rust
+
+Add the dependencies to your `Cargo.toml`:
+
+```toml
+[dependencies]
+starpc = "0.1"
+prost = "0.13"
+tokio = { version = "1", features = ["rt", "macros"] }
+
+[build-dependencies]
+starpc-build = "0.1"
+prost-build = "0.13"
+```
+
+Create a `build.rs` to generate code from your proto files:
+
+```rust
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    starpc_build::configure()
+        .compile_protos(&["proto/echo.proto"], &["proto"])?;
+    Ok(())
+}
+```
+
+Implement and use your service:
+
+```rust
+use starpc::{Client, Mux, Server, SrpcClient};
+use std::sync::Arc;
+
+// Include generated code
+mod proto {
+    include!(concat!(env!("OUT_DIR"), "/echo.rs"));
+}
+
+use proto::*;
+
+// Implement the server trait
+struct EchoServer;
+
+#[starpc::async_trait]
+impl EchoerServer for EchoServer {
+    async fn echo(&self, request: EchoMsg) -> starpc::Result<EchoMsg> {
+        Ok(request) // Echo back the message
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create server
+    let mux = Arc::new(Mux::new());
+    mux.register(Arc::new(EchoerHandler::new(EchoServer)))?;
+    let server = Server::with_arc(mux);
+
+    // Create an in-memory connection for demonstration
+    let (client_stream, server_stream) = tokio::io::duplex(64 * 1024);
+
+    // Spawn server handler
+    tokio::spawn(async move {
+        let _ = server.handle_stream(server_stream).await;
+    });
+
+    // Create client
+    let opener = starpc::client::transport::SingleStreamOpener::new(client_stream);
+    let client = SrpcClient::new(opener);
+    let echoer = EchoerClientImpl::new(client);
+
+    // Make RPC call
+    let response = echoer.echo(&EchoMsg { body: "Hello!".into() }).await?;
+    println!("Response: {}", response.body);
+
+    Ok(())
+}
+```
+
+See the [echo example](./echo/main.rs) for a complete working example.
+
 #### WebSocket Example
 
 Connect to a WebSocket server:
@@ -226,21 +315,8 @@ Uses [protobuf-es-lite] (fork of [protobuf-es]) for TypeScript.
 
 ### MacOS
 
-Install required packages:
-
-```bash
-brew install bash make coreutils gnu-sed findutils protobuf
-brew link --overwrite protobuf
-```
-
-Add to your shell rc file (.bashrc, .zshrc):
-
-```bash
-export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
-export PATH="/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH"
-export PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"
-export PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"
-```
+The `aptre` CLI handles all protobuf generation without requiring additional
+homebrew packages. Just run `bun run gen` after installing bun.
 
 ## Support
 

package/dist/echo/echo.pb.js

@@ -1,4 +1,4 @@
-// @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
+// @generated by protoc-gen-es-lite unknown with parameter "ts_nocheck=false,target=ts"
 // @generated from file github.com/aperturerobotics/starpc/echo/echo.proto (package echo, syntax proto3)
 /* eslint-disable */
 import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';

package/dist/mock/mock.pb.d.ts

@@ -1,4 +1,4 @@
-import type { MessageType } from "@aptre/protobuf-es-lite";
+import type { MessageType } from '@aptre/protobuf-es-lite';
 export declare const protobufPackage = "e2e.mock";
 /**
  * MockMsg is the mock message body.

package/dist/mock/mock.pb.js

@@ -1,14 +1,13 @@
-// @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
+// @generated by protoc-gen-es-lite unknown with parameter "ts_nocheck=false,target=ts"
 // @generated from file github.com/aperturerobotics/starpc/mock/mock.proto (package e2e.mock, syntax proto3)
 /* eslint-disable */
-import { createMessageType, ScalarType } from "@aptre/protobuf-es-lite";
-export const protobufPackage = "e2e.mock";
-;
+import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';
+export const protobufPackage = 'e2e.mock';
 // MockMsg contains the message type declaration for MockMsg.
 export const MockMsg = createMessageType({
-    typeName: "e2e.mock.MockMsg",
+    typeName: 'e2e.mock.MockMsg',
     fields: [
-        { no: 1, name: "body", kind: "scalar", T: ScalarType.STRING },
+        { no: 1, name: 'body', kind: 'scalar', T: ScalarType.STRING },
     ],
     packedByDefault: true,
 });

package/dist/mock/mock_srpc.pb.d.ts

@@ -1,6 +1,6 @@
-import { MockMsg } from "./mock.pb.js";
-import { MethodKind } from "@aptre/protobuf-es-lite";
-import { ProtoRpc } from "starpc";
+import { MockMsg } from './mock.pb.js';
+import { MethodKind } from '@aptre/protobuf-es-lite';
+import { ProtoRpc } from 'starpc';
 /**
  * Mock service mocks some RPCs for the e2e tests.
  *

package/dist/mock/mock_srpc.pb.js

@@ -1,15 +1,15 @@
 // @generated by protoc-gen-es-starpc none with parameter "target=ts,ts_nocheck=false"
 // @generated from file github.com/aperturerobotics/starpc/mock/mock.proto (package e2e.mock, syntax proto3)
 /* eslint-disable */
-import { MockMsg } from "./mock.pb.js";
-import { MethodKind } from "@aptre/protobuf-es-lite";
+import { MockMsg } from './mock.pb.js';
+import { MethodKind } from '@aptre/protobuf-es-lite';
 /**
  * Mock service mocks some RPCs for the e2e tests.
  *
  * @generated from service e2e.mock.Mock
  */
 export const MockDefinition = {
-    typeName: "e2e.mock.Mock",
+    typeName: 'e2e.mock.Mock',
     methods: {
         /**
          * MockRequest runs a mock unary request.
@@ -17,12 +17,12 @@ export const MockDefinition = {
          * @generated from rpc e2e.mock.Mock.MockRequest
          */
         MockRequest: {
-            name: "MockRequest",
+            name: 'MockRequest',
             I: MockMsg,
             O: MockMsg,
             kind: MethodKind.Unary,
         },
-    }
+    },
 };
 export const MockServiceName = MockDefinition.typeName;
 export class MockClient {

package/dist/rpcstream/rpcstream.pb.js

@@ -1,4 +1,4 @@
-// @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
+// @generated by protoc-gen-es-lite unknown with parameter "ts_nocheck=false,target=ts"
 // @generated from file github.com/aperturerobotics/starpc/rpcstream/rpcstream.proto (package rpcstream, syntax proto3)
 /* eslint-disable */
 import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';

package/dist/srpc/rpcproto.pb.js

@@ -1,4 +1,4 @@
-// @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
+// @generated by protoc-gen-es-lite unknown with parameter "ts_nocheck=false,target=ts"
 // @generated from file github.com/aperturerobotics/starpc/srpc/rpcproto.proto (package srpc, syntax proto3)
 /* eslint-disable */
 import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';

package/echo/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "echo-example"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish = false
+
+[[bin]]
+name = "echo-example"
+path = "main.rs"
+
+[dependencies]
+starpc = { workspace = true }
+prost = { workspace = true }
+tokio = { version = "1", features = ["full"] }
+async-trait = { workspace = true }
+
+[build-dependencies]
+starpc-build = { workspace = true }
+prost-build = { workspace = true }

package/echo/build.rs

@@ -0,0 +1,15 @@
+use std::io::Result;
+use std::path::PathBuf;
+
+fn main() -> Result<()> {
+    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    // Use simplified proto without rpcstream dependency
+    let proto_path = manifest_dir.join("echo_rust.proto");
+
+    println!("cargo:rerun-if-changed={}", proto_path.display());
+
+    starpc_build::configure()
+        .compile_protos(&[proto_path], &[&manifest_dir])?;
+
+    Ok(())
+}