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

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.