addsvc

Documentation

Overview

Package addsvc is an example microservice, useful for education. It can sum integers and concatenate strings. A client library is available in the client subdirectory. A server binary is available in cmd/addsrv. An example client binary is available in cmd/addcli.

Index

• Variables
• func DecodeGRPCConcatRequest(_ context.Context, grpcReq interface{}) (interface{}, error)
• func DecodeGRPCConcatResponse(_ context.Context, grpcReply interface{}) (interface{}, error)
• func DecodeGRPCSumRequest(_ context.Context, grpcReq interface{}) (interface{}, error)
• func DecodeGRPCSumResponse(_ context.Context, grpcReply interface{}) (interface{}, error)
• func DecodeHTTPConcatRequest(_ context.Context, r *http.Request) (interface{}, error)
• func DecodeHTTPConcatResponse(_ context.Context, r *http.Response) (interface{}, error)
• func DecodeHTTPSumRequest(_ context.Context, r *http.Request) (interface{}, error)
• func DecodeHTTPSumResponse(_ context.Context, r *http.Response) (interface{}, error)
• func EncodeGRPCConcatRequest(_ context.Context, request interface{}) (interface{}, error)
• func EncodeGRPCConcatResponse(_ context.Context, response interface{}) (interface{}, error)
• func EncodeGRPCSumRequest(_ context.Context, request interface{}) (interface{}, error)
• func EncodeGRPCSumResponse(_ context.Context, response interface{}) (interface{}, error)
• func EncodeHTTPGenericRequest(_ context.Context, r *http.Request, request interface{}) error
• func EncodeHTTPGenericResponse(_ context.Context, w http.ResponseWriter, response interface{}) error
• func EndpointInstrumentingMiddleware(duration metrics.Histogram) endpoint.Middleware
• func EndpointLoggingMiddleware(logger log.Logger) endpoint.Middleware
• func MakeConcatEndpoint(s Service) endpoint.Endpoint
• func MakeGRPCServer(ctx context.Context, endpoints Endpoints, tracer stdopentracing.Tracer, ...) pb.AddServer
• func MakeHTTPHandler(ctx context.Context, endpoints Endpoints, tracer stdopentracing.Tracer, ...) http.Handler
• func MakeSumEndpoint(s Service) endpoint.Endpoint
• func MakeThriftConcatEndpoint(client *thriftadd.AddServiceClient) endpoint.Endpoint
• func MakeThriftHandler(ctx context.Context, e Endpoints) thriftadd.AddService
• func MakeThriftSumEndpoint(client *thriftadd.AddServiceClient) endpoint.Endpoint
• type Endpoints
  • func (e Endpoints) Concat(ctx context.Context, a, b string) (string, error)
  • func (e Endpoints) Sum(ctx context.Context, a, b int) (int, error)
• type Middleware
  • func ServiceInstrumentingMiddleware(ints, chars metrics.Counter) Middleware
  • func ServiceLoggingMiddleware(logger log.Logger) Middleware
• type Service
  • func NewBasicService() Service

Variables

var (
	// ErrTwoZeroes is an arbitrary business rule for the Add method.
	ErrTwoZeroes = errors.New("can't sum two zeroes")

	// ErrIntOverflow protects the Add method. We've decided that this error
	// indicates a misbehaving service and should count against e.g. circuit
	// breakers. So, we return it directly in endpoints, to illustrate the
	// difference. In a real service, this probably wouldn't be the case.
	ErrIntOverflow = errors.New("integer overflow")

	// ErrMaxSizeExceeded protects the Concat method.
	ErrMaxSizeExceeded = errors.New("result exceeds maximum size")
)

Functions

func DecodeGRPCConcatRequest

func DecodeGRPCConcatRequest(_ context.Context, grpcReq interface{}) (interface{}, error)

DecodeGRPCConcatRequest is a transport/grpc.DecodeRequestFunc that converts a gRPC concat request to a user-domain concat request. Primarily useful in a server.

func DecodeGRPCConcatResponse

func DecodeGRPCConcatResponse(_ context.Context, grpcReply interface{}) (interface{}, error)

