Add hook names to hooks API

This adds hook names to the gitano.hooks API which is there to
explain what the hook functions should do, and to provide a logical
name for hooks, rather than expecting people to not typo strings.

1 files changed, 36 insertions, 0 deletions

diff --git a/lib/gitano/hooks.lua b/lib/gitano/hooks.lua
index 0de2325..0c3cba9 100644
--- a/lib/gitano/hooks.lua
+++ b/lib/gitano/hooks.lua
@@ -34,6 +34,41 @@
 
 local hooks = {}
 
+-- In order to centralise and ensure hook names are good, these
+-- are the names of the hooks Gitano uses internally.
+-- Plugins are at liberty to add their own hooks if they want, but
+-- Gitano is unlikely to call them itself.
+
+local hook_names = {
+   -- Called by gitano.auth.is_authorized to allow manipulation of the
+   -- command line if wanted.  Hook functions should take the form:
+   -- function preauth_cmdline_hook(cancel, config, ip, user, keytag, ...)
+   --   -- Decide what to do, if we're rejecting the command then set cancel
+   --   -- to something truthy such as:
+   --   return "stop", true, "Some reason"
+   --   -- otherwise try
+   --   return "continue"
+   --   -- or
+   --   return "update", cancel, config, ip, user, keytag, ...
+   -- end
+   PREAUTH_CMDLINE = "PREAUTH_CMDLINE",
+   -- Called by gitano-post-receive to allow processing to occur on the git
+   -- post-receive event if needed.  The hook carries all the usual functions
+   -- as well as any registered by plugins.
+   -- Core admin stuff (running gitano-admin updates, update-server-info, etc)
+   -- runs at -1000.  The supple hooks run at 0.  Hook functions take the form:
+   -- function post_receive_hook(repo, updates)
+   --   -- Decide what to do.  If we want to stop the hooks, return "stop"
+   --   -- but only do that if we MUST, since it will alter expected behaviour.
+   --   return "stop"
+   --   -- Otherwise, normally we'd just continue
+   --   return "continue"
+   --   -- Finally we can update if we want to alter the updates table
+   --   return "update", repo, different_updates
+   -- end
+   POST_RECEIVE = "POST_RECEIVE",
+}
+
 local function _get_hook(hookname)
    local ret = hooks[hookname] or {}
    hooks[hookname] = ret
@@ -98,4 +133,5 @@ end
 return {
    add = add_to_hook,
    run = run_hook,
+   names = hook_names,
 }