Author: dylan
Date: 2005-03-22 00:48:06 -0500 (Tue, 22 Mar 2005)
New Revision: 651
Modified:
trunk/
trunk/docs/spec/Haver/Spec.pod
Log:
[EMAIL PROTECTED]: dylan | 2005-03-22 00:40:27 -0500
adding most recent work.
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:855
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
+ 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:856
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
Modified: trunk/docs/spec/Haver/Spec.pod
===================================================================
--- trunk/docs/spec/Haver/Spec.pod 2005-03-22 05:48:04 UTC (rev 650)
+++ trunk/docs/spec/Haver/Spec.pod 2005-03-22 05:48:06 UTC (rev 651)
@@ -8,7 +8,6 @@
and is being developed by an international coalition of four people.
It does B<not> utilize advanced technologies such as XML.
-
=head1 INTRODUCTION
Haver is a simple line based, tab delimited protocol. It is
@@ -18,67 +17,71 @@
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.
+in playful and perhaps silly ways. It is an itch that we are scratching.
-It is also a programming exercise for the authors, who have been having a lot
of fun
-writing haver clients in various languages.
+It is also a fun programming exercise.
=head2 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.
+B<Haver> is (mostly) a client-server protocol.
+Thus a server is needed for two haver clients to communicate.
+Servers store metadata about each client, and also maintain the list of
channels.
-Instead, haver servers route messages to their clients,
-and maintain data about their clients and channels.
-Monolithic servers will do more than just this, and will handle many messages
-internally. Micro-servers will offload this burden unto special service
clients.
-
=head2 Clients
-A client is a simple TCP/IP program that conforms to the Haver protocol.
-There are at least two types of clients: Users and Services.
+A haver client is any TCP/IP program that conforms to the haver protocol.
+
+There are two kinds of clients: users and services.
+
+=head3 Users
+
The vast majority of clients will be users, which are representations
-of either real people, bots, or GreenReaper.
+of either real people, chatbots, or GreenReaper.
-Services may add new protocol messages to the server,
-produce virtual user-like entities called Agents to interact with
-the real users, and extend virtual channels into the server allows different
-forms of server linking.
+=head3 Services
-=head2 Channels
+Services may add new protocol commands to the server,
+produce virtual user entities (called agents) to interact with the real users,
+and may be allowed to extend ``virtual'' channels into the server to
+allow different forms of server linking.
-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).
+Services can not join channels.
-They may either automagically created upon use, or channel creation can be
-restricted to privileged users.
+=head2 Channels
-=head2 Lobby
+Channels are collections of users, as in IRC. Unlike IRC, channels are never
automagically
+created. Depending on the whim of the server admins, channels may be created
by anyone
+or that action may be restricted to users with the proper privledges.
-There is a global entity which is very similiar to a channel, but not quite.
-It is called the lobby, and it contains all users, channels, and services that
exist on the server.
-It is in essence a virtual channel.
+=head3 Lobby
-=head2 Namespace
+The lobby is like a special channel. It contains all the users, services, and
channels
+of the server.
-Users, Services, and Channels all exist in seperate namespaces.
-Thus you can have a channel named bob, a user named bob, and a service named
bob.
+=head2 Entities
-The lobby exists outside of this namespace scheme.
+Channels, users, and services share many common attributes, so it is useful to
refer to them
+both as entities.
=head1 PROTOCOL
+The haver protocol is relatively easy to parse:
+Simply split lines on the tab character. There is an optional escaping
+mechanism, and support for Unicode. These issues are explained next.
+
+=head2 Character codes
+
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 message names, identifiers, and delimiters.
+=head2 Parsing
+
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 or message name.
+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.
+The command and arguments together make up the message.
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).
@@ -89,49 +92,82 @@
and an Esc by ``<Esc>e''.
Naturally, replace ``<Esc>'' with the Esc character (0x1b).
-See L<Haver::Spec::Escapes> for more information and a perl example.
+=head2 ASCII NULs
+Currently there is no defined behavior for ASCII NUL characters in the
protocol.
+Comments and suggestions on how to deal with them is welcome.
+
=head1 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),
-and message names.
-
=head2 Dates and Times
-Dates are expressed in YYYY-MM-DD format, e.g. 1985-09-14.
+Dates and times are always assumed to be in UTC.
-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.
+Whenever a date appears in the haver protocol,
+it is given in the form C<%Y-%m-%d %H:%M:%S>,
+where:
-Time zones are in the form of [+-]HHMM.
-For example, EDT is -0400.
+=over 4
-A full datetime is thus ``YYYY-MM-DD HH:MM:SS [-+]HHMM'',
-for example: ``2004-08-15 19:01:05 -0400''.
+=item %Y
+This is year, such 2004 or 1985.
+
+=item %m
+
+The month, from 01 to 12.
+
+=item %d
+
+The day, from 01 to 31.
+
+=item %H
+
+The hour, from 00 to 23.
+
+=item %M
+
+The minute, from 00 to 59.
+
+=item %S
+
+The second, from 00 to 60 (for leap seconds).
+
+=back
+
+An example: 2005-03-22 04:10:28.
+
=head2 Identifiers
-The format for identifiers is best expressed
-by the regular expression C</&?[A-Za-z][A-Za-z0-9_.'@-]+/>
+A valid identifier must match the perl-style regular expression:
+S</&?[a-z][a-z0-9_.'@-]+/i>.
+Identifiers are case insensitive.
-In English, identifiers may be prefixed with an ampersand (C<&>),
-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 (C<@>).
-All other characters constitute an illegal ID.
+Identifiers beginning with C<&> or containing C<@> are reserved by the server.
-Further, the length of the ID must be greater than two
-and less than or equal to 20 (C<length(id) E<gt> 2 && length(id) <= 20>).
-=head2 Message names
+=head2 Commands
-Message names must only contain upper-case letters, hyphers, underscores,
-and colons. (C</[A-Z:_-]/>).
+The command portion of a message must match the regex:
+S</[A-Z][A-Z:_-]+/>.
+
+=begin comment
+
=head1 CLIENT MESSAGES
+This event @strong{must} be the first message sent by the client. If a
different
+message is received, servers @strong{must} immediately terminate the
connection.
+
+The parameter @var{client} is the name and version
+number of the client software, comparable to the ``User-Agent:''
+in HTTP. The format should be ``Program Name/#.#.#'', where ``#''
+is a number from 0 to 9. This format shall not be strictly enforced,
+but clients are encouraged to not deviate from it.
+
+The server will respond to this event
+by sending @command{HAVER} and @command{WANT IDENT}.
+
+=end comment
+
