New data model proposal for next 1.0 release

[phpfreechat]

This is the new data model proposal I will use to implement the 1.0 features : moderation, channels and private messages
This is a draft so don't hesitate to add comments.

----------
The default 'File' container structure :

Code: Select all

serverid/metadata                                        (server metadata : should looks like phpfreechatconfig attributes)
serverid/messages                                        (server messages : connect/quit notices, motd, ...)
serverid/messages.index                                  (server messages index repository, only contains a number which is incrementaly increased +1)
serverid/channels/encoded_chan1/metadata                 (channel metadata : channels flags, channel op-mod/erator ... )
serverid/channels/encoded_chan1/messages.index           (same as server messages index repository, but just for this channel)
serverid/channels/encoded_chan1/messages                 (channel messages : messages, channel notices ...)
serverid/channels/encoded_chan1/nicknames/encoded_nick1  (a directory which contains one empty file for one nickname, nicknames metadata can be found into the serverid/nicknames/ directory)
serverid/channels/encoded_chan1/nicknames/encoded_nick2
serverid/channels/encoded_chan2/metadata
serverid/channels/encoded_chan2/messages.index
serverid/channels/encoded_chan2/messages
serverid/channels/encoded_chan2/nicknames/encoded_nick3
serverid/nicknames/encoded_nick1                         (a directory which contains one file for one nickname, the file contains nick metadata: nickid, timeout ...)
serverid/nicknames/encoded_nick2
serverid/nicknames/encoded_nick3

----------
The container API :

Code: Select all

/* I will add this to the abstract container class */
setServer($serverid) { $this->serverid = $serverid; }

/**
 * Store/update the alive user status somewhere
 * The default File container will just touch (update the date) the nickname file.
 * @param $chan where to update the nick, if null then update the server nick
 * @param $nick nickname to update (raw nickname)
 */
updateNick($chan, $nick)

/**
 * Returns the nickid, this is a unique id used to identify a user (taken from session)
 * By default this nickid is just stored into the user' metadata, same as :->getNickMeta("nickid")
 * @param $nick
 * @return string the nick id
 */
getNickId($nick)

/**
 * Change the user' nickname
 * Notice: this function must update all channels the users joined (use stored channel list into metadata)
 * @param $newnick
 * @param $oldnick
 */
changeNick($newnick, $oldnick)

/**
 * Create (connect/join) the nickname into the server or the channel locations
 * Notice: this function must update all channels the users joined (use stored channel list into metadata)
 * @param $chan if NULL then create the user on the server (connect), otherwise create the user on the given channel (join)
 * @param $nick the nickname to create
 */
createNick($chan, $nick)

/**
 * Remove (disconnect/quit) the nickname from the server or from a channel
 * Notice: this function must update all channels if the user disconnect completly (use stored channel list into metadata)
 * @param $chan if NULL then remove the user on the server (disconnect) and on all the joined channels, otherwise just remove the user from the given channel (quit)
 * @param $nick the nickname to remove
 */
removeNick($chan, $nick)

/**
 * Remove (disconnect/quit) the timeouted nickname from the server or from a channel
 * Notice: this function must remove all nicknames which are not uptodate from the given channel or from the server
 * @param $chan if NULL then check obsolete nick on the server, otherwise just check obsolete nick on the given channel
 * @return array() contains all disconnected nicknames
 */
removeObsoleteNick($chan)

/**
 * Returns the nickname list on the given channel or on the whole server
 * @param $chan if NULL then returns all connected user, otherwise just returns the channel nicknames
 * @return array() contains a nickname list
 */
getOnlineNick($chan)

/**
 * Write a message to the given channel or to the server
 * Notice: a message is very generic, it can be a misc command (notice, me, ...)
 * @param $chan if NULL then write the message on the server, otherwise just write the message on the channel message pool
 * @param $nick is the sender nickname
 * @param $msg is the raw message to write
 */
writeMsg($chan, $nick, $msg)

/**
 * Read the last posted messages from a channel or from the server
 * @param $chan if NULL then read from the server, otherwise read from the given channel
 * @param $from_id read all message with a greater id
 * @return array() contains the messages list
 */
readNewMsg($chan, $from_id)

