v1

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2024 License: ISC Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterAuthManagerInitFn 

func RegisterAuthManagerInitFn(pluginID string, fn func(InitArgs) (AuthManager, error))

RegisterAuthManagerInitFn registers an AuthManager initialization function with this package. This should be done by the plugin implementation as part of its package level init() function. The registered function is called at runtime to initialize the AuthManager.

func RegisterPluginInitFn 

func RegisterPluginInitFn(pluginID string, fn func(InitArgs) (Plugin, error))

RegisterPluginInitFn registers a Plugin initialization function with this package. This should be done by the plugin implementation as part of its package level init() function. The registered function is called at runtime to initialize the Plugin.

func RegisterUserManagerInitFn 

func RegisterUserManagerInitFn(pluginID string, fn func(InitArgs) (UserManager, error))

RegisterUserManagerInitFn registers a UserManager initialization function with this package. This should be done by the plugin implementation as part of its package level init() function. The registered function is called at runtime to initialize the UserManager .

Types

type AuthManager 

type AuthManager interface {
	// ID returns the plugin ID.
	ID() string

	// Version returns the lowest supported plugin API version.
	Version() uint32

	// Authorize checks if the user is authorized to execute a plugin command.
	//
	// A UserError is returned if the user is not authorized.
	Authorize(AuthorizeArgs) error
}

AuthManager provides user authorization for plugin commands.

Any changes made to the Session or User during method execution will be persisted by the caller.

func NewAuthManager 

func NewAuthManager(pluginID string, args InitArgs) (AuthManager, error)

NewAuthManager uses the registered authManager initialization function to initialize and return an AuthManager.

type AuthorizeArgs 

type AuthorizeArgs struct {
	Session  *Session
	User     *User
	PluginID string
	Version  uint32 // Plugin API version
	Cmd      string
}

AuthorizeArgs contains the arguments for the Authorize method.

type Cmd 

type Cmd struct {
	PluginID string
	Version  uint32 // Plugin API version
	Cmd      string
	Payload  string // JSON encoded
}

Cmd represents a plugin command.

type HookArgs 

type HookArgs struct {
	Type  HookT
	Cmd   Cmd
	Reply *Reply
	User  *User
}

HookArgs contains the arguments for the plugin hook methods.

type HookT 

type HookT string

HookT represents a plugin hook. Pre hooks allow plugins to add plugin specific validation onto external plugin commands. Post hooks allow plugins to update caches with any necessary changes that result from the execution of the command. 

const (
	// HookInvalid is an invalid hook.
	HookInvalid HookT = "invalid"

	// HookPreNewUser is the hook that is executed before a NewUser command
	// is executed.
	HookPreNewUser HookT = "pre-new-user"

	// HookPostNewUser is the hook that is executed after the successful
	// execution of a NewUser command.
	HookPostNewUser HookT = "post-new-user"

	// HookPreWrite is the hook that is executed before a plugin write command
	// is executed.
	HookPreWrite HookT = "pre-write"

	// HookPostWrite is the hook that is executed after the successful execution
	// of a plugin write command.
	HookPostWrite HookT = "post-write"
)

type InitArgs 

type InitArgs struct {
	Settings []Setting
}

InitArgs contains the arguments used to initialize the plugin interface types.

type Plugin 

type Plugin interface {
	// ID returns the plugin ID.
	ID() string

	// Version returns the lowest supported plugin API version.
	Version() uint32

	// SetPermission sets the user permission level for a command.
	SetPermission(cmd, permissionLevel string)

	// Permissions returns the user permissions for each plugin commands. These
	// are provided to the AuthPlugin on startup. The AuthPlugin handles user
	// authorization at runtime.
	Permissions() map[string]string // [cmd]permissionLevel

	// Hook executes a plugin hook.
	Hook(HookArgs) error

	// HookTx executes a plugin hook using a database transaction.
	HookTx(*sql.Tx, HookArgs) error

	// WriteTx executes a write plugin command using a database transaction.
	WriteTx(*sql.Tx, WriteArgs) (*Reply, error)

	// Read executes a read plugin command.
	Read(ReadArgs) (*Reply, error)

	// ReadTx executes a read plugin command using a database transaction.
	ReadTx(*sql.Tx, ReadArgs) (*Reply, error)
}

Plugin represents a politeia plugin.

