-
Notifications
You must be signed in to change notification settings - Fork 0
DB API
API Version: pre-alpha
The database API is a list of Erlang function calls that match a certain specification. If you want EMP to use a database other than what was provided you will need to implement all functions and then follow the Swapping guide.
We will break up the API into 6 sections:
There are three functions: start_link/2, verify/2, and install/2. They all will take a list of Erlang nodes which will be running EMP (in case you want to set things up on all of them) and a list of arguments for your database as tuples.
-spec start_link( nonempty_nodelist(), [tuple()] ) -> possible_failure({ok, pid()}).Starts the EMP DB system and is called only when starting up. This should return a PID (Erlang process id) of the running server so that the application knows what to monitor. If your system requires multiple processes, consider making them all children of a supervisor process.
-spec verify( nonempty_nodelist(), [tuple()] ) ->
ok | {install, nonempty_nodelist()} |
{error, continue | shutdown, Reason :: any()}.This will need to verify that the database has been installed correctly.
-spec install( nonempty_nodelist(), [tuple()] ) -> possible_failure( ok ).EMP will first call verify/2 and if it gets an install message back, it will call this function to run the installation process over again.
The EMP database will need to keep track of EMPUSER objects. They are used for authentication and for event pattern matching. Sessions are started by interfaces and are uniquely identified as well.
-spec get_root_user() -> possible_failure( 'EMPUSER'() ).Grab the admin user for the local node. This may be deprecated in the future as we are redoing the idea of node privileges. (also see EMPUSER)
-spec add_user( binary(), useroptions() ) -> possible_failure( ok ).Add a user to the database given the user name and a list of information about the user. See empdb.hrl for more information on useroptions().
-spec rm_user( binary() ) -> possible_failure( ok ).Remove a user by name.
-spec get_users() -> possible_failure( ['EMPUSER'()] ).Get a list of users. (also see EMPUSER)
-spec user_login( binary() ) ->
possible_failure( {ok, 'EMPUSER'(), 'UUID'()} ).Given a the user's public key, attempt to log the user in. Return the username and a session ID.
-spec user_login( binary(), binary() ) ->
possible_failure( {ok, 'EMPUSER'(), 'UUID'()} ).Given a username and password, log the user in. Return the username and a session ID.
-spec user_logout( 'UUID'() ) -> possible_failure( ok ).Log out a user given the session ID.
-spec verify_session( 'UUID'() ) -> possible_failure( ok ).Verify that a particular session id is still active.
All of these are still in flux, as we are working on the subscription model to make it internally faster to represent.
-spec add_subscription( 'EMPUSER'(), 'EMPPLUGINDEF'(),
'EMPPLUGINDEF'(), 'EMPSUBSCRIPTION'() ) ->
possible_failure( {ok, 'UUID'()} ).Add a user's subscription between two plug-ins with a particular mapping. (see, EMPUSER, EMPPLUGINDEF, EMPSUBSCRIPTION)
-spec rm_subscription( 'UUID'() ) -> possible_failure( ok ).Remove a subscription by id.
-spec get_subscriptions( 'EMPUSER'(), 'EMPPLUGINDEF'() ) ->
possible_failure( ['EMPSUBSCRIPTION'()] ).Get all subscriptions for a particular plugin, user pair. (see, EMPUSER, EMPPLUGINDEF, EMPSUBSCRIPTION)
The plug-in installation process is being updated currently. These may change slightly, but shouldn't see anything too drastic. Current steps EMP takes when installing a plugin is to register it first, and then copy its data into the database through compression. This way it can be transported to other nodes easily if we need to distribute it across several servers.
-spec register_plugin( atom(), [tuple()], ['EMPCOMMAND'()], ['EMPEVENT'()] ) ->
possible_failure( {ok, 'UUID'()} ).Register a plugin with a module name, and its configuration details, along with its commands and event types. Return the new plug-in's ID. (see EMPCOMMAND, and EMPEVENT)
-spec get_plugin_defs( 'EMPUSER'() ) -> possible_failure( ['EMPPLUGINDEF'()] ).Get all plug-in definitions for a given user. This is only ever called once upon startup, so its safe to make this take a long time. (see EMPUSER, and EMPPLUGINDEF)
-spec get_target( 'EMPUSER'(), 'EMPPLUGINDEF'() ) ->
possible_failure( binary() ).Get the target name for a particular plugin/user pair. The original target can be taken from the configuration data when installed. The string returned can be used by the user to reference the plugin. This is helpful if you have two versions of the same plugin, they can go by two names.
-spec get_commands( 'UUID'() ) -> possible_failure( [ 'EMPCOMMAND'() ] ).Get commands for a particular plugin id.
-spec get_events( 'UUID'() ) -> possible_failure( [ 'EMPEVENT'() ] ).Get events for a particular plugin id.
-spec install_plugin( atom(), [binary()] ) -> possible_failure( ok ).Save a list of files in the database for a particular plugin.
-spec uninstall_plugin( atom() ) -> possible_failure( ok ).Remove all saved files for a particular plugin.
EMP will also use the database like a quick global dictionary.
-spec emp_get_var( atom() ) -> possible_failure( term() ).Get the value of a particular variable.
-spec emp_get_vars() -> possible_failure( [ {atom(), term()} ] ).Get all the values currently saved. Only ever called once during startup.
-spec emp_set_var( atom(), term() ) -> possible_failure( term() ).Set the value of a particular variable.
Plug-in's can use EMP for persistence of settings on a per user basis too.
-spec plugin_get_var( 'EMPPLUGINDEF'(), 'EMPUSER'(), binary() ) ->
possible_failure( term() ).Get a particular variable for a plugin/user pair. (see EMPPLUGINDEF, EMPUSER)
-spec plugin_set_var( 'EMPPLUGINDEF'(), 'EMPUSER'(), binary(), term() ) ->
possible_failure( ok ).Set a particular variable for a plugin/user pair. (see EMPPLUGINDEF, EMPUSER)
-spec plugin_state_saver( 'EMPPLUGINDEF'(), 'EMPUSER'(), [{binary(),term()}] ) ->
possible_failure( ok ).Configurations are separate from variables (they are accessed less frequently). (see EMPPLUGINDEF, EMPUSER)
-spec plugin_get_config( 'EMPPLUGINDEF'(), 'EMPUSER'(), binary() ) ->
possible_failure( term() ).Configurations are separate from variables (they are accessed less frequently). They are also not set during runtime. (see EMPPLUGINDEF, EMPUSER)
-spec plugin_load_prev_state( 'EMPPLUGINDEF'(), 'EMPUSER'() ) ->
possible_failure( [{binary(),term()}] ).Only called when the plugin is restarted. It gets all configurations. (see EMPPLUGINDEF, EMPUSER)