/**
 * Returns the last message id
 * Notice: the default file container just returns the messages.index file content
 * @param $chan if NULL then read if from the server, otherwise read if from the given channel
 * @return int is the last posted message id
 */
getLastMsgId($chan)

/**
 * Read and write meta data for a given nickname
 * Notice: the default file container store these metadata into the server nickname file
 * Tip: if metadata are stored into one big file, then read the whole file at first request
 *      and keep it in memory during the request, it will optimize file access
 * @param $key is the index which identify a metadata
 * @param $value is the value to associate to the key
 */
getNickMeta($key)
setNickMeta($key, $value)

/**
 * Read and write meta data for the server (global)
 * Notice: the default file container store these metadata into the server metadata file
 * Tip: if metadata are stored into one big file, then read the whole file at first request
 *      and keep it in memory during the request, it will optimize file access
 * @param $key is the index which identify a metadata
 * @param $value is the value to associate to the key
 */
getServerMeta($key)
setServerMeta($key, $value)

/**
 * Read and write meta data for a given channel
 * Notice: the default file container store these metadata into the channel metadata file
 * Tip: if metadata are stored into one big file, then read the whole file at first request
 *      and keep it in memory during the request, it will optimize file access
 * @param $key is the index which identify a metadata
 * @param $value is the value to associate to the key
 */
getChanMeta($chan, $key)
setChanMeta($chan, $key, $value)

----------
A session example with toto and titi users which illustrate how nicknames files are created/deleted/updated :

Code: Select all

(toto) /connect
(toto) /nick toto
(toto)          touch serverid/nicknames/toto
(toto) /join channel1
(toto)          touch serverid/channel1/nicknames/toto
(titi) /update channel1
(toto)          touch serverid/nicknames/toto
(titi)          touch serverid/channel1/nicknames/toto
(toto) /join channel2 (toto)
(toto)          touch serverid/channel2/nicknames/toto
(titi) /update channel2
(toto)          touch serverid/nicknames/toto
(titi)          touch serverid/channel1/nicknames/toto
(toto) /quit channel1 (toto)
(toto)          rm serverid/channel1/nicknames/toto
(titi) /update channel2
(toto)          touch serverid/nicknames/toto
(titi)          touch serverid/channel1/nicknames/toto
(toto) *close the chat window*

(titi) /connect
(titi) /nick titi
(titi)          touch serverid/nicknames/titi
(titi) /join channel1
(titi)          touch serverid/channel1/nicknames/titi
(titi) /update channel1
(toto)          rm serverid/nicknames/toto
(toto)          touch serverid/nicknames/titi
(titi)          touch serverid/channel1/nicknames/titi
(titi) /join channel2
(titi)          touch serverid/channel2/nicknames/titi
(titi) /update channel2
(toto)          touch serverid/nicknames/titi
(titi)          rm serverid/channel2/nicknames/toto
(titi)          touch serverid/channel2/nicknames/titi
(titi) /quit channel1
(titi)          rm serverid/channel1/nicknames/titi
(titi) /quit
(titi)          rm serverid/nicknames/titi

----------
Queries the model must satisfy (to complete):

1. How to know connected nickname list on 'channel1' ?
List the files into serverid/channels/encoded_channel1/nicknames/ and decode the found filenames

2. How to know list of connected user on the server ?
List the files into serverid/nicknames/ and decode the found filenames

3. How to disconnect a user by timeout ?
Only other users can disconnect a timeouted user.
Consider one connected user on channel1.
2 steps :
- into serverid/channels/encoded_channel1/nicknames/, check the files modification times and remove the timeouted files (generate a server notice on the channel1 if necessary)
- into serverid/nicknames/, do the same as the channel1 procedure (generate a notice into the global server messages)

4. How to change nick when user is connected to several channels ?
- Rename nickname stored into serverid/nicknames/
- Request the user's metadata, and read the 'channels' parameters.
- Rename each nickname stored into every joined channels serverid/channels/encoded_channel.../nicknames/

5. How to handle private message ?
A private chat will be a channel (with a specific name) with only two nicknames.

6. How to notify the user when he is invited to talk on a private chat ?
Use the server message pool to post a "invite" command. Then the other user will read it and automaticaly join the private channel.

