KGB_protocol - specification of the client-server communication protocol

Message content is authenticated by using two HTTP headers. The X-KGB-Project header must contain the project ID, as defined in server's configuration. The X-KGB-Auth header must contain a SHA1 hash (in hexadecimal notation) calculated over the shared secret, the project ID and the JSON-encoded message. Upon receiving the HTTP request the server calculates the hash using the supplied project ID, the server copy of the shared secret for that project and the content of the HTTP request. If the hash matches the one provided in the X-KGB-Auth header, the authentication succeeds and the request is processed. Otherwise an error is returned.

Damyan Ivanov dmn@debian.org

Copyright (C) 2012 Damyan Ivanov This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. perl v5.40.0 2024-09-20 KGB-PROTOCOL(7p)

The protocol used by the KGB collaboration service is based on JSON-RPC (<http://json-rpc.org/>). KGB service helps collaboration by relaying notifications about commits in a version control system to IRC. It consists of client, hooked to the version control system which sends information about changes to the server, and a server, listening for client's notifications and relaying them on configured IRC channels.

commit_v4arguments This method takes information about a single commit and relays it to IRC. arguments is a map with the members described below. Any additional members are ignored. commit_idstring A string identifying the commit in the version control system. Git (short) hash, Subversion revision number, this kind of thing. rev_prefixstring A string to prepend to the commit ID when displaying on IRC. "r" is particularly useful for Subversion repositories. authorstring A string representing the commit author. branchstring A string representing the commit branch. modulestring A string representing the commit module or sub-project. commit_logstring The commit message. changeslistofstrings List of changes files/directories in the commit. Each string is a path, optionally prepended with "(A)" for added paths, "(M)" for modified paths and "(D)" for deleted paths. If no prefix is given modification is assumed. An additional plus sign flags property changes (Specific to Subversion term), e.g. "(M+)". extramap A map with additional parameters. Currently supported members are: web_link A URL with commit details (e.g. gitweb or viewvc). use_irc_notices A flag whether to use IRC notices instead of regular messages. use_color A flag whether to use colors when sending commit notifications. Defaults to 1. relay_messagemessage This method takes only one string argument which is the message to relay to IRC. There are no restrictions or requirements to the message content, which is relayed verbatim to project's IRC channels. ERRORSErrorsreportedonHTTPlevel Authentication errors use HTTP code 401, while other errors -- bad or missing headers and problems with the JSON data use HTTP code 400. The error text is in the reason phrase of the HTTP status line (see RFC 2616, section 6.1). ErrorsreportedonJSON-RPClevel After successful authentication and decoding of the JSON request, all the errors are reported as mandated by the JSON-RPC specification.

KGB_protocol - specification of the client-server communication protocol