oklahomer/go-sarah

package sarah

import (
    "context"
    "errors"
    "fmt"
    "github.com/oklahomer/go-kasumi/logger"
    "reflect"
    "regexp"
    "strings"
    "sync"
)

var (
    // ErrCommandInsufficientArgument depicts an error that not enough arguments are set to CommandProps.
    // This can be returned by CommandPropsBuilder.Build.
    ErrCommandInsufficientArgument = errors.New("BotType, Identifier, InstructionFunc, MatchFunc and (Configurable)Func must be set")
)

// CommandResponse is returned by Command or ContextualFunc when the execution is finished.
type CommandResponse struct {
    // Content represents a group of data returned to the user.
    // Since this is passed to Bot.SendMessage as part of OutputMessage,
    // its type may vary depending on the Bot's integrating chat service.
    Content interface{}

    // UserContext represents a user's contextual state to be stored.
    // When this is non-nil and a UserContextStorage is present for the Bot, this value is passed to UserContextStorage.
    // The user's next Input is fed to UserContext.Next so the user can continue the interaction until UserContext is no longer returned.
    UserContext *UserContext
}

// Command defines an interface that all executable command MUST satisfy.
// This is executed against a user's input.
type Command interface {
    // Identifier returns a unique id of this Command.
    Identifier() string

    // Execute receives an Input sent by a user and returns a response in a form of CommandResponse.
    Execute(context.Context, Input) (*CommandResponse, error)

    // Instruction returns a help message to show the Command usage to the requesting user.
    // A list of instructions may be returned to a user at once, so the message should be simple.
    Instruction(*HelpInput) string

    // Match is used to judge if this Command corresponds to the given Input.
    // If this returns true, the Bot implementation should proceed to Execute this Command with the current Input.
    Match(Input) bool
}

type commandConfigWrapper struct {
    value CommandConfig
    mutex *sync.RWMutex
}

type defaultCommand struct {
    identifier      string
    matchFunc       func(Input) bool
    instructionFunc func(*HelpInput) string
    commandFunc     commandFunc
    configWrapper   *commandConfigWrapper
}

func (command *defaultCommand) Identifier() string {
    return command.identifier
}

func (command *defaultCommand) Instruction(input *HelpInput) string {
    return command.instructionFunc(input)
}

func (command *defaultCommand) Match(input Input) bool {
    return command.matchFunc(input)
}

func (command *defaultCommand) Execute(ctx context.Context, input Input) (*CommandResponse, error) {
    wrapper := command.configWrapper
    if wrapper == nil {
        return command.commandFunc(ctx, input)
    }

    // If the command has a config struct, lock before execution.
    // The config struct may be updated by ConfigWatcher at the same time.
    wrapper.mutex.RLock()
    defer wrapper.mutex.RUnlock()
    return command.commandFunc(ctx, input, wrapper.value)
}

func buildCommand(ctx context.Context, props *CommandProps, watcher ConfigWatcher) (Command, error) {
    if props.config == nil {
        return &defaultCommand{
            identifier:      props.identifier,
            matchFunc:       props.matchFunc,
            instructionFunc: props.instructionFunc,
            commandFunc:     props.commandFunc,
            configWrapper:   nil,
        }, nil
    }

    // https://github.com/oklahomer/go-sarah/issues/44
    locker := configLocker.get(props.botType, props.identifier)

    cfg := props.config
    err := func() error {
        locker.Lock()
        defer locker.Unlock()

        rv := reflect.ValueOf(cfg)
        if rv.Kind() == reflect.Ptr || rv.Kind() == reflect.Map {
            return watcher.Read(ctx, props.botType, props.identifier, cfg)
        }

        // https://groups.google.com/forum/#!topic/Golang-Nuts/KB3_Yj3Ny4c
        // Obtain a pointer to the *underlying type* instead of CommandConfig.
        n := reflect.New(reflect.TypeOf(cfg))

        // Copy the current field value to the newly created instance.
        // This includes private field values.
        n.Elem().Set(rv)

        // Pass the pointer of the created instance.
        e := watcher.Read(ctx, props.botType, props.identifier, n.Interface())
        if e == nil {
            // Replace the current value with the updated one.
            cfg = n.Elem().Interface()
        }
        return e
    }()

    var notFoundErr *ConfigNotFoundError
    if err != nil && !errors.As(err, &notFoundErr) {
        // Unacceptable error
        return nil, fmt.Errorf("failed to read config for %s:%s: %w", props.botType, props.identifier, err)
    }

    return &defaultCommand{
        identifier:      props.identifier,
        matchFunc:       props.matchFunc,
        instructionFunc: props.instructionFunc,
        commandFunc:     props.commandFunc,
        configWrapper: &commandConfigWrapper{
            value: cfg,
            mutex: locker,
        },
    }, nil
}

