gateway

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2018 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// These custom codes defined here to conform REST API Syntax
	// It is supposed that you do not send them over the wire as part of gRPC Status,
	// because they will be treated as Unknown by gRPC library.
	// You should use them to send successfull status of your RPC method
	// using SetStatus function from this package.
	Created codes.Code = 10000 + iota // 10000 is an offset from standard codes
	Updated
	Deleted
	LongRunning
	PartialContent
)
View Source 
const (
	// DefaultServerAddress is the standard gRPC server address that a REST
	// gateway will connect to.
	DefaultServerAddress = ":9090"
)

Variables

View Source 
var (
	// ProtoMessageErrorHandler uses PrefixOutgoingHeaderMatcher.
	// To use ProtoErrorHandler with custom outgoing header matcher call NewProtoMessageErrorHandler.
	ProtoMessageErrorHandler = NewProtoMessageErrorHandler(PrefixOutgoingHeaderMatcher)
	// ProtoStreamErrorHandler uses PrefixOutgoingHeaderMatcher.
	// To use ProtoErrorHandler with custom outgoing header matcher call NewProtoStreamErrorHandler.
	ProtoStreamErrorHandler = NewProtoStreamErrorHandler(PrefixOutgoingHeaderMatcher)
)
View Source 
var (
	// ForwardResponseMessage is default implementation of ForwardResponseMessageFunc
	ForwardResponseMessage = NewForwardResponseMessage(PrefixOutgoingHeaderMatcher, ProtoMessageErrorHandler, ProtoStreamErrorHandler)
	// ForwardResponseStream is default implementation of ForwardResponseStreamFunc
	ForwardResponseStream = NewForwardResponseStream(PrefixOutgoingHeaderMatcher, ProtoMessageErrorHandler, ProtoStreamErrorHandler)
)

Functions

func Code 

func Code(cname string) codes.Code

Code returns an instance of gRPC code by its string name. The `cname` must be in upper case and one of the code names defined in REST API Syntax. If code name is invalid or unknow the codes.Unknown will be returned.

func CodeName 

func CodeName(c codes.Code) string

CodeName returns stringname of gRPC code, function handles as standard codes from "google.golang.org/grpc/codes" as well as custom ones defined in this package. The codes.Unimplemented is named "NOT_IMPLEMENTED" in accordance with REST API Syntax Specification.

func FieldSelection 

func FieldSelection(ctx context.Context) *query.FieldSelection

FieldSelection extracts op.FieldSelection from gRPC metadata

func Filtering 

func Filtering(ctx context.Context) (*query.Filtering, error)

Filtering extracts filter parameters from incoming gRPC context. If filtering collection operator has not been specified in query string of incoming HTTP testRequest function returns (nil, nil). If provided filtering parameters are invalid function returns `status.Error(codes.InvalidArgument, parser_error)` See: `query.ParseFiltering` for details.

func HTTPStatusFromCode 

func HTTPStatusFromCode(code codes.Code) int

HTTPStatusFromCode converts a gRPC error code into the corresponding HTTP response status. 

func Header(ctx context.Context, key string) (string, bool)

Header returns first value for a given key if it exists in gRPC metadata from incoming or outcoming context, otherwise returns (nil, false)

Calls HeaderN(ctx, key, 1)

Provided key is converted to lowercase (see grpc/metadata.New). If key is not found the prefix "grpcgateway-" is added to the key and key is being searched once again.

func HeaderN 

func HeaderN(ctx context.Context, key string, n int) (val []string, found bool)

HeaderN returns first n values for a given key if it exists in gRPC metadata from incoming or outcoming context, otherwise returns (nil, false)

If n < 0 all values for a given key will be returned If n > 0 at least n values will be returned, or (nil, false) If n == 0 result is (nil, false)

Provided key is converted to lowercase (see grpc/metadata.New). If key is not found the prefix "grpcgateway-" is added to the key and key is being searched once again.

func MetadataAnnotator 

func MetadataAnnotator(ctx context.Context, req *http.Request) metadata.MD

MetadataAnnotator is a function for passing metadata to a gRPC context It must be mainly used as ServeMuxOption for gRPC Gateway 'ServeMux' See: 'WithMetadata' option.

MetadataAnnotator extracts values of query operators from incoming HTTP testRequest accroding to REST API Syntax. E.g: - _order_by="name asc,age desc" - _fields="name,age" - _filter="name == 'John'" - _limit=1000 - _offset=1001 - _page_token=QWxhZGRpbjpvcGVuIHNlc2FtZQ

func NewGateway 

func NewGateway(options ...Option) (*http.ServeMux, error)

NewGateway creates a gRPC REST gateway with HTTP handlers that have been generated by the gRPC gateway protoc plugin

func NewPaginationContext added in v0.5.0 

func NewPaginationContext(ctx context.Context, p *query.Pagination) context.Context

