runtime

package
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2022 License: BSD-3-Clause Imports: 47 Imported by: 0

Documentation

Overview

Package runtime contains runtime helper functions used by servers which protoc-gen-grpc-gateway generates.

Index

Constants

View Source 
const MIMEWildcard = "*"

MIMEWildcard is the fallback MIME type used for requests which do not match a registered MIME type.

View Source 
const MetadataHeaderPrefix = "Grpc-Metadata-"

MetadataHeaderPrefix is the http prefix that represents custom metadata parameters to or from a gRPC call.

View Source 
const MetadataPrefix = "grpcgateway-"

MetadataPrefix is prepended to permanent HTTP header keys (as specified by the IANA) when added to the gRPC context.

View Source 
const MetadataTrailerPrefix = "Grpc-Trailer-"

MetadataTrailerPrefix is prepended to gRPC metadata as it is converted to HTTP headers in a response handled by grpc-gateway

Variables

View Source 
var (
	// ErrNotMatch indicates that the given HTTP request path does not match to the pattern.
	ErrNotMatch = errors.New("not match to the path pattern")
	// ErrInvalidPattern indicates that the given definition of Pattern is not valid.
	ErrInvalidPattern = errors.New("invalid pattern")
	// ErrMalformedSequence indicates that an escape sequence was malformed.
	ErrMalformedSequence = errors.New("malformed escape sequence")
)
View Source 
var (
	// CallerServiceId sets the gRPC caller service ID of the gateway.
	// For ease-gateway, it's ServiceId_EASE_GATEWAY.
	CallerServiceId = vexpb.ServiceId_EASE_GATEWAY
)
View Source 
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 AddMethod 

func AddMethod(spec *skypb.ServiceSpec, svcName, methodName, path, httpMethod string, loginRequired, clientSignRequired, isThirdParty bool, specSource, apiSource, tokenType, timeout string)

AddMethod adds an API method to the service object with the given spec.

func AddService 

func AddService(s *Service, enabler, disabler func())

AddService adds a service handler to the pool as available list. This will not automatically call Regsiter.

func AnnotateContext 

func AnnotateContext(ctx context.Context, mux *ServeMux, req *http.Request, rpcMethodName string, options ...AnnotateContextOption) (context.Context, error)

AnnotateContext adds context information such as metadata from the request.

At a minimum, the RemoteAddr is included in the fashion of "X-Forwarded-For", except that the forwarded destination is not another HTTP service but rather a gRPC service.

func AnnotateIncomingContext 

func AnnotateIncomingContext(ctx context.Context, mux *ServeMux, req *http.Request, rpcMethodName string, options ...AnnotateContextOption) (context.Context, error)

AnnotateIncomingContext adds context information such as metadata from the request. Attach metadata as incoming context.

func Bool 

func Bool(val string) (bool, error)

Bool converts the given string representation of a boolean value into bool.

func BoolSlice 

func BoolSlice(val, sep string) ([]bool, error)

BoolSlice converts 'val' where individual booleans are separated by 'sep' into a bool slice.

func BoolValue 

func BoolValue(val string) (*wrapperspb.BoolValue, error)

BoolValue well-known type support as wrapper around bool type

func Bytes 

func Bytes(val string) ([]byte, error)

Bytes converts the given string representation of a byte sequence into a slice of bytes A bytes sequence is encoded in URL-safe base64 without padding

func BytesSlice 

func BytesSlice(val, sep string) ([][]byte, error)

BytesSlice converts 'val' where individual bytes sequences, encoded in URL-safe base64 without padding, are separated by 'sep' into a slice of bytes slices slice.

func BytesValue 

func BytesValue(val string) (*wrapperspb.BytesValue, error)

BytesValue well-known type support as wrapper around bytes[] type

func DefaultHTTPErrorHandler 

func DefaultHTTPErrorHandler(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, r *http.Request, err error)

DefaultHTTPErrorHandler is the default error handler. If "err" is a gRPC Status, the function replies with the status code mapped by HTTPStatusFromCode. If "err" is a HTTPStatusError, the function replies with the status code provide by that struct. This is intended to allow passing through of specific statuses via the function set via WithRoutingErrorHandler for the ServeMux constructor to handle edge cases which the standard mappings in HTTPStatusFromCode are insufficient for. If otherwise, it replies with http.StatusInternalServerError.

The response body written by this function is a Status message marshaled by the Marshaler.

func DefaultHeaderMatcher 

func DefaultHeaderMatcher(key string) (string, bool)

