httpgrpc

README

httpgrpc

Golang Microservice API to convert external HTTP endpoints on a proxy to internally exposed GRPC messages. Allows a generic proxy to talk to services via a standard message while still allowing each service to maintain its API using GRPC and protocol buffers.

There are multiple implemenations that follow this basic intent already (HTTP+JSON reverse proxied to GRPC) but assume your service is directly handling external HTTP traffic, rather than sitting behind load-balanced webservers in a DMZ somewhere separate to your nice safe application server. For example, here and here.

This differs, in that your application is only expected to be handling GRPC. The logic used by the reverse proxy to determine where to send the message is up to you, this library simply sets the standard for what must be passed on - an HTTP method, a procedure name and the JSON payload. Your service must provide a procedure with a name that matches the format MethodnameProcedureName, such as PostLogin or GetUserPhoto.

Installation

go get "github.com/LLKennedy/httpgrpc"

Basic Usage

TODO

Testing

On windows, the simplest way to test is to use the powershell script.

./test.ps1

To emulate the testing which occurs in build pipelines for linux and mac, run the following:

go test ./... -race

Documentation

Index

• Variables
• func RegisterExposedServiceServer(s *grpc.Server, srv ExposedServiceServer)
• type ExposedServiceClient
  • func NewExposedServiceClient(cc *grpc.ClientConn) ExposedServiceClient
• type ExposedServiceServer
• type Method
  • func (Method) EnumDescriptor() ([]byte, []int)
  • func (x Method) String() string
• type QueryParam
  • func (*QueryParam) Descriptor() ([]byte, []int)
  • func (m *QueryParam) GetKey() string
  • func (m *QueryParam) GetValue() string
  • func (*QueryParam) ProtoMessage()
  • func (m *QueryParam) Reset()
  • func (m *QueryParam) String() string
  • func (m *QueryParam) XXX_DiscardUnknown()
  • func (m *QueryParam) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
  • func (m *QueryParam) XXX_Merge(src proto.Message)
  • func (m *QueryParam) XXX_Size() int
  • func (m *QueryParam) XXX_Unmarshal(b []byte) error
• type Request
  • func (*Request) Descriptor() ([]byte, []int)
  • func (m *Request) GetMethod() Method
  • func (m *Request) GetParams() []*QueryParam
  • func (m *Request) GetPayload() []byte
  • func (m *Request) GetProcedure() string
  • func (*Request) ProtoMessage()
  • func (m *Request) Reset()
  • func (m *Request) String() string
  • func (m *Request) XXX_DiscardUnknown()
  • func (m *Request) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
  • func (m *Request) XXX_Merge(src proto.Message)
  • func (m *Request) XXX_Size() int
  • func (m *Request) XXX_Unmarshal(b []byte) error
• type Response
  • func (*Response) Descriptor() ([]byte, []int)
  • func (m *Response) GetPayload() []byte
  • func (m *Response) GetStatusCode() uint32
  • func (*Response) ProtoMessage()
  • func (m *Response) Reset()
  • func (m *Response) String() string
  • func (m *Response) XXX_DiscardUnknown()
  • func (m *Response) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
  • func (m *Response) XXX_Merge(src proto.Message)
  • func (m *Response) XXX_Size() int
  • func (m *Response) XXX_Unmarshal(b []byte) error
• type UnimplementedExposedServiceServer
  • func (*UnimplementedExposedServiceServer) Proxy(ctx context.Context, req *Request) (*Response, error)

Variables

var Method_name = map[int32]string{
	0: "UNKNOWN",
	1: "GET",
	2: "HEAD",
	3: "POST",
	4: "PUT",
	5: "DELETE",
	6: "CONNECT",
	7: "OPTIONS",
	8: "TRACE",
	9: "PATCH",
}

var Method_value = map[string]int32{
	"UNKNOWN": 0,
	"GET":     1,
	"HEAD":    2,
	"POST":    3,
	"PUT":     4,
	"DELETE":  5,
	"CONNECT": 6,
	"OPTIONS": 7,
	"TRACE":   8,
	"PATCH":   9,
}

Functions

func RegisterExposedServiceServer

func RegisterExposedServiceServer(s *grpc.Server, srv ExposedServiceServer)

Types

type ExposedServiceClient

type ExposedServiceClient interface {
	// Proxies a message to the internal GRPC API
	Proxy(ctx context.Context, in *Request, opts ...grpc.CallOption) (*Response, error)
}

ExposedServiceClient is the client API for ExposedService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.

func NewExposedServiceClient

func NewExposedServiceClient(cc *grpc.ClientConn) ExposedServiceClient

type ExposedServiceServer

type ExposedServiceServer interface {
	// Proxies a message to the internal GRPC API
	Proxy(context.Context, *Request) (*Response, error)
}

ExposedServiceServer is the server API for ExposedService service.

type Method

type Method int32

All valid HTTP method names

