gateway

package
v0.24.4 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2021 License: Apache-2.0 Imports: 30 Imported by: 0

README

Gateway

This package contains helper functions that support creating, configuring, and running a gRPC REST gateway that is REST syntax compliant. Google already provides a lot of documentation related to the gRPC gateway, so this README will mostly serve to link to existing docs.

gRPC is great — it generates API clients and server stubs in many programming languages, it is fast, easy-to-use, bandwidth-efficient and its design is combat-proven by Google. However, you might still want to provide a traditional RESTful API as well. Reasons can range from maintaining backwards-compatibility, supporting languages or clients not well supported by gRPC to simply maintaining the aesthetics and tooling involved with a RESTful architecture.

Define REST Endpoints in Proto Schema

You can map your gRPC service methods to one or more REST API endpoints. Google's official gRPC documentation has several great examples here.

Note that it is possible to define multiple HTTP methods for one RPC by using the additional_bindings option.

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (google.api.http) = {
      get: "/v1/messages/{message_id}"
        additional_bindings {
          get: "/v1/users/{user_id}/messages/{message_id}"
        }
      };
    }
  }
}

message GetMessageRequest {
  string message_id = 1;
  string user_id = 2;
}

This enables the following two alternative HTTP JSON to RPC mappings:

HTTP Verb REST Endpoint RPC
GET /v1/messages/123456 GetMessage(message_id: "123456")
GET /v1/users/me/messages/123456 GetMessage(user_id: "me", message_id: "123456")

HTTP Headers

Your application or service might depend on HTTP headers from incoming REST requests. The official gRPC gateway documentation describes how to handle HTTP headers in detail, so check out the documentation here.

Using Headers in gRPC Service

To extract headers from metadata, you can use the FromIncomingContext function.

import (
    "context"

    "google.golang.org/grpc/metadata"
    "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
)

func (s *myServiceImpl) MyMethod(ctx context.Context, req *MyRequest) (*MyResponse, error) {
    var userAgent string

    if md, ok := metadata.FromIncomingContext(ctx); ok {
        // Uppercase letters are automatically converted to lowercase, see metadata.New
        if u, ok [runtime.MetadataPrefix+"user-agent"]; ok {
            userAgen = u[0]
        }
    }
}

You can also use the helper function provided in this package.

import (
    "context"

    "github.com/kirinse/atlas-app-toolkit/gateway"
)

func (s *myServiceImpl) MyMethod(ctx context.Context, req *MyRequest) (*MyResponse, error) {
    var userAgent string

    if h, ok := gateway.Header(ctx, "user-agent"); ok {
        userAgent = h
    }
}
Adding Headers to REST Response

To send metadata from the gRPC server to the REST client, you need to use the SetHeader function.

import (
    "context"

    "google.golang.org/grpc"
    "google.golang.org/grpc/metadata"
)

func (s *myServiceImpl) MyMethod(ctx context.Context, req *MyRequest) (*MyResponse, error) {
    md := metadata.Pairs("myheader", "myvalue")
    if err := grpc.SetHeader(ctx, md); err != nil {
        return nil, err
    }
    return nil, nil
}

If you do not use any custom outgoing header matcher, you will see something like this.

$ curl -i http://localhost:8080/resource

HTTP/1.1 200 OK
Content-Type: application/json
Grpc-Metadata-Myheader: myvalue
Date: Wed, 31 Jan 2018 15:28:52 GMT
Content-Length: 2

{}

Responses

You may need to modify the HTTP response body returned by the gRPC gateway. For instance, the gRPC Gateway translates non-error gRPC responses into 200 - OK HTTP responses, which might not suit your particular use case.

Overwrite Default Response Forwarder

By default, an HTTP response returned by the gRPC Gateway doesn't conform to the Infoblox REST API Syntax (e.g. it has no success section).

To override this behavior, the gRPC Gateway documentation recommends overwriting ForwardResponseMessage and ForwardResponseStream functions correspondingly. See this documentation for further information.

