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.

Usage

// create a registry
reg := registrar.NewRegistry()

// registry drivers
one := &driverOne{name: "driverOne", protocol: "tcp", metadata: "this is driver one", features: registrar.Features{registrar.Feature("always double checking")}}
two := &driverTwo{name: "driverTwo", protocol: "udp", metadata: "this is driver two", features: registrar.Features{registrar.Feature("set and forget")}}
reg.Register(one.name, one.protocol, one.features, one.metadata, one)
reg.Register(two.name, two.protocol, two.features, two.metadata, two)

// do some filtering
ctx := context.Background()
reg.Drivers = reg.Using("tcp")
reg.Drivers = reg.FilterForCompatible(ctx)

// get the interfaces for use
interfaces := reg.GetDriverInterfaces()

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

Overview

Package registrar implements a variant of the registration pattern.

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) PreferDriver(drivers ...string) Drivers
  • 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. Order is preserved.

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) PreferDriver

func (r Registry) PreferDriver(drivers ...string) Drivers

PreferDriver will reorder the registry by moving preferred drivers to the start.

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.