// StripMessage is a utility function that applies the given regular expression to the input string and replaces the matching part with the empty string.
// Use this to extract the meaningful input value out of the entire user message.
// e.g. ".echo Hey!" becomes "Hey!"
func StripMessage(pattern *regexp.Regexp, input string) string {
    return strings.TrimSpace(pattern.ReplaceAllString(input, ""))
}

// Commands stashes all registered Command.
// A Bot implementation can refer to this to register a given command on Bot.AppendCommand call, and to find a matching Command on Bot.Respond call.
type Commands struct {
    collection []Command
    mutex      sync.RWMutex
}

// NewCommands creates and returns new Commands instance.
func NewCommands() *Commands {
    return &Commands{
        collection: []Command{},
        mutex:      sync.RWMutex{},
    }
}

// Append lets developers register a new Command to its internal stash.
// If another command is already registered with the same ID, the existing one is replaced in favor of the new one.
func (commands *Commands) Append(command Command) {
    commands.mutex.Lock()
    defer commands.mutex.Unlock()

    // See if a command with the same identifier exists.
    for i, cmd := range commands.collection {
        if cmd.Identifier() == command.Identifier() {
            logger.Infof("Replace old command in favor of newly appending one: %s.", command.Identifier())
            commands.collection[i] = command
            return
        }
    }

    // Not stored, then append to the last.
    logger.Infof("Append new command: %s.", command.Identifier())
    commands.collection = append(commands.collection, command)
}

// FindFirstMatched looks for the first matching command by calling each Command's Command.Match method:
// The first Command to return true is considered as "first matched" and is returned.
//
// The check for each Command is run in the order of registration; The earlier the Commands.Append is called, the earlier the check.
// Be sure to register an important Command first.
func (commands *Commands) FindFirstMatched(input Input) Command {
    commands.mutex.RLock()
    defer commands.mutex.RUnlock()

    for _, command := range commands.collection {
        if command.Match(input) {
            return command
        }
    }

    return nil
}

// ExecuteFirstMatched tries finding a matching command with the given Input and executes a Command if one is available.
func (commands *Commands) ExecuteFirstMatched(ctx context.Context, input Input) (*CommandResponse, error) {
    command := commands.FindFirstMatched(input)
    if command == nil {
        return nil, nil
    }

    return command.Execute(ctx, input)
}

// Helps returns all belonging commands' help messages in a form of *CommandHelps.
func (commands *Commands) Helps(input *HelpInput) *CommandHelps {
    commands.mutex.RLock()
    defer commands.mutex.RUnlock()

    helps := &CommandHelps{}
    for _, command := range commands.collection {
        instruction := command.Instruction(input)
        if instruction == "" {
            continue
        }

        h := &CommandHelp{
            Identifier:  command.Identifier(),
            Instruction: instruction,
        }
        *helps = append(*helps, h)
    }
    return helps
}

// CommandHelps is an alias to a slice of CommandHelp pointers.
type CommandHelps []*CommandHelp

// CommandHelp represents an instruction for the corresponding Command.
type CommandHelp struct {
    // Identifier represents the unique id of the corresponding Command.
    Identifier string

    // Instruction represents a help message to guide the Command usage.
    Instruction string
}

// CommandConfig provides an interface that every command configuration value must satisfy, which actually is empty.
// Think of this as a kind of marker interface with a more meaningful name.
type CommandConfig interface{}

type commandFunc func(context.Context, Input, ...CommandConfig) (*CommandResponse, error)

// NewCommandPropsBuilder returns new CommandPropsBuilder instance.
// Use this to set up a CommandProps that can be used to build a Command on the fly.
func NewCommandPropsBuilder() *CommandPropsBuilder {
    return &CommandPropsBuilder{
        props: &CommandProps{},
    }
}

// CommandProps is a designated non-serializable configuration struct to be used for Command construction.
// This holds a relatively complex set of Command construction arguments and properties.
type CommandProps struct {
    botType         BotType
    identifier      string
    config          CommandConfig
    commandFunc     commandFunc
    matchFunc       func(Input) bool
    instructionFunc func(*HelpInput) string
}

// CommandPropsBuilder helps to construct a CommandProps.
// A developer may set up a Command construction property -- CommandProps -- by calling CommandPropsBuilder.Build or CommandPropsBuilder.MustBuild at the end.
// A validation logic runs on build, so the returning CommandProps instant is safe to be passed to RegisterCommandProps.
type CommandPropsBuilder struct {
    props *CommandProps // This instance is not fully constructed til Build() is called.
}

