1App::KGB::Client(3)   User Contributed Perl Documentation  App::KGB::Client(3)
2
3
4

NAME

6       App::KGB::Client - relay commits to KGB servers
7

SYNOPSIS

9           use App::KGB::Client;
10           my $client = App::KGB::Client( <parameters> );
11           $client->run;
12

DESCRIPTION

14       App::KGB::Client is the backend behind kgb-client(1). It handles the
15       repository-independent parts of sending the notifications to the KGB
16       server, kgb-bot(1). Details about extracting change from commits,
17       branches and modules is done by sub-classes specific to the version
18       control system in use.
19

CONFIGURATION

21       The following parameters are accepted in the constructor:
22
23       repo_id repository name
24           Short repository identifier. Will be used for identifying the
25           repository to the KGB daemon, which will also use this for IRC
26           notifications. Mandatory.
27
28       uri URI
29           URI of the KGB server. Something like "http://some.server:port".
30           Mandatory either as a top-level parameter or as a sub-parameter of
31           servers array.
32
33       proxy URI
34           URI of the SOAP proxy. If not given, it is the value of the uri
35           option, with "?session=KGB" added.
36
37       password password
38           Password for authentication to the KGB server. Mandatory either as
39           a top-level parameter or as a sub-parameter of servers array.
40
41       timeout seconds
42           Timeout for server communication. Default is 15 seconds, as we want
43           instant IRC and commit response.
44
45       servers
46           An array of servers, each an instance of
47           App::KGB::Client::ServerRef class.
48
49           When several servers are configured, the list is shuffled and then
50           the servers are tried one after another until a successful request
51           is done, or the list is exhausted, in which case an exception is
52           thrown.
53
54           When shuffling, preference is added to the last server used by the
55           client, or by other clients (given "status_dir" is configured).
56
57       batch_messages
58           If true, the notifications are sent as a batch in one request to
59           the server.  Useful with VCS that send many changes a time (e.g.
60           Git).
61
62           Defaults to false, but will be changed later after some grace
63           period for server upgrade.
64
65       br_mod_re
66           A list of regular expressions (simple strings, not qr objects) that
67           serve for detection of branch and module of commits. Each item from
68           the list is tried in turn, until an item is found that matches all
69           the paths that were modified by the commit. Regular expressions
70           must have two captures: the first one giving the branch name, and
71           the second one giving the module name.
72
73           All the paths that were modified by the commit must resolve to the
74           same branch and module in order for the branch and module to be
75           transmitted to the KGB server.
76
77               Example: ^/(trunk)/([^/]+)/
78                        # /trunk/module/file
79                        ^/branches/([^/]+)/([^/]+)/
80                        # /branches/test/module/file
81
82       mod_br_re
83           Same as br_mod_re, but captures module name first and branch name
84           second.
85
86               Example: ^/branches/([^/]+)/([^/]+)/
87                        # /branches/test/module/file
88
89       ignore_branch
90           When most of the development is in one branch, transmitting it to
91           the KGB server and seeing it on IRC all the time can be annoying.
92           Therefore, if you define ignore_branch, and a given commit is in a
93           branch with that name, the branch name is not transmitted to the
94           server. Module name is still transmitted.
95
96       module
97           Forces explicit module name, overriding the branch and module
98           detection. Useful in Git-hosted sub-projects that want to share
99           single configuration file, but still want module indication in
100           notifications.
101
102       single_line_commits off|forced|auto
103           Request different modes of commit message processing:
104
105           off No processing is done. The commit message is printed as was
106               given, with each line in a separate IRC message, blank lines
107               omitted. This is the only possible behaviour in versions before
108               1.14.
109
110           forced
111               Only the first line is sent to IRC, regardless of whether it is
112               followed by a blank line or not.
113
114           auto
115               If the first line is followed by an empty line, only the first
116               line is sent to IRC and the rest is ignored. This is the
117               default since version 1.14.
118
119       use_irc_notices
120           If true signals the server that it should use IRC notices instead
121           of regular messages. Use this if regular messages are too
122           distracting for your channel.
123
124       use_color
125           If true (the default) signals the server that it should use colors
126           for commit notifications.
127
128       status_dir
129           Specifies a directory to store information about the last server
130           contacted successfully. The client would touch files in that
131           directory after successful completion of a notification with remote
132           server.
133
134           Later, when asked to do another notification, the client would
135           start from the most recently contacted server. If that was
136           contacted too far in the past, the information in the directory is
137           ignored and a random server is picked, as usual.
138
139       verbose
140           Print diagnostic information.
141
142       protocol version
143           Use specified protocol version. If "auto" (the default), the
144           version of the protocol 2, unless web_link is also given, in which
145           case protocol version 3 is default;
146
147       web_link template
148           A web link template to be sent to the server. The following items
149           are expanded:
150
151           ${branch}
152           ${module}
153           ${commit}
154           ${project}
155       short_url_service service
156           A WWW::Shorten service to use for shortening the web_link. See
157           WWW::Shorten for the list of supported services.
158
159       msg_template string
160           Provides a way to customize the notifications' appearance on IRC.
161           When present, all message construction is done on the client and
162           the prepared messages (possibly with colors etc) are sent to the
163           server for relaying to IRC.
164
165           The following special items are recognized and replaced with the
166           respective commit elements.
167
168           ${project_id}
169               The ID of the project.
170
171           ${author_login}
172               The login of the author (e.g. "joe").
173
174           ${author_name}
175               The name of the commit author (e.g. "Joe Random")
176
177           ${author_via}
178               The name of the commit author, plus the name of the committer
179               if that is different (e.g. "Joe Random" or "Joe Random (via Max
180               Random)")
181
182           ${branch}
183               The branch of the commit.
184
185           ${module}
186               The module of the commit.
187
188           ${commit} =item ${revision}
189               The ID of the commit.
190
191           ${path}
192               The changed path(s).
193
194           ${log}
195               The log message of the commit.
196
197           ${web}
198               The web link associated with the commit. Replaced with the
199               empty string unless the web_link option is also given.
200
201       style hash reference
202           Provides a color map for different parts of the message. The
203           following keys are supported. Defaults are used when keys are
204           missing in the hash. use_color must be true for this to have any
205           effect. Used only when msg_template is also given.
206
207           revision =item commit_id
208               Commit ID. Default: none.
209
210           path
211               Changed path. Default: teal.
212
213               Depending on the action performed to the path, additional
214               coloring is made:
215
216               addition
217                   Used for added paths. Default: green.
218
219               modification
220                   Used for modified paths. Default: teal.
221
222               deletion
223                   Used for deleted paths. Default: bold red.
224
225               replacement Used for replaced paths (a Subversion concept).
226               Default: brown.
227               prop_change
228                   Used for paths with changed properties (a Subversion
229                   concept), combined with other colors depending on the
230                   action -- addition, modification or replacement.  Default:
231                   underline.
232
233           author
234               Commit author. Default: green.
235
236           branch
237               Commit branch. Default: brown.
238
239           module
240               Project module. Default: purple.
241
242           web URL to commit information. Default: silver.
243
244           separator
245               The separator before the commit log. Default: none.
246