DefaultHeaderMatcher is used to pass http request headers to/from gRPC context. This adds permanent HTTP header keys (as specified by the IANA) to gRPC context with grpcgateway- prefix. HTTP headers that start with 'Grpc-Metadata-' are mapped to gRPC metadata after removing prefix 'Grpc-Metadata-'.

func DefaultRoutingErrorHandler 

func DefaultRoutingErrorHandler(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, r *http.Request, httpStatus int)

DefaultRoutingErrorHandler is our default handler for routing errors. By default http error codes mapped on the following error codes: 

NotFound -> grpc.NotFound
StatusBadRequest -> grpc.InvalidArgument
MethodNotAllowed -> grpc.Unimplemented
Other -> grpc.Internal, method is not expecting to be called for anything else

func DefaultStreamErrorHandler 

func DefaultStreamErrorHandler(_ context.Context, err error) *status.Status

func DoubleValue 

func DoubleValue(val string) (*wrapperspb.DoubleValue, error)

DoubleValue well-known type support as wrapper around float64 type

func Duration 

func Duration(val string) (*durationpb.Duration, error)

Duration converts the given string into a timestamp.Duration.

func Enum 

func Enum(val string, enumValMap map[string]int32) (int32, error)

Enum converts the given string into an int32 that should be type casted into the correct enum proto type.

func EnumSlice 

func EnumSlice(val, sep string, enumValMap map[string]int32) ([]int32, error)

EnumSlice converts 'val' where individual enums are separated by 'sep' into a int32 slice. Each individual int32 should be type casted into the correct enum proto type.

func FieldMaskFromRequestBody 

func FieldMaskFromRequestBody(r io.Reader, msg proto.Message) (*field_mask.FieldMask, error)

FieldMaskFromRequestBody creates a FieldMask printing all complete paths from the JSON body.

func Float32 

func Float32(val string) (float32, error)

Float32 converts the given string representation of a floating point number into float32.

func Float32Slice 

func Float32Slice(val, sep string) ([]float32, error)

Float32Slice converts 'val' where individual floating point numbers are separated by 'sep' into a float32 slice.

func Float64 

func Float64(val string) (float64, error)

Float64 converts the given string representation into representation of a floating point number into float64.

func Float64Slice 

func Float64Slice(val, sep string) ([]float64, error)

Float64Slice converts 'val' where individual floating point numbers are separated by 'sep' into a float64 slice.

func FloatValue 

func FloatValue(val string) (*wrapperspb.FloatValue, error)

FloatValue well-known type support as wrapper around float32 type

func ForwardResponseMessage 

func ForwardResponseMessage(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, req *http.Request, resp proto.Message, opts ...func(context.Context, http.ResponseWriter, proto.Message) error)

ForwardResponseMessage forwards the message "resp" from gRPC server to REST client.

func ForwardResponseStream 

func ForwardResponseStream(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, req *http.Request, recv func() (proto.Message, error), opts ...func(context.Context, http.ResponseWriter, proto.Message) error)

ForwardResponseStream forwards the stream from gRPC server to REST client.

func GetServicGroups 

func GetServicGroups() map[string]*ServiceGroup

GetServicGroups returns the current available service groups.

func HTTPError 

func HTTPError(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, r *http.Request, err error)

HTTPError uses the mux-configured error handler.

func HTTPPathPattern added in v1.0.4 

func HTTPPathPattern(ctx context.Context) (string, bool)

HTTPPathPattern returns the HTTP path pattern string relating to the HTTP handler, if one exists. The format of the returned string is defined by the google.api.http path template type.

func HTTPStatusFromCode 

func HTTPStatusFromCode(code codes.Code) int

HTTPStatusFromCode converts a gRPC error code into the corresponding HTTP response status. See: https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto

func Int32 

func Int32(val string) (int32, error)

Int32 converts the given string representation of an integer into int32.

func Int32Slice 

func Int32Slice(val, sep string) ([]int32, error)

Int32Slice converts 'val' where individual integers are separated by 'sep' into a int32 slice.

func Int32Value 

func Int32Value(val string) (*wrapperspb.Int32Value, error)

Int32Value well-known type support as wrapper around int32 type

func Int64 

func Int64(val string) (int64, error)

Int64 converts the given string representation of an integer into int64.

func Int64Slice 

func Int64Slice(val, sep string) ([]int64, error)

Int64Slice converts 'val' where individual integers are separated by 'sep' into a int64 slice.

func Int64Value 

func Int64Value(val string) (*wrapperspb.Int64Value, error)

Int64Value well-known type support as wrapper around int64 type

