KGB_protocol - specification of the client-server communication protocol
The protocol used by the KGB collaboration service is based on JSON-RPC
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
Message content is authenticated by using two HTTP headers. The
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
header, the authentication succeeds and the request is
processed. Otherwise an error is returned.
This method takes information about a single commit and relays it to IRC.
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
- rev_prefix string
- A string to prepend to the commit ID when displaying on
IRC. "r" is particularly useful for Subversion
- 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
- 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.
- extra map
- A map with additional parameters. Currently supported
- A URL with commit details (e.g. gitweb or viewvc).
- A flag whether to use IRC notices instead of regular
- A flag whether to use colors when sending commit
notifications. Defaults to 1.
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 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,
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.
- Damyan Ivanov firstname.lastname@example.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
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.