1App::KGB::Client(3) User Contributed Perl Documentation App::KGB::Client(3)
2
6 App::KGB::Client - relay commits to KGB servers
7
9 use App::KGB::Client;
10 my $client = App::KGB::Client( <parameters> );
11 $client->run;
12
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
21 The following parameters are accepted in the constructor:
22 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 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 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 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 timeout seconds
42 Timeout for server communication. Default is 15 seconds, as we want
43 instant IRC and commit response.
44 servers
46 An array of servers, each an instance of
47 App::KGB::Client::ServerRef class.
48 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 When shuffling, preference is added to the last server used by the
55 client, or by other clients (given "status_dir" is configured).
56 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 Defaults to false, but will be changed later after some grace
63 period for server upgrade.
64 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 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 Example: ^/(trunk)/([^/]+)/
78 # /trunk/module/file
79 ^/branches/([^/]+)/([^/]+)/
80 # /branches/test/module/file
81 mod_br_re
83 Same as br_mod_re, but captures module name first and branch name
84 second.
85 Example: ^/branches/([^/]+)/([^/]+)/
87 # /branches/test/module/file
88 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 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 single_line_commits off|forced|auto
103 Request different modes of commit message processing:
104 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 forced
111 Only the first line is sent to IRC, regardless of whether it is
112 followed by a blank line or not.
113 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 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 use_color
125 If true (the default) signals the server that it should use colors
126 for commit notifications.
127 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 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 verbose
140 Print diagnostic information.
141 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 web_link template
148 A web link template to be sent to the server. The following items
149 are expanded:
150 ${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 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 The following special items are recognized and replaced with the
166 respective commit elements.
167 ${project_id}
169 The ID of the project.
170 ${author_login}
172 The login of the author (e.g. "joe").
173 ${author_name}
175 The name of the commit author (e.g. "Joe Random")
176 ${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 ${branch}
183 The branch of the commit.
184 ${module}
186 The module of the commit.
187 ${commit} =item ${revision}
189 The ID of the commit.
190 ${path}
192 The changed path(s).
193 ${log}
195 The log message of the commit.
196 ${web}
198 The web link associated with the commit. Replaced with the
199 empty string unless the web_link option is also given.
200 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 revision =item commit_id
208 Commit ID. Default: none.
209 path
211 Changed path. Default: teal.
212 Depending on the action performed to the path, additional
214 coloring is made:
215 addition
217 Used for added paths. Default: green.
218 modification
220 Used for modified paths. Default: teal.
221 deletion
223 Used for deleted paths. Default: bold red.
224 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 author
234 Commit author. Default: green.
235 branch
237 Commit branch. Default: brown.
238 module
240 Project module. Default: purple.
241 web URL to commit information. Default: silver.
243 separator
245 The separator before the commit log. Default: none.
246
248 new ( { initial values } )
249 Standard constructor with initial values in a hashref.
250 my $c = App::KGB::Client->new(
252 { repo_id => 'my-repo',
253 servers => \@servers,
254 ...
255 }
256 );
257 See above.
259
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 ( $branch, $module ) = $client->detect_branch_and_module($changes);
268 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 expand_link ($string, \%data)
277 Expands items in the form ${item} in $string, using the data in the
278 supplied hash reference.
279 Passing
281 "http://git/${module}.git?commit=${commit}",
283 { module => 'dh-make-perl', commit => '225ceca' }
284 would result in "http://git/dh-make-perl.git?commit=225ceca".
286 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 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 init_painter
296 Creates an internal instance of App::KGB::Painter used to color
297 message elements.
298 Does nothing if use_color is false or if painter has been already
300 created.
301 colorize category => text
303 Returns a colored version of text. If there is no painter, returns
304 just text.
305 colorize_change change
307 returns a colorized string representing a single change
308 colorize_changes \@changes
310 returns a colorized string of all commit's changes
311 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 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 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 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 If batch_messages flag is true, relays accumulated messages after
333 processing.
334 send_changes \@args
336 Tries to send the changes described in the given array reference to
337 all configured servers.
338 relay_message message
340 Send a simple message to servers for relaying. Implements the
341 --relay-msg command line option.
342
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 Repository classes must provide the following method:
350 dsescribe_commit
352 This method returns an App::KGB::Commit object that represents a
353 single commit of the repository.
354 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
364 App::KGB::Client::Subversion
365 App::KGB::Client::Git
366perl v5.34.0 2021-07-22 App::KGB::Client(3)