Standardized Hooks: Advanced Usage

For cPanel & WHM 11.32

Note: The Standardized Hooks documentation is currently under revision. You should check back shortly for improvements to this information.

Introduction

The Standardized Hooks system offers more functionality than simply executing code. You can also use checks, rollbacks, and exceptions.

• Rollbacks — Rollbacks allow you to undo changes that were made before a hook failed. Rollbacks are optional and should be defined in a hook's context and within the hook itself. A rollback will only run after a hook fails, and only if the hook is defined as a blocking hook.
• Checks — Checks should be defined in the hook itself, and are run before the hook. Essentially, checks determine whether the hook will be allowed to run, given the current conditions. Checks are optional. If no check exists in the hook, the process is ignored and the system will attempt to run the hook.
• Exceptions — Exceptions are used to indicate a serious failure from an underlying script. (For example, a remote server could not be contacted.)

Rollbacks

The Standardized Hooks system provides the ability to execute multiple hooks for a single action, which is one of the core features of this system. However, this create a major issue. If a hook that is executed after your hook denies the execution of an event, and your hook has made changes, it needs to be able to roll back the changes your hook made.

This is only an issue in the case of a blocking context (an insertion point that will not proceed with actions if a hook fails). For non-blocking contexts, this is not an issue, as the system will simply log a failure and move on.

Your rollback function must be of the same execution type as your hook. To define a rollback, simply add a rollback variable into your describe hash. This should reference either a script or a module, depending on the execution type used for the hook.

sub describe {
    my $hooks = [
        {
            'namespace' => 'Passwd',
            'function'  => 'ChangePasswd',
            'stage'     => 'pre',
            'hook'      => 'Boo::InversePassword',
            ‘rollback’  => ‘Boo::rollback_my_awesome_change’,
        },
    ];
    return $hooks;
}

The code above will execute a module called Boo::rollback_my_awesome_change if a hook fails after its run.

Checks

Checks allow you to ensure that certain hooks are only run under certain conditions. For example, you can use this feature to prevent accounts from accessing subsystems to which they should not have access.

Checks are defined in the hook itself, and are run before the hook. Checks are optional. If no check exists in the hook, the process is ignored and the system will attempt to run the hook.

Checks are handled by a check subroutine within the Standardized Hooks system. This subroutine returns a 1 or a 0 (or prints a 1 or 0 if script hooks are being used) that indicates whether the hook is allowed to run.

sub describe {
    my $hooks = [
        {
            'namespace' => 'Passwd',
            'function'  => 'ChangePasswd',
            'stage'     => 'pre',
            'hook'      => '/var/cpanel/my/awesome/hook.pl',
            'check'  => '/var/cpanel/my/awesome/check_script.php',
        },
    ];
    return $hooks;
}

The code above will execute /var/cpanel/my/awsome/check_script.php before executing the hook.

Exceptions

The Standardized Hooks system is also capable of throwing exceptions. Exceptions are used to indicate a serious failure from an underlying script. (For example, a remote server could not be contacted.)

Hooks will stop processing immediately when an exception is thrown for a blocking hook. If the hook is not blocking, the system will simply loop. If an exception occurs, an error is printed to /usr/local/cpanel/logs/error_log.

Exceptions can be thrown from the check or main stages of a hook. You can simply use Perl's die function with a string that prints BAILOUT at the beginning. This line will trigger the Standardized Hooks system's exception handling code.

sub my_hook {
	my ($context, $data) = @_;
	my $conn = AwesomeServer->connect($user, $pass, $whatever);
	if (!$conn) {
		die “BAILOUT Could not connect to remote server”;
	}
	...
	return 1;
}

The code above will trigger an exception and print a string that says Could not connect to remote server.

Note: When using script hooks, the check simply needs to print BAILOUT at the beginning of the response. The hooks handling code will then assume that an exception is being thrown and prevent the hook from executing.