const (
	Method_UNKNOWN Method = 0
	Method_GET     Method = 1
	Method_HEAD    Method = 2
	Method_POST    Method = 3
	Method_PUT     Method = 4
	Method_DELETE  Method = 5
	Method_CONNECT Method = 6
	Method_OPTIONS Method = 7
	Method_TRACE   Method = 8
	Method_PATCH   Method = 9
)

func (Method) EnumDescriptor

func (Method) EnumDescriptor() ([]byte, []int)

func (Method) String

func (x Method) String() string

type QueryParam

type QueryParam struct {
	// URL-decoded query param key
	Key string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
	// URL-decoded query param value
	Value                string   `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

Clearly defined parmaterisation

func (*QueryParam) Descriptor

func (*QueryParam) Descriptor() ([]byte, []int)

func (*QueryParam) GetKey

func (m *QueryParam) GetKey() string

func (*QueryParam) GetValue

func (m *QueryParam) GetValue() string

func (*QueryParam) ProtoMessage

func (*QueryParam) ProtoMessage()

func (*QueryParam) Reset

func (m *QueryParam) Reset()

func (*QueryParam) String

func (m *QueryParam) String() string

func (*QueryParam) XXX_DiscardUnknown

func (m *QueryParam) XXX_DiscardUnknown()

func (*QueryParam) XXX_Marshal

func (m *QueryParam) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*QueryParam) XXX_Merge

func (m *QueryParam) XXX_Merge(src proto.Message)

func (*QueryParam) XXX_Size

func (m *QueryParam) XXX_Size() int

func (*QueryParam) XXX_Unmarshal

func (m *QueryParam) XXX_Unmarshal(b []byte) error

type Request

type Request struct {
	// HTTP method from requestor
	Method Method `protobuf:"varint,1,opt,name=method,proto3,enum=httpgrpc.Method" json:"method,omitempty"`
	// Desired procedure name
	Procedure string `protobuf:"bytes,2,opt,name=procedure,proto3" json:"procedure,omitempty"`
	// JSON payload of the request, if present
	Payload []byte `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
	// Query params of the request, if present
	Params               []*QueryParam `protobuf:"bytes,4,rep,name=params,proto3" json:"params,omitempty"`
	XXX_NoUnkeyedLiteral struct{}      `json:"-"`
	XXX_unrecognized     []byte        `json:"-"`
	XXX_sizecache        int32         `json:"-"`
}

The request data from the HTTP request

func (*Request) Descriptor

func (*Request) Descriptor() ([]byte, []int)

func (*Request) GetMethod

func (m *Request) GetMethod() Method

func (*Request) GetParams

func (m *Request) GetParams() []*QueryParam

func (*Request) GetPayload

func (m *Request) GetPayload() []byte

func (*Request) GetProcedure

func (m *Request) GetProcedure() string

func (*Request) ProtoMessage

func (*Request) ProtoMessage()

func (*Request) Reset

func (m *Request) Reset()

func (*Request) String

func (m *Request) String() string

func (*Request) XXX_DiscardUnknown

func (m *Request) XXX_DiscardUnknown()

func (*Request) XXX_Marshal

func (m *Request) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Request) XXX_Merge

func (m *Request) XXX_Merge(src proto.Message)

func (*Request) XXX_Size

func (m *Request) XXX_Size() int

func (*Request) XXX_Unmarshal

func (m *Request) XXX_Unmarshal(b []byte) error

type Response

type Response struct {
	// Manually set status code rather than rely on error-handling at the proxy
	StatusCode uint32 `protobuf:"varint,1,opt,name=status_code,json=statusCode,proto3" json:"status_code,omitempty"`
	// JSON data to return to the requestor
	Payload              []byte   `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

The response to send to the requestor

func (*Response) Descriptor

func (*Response) Descriptor() ([]byte, []int)

func (*Response) GetPayload

func (m *Response) GetPayload() []byte

func (*Response) GetStatusCode

func (m *Response) GetStatusCode() uint32

func (*Response) ProtoMessage

func (*Response) ProtoMessage()

func (*Response) Reset

func (m *Response) Reset()

func (*Response) String

func (m *Response) String() string

func (*Response) XXX_DiscardUnknown

func (m *Response) XXX_DiscardUnknown()

func (*Response) XXX_Marshal

func (m *Response) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Response) XXX_Merge

func (m *Response) XXX_Merge(src proto.Message)

func (*Response) XXX_Size

func (m *Response) XXX_Size() int

func (*Response) XXX_Unmarshal

func (m *Response) XXX_Unmarshal(b []byte) error

type UnimplementedExposedServiceServer

type UnimplementedExposedServiceServer struct {
}

UnimplementedExposedServiceServer can be embedded to have forward compatible implementations.

func (*UnimplementedExposedServiceServer) Proxy

func (*UnimplementedExposedServiceServer) Proxy(ctx context.Context, req *Request) (*Response, error)