The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Haver-Spec-0.08
/ Haver::Spec

NAME

Haver::Spec - The core haver protocol.

DESCRIPTION

This document describes the core functionality of the Haver protocol. It is not as comprehensive as the Manual, but it is slightly better than keeping these things in plain text files.

BEGIN YOUR FEAR

Here's a general overview with examples. Lines beginning with C: are from the client, and lines beginning with S: are from the server. Items enclosed in square brackets are optional.

HAVER/IDENT/HELLO

$supported is a comma-seperated last of supported extensions (See "EXTENSIONS")

C: HAVER  Foobar/1.0 [$supported]
S: HAVER  example.com  FoobarServer/1.0
C: IDENT  $name
S: HELLO  $name

JOIN/PART/LIST

$namespace is one of "user", "service", or "channel".

C: JOIN  $channel 
S: JOIN  $channel  $user

C: PART  $channel
S: PART  $channel  $user

C: LIST  $channel  $namespace
S: LIST  $channel  $namespace  Thing1  Thing2  Thing3

IN/TO/FROM

Public messages (a message sent to everyone in a channel)

C: IN  $channel  $type  @args
S: IN  $channel  $user  $type  @args

Private messages (a message sent ot a select group of users)

C: TO    $users  $type  @args
S: FROM  $users  $type  @args

Clients must use any word (/^\w+$/) for $type, but it is typically "do" or "say".

INFO

C: INFO  $namespace  $name
S: INFO  $namespace  $name  $key1  $value1  $key2  $value2 ...

Sending this message results in the server sending back a message (S:INFO) with a list of key/value pairs. The keys vary depending on what is queried. Different server implementations may add extra keys too. Good user agents will allow the user to see any and all keys assigned to entity, even ones that did not exist when the user agent was programmed.

Keys for Users and Services

address

A (probably masked) IP address. E.g. 1.2.3.*

version

The name and version number of the user-agent and service program, as sent by C:HAVER.

idle

The number of seconds the client has been idle. For users, idle is defined as the length of time between sending TO or IN messages.

email

The email address of the user or service. All registered services and users will have email addresses associated with them.

Keys for Channels

creator

The name of the user that created the channel.

created

The date and time the channel was created.

Keys for the Lobby

booted

The date and time the server was booted.

hostname

The hostname of the server.

version

The version name of the server, the same as from S:HAVER.

POKE/OUCH

POKE is used to see if the server is alive. The server will respond with OUCH.

C: POKE  $string
S: OUCH  $string

PING/PONG

If the server sends PING, the client must respond with PONG, like so:

S: PING  $string
C: PONG  $string

BYE/QUIT

To disconnect, a client should send BYE:

C: BYE  $detail

The server will reply with:

S: BYE  $type  $detail

All users sharing a channel with the client will see:

S: QUIT  $sender  $type  $detail

The $type of quit is one of several things:

  • closed

  • error ($detail = error code?)

  • bye ($detail = from BYE)

  • ping

  • ghost

  • kill ($detail = killer)

YOU FAIL

The server may respond to any given message with FAIL, which has the form of:

S: FAIL  $cmd  $error [@args]

Where $cmd is the name of the message that failed, $error is the error name, and @args are bits of information related to the error.

invalid.name

You used a name that contains invalid characters.

reserved.name

You used a name that contains characters only special people are allowed to use.

exists.user

The user name you requested is in use.

unknown.user

That user name does not exist on the server.

unknown.channel

That channel name does not exist on the server.

unknown.namespace

The namespace (used in LIST, for example) is not one that the server is aware of.

invalid.type

The $type argument of an IN or TO message contained non-word characters.

already.joined

Tried to join a channel that you're already in.

already.parted

Tried to part a channel you're not in.

I MEAN, HI

I could describe the messages here in greater detail, but I think that belongs in the manual. There might be some other useful information to put in this section, too. But it is five thirteen in the morning, so I can't think of it.

EXTENSIONS

Currently defined extensions: Haver::Spec::Ghost, Haver::Spec::Auth, Haver::Spec::Reg.

AUTHOR

Dylan William Hardison, <dylan@haverdev.org>

SEE ALSO

http://www.haverdev.org/.

COPYRIGHT and LICENSE

Copyright (C) 2005 by Dylan William Hardison. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this module; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA