<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>The Evolution of Finger: building a simple finger service</title>
</head>
<body>
<h1>The Evolution of Finger: building a simple finger service</h1>
<h2>Introduction</h2>
<p> This is the first part of the Twisted tutorial <a
href="index.xhtml">Twisted from Scratch, or The Evolution of Finger</a>.</p>
<p>By the end of this section of the tutorial, our finger server will answer
TCP finger requests on port 1079, and will read data from the web.</p>
<h2>Refuse Connections</h2>
<a href="listings/finger/finger01.py" class="py-listing">finger01.py</a>
<p>This example only runs the reactor. Nothing at all will happen until we
interrupt the program. It will consume almost no CPU resources. Not very
useful, perhaps -- but this is the skeleton inside which the Twisted program
will grow.
</p>
<h3>The Reactor</h3>
<p>
You don't call Twisted, Twisted calls you. The <code class="API" base="twisted.internet">reactor</code> is Twisted's
main event loop. There is exactly one reactor in any running Twisted
application. Once started it loops over and over again, responding to network
events, and making scheduled calls to code.
</p>
<h2>Do Nothing</h2>
<a href="listings/finger/finger02.py" class="py-listing">finger02.py</a>
<p>Here, we start listening on port 1079. The 1079 is a reminder that
eventually, we want to run on port 79, the standard port for finger servers.
We define a protocol which does not respond to any events. Thus, connections to
1079 will be accepted, but the input ignored.</p>
<h2>Drop Connections</h2>
<a href="listings/finger/finger03.py" class="py-listing">finger03.py</a>
<p>Here we add to the protocol the ability to respond to the event of beginning
a connection -- by terminating it. Perhaps not an interesting behavior, but
it is already close to behaving according to the letter of the protocol. After
all, there is no requirement to send any data to the remote connection in the
standard. The only problem, as far as the standard is concerned, is that we
terminate the connection too soon. A client which is slow enough will see his
send() of the username result in an error.</p>
<h2>Read Username, Drop Connections</h2>
<a href="listings/finger/finger04.py" class="py-listing">finger04.py</a>
<p>Here we make <code>FingerProtocol</code> inherit from <code class="API"
base="twisted.protocols.basic">LineReceiver</code>, so that we get data-based
events on a line-by-line basis. We respond to the event of receiving the line
with shutting down the connection.
</p>
<p>Congratulations, this is the first standard-compliant version of the code.
However, usually people actually expect some data about users to be
transmitted.</p>
<h2>Read Username, Output Error, Drop Connections</h2>
<a href="listings/finger/finger05.py" class="py-listing">finger05.py</a>
<p>Finally, a useful version. Granted, the usefulness is somewhat
limited by the fact that this version only prints out a <q>No such user</q>
message. It could be used for devastating effect in honey-pots,
of course.</p>
<h2>Output From Empty Factory</h2>
<a href="listings/finger/finger06.py" class="py-listing">finger06.py</a>
<p>The same behavior, but finally we see what usefulness the
factory has: as something that does not get constructed for
every connection, it can be in charge of the user database.
In particular, we won't have to change the protocol if
the user database back-end changes.</p>
<h2>Output from Non-empty Factory</h2>
<a href="listings/finger/finger07.py" class="py-listing">finger07.py</a>
<p>Finally, a really useful finger database. While it does not
supply information about logged in users, it could be used to
distribute things like office locations and internal office
numbers. As hinted above, the factory is in charge of keeping
the user database: note that the protocol instance has not
changed. This is starting to look good: we really won't have
to keep tweaking our protocol.</p>
<h2>Use Deferreds</h2>
<a href="listings/finger/finger08.py" class="py-listing">finger08.py</a>
<p>But, here we tweak it just for the hell of it. Yes, while the
previous version worked, it did assume the result of getUser is
always immediately available. But what if instead of an in memory
database, we would have to fetch result from a remote Oracle?
Or from the web? Or, or...</p>
<h2>Run 'finger' Locally</h2>
<a href="listings/finger/finger09.py" class="py-listing">finger09.py</a>
<p>...from running a local command? Yes, this version runs
finger locally with whatever arguments it is given, and returns the
standard output. This is probably insecure, so you probably don't
want a real server to do this without a lot more validation of the
user input. This will do exactly what the standard version
of the finger server does.</p>
<h2>Read Status from the Web</h2>
<p>The web. That invention which has infiltrated homes around the
world finally gets through to our invention. Here we use the built-in
Twisted web client, which also returns a deferred. Finally, we manage
to have examples of three different database back-ends, which do
not change the protocol class. In fact, we will not have to change
the protocol again until the end of this tutorial: we have achieved,
here, one truly usable class.</p>
<a href="listings/finger/finger10.py" class="py-listing">finger10.py</a>
<h2>Use Application</h2>
<p>Up until now, we faked. We kept using port 1079, because really,
who wants to run a finger server with root privileges? Well, the
common solution is <q>privilege shedding</q>: after binding to the
network, become a different, less privileged user. We could have done
it ourselves, but Twisted has a built-in way to do it. We will create
a snippet as above, but now we will define an application object. That
object will have uid and gid attributes. When running it (later we
will see how) it will bind to ports, shed privileges and then run.</p>
<p>After saving the next example (finger11.py) as <q>finger.tac</q>,
read on to find out how to run this code using the twistd utility.</p>
<a href="listings/finger/finger11.py" class="py-listing">finger11.py</a>
<h2>twistd</h2>
<p>This is how to run <q>Twisted Applications</q> -- files which define an
'application'. twistd (TWISTed Daemonizer) does everything a daemon
can be expected to -- shuts down stdin/stdout/stderr, disconnects
from the terminal and can even change runtime directory, or even
the root filesystems. In short, it does everything so the Twisted
application developer can concentrate on writing his networking code.
</p>
<pre class="shell">
root% twistd -ny finger.tac # just like before
root% twistd -y finger.tac # daemonize, keep pid in twistd.pid
root% twistd -y finger.tac --pidfile=finger.pid
root% twistd -y finger.tac --rundir=/
root% twistd -y finger.tac --chroot=/var
root% twistd -y finger.tac -l /var/log/finger.log
root% twistd -y finger.tac --syslog # just log to syslog
root% twistd -y finger.tac --syslog --prefix=twistedfinger # use given prefix
</pre>
</body>
</html>