##
## 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