func MarshalerForRequest 

func MarshalerForRequest(mux *ServeMux, r *http.Request) (inbound Marshaler, outbound Marshaler)

MarshalerForRequest returns the inbound/outbound marshalers for this request. It checks the registry on the ServeMux for the MIME type set by the Content-Type header. If it isn't set (or the request Content-Type is empty), checks for "*". If there are multiple Content-Type headers set, choose the first one that it can exactly match in the registry. Otherwise, it follows the above logic for "*"/InboundMarshaler/OutboundMarshaler.

func NewServerMetadataContext 

func NewServerMetadataContext(ctx context.Context, md ServerMetadata) context.Context

NewServerMetadataContext creates a new context with ServerMetadata

func PopulateFieldFromPath 

func PopulateFieldFromPath(msg proto.Message, fieldPathString string, value string) error

PopulateFieldFromPath sets a value in a nested Protobuf structure.

func PopulateQueryParameters 

func PopulateQueryParameters(msg proto.Message, values url.Values, filter *utilities.DoubleArray) error

PopulateQueryParameters parses query parameters into "msg" using current query parser

func PreLoadBalance 

func PreLoadBalance(ctx context.Context, balancer, hashHeyType string, req proto.Message) context.Context

PreLoadBalance processes context to affect the load balancer.

func RPCMethod 

func RPCMethod(ctx context.Context) (string, bool)

RPCMethod returns the method string for the server context. The returned string is in the format of "/package.service/method".

func RequestAccepted 

func RequestAccepted(ctx context.Context, spec *pb.ServiceSpec, name string, methodName string, w http.ResponseWriter, r *http.Request) (context.Context, error)

RequestAccepted will forward call to the hook if been set, otherwise no-op.

func RequestHandled 

func RequestHandled(ctx context.Context, spec *pb.ServiceSpec, name string, methodName string, out proto.Message, meta *ServerMetadata, err error)

RequestHandled will forward call to the hook if been set otherwise noop.

func RequestParsed 

func RequestParsed(ctx context.Context, spec *pb.ServiceSpec, name string, methodName string, reqProto proto.Message, meta *ServerMetadata) error

RequestParsed forwards the call to the RequestParsed method of GatewayServiceHook.

func RequestReceived 

func RequestReceived(w http.ResponseWriter, r *http.Request) (context.Context, error)

RequestReceived will forward call to the hook if set; otherwise no-op.

func SetGatewayServiceHook 

func SetGatewayServiceHook(h GatewayServiceHook) error

SetGatewayServiceHook sets a GatewayServiceHook. It should be called exactly once, after all init() functions are called (so that all gateway handlers are properly registered). That said, do not call it in function init().

func String 

func String(val string) (string, error)

String just returns the given string. It is just for compatibility to other types.

func StringSlice 

func StringSlice(val, sep string) ([]string, error)

StringSlice converts 'val' where individual strings are separated by 'sep' into a string slice.

func StringValue 

func StringValue(val string) (*wrapperspb.StringValue, error)

StringValue well-known type support as wrapper around string type

func Timestamp 

func Timestamp(val string) (*timestamppb.Timestamp, error)

Timestamp converts the given RFC3339 formatted string into a timestamp.Timestamp.

func UInt32Value 

func UInt32Value(val string) (*wrapperspb.UInt32Value, error)

UInt32Value well-known type support as wrapper around uint32 type

func UInt64Value 

func UInt64Value(val string) (*wrapperspb.UInt64Value, error)

UInt64Value well-known type support as wrapper around uint64 type

func Uint32 

func Uint32(val string) (uint32, error)

Uint32 converts the given string representation of an integer into uint32.

func Uint32Slice 

func Uint32Slice(val, sep string) ([]uint32, error)

Uint32Slice converts 'val' where individual integers are separated by 'sep' into a uint32 slice.

func Uint64 

func Uint64(val string) (uint64, error)

Uint64 converts the given string representation of an integer into uint64.

func Uint64Slice 

func Uint64Slice(val, sep string) ([]uint64, error)

Uint64Slice converts 'val' where individual integers are separated by 'sep' into a uint64 slice.

Types

type AnnotateContextOption added in v1.0.4 

type AnnotateContextOption func(ctx context.Context) context.Context

func WithHTTPPathPattern added in v1.0.4 

func WithHTTPPathPattern(pattern string) AnnotateContextOption

type Decoder 

type Decoder interface {
	Decode(v interface{}) error
}

Decoder decodes a byte sequence

type DecoderFunc 

