mattermost/plugin/helpers.go

// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
// See LICENSE.txt for license information.

package plugin

import (
	"database/sql/driver"

	"github.com/mattermost/mattermost-server/v6/model"
)

// Helpers provide a common patterns plugins use.
//
// Plugins obtain access to the Helpers by embedding MattermostPlugin.
type Helpers interface {
	// EnsureBot either returns an existing bot user matching the given bot, or creates a bot user from the given bot.
	// A profile image or icon image may be optionally passed in to be set for the existing or newly created bot.
	// Returns the id of the resulting bot.
	//
	// Minimum server version: 5.10
	EnsureBot(bot *model.Bot, options ...EnsureBotOption) (string, error)

	// KVSetJSON stores a key-value pair, unique per plugin, marshalling the given value as a JSON string.
	//
	// Deprecated: Use p.API.KVSetWithOptions instead.
	//
	// Minimum server version: 5.2
	KVSetJSON(key string, value interface{}) error

	// KVCompareAndSetJSON updates a key-value pair, unique per plugin, but only if the current value matches the given oldValue after marshalling as a JSON string.
	// Inserts a new key if oldValue == nil.
	// Returns (false, err) if DB error occurred
	// Returns (false, nil) if current value != oldValue or key already exists when inserting
	// Returns (true, nil) if current value == oldValue or new key is inserted
	//
	// Deprecated: Use p.API.KVSetWithOptions instead.
	//
	// Minimum server version: 5.12
	KVCompareAndSetJSON(key string, oldValue interface{}, newValue interface{}) (bool, error)

	// KVCompareAndDeleteJSON deletes a key-value pair, unique per plugin, but only if the current value matches the given oldValue after marshalling as a JSON string.
	// Returns (false, err) if DB error occurred
	// Returns (false, nil) if current value != oldValue or the key was already deleted
	// Returns (true, nil) if current value == oldValue
	//
	// Minimum server version: 5.16
	KVCompareAndDeleteJSON(key string, oldValue interface{}) (bool, error)

	// KVGetJSON retrieves a value based on the key, unique per plugin, unmarshalling the previously set JSON string into the given value. Returns true if the key exists.
	//
	// Minimum server version: 5.2
	KVGetJSON(key string, value interface{}) (bool, error)

	// KVSetWithExpiryJSON stores a key-value pair with an expiry time, unique per plugin, marshalling the given value as a JSON string.
	//
	// Deprecated: Use p.API.KVSetWithOptions instead.
	//
	// Minimum server version: 5.6
	KVSetWithExpiryJSON(key string, value interface{}, expireInSeconds int64) error

	// KVListWithOptions returns all keys that match the given options.  If no options are provided then all keys are returned.
	//
	// Minimum server version: 5.6
	KVListWithOptions(options ...KVListOption) ([]string, error)

	// CheckRequiredServerConfiguration checks if the server is configured according to
	// plugin requirements.
	//
	// Minimum server version: 5.2
	CheckRequiredServerConfiguration(req *model.Config) (bool, error)

	// ShouldProcessMessage returns if the message should be processed by a message hook.
	//
	// Use this method to avoid processing unnecessary messages in a MessageHasBeenPosted
	// or MessageWillBePosted hook, and indeed in some cases avoid an infinite loop between
	// two automated bots or plugins.
	//
	// The behaviour is customizable using the given options, since plugin needs may vary.
	// By default, system messages and messages from bots will be skipped.
	//
	// Minimum server version: 5.2
	ShouldProcessMessage(post *model.Post, options ...ShouldProcessMessageOption) (bool, error)

	// InstallPluginFromURL installs the plugin from the provided url.
	//
	// Minimum server version: 5.18
	InstallPluginFromURL(downloadURL string, replace bool) (*model.Manifest, error)

	// GetPluginAssetURL builds a URL to the given asset in the assets directory.
	// Use this URL to link to assets from the webapp, or for third-party integrations with your plugin.
	//
	// Minimum server version: 5.2
	GetPluginAssetURL(pluginID, asset string) (string, error)
}

// HelpersImpl implements the helpers interface with an API that retrieves data on behalf of the plugin.
type HelpersImpl struct {
	API API
}

// ResultContainer contains the output from the LastInsertID
// and RowsAffected methods for a given set of rows.
// It is used to embed another round-trip to the server,
// and helping to avoid tracking results on the server.
type ResultContainer struct {
	LastID            int64
	LastIDError       error
	RowsAffected      int64
	RowsAffectedError error
}

// Driver is a sql driver interface that is used by plugins to perform
// raw SQL queries without opening DB connections by themselves. This interface
// is not subject to backward compatibility guarantees and is only meant to be
// used by plugins built by the Mattermost team.
type Driver interface {
	// Connection
	Conn(isMaster bool) (string, error)
	ConnPing(connID string) error
	ConnClose(connID string) error
	ConnQuery(connID, q string, args []driver.NamedValue) (string, error)         // rows
	ConnExec(connID, q string, args []driver.NamedValue) (ResultContainer, error) // result

	// Transaction
	Tx(connID string, opts driver.TxOptions) (string, error)
	TxCommit(txID string) error
	TxRollback(txID string) error

	// Statement
	Stmt(connID, q string) (string, error)
	StmtClose(stID string) error
	StmtNumInput(stID string) int
	StmtQuery(stID string, args []driver.NamedValue) (string, error)         // rows
	StmtExec(stID string, args []driver.NamedValue) (ResultContainer, error) // result

	// Rows
	RowsColumns(rowsID string) []string
	RowsClose(rowsID string) error
	RowsNext(rowsID string, dest []driver.Value) error
	RowsHasNextResultSet(rowsID string) bool
	RowsNextResultSet(rowsID string) error
	RowsColumnTypeDatabaseTypeName(rowsID string, index int) string
	RowsColumnTypePrecisionScale(rowsID string, index int) (int64, int64, bool)

	// TODO: add this
	// RowsColumnScanType(rowsID string, index int) reflect.Type

	// Note: the following cannot be implemented because either MySQL or PG
	// does not support it. So this implementation has to be a common subset
	// of both DB implementations.
	// RowsColumnTypeLength(rowsID string, index int) (int64, bool)
	// RowsColumnTypeNullable(rowsID string, index int) (bool, bool)
	// ResetSession(ctx context.Context) error
	// IsValid() bool
}