registrar

README

Registrar

A Go library implementing a variant of the registration pattern

Description

The registration, driver, strategy or singleton pattern is the idea that implementations of the same functionality are built up into a registry for use and/or selection at runtime. This pattern is used in a few places in the standard library with the net/http, database/sql, and flag packages. In my experience, most notably with the registration of database/sql drivers.

This library is a variant of this pattern. Its use case is to build up a registry of implementations which can be filtered or ordered and returned as a generic slice of interface{}. These interfaces can then be passed along to functions that can type assert or switch case on them to run concrete interface methods. The registration of a driver in this package is explicit (Registrar.Register()). All magic is purposefully avoided. See the examples directory for code snippets.

Background

This library is produced as a general library but was built from its original use-case in bmclib. The purpose of bmclib is to interact with Baseboard Management Controllers (BMC). There are many different ways to interact with a single BMC, so a registry of the different implementations is built up and then when a request to perform a single action (power state for example) is tried with all the different implementations until one works.

References

• https://dave.cheney.net/2017/06/11/go-without-package-scoped-variables
• https://eli.thegreenplace.net/2019/design-patterns-in-gos-databasesql-package/
• https://peter.bourgon.org/blog/2017/06/09/theory-of-modern-go.html

Documentation

Index

• type Driver
• type Drivers
• type Feature
• type Features
• type Option
  • func WithDrivers(drivers Drivers) Option
  • func WithLogger(logger logr.Logger) Option
• type Registry
  • func NewRegistry(opts ...Option) *Registry
  • func (r Registry) FilterForCompatible(ctx context.Context) Drivers
  • func (r Registry) For(driver string) Drivers
  • func (r Registry) GetDriverInterfaces() []interface{}
  • func (r Registry) PreferProtocol(protocols ...string) Drivers
  • func (r *Registry) Register(name, protocol string, features Features, metadata interface{}, ...)
  • func (r Registry) Supports(features ...Feature) Drivers
  • func (r Registry) Using(proto string) Drivers
• type Verifier

Types

type Driver

type Driver struct {
	Name            string
	Protocol        string
	Features        Features
	Metadata        interface{}
	DriverInterface interface{}
}

Driver holds the info about a driver

type Drivers

type Drivers []*Driver

Drivers holds a slice of Driver types

type Feature

type Feature string

Feature represents a single feature a driver supports

type Features

type Features []Feature

Features holds the features a driver supports

type Option

type Option func(*Registry)

Option for setting optional Registry values

func WithDrivers

func WithDrivers(drivers Drivers) Option

WithDrivers sets the drivers

func WithLogger

func WithLogger(logger logr.Logger) Option

WithLogger sets the logger

type Registry

type Registry struct {
	Logger  logr.Logger
	Drivers Drivers
}

Registry holds the registered drivers

func NewRegistry

func NewRegistry(opts ...Option) *Registry

NewRegistry returns a new Driver registry

func (Registry) FilterForCompatible

func (r Registry) FilterForCompatible(ctx context.Context) Drivers

FilterForCompatible updates the driver registry with only compatible implementations. compatible implementations are determined by running the Compatible method of the Verifier interface. registered drivers must implement the Verifier interface for this.

func (Registry) For

func (r Registry) For(driver string) Drivers

For does the actual work of filtering for a specific driver name

func (Registry) GetDriverInterfaces

func (r Registry) GetDriverInterfaces() []interface{}

GetDriverInterfaces returns a slice of just the generic driver interfaces

func (Registry) PreferProtocol

func (r Registry) PreferProtocol(protocols ...string) Drivers

PreferProtocol does the actual work of moving preferred protocols to the start of the driver registry

func (*Registry) Register

func (r *Registry) Register(name, protocol string, features Features, metadata interface{}, driverInterface interface{})

Register will add a driver a Driver registry

func (Registry) Supports

func (r Registry) Supports(features ...Feature) Drivers

Supports does the actual work of filtering for specific features

func (Registry) Using

func (r Registry) Using(proto string) Drivers

Using does the actual work of filtering for a specific protocol type

type Verifier

type Verifier interface {
	Compatible(context.Context) bool
}

Verifier allows implementations to define a method for determining whether a driver is compatible for use