Overview

Directory Server has had 3 plugin APIs so far. They have been very sucessful, and are still supported to this day.

However, they are starting to show their limits in design and with tools. We are unable to use correct modern type assertions to our interfaces (slapi_pblock_get/set), we rely on macros in many locations, and the transaction model is limited.

This is a proposal for a version 4 plugin system that lifts many of these limitations, while still being able to support the existing plugin v1 through v3 api.

v3 limitations.

v4 suggestions

This is not a backwards compatible change. Plugins must be redesigned to work.

v3 plugins will continue to operate, but will cause errors to be logged and certain fall backs to activate.

Pblock v4

The reason for this is you have a const type from the pblock (you shouldn’t change it without using set), you have proper checks of the value, the struct is abstract from the api (and can now be changed), no need to use macros, it is externally portable to other languages who wish to access libslapd.

Plugin API

Now the plugin function signature would be:

slapi_v4_plugin_result *
some_plugin_callback_fn(Slapi_PBlock) {
    if (result) {
        // Hey, everthing worked
        slapi_v4_plugin_result *res = slapi_v4_plugin_result_new(SLAPI_V4_PLUGIN_SUCCESS, "Operation on X succeeded");
        return res;
    } else {
        // Ruh roh.
        slapi_v4_plugin_result *res = slapi_v4_plugin_result_new(SLAPI_V4_PLUGIN_FAILURE, "Operation on X failed");
        return res;
    }
}

The plugin framework on SUCCESS, if the log level was at a level IE PLUGIN or TRACE, we would see the success message in the log.

During normal operation, if the plugin failed, we would log at the ERR level the message in the result, along with the code. This message could be plugged into send_ldap_result code also. This result struct could be expanded to contain an ldap result code, and message to be sent.

Plugin function hooks

The following function registration points are proposed. This is not an exhaustive list.

SLAPI_V4_PLUGIN_RO_PRE_BIND_FN
SLAPI_V4_PLUGIN_RO_PRE_COMPARE_FN
SLAPI_V4_PLUGIN_RO_PRE_ENTRY_FN
SLAPI_V4_PLUGIN_RO_PRE_EXTOP_FN
SLAPI_V4_PLUGIN_WR_PRE_EXTOP_FN
SLAPI_V4_PLUGIN_RO_PRE_REFERRAL_FN
SLAPI_V4_PLUGIN_RO_PRE_RESULT_FN
SLAPI_V4_PLUGIN_RO_PRE_SEARCH_FN
SLAPI_V4_PLUGIN_RO_PRE_UNBIND_FN
SLAPI_V4_PLUGIN_WR_PRE_ADD_FN
SLAPI_V4_PLUGIN_WR_PRE_DELETE_FN
SLAPI_V4_PLUGIN_WR_PRE_DELETE_TOMBSTONE_FN
SLAPI_V4_PLUGIN_WR_PRE_MODIFY_FN
SLAPI_V4_PLUGIN_WR_PRE_MODRDN_FN
SLAPI_V4_PLUGIN_RO_EXTOP_FN
SLAPI_V4_PLUGIN_WR_EXTOP_FN
SLAPI_V4_PLUGIN_WR_POST_ADD_FN
SLAPI_V4_PLUGIN_WR_POST_DELETE_FN
SLAPI_V4_PLUGIN_WR_POST_MODIFY_FN
SLAPI_V4_PLUGIN_WR_POST_MODRDN_FN
SLAPI_V4_PLUGIN_RO_POST_ABANDON_FN
SLAPI_V4_PLUGIN_RO_POST_BIND_FN
SLAPI_V4_PLUGIN_WR_POST_BIND_FN
SLAPI_V4_PLUGIN_RO_POST_COMPARE_FN
SLAPI_V4_PLUGIN_RO_POST_ENTRY_FN
SLAPI_V4_PLUGIN_RO_POST_EXTOP_FN
SLAPI_V4_PLUGIN_WR_POST_EXTOP_FN
SLAPI_V4_PLUGIN_RO_POST_REFERRAL_FN
SLAPI_V4_PLUGIN_RO_POST_RESULT_FN
SLAPI_V4_PLUGIN_RO_POST_SEARCH_FAIL_FN
SLAPI_V4_PLUGIN_RO_POST_SEARCH_FN
SLAPI_V4_PLUGIN_RO_POST_UNBIND_FN
SLAPI_V4_PLUGIN_PASSWORD_QUALITY_FN
SLAPI_V4_PLUGIN_PASSWORD_STORE_FN
SLAPI_V4_PLUGIN_PASSWORD_VERIFICATION_FN
SLAPI_V4_PLUGIN_START_FN
SLAPI_V4_PLUGIN_STOP_FN
SLAPI_V4_PLUGIN_DESTROY_FN
SLAPI_V4_PLUGIN_RO_BEGIN_FN
SLAPI_V4_PLUGIN_RO_CLOSE_FN
SLAPI_V4_PLUGIN_WR_BEGIN_FN
SLAPI_V4_PLUGIN_WR_ABORT_FN
SLAPI_V4_PLUGIN_WR_COMMIT_FN

External plugins and transactions

In the list of proposed function hooks, you will notice these types.

SLAPI_V4_PLUGIN_RO_BEGIN_FN
SLAPI_V4_PLUGIN_RO_CLOSE_FN
SLAPI_V4_PLUGIN_WR_BEGIN_FN
SLAPI_V4_PLUGIN_WR_ABORT_FN
SLAPI_V4_PLUGIN_WR_COMMIT_FN

These allow an external plugin to register for events related to transactions. For example, if the kdc were bound to these, it could allow transactions in the kdc to be synced with transaction in the Directory Server. This is vital for external password databases for example. This allows better, generic behaviour of plugins, without needing complex hacks, and keeping them in sync with Directory Server behaviours.

Testing

The v4 pblock/plugin test should guarantee:

This can be done with sample plugins that assert certain behaviours, or cmocka in certain cases.

Limitations of new design

Benefits

Last modified on 1 March 2024