/ 
App-KGB-1.61
River stage zero No dependents
/ KGB_protocol

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:

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.