cyxth channels concepts §

the concept of a channel is used in all the cyxth core modules. users in the same channel can interact for example for a colab channel all users will receive changes same for calls and chat.

the channel interfaces offers a uniform way to manage users, configure channels and listen for common events and that occur within channels. here is a summary of the channel interface.

Channels are made of users who have various permissions to perform given actions on the channel. when a user performs an action it may trigger an event that is sent to users in the same channel following the channel configuration.

take an example of a user joining a call channel. first the user will use the join function which will fire the "user:join" event. depending on the call config this event may be sent to only admins to allow user to join or be sent to all other users. the config will also checked on the types and number of tracks allowed per user.

let’s go through an overview of channels and users.

users §

a channel user contains an id, permission and channel local data. the user has to be an authorized user. channel local data contains application data of the user specific to the channel which can only be edited by the user.

tsinterface ChannelUser {
 id: string;
 lData: string;
 mode: ChannelUserPermission;
}

permissions §

users have 4 basic permission flags to access a resource (colab, chat or calls) in channel.

tsenum PERM {
 // can manage users and configure channel
 ADMIN = 4,
 // can write to channel
 EDITOR = 2,
 // can only view channel and recieve updates
 VIEWER = 1,
 // user has no access
 NO_ACCESS = 0
}

by default all users have edit and view permissions only unless configured other wise. There can only be one owner who is also the creator of the channel. the owner has the special permission to delete the channel.

Editors have the permissions to modify a given resource for example, in calls they can send video or audio, in colab they can change the colab state and in chat they can send messages.

Viewers can only receive messages and view channel without editing the channel state.

No access means a user is blocked and can’t receive events nor view the channel info and users.

combining any of the flags gives you the flexibility to manage user actions in the channel efficiently i.e you can create custom permissions using the bitwise or | operation as shown below.

tslet admin = PERM.ADMIN | PERM.EDITOR | PERM.VIEWER;
// admin = 4 | 2 | 1 => 7
let default = PERM.EDITOR | PERM.VIEWER
// default = 2 | 1 => 3
let viewer = PERM.VIEWER // 1
let blocked = PERM.NO_ACCESS // 0

channels §

users perform various actions on channels. these actions can be split into three main sections

• channel initialization
• user management
• channel configuration

initialization §

initialization involves creating a channel or joining existing channels. while in the initialization phase users can get channel information, list users or even channel contents.

the first thing when interacting with cyxth will always be create or join. and then either info to get the channel information or get channel state which differs per module in colab you can get state, in chat get messages in channel if storage is enabled and in calls get the existing callers.

in some cases join may return the state too for example calls. after this initialization users now can do specific actions depending on the module i.e collaborate with colab and chat with calls or chat.

here is a sample in colab.

ts// ...
const stateId = "shared-docs"

const colab = await cyxth.colab();
let doc = await colab.join(stateId);

let state = doc.value();
let users = doc.getUsers();

//...

when users are done with the channel they can leave. channel admins have the ability to delete the channel

user management §

users with the admin priviledges can manage users in channels. these includes addUsers , delUsers and moderate users by assigning specific permissions to them. user management can also be triggered by certain events which admins have to react to i.e "user:join" depending in channel configuration or specific modules.

tsconst stateId = "shared-docs"

const colab = await cyxth.colab();
let doc = await colab.join(stateId);

doc.addUsers(["alice", "bob", "dan"]);

configuration §

channel has configure method used to configure the channel. this will mostly depend on a given module. Configuration options for a given module are generally in the form ModuleConfig for example for calls it will be CallConfig or ColabConfig for colab and so on. some options are common for example defaultPermission and actionMap to map various actions to permissions.

app-wide permissions for channels can be set with the rest api or in the cyxth console.

only admins can configure a channel.

ts// ...
doc.configure({
    defaultPermission: PERM.VIEWER,
    joinRequest: true,
})

events §

performing various actions on the channel will generally emit events. these events are prefixed with "resource:action", common events happen in the channel "cnl" or "user" resources. for example changing channel configuration will trigger "cnl:config" and if a user leaves a channel "user:left".

by listening for these events using the on method in the specific channel you are able to update and show changes to channel or users. some modules strictly require listening to certain events to function properly.

other modules may have there own resources i.e "track:add" for calls. to get a map of events in a given module check out the ModuleEventMap which lists the events and there return data types for example ColabEventMap for colab and CallEventMap for calls.

ts//...
doc.on("user:join", ({userId, mode}) => {
    activeUsers.add({id: userId, mode});
})

colab.on("user:left", ({userId}) => {
    activeUsers.remove(userId);
})

conclusion §

this channel actions, events and configuration cuts across all the cyxth modules. it should also be noted that various modules have their own unique events, configurations and actions. through out these series of guides we will be focusing on the specific resource actions, events and config, feel free to come back here for reference or the channel api reference.

-- ✌🏾