multiplexer

README

gRPC Multiplexer

gRPC Multiplexer is a proxy to allow communication with one or multiple gRPC servers that can be behind a NAT router. All these gRPC servers are reachable through a unique endpoint from the Multiplexer Server.

The whole implementation is done in Golang programming language (v1.18+). It's mainly based on gRPC-Go, Yamux and gRPC Proxy.

How does it work

Architecture

gRPC Multiplexer is decoupled into two different programs.

gRPC Multiplexer Server

The Multiplexer Server allows end-users to access to the different connected gRPC servers.

There are two endpoints on the Server:

• The proxy endpoint that allows access to the connected client.
• The multiplexer endpoint for Multiplexer Clients to connect and create tunnels to the Multiplexer Server.

gRPC Multiplexer Client

The Multiplexer Client is a bridge between the Multiplexer Server and a gRPC Server. It redirects all gRPC requests from the multiplexer to the gRPC Server.

To identify the client, a Client ID can be specified (or generated automatically if not).

The proxy endpoint

The proxy endpoint allows access to:

• Each connected gRPC server (through the Multiplexer Client). The gRPC API is the same as the destination gRPC Server. Only a gRPC metadata client-id should be specified with the ID of the Multiplexer Client to specify the server to send the request to.
• The Discovery gRPC API that allows user to list the connected gRPC servers.

Installation

Download the latest release for your architecture. It contains both server & client programs that can be run without any dependency to install.

Usage

Start the multiplexer server with listener specification for both multiplexer and proxy endpoints:

# Suppose the IP hosting the multiplexer server if 1.2.3.4
./grpc-multiplexer-server --multiplexer-listener 0.0.0.0:12345 --proxy-listener 0.0.0.0:1234

Connect a multiplexer client to the multiplexer with ID rainbow:

# Suppose the destination gRPC server is located on localhost, port 4444 
./grpc-multiplexer-client --client-id rainbow --multiplexer-address 1.2.3.4:12345 --grpc-server-address localhost:4444

For both application, use --help to have more information on their usage.

You can also configure the same options in a YAML file located:

• In your Home folder: $HOME/.grpc-multiplexer-server and $HOME/.grpc-multiplexer-server.
• Globally on the system: /etc/grpc-multiplexer/grpc-multiplexer-server.yaml and /etc/grpc-multiplexer/grpc-multiplexer-client.yaml
• Specifying the config location using --config CLI flag.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Generate protobuf code

Use buf.build to generate code :

buf generate

The generated code should be part of your pull request.

License

MIT

Documentation

Index

• Constants
• func NewClient(clientID string, gRPCServerAddr string, multiplexerAddr string) *client
• func NewServer(proxyLis net.Listener, multiplexerLis net.Listener) *server

Constants

const ClientIDMDKeyName = "client-id"

Functions

func NewClient

func NewClient(clientID string, gRPCServerAddr string, multiplexerAddr string) *client

func NewServer

func NewServer(proxyLis net.Listener, multiplexerLis net.Listener) *server