There are a number of hooks that are called when noteworthy events
occur, such as commits or new revisions arriving over the network. These
hooks can be used to feed the events into external notification systems,
such as generating email.
By default, these hooks are undefined, so no special external actions
are taken.
Hooks are presented not in alphabetic order; they are grouped by
function, and then by the order they are typically called by monotone.
note_commit (new_id, revision, certs)
Called by monotone after the revsion new_id is
committed. revision is the text of the revision, what would be
given by mtn automate get_revision new_id. certs
is a Lua table containing the set of certificate names and values
committed along with this version.
There is no default definition for this hook.
Note that since the certs table does not contain cryptographic
or trust information, and only contains one entry per cert name, it is
an incomplete source of information about the committed version. This
hook is only intended as an aid for integrating monotone with informal
commit-notification systems such as mailing lists or news services. It
should not perform any security-critical operations.
Called by monotone just after a netsync session is started, before any
of the other netsync notification hooks are called.
The arguments are:
session_id
Identifies the current netsync session in case several are happening
at the same time (only possible on a server).
my_role
One of "client" or "server".
sync_type
One of "sync", "push", or "pull".
remote_host
The network address of the remote host. At the client, this will be the name
it was told to connect to; at the server, this will use the numerical IP address
the connection was received from.
remote_key
The identity of the key being used by the other end of the connection. The fields may
be empty at the server if the key used by the client is not present at the server.
includes
excludes
The include and exclude patterns used by the client.
Called after the revision new_id is received or sent through
netsync.
There are no default definitions for these hooks.
Arguments:
new_id
The revision id.
revision
The text of the revision; what would be given
by mtn automate get_revision new_id.
certs
A Lua table containing one subtable for each cert attached to the revision
new_id. These subtables have fields named "key", "name", and
"value", containing the identity of the signing key for the cert, the name of the cert,
and the value of the cert.
Called by monotone after a cert is received (or sent) through netsync,
if the revision that the cert is attached to was not also received (or
sent) in the same netsync operation.
There is no default definition for this hook.
Arguments:
rev_id
The revision id that the cert is attached to.
key_identity
The key that the cert is signed with; see key_identity.
Called by monotone after a netsync session ends. This hook would
usually be used for post-netsync purposes, like collecting all the
data from all other netsync notification hooks, make some nice output
from them and finally send the result somewhere. It could also be
used to prepare parallel databases with all the data to be displayed
through something like viewmtn.
Arguments:
session_id
Identifies the current netsync session.
status
A three digit integer that tells whether there was an error,
and if so what kind of error it was:
200
No error, connection successful.
211
The connection was interrupted after some data may have been transferred.
212
The connection was interrupted before any data could be transferred.
412
The request is not permitted.
422
The client tried to use a key that the server doesn't know about.
432
The client and server have different epochs for a branch.
512
Protocol error (source/sink confusion).
521
Protocol error (packet received at a time when it doesn't make sense).
532
The client did not identify itself correctly. (Possible replay attack?)
In general, 2xx means there was no error, 4xx means there was a permissions
error, and 5xx means there was a protocol error. xx1 means some data may
have been transferred, xx2 means no data was transferred, and xx0 means all
data was transferred.
bytes_in
bytes_out
The number of bytes received/sent during the session.
certs_in
certs_out
The number of certs received/sent during the session.
revs_in
revs_out
The number of revisions received/sent during the session.
keys_in
keys_out
The number of keys received/sent during the session.
note_mtn_startup (...)
Called by monotone when it is first started, after all command
completion and option processing, before the command starts executing.
There is no default definition of this hook.
One use of this hook is to monitor usage of monotone, for user
interface testing.
The arguments to the hook are the command line arguments to monotone,
without the initial mtn command. They can be accessed
through the lua arg variable as in this example:
function note_mtn_startup(...)
print("Beginning note_mtn_startup")
for i = 1,arg.n do
print(arg[i])
end
print("Ending note_mtn_startup")
end