From ceb0a5999e37ef31153e839d43efb5c58b3d6714 Mon Sep 17 00:00:00 2001 From: Iheanyi Ekechukwu Date: Thu, 28 Nov 2019 14:20:13 -0500 Subject: [PATCH] Add comments to exported functions. --- client_hooks.go | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/client_hooks.go b/client_hooks.go index 948d227f..08b053a2 100644 --- a/client_hooks.go +++ b/client_hooks.go @@ -17,19 +17,35 @@ import ( "net/http" ) +// ClientOption is a functional option for extending a Twirp client. type ClientOption func(*ClientOptions) +// ClientOptions encapsulate the configurable parameters on a Twirp client. type ClientOptions struct { Hooks *ClientHooks } +// ClientHooks is a container for callbacks that can instrument a +// Twirp-generated client. These callbacks all accept a context and some return +// a context. They can use this to add to the contxt, appending values or +// deadlilns to it. +// +// The RequestPrepared hook is special because it can return errors. If it +// returns non-nil error, handling for that request will be stopped at that +// point. The Error hook will then be triggered. +// +// The RequestPrepaared hook will always be called first and wlil be called for +// every outgoinig request from the Twirp client. The last hook to be called +// will either be Error or ResponseReceived, so be sure to handle both case in +// your hooks. type ClientHooks struct { // RequestPrepared is called as soon as a request has been created and before it has been sent // to the Twirp server. RequestPrepared func(context.Context, *http.Request) (context.Context, error) // ResponseReceived is called after a request has finished sending. Since this is terminal, the context is - // not returned. + // not returned. ResponseReceived will not be called in the case of an error + // being returned from the request. ResponseReceived func(context.Context) // Error hook is called whenever an error occurs during the sending of a request. The Error is passed @@ -37,12 +53,14 @@ type ClientHooks struct { Error func(context.Context, Error) } +// DefaultClientOptions instantiates ClientOptions with their default options. func DefaultClientOptions() ClientOptions { return ClientOptions{ Hooks: nil, } } +// WithClientHooks defines the hooks for a Twirp client. func WithClientHooks(hooks *ClientHooks) ClientOption { return func(o *ClientOptions) { o.Hooks = hooks