gateway

README

rpcx-gateway

rpcx-gateway is a http gateway for rpcx services.

rpcx is a fast rpc framework. Faster, more features.

You can write rpc http clients in any programming languages such as Java、Python、C#、Node.js、Php、C\C++、Rust and others. See examples

Deployment models

There are two deployment modes: Gateway and Agent。

Gateway

You can deploy this as gateway model. Gateway is running at independent servers. Clients sends http requests to gateways, and gateways translate http requests into raw rpcx requests. And then gateways send raw rpcx requests to rpcx services.

when gateways receive rpcx responses, they translates rpcx responses into http responses and return clients.

You can scale gateway easily because it is stateless.

It works like a http load balancer.

Agent

You can also deploy this as agent model. Agents are deploy with clients. They are installed as a daemon application in node of clients. If there are multiple clients in one node, you only need to install one agent.

Clients send http requests to their local agent. The local agent translate http requests into rpcx requests, send rpcx requests to rpcx services, translate rpcx responses into http ressponses.

It works like service mesh.

Protocol

You can send a http request in any programming languages. You must set some extra http headers in requests.

• X-RPCX-Version: rpcx version
• X-RPCX-MesssageType: set 0 as request
• X-RPCX-Heartbeat: is heartbeat request or not, false in default.
• X-RPCX-Oneway: is one-way request or not, false in default.
• X-RPCX-SerializeType: 0 as raw bytes, 1 as JSON, 2 as protobuf, 3 as msgpack
• X-RPCX-MessageID: message ID, uint64 type
• X-RPCX-ServicePath: service path
• X-RPCX-ServiceMethod: service method
• X-RPCX-Meta: extra metadata

For the http response, there are some extra http headers:

• X-RPCX-Version: rpcx version
• X-RPCX-MesssageType: 1 as response
• X-RPCX-Heartbeat: is heartbeat response or not
• X-RPCX-MessageStatusType: Error or Normal. Error means there is call failure
• X-RPCX-SerializeType: 0 as raw bytes, 1 as JSON, 2 as protobuf, 3 as msgpack
• X-RPCX-MessageID: message ID, uint64 type
• X-RPCX-ServicePath: service path
• X-RPCX-ServiceMethod: service method
• X-RPCX-Meta: extra metadata
• X-RPCX-ErrorMessage: error message if X-RPCX-MessageStatusType is Error

Example

There is a golang http client example:

package main

import (
	"bytes"
	"io/ioutil"
	"log"
	"net/http"

	"github.com/rpcxio/rpcx-gateway"

	"github.com/smallnest/rpcx/codec"
)

type Args struct {
	A int
	B int
}

type Reply struct {
	C int
}

func main() {
	cc := &codec.MsgpackCodec{}

    // request 
	args := &Args{
		A: 10,
		B: 20,
	}
	data, _ := cc.Encode(args)

	req, err := http.NewRequest("POST", "http://127.0.0.1:9981/", bytes.NewReader(data))
	if err != nil {
		log.Fatal("failed to create request: ", err)
		return
    }
    
    // set extra headers
	h := req.Header
	h.Set(gateway.XSerializeType, "3")
	h.Set(gateway.XServicePath, "Arith")
	h.Set(gateway.XServiceMethod, "Mul")

    // send to gateway
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal("failed to call: ", err)
	}
	defer res.Body.Close()

	// handle http response
	replyData, err := ioutil.ReadAll(res.Body)
	if err != nil {
		log.Fatal("failed to read response: ", err)
	}

    // parse reply
	reply := &Reply{}
	err = cc.Decode(replyData, reply)
	if err != nil {
		log.Fatal("failed to decode reply: ", err)
	}

	log.Printf("%d * %d = %d", args.A, args.B, reply.C)
}

Documentation

Index

• Constants
• func HttpRequest2RpcxRequest(r *http.Request) (*protocol.Message, error)
• type Gateway
  • func NewGateway(base string, hs HTTPServer, sd client.ServiceDiscovery, ...) *Gateway
  • func (g *Gateway) Serve() error
• type HTTPServer
• type ServiceHandler

Constants

const (
	XVersion           = "X-RPCX-Version"
	XMessageType       = "X-RPCX-MesssageType"
	XHeartbeat         = "X-RPCX-Heartbeat"
	XOneway            = "X-RPCX-Oneway"
	XMessageStatusType = "X-RPCX-MessageStatusType"
	XSerializeType     = "X-RPCX-SerializeType"
	XMessageID         = "X-RPCX-MessageID"
	XServicePath       = "X-RPCX-ServicePath"
	XServiceMethod     = "X-RPCX-ServiceMethod"
	XMeta              = "X-RPCX-Meta"
	XErrorMessage      = "X-RPCX-ErrorMessage"
)

Functions

func HttpRequest2RpcxRequest

func HttpRequest2RpcxRequest(r *http.Request) (*protocol.Message, error)

Types

type Gateway

type Gateway struct {
	FailMode   client.FailMode
	SelectMode client.SelectMode
	Option     client.Option
	// contains filtered or unexported fields
}

Gateway is a rpcx gateway which can convert http invoke into rpcx invoke.

func NewGateway

func NewGateway(base string, hs HTTPServer, sd client.ServiceDiscovery, failMode client.FailMode, selectMode client.SelectMode, option client.Option) *Gateway

NewGateway returns a new gateway.

func (*Gateway) Serve

func (g *Gateway) Serve() error

Serve listens on the TCP network address addr and then calls Serve with handler to handle requests on incoming connections. Accepted connections are configured to enable TCP keep-alives.

type HTTPServer

type HTTPServer interface {
	RegisterHandler(base string, handler ServiceHandler)
	Serve() error
}

HTTPServer is a golang web interface。 You can use echo, gin, iris or other go web frameworks to implement it. You must wrap ServiceHandler into your handler of your selected web framework and add it into router.

type ServiceHandler

type ServiceHandler func(*http.Request, string) (map[string]string, []byte, error)

ServiceHandler converts http.Request into rpcx.Request and send it to rpcx service, and then converts the result and writes it into http.Response. You should get the http.Request and servicePath in your web handler.