Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Add ¶
func Add(pl Impl)
Add adds a new plugin which will be loaded on the server. Plugins should be added in an init() function. Everything else, such as loading plugin data is handled by the server. Panics if a plugin is added after the server has started.
func Initialize ¶
Initialize does all the steps necessary for the plugins to load. Returns a function that executes the Run() stage, which should be called after the server has started. It should NOT be called by any plugin or external module. Will panic if called twice.
Types ¶
type Config ¶
type Config struct {
// Path is the filepath of the configuration file, relative to the plugin directory. So, if your plugin is named
// foo, and you want to create a bar.json file in the ./plugins/foo/ folder, the path should be "bar.json". The path
// CAN NOT be an absolute path! The file extension will be used to determine the type of config file.
//
// Supported formats and the respective library used to decode/encode them are:
// - JSON (https://github.com/muhammadmuzzammil1998/jsonc)
// - TOML (https://github.com/pelletier/go-toml/v2)
// - YAML (https://github.com/go-yaml/yaml)
//
Path string
// Default allows the default content of the config file to be specified for when the file does not yet exist. If
// left empty, the Value will be marshaled and stored instead. If a value different from an empty string is set,
// the resulting configuration will also be unmarshalled again into the Value.
Default string
// Value should be a pointer to the data type to decode the configuration file into. This is usually a (pointer to)
// a struct or a map.
Value any
}
Config represent a specification for a plugin configuration file. Creating the file if not present and loading it are all handled by the server. This is meant strictly for configuration files: if your plugin edits the file during runtime this should not be used.
type Impl ¶
type Impl interface {
// Name returns the displayed name of the plugin. Currently, this is used to name the plugin's data folder. The name
// must be a valid name for a folder. The plugin name should stay the same when the server is running!
Name() string
// Setup is the first stage of plugin initialization. It is called synchronously, and in the order that the plugins
// were registered. Logic that should run before the server has started should be called here. An example use is
// defining and loading the plugin's configuration files.
Setup(this *Plugin) error
// Run is called right after the server has started. This will be done in a new goroutine created for the plugin.
// A context is passed that will be cancelled when the server shuts down. If this function returns, the plugin is
// considered to have stopped running.
// To wait for server shutdown, try to receive from the ctx.Done() channel until it closes.
Run(ctx context.Context, this *Plugin)
}
Impl is the implementation of a plugin. It is a module that extends the server functionality in different ways. It is used to set up the server before running, so things like configuration files can be created and loaded.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin stores information about a certain plugin. It can be used by the plugin implementation to access certain plugin APIs such as painlessly creating & loading configuration files.
func (*Plugin) DataFolder ¶
DataFolder returns the absolute path of the plugin's data folder. This is where configuration files and persistent plugin data should be stored. Upon calling this function, the folder will be created if it does not yet exist. If this function is never called, then no data folder is created.
func (*Plugin) Impl ¶
Impl returns the underlying implementation of the plugin. This is the interface that gets added as a plugin in plugin.Add().
func (*Plugin) Logger ¶
Logger returns a logger meant to be used by the plugin. It has an additional field displaying the plugin the logged message comes from.
func (*Plugin) WithConfigs ¶
WithConfigs accepts one or more Config structs that define configuration files for a plugin. A configuration for the plugin will immediately be loaded, and if necessary created. The loading will be done in the order the files are passed and will halt on the first error, which will immediately be returned.
Source Files