0.35.2 • Published 9 months ago

starpc v0.35.2

Weekly downloads
-
License
MIT
Repository
github
Last release
9 months ago

Stream RPC

GoDoc Widget Go Report Card Widget

Protobuf 3 RPC services over any stream multiplexer.

Introduction

starpc implements Proto3 services (server & client) in both TypeScript and Go.

Supports client-to-server and bidirectional streaming in the web browser.

rpcproto.proto contains the protocol definition.

rpcstream supports sub-streams for per-component sub-services.

The library leverages libp2p streams with @chainsafe/libp2p-yamux to coordinate balancing many ongoing RPCs over a single connection.

starpc uses protobuf-go-lite to generate reflection-free Go code and protobuf-es-lite for TypeScript interfaces.

Usage

Start with the protobuf-project template repository on the "starpc" branch.

Use "git add" to add your new .proto files, then yarn gen to generate the TypeScript and Go code.

Examples

The demo/boilerplate project implements the Echo example below.

This repository uses protowrap, see the Makefile.

Protobuf

The following examples use the echo protobuf sample.

syntax = "proto3";
package echo;

// Echoer service returns the given message.
service Echoer {
  // Echo returns the given message.
  rpc Echo(EchoMsg) returns (EchoMsg);
  // EchoServerStream is an example of a server -> client one-way stream.
  rpc EchoServerStream(EchoMsg) returns (stream EchoMsg);
  // EchoClientStream is an example of client->server one-way stream.
  rpc EchoClientStream(stream EchoMsg) returns (EchoMsg);
  // EchoBidiStream is an example of a two-way stream.
  rpc EchoBidiStream(stream EchoMsg) returns (stream EchoMsg);
}

// EchoMsg is the message body for Echo.
message EchoMsg {
  string body = 1;
}

Go

This example demonstrates both the server and client:

// construct the server
echoServer := &echo.EchoServer{}
mux := srpc.NewMux()
if err := echo.SRPCRegisterEchoer(mux, echoServer); err != nil {
	t.Fatal(err.Error())
}
server := srpc.NewServer(mux)

// create an in-memory connection to the server
openStream := srpc.NewServerPipe(server)

// construct the client
client := srpc.NewClient(openStream)

// construct the client rpc interface
clientEcho := echo.NewSRPCEchoerClient(client)
ctx := context.Background()
bodyTxt := "hello world"
out, err := clientEcho.Echo(ctx, &echo.EchoMsg{
	Body: bodyTxt,
})
if err != nil {
	t.Fatal(err.Error())
}
if out.GetBody() != bodyTxt {
	t.Fatalf("expected %q got %q", bodyTxt, out.GetBody())
}

TypeScript

See the ts-proto README to generate the TypeScript for your protobufs.

For an example of Go <-> TypeScript interop, see the integration test. For an example of TypeScript <-> TypeScript interop, see the e2e test.

Supports any AsyncIterable communication channel.

WebSocket Example

This examples demonstrates connecting to a WebSocket server:

import { WebSocketConn } from 'srpc'
import { EchoerClient } from 'srpc/echo'

const ws = new WebSocket('ws://localhost:5000/demo')
const channel = new WebSocketConn(ws)
const client = channel.buildClient()
const demoServiceClient = new EchoerClient(client)

const result = await demoServiceClient.Echo({
  body: "Hello world!"
})
console.log('output', result.body)

In-memory Demo with TypeScript Server and Client

This example demonstrates both the server and client with an in-memory pipe:

import { pipe } from 'it-pipe'
import { createHandler, createMux, Server, Client, Conn } from 'srpc'
import { EchoerDefinition, EchoerServer, runClientTest } from 'srpc/echo'
import { pushable } from 'it-pushable'

// Create the server and register the handlers.
const mux = createMux()
const echoer = new EchoerServer()
mux.register(createHandler(EchoerDefinition, echoer))
const server = new Server(mux.lookupMethodFunc)

// Create the client connection to the server with an in-memory pipe.
const clientConn = new Conn()
const serverConn = new Conn(server)
pipe(clientConn, serverConn, clientConn)
const client = new Client(clientConn.buildOpenStreamFunc())

// Examples of different types of RPC calls:

// One-shot request/response (unary):
console.log('Calling Echo: unary call...')
let result = await demoServiceClient.Echo({
  body: 'Hello world!',
})
console.log('success: output', result.body)

// Streaming from client->server with a single server response:
const clientRequestStream = pushable<EchoMsg>({objectMode: true})
clientRequestStream.push({body: 'Hello world from streaming request.'})
clientRequestStream.end()
console.log('Calling EchoClientStream: client -> server...')
result = await demoServiceClient.EchoClientStream(clientRequestStream)
console.log('success: output', result.body)

// Streaming from server -> client with a single client message.
console.log('Calling EchoServerStream: server -> client...')
const serverStream = demoServiceClient.EchoServerStream({
  body: 'Hello world from server to client streaming request.',
})
for await (const msg of serverStream) {
  console.log('server: output', msg.body)
}

Attribution

protoc-gen-go-starpc is a heavily modified version of protoc-gen-go-drpc.

Be sure to check out drpc as well: it's compatible with grpc, twirp, and more.

Uses vtprotobuf to generate Go Protobuf marshal / unmarshal code.

Uses protobuf-es-lite (fork of protobuf-es) to generate TypeScript Protobuf marshal / unmarshal code.

protoc-gen-es-starpc is a heavily modified version of protoc-gen-connect-es.

Developing on MacOS

On MacOS, some homebrew packages are required for yarn gen:

