We do have a naming issue concerning all kinds of contexts. Groups could be simple contexts without the elaborate features of places (occasionally also dubbed rooms or chatrooms), but in fact groups as such do not exist. You could have a barebones context, but nobody ever did that. What we do have are presence contexts of a person, which reaches out for the group of friends of that person. Then there are also channels, but they are just a special case of contexts. So whenever you feel oppressed by all of these terms, just think they all basically mean the same thing.
This page describes a theoretical protocol somewhat similar to what psyced currently does, but for some reason all the _place have been replaced by _group. Strange.
You may want to look at Subscription for the future way to do this in an integrated manner with other protocol functions.
Contents |
Temporary membership in a group
Sometimes you want to be a member of a group for a limited amount of time. One particular import use-case of that is joining a chat room. In contrast to permanently subscribed group the use of the '_tag'-variable is mandatory to prevent forced joins to dubious places.
Entering the group
To request membership in a group a user sends _request_enter to that group. If the group manager decides to let the user participate, the protocol flow is as follows: The group manager
- may distribute a _notice_place_enter to all members of the group
- sends the user a _echo_place_enter
The user is now considered a member of the group.
To protect the user from being forced into groups you can tag the request.
After the _echo_place_enter has been sent to the user, the group manager may send additional information about the group ( current members, topic, current discussion, .. ).
The following is an example of a user entering a room. The _request_enter may look like this.
:_source psyc://host1/~user :_target psyc://host2/@room :_nick user :_tag somethingwicked _request_enter .
The room may now distribute a notice about the new member to everyone else (using some Routing strategy).
:_source_relay psyc://host1/~user :_context psyc://host2/@room :_nick user :_nick_place room _notice_place_enter [_nick] just entered [_nick_place]. .
Note that this message does not have the _target variable. Instead _context contains the address of the group and serves as routing information. The concept of Message Distribution is described elsewhere.
Should the room prefer quiet entry, or has some other reason to give acknowledgment by unicast like the need to keep the _tag private, the user would receive a message like this:
:_target psyc://host1/~user :_source psyc://host2/@room :_tag somethingwicked :_nick user :_nick_place room _echo_place_enter .
Alternatively, the room may decide not to let you join, in which case it will send a packet with an _error_place_enter method. You may also receive a _failure if the server cannot fulfill your wish because of internal errors.
:_target psyc://host1/~user :_source psyc://host2/@room :_tag somethingwicked :_nick user :_nick_place room _error_place_enter A reason why [_nick] cannot enter [_nick_place]. .
There is also one more special case, when the room wants to bring the user up to speed on the common state of the context. Then it would unicast something to the user, which looks like this:
:_target psyc://host1/~user :_context psyc://host2/@place :_tag somethingwicked :_nick user =_nick_place place =_description This is a great place to be. _echo_place_enter You have entered [_nick_place], [_nick]. [_description] .
We aren't using multicast state yet, but one day you may see this.
Entering a group by command request
Alternate method for entering a group. See also command.
=_source_identification psyc://host.tld/~nick =_target psyc://host.tld/~nick :_group psyc://server.tld/@group _request_do_enter .
Leaving the group
A user may leave a group with or without his request. In both cases the group manager sends a _notice_place_leave . A _request_leave by the user must be answered with a _notice_place_leave independent of the users membership. If and only if the user is a member of the group, the answer may be distributed to the whole group including the user. If he is not, it must not be distributed but sent to the user directly.
There is no way a group manager can force members to stay in a group. As a security issue, the user or his server side entity may enforce unanswered leave requests after a reasonable amount of time and report abuse to their local administrator.
Example of a user leaving a room (we assume that the user is actually in that room).
:_target psyc://host2/@room :_source psyc://host1/~user _request_leave .
The group manager may now send
:_context psyc://host2/@room :_source_relay psyc://host1/~user :_nick user :_nick_place room _notice_place_leave [_nick] just left [_nick_place]. .
to everyone in the room (before de-allocating the user from the _context. see Routing for tech details) or send
:_target psyc://host1/~user :_source psyc://host2/@room :_nick user :_nick_place room _notice_place_leave [_nick] just left [_nick_place]. .
to the user only.
Permanent membership in a group
Quite often, a permanent subscription is desired. Use cases for this are
- friendship and accompanying Friendship_Establishment (usually bidirectional)
- change notifications of files, websites (bidirectional, but cares less about the subscribers presenity)
Subscription to the group
Unsubscription
Message distribution in groups
When a user has joined a group he may receive messages distributed in that group. In case of a room, a user receives everything said in that room. He may also send messages to the group. The group however may refrain from distributing messages from a user. A very simple example of that case is a moderated room.
Example: Someone submitting a message to the room:
=_source_identification psyc://host1/~user :_target psyc://host2/@room :_action shouts :_nick user _message_public Wakeup people! .
In case the room decides to distribute the message it sends..
:_source_relay psyc://host1/~user :_context psyc://host2/@room :_action shouts :_nick user :_nick_place room _message_public Wakeup people! .
..down the chain of routers and slaves that will multicast the message to all room members.
_message_echo_public is an internal variant of _message_public where the identification has received the _message_public, detected that it is an echo, then forwarded it to clients as an echo.
Message storage
When keeping a history of messages in a room, a _time_place variable of the time type is added to the set of variables. The time of arrival of the message is stored into here, according to the time type.