starpc 0.35.4 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +59 -36
  2. package/dist/srpc/conn.d.ts +2 -2
  3. package/echo/echo_srpc.pb.go +13 -0
  4. package/go.mod +4 -4
  5. package/go.sum +4 -4
  6. package/mock/mock_srpc.pb.go +3 -0
  7. package/package.json +3 -3
package/README.md CHANGED
@@ -1,50 +1,63 @@
1
- # Stream RPC
1
+ # Stream RPC (starpc)
2
2
 
3
3
  [![GoDoc Widget]][GoDoc] [![Go Report Card Widget]][Go Report Card]
4
4
 
5
- > Protobuf 3 RPC services over any stream multiplexer.
5
+ > A high-performance Protobuf 3 RPC framework supporting bidirectional streaming over any multiplexer.
6
6
 
7
7
  [GoDoc]: https://godoc.org/github.com/aperturerobotics/starpc
8
8
  [GoDoc Widget]: https://godoc.org/github.com/aperturerobotics/starpc?status.svg
9
9
  [Go Report Card Widget]: https://goreportcard.com/badge/github.com/aperturerobotics/starpc
10
10
  [Go Report Card]: https://goreportcard.com/report/github.com/aperturerobotics/starpc
11
11
 
12
- ## Introduction
12
+ ## Table of Contents
13
13
 
