wsrpc

README

wsrpc

A protoc plugin to generate Go server and Javascript client Protocol Buffer files to be used for service calls across WebSockets rather than gRPC. (See jnordberg/wsrpc for a pure Javascript solution.)

The first release will generate a TypeScript client to avoid the need for type validations in libraries like dcodeIO/protobuf.js. Which flavor of Javascript client to generate will be implemented as a secondary plugin per the Plugin interface in the protoc-gen-go generator.

For project status, see the issues and milestones.

Documentation

Overview

https://www.jonathan-petitcolas.com/2015/01/27/playing-with-websockets-in-go.html https://github.com/gorilla/websocket/tree/master/examples

• Copyright 2014 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.

Package wsrpc is a naive WebSocket variant of gRPC.

Index

• Constants
• Variables
• type Client
• type Config
• type MethodInfo
• type MethodMap
• type Request
• type RequestHandler
• type Server
  • func NewServer(c Config) *Server
  • func (s *Server) Broadcast(res []byte)
  • func (s *Server) GetServiceInfo() map[string]ServiceInfo
  • func (s *Server) Handle() func(w http.ResponseWriter, r *http.Request)
  • func (s *Server) RegisterService(sd *ServiceDescriptor, implementation interface{})
• type ServiceDescriptor
• type ServiceInfo
• type ServiceMap

Constants

const (
	Accept   = prefix + "Accept"
	Key      = prefix + "Key"
	Protocol = prefix + "Protocol"
	Version  = prefix + "Version"
)

Variables

var (
	// ErrServerStopped indicates that the operation is now illegal because of
	// the server being stopped.
	ErrServerStopped = errors.New("wsrpc: the server has been stopped")
)

Types

type Client

type Client struct {

	// Buffered channel of outbound messages to be picked up by the writePump.
	Send chan []byte

	Token *oauth2.Token
	// contains filtered or unexported fields
}

Client represents a connected browser.

type Config

type Config struct {
}

type MethodInfo

type MethodInfo struct {
	Name           string
	IsClientStream bool
	IsServerStream bool
}

MethodInfo describes an RPC endpoint.

type MethodMap

type MethodMap struct {
	Name    string
	Handler methodHandler
}

MethodMap maps a fully qualified method name to its handler.

type Request

type Request struct {
	Client     *Client
	ReceivedAt time.Time
	RawMessage []byte
	WireLength int
	Message    interface{} // decoded proto message
}

Request from browser as bytes along with WebSocket client the browser communicated through.

type RequestHandler

type RequestHandler func(req *Request) []byte

RequestHandler processes a socket request and returns a response that should be sent to the client or nil if no response is expected.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is a WebSocket server for RPC requests. The gRPC server assigns the codec per client connection but this implementation always uses protobuf so it can be defined at the server level.

func NewServer

func NewServer(c Config) *Server

NewServer creates a websocket server which has no service registered and is not yet accepting requests.

func (*Server) Broadcast

func (s *Server) Broadcast(res []byte)

Broadcast puts a message onto the broadcast channel to be sent to all connected clients.

func (*Server) GetServiceInfo

func (s *Server) GetServiceInfo() map[string]ServiceInfo

GetServiceInfo returns a map from service names to ServiceInfo. Service names include the package names, in the form of <package>.<service>.

func (*Server) Handle

func (s *Server) Handle() func(w http.ResponseWriter, r *http.Request)

Handle incoming WebSocket requests. Create a client object for each connection with a read and write event loop.

func (*Server) RegisterService

func (s *Server) RegisterService(sd *ServiceDescriptor, implementation interface{})

RegisterService registers a service and its implementation to the WebSocket server. It is called from generated code. All services should be registered before the server begins handling requests.

type ServiceDescriptor

type ServiceDescriptor struct {
	Name string
	// Pointer to the service interface used to check whether the user
	// provided implementation satisfies the interface requirements.
	Type    interface{}
	Methods []MethodMap
	About   interface{}
}

ServiceDescriptor describes an RPC service specification.

type ServiceInfo

type ServiceInfo struct {
	Methods []MethodInfo
	About   interface{} // metadata specified in ServiceDescriptor when registering service.
}

ServiceInfo lists all methods available for all services on the server.

type ServiceMap

type ServiceMap struct {
	// contains filtered or unexported fields
}

ServiceMap matches a service implementation to its methods.