ranger

README

Ranger RPC

Ranger RPC is a simple and fast proto-based RPC framework

Design Goals

• simple & fast to use
• work with standard Protocol Buffers service definitions
• works with GO's standard http server and hence does not require HTTP 2
• minimal runtime dependencies
• make it easy to generate json/yaml/protobuf based APIs

References

• Protocol Buffers
• GRPC Service Definition

Kudos

This implementation is inspired by:

• Rob Pike's video
• GRPC
• Twirp.

We at Mondoo are huge NASA fans and we want to dedicate the name to the NASA Ranger missions whose objective was to obtain the first close-up images of the surface of the Moon. These missions, which were the first American spacecraft to land on the moon, helped lay the groundwork for the Apollo program.

Authors

• Christoph Hartmann
• Dominik Richter

Documentation

Index

• Constants
• Variables
• func AnnotateContext(ctx context.Context, req *http.Request) (context.Context, context.CancelFunc, error)
• func DefaultHttpClient() *http.Client
• func HttpError(span trace.Span, w http.ResponseWriter, req *http.Request, err error)
• func NewHttpClient(opts ...HttpClientOption) *http.Client
• func NewRPCServer(service *Service) *server
• func SanitizeUrl(addr string) string
• type Client
  • func (c *Client) AddPlugin(plugin ClientPlugin)
  • func (c *Client) AddPlugins(plugins ...ClientPlugin)
  • func (c *Client) DoClientRequest(ctx context.Context, client HTTPClient, url string, in, out proto.Message) (err error)
  • func (c *Client) PrintTraceCurlCommand(url string, in proto.Message)
• type ClientPlugin
• type HTTPClient
• type HttpClientOption
  • func WithProxy(proxy *url.URL) HttpClientOption
• type Method
• type Service

Constants

const (
	ContentTypeProtobuf      = "application/protobuf"
	ContentTypeOctetProtobuf = "application/octet-stream"
	ContentTypeGrpcProtobuf  = "application/grpc+proto"
	ContentTypeJson          = "application/json"
)

Variables

var (
	DefaultHttpTimeout         = 30 * time.Second
	DefaultIdleConnTimeout     = 30 * time.Second
	DefaultTLSHandshakeTimeout = 10 * time.Second
)

var (
	// DefaultContextTimeout is used for gRPC call context.WithTimeout whenever a Grpc-Timeout inbound
	// header isn't present. If the value is 0 the sent `context` will not have a timeout.
	DefaultContextTimeout = 0 * time.Second
)

Functions

func AnnotateContext

func AnnotateContext(ctx context.Context, req *http.Request) (context.Context, context.CancelFunc, error)

AnnotateContext adds context information such as metadata from the request. It is designed to work similar to the gRPC AnnotateContext function. At a minimum, the RemoteAddr is included in the fashion of "X-Forwarded-For" in the metadata.

The implementation is derived from GRPC-Gateway AnnotateContext (BSD3-License). See: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/context.go#L78

func DefaultHttpClient

func DefaultHttpClient() *http.Client

DefaultHttpClient will set up a basic client with default timeouts/proxies/etc.

func HttpError

func HttpError(span trace.Span, w http.ResponseWriter, req *http.Request, err error)

HttpError writes an error to the response.

func NewHttpClient

func NewHttpClient(opts ...HttpClientOption) *http.Client

func NewRPCServer

func NewRPCServer(service *Service) *server

NewServer creates a new server. This function is used by the protoc-gen-rangerrpc generated code and should not be used directly.

func SanitizeUrl

func SanitizeUrl(addr string) string

SanitizeUrl parses the given url and returns a sanitized url. If no scheme is given, it will be set to https.

Types

type Client

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

Client is the client for the Ranger service. It is used as the base client for all service calls.

func (*Client) AddPlugin

func (c *Client) AddPlugin(plugin ClientPlugin)

AddPlugin adds a client plugin. Deprecated: use AddPlugins instead.

func (*Client) AddPlugins

func (c *Client) AddPlugins(plugins ...ClientPlugin)

AddPlugins adds one or many client plugins.

func (*Client) DoClientRequest

func (c *Client) DoClientRequest(ctx context.Context, client HTTPClient, url string, in, out proto.Message) (err error)

DoClientRequest makes a request to the Ranger service. It will marshal the proto.Message into the request body, do the request and then parse the response into the response proto.Message.

func (*Client) PrintTraceCurlCommand

func (c *Client) PrintTraceCurlCommand(url string, in proto.Message)

type ClientPlugin

type ClientPlugin interface {
	GetName() string
	GetHeader(content []byte) http.Header
}

ClientPlugin is a plugin that can be used to modify the http headers of a request.

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type HttpClientOption

type HttpClientOption func(c *http.Client)

func WithProxy

func WithProxy(proxy *url.URL) HttpClientOption

type Method

type Method func(ctx context.Context, reqBytes *[]byte) (proto.Message, error)

Method represents a RPC method and is used by protoc-gen-rangerrpc

type Service

type Service struct {
	Name    string
	Methods map[string]Method
}

Service is the struct that holds all available methods. The protoc-gen-rangerrpc will generate the correct client and service definition to be used.