Next: , Previous: , Up: Hooks   [Contents][Index]


6.1.2 Event Notifications and Triggers

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:

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.

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:

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.

session_id

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:

rev_id

The revision id that the cert is attached to.

key_identity

The key that the cert is signed with; see key_identity.

name

The name of the cert.

value

The cert value.

session_id

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:

key_identity

The identity of the key received; see key_identity.

session_id

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:

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

Next: , Previous: , Up: Hooks   [Contents][Index]

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status