The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Gerrit-Client-20121218
River stage zero No dependents
++
/ Gerrit::Client

NAME

Gerrit::Client - interact with Gerrit code review tool

SYNOPSIS

  use AnyEvent;
  use Gerrit::Client qw(stream_events);

  # alert me when new patch sets arrive in
  # ssh://gerrit.example.com:29418/myproject
  my $stream = stream_events(
    url => 'ssh://gerrit.example.com:29418',
    on_event => sub {
      my ($event) = @_;
      if ($event->{type} eq 'patchset-added'
          && $event->{change}{project} eq 'myproject') {
        system("xmessage", "New patch set arrived!");
      }
    }
  );

  AE::cv()->recv(); # must run an event loop for callbacks to be activated

This module provides some utility functions for interacting with the Gerrit code review tool.

This module is an AnyEvent user and may be used with any event loop supported by AnyEvent.

FUNCTIONS

stream_events url => $gerrit_url, ...

Connect to "gerrit stream-events" on the given gerrit host and register one or more callbacks for events. Returns an opaque handle to the stream-events connection; the connection will be aborted if the handle is destroyed.

$gerrit_url should be a URL with ssh schema referring to a valid Gerrit installation (e.g. "ssh://user@gerrit.example.com:29418/").

Supported callbacks are documented below. All callbacks receive the stream-events handle as their first argument.

on_event => $cb->($data)

Called when an event has been received. $data is a reference to a hash representing the event.

See the Gerrit documentation for information on the possible events.

on_error => $cb->($error)

Called when an error occurs in the connection. $error is a human-readable string.

Examples of errors include network disruptions between your host and the Gerrit server, or the ssh process being killed unexpectedly. Receiving any kind of error means that some Gerrit events may have been lost.

If this callback returns a true value, stream_events will attempt to reconnect to Gerrit and resume processing; otherwise, the connection is terminated and no more events will occur.

The default error callback will warn and return 1, retrying on all errors.

for_each_patchset(url => $url, workdir => $workdir, ...)

Set up a high-level event watcher to invoke a custom callback or command for each existing or incoming patch set on Gerrit. This method is suitable for performing automated testing or sanity checks on incoming patches.

For each patch set, a git repository is set up with the working tree and HEAD set to the patch. The callback is invoked with the current working directory set to the top level of this git repository.

Returns a guard object. Event processing terminates when the object is destroyed.

Options:

url

The Gerrit ssh URL, e.g. ssh://user@gerrit.example.com:29418/. Mandatory.

workdir

The top-level working directory under which git repositories and other data should be stored. Mandatory. Will be created if it does not exist.

The working directory is persistent across runs. Removing the directory may cause the processing of patch sets which have already been processed.

on_patchset => $sub->($change, $patchset)
on_patchset_fork => $sub->($change, $patchset)
on_patchset_cmd => $sub->($change, $patchset) | $cmd_ref

Callbacks invoked for each patchset. Only one of the above callback forms may be used.

  • on_patchset invokes a subroutine in the current process. The callback is blocking, which means that only one patch may be processed at a time. This is the simplest form and is suitable when the processing for each patch is expected to be fast or the rate of incoming patches is low.

  • on_patchset_fork invokes a subroutine in a new child process. The child terminates when the callback returns. Multiple patches may be handled in parallel.

    The caveats which apply to AnyEvent::Util::run_cmd also apply here; namely, it is not permitted to run the event loop in the child process.

  • on_patchset_cmd runs a command to handle the patch. Multiple patches may be handled in parallel.

    The argument to on_patchset_cmd may be either a reference to an array holding the command and its arguments, or a reference to a subroutine which generates and returns an array for the command and its arguments.

All on_patchset callbacks receive change and patchset hashref arguments. Note that a change may hold several patchsets.

on_error => $sub->($error)

Callback invoked when an error occurs. $error is a human-readable error string.

All errors are treated as recoverable. To abort on an error, explicitly undefine the loop guard object from within the callback.

By default, a warning message is printed for each error.

review => 0 | 1 | 'code-review' | 'verified' | ...

If false (the default), patch sets are not automatically reviewed (though they may be reviewed explicitly within the on_patchset_... callbacks).

If true, any output (stdout or stderr) from the on_patchset_... callback will be captured and posted as a review message. If there is no output, no message is posted.

If a string is passed, it is construed as a Gerrit approval category and a review score will be posted in that category. The score comes from the return value of the callback (or exit code in the case of on_patchset_cmd).

