## ## monotone-netsync -- Monotone NETSYNC Hook Abstraction ## Copyright (c) 2007 Ralf S. Engelschall ## ## You can redistribute and/or modify this file under the terms of ## the GNU General Public License as published by the Free Software ## Foundation; either version 2 of the License, or (at your option) any ## later version. ## ## This file is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ## General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with this program; if not, write to the Free Software ## Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, ## USA, or contact Ralf S. Engelschall . ## ## monotone-netsync.pod: documentation (language: Perl POD) ## =pod =head1 NAME B -- Monotone NETSYNC Hook Abstraction =head1 DESCRIPTION B is a B extension to the B distributed version control system (DVCS). It is abstraction layer over B's I B run-time hooks and intended to be used by multiple B B extensions which want to hook into the I processing of B -- usually a server process based on C. B mainly provides the following distinct features: =over 4 =item 1. Unification of hook names: the B I related B hooks are (partly historically) named very different. This abstraction layer streamlines their names. =item 2. Unification of inputs: the hook callbacks are passed a parameter table instead of positional arguments in order to unify and simplify the hook usage and reduce the code size of the hook abstraction implementation. =item 3. Register arbitrary number of hooks: one can hook an arbitrary number of hook callback functions into the I abstraction layer. This way multiple I based B extensions can use B in parallel and all leverage from the single abstraction. =item 4. Allow a hook callback function to stop the execution of subsequent hook callbacks for the same hook by means of the return code. This allows a hook callback function to finally I the operation. =item 5. Ganular hook tracing of I hooks in a logfile for accounting purposes. =back =head1 SYNOPSIS =over 4 =item F mtn --db=monotone-server.db \ --rcfile=monotone-server.lua \ address@hidden \ serve \ --bind 127.0.0.1:4691 =item F -- load Lua extensions include("lua-dump.lua") -- optional, but strongly recommended include("lua-logfile.lua") -- optional, but strongly recommended include("monotone-netsync.lua") -- initialize NETSYNC abstraction hooking layer netsync:setup(false, "monotone-server.log", "debug") -- trace all NETSYNC hooks netsync:trace("*") -- perform authentication for read access netsync:hook("allow_access_read", function(p) if p.keyid == "address@hidden" then return true else return false end end) -- perform authentication for write access netsync:hook("allow_access_write", function(p) if p.keyid == "address@hidden" then return true else return false end end) -- perform authorization for receiving certs netsync:hook("allow_receive_data_cert", function(p) if p.name == "branch" and p.value == "com.example.*" then return "accept" else return "rollback:all revisions have to be under com.example.*" end end) =back =head1 APPLICATION PROGRAMMING INTERFACE (API) The following API functions are available: =over 4 =item B(I[, I[, I]]) Initialize the I hook abstraction layer. If I is C all already existing native B B I hooks (usually from B's C) are automatically activated again under the corresponding B hooks. If I is C all existing native B B I hooks are just overridden. For I tracing and processing logging optionally specify I (a filesystem path) and I (one of "C", "C", "C" and "C"). =item B(I, I[, I[, I]]) Hook I into the I abstraction layer under hook I by appending it to the list of callback functions for this particular hook. Specify I for prepending it and I for clearing the list first. =item B(I, I) Unhook I into the I abstraction layer under hook I by removing it from the list of callback functions for this particular hook. =item B(I) Enabling tracing of the hook I. This way on every call of the hook an entry is made into the logfile. =item B(I) Disable tracing of the hook I (again). =back =head1 HOOKS The following I hooks are available: HOOK NAME SESSION STEP TYPE note_connection_start step 1 notification-only allow_access_read step 2 authentication control allow_access_write step 3 authentication control allow_receive_data_epoch step 4[.1] authorization control allow_receive_data_key step 4[.2] authorization control allow_receive_data_revision step 4[.3] authorization control allow_receive_data_cert step 4[.4] authorization control note_received_key step 5 notification-only note_received_revision step 6 notification-only note_received_cert step 7 notification-only note_connection_end step 8 notification-only =over =item B This hook is called once at the start of the NETSYNC session. It is intended for recognizing information only. Parameters: session_id session identifier ("42") local_role local role ("server", "client") peer_synctype peer sync type ("push", "pull", "sync") peer_host peer host IP address peer_key peer RSA key peer_includes peer branch include pattern peer_excludes peer branch exclude pattern Result: true continue processing false stop processing =item B This hook is called multiple times at the start of the NETSYNC session. It is intended for granting read access to a key on particular branches. Parameters: key_id key identifier/name ("address@hidden") branch branch name ("com.example") Result: true allow access false deny access =item B This hook is called once at the start of the NETSYNC session. It is intended for granting write access to a key in general. Parameters: key_id key identifier/name ("address@hidden") Result: true allow access false deny access =item B This hook is called once at the start of the NETSYNC session. It is intended for granting storage of "epoch" data. Parameters: session_id session identifier ("42") branch_name branch name ("com.example") epoch_number epoch ("0000000000000000000000") Result: "accept" accept data "ignore" ignore data "abort:" abort session, commit transaction "rollback:" abort session, rollback transaction =item B This hook is called multiple times during the NETSYNC session. It is intended for granting storage of (public) "key" data. Parameters: session_id session identifier ("42") key_id key identifier/name ("address@hidden") key_data key data ("[...base64 encoded...]" Result: "accept" accept data "ignore" ignore data "abort:" abort session, commit transaction "rollback:" abort session, rollback transaction =item B This hook is called multiple times during the NETSYNC session. It is intended for granting storage of "revision" data. Parameters: session_id session identifier ("42") rev_id revision identifier ("87186e69d9afd2ed1db17cc4c1c4708a9dcba4de") rev_data revision data (["...basic_io encoded...]) Result: "accept" accept data "ignore" ignore data "abort:" abort session, commit transaction "rollback:" abort session, rollback transaction =item B This hook is called multiple times during the NETSYNC session. It is intended for granting storage of "cert" data. Parameters: session_id session identifier ("42") rev_id revision identifier ("87186e69d9afd2ed1db17cc4c1c4708a9dcba4de") key_id key identifier/name ("address@hidden") cert_name cert name ("author", "branch", "changelog", "date", etc) cert_value cert value ("com.exampke.foo") Result: "accept" accept data "ignore" ignore data "abort:" abort session, commit transaction "rollback:" abort session, rollback transaction =item B This hook is called multiple times at the end of the NETSYNC session. It is intended for recognizing information only. Parameters: session_id session identifier ("42") key_id key identifier/name ("address@hidden") Result: true continue processing false stop processing =item B This hook is called multiple times at the end of the NETSYNC session. It is intended for recognizing information only. Parameters: session_id session identifier ("42") rev_id revision identifier ("87186e69d9afd2ed1db17cc4c1c4708a9dcba4de") rev_data revision data (["...basic_io encoded...]) rev_certs table of "key"/"name"/"value" sub-tables of all attached certs Result: true continue processing false stop processing =item B This hook is called multiple times at the end of the NETSYNC session. It is intended for recognizing information only. Parameters: session_id session identifier ("42") rev_id revision identifier ("87186e69d9afd2ed1db17cc4c1c4708a9dcba4de") key_id key identifier/name ("address@hidden") cert_name cert name ("author", "branch", "changelog", "date", etc) cert_value cert value ("com.exampke.foo") Result: true continue processing false stop processing =item B This hook is called once at the end of the NETSYNC session. It is intended for recognizing information only. Parameters: session_id session identifier ("42") status result status code ("200") bytes_in total number of bytes received ("0") bytes_out total number of bytes sent ("0") certs_in total number of certs received ("0") certs_out total number of certs sent ("0") revs_in total number of revisions received ("0") revs_out total number of revisions sent ("0") keys_in total number of keys received ("0") keys_out total number of keys sent ("0") Result: true continue processing false stop processing =back =head1 HISTORY B was refactored out as a general and reusable component from a I implementing B B extension which I implemented in September 2007 for the possible adoption of B inside his B and B projects. =head1 AUTHOR Ralf S. Engelschall address@hidden wwww.engelschall.com =cut