diff --git a/prosody-modules/mod_pubsub_peertubelivechat/mod_pubsub_peertubelivechat.lua b/prosody-modules/mod_pubsub_peertubelivechat/mod_pubsub_peertubelivechat.lua index 8c336da5..ee723e14 100644 --- a/prosody-modules/mod_pubsub_peertubelivechat/mod_pubsub_peertubelivechat.lua +++ b/prosody-modules/mod_pubsub_peertubelivechat/mod_pubsub_peertubelivechat.lua @@ -2,7 +2,7 @@ -- This idea is described in https://xmpp.org/extensions/xep-0316.html -- but here there are some differences: -- * there will be several nodes, using MUC JID+NodeID to access them --- (see https://xmpp.org/extensions/xep-0060.html#addressing-jid) +-- (see https://xmpp.org/extensions/xep-0060.html#addressing-jidnode) -- * nodes can only be subscribed by room admin/owner, -- * ... diff --git a/support/documentation/content/en/technical/tasks.md b/support/documentation/content/en/technical/tasks.md new file mode 100644 index 00000000..66b79e4c --- /dev/null +++ b/support/documentation/content/en/technical/tasks.md @@ -0,0 +1,136 @@ +--- +title: "Tasks overview" +description: "Task Application technical overview" +weight: 70 +chapter: false +livechatnotranslation: true +--- + +The livechat plugin includes a [Task Application](/peertube-plugin-livechat/documentation/user/streamers/tasks). +The present document describes how this is implemented. + +## Basics + +This features relies on [XEP-0060: Publish-Subscribe](https://xmpp.org/extensions/xep-0060.html). +This XEP provide a way to store and retrieve items, and to receive push notifications when an item is created/deleted/modified. + +There is a Prosody Module, [mod_pubsub_peertubelivechat](https://github.com/JohnXLivingston/peertube-plugin-livechat/tree/main/prosody-modules/mod_pubsub_peertubelivechat), to implement some specific use of the pubsub mechanism. + +We use the [JID+NodeID addressing](https://xmpp.org/extensions/xep-0060.html#addressing-jidnode) to specify some nodes related to each MUC room. +The JID is the MUC room JID, the NodeID is functionnality we want to address. +For now, this modules only implement one such node: "livechat-tasks", to handle tasks and task lists. +But the module code anticipates futur uses. + +The "livechat-tasks" node contains two type of objects: Task and TaskList (XML Namespaces: `urn:peertube-plugin-livechat:tasklist` and `urn:peertube-plugin-livechat:task`). Tasks have an attribute containing their task list id. + +On the front-end, we have the [livechat-converse-tasks](https://github.com/JohnXLivingston/peertube-plugin-livechat/tree/main/conversejs/custom/plugins/tasks) plugin for ConverseJS. + +## Workflow + +Here is the basic workflow used to subscribe to tasks/task-lists, and receive existing items. + +* the browsers connect to the chat, and ConverseJS uses the [XMPP discovery](https://xmpp.org/extensions/xep-0045.html#disco-roominfo) to get the room features. +* mod_pubsub_peertubelivechat declares two features: `urn:peertube-plugin-livechat:tasklist` and `urn:peertube-plugin-livechat:task`. +* the browsers detect these feature, and checks that the user has admin or owner affiliation on the MUC component. +* if not, won't display the Task Application, and stops here. +* if yes, we will continue: +* display the Task Application. +* Create a new [PubSubManager](https://github.com/JohnXLivingston/peertube-plugin-livechat/tree/main/conversejs/custom/shared/lib/pubsub-manager.js) object, that will subscribe to the pubsub node. +* The backend receives the subscription request, test user rights (must be owner/admin on the MUC), and adds the user to the subscribers. +* Note: a user with multiple browsers tabs will send multiple subscription requests, but this is not an issue. +* If the node did not exist, the backend automatically created it, and use the MUC name to create a first task-list with that name. +* Once subscribed, the frontend will request all current entries. +* The backend tests rights, and send all node entries. +* On the frontend, the PubSubManager handles the response by dispatching received items to the correct frontend component. + +Note: on the backend side, we subscribe all users with the "publisher" affiliation level. +This allows them to publish items, but not change the node configuration. + +Here is the worflow to create/modify/delete items: + +* the frontend send a publish request. +* backend checks rights. +* backend sends notifications to all subscribers, including the current users. +* On the front-end PubSubManager receives the notification, and dispatch it to the relevant component. + +## Unsubscribing + +When a user leaves a MUC room, he is automatically unsubscribe from the "livechat-tasks" node related to this room. + +When a user lose the owner/admin affiliation, he/she is removed from the "livechat-tasks" node. + +## Items + +Here we describes the content of node items. + +### Task lists + +* Item tag: `tasklist` +* XML Namespace: `urn:peertube-plugin-livechat:tasklist` +* item childs: + * `name`: the text content is the task list name + +Example: here is an example of IQ stanza to create a task-list item. + +```xml + + + + + + Task List Name + + + + + +``` + +### Tasks + +* Item tag: `task` +* XML Namespace: `urn:peertube-plugin-livechat:task` +* item attributes: + * `done`: if present and equal to "true", means that the task is done + * `list`: the list id + * `order`: the order of the task in the task list +* item childs: + * `name`: the text content is the task name + * `description`: the text content is the task description + +Example: here is an example of IQ stanza to create a task-list item. + +```xml + + + + + + The task name + here is the description + + + + + +``` + +Note: in the above example, we added `done="true"` just for the example. +Don't add the attribute if you want not the task to be marked as done (or if you want to undone the task).