import (
	"github.com/kirinse/atlas-app-toolkit/gateway"
)

func init() {
	forward_App_ListObjects_0 = gateway.ForwardResponseMessage
}
Complying with Infoblox's REST API Syntax

We made default ForwardResponseMessageFunc and ForwardResponseStreamFunc implementations that conform to Infoblox's REST API Syntax guidelines. These helper functions ensure that Infoblox teams who use toolkit follow the same REST API conventions. For non-Infoblox toolkit users, these are completely optional utilities.

Note: the forwarders still set 200 - OK as HTTP status code if no errors are encountered.

Setting HTTP Status Codes

In order to set HTTP status codes properly, you need to send metadata from your gRPC service so that default forwarders will be able to read them and set codes. This is a common approach in gRPC to send extra information for response as metadata.

We recommend using the gRPC status package and our custom function SetStatus to add extra metadata to the gRPC response.

More documentation is available in the status package.

Also you may use shortcuts like SetCreated, SetUpdated, and SetDeleted.

import (
    "github.com/kirinse/atlas-app-toolkit/gateway"
)

func (s *myService) MyMethod(req *MyRequest) (*MyResponse, error) {
    err := gateway.SetCreated(ctx, "created 1 item")
    return &MyResponse{Result: []*Item{item}}, err
}
Response Format

Unless another format is specified in the request Accept header that the service supports, services render resources in responses in JSON format by default.

By default for a successful RPC call only the proto response is rendered as JSON, however for a failed call a special format is used, and by calling special methods the response can include additional metadata.

The WithSuccess(ctx context.Context, msg MessageWithFields) function allows you to add a success block to the returned JSON. By default this block only contains a message field, however arbitrary key-value pairs can also be included. This is included at top level, alongside the assumed result or results field.

Ex.

{
  "success": {
    "foo": "bar",
    "baz": 1,
    "message": <message-text>
  },
  "results": <service-response>
}

The WithError(ctx context.Context, err error) function allows you to add an extra error to the errors list in the returned JSON. The NewWithFields(message string, kvpairs ...interface{}) function can be used to create this error, which then includes additional fields in the error, otherwise only the error message will be included. This is included at top level, alongside the assumed result or results field if the call succeeded despite the error, or alone otherwise.

Ex.

{
  "errors": [
    {
      "foo": "bar",
      "baz": 1,
      "message": <message-text>
    }
  ],
  "results": <service-response>
}

To return an error with fields and fail the RPC, return an error from NewResponseError(ctx context.Context, msg string, kvpairs ...interface{}) or NewResponseErrorWithCode(ctx context.Context, c codes.Code, msg string, kvpairs ...interface{}) to also set the return code.

The function IncludeStatusDetails(withDetails bool) allows you to include the success block with fields code and status automatically for all responses, and the first of the errors in failed responses will also include the fields. Note that this choice affects all responses that pass through gateway.ForwardResponseMessage.

Ex:

{
  "success": {
    "status": <http-status-code>,
    "code": <enumerated-error-code>,
    "message": <message-text>
  },
  "results": <service-response>
}
Example Success Responses With IncludeStatusDetails(true)

Response with no results

{
  "success": {
    "status": "CREATED",
    "message": "Account provisioned",
    "code": 201
  }
}

Response with results

{
  "success": {
    "status": "OK",
    "message": "Found 2 items",
    "code": 200
  },
  "results": [
    {
      "account_id": 4,
      "created_at": "2018-01-06T03:53:27.651Z",
      "updated_at": "2018-01-06T03:53:27.651Z",
      "account_number": null,
      "sfdc_account_id": "3",
      "id": 5
    },
    {
      "account_id": 31,
      "created_at": "2018-01-06T04:38:32.572Z",
      "updated_at": "2018-01-06T04:38:32.572Z",
      "account_number": null,
      "sfdc_account_id": "1",
      "id": 9
    }
  ]
}

Response for get by id operation

