rtplugs

README

rtplugs

The rtplugs package instruments golang http clients that supports a RoundTripper interface. It was built and tested against ReverseProxy

To extend reverseproxy use:

rt := rtplugs.New(log)  
if rt != nil {  
    // We have at least one activated plug
    defer rt.Close()
    reverseproxy.Transport = rt.Transport(reverseproxy.Transport)
}

The names of plugs that will be activated is taken from the RTPLUGS environment variable. Use a comma seperated list for activating more than one plug.

The namespace used is taken from the NAMESPACE environment variable or the /etc/podinfo/namespace file (via downwards api).

The servicename used is taken from the SERVICENAME environment variable or the /etc/podinfo/servicename file (via downwards api).

When the caller manages the list of plugs and their configuration (e.g. using its own config files) use NewConfigrablePlugs() instead of New(). When using NewConfigrablePlugs, the caller specify the name and namespace of the service, and also the plug list and its configuration

rt := rtplugs.NewConfigrablePlugs(servicename, namespace, pluglist, config, log)  
if rt != nil {  
    // We have at least one activated plug
    defer rt.Close()
    reverseproxy.Transport = rt.Transport(reverseproxy.Transport)
}

Use rt.Close() to gracefully shutdown the work of plugs. Graceful shutdown ensure no loss of data in plugs.

Optional alignment of logging facility and orderly shutdown

log is an optional (yet recommended in production) method to set the logger that will be used by rtplugs and all plugs. If log is set to nil, "go.uber.org/zap" Development template is used. If log is set to any other logger meeting the pluginterfaces.Logger interface this logger will be used instead.

For example:

func main() {
	logger, _ := zap.NewDevelopment()
	defer logger.Sync() // flushes buffer, if any
	log := logger.Sugar()

	url, err := url.Parse("http://127.0.0.1:8080")
	if err != nil {
		panic(err)
	}
	proxy := httputil.NewSingleHostReverseProxy(url)
	var h http.Handler = proxy

+	// Hook using RoundTripper
+	rt := rtplugs.New(log)
+	if rt != nil {
+		// We have at least one activated plug
+		defer rt.Close()
+		proxy.Transport = rt.Transport(proxy.Transport)
+	}

	http.Handle("/", h)
	log.Fatal(http.ListenAndServe(":8081", nil))
}

Documentation

Overview

The rtplugs package instruments golang http clients that supports a RoundTripper interface. It was built and tested against https://pkg.go.dev/net/http/httputil#ReverseProxy

Index

• type RoundTrip
  • func New(logger pi.Logger) (rt *RoundTrip)
  • func NewConfigrablePlugs(ctxin context.Context, logger pi.Logger, svcname string, namespace string, ...) (ctxout context.Context, rt *RoundTrip)
  • func (rt *RoundTrip) Close()
  • func (rt *RoundTrip) RoundTrip(req *http.Request) (resp *http.Response, err error)
  • func (rt *RoundTrip) Transport(t http.RoundTripper) http.RoundTripper

Types

type RoundTrip

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

An http.RoundTripper interface to be used as Transport for http clients

To extend reverseproxy use:

rt := rtplugs.New(log)
if rt != nil {
	defer rt.Close()
	reverseproxy.Transport = rt.Transport(reverseproxy.Transport)
}

While `log` is an optional logger

func New

func New(logger pi.Logger) (rt *RoundTrip)

New(pi.Logger) will attempt to strat a list of plugs

env RTPLUGS defines a comma seperated list of plug names A typical RTPLUGS value would be "rtplug,wsplug" The plugs may be added statically (using imports) or dynmaicaly (.so files)

func NewConfigrablePlugs

func NewConfigrablePlugs(ctxin context.Context, logger pi.Logger, svcname string, namespace string, plugs []string, c map[string]map[string]string) (ctxout context.Context, rt *RoundTrip)

Context() wraps an existing RoundTripper

Once the existing RoundTripper is wrapped, data flowing to and from the existing RoundTripper will be screened using the security plugs

func (*RoundTrip) Close

func (rt *RoundTrip) Close()

Close() gracefully shuts down all plugs

Note that Close does not unload the .so files, instead, it informs all loaded plugs to gracefully shutdown and cleanup

func (*RoundTrip) RoundTrip

func (rt *RoundTrip) RoundTrip(req *http.Request) (resp *http.Response, err error)

func (*RoundTrip) Transport

func (rt *RoundTrip) Transport(t http.RoundTripper) http.RoundTripper

Transport() wraps an existing RoundTripper

Once the existing RoundTripper is wrapped, data flowing to and from the existing RoundTripper will be screened using the security plugs