httprule

Documentation

Overview

Package httprule provides utilities to map google.api.http annotation to net/http Request and Response types. These utilities allow to generate HTTP Clients for a given proto service. The methods of this service have their HTTP mappings specified via `google.api.http` method options, e.g.:

service HelloService {
    rpc Hello (HelloRequest) returns (HelloResponse) {
        option (google.api.http) = { post:"/api/hello" body:"*" };
    };
};

HttpRule proto: https://github.com/googleapis/googleapis/blob/master/google/api/http.proto HttpRule codegen: https://pkg.go.dev/google.golang.org/genproto/googleapis/api/annotations

Index

• Variables
• func NewHTTPRequest(rule *pb.HttpRule, baseURL string, req proto.Message) (*http.Request, error)
• func ParseProtoResponse(rule *pb.HttpRule, resp *http.Response, target proto.Message) error
• func ValidateHTTPRule(rule *pb.HttpRule) error
• type ClientConn
  • func NewClientConn(baseURL string, opts ...Option) *ClientConn
  • func (c *ClientConn) Invoke(ctx context.Context, method string, args, reply interface{}, ...) error
  • func (c *ClientConn) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, ...) (grpc.ClientStream, error)
• type Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithHeader(key, value string) Option

Variables

var (
	ErrInvalidMethod    = errors.New("invalid gRPC method string")
	ErrMethodNotFound   = errors.New("method not found")
	ErrServiceNotFound  = errors.New("service not found")
	ErrNotImplemented   = errors.New("not implemented")
	ErrHttpRuleNotFound = errors.New("no HttpRule")
)

var (
	ErrInvalidHttpRule = fmt.Errorf("invalid HttpRule")
)

Functions

func NewHTTPRequest

func NewHTTPRequest(rule *pb.HttpRule, baseURL string, req proto.Message) (*http.Request, error)

NewHTTPReuqest creates an *http.Request for a given proto message and HTTPRule, containing the request mapping information.

func ParseProtoResponse

func ParseProtoResponse(rule *pb.HttpRule, resp *http.Response, target proto.Message) error

ParseProtoResponse parses a http.Response using a HttpRule into a target message. The HttpRule contains a specification of how the response body and headers are mapped into the target proto message. The body JSON may map directly to the target message, or it may map to a top-level field of the target message. Response headers may reference any top-level scalar or repeated scalar fields of the target message.

The http.Response body is consumed but not closed.

func ValidateHTTPRule

func ValidateHTTPRule(rule *pb.HttpRule) error

Types

type ClientConn

type ClientConn struct {
	HTTPClient *http.Client
	BaseURL    string
	// contains filtered or unexported fields
}

func NewClientConn

func NewClientConn(baseURL string, opts ...Option) *ClientConn

NewClientConn creates an httprule.ClientConn for making HTTP requests mapped from gRPC method calls annotated with google.api.http annotations. The baseURL is used as a prefix to the paths specified in annotations and is typically just a scheme and host, however all elements of the baseURL are preserved and the path in the annotation is appended to the path in the baseURL.

A zero-value http.Client will be used by the ClientConn for all HTTP requests it makes. An alternate http.Client can be provided as an Option.

opts are function options that modify the http.ClientConn and are typically created by the With* functions in this package.

func (*ClientConn) Invoke

func (c *ClientConn) Invoke(ctx context.Context, method string, args, reply interface{}, opts ...grpc.CallOption) error

func (*ClientConn) NewStream

func (c *ClientConn) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (grpc.ClientStream, error)

type Option

type Option func(*ClientConn)

Option is a function option for customising a httprule.ClientConn via the httprule.NewClientConn() constructor. They are typically created by the With* functions in this package.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient retuens an httprule.Option for setting the HTTP client used by a ClientConn.

func WithHeader

func WithHeader(key, value string) Option

WithHeader returns an httprule.Option for setting a header on each HTTP request made by a httprule.ClientConn. The header is added to any that may be specified by a google.api.http annotation on a method. The returned option can be passed to the NewClientConn() constructor.