From bfe265658b05e010427e952719af8283800bc6ed Mon Sep 17 00:00:00 2001 From: or-else Date: Mon, 6 Oct 2025 16:10:34 +0300 Subject: [PATCH] mention slf topic, explain internal --- docs/API.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/API.md b/docs/API.md index cd20426f..b3543e36 100644 --- a/docs/API.md +++ b/docs/API.md @@ -341,6 +341,14 @@ Message `{get what="sub"}` to `me` is different from any other topic as it retur Message `{get what="data"}` to `me` is rejected. +Internally the `me` topics are not persisted separately from the users. The `me` topics don't exist in the `topics` table or collection, they are created in memory from the `users` database record. + +### `slf` Topic + +Topic `slf` (self) provides mechanism for storing information, like bookmarks or saved messages. Messages sent to `slf` are accessible only by the user who sent them. + +This topic is created automatically when the user subscribes to it for the first time. + ### `fnd` and Tags: Finding Users and Topics Topic `fnd` is automatically created for every user at the account creation time. It serves as an endpoint for discovering other users and group topics. Users and group topics can be discovered by `tags`. Tags are optionally assigned at the topic or user creation time then can be updated by using `{set what="tags"}` against a `me` or a group topic. @@ -361,6 +369,8 @@ _CURRENTLY UNSUPPORTED_ When a new user registers with tags matching the given q [Plugins](../pbx) support `Find` service which can be used to replace default search with a custom one. +Internally the `fnd` topics are not persisted separately from the users. The `fnd` topics don't exist in the `topics` table or collection, they are created in memory from the `users` database record. + #### Query Language Tinode query language is used to define search queries for finding users and topics. The query is a string containing atomic terms separated by spaces or commas. The individual query terms are matched against user's or topic's tags. The individual terms may be written in an RTL language but the query as a whole is parsed left to right. Spaces are treated as the `AND` operator, commas (as well as commas preceded and/or followed by a space) as the `OR` operator. The order of operators is ignored: all `AND` tags are grouped together, all `OR` tags are grouped together. `OR` takes precedence over `AND`: if a tag is preceded of followed by a comma, it's an `OR` tag, otherwise an `AND`. For example, `aaa bbb, ccc` (`aaa AND bbb OR ccc`) is interpreted as `(bbb OR ccc) AND aaa`. @@ -407,6 +417,8 @@ Peer to peer (P2P) topics represent communication channels between strictly two A P2P topic is created by one user subscribing to topic with the name equal to the ID of the other user. For instance, user `usrOj0B3-gSBSs` can establish a P2P topic with user `usrIU_LOVwRNsc` by sending a `{sub topic="usrIU_LOVwRNsc"}`. Tinode will respond with a `{ctrl}` packet with the name of the newly created topic as described above. The other user will receive a `{pres}` message on `me` topic with updated access permissions. +Internally, P2P topics are stored as `p2p` followed by base64 URL encoded concatenation of two 64-bit user IDs, with the lower numeric value ID first: `p2pm7PvMGmdcx_uVkDRaSTbwA`. + The 'public' parameter of P2P topics is user-dependent. For instance a P2P topic between users A and B would show user A's 'public' to user B and vice versa. If a user updates 'public', all user's P2P topics will automatically update 'public' too. The 'private' parameter of a P2P topic is defined by each participant individually as with any other topic type.