| Repository Hooks |
| ================ |
| |
| GOALS. |
| ====== |
| |
| A hook is a program triggered by a repository read or write access. |
| The hook is handed enough information to tell what the action is, |
| what target(s) it's operating on, and who is doing it. Depending |
| on the hook's output or return status, the repository's hook driver |
| may continue the action, stop it, or suspend it in some way. |
| |
| Subversion's hook system is being implemented in stages -- the |
| parts needed for M3 are being written first, though the design |
| encompasses goals beyond M3. In the long term, the system must |
| support: |
| |
| 1. Commit emails. |
| Able to report on date of commit, author, dirs and files |
| changed, and information about the changes -- ranging from |
| change summaries to full diffs. |
| [Needed for M3.] |
| |
| 2. Pre-commit guards based on content. |
| Examine what is about to be committed, and prevent or allow |
| the commit based on that. |
| [Not strictly needed for M3, but will be provided anyway.] |
| |
| 3. Pre-commit guards based on identity. |
| Examine who is attempting to change what, and prevent or |
| allow the commit accordingly. |
| [Needed for M3.] |
| |
| 4. Read authorization |
| Examine who is attempting to read what, and prevent or allow |
| the access accordingly. |
| [Not needed for M3; designed now, but implemented post-M3.] |
| |
| |
| HOW IT WORKS. |
| ============= |
| |
| Subversion's hooks are programs that live in the repository's hooks/ |
| directory: |
| |
| $ ls some-repo |
| README custom/ dav/ db/ hooks/ conf/ |
| $ ls some-repo/hooks/ |
| start-commit pre-commit post-commit |
| start-commit.tmpl pre-commit.tmpl post-commit.tmpl |
| read-sentinels write-sentinels |
| read-sentinels.tmpl write-sentinels.tmpl |
| $ |
| |
| The actual hooks are `start-commit', `pre-commit' and `post-commit'. |
| The template (.tmpl) files are example shell scripts to get you |
| started; look there for details about how each hook works. When a |
| repository is created, the templates are created automatically -- to |
| make your own hook, just copy `foo.tmpl' to `foo' and edit. |
| |
| (The `read-sentinels' and `write-sentinels' are not yet implemented |
| They are intended to be more like daemons than hooks. A sentinel is |
| started up at the beginning of a user operation. The Subversion |
| server communicates with the sentinel using a protocol yet to be |
| defined. Depending on the sentinel's responses, Subversion may stop |
| or otherwise modify the operation.) |
| |
| Here is when they are run: |
| |
| start-commit: Before the committer's txn is even created. |
| pre-commit: When the txn is finished, but before it is committed. |
| post-commit: After the txn is committed, and we have a new rev. |
| |
| Note that they must be executable by the user who will invoke them |
| (commonly the user httpd runs as), and that that same user needs to be |
| able to access the repository. |
| |
| Typically, `start-commit' is used to check that the user has commit |
| privileges at all. Then the `pre-commit' hook is used to protect |
| against commits that are disallowed due to content or location (for |
| example, your site might require that all commits to a certain branch |
| include a ticket number from the bug tracker), and `post-commit' is |
| used to mail out commit messages. |
| |
| The pre-commit and post-commit hooks may need to know things about the |
| change about to be committed (or that has just been committed). The |
| solution is a standalone program, `svnlook', which was installed in |
| the same place as the `svn' binary. Use `svnlook' to examine a txn or |
| revision tree. It produces output that is both human- and |
| machine-readable, so hook scripts can easily parse it. Note that |
| `svnlook' is read-only -- it can only inspect, not change the |
| repository. |
| |
| Run "svnlook" with no arguments to see how it works. |
| |
| More On Read and Write Sentinels (just discussion, not implemented yet!) |
| ------------------------------------------------------------------------ |
| |
| (Thanks to Thom Wood <thom@collab.net> for proposing this.) |
| |
| The `read-sentinels' and `write-sentinels' work somewhat differently. |
| A sentinel is started whenever a revision or txn root object is opened |
| (see svn_fs.h). All operations on paths beneath that root are first |
| "checked" with the sentinel; the sentinel's response determines |
| whether the operation is permitted. |
| |
| Our hope is that sentinels can be kept very simple: they will simply |
| take paths on stdin, and respond with "Okay" or "Not Okay" (or |
| slightly more formal XML equivalents). All kinds of read operations |
| on a path will be treated as equivalent, as will all write operations. |
| The relevant question will be simply: was the user allowed to read or |
| write this path? |
| |
| The point of sentinels is to provide real-time feedback as a commit |
| is being built (or even before the txn is started), or as a |
| checkout or update is being produced -- but without the overhead of |
| starting up a program anew for each path under the root. |
| |
| Almost all reading and writing functions in svn_fs.h will need to be |
| wrapped by libsvn_repos, which will drive the sentinels: |
| |
| Read actions to be wrapped: |
| --------------------------- |
| svn_fs_revision_root |
| svn_fs_is_dir |
| svn_fs_is_file |
| svn_fs_node_prop |
| svn_fs_node_proplist |
| svn_fs_txn_prop |
| svn_fs_txn_proplist |
| svn_fs_copied_from |
| svn_fs_is_different |
| svn_fs_dir_entries |
| svn_fs_file_length |
| svn_fs_file_contents |
| svn_fs_youngest_rev |
| svn_fs_revision_prop |
| svn_fs_revision_proplist |
| |
| Write actions to be wrapped: |
| ---------------------------- |
| svn_fs_begin_txn |
| svn_fs_commit_txn |
| svn_fs_txn_root |
| svn_fs_change_txn_prop |
| svn_fs_change_node_prop |
| svn_fs_make_dir |
| svn_fs_delete |
| svn_fs_delete_tree |
| svn_fs_rename |
| svn_fs_copy |
| svn_fs_link |
| svn_fs_make_file |
| svn_fs_apply_textdelta |
| svn_fs_change_rev_prop |
| |
| The exact sentinel protocol is still TBD; obviously, a precise |
| specification is very important for sentinel implementors. |
| |
| |
| FAQ (Frequently Anticipated Questions). |
| ======================================= |
| |
| Q: Why is `svnlook' a read-only interface to the repository? |
| |
| A: Because if it changed the txn before commit, the working copy |
| would have no way of knowing what happened, and would therefore |
| be out of sync and not know it. Subversion currently has no way |
| to handle this situation, and maybe never will. Someday the |
| hooks may leave txns in a "holding" state (for supervised |
| commits, a handy feature many have requested), but even then the |
| working copy should be told definitively that the commit did not |
| succeed. Later on, the commit will come through as an update. |