DecodeGRPCConcatResponse is a transport/grpc.DecodeResponseFunc that converts a gRPC concat reply to a user-domain concat response. Primarily useful in a client.

func DecodeGRPCSumRequest

func DecodeGRPCSumRequest(_ context.Context, grpcReq interface{}) (interface{}, error)

DecodeGRPCSumRequest is a transport/grpc.DecodeRequestFunc that converts a gRPC sum request to a user-domain sum request. Primarily useful in a server.

func DecodeGRPCSumResponse

func DecodeGRPCSumResponse(_ context.Context, grpcReply interface{}) (interface{}, error)

DecodeGRPCSumResponse is a transport/grpc.DecodeResponseFunc that converts a gRPC sum reply to a user-domain sum response. Primarily useful in a client.

func DecodeHTTPConcatRequest

func DecodeHTTPConcatRequest(_ context.Context, r *http.Request) (interface{}, error)

DecodeHTTPConcatRequest is a transport/http.DecodeRequestFunc that decodes a JSON-encoded concat request from the HTTP request body. Primarily useful in a server.

func DecodeHTTPConcatResponse

func DecodeHTTPConcatResponse(_ context.Context, r *http.Response) (interface{}, error)

DecodeHTTPConcatResponse is a transport/http.DecodeResponseFunc that decodes a JSON-encoded concat response from the HTTP response body. If the response has a non-200 status code, we will interpret that as an error and attempt to decode the specific error message from the response body. Primarily useful in a client.

func DecodeHTTPSumRequest

func DecodeHTTPSumRequest(_ context.Context, r *http.Request) (interface{}, error)

DecodeHTTPSumRequest is a transport/http.DecodeRequestFunc that decodes a JSON-encoded sum request from the HTTP request body. Primarily useful in a server.

func DecodeHTTPSumResponse

func DecodeHTTPSumResponse(_ context.Context, r *http.Response) (interface{}, error)

DecodeHTTPSumResponse is a transport/http.DecodeResponseFunc that decodes a JSON-encoded sum response from the HTTP response body. If the response has a non-200 status code, we will interpret that as an error and attempt to decode the specific error message from the response body. Primarily useful in a client.

func EncodeGRPCConcatRequest

func EncodeGRPCConcatRequest(_ context.Context, request interface{}) (interface{}, error)

EncodeGRPCConcatRequest is a transport/grpc.EncodeRequestFunc that converts a user-domain concat request to a gRPC concat request. Primarily useful in a client.

func EncodeGRPCConcatResponse

func EncodeGRPCConcatResponse(_ context.Context, response interface{}) (interface{}, error)

EncodeGRPCConcatResponse is a transport/grpc.EncodeResponseFunc that converts a user-domain concat response to a gRPC concat reply. Primarily useful in a server.

func EncodeGRPCSumRequest

func EncodeGRPCSumRequest(_ context.Context, request interface{}) (interface{}, error)

EncodeGRPCSumRequest is a transport/grpc.EncodeRequestFunc that converts a user-domain sum request to a gRPC sum request. Primarily useful in a client.

func EncodeGRPCSumResponse

func EncodeGRPCSumResponse(_ context.Context, response interface{}) (interface{}, error)

EncodeGRPCSumResponse is a transport/grpc.EncodeResponseFunc that converts a user-domain sum response to a gRPC sum reply. Primarily useful in a server.

func EncodeHTTPGenericRequest

func EncodeHTTPGenericRequest(_ context.Context, r *http.Request, request interface{}) error

EncodeHTTPGenericRequest is a transport/http.EncodeRequestFunc that JSON-encodes any request to the request body. Primarily useful in a client.

func EncodeHTTPGenericResponse

func EncodeHTTPGenericResponse(_ context.Context, w http.ResponseWriter, response interface{}) error

EncodeHTTPGenericResponse is a transport/http.EncodeResponseFunc that encodes the response as JSON to the response writer. Primarily useful in a server.

func EndpointInstrumentingMiddleware

func EndpointInstrumentingMiddleware(duration metrics.Histogram) endpoint.Middleware

