NAME¶
App::KGB::Client - relay commits to KGB servers
SYNOPSIS¶
use App::KGB::Client;
my $client = App::KGB::Client( <parameters> );
$client->run;
DESCRIPTION¶
App::KGB::Client is the backend behind
kgb-client(1). It handles
the repository-independent parts of sending the notifications to the KGB
server,
kgb-bot(1). Details about extracting change from commits,
branches and modules is done by sub-classes specific to the version control
system in use.
CONFIGURATION¶
The following parameters are accepted in the constructor:
- repo_id repository name
- Short repository identifier. Will be used for identifying
the repository to the KGB daemon, which will also use this for IRC
notifications. Mandatory.
- uri URI
- URI of the KGB server. Something like
"http://some.server:port". Mandatory either as a
top-level parameter or as a sub-parameter of servers array.
- proxy URI
- URI of the SOAP proxy. If not given, it is the value of the
uri option, with "?session=KGB" added.
- password password
- Password for authentication to the KGB server.
Mandatory either as a top-level parameter or as a sub-parameter of
servers array.
- timeout seconds
- Timeout for server communication. Default is 15 seconds, as
we want instant IRC and commit response.
- servers
- An array of servers, each an instance of
App::KGB::Client::ServerRef class.
When several servers are configured, the list is shuffled and then the
servers are tried one after another until a successful request is done, or
the list is exhausted, in which case an exception is thrown.
When shuffling, preference is added to the last server used by the client,
or by other clients (given "status_dir" is configured).
- br_mod_re
- A list of regular expressions (simple strings, not qr
objects) that serve for detection of branch and module of commits. Each
item from the list is tried in turn, until an item is found that matches
all the paths that were modified by the commit. Regular expressions must
have two captures: the first one giving the branch name, and the second
one giving the module name.
All the paths that were modified by the commit must resolve to the same
branch and module in order for the branch and module to be transmitted to
the KGB server.
Example: ([^/]+)/([^/]+)/
# branch/module
- br_mod_re_swap 1
- If you can only provide the module name in the first
capture and the branch name in the second, use this option to signal the
fact to kgb-client.
- ignore_branch
- When most of the development is in one branch, transmitting
it to the KGB server and seeing it on ORC all the time can be annoing.
Therefore, if you define ignore_branch, and a given commit is in a
branch with that name, the branch name is not transmitted to the server.
Module name is still transmitted.
- module
- Forces explicit module name, overriding the branch and
module detection. Useful in Git-hosted sub-projects that want to share
single configuration file, but still want module indication in
notifications.
- single_line_commits off|forced|auto
- Request different modes of commit message processing:
- off
- No processing is done. The commit message is printed as was
given, with each line in a separate IRC message, blank lines omitted. This
is the only possible behaviour in versions before 1.14.
- forced
- Only the first line is sent to IRC, regardles of whether it
is followed by a blank line or not.
- auto
- If the first line is followed by an empty line, only the
first line is sent to IRC and the rest is ignored. This is the default
since version 1.14.
- status_dir
- Specifies a directory to store information about the last
server contacted successfuly. The client would touch files in that
directory after successful completion of a notification with remote
server.
Later, when asked to do another notification, the client would start from
the most recently contacted server. If that was contacted too far in the
past, the information in the directory is ignored and a random server is
picked, as usual.
- verbose
- Print diagnostic information.
CONSTRUCTOR¶
new ( { initial values } )¶
Standard constructor with initial values in a hashref.
my $c = App::KGB::Client->new(
{ repo_id => 'my-repo',
servers => \@servers,
...
}
);
See above.
METHODS¶
- detect_branch_and_module ( $changes )
- Given a set of changes (an arrayref of App::KGB::Change
objects), runs all the regular expressions as listed in br_mod_re
and if a regular expression that matches all the changed paths and returns
the branch and module.
In case the module detected is the same as ignore_module,
"undef" is returned for module.
( $branch, $module ) = $client->detect_branch_and_module($changes);
- shuffle_servers
- Returns a shuffled variant of
"$self->servers". It considers the last successfuly used
server by this client instance and puts it first. If there is no such
server, it considers the state in "status_dir" and picks the
last server noted there, if it was used in the last 5 minutes.
- process_commit ($commit)
- Processes a single commit, trying to send the changes
summary to each of the servers, defined inn servers, until some
server is successfuly notified.
- process
- The main processing method. Calls describe_commit
and while it returns true values, gives them to
process_commit.
PROVIDING REPOSITORY-SPECIFIC FUNCTIONALITY¶
App::KGB::Client is a generic class providing repository-agnostic functionality.
All repository-specific methods are to be provided by classes, inheriting from
App::KGB::Client. See App::KGB::Client::Subversion and App::KGB::Client::Git.
Repository classes must provide the following method:
- dsescribe_commit
- This method returns an App::KGB::Commit object that
represents a single commit of the repository.
describe_commit is called several times, until it returns
"undef". The idea is that a single App::KGB::Client run can be
used to process several commits (for example if the repository is Git). If
this is the case each call to describe_commit shall return
information about the next commit in the series. For Subversion, this
module is expected to return only one commit, subsequent calls shall
return "undef".
SEE ALSO¶
- App::KGB::Client::Subversion
- App::KGB::Client::Git