Writing a lilyCore Client
History
There is no fundamental requirement in lily for clients. It is
certainly quite possible to telnet directly to the lily server and
begin using it [try
telnet rpi.lily.org 7777]. Unfortunately,
several problems begin to manifest themselves quickly: lack of input
control and no bell. As you type any output from the server will
be interleaved with the input you type. This can make it impossible
to understand what you are sending, and is significantly exacerbated
by a lack of
^R support in your terminal emulator. As well,
when lily was being written in 1994 MOO lacked support for transmitting
binary data, such as the bell character (
0x07 for VT100s).
These two issues, coupled with the user interface expectations of
the prior system, lead directly to the first lily client.
While the first client was being written, there was only a single
message being transmitted from the server to a client:
%g.
This was translated by the client into the bell character and
resulted in a beep. From this simple beginning a set of twenty
client options now exist.
Available Protocols
As a potential client author in 2001, the number of options before
you are dizzying. The interface between lily clients and the server
are quite rich and provide varying degrees of control for the author.
The most significant set of criteria to consider are: how much data
do you want to store in the client and how rich do you want the
interface to be. The protocol with the least associated data and
concomitant lack of possible richness is Terminal. The protocol
with the most data and the greatest degree of freedom for a rich
interface is SLCP. In detail the protocols are:
- Terminal
- The simplest of the protocols. It treats your connection as
though it were a terminal window. The server lays out all of the
output being sent to the client based on an eighty column window
size. Thus, a simple client can be written which does nothing but
open a TCP/IP socket connection to the aforementioned port. As you
add features to the client it will be necessary to support some of
the varied options which lily makes available to all clients. These
features enable you to figure out who sent the last message to you,
modify the number of columns the server formats to, and other similar
features. Documentation on the full range of options is in ClientOptions.
- SLCP
- The richest and most complex protocol currently available. At
connect time a copy of the lily objects visible to that user is
published to the client. From that point on all changes to the
database are also published to the client, regardless of the user's
desire to see them. To facilitate centralized settings management,
flags are provided with each event letting the client know to what
degree the user is interested in that event.
SLCP moves nearly
all the work of processing events and formatting output down to the
client. This frees a client developer to alter the standard lily
messages in any way they choose, or even to render lily in a
completely new way. It also has the added burden of exposing a great
many events which would normally never be transmitted to the user.
The client must parse, track, and interpret each of these and you
can be assured the work is non-nominal. If you are interested
in using SLCP the finest such client is by far
TigerLily. Its developers can offer
a great deal of help to people coming up to speed with SLCP.
- SLCP-name (nee SLCPjr)
- An untested protocol which enables a client to format messages
and events on its own, but does not provide a full database snapshot.
It should be possible to use this protocol today to at least format
messages. If you should choose to do so, please let the server
developers know about it. They will be glad to support this protocol,
since clily is expected to use it in the near future (right
Garance?).
- Jabber
- Jabber is an open source
instant messaging protocol. Support for it was added when the
protocol was first devised (March 1999). The protocol was very
unstable then, and rightly so. Unfortunately, our work stopped after
a few weeks and has not been picked up again. If you are a Jabber
client author already or want to use Jabber, please let the server
developers know!
Server Ports
The lily server originally listened on only port 7777, the default
MOO port at the time lily was written. This port offers all the
semantics associated with the Terminal client by default. An example
of this is the way the login prompt lacks a newline. This feature
is designed to make Terminal clients appear to have been prompted.
This behavior can be very frustrating for clients which are going
to use the carriage return as a line separator, and intend to parse
the output of the server. It is easy to detect such a client since
their networking code often has special references to the 'login:'
or 'password:' prompts.
As lily began to support more and more diverse protocols this issue
came to a head. Support for HTTP was desired and it was simply not
possible to multiplex those requests on the default lily port. As
a result we opened up port 8080 and began to process HTTP requests.
The next step was taken with the advent of Jabber. Soon ports were
being opened for HTTP, Jabber, and POP authentication.
- lily (port 7777)
- Implements the behavior commonly associated with a Terminal
client. It is possible to coerce the server into offering less
Terminal-like services through the use of client options.
- HTTP (port set by lily administrators)
- The port number this runs on If lily server administrators
configure $http_port at setup time, it will activate the built in
webserver, making available some limited information about the
running lily server and its code. This webserver provides a
simplistic interface to public discussions and users, allowing
someone with a lily account access to view this information.
More interestingly:
- Tisane
is now bundled with the lily core.
- A source code browser allows developers to easily view pretty
printed, hyperlinked source.
- New account requests can be submitted directly from the web
interface. Admins logged into the core see the requests, and can
automatically generate the account.
- Jabber (port ?)
- This interface is still under development. If you would like
to make use of it, or participate, please contact the server
developers.
- POP Authentication (port ?)
- POP authentication was started by purlah on a private core.
Work was done to incorporate it into the main development trunk,
but it was never completed.
- SSL (port 7778)
- Can one of the SSL developers please fill this in a bit?
Getting Started
Before you can begin developing a lily client there are a number of
documents to read:
Then make the decision about which protocol type you are going to
make use of: Terminal, SLCP, SLCP-name, or Jabber. The latter two
protocols may require a fair amount of effort on the part of the
server developers to work out kinks, so keep that in mind. Should
you decide to use SLCP read
SimpleLilyClientProtocol.
Once your client is underway there are additional documents which
may provide interesting such as:
Revision 5, 24 September 2001, ChristianRatliff
Revision 6, 23 August 2002, DD
to top