plugin

README

plugin-api

This repository consisted of APIs used in gotify plugins.

Usage

Plugin API

https://gotify.net/docs/plugin

CLI tools

github.com/gotify/cmd/gomod-cap

Since go.mod follows a minimal version selection, packages are built with the lowest common version requirement defined in go.mod. This poses a problem when developing plugins:

If the gotify server is built with the following go.mod:

require some/package v0.1.0

But when the plugin is built, it used a newer version of this package:

require some/package v0.1.1

Since the server is built with v0.1.0 and the plugin is built with v0.1.1 of some/package, the built plugin could not be loaded due to different import package versions.

gomod-cap is a simple util to ensure that plugin go.mod files does not have higher version requirements than the main gotify go.mod file.

To resolve all incompatible requirements:

$ go run github.com/gotify/plugin-api/cmd/gomod-cap -from /path/to/gotify/server/go.mod -to /path/to/plugin/go.mod

To only check for incompatible requirements(useful in CI):

$ go run github.com/gotify/plugin-api/cmd/gomod-cap -from /path/to/gotify/server/go.mod -to /path/to/plugin/go.mod -check=true

Documentation

Index

• type Configurer
• type Displayer
• type Info
• type Message
• type MessageHandler
• type Messenger
• type Plugin
• type StorageHandler
• type Storager
• type UserContext
• type Webhooker

Types

type Configurer

type Configurer interface {
	Plugin
	// DefaultConfig will be called on plugin first run to set the default config.
	// DefaultConfig will also be used if the provided config cannot be validate during initialization.
	// The default configuration will be provided to the user for future editing. Used for generating schemas and unmarshaling.
	DefaultConfig() interface{}
	// ValidateAndSetConfig will be called every time the plugin is initialized or the configuration has been changed by the user.
	// Plugins should check whether the configuration is valid and optionally return an error.
	// Parameter is guaranteed to be the same type as the return type of DefaultConfig()
	ValidateAndSetConfig(c interface{}) error
}

Configurer is the interface plugins should implement in order to provide configuration interface to the user

type Displayer

type Displayer interface {
	Plugin
	GetDisplay(location *url.URL) string
}

Displayer is the interface plugins should implement to show a text to the user. The text will appear on the plugin details page and can be multi-line. Markdown syntax is allowed. Good for providing dynamically generated instructions to the user. Location is the current location the user is accessing the API from, nil if not recoverable. Location contains the path to the display api endpoint, you may only need the base url. Example: https://gotify.net/plugin/5/display

type Info

type Info struct {
	Version     string
	Author      string
	Name        string
	Website     string
	Description string
	License     string
	ModulePath  string
}

Info is returned by the exported plugin function GetPluginInfo() for identification plugins are identified by their ModulePath, gotify will refuse to load plugins with empty ModulePath

type Message

type Message struct {
	Message  string
	Title    string
	Priority int
	Extras   map[string]interface{}
}

Message describes a message to be send by MessageHandler#SendMessage

type MessageHandler

type MessageHandler interface {
	// SendMessage sends a message with the given information in the request.
	SendMessage(msg Message) error
}

MessageHandler consists of message callbacks to be used by plugins.

type Messenger

type Messenger interface {
	Plugin
	// SetMessageHandler is called every time the plugin is initialized.
	// Plugins should record the handler and use the callbacks provided in the handler to send messages.
	SetMessageHandler(h MessageHandler)
}

Messenger is the interface plugins should implement to send messages.

type Plugin

type Plugin interface {
	// Enable is called every time a plugin is started. Spawn custom goroutines here for polling, etc.
	// It is always called after ^Set.*Handler$
	Enable() error
	// Disable is called every time a plugin is disabled. Plugins should stop all custom goroutines here.
	Disable() error
}

Plugin is the interface every plugin need to implement

type StorageHandler

type StorageHandler interface {
	Save(b []byte) error
	Load() ([]byte, error)
}

StorageHandler consists callbacks used to perform read/writes to the persistent storage for plugins.

type Storager

type Storager interface {
	Plugin
	SetStorageHandler(handler StorageHandler)
}

Storager is the interface plugins should implement to use persistent storage.

type UserContext

type UserContext struct {
	ID    uint
	Name  string
	Admin bool
}

UserContext is provided when calling New to create a plugin instance for each user

type Webhooker

type Webhooker interface {
	Plugin
	// RegisterWebhook is called for plugins to create their own handler.
	RegisterWebhook(basePath string, mux *gin.RouterGroup)
}

Webhooker is the interface plugin should implement to register custom handlers.