EndpointInstrumentingMiddleware returns an endpoint middleware that records the duration of each invocation to the passed histogram. The middleware adds a single field: "success", which is "true" if no error is returned, and "false" otherwise.

func EndpointLoggingMiddleware

func EndpointLoggingMiddleware(logger log.Logger) endpoint.Middleware

EndpointLoggingMiddleware returns an endpoint middleware that logs the duration of each invocation, and the resulting error, if any.

func MakeConcatEndpoint

func MakeConcatEndpoint(s Service) endpoint.Endpoint

MakeConcatEndpoint returns an endpoint that invokes Concat on the service. Primarily useful in a server.

func MakeGRPCServer

func MakeGRPCServer(ctx context.Context, endpoints Endpoints, tracer stdopentracing.Tracer, logger log.Logger) pb.AddServer

MakeGRPCServer makes a set of endpoints available as a gRPC AddServer.

func MakeHTTPHandler

func MakeHTTPHandler(ctx context.Context, endpoints Endpoints, tracer stdopentracing.Tracer, logger log.Logger) http.Handler

MakeHTTPHandler returns a handler that makes a set of endpoints available on predefined paths.

func MakeSumEndpoint

func MakeSumEndpoint(s Service) endpoint.Endpoint

MakeSumEndpoint returns an endpoint that invokes Sum on the service. Primarily useful in a server.

func MakeThriftConcatEndpoint

func MakeThriftConcatEndpoint(client *thriftadd.AddServiceClient) endpoint.Endpoint

MakeThriftConcatEndpoint returns an endpoint that invokes the passed Thrift client. Useful only in clients, and only until a proper transport/thrift.Client exists.

func MakeThriftHandler

func MakeThriftHandler(ctx context.Context, e Endpoints) thriftadd.AddService

MakeThriftHandler makes a set of endpoints available as a Thrift service.

func MakeThriftSumEndpoint

func MakeThriftSumEndpoint(client *thriftadd.AddServiceClient) endpoint.Endpoint

MakeThriftSumEndpoint returns an endpoint that invokes the passed Thrift client. Useful only in clients, and only until a proper transport/thrift.Client exists.

Types

type Endpoints

type Endpoints struct {
	SumEndpoint    endpoint.Endpoint
	ConcatEndpoint endpoint.Endpoint
}

Endpoints collects all of the endpoints that compose an add service. It's meant to be used as a helper struct, to collect all of the endpoints into a single parameter.

In a server, it's useful for functions that need to operate on a per-endpoint basis. For example, you might pass an Endpoints to a function that produces an http.Handler, with each method (endpoint) wired up to a specific path. (It is probably a mistake in design to invoke the Service methods on the Endpoints struct in a server.)

In a client, it's useful to collect individually constructed endpoints into a single type that implements the Service interface. For example, you might construct individual endpoints using transport/http.NewClient, combine them into an Endpoints, and return it to the caller as a Service.

func (Endpoints) Concat

func (e Endpoints) Concat(ctx context.Context, a, b string) (string, error)

Concat implements Service. Primarily useful in a client.

func (Endpoints) Sum

func (e Endpoints) Sum(ctx context.Context, a, b int) (int, error)

Sum implements Service. Primarily useful in a client.

type Middleware

type Middleware func(Service) Service

Middleware describes a service (as opposed to endpoint) middleware.

func ServiceInstrumentingMiddleware

func ServiceInstrumentingMiddleware(ints, chars metrics.Counter) Middleware

ServiceInstrumentingMiddleware returns a service middleware that instruments the number of integers summed and characters concatenated over the lifetime of the service.

func ServiceLoggingMiddleware

func ServiceLoggingMiddleware(logger log.Logger) Middleware

ServiceLoggingMiddleware returns a service middleware that logs the parameters and result of each method invocation.

type Service

type Service interface {
	Sum(ctx context.Context, a, b int) (int, error)
	Concat(ctx context.Context, a, b string) (string, error)
}

Service describes a service that adds things together.

func NewBasicService

func NewBasicService() Service

NewBasicService returns a naïve, stateless implementation of Service.