hub

README

hub

A plugin-based application framework, for one app or many! Use this as a Nextcloud-like platform, or just to bootstrap your (AGPLv3) app.

Documentation

Overview

Currently this package only contains the definitions for various plugin types. It is planned to contain a plugin manager interface and an implementation of one to make simple "startup scripts" listing plugins.

Index

• type APIPlugin
• type CrossPlugin
• type DB
  • func (db *DB) CheckAuthToken(token string) (models.User, error)
  • func (db *DB) GetAuthToken(token string) (models.AuthToken, error)
  • func (db *DB) GetUser(id string) (models.User, error)
  • func (db *DB) IssueAuthToken(u models.User) (token string, err error)
• type Manager
  • func GetDefaultManager(logger *log.Logger) (Manager, error)
  • func GetManager(logger *log.Logger, dsn string) (Manager, error)
• type Plugin
• type PluginParams

Types

type APIPlugin

type APIPlugin interface {
	Plugin
	// A router mounted on /. Generally, keep API extensions inside of
	// `/api/`; this interface gives / for well-known URIs, etc.
	Route(chi.Router)
}

A plugin with an API router.

type CrossPlugin

type CrossPlugin interface{ Plugin }

A plugin that extends another plugin.

type DB

type DB struct{ *bun.DB }

func (*DB) CheckAuthToken

func (db *DB) CheckAuthToken(token string) (models.User, error)

func (*DB) GetAuthToken

func (db *DB) GetAuthToken(token string) (models.AuthToken, error)

func (*DB) GetUser

func (db *DB) GetUser(id string) (models.User, error)

func (*DB) IssueAuthToken

func (db *DB) IssueAuthToken(u models.User) (token string, err error)

type Manager

type Manager interface {
	// On error, returns the index of the plugin erroring and the error
	// received, or “(-1, nil)“ if all plugins initialized successfully.
	AddPlugins(...Plugin) (int, error)
	GetPluginMap() map[string]Plugin
	// Finishishes initializing each plugin, specifically by passing the
	// plugin map to CrossPlugins.
	Finalize()
	// Starts listening. If the Server pointer is nil, Listen will use the
	// implementation default. Implementors should not modify a passed
	// Server except its Handler.
	Listen(*http.Server)
	// Shuts down the “http.Server“ in Listen() and calls Destroy() on
	// each plugin. Returns any error in shutting down, for instance from
	// “http.Server.Shutdown()“.
	Shutdown() error
}

func GetDefaultManager

func GetDefaultManager(logger *log.Logger) (Manager, error)

Returns a Manager using “config/hub.yml“ to set up.

func GetManager

func GetManager(logger *log.Logger, dsn string) (Manager, error)

type Plugin

type Plugin interface {
	Init(*log.Logger, PluginParams) error
	// Returns the D-Bus or Java–style name for the plugin. Must not rely
	// on an earlier Init() call.
	DBusName() string
	// Function to close connections, end requests, etc.
	Destroy()
}

A plugin.

There is an example plugin in the package codeberg.org/libreedu/hub/plugins/example which simply registers the endpoint `/api/example-plugin` and returns the string "Hello, world!"

Plugins should use package-scope variables, if they must work with `-buildmode plugin`, because exported shared object types cannot maintain state.

type PluginParams

type PluginParams struct {
	// A struct containing a bun DB, generally Postgres or another system
	// supporting  PL/pgSQL. If you prefer, you can access a `*sql.DB` at
	// `plugin.DB.DB.DB`.
	//
	// Please be mindful of other plugins and contain your plugin's data
	// in its own Postgres schema.
	DB *DB
	// A Viper config object pointing to your plugin configuration. Ensure
	// that you call ReadInConfig().
	Config *viper.Viper
}