NewPaginationContext return the new `context.Context` that caries `*query.Pagination` instance.

func NewProtoMessageErrorHandler 

func NewProtoMessageErrorHandler(out runtime.HeaderMatcherFunc) runtime.ProtoErrorHandlerFunc

NewProtoMessageErrorHandler returns runtime.ProtoErrorHandlerFunc

func Pagination 

func Pagination(ctx context.Context) (*query.Pagination, error)

Pagination extracts pagination parameters from incoming gRPC context. If some of parameters has not been specified in query string of incoming HTTP testRequest corresponding fields in `query.PaginationRequest` structure will be set to nil. If provided pagination parameters are invalid function returns `status.Error(codes.InvalidArgument, parser_error)` See: `query.ParsePagination` for details.

func PrefixOutgoingHeaderMatcher 

func PrefixOutgoingHeaderMatcher(key string) (string, bool)

PrefixOutgoingHeaderMatcher prefixes outgoing gRPC metadata with runtime.MetadataHeaderPrefix ("Grpc-Metadata-"). It behaves like the default gRPC-Gateway outgoing header matcher (if none is provided as an option).

func SetCreated 

func SetCreated(ctx context.Context, msg string) error

SetCreated is a shortcut for SetStatus(ctx, status.New(Created, msg))

func SetDeleted 

func SetDeleted(ctx context.Context, msg string) error

SetDeleted is a shortcut for SetStatus(ctx, status.New(Deleted, msg))

func SetFieldSelection 

func SetFieldSelection(ctx context.Context, fields *query.FieldSelection) error

SetFieldSelection sets op.FieldSelection to gRPC metadata

func SetPageInfo 

func SetPageInfo(ctx context.Context, p *query.PageInfo) error

SetPagination sets page info to outgoing gRPC context.

func SetRunning 

func SetRunning(ctx context.Context, message, resource string) error

SetRunning is a shortcut for SetStatus(ctx, status.New(LongRunning, url))

func SetStatus 

func SetStatus(ctx context.Context, st *status.Status) error

SetStatus sets gRPC status as gRPC metadata Status.Code will be set with metadata key `grpcgateway-status-code` and with value as string name of the code. Status.Message will be set with metadata key `grpcgateway-status-message` and with corresponding value.

func SetUpdated 

func SetUpdated(ctx context.Context, msg string) error

SetUpdated is a shortcut for SetStatus(ctx, status.New(Updated, msg))

func Sorting 

func Sorting(ctx context.Context) (*query.Sorting, error)

Sorting extracts sort parameters from incoming gRPC context. If sorting collection operator has not been specified in query string of incoming HTTP testRequest function returns (nil, nil). If provided sorting parameters are invalid function returns `status.Error(codes.InvalidArgument, parser_error)` See: `query.ParseSorting` for details.

func UnaryServerInterceptor 

func UnaryServerInterceptor() grpc.UnaryServerInterceptor

UnaryServerInterceptor returns grpc.UnaryServerInterceptor that should be used as a middleware if an user's testRequest message defines any of collection operators.

Returned middleware populates collection operators from gRPC metadata if they defined in a testRequest message.

Types

type ForwardResponseMessageFunc 

type ForwardResponseMessageFunc func(context.Context, *runtime.ServeMux, runtime.Marshaler, http.ResponseWriter, *http.Request, proto.Message, ...func(context.Context, http.ResponseWriter, proto.Message) error)

ForwardResponseMessageFunc forwards gRPC response to HTTP client inaccordance with REST API Syntax

func NewForwardResponseMessage 

func NewForwardResponseMessage(out runtime.HeaderMatcherFunc, meh runtime.ProtoErrorHandlerFunc, seh ProtoStreamErrorHandlerFunc) ForwardResponseMessageFunc

NewForwardResponseMessage returns ForwardResponseMessageFunc

type ForwardResponseStreamFunc 

type ForwardResponseStreamFunc func(context.Context, *runtime.ServeMux, runtime.Marshaler, http.ResponseWriter, *http.Request, func() (proto.Message, error), ...func(context.Context, http.ResponseWriter, proto.Message) error)

ForwardResponseStreamFunc forwards gRPC stream response to HTTP client inaccordance with REST API Syntax

func NewForwardResponseStream 

func NewForwardResponseStream(out runtime.HeaderMatcherFunc, meh runtime.ProtoErrorHandlerFunc, seh ProtoStreamErrorHandlerFunc) ForwardResponseStreamFunc

NewForwardResponseStream returns ForwardResponseStreamFunc

type Option 

type Option func(*gateway)

Option is a functional option that modifies the REST gateway on initialization

func WithDialOptions 

func WithDialOptions(options ...grpc.DialOption) Option

WithDialOptions assigns a list of gRPC dial options to the REST gateway

func WithEndpointRegistration 

func WithEndpointRegistration(prefix string, endpoints ...registerFunc) Option

