1KGB-PROTOCOL(7p)      User Contributed Perl Documentation     KGB-PROTOCOL(7p)
2
3
4

NAME

6       KGB_protocol - specification of the client-server communication
7       protocol
8

DESCRIPTION

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

AUTHENTICATION

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

METHODS

33   commit_v4 arguments
34       This method takes information about a single commit and relays it to
35       IRC.  arguments is a map with the members described below. Any
36       additional members are ignored.
37
38       commit_id string
39           A string identifying the commit in the version control system. Git
40           (short) hash, Subversion revision number, this kind of thing.
41
42       rev_prefix string
43           A string to prepend to the commit ID when displaying on IRC. "r" is
44           particularly useful for Subversion repositories.
45
46       author string
47           A string representing the commit author.
48
49       branch string
50           A string representing the commit branch.
51
52       module string
53           A string representing the commit module or sub-project.
54
55       commit_log string
56           The commit message.
57
58       changes list of strings
59           List of changes files/directories in the commit. Each string is a
60           path, optionally prepended with "(A)" for added paths, "(M)" for
61           modified paths and "(D)" for deleted paths. If no prefix is given
62           modification is assumed. An additional plus sign flags property
63           changes (Specific to Subversion term), e.g.  "(M+)".
64
65       extra map
66           A map with additional parameters. Currently supported members are:
67
68           web_link
69               A URL with commit details (e.g. gitweb or viewvc).
70
71           use_irc_notices
72               A flag whether to use IRC notices instead of regular messages.
73
74           use_color
75               A flag whether to use colors when sending commit notifications.
76               Defaults to 1.
77
78   relay_message message
79       This method takes only one string argument which is the message to
80       relay to IRC. There are no restrictions or requirements to the message
81       content, which is relayed verbatim to project's IRC channels.
82
83   ERRORS
84       Errors reported on HTTP level
85
86       Authentication errors use HTTP code 401, while other errors -- bad or
87       missing headers and problems with the JSON data use HTTP code 400.
88
89       The error text is in the reason phrase of the HTTP status line (see RFC
90       2616, section 6.1).
91
92       Errors reported on JSON-RPC level
93
94       After successful authentication and decoding of the JSON request, all
95       the errors are reported as mandated by the JSON-RPC specification.
96

AUTHOR

98       Damyan Ivanov dmn@debian.org
99

101       Copyright (C) 2012 Damyan Ivanov
102
103       This program is free software; you can redistribute it and/or modify it
104       under the terms of the GNU General Public License as published by the
105       Free Software Foundation; either version 2 of the License, or (at your
106       option) any later version.
107
108       This program is distributed in the hope that it will be useful, but
109       WITHOUT ANY WARRANTY; without even the implied warranty of
110       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
111       General Public License for more details.
112
113       You should have received a copy of the GNU General Public License along
114       with this program; if not, write to the Free Software Foundation, Inc.,
115       51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
116
117
118
119perl v5.28.2                      2018-06-04                  KGB-PROTOCOL(7p)
Impressum