type DecoderFunc func(v interface{}) error

DecoderFunc adapts an decoder function into Decoder.

func (DecoderFunc) Decode 

func (f DecoderFunc) Decode(v interface{}) error

Decode delegates invocations to the underlying function itself.

type DecoderWrapper 

type DecoderWrapper struct {
	*json.Decoder
	protojson.UnmarshalOptions
}

DecoderWrapper is a wrapper around a *json.Decoder that adds support for protos to the Decode method.

func (DecoderWrapper) Decode 

func (d DecoderWrapper) Decode(v interface{}) error

Decode wraps the embedded decoder's Decode method to support protos using a jsonpb.Unmarshaler.

type Delimited 

type Delimited interface {
	// Delimiter returns the record separator for the stream.
	Delimiter() []byte
}

Delimited defines the streaming delimiter.

type Encoder 

type Encoder interface {
	Encode(v interface{}) error
}

Encoder encodes gRPC payloads / fields into byte sequence.

type EncoderFunc 

type EncoderFunc func(v interface{}) error

EncoderFunc adapts an encoder function into Encoder

func (EncoderFunc) Encode 

func (f EncoderFunc) Encode(v interface{}) error

Encode delegates invocations to the underlying function itself.

type ErrorHandlerFunc 

type ErrorHandlerFunc func(context.Context, *ServeMux, Marshaler, http.ResponseWriter, *http.Request, error)

ErrorHandlerFunc is the signature used to configure error handling.

type GatewayServiceHook 

type GatewayServiceHook interface {
	// Bootstrap is a callback function which will be called when
	// SetGatewayServiceHook() is executed. The call is guaranteed to be
	// after all gateway services are registered and before any request
	// arrives.
	//
	// The passed-in service map contains all the service information known
	// by the gateway at compile time. The interface implementation can
	// safely hold this map because it will not be changed as soon as
	// Bootstrap() is called.
	//
	// The typical jobs which can be done in Bootstrap() include
	// initialization or starting service maintenance workers.
	Bootstrap(svcs map[string]*ServiceGroup) error

	// RequestReceived is called after the request arrives at the gateway
	// but before the routing decision is made.
	// Parameters:
	//     w: the raw HTTP response writer of current request
	//     r: the raw HTTP request
	//
	// Returns:
	//     err: the error returned to HTTP handler; when it's non-nil, the
	// request fails with an internal server error (500)
	RequestReceived(w http.ResponseWriter, r *http.Request) (ctx context.Context, err error)

	// RequestAccepted is called when a request is accepted and routed at
	// the gateway but before the protocol buffer is parsed.
	//
	// Parameters:
	//     svc: the service object to which the gateway routes
	//     m: the method object to which the gateway routes
	//     w:   the raw HTTP response writer of current request
	//     r:    the raw HTTP request
	// Returns:
	//     ctxVals: the values to be put into context and passed along the
	//              chain
	//     err:     the error returned to HTTP handler; when it's non-nil,
	//              the request fails with an internal server error (500)
	RequestAccepted(ctx context.Context, svc *Service, m *Method, w http.ResponseWriter, r *http.Request) (ctxret context.Context, err error)

	// RequestParsed is called after the request payload is unmarshaled and
	// before the gRPC call is invoked.
	//
	// Parameters:
	//    ctx:      the context
	//    svc:      the service object to which the gateway routes
	//    m: the method object to which the gateway routes
	//    reqProto: the request proto message
	//    meta:     the server meta data
	RequestParsed(ctx context.Context, svc *Service, m *Method, reqProto proto.Message, meta *ServerMetadata) error

	// RequestHandled is called after a request is completely handled, either
	// succeeded or failed.
	//
	// Parameters:
	//    ctx:  is the context.
	//    svc:  is the service object under current context.
	//    m: the method object to which the gateway routes
	//    out:  is the response message from grpc server.
	//    meta: the meta data.
	//    err:  is the err which returned from grpc server
	RequestHandled(ctx context.Context, svc *Service, m *Method, responseProto proto.Message, meta *ServerMetadata, err error)
}

GatewayServiceHook collects the injection points with which gateway runtime calls back on different stages of request processing. It allows us to intercept the flow and inject our business logic, such as authentication, etc.

At runtime we only need one instance of GatewayServiceHook since it's designed as goroutine-safe.

type HTTPBodyMarshaler 

type HTTPBodyMarshaler struct {
	Marshaler
}

HTTPBodyMarshaler is a Marshaler which supports marshaling of a google.api.HttpBody message as the full response body if it is the actual message used as the response. If not, then this will simply fallback to the Marshaler specified as its default Marshaler.