WithEndpointRegistration takes a group of HTTP handlers that have been generated by the gRPC gateway protoc plugin and registers them to the REST gateway with some prefix (e.g. www.website.com/prefix/endpoint)

func WithMux added in v0.5.0 

func WithMux(mux *http.ServeMux) Option

WithMux will use the given http.ServeMux to register the gateway endpoints.

func WithServerAddress 

func WithServerAddress(address string) Option

WithServerAddress determines what address the gateway will connect to. By default, the gateway will connect to 0.0.0.0:9090

type ProtoErrorHandler 

type ProtoErrorHandler struct {
	OutgoingHeaderMatcher runtime.HeaderMatcherFunc
}

ProtoErrorHandler implements runtime.ProtoErrorHandlerFunc in method MessageHandler and ProtoStreamErrorHandlerFunc in method StreamHandler in accordance with REST API Syntax Specification. See RestError for the JSON format of an error

func (*ProtoErrorHandler) MessageHandler 

func (h *ProtoErrorHandler) MessageHandler(ctx context.Context, mux *runtime.ServeMux, marshaler runtime.Marshaler, rw http.ResponseWriter, req *http.Request, err error)

MessageHandler implements runtime.ProtoErrorHandlerFunc in accordance with REST API Syntax Specification. See RestError for the JSON format of an error

func (*ProtoErrorHandler) StreamHandler 

func (h *ProtoErrorHandler) StreamHandler(ctx context.Context, headerWritten bool, mux *runtime.ServeMux, marshaler runtime.Marshaler, rw http.ResponseWriter, req *http.Request, err error)

StreamHandler implements ProtoStreamErrorHandlerFunc in accordance with REST API Syntax Specification. See RestError for the JSON format of an error

type ProtoStreamErrorHandlerFunc 

type ProtoStreamErrorHandlerFunc func(context.Context, bool, *runtime.ServeMux, runtime.Marshaler, http.ResponseWriter, *http.Request, error)

ProtoStreamErrorHandlerFunc handles the error as a gRPC error generated via status package and replies to the testRequest. Addition bool argument indicates whether method (http.ResponseWriter.WriteHeader) was called or not.

func NewProtoStreamErrorHandler 

func NewProtoStreamErrorHandler(out runtime.HeaderMatcherFunc) ProtoStreamErrorHandlerFunc

NewProtoStreamErrorHandler returns ProtoStreamErrorHandlerFunc

type ResponseForwarder 

type ResponseForwarder struct {
	OutgoingHeaderMatcher runtime.HeaderMatcherFunc
	MessageErrHandler     runtime.ProtoErrorHandlerFunc
	StreamErrHandler      ProtoStreamErrorHandlerFunc
}

ResponseForwarder implements ForwardResponseMessageFunc in method ForwardMessage and ForwardResponseStreamFunc in method ForwardStream in accordance with REST API Syntax Specification. See: https://github.com/infobloxopen/atlas-app-toolkit#responses for format of JSON response.

func (*ResponseForwarder) ForwardMessage 

func (fw *ResponseForwarder) ForwardMessage(ctx context.Context, mux *runtime.ServeMux, marshaler runtime.Marshaler, rw http.ResponseWriter, req *http.Request, resp proto.Message, opts ...func(context.Context, http.ResponseWriter, proto.Message) error)

ForwardMessage implements runtime.ForwardResponseMessageFunc

func (*ResponseForwarder) ForwardStream 

func (fw *ResponseForwarder) ForwardStream(ctx context.Context, mux *runtime.ServeMux, marshaler runtime.Marshaler, rw http.ResponseWriter, req *http.Request, recv func() (proto.Message, error), opts ...func(context.Context, http.ResponseWriter, proto.Message) error)

ForwardStream implements runtime.ForwardResponseStreamFunc. RestStatus comes first in the chuncked result.

type RestError 

type RestError struct {
	Status  *RestStatus   `json:"error,omitempty"`
	Details []interface{} `json:"details,omitempty"`
}

RestError represents an error in accordance with REST API Syntax Specification. See: https://github.com/infobloxopen/atlas-app-toolkit#errors

type RestStatus 

type RestStatus struct {
	HTTPStatus int `json:"status,omitempty"`
	// Code is a string representation of an error code
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`

	// Pagination response parameters
	PageToken string `json:"_page_token,omitempty"`
	Offset    string `json:"_offset,omitempty"`
	Size      string `json:"_size,omitempty"`
}

RestStatus represents a response status in accordance with REST API Syntax. See: https://github.com/infobloxopen/atlas-app-toolkit#responses

func Status 

func Status(ctx context.Context, st *status.Status) *RestStatus

Status returns REST representation of gRPC status. If status.Status is not nil it will be converted in accrodance with REST API Syntax otherwise context will be used to extract `grpcgatewau-status-code` and `grpcgateway-status-message` from gRPC metadata. If `grpcgatewau-status-code` is not set it is assumed that it is OK.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.