// BotType is a setter to provide the belonging BotType.
func (builder *CommandPropsBuilder) BotType(botType BotType) *CommandPropsBuilder {
    builder.props.botType = botType
    return builder
}

// Identifier is a setter for a Command identifier.
func (builder *CommandPropsBuilder) Identifier(id string) *CommandPropsBuilder {
    builder.props.identifier = id
    return builder
}

// MatchPattern is a setter to provide a command match pattern.
// This regular expression is used against the given Input to see if the Command matches the Input.
//
// Use MatchFunc to set a more customizable matcher logic.
func (builder *CommandPropsBuilder) MatchPattern(pattern *regexp.Regexp) *CommandPropsBuilder {
    builder.props.matchFunc = func(input Input) bool {
        return pattern.MatchString(input.Message())
    }
    return builder
}

// MatchFunc is a setter for a function to judge if an incoming Input "matches" the Command.
// When this returns true, this command is considered to "match the user input" and becomes a Command execution candidate.
//
// MatchPattern may be used to specify a regular expression that is checked against user input, Input.Message();
// MatchFunc can specify more customizable matching logic.
// e.g. only return true on a specific sender's specific message on a specific time range.
func (builder *CommandPropsBuilder) MatchFunc(matchFunc func(Input) bool) *CommandPropsBuilder {
    builder.props.matchFunc = matchFunc
    return builder
}

// Func is a setter to provide a command function that requires no configuration.
// If ConfigurableFunc and Func are both called, the later call overrides the previous one.
func (builder *CommandPropsBuilder) Func(fn func(context.Context, Input) (*CommandResponse, error)) *CommandPropsBuilder {
    builder.props.config = nil
    builder.props.commandFunc = func(ctx context.Context, input Input, cfg ...CommandConfig) (*CommandResponse, error) {
        return fn(ctx, input)
    }
    return builder
}

// ConfigurableFunc is a setter to provide a command function that takes a configuration value as a struct.
// While Func lets developers set a simple function, this allows them to provide a function that requires some sort of configuration struct.
// On Sarah initiation, configuration settings are read by ConfigWatcher and mapped to the given CommandConfig value.
// This configuration value is passed to the command -- fn -- as its third argument.
func (builder *CommandPropsBuilder) ConfigurableFunc(config CommandConfig, fn func(context.Context, Input, CommandConfig) (*CommandResponse, error)) *CommandPropsBuilder {
    builder.props.config = config
    builder.props.commandFunc = func(ctx context.Context, input Input, cfg ...CommandConfig) (*CommandResponse, error) {
        return fn(ctx, input, cfg[0])
    }
    return builder
}

// Instruction is a setter to provide an instruction of command execution.
// This should be used to provide command usage for end-users.
func (builder *CommandPropsBuilder) Instruction(instruction string) *CommandPropsBuilder {
    builder.props.instructionFunc = func(input *HelpInput) string {
        return instruction
    }
    return builder
}

// InstructionFunc is a setter to provide a function that receives a user input and returns an instruction.
// Use Instruction() when a simple text instruction can always be returned.
// If the instruction has to be customized per user or the instruction has to be hidden in a certain group or from a certain user,
// use InstructionFunc() as it takes HelpInput as its argument.
// Use *HelpInput and judge if an instruction should be returned to the user.
// e.g. .reboot command is only supported for administrator users in the admin group so this command should be hidden in other groups.
//
// Also, see MatchFunc() for such an authentication mechanism.
func (builder *CommandPropsBuilder) InstructionFunc(fnc func(input *HelpInput) string) *CommandPropsBuilder {
    builder.props.instructionFunc = fnc
    return builder
}

// Build builds a new CommandProps instance with the provided values.
func (builder *CommandPropsBuilder) Build() (*CommandProps, error) {
    if builder.props.botType == "" ||
        builder.props.identifier == "" ||
        builder.props.instructionFunc == nil ||
        builder.props.matchFunc == nil ||
        builder.props.commandFunc == nil {

        return nil, ErrCommandInsufficientArgument
    }

    return builder.props, nil
}

// MustBuild is like Build but panics if any error occurs on Build.
// It simplifies the initialization of a global variable holding the built CommandProps instance.
func (builder *CommandPropsBuilder) MustBuild() *CommandProps {
    props, err := builder.Build()
    if err != nil {
        panic(fmt.Errorf("error on building CommandProps: %w", err))
    }

    return props
}