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.

Usage

For deployment

All you need is a launch script like below. It uhm, should be pretty self-explanatory.

Expand

package main

import (
    "os"
    "os/signal"
    "syscall"

    "codeberg.org/libreedu/common/log"
    "pkg.bitpond.org/hub"

    auth_userpass "pkg.bitpond.org/hub/plugins/auth_userpass/import"
    core "pkg.bitpond.org/hub/plugins/core/import"
    example "pkg.bitpond.org/hub/plugins/example/import"
)

func main() {
    logger := log.New(os.Stdout, "hub-dist")
    defer logger.Recover()(true)

    manager, err := hub.GetDefaultManager(logger)
    if err != nil {
        panic(err.Error())
    }
    manager.AddPlugins(core.Plugin, example.Plugin, auth_userpass.Plugin)
    manager.Finalize()
    go manager.Listen(nil)

    ch := make(chan os.Signal, 1)
    signal.Notify(ch)
    for {
        switch <-ch {
        case os.Interrupt, syscall.SIGTERM, syscall.SIGINT:
            logger.Infof("Received interrupt signal, exiting")
            manager.Shutdown()
            return
        }
    }
}

While it is possible to use plugins distributed as ELF (see Manager.AddPluginFile), it is discouraged because the versions of bitpond Hub and all of its dependencies must be precisely equal to those required by the plugin file.

There's a problem though: you can't use the web interfaces for some plugins. Many plugins use compiled resources which you do not generally want to store in version control. If you need any of those resources, what you can do instead is use vendoring for your module (run go mod vendor), with a tool such as modvendor (modvendor -copy="**/hubplugin.just **/embed/**/*.* **/web/**/*.*" -v), and then run just -f path/to/hubplugin.just preflight in each of the plugin directories. In shell script, this can be done automatically with:

for file in $(find vendor -name hubplugin.just); do just -f "$file" preflight; done

So this might be a good Justfile:

dist: vendor preflight
  mkdir -p bin
  go build -o ./hub -trimpath -buildmode pie .

vendor:
  go mod vendor
  go run github.com/goware/modvendor@latest -copy="**/web/**/*.*" -v

preflight:
  for file in $(find vendor -name hubplugin.just); do just -f "$file" preflight; done

For plugin development

For the most part, you can just follow the example plugin template. If you want your plugin to be loadable as a file by itself, you can use -buildmode plugin and a small file like this:

package main
import plugin "codeberg.org/.../import-path"
var Plugin = plugin.Plugin

If you need to embed any compiled resources, without including them in version control, you can write a Justfile in your module with the name hubplugin.just which can be run by people with the simple build scripts above. Then you can use go:embed directives like usual. (Note that Justfiles always run in their containing directory.)

Also, as above, if you want to embed non-Go files please don't include a . in your directory names and put them all in a folder named web or embed.

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.

For documentation of plugin types, see the package pkg.bitpond.org/hub/internal/types

Index

• Variables
• type APIPlugin
• type CrossPlugin
• type DB
• type DatabasePlugin
• type Manager
  • func GetDefaultManager(logger *log.Logger) (Manager, error)
  • func GetManager(logger *log.Logger, dsn string) (Manager, error)
• type Plugin
• type PluginParams

Variables

var Version string

Types

type APIPlugin

type APIPlugin = types.APIPlugin

A plugin with an API router.

type CrossPlugin

type CrossPlugin = types.CrossPlugin

A plugin that extends another plugin, or just has access to the plugin map.

type DB

type DB = types.DB

type DatabasePlugin

type DatabasePlugin = types.DatabasePlugin

A plugin with managed file-based SQL migrations. Migrations() returns a map of Unix timestamps to Go migrations. Any migrations since the last are each executed until one throws an error. On error, Destroy() is called, the database is restored, and an error is logged.

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)
	AddPluginFile(filename string) 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. Listen will not modify a passed Server
	// except for the 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)

func GetManager

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

type Plugin

type Plugin = types.Plugin

A plugin.

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

type PluginParams

type PluginParams = types.PluginParams