func (*HTTPBodyMarshaler) ContentType 

func (h *HTTPBodyMarshaler) ContentType(v interface{}) string

ContentType returns its specified content type in case v is a google.api.HttpBody message, otherwise it will fall back to the default Marshalers content type.

func (*HTTPBodyMarshaler) Marshal 

func (h *HTTPBodyMarshaler) Marshal(v interface{}) ([]byte, error)

Marshal marshals "v" by returning the body bytes if v is a google.api.HttpBody message, otherwise it falls back to the default Marshaler.

type HTTPStatusError added in v1.0.4 

type HTTPStatusError struct {
	HTTPStatus int
	Err        error
}

HTTPStatusError is the error to use when needing to provide a different HTTP status code for an error passed to the DefaultRoutingErrorHandler.

func (*HTTPStatusError) Error added in v1.0.4 

func (e *HTTPStatusError) Error() string

type HandlerFunc 

type HandlerFunc func(ctx context.Context, w http.ResponseWriter, r *http.Request, pathParams map[string]string)

A HandlerFunc handles a specific pair of path pattern and HTTP method.

type HeaderMatcherFunc 

type HeaderMatcherFunc func(string) (string, bool)

HeaderMatcherFunc checks whether a header key should be forwarded to/from gRPC context.

type JSONBuiltin 

type JSONBuiltin struct{}

JSONBuiltin is a Marshaler which marshals/unmarshals into/from JSON with the standard "encoding/json" package of Golang. Although it is generally faster for simple proto messages than JSONPb, it does not support advanced features of protobuf, e.g. map, oneof, ....

The NewEncoder and NewDecoder types return *json.Encoder and *json.Decoder respectively.

func (*JSONBuiltin) ContentType 

func (*JSONBuiltin) ContentType(_ interface{}) string

ContentType always Returns "application/json".

func (*JSONBuiltin) Delimiter 

func (j *JSONBuiltin) Delimiter() []byte

Delimiter for newline encoded JSON streams.

func (*JSONBuiltin) Marshal 

func (j *JSONBuiltin) Marshal(v interface{}) ([]byte, error)

Marshal marshals "v" into JSON

func (*JSONBuiltin) NewDecoder 

func (j *JSONBuiltin) NewDecoder(r io.Reader) Decoder

NewDecoder returns a Decoder which reads JSON stream from "r".

func (*JSONBuiltin) NewEncoder 

func (j *JSONBuiltin) NewEncoder(w io.Writer) Encoder

NewEncoder returns an Encoder which writes JSON stream into "w".

func (*JSONBuiltin) Unmarshal 

func (j *JSONBuiltin) Unmarshal(data []byte, v interface{}) error

Unmarshal unmarshals JSON data into "v".

type JSONPb 

type JSONPb struct {
	protojson.MarshalOptions
	protojson.UnmarshalOptions
}

JSONPb is a Marshaler which marshals/unmarshals into/from JSON with the "google.golang.org/protobuf/encoding/protojson" marshaler. It supports the full functionality of protobuf unlike JSONBuiltin.

The NewDecoder method returns a DecoderWrapper, so the underlying *json.Decoder methods can be used.

func (*JSONPb) ContentType 

func (*JSONPb) ContentType(_ interface{}) string

ContentType always returns "application/json".

func (*JSONPb) Delimiter 

func (j *JSONPb) Delimiter() []byte

Delimiter for newline encoded JSON streams.

func (*JSONPb) Marshal 

func (j *JSONPb) Marshal(v interface{}) ([]byte, error)

Marshal marshals "v" into JSON.

func (*JSONPb) NewDecoder 

func (j *JSONPb) NewDecoder(r io.Reader) Decoder

NewDecoder returns a Decoder which reads JSON stream from "r".

func (*JSONPb) NewEncoder 

func (j *JSONPb) NewEncoder(w io.Writer) Encoder

NewEncoder returns an Encoder which writes JSON stream into "w".

func (*JSONPb) Unmarshal 

func (j *JSONPb) Unmarshal(data []byte, v interface{}) error

Unmarshal unmarshals JSON "data" into "v"

type MalformedSequenceError added in v1.0.4 

type MalformedSequenceError string

func (MalformedSequenceError) Error added in v1.0.4 

func (e MalformedSequenceError) Error() string

type Marshaler 

type Marshaler interface {
	// Marshal marshals "v" into byte sequence.
	Marshal(v interface{}) ([]byte, error)
	// Unmarshal unmarshals "data" into "v".
	// "v" must be a pointer value.
	Unmarshal(data []byte, v interface{}) error
	// NewDecoder returns a Decoder which reads byte sequence from "r".
	NewDecoder(r io.Reader) Decoder
	// NewEncoder returns an Encoder which writes bytes sequence into "w".
	NewEncoder(w io.Writer) Encoder
	// ContentType returns the Content-Type which this marshaler is responsible for.
	// The parameter describes the type which is being marshalled, which can sometimes
	// affect the content type returned.
	ContentType(v interface{}) string
}

Marshaler defines a conversion between byte sequence and gRPC payloads / fields.

type Method 

type Method struct {
	Name               string
	Path               string
	HttpMethod         string
	Enabled            bool
	LoginRequired      bool
	ClientSignRequired bool
	IsThirdParty       bool
	SpecifiedSource    options.SpecSourceType
	ApiSource          options.ApiSourceType
	TokenType          options.AuthTokenType
	Timeout            string
}

Method represents a gRPC service method.

type Pattern 

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

Pattern is a template pattern of http request paths defined in https://github.com/googleapis/googleapis/blob/master/google/api/http.proto

func MustPattern 

func MustPattern(p Pattern, err error) Pattern

MustPattern is a helper function which makes it easier to call NewPattern in variable initialization.

func NewPattern 

func NewPattern(version int, ops []int, pool []string, verb string) (Pattern, error)

NewPattern returns a new Pattern from the given definition values. "ops" is a sequence of op codes. "pool" is a constant pool. "verb" is the verb part of the pattern. It is empty if the pattern does not have the part. "version" must be 1 for now. It returns an error if the given definition is invalid.

func (Pattern) Match deprecated 

func (p Pattern) Match(components []string, verb string) (map[string]string, error)

MatchAndEscape examines components to determine if they match to a Pattern. It will never perform per-component unescaping (see: UnescapingModeLegacy). MatchAndEscape will return an error if no Patterns matched. If successful, the function returns a mapping from field paths to their captured values.

Deprecated: Use MatchAndEscape.

func (Pattern) MatchAndEscape added in v1.0.4 

func (p Pattern) MatchAndEscape(components []string, verb string, unescapingMode UnescapingMode) (map[string]string, error)

MatchAndEscape examines components to determine if they match to a Pattern. MatchAndEscape will return an error if no Patterns matched or if a pattern matched but contained malformed escape sequences. If successful, the function returns a mapping from field paths to their captured values.

func (Pattern) String 

func (p Pattern) String() string

func (Pattern) Verb 

func (p Pattern) Verb() string

Verb returns the verb part of the Pattern.

type ProtoMarshaller 

type ProtoMarshaller struct{}

ProtoMarshaller is a Marshaller which marshals/unmarshals into/from serialize proto bytes

func (*ProtoMarshaller) ContentType 

func (*ProtoMarshaller) ContentType(_ interface{}) string

ContentType always returns "application/octet-stream".

func (*ProtoMarshaller) Marshal 

func (*ProtoMarshaller) Marshal(value interface{}) ([]byte, error)

Marshal marshals "value" into Proto

func (*ProtoMarshaller) NewDecoder 

func (marshaller *ProtoMarshaller) NewDecoder(reader io.Reader) Decoder

NewDecoder returns a Decoder which reads proto stream from "reader".

func (*ProtoMarshaller) NewEncoder 

func (marshaller *ProtoMarshaller) NewEncoder(writer io.Writer) Encoder

NewEncoder returns an Encoder which writes proto stream into "writer".

func (*ProtoMarshaller) Unmarshal 

func (*ProtoMarshaller) Unmarshal(data []byte, value interface{}) error

Unmarshal unmarshals proto "data" into "value"

type QueryParameterParser 

type QueryParameterParser interface {
	Parse(msg proto.Message, values url.Values, filter *utilities.DoubleArray) error
}

QueryParameterParser defines interface for all query parameter parsers

type RoutingErrorHandlerFunc 

type RoutingErrorHandlerFunc func(context.Context, *ServeMux, Marshaler, http.ResponseWriter, *http.Request, int)

RoutingErrorHandlerFunc is the signature used to configure error handling for routing errors.

type ServeMux 

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

ServeMux is a request multiplexer for grpc-gateway. It matches http requests to patterns and invokes the corresponding handler.

func NewServeMux 

func NewServeMux(opts ...ServeMuxOption) *ServeMux

NewServeMux returns a new ServeMux whose internal mapping is empty.

