Author: dylan
Date: 2004-08-20 20:33:10 -0400 (Fri, 20 Aug 2004)
New Revision: 353
Added:
trunk/docs/manual/chap/
trunk/docs/manual/chap/events.texi
trunk/docs/manual/chap/events/
trunk/docs/manual/chap/events/basic.texi
trunk/docs/manual/chap/formats.texi
trunk/docs/manual/chap/introduction.texi
trunk/docs/manual/chap/protocol.texi
trunk/docs/manual/haver.texi
Log:
Presenting, the new texinfo manual. :)
Added: trunk/docs/manual/chap/events/basic.texi
===================================================================
--- trunk/docs/manual/chap/events/basic.texi 2004-08-21 00:31:44 UTC (rev
352)
+++ trunk/docs/manual/chap/events/basic.texi 2004-08-21 00:33:10 UTC (rev
353)
@@ -0,0 +1,182 @@
[EMAIL PROTECTED] Basic Events
[EMAIL PROTECTED] Basic Events
+
+This section describes how a client connects
+to the server and authenticates itself. It also
+describes how to disconnect.
+
[EMAIL PROTECTED] {Client Event} HAVER client
+This event must only be sent once during
+the lifetime of the connection.
+The server will not recognize the client until this event is
+sent.
+
+The parameter @var{client} is the name and version
+number of the client software, comparable to the ``User-Agent:''
+in HTTP. The prefered format is ``Program Name/#.#.#'', where ``#''
+is a number from 0 to 9. This format is not strictly enforced.
+
+The server will respond to this event
+by sending @command{HAVER} and @command{WANT IDENT}.
+
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] #################################
+
[EMAIL PROTECTED] {Server Event} HAVER server
+This event is sent after the client sends @command{HAVER}.
+The parameter @var{server} is name and version number of the server,
+for example ``Haver::Server::POE/0.07''.
+
+The client can just ignore this.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] #################################
+
[EMAIL PROTECTED] {Server Event} WANT cmd [EMAIL PROTECTED]
+
+When the server sends this event, the client
[EMAIL PROTECTED] either send the event @command{cmd}
+or [EMAIL PROTECTED] @var{cmd}''. To send any other event will
+cause the server to promptly disconnect the client.
+
+The parameters of @command{WANT} events
+can vary depending on the value of @var{cmd},
+as explain in the following table.
+
+
[EMAIL PROTECTED] @command
[EMAIL PROTECTED] IDENT
[EMAIL PROTECTED] will be empty.
[EMAIL PROTECTED] AUTH
[EMAIL PROTECTED] will be a list of acceptable authorization methods.
[EMAIL PROTECTED] AUTH:PASS
[EMAIL PROTECTED] will contain one item: the hashing method
+the client must use in its @command{AUTH:PASS} event.
+
+Typically it will be SHA-1
+or a function related to the SHA family of hash functions,
+such as SHA-256. However other hash functions are possible.
+
+The canonical hash function is``sha1''.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] deffn
+
+
[EMAIL PROTECTED] #################################
+
[EMAIL PROTECTED] {Client Event} IDENT id [mode]
+This event must only be sent when the server requests it with @command{WANT}.
+
[EMAIL PROTECTED] is the id the client wishes to go by.
+It must be in the format specified in @xref{Identifier Format}.
+
[EMAIL PROTECTED] is the mode (or namespace) the client will operate
+in. It is optional and defaults to ``user''. It must be
+in the format specified in @xref{Namespace Format}.
+
+If there are no errors,
+the server will send @command{ACCEPT} if @var{id} requires
+no authoriztion. If authorization is required, the server
+will issue @command{WANT AUTH}.
+
+Should an error occure, the server will issue @command{WANT IDENT} again.
+
[EMAIL PROTECTED]:}
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] unsupported.mode
[EMAIL PROTECTED] reserved.id
[EMAIL PROTECTED] used.id
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Client Event} AUTH method
+This event must only be sent when the server requests
+it with @command{WANT}.
+
+Request to use the authorization method @var{method},
+where @var{method} is one from the @command{WANT AUTH} mentioned
+above.
+
+Typically, @var{method} will be ``PASS'', but other authorization
+methods may be supported in the future.
+
+The server will issue @command{WANT WANT:foo}
+where ``foo'' is @var{method}.
+
[EMAIL PROTECTED]:}
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] unknown.authmethod
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Client Event} AUTH:PASS passhash
+This event must only be sent when the server
+requests it with @command{WANT}.
+
+passhash is the client's password + server's canonical hostname + client's id,
+hashed with hash function specified in the server's @command{WANT} request,
+and encoded with base64.
+
+In pseudo code, assuming the hash function is sha1:
[EMAIL PROTECTED]
+id = "fred"
+host = "example.com"
+password = "password"
+
+passhash_raw = sha1(password + host + id)
+passhash = base64_encode(passhash_raw)
+
+# the following is true:
+passhash == "n99EdTWT1x/urmLJm/AAlKkoQTQ"
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Client Event} BYE [why]
+Disconnect from the server.
+The parameter @var{why} is the reason for the disconnect,
+such as ``lost terminal'', ``reboot'', etc.
+This is not meant to be set by a human being, but instead
+the client software.
+
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Server Event} BYE type [EMAIL PROTECTED]
[EMAIL PROTECTED] {Server Event} QUIT uid type [EMAIL PROTECTED]
+
[EMAIL PROTECTED] is sent to the client right before the server disconnects it.
+
[EMAIL PROTECTED] is similar, however it is sent to all users that share a
channel
+with the exciting user. It is only sent when a user exits, other types
+of clients donot cause this. This is equivelent of @var{uid}
+parting every channel.
+
+Depending on the value of @var{tyoe}, @var{args} will be different things.
+The following table lists the different types of client disconnections.
+
[EMAIL PROTECTED] @i
[EMAIL PROTECTED] ACTIVE
+This is sent when the client has issued the server @command{BYE} event.
+
+The @var{args} may contain a single item, which
+is describes the reason for the disconnection. For example,
+``lost terminal'', ``reboot'', ``crash'', etc.
+
[EMAIL PROTECTED] DISCON
+The socket was closed. @var{args} might contain more information.
+
[EMAIL PROTECTED] TIMEOUT
+This means the client did not complete the login procedure
+fast enough. Typically, the login procedure must be completed in
+20 seconds from login, however this can be different depending on server.
+
[EMAIL PROTECTED] PING
+The client did not respond to a @command{PING}
+in time.
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] deffn
Added: trunk/docs/manual/chap/events.texi
===================================================================
--- trunk/docs/manual/chap/events.texi 2004-08-21 00:31:44 UTC (rev 352)
+++ trunk/docs/manual/chap/events.texi 2004-08-21 00:33:10 UTC (rev 353)
@@ -0,0 +1,197 @@
[EMAIL PROTECTED] Events
[EMAIL PROTECTED] Events
+
[EMAIL PROTECTED]
+* Basic Events::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] chap/events/basic.texi
+
[EMAIL PROTECTED]
+ \begin{cmddef}{MSG}{\param{where} \param{type} \params{msg}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Send a public message \params{msg}\ of type \param{type}
+ to the channel \param{where}.
+
+ \citem{\Res}
+ The server will send \scmd{MSG} to every user in
\param{where}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{unknown.cid}{where}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{PMSG}{\param{to} \param{type} \params{msg}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Send a private message \params{msg}\ of type
\param{type}
+ to the user \param{to}.
+
+ \citem{\Res}
+ The user \param{to} will recieve \scmd{PMSG},
+ the sender recieves nothing (Unless there is an error).
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.uid}{to}
+ \eitem{unknown.uid}{to}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{JOIN}{\param{where}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Attempt to join \param{where}.
+
+ \citem{\Res}
+ Upon successful entry, the server will send
+ \scmd{JOIN} to each user in the channel, including the
joiner.
+
+ \comment{There should be some support for passworded
channels,
+ and channels that maintain a wait-list.}
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{unknown.cid}{where}
+ \eitem{joined}{where}
+ \end{errors}
+ \comment{Further errors will be added for when people
are banned, etc.}
+ \end{cmddef}
+
+ \begin{cmddef}{PART}{\param{where}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Attempt to leave \param{where}.
+
+ \citem{\Res}
+ The server will send \scmd{PART}
+ to every user in the channel \emph{before} the user
+ actually leaves the channel. Thus the parter will get
his
+ own part message.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{unknown.cid}{where}
+ \eitem{timetravel}{where}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{BYE}{\opt{reason}}
+ \citem{\Desc}
+ Part every channel and disconnect from the server.
+
+ \citem{\Res}
+ The server will send \scmd{BYE}
+ and disconnect shortly after that.
+
+ The server will send \scmd{QUIT} to any other clients
+ that need to be notified of this client's departure.
+
+ \citem{\Err} None.
+ \end{cmddef}
+
+ \begin{cmddef}{INFO}{\param{ns} \param{id}}
+ \citem{\Desc}
+ Get information about the in the namespace \param{ns}
with the id \param{id}.
+ This will only return the most ``relevant'' fields of
the object,
+ not all of them.
+
+ \citem{\Res}
+ The server will send \scmd{INFO}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.id}{ns id}
+ \eitem{syntax.ns}{ns}
+ \eitem{unknown.id}{ns id}
+ \eitem{unknown.ns}{ns}
+
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{LINFO}{\param{where} \param{ns} \param{id}}
+ \citem{\Desc}
+ This is like INFO, except local to a channel
\param{where},
+ the ``L'' standing for local. The only other
+ difference is \param{id} may be ``*'' (the asterisk),
+ in which case it is as if the client sent \cmd{LINFO}
+ requests to every \param{ns} in \param{where}.
+
+ \comment{Perhaps \param{ns} should be allowed to be
``*''
+ as well?}
+ \citem{\Res}
+ The server will send \scmd{LINFO}.
+
+ If \param{id} is ``*'', the server will
+ send \scmd{END} \cmd{LINFO} after all other
\scmd{LINFO}'s
+ have been sent.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{unknown.cid}{where}
+ \eitem{syntax.ns}{ns}
+ \eitem{unknown.ns}{ns}
+ \eitem{syntax.id}{ns id}
+ \eitem{unknown.id}{ns id}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{LIST}{\opt{where} \param{ns}}
+ \citem{\Desc}
+ Request a list of all things in \param{where}
+ with the namespace \param{ns}.
+
+ \param{where} defaults to ``*'', in which case
+ the server will list every user on the server
+ (even those joined to no channel). This may
+ be restricted to privledged users or services.
+
+ \comment{Perhaps \param{ns} can also be ``*''?}
+
+ \citem{\Res}
+ The server will send \scmd{LIST}.
+ If \param{where} is omitted, ``*'' will
+ be sent. So don't worry, \scmd{LIST} is not ambigous.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{syntax.ns}{ns}
+ \eitem{unknown.cid}{where}
+ \eitem{unknown.ns}{ns}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{POKE}{\opt{data}}
+ \citem{\Desc}
+ This command is used to check if the server is still
responding.
+
+ \citem{\Res}
+ The server will reply with \scmd{OUCH}.
+ If present, \param{data} will be part of this
+ reply.
+
+ If you poke more than once per reasonable
+ amount of time, the server may issue a warning or even
+ disconnect you. Generally, reasonable amount
+ of time is five seconds. In general you should at least
not
+ poke more than once per minute, however.
+
+ It is preferable if clients only poke when they have not
+ recieved a message from the server in a minute or two.
+
+ \citem{\Err} None.
+ \end{cmddef}
+
+\end{commands}
[EMAIL PROTECTED] ignore
Added: trunk/docs/manual/chap/formats.texi
===================================================================
--- trunk/docs/manual/chap/formats.texi 2004-08-21 00:31:44 UTC (rev 352)
+++ trunk/docs/manual/chap/formats.texi 2004-08-21 00:33:10 UTC (rev 353)
@@ -0,0 +1,56 @@
[EMAIL PROTECTED] Formats
[EMAIL PROTECTED] Formats
+
+This section describes formats used in the haver protocol,
+such as how dates, times, and time zones are formatted.
+It also describes the format for identifiers (the ids of channels, users, etc).
+
[EMAIL PROTECTED]
+* Date and Time Format::
+* Identifier Format::
+* Namespace Format::
+* Command Format::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] Date and Time Format
[EMAIL PROTECTED] Dates and Times
+
+Dates are expressed in YYYY-MM-DD format, e.g. 1985-09-14.
+
+The format for times is HH:MM:SS.nnn.
+HH is from 0 to 23, MM is from 0 to 59,
+SS is from 0 to 59 [What about leap seconds?].
+The ``.nn'' part is fractional parts of a second,
+it is optional and may be ommited.
+
+Time zones are in the form of [+-]HHMM.
+For example, EDT is -0400.
+
+A full datetime is thus ``YYYY-MM-DD HH:MM:SS [-+]HHMM'',
+for example: ``2004-08-15 19:01:05 -0400''.
+
[EMAIL PROTECTED] Identifier Format
[EMAIL PROTECTED] Identifiers
+
+The format for identifiers is best expressed
+by the regular expression @code{/&?[A-Za-z][A-Za-z0-9_.'@@-]+/}.
+
+In English, identifiers may be prefixed with an ampersand (&),
+must begin with a letter, and must be followed by one or more of: letters;
+numbers; periods; hyphens; underscores; single quotes; or the at symbol (@@).
+All other characters constitute an illegal ID.
+
+Further, the length of the ID must be greater than two
+and less than or equal to 20 (@code{length(id) > 2 && length(id) <= 20}).
+
[EMAIL PROTECTED] Namespace Format
[EMAIL PROTECTED] Namespaces
+
+Namespaces must contain only lower case letters,
+and follow the same length rules as identifiers.
+
[EMAIL PROTECTED] Command Format
[EMAIL PROTECTED] Commands
+
+Commands must only contain upper-case letters, hyphers, underscores,
+and colons. (@code{/[A-Z:_-]/}).
Added: trunk/docs/manual/chap/introduction.texi
===================================================================
--- trunk/docs/manual/chap/introduction.texi 2004-08-21 00:31:44 UTC (rev
352)
+++ trunk/docs/manual/chap/introduction.texi 2004-08-21 00:33:10 UTC (rev
353)
@@ -0,0 +1,79 @@
[EMAIL PROTECTED] Introduction
[EMAIL PROTECTED] Introduction
+
+Haver is a simple line based, tab delimited protocol. It is
+not meant as a replacement to IRC, Jabber,
+or SILC. Nevertheless, it should be rather
+less difficult to write clients for haver than the above mentioned protocols.
+
+This protocol is being designed because current protocols are either
+too limited (e.g. IRC) or too complicated (e.g. jabber, SILC) to extend
+in playful and useless ways. Something simple and powerful needs to exist,
+and this could very well be haver.
+
+
[EMAIL PROTECTED]
+* Servers::
+* Clients::
+* Channels::
[EMAIL PROTECTED] menu
+
+
[EMAIL PROTECTED] Servers
[EMAIL PROTECTED] Servers
+
+A Haver server is almost, but not quite, entirely unlike chocolate.
+While chocolate's main purpose is to delight with its delicious
+taste, haver servers do not have any taste.
+
+Instead, haver servers route messages (commands) to their clients,
+and maintain data about their clients and channels.
+Monolithic servers will do more than just this, and will handle many commands
+internally. Micro-servers will offload this burden unto special service
clients.
+
[EMAIL PROTECTED] Clients
[EMAIL PROTECTED] Clients
+
+A Haver client sends and receives commands from the server, basically.
+
+Each client has an identifier (id) and a namespace.
+The functionality available to a client, what it is allowed to do,
+is strongly influenced by its namespace.
+
[EMAIL PROTECTED]
+* Users:: Clients that don't do anything useful. Lazy bums.
+* Services:: Clients that perform a useful task.
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] Users
[EMAIL PROTECTED] Users
+
+The vast majority of clients will be users, which are representations
+of either real people, bots, or even Helephants.
+
+Users may or may not require authorization, depending
+on if the user is registered or not.
+
[EMAIL PROTECTED] cross-ref: Authoriztion.
+
[EMAIL PROTECTED] Services
[EMAIL PROTECTED] Services
+
+Services may add new protocol commands to the server,
+and will typically require some form of authorization.
+
+Services may produce virtual user-like entities to interact with
+the real users. These are called agents, and are rather like privileged bots.
+
+In addition, services may be allowed to extend ``virtual'' channels into
+the server to allow different forms of server linking.
+
[EMAIL PROTECTED] cross-ref: Authoriztion.
+
[EMAIL PROTECTED] Channels
[EMAIL PROTECTED] Channels
+
+Channels are pretty much like they are on IRC, except their identifiers
(channel ids, cids)
+follow the same rules as identifiers for the other types of objects (users,
services, etc).
+
+They may either automagically created upon use, or channel creation can be
restricted to privileged users.
Added: trunk/docs/manual/chap/protocol.texi
===================================================================
--- trunk/docs/manual/chap/protocol.texi 2004-08-21 00:31:44 UTC (rev
352)
+++ trunk/docs/manual/chap/protocol.texi 2004-08-21 00:33:10 UTC (rev
353)
@@ -0,0 +1,82 @@
[EMAIL PROTECTED] Protocol
[EMAIL PROTECTED] Protocol
+
+The haver protocol is in the UTF-8 encoding, as defined in
+RFC 2279. However, only the first 127 character codes (the ASCII range)
+are used for commands, identifiers, and delimiters.
+
+The protocol is delimited into lines separated by CR LF (0x0D 0x0A).
+Each line is further delimited by the Tab character (0x09)
+into a series of tokens.
+The first of the tokens is called the command,
+the remaining tokens (if any) are refered to as the arguments.
+
+If a literal tab, carriage return, or line feed needs to be sent,
+it must be written in escaped form with the Esc character (0x1b).
+In addition, Esc itself and the ASCII NUL character (0x00) must be escaped.
+
+A literal carriage return is represented by ``<Esc>r''
+a literal line feed by ``<Esc>n'', a tab by ``<Esc>t'',
+and an Esc by ``<Esc>e''.
+Naturally, replace ``<Esc>'' with the Esc character (0x1b).
+
+Here is an example in perl:
+
[EMAIL PROTECTED]
+#!/usr/bin/perl
+# FIXME: make this example easier to understand.
+
+our $CR = "\x0D";
+our $LF = "\x0A";
+our %Escape = (
+ $CR => 'r',
+ $LF => 'n',
+ "\e" => 'e',
+ "\t" => 't',
+);
+our %Unescape = reverse %Escape;
+my $Chars = join('', keys %Escape);
+my $Codes = join('', keys %Unescape);
+
+
+sub escape @{
+ my ($s) = @@_;
+ $s =~ s/([$Chars])/[EMAIL PROTECTED];
+ return $s;
[EMAIL PROTECTED]
+
+sub unescape @{
+ my ($s) = @@_;
+ $s =~ s/\e([$Codes])/[EMAIL PROTECTED];
+ return $s;
[EMAIL PROTECTED]
+
+# Take a line, remove the CR-LF,
+# split it into a list,
+# unescape each item in the list.
+sub line2event @{
+ my ($line) = @@_;
+ $line =~ s/$CRLF$//g;
+ my @@e = split("\t", $line);
+ foreach (@@e) @{
+ $_ = unescape($_);
+ @}
+
+ return wantarray ? @@e : \@@e;
[EMAIL PROTECTED]
+
+# Take a list, escape each item,
+# join together with "\t", and append CR-LF.
+sub event2line @{
+ my @@event;
+ if (@@_ > 1) @{
+ @@event = @@_;
+ @} else @{
+ @@event = @@@[EMAIL PROTECTED];
+ @}
+ foreach (@@event) @{
+ $_ = escape($_);
+ @}
+ join("\t", @@event) . $CRLF;
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
Added: trunk/docs/manual/haver.texi
===================================================================
--- trunk/docs/manual/haver.texi 2004-08-21 00:31:44 UTC (rev 352)
+++ trunk/docs/manual/haver.texi 2004-08-21 00:33:10 UTC (rev 353)
@@ -0,0 +1,66 @@
+\input texinfo @c -*-texinfo-*-
[EMAIL PROTECTED] %**start of header
[EMAIL PROTECTED] haver.info
[EMAIL PROTECTED] The Divine Secrets of Haver (@value{version})
[EMAIL PROTECTED] %**end of header
+
[EMAIL PROTECTED] version 4
+
[EMAIL PROTECTED]
+This document describes the Haver protocol, version @value{version}.
+
+Copyright @copyright{} 2004 Dylan William Hardison.
+
[EMAIL PROTECTED]
+Permission is granted to copy, distribute and/or modify this document
+in any way, provided the title be changed and this notice preserved.
[EMAIL PROTECTED] quotation
[EMAIL PROTECTED] copying
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] The Divine Secrets of Haver
[EMAIL PROTECTED] A Journey into Madness
[EMAIL PROTECTED] Version @value{version}
[EMAIL PROTECTED] Dylan William Hardison
+
[EMAIL PROTECTED] The following two commands
[EMAIL PROTECTED] start the copyright page.
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] 0pt plus 1filll
[EMAIL PROTECTED]
+
[EMAIL PROTECTED] titlepage
+
[EMAIL PROTECTED] So the toc is printed at the start.
[EMAIL PROTECTED]
+
[EMAIL PROTECTED]
+
[EMAIL PROTECTED] Top
[EMAIL PROTECTED] Divine Secrets of Haver
+
+
[EMAIL PROTECTED] Abstract
+
+Haver is a network protocol for real time textual confrencing,
+and is being developed by an international coalition of four people.
+It does not utilize advanced technologies such as XML.
+
+
[EMAIL PROTECTED] ifnottex
+
[EMAIL PROTECTED]
+* Introduction:: Introducing Haver.
+* Protocol:: How to parse the protocol.
+* Formats:: Format for dates, times, ids, etc.
+* Events:: How servers and clients communicate.
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] chap/introduction.texi
[EMAIL PROTECTED] chap/protocol.texi
[EMAIL PROTECTED] chap/formats.texi
[EMAIL PROTECTED] chap/events.texi
+
+
[EMAIL PROTECTED]
