Next: User Defaults, Previous: Common Data Types, Up: Hooks [Contents][Index]
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.
note_netsync_start (session_id, my_role, sync_type, remote_host, remote_key, includes, excludes)
Called by monotone just after a netsync session is started, before any of the other netsync notification hooks are called.
The arguments are:
Identifies the current netsync session in case several are happening at the same time (only possible on a server).
One of "client" or "server".
One of "sync", "push", or "pull".
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.
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.
The include and exclude patterns used by the client.
note_netsync_revision_received (new_id, revision, certs, session_id)
note_netsync_revision_sent (rev_id, revision, certs, session_id)
Called after the revision new_id is received or sent through netsync.
There are no default definitions for these hooks.
Arguments:
The revision id.
The text of the revision; what would be given
by mtn automate get_revision new_id.
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.
Identifies the current netsync session.
note_netsync_cert_received (rev_id, key_identity, name, value, session_id)
note_netsync_cert_sent (rev_id, key_identity, name, value, session_id)
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:
The revision id that the cert is attached to.
The key that the cert is signed with; see key_identity.
The name of the cert.
The cert value.
Identifies the netsync session.
note_netsync_pubkey_received (key_identity, session_id)
note_netsync_pubkey_sent (key_identity, session_id)
Called by monotone after a pubkey is received or sent through netsync.
There is no default definition for this hook.
Arguments:
The identity of the key received; see key_identity.
Identifies the current netsync session.
note_netsync_end (session_id, status, bytes_in, bytes_out, certs_in, certs_out, revs_in, revs_out, keys_in, keys_out)
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:
Identifies the current netsync session.
A three digit integer that tells whether there was an error, and if so what kind of error it was:
No error, connection successful.
The connection was interrupted after some data may have been transferred.
The connection was interrupted before any data could be transferred.
The request is not permitted.
The client tried to use a key that the server doesn’t know about.
The client and server have different epochs for a branch.
Protocol error (source/sink confusion).
Protocol error (packet received at a time when it doesn’t make sense).
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.
The number of bytes received/sent during the session.
The number of certs received/sent during the session.
The number of revisions received/sent during the session.
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
Next: User Defaults, Previous: Common Data Types, Up: Hooks [Contents][Index]