{
  "success": {
    "status": "OK",
    "message": "object found",
    "code": 200
  },
  "results": {
      "account_id": 4,
      "created_at": "2018-05-06T03:53:27.651Z",
      "updated_at": "2018-05-06T03:53:27.651Z",
      "id": 5
   }
}

Response with results and service-defined results tag rpz_hits

{
  "success": {
    "status": "OK",
    "message": "Read 360 items",
    "code": 200
  },
  "rpz_hits": [
    {
      "pid": "default",
      "rip": "10.35.205.4",
      "policy_name": "Default",
      "ttl": -1,
      "qtype": 1,
      "qip": "10.120.20.247",
      "confidence": 3,
      "network": "on-prem",
      "event_time": "2017-12-13T07:07:50.000Z",
      "feed_name": "rpz",
      "dsource": 1,
      "rcode": 3,
      "timestamp": "11e7-dfd4-54e564f0-0000-0000287cd227",
      "company": "302002|0",
      "feed_type": "0",
      "user": "unknown",
      "device": "10.120.20.247",
      "severity": 3,
      "country": "unknown",
      "policy_action": "Block",
      "qname": "barfywyjgx.com",
      "tproperty": "A",
      "tclass": "UNKNOWN"
    },
    ...
  ]
}

Query String Filtering

When using the collection operators with the grpc-gateway, extraneous errors may be logged during rpcs as the query string is parsed that look like this:

field not found in *foo.ListFoobarRequest: _order_by

and the usage of any of the collection operator field names without the leading underscore (order_by, filter,... instead of _order_by, filter,...) in query strings may result in the error unsupported field type reflect.Value, being returned.

This can be resolved by overwriting the default filter for each rpc with these operators using the one defined in filter.go.

filter_Foobar_List_0 = gateway.DefaultQueryFilter
Translating gRPC Errors to HTTP

To respond with an error message that is REST API syntax-compliant, you can write your own ProtoErrorHandler or use DefaultProtoErrorHandler provided in this package.

Passing errors from the gRPC service to the REST client is supported by the gRPC gateway, so see the gRPC gateway documentation here.

Here's an example that shows how to use DefaultProtoErrorHandler.

import (
    "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
    "github.com/kirinse/atlas-app-toolkit/gateway"

    "github.com/yourrepo/yourapp"
)

func main() {
    // create error handler option
    errHandler := runtime.WithProtoErrorHandler(gateway.DefaultProtoErrorHandler)

    // pass that option as a parameter
    mux := runtime.NewServeMux(errHandler)

    // register you app handler
    yourapp.RegisterAppHandlerFromEndpoint(ctx, mux, addr)

    ...

    // Profit!
}

You can find sample in example folder. See code

Sending Error Details

The idiomatic way to send an error from you gRPC service is to simple return it from you gRPC handler either as status.Errorf() or errors.New(). If additional fields are required, then use the NewResponseError(ctx context.Context, msg string, kvpairs ...interface{}) or NewResponseErrorWithCode(ctx context.Context, c codes.Code, msg string, kvpairs ...interface{}) functions instead.

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

func (s *myServiceImpl) MyMethod(req *MyRequest) (*MyResponse, error) {
    return nil, status.Errorf(codes.Unimplemented, "method is not implemented: %v", req)
}

func (s *myServiceImpl) MyMethod2(ctx context.Context, req *MyRequest) (*MyResponse, error) {
    return nil, NewResponseErrorWithCode(ctx, codes.Internal, "something broke on our end", "retry_in", 30)
}

Documentation

Index

Constants

View Source 
const (
	// Created 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"
)
View Source 
const XForwardedFor = "X-Forwarded-For"

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)
)
View Source 
var DefaultQueryFilter = utilities.NewDoubleArray(defaultFilterFields)

DefaultQueryFilter can be set to override the filter_{service}_{rpc}_{num} field in generated .pb.gw.go files to prevent parse errors in the gateway and potentially reduce log noise due to unrecognized fields

View Source 
var OldStatusCreatedOnUpdate = false