[phpfreechat]

I spoke with Bernhard Grün about this model and gave a nice comment about meta data.
Rather than defining 3 metadata function, just define one. So common code is grouped and easily maintained.

Here the default 'File' container structure for metadata :
(it separates each metadata into one file with a simple hash function on the key)

Code: Select all

serverid/metadata/server/hashed_key1
serverid/metadata/server/hashed_key2
serverid/metadata/channels/encoded_chan1/hashed_key1
serverid/metadata/channels/encoded_chan1/hashed_key2
serverid/metadata/nicknames/encoded_nick1/hashed_key1
serverid/metadata/nicknames/encoded_nick1/hashed_key2

Now here the more generic functions to manipulate that model :

Code: Select all

/**
 * Read meta data identified by a key
 * As an example the default file container store metadata into metadata/type/subtype/hash(key)
 * @param $key is the index which identify a metadata
 * @param $type is used to "group" some metadata
 * @param $subtype is used to "group" precisely some metadata, use NULL to ignore it
 * @return mixed the value assigned to the key
 */
getMeta($key, $type, $subtype = NULL)


/**
 * Write a meta data value identified by a key
 * As an example the default file container store metadata into metadata/type/subtype/hash(key)
 * @param $key is the index which identify a metadata
 * @param $value is the value associated to the key
 * @param $type is used to "group" some metadata
 * @param $subtype is used to "group" precisely some metadata, use NULL to ignore it
 */
setMeta($key, $value, $type, $subtype = NULL)

/**
 * Remove a meta data key/value couple
 * Notice: if key is NULL then all the meta data must be removed
 * @param $key is the key to delete, use NULL to delete all the metadata
 * @param $type is used to "group" some metadata
 * @param $subtype is used to "group" precisely some metadata, use NULL to ignore it
 */
rmMeta($key, $type, $subtype = NULL)

Don't hesitate to comment.

[Djamoer]

Sorry if this is sounds kinda stupid.

- What is metadata? What kind of information going to be stored on metadata?
- What is serverid? Is it a container for several server, so basically with one installtion, we can have multiple different channel, just like in RC, we can assume having freenode.net, dal.net, and etc?
- What's going to be inside the nicknames folder? I believe encoded_nick1 is the session id for the current user, right? Then what's the hashed_key going to be? Is it a files? What's gonna be on there? If it's a file, then what about encoded_nick1, is it a folder?
- Same question with nick but for channel.

Please answer to my questions when you have time, if not, I will patiently waiting for more explanation.

Thank you

[phpfreechat]

- What is metadata? What kind of information going to be stored on metadata?

examples :
- the server configurations option could be stored in the server metadata file
- a nickname could have some flags for moderation : operator, administrator ...
- a nickname could have a Name/Surname/Address ..., a small image (avatar) ..., can be away (with linked away message...)
- a channel can have a topic, can have channel master ...

- What is serverid? Is it a container for several server, so basically with one installtion, we can have multiple different channel, just like in RC, we can assume having freenode.net, dal.net, and etc?

'serverid' looks like the hostname on IRC.
Into one server (identified by its serverid) it's possible to create several channels and join/quit these channel without disconnecting (you keep the same nickname from begining to end).

- What's going to be inside the nicknames folder? I believe encoded_nick1 is the session id for the current user, right? Then what's the hashed_key going to be? Is it a files? What's gonna be on there? If it's a file, then what about encoded_nick1, is it a folder?
- Same question with nick but for channel.

encoded_nick1, hashed_key, are files.
The default File container use a folder to know which nickname is connected. One file per nickname. The filename is created from the nickname using a simple encoding function.
A need to encode because filesystem doesn't support unicode strings (none latine characteres) and special characteres.
The encoding fonction is really simple : function _encode($str) { base64_encode(urlencode($str)); }
The decoding function is also very simple : function _decode($str) { urldecode(base64_decode($str)); }
About the hashed_key, I think I could name it encoded_key and use the same encode/decode function as the nicknames.

I hope I was clear.

[Djamoer]

Ok, I think it's clear to me now. Thanks for taking your time in explaining my question.