14
- **starpc** implements [Proto3 services] (server & client) in both TypeScript and Go.
14
+ - [Features](#features)
15
+ - [Installation](#installation)
16
+ - [Quick Start](#quick-start)
17
+ - [Examples](#examples)
18
+ - [Protobuf Definition](#protobuf)
19
+ - [Go Implementation](#go)
20
+ - [TypeScript Implementation](#typescript)
21
+ - [Development Setup](#development-setup)
22
+ - [Support](#support)
15
23
 
16
- [Proto3 services]: https://developers.google.com/protocol-buffers/docs/proto3#services
17
-
18
- Supports **client-to-server and bidirectional streaming** in the web browser.
19
-
20
- [rpcproto.proto](./srpc/rpcproto.proto) contains the protocol definition.
21
-
22
- [rpcstream] supports sub-streams for per-component sub-services.
23
-
24
- [rpcstream]: ./rpcstream
24
+ ## Features
25
25
 
26
- The library leverages libp2p streams with `@chainsafe/libp2p-yamux` to
27
- coordinate balancing many ongoing RPCs over a single connection.
28
-
29
- starpc uses [protobuf-go-lite] to generate reflection-free Go code and [protobuf-es-lite] for TypeScript interfaces.
26
+ - Full [Proto3 services] implementation for both TypeScript and Go
27
+ - Bidirectional streaming support in web browsers
28
+ - Built on libp2p streams with `@chainsafe/libp2p-yamux`
29
+ - Efficient RPC multiplexing over single connections
30
+ - Zero-reflection Go code via [protobuf-go-lite]
31
+ - TypeScript interfaces via [protobuf-es-lite]
32
+ - Sub-streams support through [rpcstream]
30
33
 
34
+ [Proto3 services]: https://developers.google.com/protocol-buffers/docs/proto3#services
31
35
  [protobuf-go-lite]: https://github.com/aperturerobotics/protobuf-go-lite
32
36
  [protobuf-es-lite]: https://github.com/aperturerobotics/protobuf-es-lite
37
+ [rpcstream]: ./rpcstream
33
38
 
34
- ## Usage
39
+ ## Installation
35
40
 
36
- Start with the [protobuf-project] template repository on the "starpc" branch.
41
+ ```bash
42
+ # Clone the template project
43
+ git clone -b starpc https://github.com/aperturerobotics/protobuf-project
44
+ cd protobuf-project
37
45
 
38
- [protobuf-project]: https://github.com/aperturerobotics/protobuf-project/tree/starpc
46
+ # Install dependencies
47
+ yarn install
39
48
 
40
- Use "git add" to add your new .proto files, then `yarn gen` to generate the
41
- TypeScript and Go code.
49
+ # Generate TypeScript and Go code
50
+ yarn gen
51
+ ```
42
52
 
43
- ## Examples
53
+ ## Quick Start
44
54
 
45
- The demo/boilerplate project implements the Echo example below.
55
+ 1. Start with the [protobuf-project] template repository (starpc branch)
56
+ 2. Add your .proto files to the project
57
+ 3. Run `yarn gen` to generate TypeScript and Go code
58
+ 4. Implement your services using the examples below
46
59
 
47
- This repository uses protowrap, see the [Makefile](./Makefile).
60
+ [protobuf-project]: https://github.com/aperturerobotics/protobuf-project/tree/starpc
48
61
 
49
62
  ### Protobuf
50
63
 
@@ -128,7 +141,7 @@ This examples demonstrates connecting to a WebSocket server:
128
141
  import { WebSocketConn } from 'srpc'
129
142
  import { EchoerClient } from 'srpc/echo'
130
143
 
131
- const ws = new WebSocket('ws://localhost:5000/demo')
144
+ const ws = new WebSocket('ws://localhost:1347/demo')
132
145
  const channel = new WebSocketConn(ws)
133
146
  const client = channel.buildClient()
134
147
  const demoServiceClient = new EchoerClient(client)
@@ -207,31 +220,41 @@ Uses [protobuf-es-lite] (fork of [protobuf-es]) to generate TypeScript Protobuf
207
220
 
208
221
  `protoc-gen-es-starpc` is a heavily modified version of `protoc-gen-connect-es`.
209
222
 
210
- ## Developing on MacOS
223
+ ## Development Setup
211
224
 
212
- On MacOS, some homebrew packages are required for `yarn gen`:
225
+ ### MacOS Requirements
213
226
 
214
- ```
227
+ 1. Install required packages:
228
+ ```bash
215
229
  brew install bash make coreutils gnu-sed findutils protobuf
216
230
  brew link --overwrite protobuf
217
231
  ```
218
232
 
219
- Add to your .bashrc or .zshrc:
220
-
221
- ```
233
+ 2. Add to your .bashrc or .zshrc:
234
+ ```bash
222
235
  export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
223
236
  export PATH="/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH"
224
237
  export PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"
225
238
  export PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"
226
239
  ```
227
240
 
228
- ## Support
241
+ ## Attribution
229
242
 
230
- Please file a [GitHub issue] and/or [Join Discord] with any questions.
243
+ - `protoc-gen-go-starpc`: Modified version of `protoc-gen-go-drpc`
244
+ - `protoc-gen-es-starpc`: Modified version of `protoc-gen-connect-es`
245
+ - Uses [vtprotobuf] for Go Protobuf marshaling
246
+ - Uses [protobuf-es-lite] for TypeScript Protobuf interfaces
231
247
 
232
- [GitHub issue]: https://github.com/aperturerobotics/starpc/issues/new
248
+ [vtprotobuf]: https://github.com/planetscale/vtprotobuf
249
+
250
+ ## Support
233
251
 
234
- ... or feel free to reach out on [Matrix Chat].
252
+ Need help? We're here:
235
253
 
254
+ - [File a GitHub Issue][GitHub issue]
255
+ - [Join our Discord][Join Discord]
256
+ - [Matrix Chat][Matrix Chat]
257
+
258
+ [GitHub issue]: https://github.com/aperturerobotics/starpc/issues/new
236
259
  [Join Discord]: https://discord.gg/KJutMESRsT
237
260
  [Matrix Chat]: https://matrix.to/#/#aperturerobotics:matrix.org
package/dist/srpc/conn.d.ts CHANGED
@@ -16,8 +16,8 @@ export declare class StreamConn implements Duplex<AsyncGenerator<Uint8Array | Ui
16
16
  private _muxer;
17
17
  private _server?;
18
18
  constructor(server?: StreamHandler, connParams?: StreamConnParams);
19
- get sink(): import("it-stream-types").Sink<AsyncGenerator<Uint8Array | Uint8ArrayList, any, any>, unknown>;
20
- get source(): AsyncGenerator<Uint8Array | Uint8ArrayList, any, any>;
19
+ get sink(): import("it-stream-types").Sink<AsyncGenerator<Uint8Array<ArrayBufferLike> | Uint8ArrayList, any, any>, unknown>;
20
+ get source(): AsyncGenerator<Uint8Array<ArrayBufferLike> | Uint8ArrayList, any, any>;
21
21
  get streams(): Stream[];
22
22
  get muxer(): StreamMuxer;
23
23
  get server(): StreamHandler | undefined;
package/echo/echo_srpc.pb.go CHANGED
@@ -13,13 +13,20 @@ import (
13
13
  )
14
14
 
15
15
  type SRPCEchoerClient interface {
16
+ // SRPCClient returns the underlying SRPC client.
16
17
  SRPCClient() srpc.Client
17
18
 
19
+ // Echo returns the given message.
18
20
  Echo(ctx context.Context, in *EchoMsg) (*EchoMsg, error)
21
+ // EchoServerStream is an example of a server -> client one-way stream.
19
22
  EchoServerStream(ctx context.Context, in *EchoMsg) (SRPCEchoer_EchoServerStreamClient, error)
23
+ // EchoClientStream is an example of client->server one-way stream.
20
24
  EchoClientStream(ctx context.Context) (SRPCEchoer_EchoClientStreamClient, error)
25
+ // EchoBidiStream is an example of a two-way stream.
21
26
  EchoBidiStream(ctx context.Context) (SRPCEchoer_EchoBidiStreamClient, error)
27
+ // RpcStream opens a nested rpc call stream.
22
28
  RpcStream(ctx context.Context) (SRPCEchoer_RpcStreamClient, error)
29
+ // DoNothing does nothing.
23
30
  DoNothing(ctx context.Context, in *emptypb.Empty) (*emptypb.Empty, error)
24
31
  }
25
32
 
@@ -216,11 +223,17 @@ func (c *srpcEchoerClient) DoNothing(ctx context.Context, in *emptypb.Empty) (*e
216
223
  }
217
224
 
218
225
  type SRPCEchoerServer interface {
226
+ // Echo returns the given message.
219
227
  Echo(context.Context, *EchoMsg) (*EchoMsg, error)
228
+ // EchoServerStream is an example of a server -> client one-way stream.
220
229
  EchoServerStream(*EchoMsg, SRPCEchoer_EchoServerStreamStream) error
230
+ // EchoClientStream is an example of client->server one-way stream.
221
231
  EchoClientStream(SRPCEchoer_EchoClientStreamStream) (*EchoMsg, error)
232
+ // EchoBidiStream is an example of a two-way stream.
222
233
  EchoBidiStream(SRPCEchoer_EchoBidiStreamStream) error
234
+ // RpcStream opens a nested rpc call stream.
223
235
  RpcStream(SRPCEchoer_RpcStreamStream) error
236
+ // DoNothing does nothing.
224
237
  DoNothing(context.Context, *emptypb.Empty) (*emptypb.Empty, error)
225
238
  }
226
239
 
package/go.mod CHANGED
@@ -2,7 +2,7 @@ module github.com/aperturerobotics/starpc
2
2
 
3
3
  go 1.23
4
4
 
5
- toolchain go1.23.3
5
+ toolchain go1.23.4
6
6
 
7
7
  replace (
8
8
  // This fork uses go-protobuf-lite and adds post-quantum crypto support.
@@ -14,12 +14,12 @@ replace (
14
14
 
15
15
  require (
16
16
  github.com/aperturerobotics/protobuf-go-lite v0.8.0 // latest
17
- github.com/aperturerobotics/util v1.26.2 // latest
17
+ github.com/aperturerobotics/util v1.26.3 // latest
18
18
  )
19
19
 
20
20
  require (
21
21
  github.com/coder/websocket v1.8.12 // latest
22
- github.com/libp2p/go-libp2p v0.37.0 // latest
22
+ github.com/libp2p/go-libp2p v0.37.2 // latest
23
23
  github.com/libp2p/go-yamux/v4 v4.0.2-0.20240826150533-e92055b23e0e // master
24
24
  github.com/pkg/errors v0.9.1 // latest
25
25
  github.com/sirupsen/logrus v1.9.3 // latest
@@ -42,7 +42,7 @@ require (
42
42
  github.com/multiformats/go-varint v0.0.7 // indirect
43
43
  github.com/spaolacci/murmur3 v1.1.0 // indirect
44
44
  golang.org/x/crypto v0.29.0 // indirect
45
- golang.org/x/exp v0.0.0-20241009180824-f66d83c29e7c // indirect
45
+ golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f // indirect
46
46
  golang.org/x/sys v0.27.0 // indirect
47
47
  lukechampine.com/blake3 v1.3.0 // indirect
48
48
  )
package/go.sum CHANGED
@@ -4,8 +4,8 @@ github.com/aperturerobotics/json-iterator-lite v1.0.0 h1:cihbrYWoK/S2RYXhJLpDZd+
4
4
  github.com/aperturerobotics/json-iterator-lite v1.0.0/go.mod h1:snaApCEDtrHHP6UWSLKiYNOZU9A5NyzccKenx9oZEzg=
5
5
  github.com/aperturerobotics/protobuf-go-lite v0.8.0 h1:SoiTAVArmOrNTX31e6CC5Bem6HuOElg3YYNhp4AAPQc=
6
6
  github.com/aperturerobotics/protobuf-go-lite v0.8.0/go.mod h1:y49wVEezRHg78uQ2OzLLZbtTTWuox+ChmaTuh6FLJW8=
7
- github.com/aperturerobotics/util v1.26.2 h1:PrBgJ3ydAwSD59o7s5zRfL+mbphIC6xo2Inor7/K+ok=
8
- github.com/aperturerobotics/util v1.26.2/go.mod h1:jp9+cf8cTlX5Jf0F9RlXmKtEw0yXC6gU92V9lXoZ74M=
7
+ github.com/aperturerobotics/util v1.26.3 h1:Z7pjEJX27FDUQyP8OHlBcyEc8MGl8z/ZS1vpRBsIU9E=
8
+ github.com/aperturerobotics/util v1.26.3/go.mod h1:D/N1pG02cPukZtwGggCeb8R/wq11Iy76xjSEGFYa06c=
9
9
  github.com/coder/websocket v1.8.12 h1:5bUXkEPPIbewrnkU8LTCLVaxi4N4J8ahufH2vlo4NAo=
10
10
  github.com/coder/websocket v1.8.12/go.mod h1:LNVeNrXQZfe5qhS9ALED3uA+l5pPqvwXg3CKoDBB2gs=
11
11
  github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -55,8 +55,8 @@ github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsT
55
55
  github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
56
56
  golang.org/x/crypto v0.29.0 h1:L5SG1JTTXupVV3n6sUqMTeWbjAyfPwoda2DLX8J8FrQ=
57
57
  golang.org/x/crypto v0.29.0/go.mod h1:+F4F4N5hv6v38hfeYwTdx20oUvLLc+QfrE9Ax9HtgRg=
58
- golang.org/x/exp v0.0.0-20241009180824-f66d83c29e7c h1:7dEasQXItcW1xKJ2+gg5VOiBnqWrJc+rq0DPKyvvdbY=
59
- golang.org/x/exp v0.0.0-20241009180824-f66d83c29e7c/go.mod h1:NQtJDoLvd6faHhE7m4T/1IY708gDefGGjR/iUW8yQQ8=
58
+ golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f h1:XdNn9LlyWAhLVp6P/i8QYBW+hlyhrhei9uErw2B5GJo=
59
+ golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f/go.mod h1:D5SMRVC3C2/4+F/DB1wZsLRnSNimn2Sp/NPsCrsv8ak=
60
60
  golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
61
61
  golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
62
62
  golang.org/x/sys v0.27.0 h1:wBqf8DvsY9Y/2P8gAfPDEYNuS30J4lPHJxXSb/nJZ+s=
package/mock/mock_srpc.pb.go CHANGED
@@ -11,8 +11,10 @@ import (
11
11
  )
12
12
 
13
13
  type SRPCMockClient interface {
14
+ // SRPCClient returns the underlying SRPC client.
14
15
  SRPCClient() srpc.Client
15
16
 
17
+ // MockRequest runs a mock unary request.
16
18
  MockRequest(ctx context.Context, in *MockMsg) (*MockMsg, error)
17
19
  }
18
20
 
@@ -44,6 +46,7 @@ func (c *srpcMockClient) MockRequest(ctx context.Context, in *MockMsg) (*MockMsg
44
46
  }
45
47
 
46
48
  type SRPCMockServer interface {
49
+ // MockRequest runs a mock unary request.
47
50
  MockRequest(context.Context, *MockMsg) (*MockMsg, error)
48
51
  }
49
52
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "starpc",
3
- "version": "0.35.4",
3
+ "version": "0.36.0",
4
4
  "description": "Streaming protobuf RPC service protocol over any two-way channel.",
5
5
  "license": "MIT",
6
6
  "author": {
@@ -21,9 +21,9 @@
21
21
  "type": "module",
22
22
  "exports": {
23
23
  ".": {
24
+ "types": "./dist/index.d.ts",
24
25
  "import": "./dist/index.js",
25
- "require": "./dist/index.js",
26
- "types": "./dist/index.d.ts"
26
+ "require": "./dist/index.js"
27
27
  }
28
28
  },
29
29
  "files": [