OldStatusCreatedOnUpdate if true will return http.StatusCreated from HTTPStatusFromCode function if gRPC code is equal to Updated. This variable should only be set in an init() function by code that vendors this library.

Functions

func AtlasDefaultHeaderMatcher added in v0.23.0 

func AtlasDefaultHeaderMatcher() func(string) (string, bool)

AtlasDefaultHeaderMatcher func used to add all headers used by atlas-app-toolkit This function also passes through all the headers that runtime.DefaultHeaderMatcher handles. AtlasDefaultHeaderMatcher can be used as a Incoming/Outgoing header matcher.

func ChainHeaderMatcher added in v0.23.0 

func ChainHeaderMatcher(matchers ...runtime.HeaderMatcherFunc) runtime.HeaderMatcherFunc

ChainHeaderMatcher func is used to build chain on header matcher funcitons this function can be used as incoming or outgoing header matcher keep in mind that gRPC metadata treat as case insensitive strings

func ClientUnaryInterceptor added in v0.7.0 

func ClientUnaryInterceptor(parentCtx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error

ClientUnaryInterceptor parse collection operators and stores in corresponding message fields

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 ExtendedDefaultHeaderMatcher added in v0.18.2 

func ExtendedDefaultHeaderMatcher(headerNames ...string) func(string) (string, bool)

ExtendedDefaultHeaderMatcher func is used to add custom headers to be matched from incoming http requests, If this returns true the header will be added to grpc context. This function also passes through all the headers that runtime.DefaultHeaderMatcher handles.

func GeoIPHeaderMatcher added in v0.23.0 

func GeoIPHeaderMatcher() runtime.HeaderMatcherFunc

GeoIPHeaderMatcher X-Geo-* headers are set of geo metadata from MaxMind DB injected on ingress nginx

func GetCollectionOp added in v0.7.0 

func GetCollectionOp(res, op interface{}) error

func GetFieldSelection added in v0.14.0 

func GetFieldSelection(req proto.Message) (fieldName string, fs *query.FieldSelection, err error)

func GetFiltering added in v0.14.0 

func GetFiltering(req proto.Message) (fieldName string, f *query.Filtering, err error)

func GetGeoHeaders added in v0.24.2 

func GetGeoHeaders() []string

GetGeoHeaders returns a slice of x-geo- headers.

func GetPageInfo added in v0.14.0 

func GetPageInfo(resp proto.Message) (fieldName string, pg *query.PageInfo, err error)

func GetPagination added in v0.14.0 

func GetPagination(req proto.Message) (fieldName string, p *query.Pagination, err error)

func GetSorting added in v0.14.0 

func GetSorting(req proto.Message) (fieldName string, s *query.Sorting, err error)

func GetXB3Headers added in v0.24.2 

func GetXB3Headers() []string

GetXB3Headers returns a slice of x-b3- headers.

func HTTPStatus added in v0.16.0 

func HTTPStatus(ctx context.Context, st *status.Status) (int, string)

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

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 IncludeStatusDetails added in v0.17.1 

func IncludeStatusDetails(withDetails bool)

IncludeStatusDetails enables/disables output of status & code fields in all http json translated in the gateway with this package's ForwardResponseMessage

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 stores request URL in gRPC metadata from incoming HTTP кequest

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 NewPresenceAnnotator added in v0.8.0 

func NewPresenceAnnotator(methods ...string) func(context.Context, *http.Request) metadata.MD

NewPresenceAnnotator will parse the JSON input and then add the paths to the metadata to be pulled from context later

func NewProtoMessageErrorHandler 

func NewProtoMessageErrorHandler(out runtime.HeaderMatcherFunc) runtime.ErrorHandlerFunc

NewProtoMessageErrorHandler returns runtime.ProtoErrorHandlerFunc

func NewResponseError added in v0.17.1 

func NewResponseError(ctx context.Context, msg string, kvpairs ...interface{}) error

NewResponseError sets the error in the context with extra fields, to override the standard message-only error

func NewResponseErrorWithCode added in v0.17.1 

func NewResponseErrorWithCode(ctx context.Context, c codes.Code, msg string, kvpairs ...interface{}) error

NewResponseErrorWithCode sets the return code and returns an error with extra fields in MD to be extracted in the gateway response writer

func PrefixOutgoingHeaderMatcher 

func PrefixOutgoingHeaderMatcher(key string) (string, bool)

PrefixOutgoingHeaderMatcher discards all grpc header metadata.

func PresenceClientInterceptor added in v0.8.0 

func PresenceClientInterceptor(options ...presenceInterceptorOption) grpc.UnaryClientInterceptor

PresenceClientInterceptor gets the interceptor for populating a fieldmask in a proto message from the fields given in the metadata/context

func QueryFilterWith added in v0.15.0 

func QueryFilterWith(extraFields []string) *utilities.DoubleArray

QueryFilterWith will add extra fields to the standard fields in the default filter.

func RequestIDHeaderMatcher added in v0.23.0 

func RequestIDHeaderMatcher() runtime.HeaderMatcherFunc

RequestIDHeaderMatcher request id header contains unique identifier for request

func SetCollectionOps added in v0.7.0 

func SetCollectionOps(req, op interface{}) error

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 SetPageInfo 

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

SetPagination sets page info to outgoing gRPC context. Deprecated: Please add `infoblox.api.PageInfo` as part of gRPC message and do not rely on 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 TracingHeaderMatcher added in v0.23.0 

func TracingHeaderMatcher() runtime.HeaderMatcherFunc

TracingHeaderMatcher tracing headers

func UnaryServerInterceptor 

func UnaryServerInterceptor() grpc.UnaryServerInterceptor

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

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

func WithCodedSuccess added in v0.17.1 

func WithCodedSuccess(ctx context.Context, c codes.Code, msg string, args ...interface{}) error

WithCodedSuccess wraps a SetStatus and WithSuccess call into one, just to make things a little more "elegant"

func WithError added in v0.16.0 

func WithError(ctx context.Context, err error)

WithError will save an error message into the grpc trailer metadata, if it is an error that implements MessageWithFields, it also saves the fields. This error will then be inserted into the return JSON if the ResponseForwarder is used

func WithOverrideFieldMask added in v0.19.2 

func WithOverrideFieldMask(d *presenceInterceptorOptionsDecorator)

WithOverrideFieldMask represent an option to override field mask generated by grpc-gateway

func WithSuccess added in v0.16.0 

func WithSuccess(ctx context.Context, msg MessageWithFields)

WithSuccess will save a MessageWithFields into the grpc trailer metadata. This success message will then be inserted into the return JSON if the ResponseForwarder is used

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.ErrorHandlerFunc, 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.ErrorHandlerFunc, seh ProtoStreamErrorHandlerFunc) ForwardResponseStreamFunc

NewForwardResponseStream returns ForwardResponseStreamFunc

type MessageWithFields added in v0.16.0 

type MessageWithFields interface {
	error
	GetFields() map[string]interface{}
	GetMessage() string
}

func NewWithFields added in v0.16.0 

func NewWithFields(message string, kvpairs ...interface{}) MessageWithFields

NewWithFields returns a new MessageWithFields that requires a message string, and then treats the following arguments as alternating keys and values a non-string key will immediately return the result so far, ignoring later values. The values can be any type

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 WithGatewayOptions added in v0.7.0 

func WithGatewayOptions(opt ...runtime.ServeMuxOption) Option

WithGatewayOptions allows for additional gateway ServeMuxOptions beyond the default ProtoMessageErrorHandler and MetadataAnnotator from this package

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.ErrorHandlerFunc
	StreamErrHandler      ProtoStreamErrorHandlerFunc
}

ResponseForwarder implements ForwardResponseMessageFunc in method ForwardMessage and ForwardResponseStreamFunc in method ForwardStream in accordance with REST API Syntax Specification. See: https://github.com/kirinse/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 RestErrs added in v0.16.0 

type RestErrs struct {
	Error []map[string]interface{} `json:"error,omitempty"`
}

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.