Updates to the User object plugin data will be persisted by the backend for operations that are part of write commands. Updates made during read-only commands are ignored.

func NewPlugin 

func NewPlugin(pluginID string, args InitArgs) (Plugin, error)

NewPlugin uses the registered plugin initialization function to initialize and return a Plugin.

type PluginData 

type PluginData struct {
	// contains filtered or unexported fields
}

PluginData contains the user data that is owned by the plugin.

These fields can be updated by the plugin during execution of write commands. Updates are persisted by the backend on successful completion of the plugin command execution. Any updates made during the execution of read-only commands are ignored.

The encrypted data blob will be provided to the plugin as clear text, but will be saved to the database by the backend as encrypted. The plugin does not need to worry about encrypting/decrypting the data.

func NewPluginData 

func NewPluginData(clearText, encrypted []byte) *PluginData

NewPluginData returns a new PluginData.

func (*PluginData) ClearText 

func (d *PluginData) ClearText() []byte

ClearText returns the clear text plugin data.

func (*PluginData) Encrypted 

func (d *PluginData) Encrypted() []byte

Encrypted returns the encrypted plugin data. The data is returned as clear text to the plugin, but is saved to the database as encrypted. The plugin does not need to worry about encrypting/decrypting the data.

func (*PluginData) SetClearText 

func (d *PluginData) SetClearText(b []byte)

SetClearText updates the clear text plugin data.

func (*PluginData) SetEncrypted 

func (d *PluginData) SetEncrypted(b []byte)

SetEncrypted updates the encrypted plugin data. The provided data should be clear text. It will be encrypted prior to being saved to the database. The plugin does not need to worry about encrypting/decrypting the data.

func (*PluginData) Updated 

func (d *PluginData) Updated() bool

Updated returns whether the plugin data has been updated.

type ReadArgs 

type ReadArgs struct {
	Cmd  Cmd
	User *User
}

ReadArgs contain the arguments for the plugin read methods.

type Reply 

type Reply struct {
	Payload string // JSON encoded
	Error   error
}

Reply is the reply to a plugin command.

type Session 

type Session struct {
	UserID    string
	CreatedAt int64

	// Delete can be set by the AuthManager plugin to instruct the backend to
	// delete the session.
	Delete bool
}

Session contains the data that is saved as part of a user session.

Plugins do not have direct access to the sessions database, but the AuthManager plugin is able to update fields on this session struct. Updates are saved to the sessions database by the backend.

type Setting 

type Setting struct {
	Key   string // Name of setting
	Value string // Value of setting
}

Setting represents a configurable plugin setting.

The value can either contain a single value or multiple values. Multiple values will be formatted as a JSON encoded []string.

type User 

type User struct {
	ID         uuid.UUID // Unique ID
	PluginData *PluginData
}

User represents a politeia user. The user will contain the PluginData for the plugin that is executing the command or hook.

type UserError 

type UserError struct {
	PluginID     string `json:"pluginid"`
	ErrorCode    uint32 `json:"errorcode"`
	ErrorContext string `json:"errorcontext,omitempty"`
}

UserError is the reply that is returned when a plugin command encounters an error that was caused by the user.

func (UserError) Error 

func (e UserError) Error() string

Error satisfies the error interface.

type UserManager 

type UserManager interface {
	// ID returns the plugin ID.
	ID() string

	// Version returns the lowest supported plugin API version.
	Version() uint32

	// NewUserCmd executes a command that results in a new user being added to
	// the database. The user provided to this method is a newly created user
	// that has not been inserted into the user database yet, but will be
	// inserted if this command executes successfully without any user errors
	// or unexpected errors.
	NewUser(*sql.Tx, WriteArgs) (*Reply, error)
}

UserManager provides methods that result in state changes to the user database that cannot be done inside of plugins.

For example, plugins do not have access to the user database methods that insert users into the database. These actions must be done by the backend. The UserManager interface allows plugins to add plugin specific behavior onto these actions.

Any changes made to the User during method execution will be persisted by the caller.

func NewUserManager 

func NewUserManager(pluginID string, args InitArgs) (UserManager, error)

NewUserManager uses the registered user manager initialization function to initialize and return a UserManager.

type WriteArgs 

type WriteArgs struct {
	Cmd  Cmd
	User *User
}

WriteArgs contain the arguments for the plugin write methods.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.