=============
Relationships
=============

A relationship between two users in the AcceleratXR platform is referred to internally as a ``UserLink``. Users can 
have any number of links to any number of other users. Each link describes the type relationship between two users
in addition to an optional alias and arbitrary data map. This makes it possible to implement the following social
network concepts.

* Followers
* Friends
* Blocked Users
* Recently Met Users

The ``alias`` allows users to provide a custom name for the other user that is specific to them within their list. This
can be helpful in identifying the relationship among many other users with similar common names. Lastly, the ``data``
property is also provided in order to give you the ability to implement additional capabilities that may be app
specific.

Encountering Users (\ ``ENCOUNTER``\ )
--------------------------------------

When players encounter one another while interacting in the product it is possible to create an ``ENCOUNTER`` user
link. This link is intended to track all players that a user may have recently met and desire to see again in the
future.

Following Users (\ ``FOLLOW``\ )
--------------------------------

User links with the ``FOLLOW`` type describes relationships where a user is interested in being following the activity
of another user. This relationship is one-way in that the source user (\ ``userUid``\ ) wants to follow the activity
other user (\ ``otherUid``\ ). This makes it possible to create loosely coupled relationships between users which can
be beneficial when needing to create and maintain a set of one-way relationships for users such as subscribing to a
user's feed.

Friending Users (\ ``FRIEND``\ )
--------------------------------

A user link with the ``FRIEND`` type is the two-way relationship whereby two users indepedently have chosen to follow
the other. As this is a two-way relationship, requiring both users to participate, it is not possible to simply create
a user link with the ``FRIEND`` type. Instead, any time two users create a ``FOLLOW`` link to each other the system
will automatically upgrade their relationship to a ``FRIEND`` type. Should either side choose to delete their
respective side of the relationship then the opposing link will be downgraded down to a ``FOLLOW`` link.

For applications implementing a friends list system it is recommended that each user creates a ``FOLLOW`` link to
another and then sends a friend invite message to encourage the other user to create the needed opposite link to
complete the ``FRIEND`` relationship. This can be accomplished via the following steps.

Given user A wants to add user B as a friend...


#. User A creates a UserLink to user B with type ``FOLLOW``.
#. User A sends message to user B containing an ``invite`` attachment to add them as a friend.

.. code-block:: javascript

   {
       senderUid: <UserA_UUID>,
       receiverUid: <UserB_UUID>,
       subject: "UserA wants to be your friend!",
       body: "User A wants to be your friend.",
       attachments: {
           invite: "{ type: \"userlink\", userUid: <UserA_UUID> }"
       }
   }


#. User B receives message containing friend invite sent by User A.
#. User B accepts friend invite. Creates a UserLink to user A with type ``FOLLOW``
#. System automatically upgrades both connections to ``FRIEND``

Blocking Users (\ ``BLOCK``\ )
------------------------------

Not everyone is going to want to be friends. In the event that a user wishes not to interact with another user they
can create a UserLink with the ``BLOCK`` type. This relationship is always a one-way relationship however it is special
in that the system will not allow a user to create an opposing ``FOLLOW`` link if an existing ``BLOCK`` exists.
Similarly, if there exists a ``FOLLOW`` relationship between the two users then that link will be removed once a
``BLOCK`` link is created. This is true even in the event that a ``FRIEND`` relationship exists. In the event that a
user attempts to follow a user that has blocked them an error is returned by the service. It is the responsibilty of
the application to decide whether or not this error should be displayed to the user.