| 1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11-strict.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Style-Type" content="text/css"/> |
| 6 |
<style type="text/css">@import "style.css";</style> |
| 7 |
<title>IRC Services Technical Reference Manual - 1. Program structure overview</title> |
| 8 |
</head> |
| 9 |
|
| 10 |
<body> |
| 11 |
<h1 class="title" id="top">IRC Services Technical Reference Manual</h1> |
| 12 |
|
| 13 |
<h2 class="section-title">1. About this manual</h2> |
| 14 |
|
| 15 |
<p class="section-toc"> |
| 16 |
1-1. <a href="#s1">Intended audience</a> |
| 17 |
<br/>1-2. <a href="#s2">Structure of this manual</a> |
| 18 |
<br/>1-3. <a href="#s3">History of Services development</a> |
| 19 |
</p> |
| 20 |
|
| 21 |
<p class="backlink"><a href="index.html">Table of Contents</a> | |
| 22 |
<a href="2.html">Next section: Core Services functionality</a></p> |
| 23 |
|
| 24 |
<!------------------------------------------------------------------------> |
| 25 |
<hr/> |
| 26 |
|
| 27 |
<h3 class="subsection-title" id="s1">1-1. Intended audience</h3> |
| 28 |
|
| 29 |
<p>This manual is written with an intended audience of programmers looking |
| 30 |
to change or extend the IRC Services source code, and covers the overall |
| 31 |
structure of the code as well as details on each of Services' functions. |
| 32 |
The content of this manual is highly technical, and requires a reasonably |
| 33 |
high level of expertise (both in programming in general and in the C |
| 34 |
language and Unix computer systems in particular) to peruse.</p> |
| 35 |
|
| 36 |
<p>For information on installing and using IRC Services, please see the |
| 37 |
<a href="../index.html">user's manual</a>.</p> |
| 38 |
|
| 39 |
<p>Note that this manual describes Services for IRC Networks version 5.1.24, |
| 40 |
and its contents may not be applicable to modified versions or derivative |
| 41 |
programs. Also, this manual is intended to be used alongside the source |
| 42 |
code; details of function parameters, structure fields, and the like are |
| 43 |
often omitted for the sake of brevity and clarity. <!-- Use the source, |
| 44 |
Luke! --> </p> |
| 45 |
|
| 46 |
|
| 47 |
<p class="backlink"><a href="#top">Back to top</a></p> |
| 48 |
|
| 49 |
<!------------------------------------------------------------------------> |
| 50 |
<hr/> |
| 51 |
|
| 52 |
<h3 class="subsection-title" id="s2">1-2. Structure of this manual</h3> |
| 53 |
|
| 54 |
<p>Services can be broken up into two parts: the <b>core functionality</b>, |
| 55 |
which implements the "IRC server" part of Services, and <b>modules</b>, |
| 56 |
which add the "bot-like" functions to Services as well as provide common |
| 57 |
interfaces to differing implementations of some functions.</p> |
| 58 |
|
| 59 |
<p>The core Services functionality is primarily discussed in |
| 60 |
<a href="2.html">section 2</a>. Two topics, however, are given their own |
| 61 |
sections due to their complexity: communications (<a href="3.html">section |
| 62 |
3</a>) and module handling (<a href="4.html">section 4</a>).</p> |
| 63 |
|
| 64 |
<p>Modules are divided into four groups:</p> |
| 65 |
|
| 66 |
<ul> |
| 67 |
<li><b>protocol modules</b> (<a href="5.html">section 5</a>), which |
| 68 |
handle the interface between the generic IRC server implemented by the |
| 69 |
Services core and the particular protocols used by various IRC servers;</li> |
| 70 |
<li><b>database modules</b> (<a href="6.html">section 6</a>), which handle |
| 71 |
the storage and retrieval of data used by pseudoclients and other Services |
| 72 |
functions;</li> |
| 73 |
<li><b>pseudoclient modules</b> (<a href="7.html">section 7</a>), which |
| 74 |
implement the various pseudoclients themselves; and</li> |
| 75 |
<li><b>other modules</b> (<a href="8.html">section 8</a>), including all |
| 76 |
modules not covered above.</li> |
| 77 |
</ul> |
| 78 |
|
| 79 |
<p><a href="9.html">Section 9</a> covers <tt>convert-db</tt>, the tool |
| 80 |
included with Services to convert databases from other Services-like |
| 81 |
programs to an XML data stream that can then be imported into Services |
| 82 |
itself. The compilation of Services (the <tt>configure</tt> script and |
| 83 |
<tt>Makefile</tt> files) is described in <a href="10.html">section 10</a>, |
| 84 |
and areas where Services could potentially be improved are discussed in |
| 85 |
<a href="11.html">section 11</a>.</p> |
| 86 |
|
| 87 |
<p>A source code reference is included as <a href="a.html">Appendix A</a> |
| 88 |
(by source file) and <a href="b.html">Appendix B</a> (by function name).</p> |
| 89 |
|
| 90 |
<p class="backlink"><a href="#top">Back to top</a></p> |
| 91 |
|
| 92 |
<!------------------------------------------------------------------------> |
| 93 |
<hr/> |
| 94 |
|
| 95 |
<h3 class="subsection-title" id="s3">1-3. History of Services development</h3> |
| 96 |
|
| 97 |
<p>Before discussing the details of the Services code base, it is worth |
| 98 |
mentioning the history of Services development.</p> |
| 99 |
|
| 100 |
<p>Originally, I (Andrew Church, the developer of Services) started writing |
| 101 |
Services as something of a "quick hack" for my personal server, which I had |
| 102 |
set up for the use of a channel I frequented at the time that had decided |
| 103 |
to move away from the DALnet IRC network. DALnet did not at the time—and |
| 104 |
to the best of my knowledge still does not—publish the source code to |
| 105 |
their nickname and channel registration services, nor was I able to locate |
| 106 |
any other similar usable open-source software, so I took the route of |
| 107 |
writing my own. This motive had, at least initially, significant influence |
| 108 |
on the user interface design; the service nicknames NickServ and ChanServ |
| 109 |
seem to have been around since the early days of IRC, but the basic |
| 110 |
commands, such as <tt>REGISTER</tt>, <tt>SET</tt>, and the NickServ |
| 111 |
<tt>RECOVER</tt> and <tt>RELEASE</tt> functions, were based on those seen |
| 112 |
on DALnet. (Ironically, it seems that DALnet has since incorporated at |
| 113 |
least one feature, the channel successor concept, from this program due to |
| 114 |
user pressure.)</p> |
| 115 |
|
| 116 |
<p>The first "release" of Services—using the term loosely, |
| 117 |
since I had no interest in releasing Services publicly at this |
| 118 |
point—was made on April 5, 1996, when the program first went online. |
| 119 |
Since my IRC server was mainly for private use, there was little call for |
| 120 |
additional features, and aside from occasional bug fixes, not much |
| 121 |
development was performed during this time. The code base itself could be |
| 122 |
called "functional" at best; while I have always put effort into writing |
| 123 |
good code rather than simply "working" code, I had considerably less skill |
| 124 |
in programming at that time. In fact, work on Services accounted for a |
| 125 |
significant amount of my programming experience during its first several |
| 126 |
years of existence, and careful reading of the Services source code may |
| 127 |
well reveal the effect of that experience.</p> |
| 128 |
|
| 129 |
<p>My private IRC server eventually expanded into a small network, as |
| 130 |
friends of mine connected servers of their own. I stored a copy of the |
| 131 |
Services source code on each server, both to function as a backup of the |
| 132 |
code itself and to allow a backup copy of Services to be started in case |
| 133 |
the primary one should fail for some reason. This backfired, however, when |
| 134 |
one such server was broken into on November 19, 1996; a few days later, we |
| 135 |
received a message essentially accusing us of stealing Services from |
| 136 |
another IRC network called IceNet. Investigation showed the purported |
| 137 |
"original" Services to in fact be a copy of my own program, presumably |
| 138 |
taken from the broken-into server. I was naturally upset, and exchanged |
| 139 |
several angry messages with an IceNet administrator, but the situation was |
| 140 |
amicably resolved in the end, and IceNet continued using my program.</p> |
| 141 |
|
| 142 |
<p>After this incident, I began receiving occasional requests for copies of |
| 143 |
the program, and at some point over the next month or two I decided that, |
| 144 |
since so many people seemed interested in it and I had no particular reason |
| 145 |
to keep it secret, I would release the source code publicly, free for |
| 146 |
anyone to use. The first public release was version 2.2.0, on January 10, |
| 147 |
1997. This sudden "change of heart" is also the reason Services has such a |
| 148 |
generic name: I had not originally planned to publish the program, so I had |
| 149 |
not bothered to come up with a distinctive name for it. The moniker |
| 150 |
"EsperNet Services", from the name of the network for which I developed it, |
| 151 |
appeared every now and then, but (partly to avoid users of the program |
| 152 |
flooding EsperNet administrators with help requests) I only called it |
| 153 |
"Services". The current full name, "Services for IRC Networks", was chosen |
| 154 |
when the program was listed on the <a href="http://freshmeat.net/">FreshMeat |
| 155 |
software index</a> <span class="remotehost">[freshmeat.net]</span>.</p> |
| 156 |
|
| 157 |
<p>I continued Services development through mid-1999, extending the program |
| 158 |
to deal with users' feature requests and my own experience. But after |
| 159 |
graduating from university and moving to Japan to work, I found myself with |
| 160 |
little time available for work on Services; so, after doing some |
| 161 |
preliminary work for version 4.3, I handed the code base off to Andrew |
| 162 |
Kempe, a user of Services who had contributed numerous suggestions and |
| 163 |
improvements. At the time, I had already had some preliminary thoughts |
| 164 |
toward redesigning Services, including the module system which eventually |
| 165 |
saw the light of day in version 5.0, but as my IRC use had declined |
| 166 |
significantly, I had intended to just let Services go, to be developed by |
| 167 |
others with more interest.</p> |
| 168 |
|
| 169 |
<p>However, in late 2000, Andrew Kempe wrote to me explaining that he no |
| 170 |
longer had time to work on Services, and I ended up deciding to continue |
| 171 |
Services development where he had left off. I reviewed his additions, |
| 172 |
notably the session limiting system (now the <tt>operserv/sessions</tt> |
| 173 |
module), and began preparations for releasing version 4.5. I also began |
| 174 |
using the CVS source code management tool to keep better track of changes |
| 175 |
to the code. (I had at one point considered taking advantage of CVS to |
| 176 |
allow others to update the code as well, but copyright issues aside, there |
| 177 |
were simply very few people I trusted to write code to my standards, and |
| 178 |
with the exception for a time of a friend from EsperNet, I was the only one |
| 179 |
who actually developed the code.)</p> |
| 180 |
|
| 181 |
<p>After releasing version 4.5.0, I decided to start work on a major |
| 182 |
redesign of Services, including the implementation of my former module |
| 183 |
idea. Over the five years until this time, the Services source code had |
| 184 |
not undergone any significant redesign, and the result of continually |
| 185 |
adding features on top of other features was, to put it politely, a mess. |
| 186 |
In one of my favorite computer science books, <i>The Mythical Man-Month</i>, |
| 187 |
the author, Dr. Frederick Brooks, gives as one of the tenets of software |
| 188 |
development: "<i>Plan to throw one away; you will, anyhow</i>" (chapter |
| 189 |
11). Indeed, I had learned a lot about both software design and |
| 190 |
programming in general and IRC service software in particular over the |
| 191 |
years, and it was easy to see where the current Services code was |
| 192 |
inadequate or poorly designed. So, around the release of version 4.5.8, I |
| 193 |
split off a copy of the code base, added in the module support system I had |
| 194 |
started work on separately, and began a year-plus effort to clean up the |
| 195 |
code. I did not actually rewrite the program from scratch, since I lacked |
| 196 |
both the time and the incentive to do so, but the structure of the program |
| 197 |
was vastly improved.</p> |
| 198 |
|
| 199 |
<p>The one major goal for version 5.0 which I did not complete was a new |
| 200 |
database implementation. The database system which existed at the time was |
| 201 |
heavily intertwined with the individual pseudoclients (NickServ, ChanServ, |
| 202 |
and so on), making it very difficult for third parties to add new features |
| 203 |
that required persistent data; this was exacerbated by the database file |
| 204 |
format, originally just a binary dump of the data structures stored in |
| 205 |
memory, which lacked any sort of flexibility at all and was highly |
| 206 |
susceptible to data corruption. Every time a new field was added, the |
| 207 |
database files' identifying version number was incremented, rendering the |
| 208 |
files incompatible with previous versions, and requiring highly complex |
| 209 |
routines in later releases to handle data from earlier versions. It had |
| 210 |
been my intention to implement a format-agnostic system for 5.0 along with |
| 211 |
a more expandable and robust file format, but this proved to be too much to |
| 212 |
handle at once, and I ended up simply moving all of the database handling |
| 213 |
to a module (<tt>database/version4</tt>) that used dozens of hacks to read |
| 214 |
and write the data in a format that remained compatible with the previous |
| 215 |
version (4.5).</p> |
| 216 |
|
| 217 |
<p>After a couple of years of on-and-off work, I finally found the time to |
| 218 |
go back and redesign the database system, and the result is the code |
| 219 |
present in this version. However, as I no longer use IRC, my interest in |
| 220 |
continuing development of Services has waned, and I have ended Services |
| 221 |
development as of version 5.1.</p> |
| 222 |
|
| 223 |
<p class="backlink"><a href="#top">Back to top</a></p> |
| 224 |
|
| 225 |
<!------------------------------------------------------------------------> |
| 226 |
<hr/> |
| 227 |
|
| 228 |
<p class="backlink"><a href="index.html">Table of Contents</a> | |
| 229 |
<a href="2.html">Next section: Core Services functionality</a></p> |
| 230 |
|
| 231 |
</body> |
| 232 |
</html> |
