NAME

       KGB_protocol - specification of the client-server communication protocol

DESCRIPTION

       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.

AUTHENTICATION

       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.

METHODS

   commit_v4 arguments
       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_id string
           A string identifying the commit in the version control system. Git (short) hash,
           Subversion revision number, this kind of thing.

       rev_prefix string
           A string to prepend to the commit ID when displaying on IRC. "r" is particularly
           useful for Subversion repositories.

       author string
           A string representing the commit author.

       branch string
           A string representing the commit branch.

       module string
           A string representing the commit module or sub-project.

       commit_log string
           The commit message.

       changes list of strings
           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+)".

       extra map
           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_message message
       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.

   ERRORS
       Errors reported on HTTP level

       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).

       Errors reported on JSON-RPC level

       After successful authentication and decoding of the JSON request, all the errors are
       reported as mandated by the JSON-RPC specification.

AUTHOR

       Damyan Ivanov dmn@debian.org

COPYRIGHT & LICENSE

       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.