on_review => $sub->( $change, $patchset, $message, $score )

Optional callback invoked prior to performing a review (when the `review' option is set to a true value).

The callback should return a true value if the review should be posted, false otherwise. This may be useful for the implementation of a dry-run mode.

The callback may be invoked with an undefined $message and $score, which indicates that a patchset was successfully processed but no message or score was produced.

wanted => $sub->( $change, $patchset )

The optional `wanted' subroutine may be used to limit the patch sets processed.

If given, a patchset will only be processed if this callback returns a true value. This can be used to avoid git clones of unwanted projects.

For example, patchsets for all Gerrit projects under a 'test/' namespace could be excluded from processing by the following:

    wanted => sub { $_[0]->{project} !~ m{^test/} }
git_work_tree => 0 | 1

By default, while processing a patchset, a git work tree is set up with content set to the appropriate revision.

git_work_tree = 0> may be passed to disable the work tree, saving some time and disk space. In this case, a bare clone is used, with HEAD referring to the revision to be processed.

This may be useful when the patch set processing does not require a work tree (e.g. the incoming patch is directly scanned).

Defaults to 1.

query => $query | 0

The Gerrit query used to find the initial set of patches to be processed. The query is executed when the loop begins and whenever the connection to Gerrit is interrupted, to avoid missed patchsets.

Defaults to "status:open", meaning every open patch will be processed.

Note that the query is not applied to incoming patchsets observed via stream-events. The wanted parameter may be used for that case.

If a false value is passed, querying is disabled altogether. This means only patchsets arriving while the loop is running will be processed.

random_change_id

Returns a random Change-Id (the character 'I' followed by 40 hexadecimal digits), suitable for usage as the Change-Id field in a commit to be pushed to gerrit.

next_change_id

Returns the 'next' Change-Id which should be used for a commit created by the current git author/committer (which should be set by git_environment prior to calling this method). The current working directory must be within a git repository.

This method is suitable for usage within a script which periodically creates commits for review, but should have only one outstanding review (per branch) at any given time. The returned Change-Id is (hopefully) unique, and stable; it only changes when a new commit arrives in the git repository from the current script.

For example, consider a script which is run once per day to clone a repository, generate a change and push it for review. If this function is used to generate the Change-Id on the commit, the script will update the same change in gerrit until that change is merged. Once the change is merged, next_change_id returns a different value, resulting in a new change. This ensures the script has a maximum of one pending review any given time.

If any problems occur while determining the next Change-Id, a warning is printed and a random Change-Id is returned.

git_environment(name => $name, email => $email, author_only => [0|1] )

Returns a copy of %ENV modified suitably for the creation of git commits by a script/bot.

Options:

name

The human-readable name used for git commits. Mandatory.

email

The email address used for git commits. Mandatory.

author_only

If 1, the environment is only modified for the git author, and not the git committer. Depending on the gerrit setup, this may be required to avoid complaints about missing "Forge Identity" permissions.

Defaults to 0.

When generating commits for review in gerrit, this method may be used in conjunction with "next_change_id" to ensure this bot has only one outstanding change for review at any time, as in the following example:

    local %ENV = git_environment(
        name => 'Indent Bot',
        email => 'indent-bot@example.com',
    );

    # fix up indenting in all the .cpp files
    (system('indent *.cpp') == 0) || die 'indent failed';

    # then commit and push them; commits are authored and committed by
    # 'Indent Bot <indent-bot@example.com>'.  usage of next_change_id()
    # ensures that this bot has a maximum of one outstanding change for
    # review
    my $message = "Fixed indentation\n\nChange-Id: ".next_change_id();
    (system('git add -u *.cpp') == 0)
      || die 'git add failed';
    (system('git', 'commit', '-m', $message) == 0)
      || die 'git commit failed';
    (system('git push gerrit HEAD:refs/for/master') == 0)
      || die 'git push failed';
review $commit_or_change, url => $gerrit_url, ...

Wrapper for the `gerrit review' command; add a comment and/or update the status of a change in gerrit.

$commit_or_change is mandatory, and is either a git commit (in abbreviated or full 40-digit form), or a gerrit change number and patch set separated by a comment (e.g. 3404,3 refers to patch set 3 of the gerrit change accessible at http://gerrit.example.com/3404). The latter form is deprecated and may be removed in some version of gerrit.

$gerrit_url is also mandatory and should be a URL with ssh schema referring to a valid Gerrit installation (e.g. "ssh://user@gerrit.example.com:29418/"). The URL may optionally contain the relevant gerrit project.

All other arguments are optional, and include:

on_success => $cb->()
on_error => $cb->( $error )

Callbacks invoked when the operation succeeds or fails.

abandon => 1|0
message => $string
project => $string
restore => 1|0
stage => 1|0
submit => 1|0
code_review => $number
sanity_review => $number
verified => $number

These options are passed to the `gerrit review' command. For information on their usage, please see the output of `gerrit review --help' on your gerrit installation, or see the Gerrit documentation.

Note that certain options can be disabled on a per-site basis. `gerrit review --help' will show only those options which are enabled on the given site.

query $query, url => $gerrit_url, ...

Wrapper for the `gerrit query' command; send a query to gerrit and invoke a callback with the results.

$query is the Gerrit query string, whose format is described in the Gerrit documentation. "status:open age:1w" is an example of a simple Gerrit query.

$url is the URL with ssh schema of the Gerrit site to be queried (e.g. "ssh://user@gerrit.example.com:29418/"). If the URL contains a path (project) component, it is ignored.

All other arguments are optional, and include:

on_success => $cb->( @results )

Callback invoked when the query completes.

Each element of @results is a hashref representing a Gerrit change, parsed from the JSON output of `gerrit query'. The format of Gerrit change objects is described in the Gerrit documentation.

on_error => $cb->( $error )

Callback invoked when the query command fails. $error is a human-readable string describing the error.

all_approvals => 0|1
comments => 0|1
commit_message => 0|1
current_patch_set => 0|1
dependencies => 0|1
files => 0|1
patch_sets => 0|1
submit_records => 0|1

These options are passed to the `gerrit query' command and may be used to increase the level of information returned by the query. For information on their usage, please see the output of `gerrit query --help' on your gerrit installation, or see the Gerrit documentation.

quote $string

Returns a copy of the input string with special characters escaped, suitable for usage with Gerrit CLI commands.

Gerrit commands run via ssh typically need extra quoting because the ssh layer already evaluates the command string prior to passing it to Gerrit. This function understands how to quote arguments for this case.

Note: do not use this function for passing arguments to other Gerrit::Client functions; those perform appropriate quoting internally.

VARIABLES

@Gerrit::Client::SSH

The ssh command and initial arguments used when Gerrit::Client invokes ssh.

  # force IPv6 for this connection
  local @Gerrit::Client::SSH = ('ssh', '-oAddressFamily=inet6');
  my $stream = Gerrit::Client::stream_events ...

The default value is ('ssh').

@Gerrit::Client::GIT

The git command and initial arguments used when Gerrit::Client invokes git.

  # use a local object cache to speed up initial clones
  local @Gerrit::Client::GIT = ('env', "GIT_ALTERNATE_OBJECT_DIRECTORIES=$ENV{HOME}/gitcache", 'git');
  my $guard = Gerrit::Client::for_each_patchset ...

The default value is ('git').

$Gerrit::Client::MAX_CONNECTIONS

Maximum number of simultaneous git connections Gerrit::Client may make to a single Gerrit server. The amount of parallel git clones and fetches should be throttled, otherwise the Gerrit server may drop incoming connections.

The default value is 2.

$Gerrit::Client::MAX_FORKS

Maximum number of processes allowed to run simultaneously for handling of patchsets in for_each_patchset. This limit applies only to local work processes, not git clones or fetches from gerrit.

Note that $AnyEvent::Util::MAX_FORKS may also impact the maximum number of processes. $AnyEvent::Util::MAX_FORKS should be set higher than or equal to $Gerrit::Client::MAX_FORKS.

The default value is 4.

$Gerrit::Client::DEBUG

If set to a true value, various debugging messages will be printed to standard error. May be set by the GERRIT_CLIENT_DEBUG environment variable.

AUTHOR

Rohan McGovern, <rohan@mcgovern.id.au>

BUGS

Please use http://rt.cpan.org/ to view or report bugs.

When reporting a reproducible bug, please include the output of your program with the environment variable GERRIT_CLIENT_DEBUG set to 1.

LICENSE AND COPYRIGHT

Copyright (C) 2012 Rohan McGovern <rohan@mcgovern.id.au>

Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 2.1 as published by the Free Software Foundation.

This program 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser 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.