brew install bash make coreutils gnu-sed findutils protobuf
brew link --overwrite protobuf

Add to your .bashrc or .zshrc:

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"

Support

Please file a GitHub issue and/or Join Discord with any questions.

... or feel free to reach out on Matrix Chat.

0.35.2

9 months ago

0.33.11

11 months ago

0.34.0

10 months ago

0.35.1

9 months ago

0.35.0

10 months ago

0.33.10

11 months ago

0.33.7

12 months ago

0.33.6

1 year ago

0.33.5

1 year ago

0.33.4

1 year ago

0.33.3

1 year ago

0.33.1

1 year ago

0.33.0

1 year ago

0.33.9

12 months ago

0.33.8

12 months ago

0.32.18

1 year ago

0.32.17

1 year ago

0.32.16

1 year ago

0.32.15

1 year ago

0.32.14

1 year ago

0.32.13

1 year ago

0.32.12

1 year ago

0.32.11

1 year ago

0.32.9

1 year ago

0.32.10

1 year ago

0.32.8

1 year ago

0.32.7

1 year ago

0.32.6

1 year ago

0.32.4

1 year ago

0.32.3

1 year ago

0.31.14

1 year ago

0.32.2

1 year ago

0.32.1

1 year ago

0.32.0

1 year ago

0.31.12

1 year ago

0.31.13

1 year ago

0.31.10

1 year ago

0.31.11

1 year ago

0.31.9

1 year ago

0.31.8

1 year ago

0.31.7

1 year ago

0.31.6

1 year ago

0.31.5

1 year ago

0.30.1

1 year ago

0.31.4

1 year ago

0.31.3

1 year ago

0.31.2

1 year ago

0.31.1

1 year ago

0.31.0

1 year ago

0.30.0

1 year ago

0.29.0

1 year ago

0.29.1

1 year ago

0.28.1

1 year ago

0.28.0

1 year ago

0.27.3

1 year ago

0.27.2

1 year ago

0.27.1

1 year ago

0.26.2

1 year ago

0.27.0

1 year ago

0.26.1

1 year ago

0.26.0

1 year ago

0.25.5

1 year ago

0.25.4

1 year ago

0.25.3

1 year ago

0.25.2

1 year ago

0.25.1

1 year ago

0.25.0

1 year ago

0.24.1

1 year ago

0.24.0

1 year ago

0.23.2

1 year ago

0.23.1

1 year ago

0.23.0

1 year ago

0.22.8

1 year ago

0.22.7

2 years ago

0.22.6

2 years ago

0.22.5

2 years ago

0.22.4

2 years ago

0.22.3

2 years ago

0.22.2

2 years ago

0.22.1

2 years ago

0.22.0

2 years ago

0.21.6

2 years ago

0.21.5

2 years ago

0.21.4

2 years ago

0.21.3

2 years ago

0.21.2

2 years ago

0.21.1

2 years ago

0.21.0

2 years ago

0.20.1

2 years ago

0.20.0

2 years ago

0.19.2

2 years ago

0.19.3

2 years ago

0.19.0

2 years ago

0.19.1

2 years ago

0.17.0

3 years ago

0.17.1

3 years ago

0.18.1

2 years ago

0.18.2

2 years ago

0.18.3

2 years ago

0.18.0

2 years ago

0.15.4

3 years ago

0.11.0

3 years ago

0.13.0

3 years ago

0.11.2

3 years ago

0.13.1

3 years ago

0.11.3

3 years ago

0.15.0

3 years ago

0.13.2

3 years ago

0.15.1

3 years ago

0.13.3

3 years ago

0.15.2

3 years ago

0.15.3

3 years ago

0.10.9

3 years ago

0.12.0

3 years ago

0.12.1

3 years ago

0.14.0

3 years ago

0.12.2

3 years ago

0.14.1

3 years ago

0.12.3

3 years ago

0.16.0

3 years ago

0.16.1

3 years ago

0.10.7

3 years ago

0.10.8

3 years ago

0.10.1

3 years ago

0.10.2

3 years ago

0.10.3

3 years ago

0.10.4

3 years ago

0.10.5

3 years ago

0.10.6

3 years ago

0.10.0

3 years ago

0.9.2

3 years ago

0.9.1

3 years ago

0.9.0

3 years ago

0.8.6

3 years ago

0.8.5

3 years ago

0.8.4

3 years ago

0.8.3

3 years ago

0.8.2

3 years ago

0.8.1

3 years ago

0.8.0

3 years ago

0.7.1

3 years ago

0.7.0

3 years ago

0.6.2

3 years ago

0.6.1

3 years ago

0.6.0

3 years ago

0.5.2

3 years ago

0.5.1

3 years ago

0.5.0

3 years ago

0.4.9

3 years ago

0.4.8

3 years ago

0.4.7

3 years ago

0.4.6

3 years ago

0.4.5

3 years ago

0.4.3

3 years ago

0.4.2

3 years ago

0.4.1

3 years ago

0.4.0

3 years ago

0.3.6

3 years ago

0.3.5

3 years ago

0.3.4

3 years ago

0.3.3

3 years ago

0.3.2

3 years ago

0.3.1

3 years ago

0.3.0

3 years ago

0.2.2

3 years ago

0.2.1

3 years ago

0.2.0

3 years ago

0.1.9

3 years ago

0.1.8

3 years ago

0.1.7

3 years ago

0.1.6

3 years ago

0.1.5

3 years ago

0.1.4

3 years ago

0.1.3

3 years ago

0.1.2

3 years ago

0.1.1

3 years ago

0.1.0

3 years ago

0.0.1

3 years ago