--- name: "App::KGB::Client" section: "3pm" platform: "linux" package: "kgb-client" version: "1.61-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/App::KGB::Client" --- # App::KGB::Client(3pm) relay commits to KGB servers ## NAME App::KGB::Client - relay commits to KGB servers ## SYNOPSIS ``` use App::KGB::Client; my $client = App::KGB::Client( ); $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") - ${author\_via} The name of the commit author, plus the name of the committer if that is different (e.g. "Joe Random" or "Joe Random (via Max 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 successfully 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)](/git/1.md)). If this is the case each call to **describe\_commit** shall return information about the next commit in the series. For [**svn**(1)](/svn/1.md), this module is expected to return only one commit, subsequent calls shall return `"undef"`. ## SEE ALSO - App::KGB::Client::Subversion - App::KGB::Client::Git