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).
- batch_messages
- If true, the notifications are sent as a batch in one request to the
server. Useful with VCS that send many changes a time (e.g. Git).
Defaults to false, but will be changed later after some grace period for
server upgrade.
- 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: ^/(trunk)/([^/]+)/
# /trunk/module/file
^/branches/([^/]+)/([^/]+)/
# /branches/test/module/file
- mod_br_re
- Same as br_mod_re, but captures module name first and branch name
second.
Example: ^/branches/([^/]+)/([^/]+)/
# /branches/test/module/file
- ignore_branch
- When most of the development is in one branch, transmitting it to the KGB
server and seeing it on IRC all the time can be annoying. 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, regardless 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.
- use_irc_notices
- If true signals the server that it should use IRC notices instead of
regular messages. Use this if regular messages are too distracting for
your channel.
- use_color
- If true (the default) signals the server that it should use colors for
commit notifications.
- status_dir
- Specifies a directory to store information about the last server contacted
successfully. 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.
- protocol version
- Use specified protocol version. If "auto" (the default), the
version of the protocol 2, unless web_link is also given, in which
case protocol version 3 is default;
- web_link template
- A web link template to be sent to the server. The following items are
expanded:
- ${branch}
- ${module}
- ${commit}
- ${project}
- short_url_service service
- A WWW::Shorten service to use for shortening the web_link. See
WWW::Shorten for the list of supported services.
- msg_template string
- Provides a way to customize the notifications' appearance on IRC. When
present, all message construction is done on the client and the prepared
messages (possibly with colors etc) are sent to the server for relaying to
IRC.
The following special items are recognized and replaced with the respective
commit elements.
- ${project_id}
- The ID of the project.
- ${author_login}
- The login of the author (e.g. "joe").
- ${author_name}
- The name of the commit author (e.g. "Joe Random")
- ${branch}
- The branch of the commit.
- ${module}
- The module of the commit.
- ${commit} =item ${revision}
- The ID of the commit.
- ${path}
- The changed path(s).
- ${log}
- The log message of the commit.
- ${web}
- The web link associated with the commit. Replaced with the empty string
unless the web_link option is also given.
- style hash reference
- Provides a color map for different parts of the message. The following
keys are supported. Defaults are used when keys are missing in the hash.
use_color must be true for this to have any effect. Used only when
msg_template is also given.
- revision =item commit_id
- Commit ID. Default: none.
- path
- Changed path. Default: teal.
Depending on the action performed to the path, additional coloring is
made:
- addition
- Used for added paths. Default: green.
- modification
- Used for modified paths. Default: teal.
- deletion
- Used for deleted paths. Default: bold red.
- replacement Used for replaced paths (a Subversion concept). Default:
brown.
- prop_change
- Used for paths with changed properties (a Subversion concept), combined
with other colors depending on the action -- addition, modification or
replacement. Default: underline.
- author
- Commit author. Default: green.
- branch
- Commit branch. Default: brown.
- module
- Project module. Default: purple.
- web
- URL to commit information. Default: silver.
- separator
- The separator before the commit log. Default: none.
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 mod_br_re
and if a regular expression that matches all the changed paths and returns
the branch and 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.
- expand_link ($string, \%data)
- Expands items in the form ${item} in $string,
using the data in the supplied hash reference.
Passing
"http://git/${module}.git?commit=${commit}",
{ module => 'dh-make-perl', commit => '225ceca' }
would result in "http://git/dh-make-perl.git?commit=225ceca".
- shorten_url (url)
- Uses the configured short_url_service to shorten the given URL. If
no shortening service is configured, the original URL is returned.
- note_last_server($srv)
- If "status_dir" is configured, notes $srv as the last used
server to be used in subsequent requests.
- init_painter
- Creates an internal instance of App::KGB::Painter used to color message
elements.
Does nothing if use_color is false or if painter has been already
created.
- colorize category => text
- Returns a colored version of text. If there is no painter, returns
just text.
- colorize_change change
- returns a colorized string representing a single change
- colorize_changes \@changes
- returns a colorized string of all commit's changes
- format_message $template %details
- Returns a formatted message, ready to be sent to the servers. The message
is formatted according to the message_format configuration
parameter, honouring colors and use_color.
- process_commit ($commit)
- Processes a single commit, returning something for sending to the remote
server. Something is either a reference to array of arguments to be
passed to App::KGB::ServerRef's send_changes method, or, in message-relay
mode, a plain scalar string representing the commit.
If $commit is a plain scalar (not a reference), then it is assumed to be an
already processed string and is returned directly.
- process
- The main processing method. Calls describe_commit and while it
returns true values, gives them to process_commit and send the
result to the server.
If batch_messages flag is true, relays accumulated messages after
processing.
- send_changes \@args
- Tries to send the changes described in the given array reference to all
configured servers.
- relay_message message
- Send a simple message to servers for relaying. Implements the --relay-msg
command line option.
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(1)). If this is the case each call to describe_commit
shall return information about the next commit in the series. For
svn(1), this module is expected to return only one commit,
subsequent calls shall return "undef".
SEE ALSO¶
- App::KGB::Client::Subversion
- App::KGB::Client::Git