func (*ServeMux) GetForwardResponseOptions 

func (s *ServeMux) GetForwardResponseOptions() []func(context.Context, http.ResponseWriter, proto.Message) error

GetForwardResponseOptions returns the ForwardResponseOptions associated with this ServeMux.

func (*ServeMux) Handle 

func (s *ServeMux) Handle(meth string, pat Pattern, sid data.ServiceId, h HandlerFunc)

Handle associates "h" to the pair of HTTP method and path pattern.

func (*ServeMux) HandlePath 

func (s *ServeMux) HandlePath(meth string, pathPattern string, sid data.ServiceId, h HandlerFunc) error

HandlePath allows users to configure custom path handlers. refer: https://grpc-ecosystem.github.io/grpc-gateway/docs/operations/inject_router/

func (*ServeMux) ServeHTTP 

func (s *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches the request to the first handler whose pattern matches to r.Method and r.URL.Path.

type ServeMuxOption 

type ServeMuxOption func(*ServeMux)

ServeMuxOption is an option that can be given to a ServeMux on construction.

func SetQueryParameterParser 

func SetQueryParameterParser(queryParameterParser QueryParameterParser) ServeMuxOption

SetQueryParameterParser sets the query parameter parser, used to populate message from query parameters. Configuring this will mean the generated OpenAPI output is no longer correct, and it should be done with careful consideration.

func WithDisablePathLengthFallback 

func WithDisablePathLengthFallback() ServeMuxOption

WithDisablePathLengthFallback returns a ServeMuxOption for disable path length fallback.

func WithErrorHandler 

func WithErrorHandler(fn ErrorHandlerFunc) ServeMuxOption

WithErrorHandler returns a ServeMuxOption for configuring a custom error handler.

This can be used to configure a custom error response.

func WithForwardResponseOption 

func WithForwardResponseOption(forwardResponseOption func(context.Context, http.ResponseWriter, proto.Message) error) ServeMuxOption

WithForwardResponseOption returns a ServeMuxOption representing the forwardResponseOption.

forwardResponseOption is an option that will be called on the relevant context.Context, http.ResponseWriter, and proto.Message before every forwarded response.

The message may be nil in the case where just a header is being sent.

func WithHealthEndpointAt added in v1.0.4 

func WithHealthEndpointAt(healthCheckClient grpc_health_v1.HealthClient, endpointPath string, sid data.ServiceId) ServeMuxOption

WithHealthEndpointAt returns a ServeMuxOption that will add an endpoint to the created ServeMux at the path specified by endpointPath. When called the handler will forward the request to the upstream grpc service health check (defined in the gRPC Health Checking Protocol).

See here https://grpc-ecosystem.github.io/grpc-gateway/docs/operations/health_check/ for more information on how to setup the protocol in the grpc server.

If you define a service as query parameter, this will also be forwarded as service in the HealthCheckRequest.

func WithHealthzEndpoint added in v1.0.4 

func WithHealthzEndpoint(healthCheckClient grpc_health_v1.HealthClient, sid data.ServiceId) ServeMuxOption

WithHealthzEndpoint returns a ServeMuxOption that will add a /healthz endpoint to the created ServeMux.

See WithHealthEndpointAt for the general implementation.

func WithIncomingHeaderMatcher 

func WithIncomingHeaderMatcher(fn HeaderMatcherFunc) ServeMuxOption

WithIncomingHeaderMatcher returns a ServeMuxOption representing a headerMatcher for incoming request to gateway.

This matcher will be called with each header in http.Request. If matcher returns true, that header will be passed to gRPC context. To transform the header before passing to gRPC context, matcher should return modified header.

func WithMarshalerOption 

func WithMarshalerOption(mime string, marshaler Marshaler) ServeMuxOption

WithMarshalerOption returns a ServeMuxOption which associates inbound and outbound Marshalers to a MIME type in mux.

func WithMetadata 

func WithMetadata(annotator func(context.Context, *http.Request) metadata.MD) ServeMuxOption

WithMetadata returns a ServeMuxOption for passing metadata to a gRPC context.

This can be used by services that need to read from http.Request and modify gRPC context. A common use case is reading token from cookie and adding it in gRPC context.

func WithOutgoingHeaderMatcher 

func WithOutgoingHeaderMatcher(fn HeaderMatcherFunc) ServeMuxOption

WithOutgoingHeaderMatcher returns a ServeMuxOption representing a headerMatcher for outgoing response from gateway.

This matcher will be called with each header in response header metadata. If matcher returns true, that header will be passed to http response returned from gateway. To transform the header before passing to response, matcher should return modified header.

func WithRoutingErrorHandler 

func WithRoutingErrorHandler(fn RoutingErrorHandlerFunc) ServeMuxOption

WithRoutingErrorHandler returns a ServeMuxOption for configuring a custom error handler to handle http routing errors.

Method called for errors which can happen before gRPC route selected or executed. The following error codes: StatusMethodNotAllowed StatusNotFound StatusBadRequest

func WithStreamErrorHandler 

func WithStreamErrorHandler(fn StreamErrorHandlerFunc) ServeMuxOption

WithStreamErrorHandler returns a ServeMuxOption that will use the given custom stream error handler, which allows for customizing the error trailer for server-streaming calls.

For stream errors that occur before any response has been written, the mux's ErrorHandler will be invoked. However, once data has been written, the errors must be handled differently: they must be included in the response body. The response body's final message will include the error details returned by the stream error handler.

func WithUnescapingMode added in v1.0.4 

func WithUnescapingMode(mode UnescapingMode) ServeMuxOption

WithEscapingType sets the escaping type. See the definitions of UnescapingMode for more information.

type ServerMetadata 

type ServerMetadata struct {
	HeaderMD  metadata.MD
	TrailerMD metadata.MD
}

ServerMetadata consists of metadata sent from gRPC server.

func ServerMetadataFromContext 

func ServerMetadataFromContext(ctx context.Context) (md ServerMetadata, ok bool)

ServerMetadataFromContext returns the ServerMetadata in ctx

type ServerTransportStream 

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

ServerTransportStream implements grpc.ServerTransportStream. It should only be used by the generated files to support grpc.SendHeader outside of gRPC server use.

func (*ServerTransportStream) Header 

func (s *ServerTransportStream) Header() metadata.MD

Header returns the header metadata of the stream.

func (*ServerTransportStream) Method 

func (s *ServerTransportStream) Method() string

Method returns the method for the stream.

func (*ServerTransportStream) SendHeader 

func (s *ServerTransportStream) SendHeader(md metadata.MD) error

SendHeader sets the header metadata.

func (*ServerTransportStream) SetHeader 

func (s *ServerTransportStream) SetHeader(md metadata.MD) error

SetHeader sets the header metadata.

func (*ServerTransportStream) SetTrailer 

func (s *ServerTransportStream) SetTrailer(md metadata.MD) error

SetTrailer sets the trailer metadata.

func (*ServerTransportStream) Trailer 

func (s *ServerTransportStream) Trailer() metadata.MD

Trailer returns the cached trailer metadata.

type Service 

type Service struct {
	Spec     skypb.ServiceSpec
	Name     string
	Methods  []*Method
	Register func(*ServeMux) error
	Enable   func(spec *skypb.ServiceSpec, conn *grpc.ClientConn)
	Disable  func()
}

Service is the controller class for each grpc service handler.

type ServiceGroup 

type ServiceGroup struct {
	Spec     skypb.ServiceSpec
	Enable   func()
	Disable  func()
	Services map[string]*Service
}

ServiceGroup groups services with the same spec.

func GetServiceGroup 

func GetServiceGroup(spec *skypb.ServiceSpec) *ServiceGroup

GetServiceGroup returns the ServiceGroup with the given spec.

type StreamErrorHandlerFunc 

type StreamErrorHandlerFunc func(context.Context, error) *status.Status

StreamErrorHandlerFunc is the signature used to configure stream error handling.

type UnescapingMode added in v1.0.4 

type UnescapingMode int

UnescapingMode defines the behavior of ServeMux when unescaping path parameters. 

const (
	// UnescapingModeLegacy is the default V2 behavior, which escapes the entire
	// path string before doing any routing.
	UnescapingModeLegacy UnescapingMode = iota

	// UnescapingModeAllExceptReserved unescapes all path parameters except RFC 6570
	// reserved characters.
	UnescapingModeAllExceptReserved

	// UnescapingModeAllExceptSlash unescapes URL path parameters except path
	// separators, which will be left as "%2F".
	UnescapingModeAllExceptSlash

	// UnescapingModeAllCharacters unescapes all URL path parameters.
	UnescapingModeAllCharacters

	// UnescapingModeDefault is the default escaping type.
	// TODO(v3): default this to UnescapingModeAllExceptReserved per grpc-httpjson-transcoding's
	// reference implementation
	UnescapingModeDefault = UnescapingModeLegacy
)

Source Files

View all Source files

Directories

Path Synopsis
internal
examplepb

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.