github.com/decred/politeia@v1.4.0/politeiawww/plugin/v1/plugin.go (about)

     1  // Copyright (c) 2022 The Decred developers
     2  // Use of this source code is governed by an ISC
     3  // license that can be found in the LICENSE file.
     4  
     5  package v1
     6  
     7  import (
     8  	"database/sql"
     9  	"fmt"
    10  )
    11  
    12  // Plugin represents a politeia plugin.
    13  //
    14  // Updates to the User object plugin data will be persisted by the backend for
    15  // operations that are part of write commands. Updates made during read-only
    16  // commands are ignored.
    17  type Plugin interface {
    18  	// ID returns the plugin ID.
    19  	ID() string
    20  
    21  	// Version returns the lowest supported plugin API version.
    22  	Version() uint32
    23  
    24  	// SetPermission sets the user permission level for a command.
    25  	SetPermission(cmd, permissionLevel string)
    26  
    27  	// Permissions returns the user permissions for each plugin commands. These
    28  	// are provided to the AuthPlugin on startup. The AuthPlugin handles user
    29  	// authorization at runtime.
    30  	Permissions() map[string]string // [cmd]permissionLevel
    31  
    32  	// Hook executes a plugin hook.
    33  	Hook(HookArgs) error
    34  
    35  	// HookTx executes a plugin hook using a database transaction.
    36  	HookTx(*sql.Tx, HookArgs) error
    37  
    38  	// WriteTx executes a write plugin command using a database transaction.
    39  	WriteTx(*sql.Tx, WriteArgs) (*Reply, error)
    40  
    41  	// Read executes a read plugin command.
    42  	Read(ReadArgs) (*Reply, error)
    43  
    44  	// ReadTx executes a read plugin command using a database transaction.
    45  	ReadTx(*sql.Tx, ReadArgs) (*Reply, error)
    46  }
    47  
    48  // HookArgs contains the arguments for the plugin hook methods.
    49  type HookArgs struct {
    50  	Type  HookT
    51  	Cmd   Cmd
    52  	Reply *Reply
    53  	User  *User
    54  }
    55  
    56  // WriteArgs contain the arguments for the plugin write methods.
    57  type WriteArgs struct {
    58  	Cmd  Cmd
    59  	User *User
    60  }
    61  
    62  // ReadArgs contain the arguments for the plugin read methods.
    63  type ReadArgs struct {
    64  	Cmd  Cmd
    65  	User *User
    66  }
    67  
    68  // Cmd represents a plugin command.
    69  type Cmd struct {
    70  	PluginID string
    71  	Version  uint32 // Plugin API version
    72  	Cmd      string
    73  	Payload  string // JSON encoded
    74  }
    75  
    76  // Reply is the reply to a plugin command.
    77  type Reply struct {
    78  	Payload string // JSON encoded
    79  	Error   error
    80  }
    81  
    82  // HookT represents a plugin hook. Pre hooks allow plugins to add plugin
    83  // specific validation onto external plugin commands. Post hooks allow plugins
    84  // to update caches with any necessary changes that result from the execution
    85  // of the command.
    86  type HookT string
    87  
    88  const (
    89  	// HookInvalid is an invalid hook.
    90  	HookInvalid HookT = "invalid"
    91  
    92  	// HookPreNewUser is the hook that is executed before a NewUser command
    93  	// is executed.
    94  	HookPreNewUser HookT = "pre-new-user"
    95  
    96  	// HookPostNewUser is the hook that is executed after the successful
    97  	// execution of a NewUser command.
    98  	HookPostNewUser HookT = "post-new-user"
    99  
   100  	// HookPreWrite is the hook that is executed before a plugin write command
   101  	// is executed.
   102  	HookPreWrite HookT = "pre-write"
   103  
   104  	// HookPostWrite is the hook that is executed after the successful execution
   105  	// of a plugin write command.
   106  	HookPostWrite HookT = "post-write"
   107  )
   108  
   109  // UserError is the reply that is returned when a plugin command encounters an
   110  // error that was caused by the user.
   111  type UserError struct {
   112  	PluginID     string `json:"pluginid"`
   113  	ErrorCode    uint32 `json:"errorcode"`
   114  	ErrorContext string `json:"errorcontext,omitempty"`
   115  }
   116  
   117  // Error satisfies the error interface.
   118  func (e UserError) Error() string {
   119  	return fmt.Sprintf("%v plugin user error: %v", e.PluginID, e.ErrorCode)
   120  }