api

type Constraints struct {
	// Min is the minimum number of plugins required of a specific type. If
	// zero, there is no lower bound (i.e. the plugin type is optional).
	Min int

	// Max is the maximum number of plugins required of a specific type. If
	// zero, there is no upper bound.
	Max int
}

type Facade interface {
	// ServiceClient is used to initialize the service client with the
	// connection to the plugin providing the service server.
	ServiceClient

	// InitInfo is used to initialize the facade with information for the
	// loaded plugin providing the service server.
	InitInfo(info Info)

	// InitLog initializes the facade with the logger for the loaded plugin
	// that provides the service server.
	InitLog(log *slog.Logger)

	Version() uint
}

type Info interface {
	// The name of the plugin
	Name() string

	// The type of the plugin
	Type() string

	// Tags associated with the plugin
	Tags() []string

	// Build of the plugin
	Build() string

	// Version of the plugin
	Version() uint
}

type NeedsHostServices interface {
	// BrokerHostServices is invoked by the plugin loader and provides a broker
	// that can be used by plugins/services to initialize clients to host
	// services. If an error is returned, plugin loading will fail.
	// This gives server implementations control over whether or not the
	// absence of a particular host service is a catastrophic failure.
	BrokerHostServices(ServiceBroker) error
}

type NeedsLogger interface {
	SetLogger(logger hclog.Logger)
}

type PluginClient interface {
	ServiceClient

	// Type returns the type of plugin
	Type() string
}

type PluginRepo interface {
	ServiceRepo

	// Constraints returns the constraints required by the plugin repository.
	// The Load function will ensure that these constraints are satisfied before
	// returning successfully.
	Constraints() Constraints
}

type PluginServer interface {
	ServiceServer

	// Type returns the type of plugin
	Type() string
}

type Repository interface {
	// Plugins returns a map of plugin repositories, keyed by the plugin type.
	Plugins() map[string]PluginRepo

	// Services returns service repositories.
	Services() []ServiceRepo
}

type ServiceBroker interface {
	// BrokerClient initializes the passed in host service client. If the
	// host service is not available, the host service client will
	// remain uninitialized and the function will return false.
	BrokerClient(ServiceClient) bool
}

type ServiceClient interface {
	// GRPCServiceName returns the full gRPC service name (e.g.
	GRPCServiceName() string

	// InitClient initializes the client using the given gRPC client
	// connection. It returns the client implementation that was initialized.
	InitClient(conn grpc.ClientConnInterface) any
}

type ServiceRepo interface {
	// Binder returns a function that is used by the catalog system to "bind"
	// the facade returned by selected version to the repository. It MUST
	// return void and take a single argument of type X, where X can be
	// assigned to by any of the facade implementation types returned by the
	// provided versions (see Versions).
	Binder() any

	// Versions returns the versions supported by the repository, ordered by
	// most to least preferred. The first version supported by the plugin will
	// be used. When a deprecated version is bound, warning messaging will
	// recommend the first version in the list as a replacement, unless it is
	// also deprecated.
	Versions() []Version

	// Clear is called when loading fails to clear the repository of any
	// previously bound facades.
	Clear()
}

type ServiceServer interface {
	// GRPCServiceName returns the full gRPC service name (e.g.
	GRPCServiceName() string

	// RegisterServer registers the server implementation with the given gRPC server.
	// It returns the implementation that was registered.
	RegisterServer(server *grpc.Server) any
}

type Version interface {
	// New returns a new facade for this version. Instantiated facades are only
	// bound via the repo binder when they match a gRPC service name provided
	// by the plugin.
	New() Facade

	Deprecated() bool
}