CONSTRUCTOR

248   new ( { initial values } )
249       Standard constructor with initial values in a hashref.
250
251           my $c = App::KGB::Client->new(
252               {   repo_id => 'my-repo',
253                   servers => \@servers,
254                   ...
255               }
256           );
257
258       See  above.
259

METHODS

261       detect_branch_and_module ( $changes )
262           Given a set of changes (an arrayref of App::KGB::Change objects),
263           runs all the regular expressions as listed in br_mod_re and
264           mod_br_re and if a regular expression that matches all the changed
265           paths and returns the branch and module.
266
267               ( $branch, $module ) = $client->detect_branch_and_module($changes);
268
269       shuffle_servers
270           Returns a shuffled variant of "$self->servers". It considers the
271           last successfully used server by this client instance and puts it
272           first. If there is no such server, it considers the state in
273           "status_dir" and picks the last server noted there, if it was used
274           in the last 5 minutes.
275
276       expand_link ($string, \%data)
277           Expands items in the form ${item} in $string, using the data in the
278           supplied hash reference.
279
280           Passing
281
282            "http://git/${module}.git?commit=${commit}",
283            { module => 'dh-make-perl', commit => '225ceca' }
284
285           would result in "http://git/dh-make-perl.git?commit=225ceca".
286
287       shorten_url (url)
288           Uses the configured short_url_service to shorten the given URL. If
289           no shortening service is configured, the original URL is returned.
290
291       note_last_server($srv)
292           If "status_dir" is configured, notes $srv as the last used server
293           to be used in subsequent requests.
294
295       init_painter
296           Creates an internal instance of App::KGB::Painter used to color
297           message elements.
298
299           Does nothing if use_color is false or if painter has been already
300           created.
301
302       colorize category => text
303           Returns a colored version of text. If there is no painter, returns
304           just text.
305
306       colorize_change change
307           returns a colorized string representing a single change
308
309       colorize_changes \@changes
310           returns a colorized string of all commit's changes
311
312       format_message $template %details
313           Returns a formatted message, ready to be sent to the servers. The
314           message is formatted according to the message_format configuration
315           parameter, honouring colors and use_color.
316
317       process_commit ($commit)
318           Processes a single commit, returning something for sending to the
319           remote server. Something is either a reference to array of
320           arguments to be passed to App::KGB::ServerRef's send_changes
321           method, or, in message-relay mode, a plain scalar string
322           representing the commit.
323
324           If $commit is a plain scalar (not a reference), then it is assumed
325           to be an already processed string and is returned directly.
326
327       process
328           The main processing method. Calls describe_commit and while it
329           returns true values, gives them to process_commit and send the
330           result to the server.
331
332           If batch_messages flag is true, relays accumulated messages after
333           processing.
334
335       send_changes \@args
336           Tries to send the changes described in the given array reference to
337           all configured servers.
338
339       relay_message message
340           Send a simple message to servers for relaying. Implements the
341           --relay-msg command line option.
342

PROVIDING REPOSITORY-SPECIFIC FUNCTIONALITY

344       App::KGB::Client is a generic class providing repository-agnostic
345       functionality. All repository-specific methods are to be provided by
346       classes, inheriting from App::KGB::Client. See
347       App::KGB::Client::Subversion and App::KGB::Client::Git.
348
349       Repository classes must provide the following method:
350
351       dsescribe_commit
352           This method returns an App::KGB::Commit object that represents a
353           single commit of the repository.
354
355           describe_commit is called several times, until it returns "undef".
356           The idea is that a single App::KGB::Client run can be used to
357           process several commits (for example if the repository is git(1)).
358           If this is the case each call to describe_commit shall return
359           information about the next commit in the series. For svn(1), this
360           module is expected to return only one commit, subsequent calls
361           shall return "undef".
362

SEE ALSO

364       App::KGB::Client::Subversion
365       App::KGB::Client::Git
366
367
368
369perl v5.32.0                      2020-12-16               App::KGB::Client(3)
Impressum