dandri/simplex-chat
1
0
Fork 0
mirror of https://github.com/simplex-chat/simplex-chat.git synced 2026-05-14 14:45:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into f/groups-via-relays

Browse Source
This commit is contained in:
spaced4ndy
2026-05-13 17:57:54 +04:00
parent b987da7c51 7908f4aad2
commit eb84bbc79a
91 changed files with 16292 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+552
View File
@@ -0,0 +1,552 @@
# Release History
## v6.5
30 April, 2026
Public channels - speak freely!
- Reliability: many relays per channel.
- Ownership: you can run your own relays.
- Security: owners hold channel keys.
- Privacy: for owners and subscribers.
Easier to invite your friends: we made connecting simpler for new users.
Safe web links:
- opt-in to send link previews.
- use SOCKS proxy for previews (if enabled).
- prevent hyperlink phishing.
- remove link tracking.
Non-profit governance: to make SimpleX Network last.
Read more on April 30 at 20:00 UTC: https://simplex.chat/blog/20260430-simplex-channels-v6-5-consortium-crowdfunding-freedom-of-speech.html
## v6.4
15 July, 2025
- Connect faster: message instantly once you tap Connect.
- Review group members: chat with new members before they join.
- Chat with admins: send your private feedback to group owners.
- New group role: Moderator - can remove messages and block members.
- Improved message delivery - less traffic on mobile networks.
Read about the new UX for making connections in the blog post: https://simplex.chat/blog/20250703-simplex-network-protocol-extension-for-securely-connecting-people.html
## v6.3
7 March, 2025
Better groups.
- Mention members and get notified when mentioned.
- Send private reports to moderators.
- Delete, block and change role for multiple members at once (Android and desktop only).
- Faster sending messages and faster deletion.
Better chat navigation
- Organize chats into lists to keep track of what's important.
- Jump to found and forwarded messages.
Better privacy and security.
- Private media file names.
- Message expiration in chats.
Read more on March 8: https://simplex.chat/blog/20250308-simplex-chat-v6-3-new-user-experience-safety-in-public-groups.html
## v6.2
7 December, 2024
- SimpleX Chat and Flux (https://runonflux.com) made an agreement to include servers operated by Flux into the app – to improve metadata privacy.
- Business chats – your customers' privacy.
- Improved user experience of chats:
- Open chat on the first unread message.
- Jump to quoted messages anywhere in the conversation.
- See who reacted to messages.
- Improved iOS push notifications.
Read more on December 10: https://simplex.chat/blog/20241210-simplex-network-v6-2-servers-by-flux-business-chats.html
## v6.1
12 October, 2024
Better security:
- SimpleX protocols reviewed by Trail of Bits.
- security improvements (don't worry, there is nothing critical there).
Better calls:
- you can switch audio and video during the call
- share the screen from desktop app.
Better iOS notifications:
- improved delivery, reduced traffic usage.
- more improvements are coming soon!
Better user experience:
- switch chat profile for 1-time invitations.
- customizable message shape.
- better message dates.
- forward up to 20 messages at once.
- delete or moderate up to 200 messages.
The protocols review by Trail of Bits and release announcement will be published on October 14 afternoon here: https://simplex.chat/blog/20241014-simplex-network-v6-1-security-review-better-calls-user-experience.html
## v6.0
11 August, 2024
New chat experience:
- connect to your friends faster.
- archive contacts to chat later.
- delete up to 20 messages at once.
- increase font size.
- new chat themes on iOS - same as on Android and desktop in the previous version.
- reachable chat toolbar - use the app with one hand.
New media options:
- share from other apps (iOS).
- play from the chat list.
- blur for better privacy.
Private routing: it protects your IP address and connections and is now enabled by default.
Connection and servers information: to control your network status and usage.
Read more on 8/14: https://simplex.chat/blog/20240814-simplex-chat-vision-funding-v6-private-routing-new-user-experience.html
## v5.8
3 June, 2024
- private message routing to protect IP addresses (opt-in in this version).
- protect IP address when receiving files.
- chat themes with wallpapers - set themes for all chats app-wide, per chat profile and per conversation - Android and desktop apps.
- some groups permissions can now be granted to admins only.
- improved message and file delivery with reduced battery usage.
- Persian interface language - Android and desktop apps.
Read more: https://simplex.chat/blog/20240604-simplex-chat-v5.8-private-message-routing-chat-themes.html
## v5.7
26 April, 2024
- quantum resistant end-to-end encryption – will be enabled for all direct chats!
- forward and save messages and files, without revealing the source.
- improved calls: in-call sounds when connecting calls, better support for bluetooth headphones.
- customizable shapes of profile images - from square to circle.
- more reliable network connection.
Lithuanian UI language in Android and desktop apps - thanks to our users!
Read more: https://simplex.chat/blog/20240426-simplex-legally-binding-transparency-v5-7-better-user-experience.html
## v5.6
21 March, 2024
1. **Quantum resistant end-to-end encryption** in direct chats (BETA).
It can be enabled for the new contacts by *Post-quantum E2EE* toggle in dev tools, and for the existing contacts - both users need to tap *Allow PQ encryption* in contact information page (and the toggle in dev tools should be enable for this button to be available).
Once quantum resistant shared secret is agreed, there will be a message indicating it - it takes about 2-3 messages from each side to be sent in turns before it gets enabled.
Read more about end-to-end encryption in SimpleX Chat here: https://simplex.chat/blog/20240314-simplex-chat-v5-6-quantum-resistance-signal-double-ratchet-algorithm.html
2. **App data migration**.
As suggested by one of SimpleX Chat users in our [users group](simplex:/contact#/?v=1-4&smp=smp%3A%2F%2FPQUV2eL0t7OStZOoAsPEV2QYWt4-xilbakvGUGOItUo%3D%40smp6.simplex.im%2Fos8FftfoV8zjb2T89fUEjJtF7y64p5av%23%2F%3Fv%3D1-2%26dh%3DMCowBQYDK2VuAyEAQqMgh0fw2lPhjn3PDIEfAKA_E0-gf8Hr8zzhYnDivRs%253D%26srv%3Dbylepyau3ty4czmn77q4fglvperknl4bi2eb2fdy2bh4jxtf32kf73yd.onion&data=%7B%22type%22%3A%22group%22%2C%22groupLinkId%22%3A%22lBPiveK2mjfUH43SN77R0w%3D%3D%22%7D), you can now migrate all data from one device to a new app installation by uploading it to the configured XFTP relays and then scanning QR code from the new device – choose *Migrate to another device* from the app settings and *Migrate from another device* on the first screen after installing the app.
3. **Use the app during the audio and video calls**.
Now you can continue using the app, with small video if it's a video call.
Also in this version:
- admins can block a member for all other members.
- much faster leaving and deleting groups.
- filtering chats no longer includes muted chats with unread messages.
- reduced memory usage when sending large files.
- desktop: scrollbars in all views with the scrolling - finally!
- iOS:
- fixed rendering glitches with messages and context menus.
- added Hungarian interface language.
The blog post with the announcement is coming on 3/23/2024.
## v5.5
23 January, 2024
- private notes - with encrypted files and media.
- paste link to connect - search bar now accepts invitation links.
- optional recent history in groups.
- improved message delivery - with reduced battery usage.
- reveal secrets in messages by tapping them.
- all files in local app storage are encrypted by default.
- allow deleting the last visible user profile.
- do not share contact address in member profile.
- many fixes!
Also, we added Hungarian (Android only) and Turkish interface - thanks to the users and Weblate (https://github.com/simplex-chat/simplex-chat/tree/stable#help-translating-simplex-chat).
## v5.4
25 November, 2023
- Link mobile and desktop apps via secure quantum-resistant protocol.
- Better groups:
- Faster to join and more reliable.
- Create groups with incognito profile.
- Block group members to hide their messages.
- Prohibit files and media in a group.
- Better calls:
- Connect faster and more stable (still far from great).
- Screen sharing in video calls in desktop app.
- Other improvements:
- profile names now allow spaces.
- when you delete contacts, they are optionally notified.
- previously used and your own SimpleX links are recognised by the app.
- many fixes and improvements.
## v5.3
22 September, 2023
All apps (Android, iOS, desktop):
- encrypt local files in app storage (except videos).
- improved groups:
- delivery receipts (up to 20 members).
- send direct messages to members even after contact is deleted.
- faster and more stable.
- simplified incognito mode.
- new privacy settings: show last messages & save draft.
- faster app loading.
- reduced memory usage by 40%.
- fixed bug preventing group members connecting (it will only help the new connections).
- iOS app fixes:
- playing videos on full screen.
- screen reader for messages.
- fixed most background crashes.
Also, 6 new interface languages added by the users: Arabic*, Bulgarian, Finnish, Hebrew*, Thai and Ukrainian!
\* Android and desktop only
## v5.2
22 July, 2023
- message delivery receipts – with opt out per contact!
- filter favorite and unread chats.
- keep your connections working after restoring from backup.
- share your address with group members via your chat profile.
- improved disappearing messages.
- a bit more usable groups.
- chat preference to prohibit message reactions.
- restart and shutdown buttons.
- more stable message delivery.
Read more: https://simplex.chat/blog/20230722-simplex-chat-v5-2-message-delivery-receipts.html
## v5.1
22 May, 2023
Mobile apps:
- message reactions 🚀
- self-destruct passcode
- improved messages:
- voice messages up to 5 minutes.
- custom time to disappear - can be set just for one message.
- message editing history.
- setting to disable audio/video calls per contact.
- welcome message visible in group profile.
Android only:
- new design and custom themes for Android - you can share them!
- configurable SOCKS proxy port.
- improved calls on lock screen.
- fixes for sending files.
- locale-dependent formatting of time and date.
Also, the users have added Japanese and Portuguese (Brazil) interfaces (the latter is available on Android only) - huge thanks!
## v5.0
20 April, 2023
- send videos and files up to 1gb - the recipient must have at least version 4.6.1.
- you can self-host XFTP servers and configure the app to use your servers.
- passcode as an alternative to system/device authentication.
- support for IPv6 server addresses.
- configurable SOCKS proxy host and port in Android app.
Also we added Polish interface language – [thanks to the users and Weblate](https://github.com/simplex-chat/simplex-chat#help-translating-simplex-chat).
See more details in this post: https://simplex.chat/blog/20230422-simplex-chat-vision-funding-v5-videos-files-passcode.html
## v4.6
25 March, 2023
Mobile apps:
- hidden chat profiles – you can protect them with a password!
- audio/video calls:
- iOS: completely re-implemented using WebRTC native library and iOS CallKit. Calls now work when the app is in background, and can be answered when the app is fully stopped.
- Android: added support for bluetooth headphones, volume control in video calls, proximity sensor turns off screen in audio calls.
- group moderation. Admins now can delete member messages and disable members (by assigning "observer" role).
- group welcome message to show to the new users when they join.
- reduced battery usage, particularly when sending messages to large groups.
- Chinese and Spanish interface.
Android app now supports Android 8+ (API 26+), and also supports 32 bit/ARMv7a devices via a separate APK. If you don't know which APK you need, try simplex.apk first. You can check your device CPU in z-cpu app.
Terminal / CLI app:
- hidden profiles are supported.
- improved help, with all supported commands included.
## v4.5
3 February, 2023
- multiple chat profiles: use different names, avatars and transport isolation.
- transport isolation: separate transport connections are used for each chat profile (default) or for each connection (BETA – enable dev tools to make this option available in Network & Servers.)
- message draft: the last message text and any attachments are now preserved when you leave the conversation (while the app is running).
- private filenames: to protect your timezone, image and voice message files now use UTC time.
## v4.4
31 December, 2022
- disappearing messages - with mutual agreement!
- live messages – they update for all recipients as you type them, every few seconds.
- connection security code verification, for contacts and group members – protect from MITM attack (e.g. invitation link substitution).
- performance improvements - faster UI loading, faster group deletion, etc.
Mobile apps:
- French language support in the UI!
iOS app:
- send animated images and "stickers" (e.g., from GIF and PNG files and from 3rd party keyboards)
## v4.3
4 December, 2022
Mobile apps:
- instant voice messages!
- irreversible deletion of sent messages on recipients devices (depends on chat preferences)
- an option to hide the app screen in the recent apps, and also prevent the screenshots on Android
- add SMP servers by scanning QR code, support for server passwords (with the new version 4.0 of SMP server)
- improved privacy and security of SimpleX invitation links in the app
## v4.2
6 November, 2022
- fixed issues from security audit!
- group links - group admins can create the links for new members to join
- auto-accept contact requests + configure to accept incognito and welcome message
- change group member role
- mark chat as unread
- on Android:
- support for image/gif/sticker keyboards
- fix keyboard bug with backspace
Beta features (enable Developer tools):
- manually switch contact or member to another address / server
- receive files faster (enable in Privacy settings)
## v4.1
13 October, 2022
Changes:
- automatic message deletion (set TTL per-chat or globally)
- change group member roles
- send multiple images at once
- connection aliases and information view
- share text and files from other apps into SimpleX (Android)
- image gallery (Android)
- scroll to quoted message (Android)
- German translations
- improved connection stability and performance
## v4.0
24 September, 2022
Changes:
Local database encryption with passphrase on iOS, Android, Linux, Mac!
Mobile apps:
- configurable WebRTC ICE servers - see https://github.com/simplex-chat/simplex-chat/blob/stable/docs/WEBRTC.md
- improved stability of establishing direct and group connections, files transfers and message reception.
- support for animated images on Android
- German language UI
- deleting files and media
Terminal app:
- disable messages and notifications per contact / group
For developers:
- [TypeScript SDK for integrating with SimpleX Chat](#typescript-sdk-for-integrating-with-simplex-chat) (e.g., chat bots or chat assistants).
## v3.2
20 August, 2022
Changes:
- use .onion addresses of the servers (if available) when Tor is used – it is based on a separate setting on iOS.
- endless scrolling and search in chats
- UI improvements
- reduced Android APK size (from 200 to 46Mb)
## v3.1
6 August, 2022
Mobile apps:
- secret chat groups!
- support accessing SimpleX messaging servers via Orbot (both iOS and Android)
- new app icons
- advanced network settings
- improved battery usage and traffic
Terminal app:
- support SOCKS5 proxy
- `/info` command to show information and servers for contacts and group members: use `/info <name>` for contact and `/info #<group> <name>` for member information.
## v3.0
9 July, 2022
Changes:
Chat core:
- support for push notifications on iOS
- support for database export/import in mobile clients
Terminal client:
- automatically accept contact requests and sending reply message with `/auto_accept on` and `/auto_accept on <message>` coomands
Mobile clients:
- instant push notifications for iOS (the sending clients have to be upgraded too for notifications to work),
- e2e encrypted WebRTC audio/video calls,
- export and import of chat database, allowing to move the chat profile to another device,
- improved privacy and performance of the protocol.
Please see [this post](https://github.com/simplex-chat/simplex-chat/blob/stable/blog/20220711-simplex-chat-v3-released-ios-notifications-audio-video-calls-database-export-import-protocol-improvements.md) for more details.
## v2.2
1 June, 2022
Changes:
- WebRTC calls integrated with CallKit (iOS)
- call notifications and alerts (Android)
- local authentication / app lock (both platforms)
- call settings and invitation timeouts
- privacy settings: auto-accepting images, link previews
- paste image from clipboard (iOS)
- SMP servers settings page (iOS)
## v2.1
21 May, 2022
New commands for terminal users:
- /clear - delete all messages in a conversation
- /image - send file as image for mobile clients
- /fforward - forward file to another conversation
- /image_forward - forward image to another conversation
## v2.0
11 May, 2022
For terminal users:
- /tail command to show the last messages from a given chat or from all chats
## v1.6
16 April, 2022
Changes:
- Improved stability of network connection.
- The new protocol to exchange files, in preparation to support images, files and groups in mobile apps. It makes sending files to groups much more efficient, and allows attaching files to the text messages. This version is backwards and forwards compatible, so you can exchange the files with the previous version. It will not be possible to receive the files sent from the next version (1.7) in the previous version (1.5) - please upgrade.
- **Up arrow** key in the terminal can be used to edit the last message you sent.
- CLI option to execute a single command / send one message, e.g. to use in CI to notify about the build completion, or for any other scenario.
- Library support + [chat bot examples](https://github.com/simplex-chat/simplex-chat/tree/stable/apps) to create SimpleX Chat chat bots.
## v1.5
3 April, 2022
Edit, delete and reply to messages, in the mobile apps and from the terminal.
## v1.4
26 March, 2022
Changes:
- message edit and delete in mobile apps
- profile images
- TCP keep-alive replacing SMP protocol pings (improved connection stability)
- bug fixes for chat scrolling and empty chat views
## v1.3
26 February, 2022
Changes:
- markdown support in messages (both platforms)
- user addresses (Android)
- group member names shown in messages
- display name validation
- asynchronous message processing (improved performance)
- search in chats
- Android app UI redesign (welcome page, help view, dark mode fixes)
## v1.2
14 February, 2022
Changes:
- message sent/unread status indicators (iOS)
- search in chats
- auto-accept contact requests option
- deduplicate contact requests
- iOS public beta launch
- connection stability fixes
## v1.1
2 February, 2022
- TLS 1.3 support.
- Terminal app is now also a backend for our new mobile app - public access to our new iOS app via TestFlight is coming soon!
- The code base now includes an iOS app preview.
## v1.0
12 January, 2022
### The most private and secure chat and application platform
We are building a new platform for distributed Internet applications where privacy of the messages _and_ the network matter. [SimpleX Chat](https://github.com/simplex-chat/simplex-chat) is our first application, a messaging application built on the SimpleX platform.
### What is SimpleX?
There is currently no messaging application other than SimpleX Chat that guarantees metadata privacy - who is communicating with whom and when. SimpleX is designed to not use any permanent users identities to protect meta-data privacy. See [SimpleX overview](https://github.com/simplex-chat/simplexmq/blob/master/protocol/overview-tjr.md) for more details.
### SimpleX protocol changes
Best possible E2E encryption - the only messenger using two-layer E2E encryption, with one layer using double ratchet protocol that provides forward secrecy and break-in recovery, and additional encryption layer providing meta-data protection. See more details about encryption algorithms in [SimpleXMQ change log](https://github.com/simplex-chat/simplexmq/blob/master/CHANGELOG.md#100).
Performance and space efficiency improvements - protocol overhead is reduced from circa 15% to 3.7% thanks to binary encoding, and performance is substantially improved due to more efficient cryptographic algorithms.
Shorter invitation and contact links due to switching from long RSA to much shorter Curve448/25519 keys - for example, you can connect to the team via [team's SimpleX Chat contact address](https://simplex.chat/contact#/?v=1&smp=smp%3A%2F%2FPQUV2eL0t7OStZOoAsPEV2QYWt4-xilbakvGUGOItUo%3D%40smp6.simplex.im%2FK1rslx-m5bpXVIdMZg9NLUZ_8JBm8xTt%23MCowBQYDK2VuAyEALDeVe-sG8mRY22LsXlPgiwTNs9dbiLrNuA7f3ZMAJ2w%3D) (you need to use it in terminal app) or just by using `/simplex` command in the chat.
This [this post](https://github.com/simplex-chat/simplex-chat/blob/master/blog/20220112-simplex-chat-v1-released.md) for more information.
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt
+26 -11
View File
@@ -91,6 +91,13 @@ enum class SimplexLinkMode {
}
}
enum class CloseBehavior {
Ask, Quit, MinimizeToTray;
companion object { val default = Ask }
}
class HintPref(val reset: () -> Unit, val isUnchanged: () -> Boolean)
// Spec: spec/state.md#AppPreferences
class AppPreferences {
// deprecated, remove in 2024
@@ -99,6 +106,7 @@ class AppPreferences {
SHARED_PREFS_NOTIFICATIONS_MODE,
if (!runServiceInBackground.get()) NotificationsMode.OFF else NotificationsMode.default
) { NotificationsMode.values().firstOrNull { it.name == this } }
val closeBehavior: SharedPreference<CloseBehavior> = mkSafeEnumPreference(SHARED_PREFS_DESKTOP_CLOSE_BEHAVIOR, CloseBehavior.default)
val notificationPreviewMode = mkStrPreference(SHARED_PREFS_NOTIFICATION_PREVIEW_MODE, NotificationPreviewMode.default.name)
val canAskToEnableNotifications = mkBoolPreference(SHARED_PREFS_CAN_ASK_TO_ENABLE_NOTIFICATIONS, true)
val backgroundServiceNoticeShown = mkBoolPreference(SHARED_PREFS_SERVICE_NOTICE_SHOWN, false)
@@ -257,17 +265,23 @@ class AppPreferences {
val oneHandUI = mkBoolPreference(SHARED_PREFS_ONE_HAND_UI, true)
val chatBottomBar = mkBoolPreference(SHARED_PREFS_CHAT_BOTTOM_BAR, true)
val hintPreferences: List<Pair<SharedPreference<Boolean>, Boolean>> = listOf(
laNoticeShown to false,
oneHandUICardShown to false,
addressCreationCardShown to false,
liveMessageAlertShown to false,
showHiddenProfilesNotice to true,
showMuteProfileAlert to true,
showReportsInSupportChatAlert to true,
showDeleteConversationNotice to true,
showDeleteContactNotice to true,
privacyLinkPreviewsShowAlert to true,
val hintPreferences: List<HintPref> = listOf(
hintPref(laNoticeShown, false),
hintPref(oneHandUICardShown, false),
hintPref(addressCreationCardShown, false),
hintPref(liveMessageAlertShown, false),
hintPref(showHiddenProfilesNotice, true),
hintPref(showMuteProfileAlert, true),
hintPref(showReportsInSupportChatAlert, true),
hintPref(showDeleteConversationNotice, true),
hintPref(showDeleteContactNotice, true),
hintPref(privacyLinkPreviewsShowAlert, true),
hintPref(closeBehavior, CloseBehavior.default),
)
private fun <T> hintPref(pref: SharedPreference<T>, default: T) = HintPref(
reset = { pref.set(default) },
isUnchanged = { pref.state.value == default },
)
private fun mkIntPreference(prefName: String, default: Int) =
@@ -479,6 +493,7 @@ class AppPreferences {
private const val SHARED_PREFS_CONNECT_REMOTE_VIA_MULTICAST_AUTO = "ConnectRemoteViaMulticastAuto"
private const val SHARED_PREFS_OFFER_REMOTE_MULTICAST = "OfferRemoteMulticast"
private const val SHARED_PREFS_DESKTOP_WINDOW_STATE = "DesktopWindowState"
private const val SHARED_PREFS_DESKTOP_CLOSE_BEHAVIOR = "DesktopCloseBehavior"
private const val SHARED_PREFS_SHOW_DELETE_CONVERSATION_NOTICE = "showDeleteConversationNotice"
private const val SHARED_PREFS_SHOW_DELETE_CONTACT_NOTICE = "showDeleteContactNotice"
private const val SHARED_PREFS_SHOW_SENT_VIA_RPOXY = "showSentViaProxy"
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatView.kt
-1
View File
@@ -3597,7 +3597,6 @@ fun providerForGallery(
override fun scrollToStart() {
initialIndex = 0
initialChatId = chatItems.firstOrNull { canShowMedia(it) }?.id ?: return
}
override fun onDismiss(index: Int) {
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/TextSelection.kt
+36 -10
View File
@@ -36,6 +36,7 @@ import androidx.compose.ui.unit.IntSize
import androidx.compose.ui.unit.dp
import chat.simplex.common.model.*
import chat.simplex.common.platform.*
import chat.simplex.common.views.chat.item.itemPrefixText
import chat.simplex.common.views.chat.item.itemSegmentDisplayText
import chat.simplex.common.views.helpers.generalGetString
import chat.simplex.res.MR
@@ -52,8 +53,10 @@ val LocalItemContext = compositionLocalOf { ItemContext() }
data class SelectionRange(
val startIndex: Int,
val startItemId: Long,
val startOffset: Int,
val endIndex: Int,
val endItemId: Long,
val endOffset: Int
)
@@ -79,11 +82,13 @@ class SelectionManager {
var viewportPosition by mutableStateOf(Offset.Zero)
var focusCharRect by mutableStateOf(Rect.Zero) // X: absolute window, Y: relative to item
var listState: State<LazyListState>? = null
var mergedItemsState: State<MergedItems>? = null
var onCopySelection: (() -> Unit)? = null
private var autoScrollJob: Job? = null
fun startSelection(startIndex: Int, anchorY: Float, anchorX: Float) {
range = SelectionRange(startIndex, -1, startIndex, -1)
val id = mergedItemsState?.value?.items?.getOrNull(startIndex)?.newest()?.item?.id ?: return
range = SelectionRange(startIndex, id, -1, startIndex, id, -1)
selectionState = SelectionState.Selecting
anchorWindowY = anchorY
anchorWindowX = anchorX
@@ -96,7 +101,8 @@ class SelectionManager {
fun updateFocusIndex(index: Int) {
val r = range ?: return
range = r.copy(endIndex = index)
val id = mergedItemsState?.value?.items?.getOrNull(index)?.newest()?.item?.id ?: return
range = r.copy(endIndex = index, endItemId = id)
}
fun updateFocusOffset(offset: Int, charRect: Rect = Rect.Zero) {
@@ -175,6 +181,15 @@ class SelectionManager {
updateFocusIndex(idx)
}
fun resyncIndices() {
val r = range ?: return
val items = mergedItemsState?.value?.items ?: return
val newStartIndex = items.indexOfFirst { it.newest().item.id == r.startItemId }
val newEndIndex = items.indexOfFirst { it.newest().item.id == r.endItemId }
if (newStartIndex < 0 || newEndIndex < 0) clearSelection()
else range = r.copy(startIndex = newStartIndex, endIndex = newEndIndex)
}
fun updateAutoScroll(draggingDown: Boolean, pointerY: Float, scope: CoroutineScope) {
val edgeDistance = if (draggingDown) viewportBottom - pointerY else pointerY - viewportTop
if (edgeDistance !in 0f..AUTO_SCROLL_ZONE_PX) {
@@ -240,15 +255,22 @@ fun selectedRange(range: SelectionRange?, index: Int): IntRange? {
}
// Extracts source text for the selected range within one item.
// Selection offsets are in display-text space. For transformed segments (mentions, links with showText),
// the full source is emitted if any part is selected. For untransformed segments, partial substring works.
// Selection offsets are in display-text space (which includes any leading itemPrefixText).
// For transformed segments (mentions, links with showText), the full source is emitted if any part
// is selected. For untransformed segments, partial substring works.
private fun selectedItemCopiedText(ci: ChatItem, sel: IntRange, linkMode: SimplexLinkMode): String {
val formattedText = ci.formattedText ?: return ci.text.substring(
sel.first.coerceAtMost(ci.text.length),
(sel.last + 1).coerceAtMost(ci.text.length)
)
val prefix = itemPrefixText(ci)
val sb = StringBuilder()
var displayOffset = 0
if (sel.first < prefix.length) {
sb.append(prefix, sel.first, minOf(prefix.length, sel.last + 1))
}
val formattedText = ci.formattedText ?: run {
val start = (sel.first - prefix.length).coerceAtLeast(0).coerceAtMost(ci.text.length)
val end = (sel.last + 1 - prefix.length).coerceAtMost(ci.text.length)
if (start < end) sb.append(ci.text, start, end)
return sb.toString()
}
var displayOffset = prefix.length
for (ft in formattedText) {
val segDisplay = itemSegmentDisplayText(ft, ci, linkMode)
val displayEnd = displayOffset + segDisplay.length
@@ -269,7 +291,7 @@ private fun selectedItemCopiedText(ci: ChatItem, sel: IntRange, linkMode: Simple
// Snaps a boundary offset to include full transformed segments.
private fun snapOffset(ci: ChatItem, offset: Int, linkMode: SimplexLinkMode, expandRight: Boolean): Int {
val formattedText = ci.formattedText ?: return offset
var displayOffset = 0
var displayOffset = itemPrefixText(ci).length
for (ft in formattedText) {
val segDisplay = itemSegmentDisplayText(ft, ci, linkMode)
val displayEnd = displayOffset + segDisplay.length
@@ -312,11 +334,15 @@ fun BoxScope.SelectionHandler(
}
manager.listState = listState
manager.mergedItemsState = mergedItems
manager.onCopySelection = {
clipboard.setText(AnnotatedString(manager.getSelectedCopiedText(mergedItems.value.items, revealedItems.value, linkMode)))
showToast(generalGetString(MR.strings.copied))
}
// Resync after the items list mutates (new message arrives, item deleted).
SideEffect { manager.resyncIndices() }
return Modifier
.focusRequester(focusRequester)
.focusable()
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIImageView.kt
+1 -1
View File
@@ -182,7 +182,7 @@ fun CIImageView(
.then(
if (!smallView) {
val w = if (previewBitmap.width * 0.97 <= previewBitmap.height) imageViewFullWidth() * 0.75f else DEFAULT_MAX_IMAGE_WIDTH
Modifier.width(w).aspectRatio(previewBitmap.width.toFloat() / previewBitmap.height.toFloat())
Modifier.width(w).aspectRatio((previewBitmap.width.toFloat() / previewBitmap.height.toFloat()).coerceAtLeast(1f / 2.33f))
} else Modifier
)
.desktopModifyBlurredState(!smallView, blurred, showMenu),
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/FramedItemView.kt
+1 -1
View File
@@ -365,7 +365,7 @@ fun FramedItemView(
is MsgContent.MCReport -> {
val prefix = buildAnnotatedString {
withStyle(SpanStyle(color = Color.Red, fontStyle = FontStyle.Italic)) {
append(if (mc.text.isEmpty()) mc.reason.text else "${mc.reason.text}: ")
append(itemPrefixText(ci))
}
}
CIMarkdownText(chatsCtx, ci, chat, chatTTL, linkMode, uriHandler, onLinkLongClick, showViaProxy = showViaProxy, showTimestamp = showTimestamp, prefix = prefix)
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/TextItemView.kt
+7
View File
@@ -85,6 +85,13 @@ fun itemDisplayText(ci: ChatItem, linkMode: SimplexLinkMode): String {
return formattedText.joinToString("") { itemSegmentDisplayText(it, ci, linkMode) }
}
// Display-only prefix rendered before ci.text (e.g. "Spam: " for reports).
// Renderers and selection code MUST share this string — otherwise selection offsets drift from screen.
fun itemPrefixText(ci: ChatItem): String = when (val mc = ci.content.msgContent) {
is MsgContent.MCReport -> if (mc.text.isEmpty()) mc.reason.text else "${mc.reason.text}: "
else -> ""
}
// Text transformations in MarkdownText must match itemSegmentDisplayText above
@Composable
fun MarkdownText (
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chatlist/ChatPreviewView.kt
+2 -2
View File
@@ -255,11 +255,11 @@ fun ChatPreviewView(
ci.content.msgContent is MsgContent.MCChat -> null
else -> ci.formattedText
}
val prefix = when (val mc = ci.content.msgContent) {
val prefix = when (ci.content.msgContent) {
is MsgContent.MCReport ->
buildAnnotatedString {
withStyle(SpanStyle(color = Color.Red, fontStyle = FontStyle.Italic)) {
append(if (text.isEmpty()) mc.reason.text else "${mc.reason.text}: ")
append(itemPrefixText(ci))
}
}
apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/SettingsView.kt
+2 -6
View File
@@ -295,14 +295,10 @@ fun ChatLockItem(
}
private fun resetHintPreferences() {
for ((pref, def) in appPreferences.hintPreferences) {
pref.set(def)
}
appPreferences.hintPreferences.forEach { it.reset() }
}
fun unchangedHintPreferences(): Boolean = appPreferences.hintPreferences.all { (pref, def) ->
pref.state.value == def
}
fun unchangedHintPreferences(): Boolean = appPreferences.hintPreferences.all { it.isUnchanged() }
@Composable
fun AppVersionItem(showVersion: () -> Unit) {
apps/multiplatform/common/src/commonMain/resources/MR/base/strings.xml
+12
View File
@@ -3079,4 +3079,16 @@
<string name="link_previews_alert_desc_socks">Link preview will be requested via SOCKS proxy. DNS lookup may still happen locally via your DNS resolver.</string>
<string name="link_previews_alert_enable">Enable</string>
<string name="link_previews_alert_disable">Disable</string>
<!-- Desktop tray / minimize-to-tray -->
<string name="close_behavior_dialog_title">Minimize to tray?</string>
<string name="close_behavior_dialog_text">If you choose Close, messages won\'t be received.\nYou can change it later in Appearance settings.</string>
<string name="close_behavior_dialog_close">Close the app</string>
<string name="close_behavior_dialog_minimize">Minimize to tray</string>
<string name="tray_show">Show SimpleX</string>
<string name="tray_quit">Quit SimpleX</string>
<string name="tray_tooltip">SimpleX</string>
<string name="tray_tooltip_unread">SimpleX — %d unread</string>
<string name="appearance_minimize_to_tray">Minimize to tray when closing window</string>
<string name="appearance_minimize_to_tray_desc">Keep SimpleX running in the background to receive messages.</string>
</resources>
apps/multiplatform/common/src/commonMain/resources/MR/images/ic_simplex_tray_dot.svg
+46
View File
@@ -0,0 +1,46 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
width="120"
height="120"
viewBox="121 0 40 40"
fill="none"
version="1.1"
id="svg3"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="m 126.52238,11.425398 5.80302,5.716401 5.88962,-5.889626 2.8582,2.858201 L 135.1836,20 l 5.7164,5.716402 -2.94482,2.8582 -5.7164,-5.629789 -5.88962,5.803014 -2.8582,-2.858201 5.88962,-5.803014 -5.803,-5.716402 z"
fill="#030749"
id="path1"
style="stroke-width:0.866122" />
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="m 137.86858,28.661214 2.94481,-2.944812 v 0 l 5.88963,-5.803014 -5.80302,-5.62979 v 0 l -2.8582,-2.8582 -5.7164,-5.7164023 2.94481,-2.9448129 5.7164,5.7164017 5.88963,-5.8030138 2.8582,2.8582008 -5.88962,5.8030145 5.7164,5.716401 5.88962,-5.803014 2.8582,2.858201 -5.88962,5.803014 5.803,5.716402 -2.9448,2.858201 -5.7164,-5.716402 -5.88963,5.803013 5.7164,5.716402 -2.8582,2.944813 -5.80301,-5.716402 -5.80302,5.803015 -2.8582,-2.858201 z"
fill="url(#paint0_linear_40_164)"
id="path2"
style="fill:url(#paint0_linear_40_164);stroke-width:0.866122" />
<!-- Unread dot in bottom-right; cy ≤ 34 to keep it inside the 40×40 viewBox bottom edge -->
<circle cx="155" cy="34" r="6" fill="#e53935" />
<defs
id="defs3">
<linearGradient
x1="135.948"
y1="-0.81632602"
x2="132.09599"
y2="36.985699"
gradientUnits="userSpaceOnUse"
id="paint0_linear_40_164"
gradientTransform="matrix(0.86612147,0,0,0.86612147,18.863485,2.6775707)">
<stop
stop-color="#01f1ff"
id="stop2" />
<stop
offset="1"
stop-color="#0197ff"
id="stop3" />
</linearGradient>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.8 KiB

apps/multiplatform/common/src/commonMain/resources/MR/images/ic_simplex_tray_dot_light.svg
+46
View File
@@ -0,0 +1,46 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
width="120"
height="120"
viewBox="121 0 40 40"
fill="none"
version="1.1"
id="svg3"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="m 126.52238,11.425398 5.80302,5.716401 5.88962,-5.889626 2.8582,2.858201 L 135.1836,20 l 5.7164,5.716402 -2.94482,2.8582 -5.7164,-5.629789 -5.88962,5.803014 -2.8582,-2.858201 5.88962,-5.803014 -5.803,-5.716402 z"
fill="#ffffff"
id="path1"
style="stroke-width:0.866122" />
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="m 137.86858,28.661214 2.94481,-2.944812 v 0 l 5.88963,-5.803014 -5.80302,-5.62979 v 0 l -2.8582,-2.8582 -5.7164,-5.7164023 2.94481,-2.9448129 5.7164,5.7164017 5.88963,-5.8030138 2.8582,2.8582008 -5.88962,5.8030145 5.7164,5.716401 5.88962,-5.803014 2.8582,2.858201 -5.88962,5.803014 5.803,5.716402 -2.9448,2.858201 -5.7164,-5.716402 -5.88963,5.803013 5.7164,5.716402 -2.8582,2.944813 -5.80301,-5.716402 -5.80302,5.803015 -2.8582,-2.858201 z"
fill="url(#paint0_linear_40_164)"
id="path2"
style="fill:url(#paint0_linear_40_164);stroke-width:0.866122" />
<!-- Unread dot in bottom-right; cy ≤ 34 to keep it inside the 40×40 viewBox bottom edge -->
<circle cx="155" cy="34" r="6" fill="#e53935" />
<defs
id="defs3">
<linearGradient
x1="135.948"
y1="-0.81632602"
x2="132.09599"
y2="36.985699"
gradientUnits="userSpaceOnUse"
id="paint0_linear_40_164"
gradientTransform="matrix(0.86612147,0,0,0.86612147,18.863485,2.6775707)">
<stop
stop-color="#01f1ff"
id="stop2" />
<stop
offset="1"
stop-color="#0197ff"
id="stop3" />
</linearGradient>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.8 KiB

apps/multiplatform/common/src/commonMain/resources/MR/images/ic_simplex_tray_light.svg
+44
View File
@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
width="120"
height="120"
viewBox="121 0 40 40"
fill="none"
version="1.1"
id="svg3"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="m 126.52238,11.425398 5.80302,5.716401 5.88962,-5.889626 2.8582,2.858201 L 135.1836,20 l 5.7164,5.716402 -2.94482,2.8582 -5.7164,-5.629789 -5.88962,5.803014 -2.8582,-2.858201 5.88962,-5.803014 -5.803,-5.716402 z"
fill="#ffffff"
id="path1"
style="stroke-width:0.866122" />
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="m 137.86858,28.661214 2.94481,-2.944812 v 0 l 5.88963,-5.803014 -5.80302,-5.62979 v 0 l -2.8582,-2.8582 -5.7164,-5.7164023 2.94481,-2.9448129 5.7164,5.7164017 5.88963,-5.8030138 2.8582,2.8582008 -5.88962,5.8030145 5.7164,5.716401 5.88962,-5.803014 2.8582,2.858201 -5.88962,5.803014 5.803,5.716402 -2.9448,2.858201 -5.7164,-5.716402 -5.88963,5.803013 5.7164,5.716402 -2.8582,2.944813 -5.80301,-5.716402 -5.80302,5.803015 -2.8582,-2.858201 z"
fill="url(#paint0_linear_40_164)"
id="path2"
style="fill:url(#paint0_linear_40_164);stroke-width:0.866122" />
<defs
id="defs3">
<linearGradient
x1="135.948"
y1="-0.81632602"
x2="132.09599"
y2="36.985699"
gradientUnits="userSpaceOnUse"
id="paint0_linear_40_164"
gradientTransform="matrix(0.86612147,0,0,0.86612147,18.863485,2.6775707)">
<stop
stop-color="#01f1ff"
id="stop2" />
<stop
offset="1"
stop-color="#0197ff"
id="stop3" />
</linearGradient>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

apps/multiplatform/common/src/commonTest/kotlin/chat/simplex/app/ProviderForGalleryTest.kt
+67
View File
@@ -0,0 +1,67 @@
package chat.simplex.app
import chat.simplex.common.model.*
import chat.simplex.common.platform.chatModel
import chat.simplex.common.views.chat.providerForGallery
import kotlinx.datetime.Clock
import kotlin.test.AfterTest
import kotlin.test.BeforeTest
import kotlin.test.Test
import kotlin.test.assertEquals
// Regression for PR #6869: scrollToStart() must not rewrite initialChatId.
class ProviderForGalleryTest {
// Synthetic items pass canShowMedia only when chatModel.connectedToRemote() is true.
@BeforeTest
fun connectChatModelToRemote() {
chatModel.currentRemoteHost.value = RemoteHostInfo(
remoteHostId = 0L,
hostDeviceName = "",
storePath = "",
bindAddress_ = null,
bindPort_ = null,
sessionState = null,
)
}
@AfterTest
fun resetChatModel() {
chatModel.currentRemoteHost.value = null
}
@Test
fun testScrollToStartPreservesAnchor() {
val items = listOf(imageItem(1L), imageItem(2L), imageItem(3L))
var scrolledTo: Int? = null
val provider = providerForGallery(items, cItemId = 3L) { scrolledTo = it }
provider.currentPageChanged(provider.initialIndex - 1)
provider.scrollToStart()
provider.onDismiss(0)
assertEquals(1, scrolledTo)
}
// Pins the onDismiss early-return contract that testScrollToStartPreservesAnchor
// relies on to read the anchor back through the scrollTo callback.
@Test
fun testOnDismissOnActiveItemDoesNotScroll() {
val items = listOf(imageItem(1L), imageItem(2L), imageItem(3L))
var scrolledTo: Int? = null
val provider = providerForGallery(items, cItemId = 3L) { scrolledTo = it }
provider.onDismiss(provider.initialIndex)
assertEquals(null, scrolledTo)
}
private fun imageItem(id: Long): ChatItem =
ChatItem(
chatDir = CIDirection.DirectRcv(),
meta = CIMeta.getSample(id, Clock.System.now(), text = ""),
content = CIContent.RcvMsgContent(MsgContent.MCImage(text = "", image = "")),
reactions = emptyList(),
file = CIFile.getSample(fileId = id, fileName = "img-$id.jpg", filePath = "img-$id.jpg"),
)
}
apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt
+35 -4
View File
@@ -31,8 +31,11 @@ import kotlin.system.exitProcess
val simplexWindowState = SimplexWindowState()
fun showApp() {
val closedByError = mutableStateOf(true)
while (closedByError.value) {
// Probe SystemTray off the EDT — the lazy's first read would otherwise block the
// EDT during composition; JDK-8322750's GNOME detection forks a subprocess.
trayIsAvailable
while (true) {
val closedByError = mutableStateOf(false)
application(exitProcessOnExit = false) {
CompositionLocalProvider(
LocalWindowExceptionHandlerFactory provides WindowExceptionHandlerFactory { window ->
@@ -43,8 +46,9 @@ fun showApp() {
shareText = true
)
Log.e(TAG, "App crashed, thread name: " + Thread.currentThread().name + ", exception: " + e.stackTraceToString())
window.dispatchEvent(WindowEvent(window, WindowEvent.WINDOW_CLOSING))
// Must precede dispatchEvent — handleCloseRequest reads this flag.
closedByError.value = true
window.dispatchEvent(WindowEvent(window, WindowEvent.WINDOW_CLOSING))
includeMoreFailedComposables()
// If the left side of screen has open modal, it's probably caused the crash
if (ModalManager.start.hasModalsOpen()) {
@@ -73,9 +77,11 @@ fun showApp() {
}
}
) {
SimplexTray()
AppWindow(closedByError)
}
}
if (!closedByError.value) break
}
exitProcess(0)
}
@@ -115,7 +121,7 @@ private fun ApplicationScope.AppWindow(closedByError: MutableState<Boolean>) {
simplexWindowState.windowState = windowState
// Reload all strings in all @Composable's after language change at runtime
if (remember { ChatController.appPrefs.appLanguage.state }.value != "") {
Window(state = windowState, icon = painterResource(MR.images.ic_simplex), onCloseRequest = { closedByError.value = false; exitApplication() }, onKeyEvent = {
Window(state = windowState, visible = simplexWindowState.windowVisible.value, icon = painterResource(MR.images.ic_simplex), onCloseRequest = { handleCloseRequest(closedByError) }, onKeyEvent = {
if (it.key == Key.Escape && it.type == KeyEventType.KeyUp) {
simplexWindowState.backstack.lastOrNull()?.invoke() != null
} else {
@@ -224,6 +230,30 @@ private fun ApplicationScope.AppWindow(closedByError: MutableState<Boolean>) {
}
}
// Not invoked for macOS Cmd+Q — that goes through AWT's default QuitHandler and
// exits the process directly. Intentional: Cmd+Q is canonical "always quit" on macOS.
private fun ApplicationScope.handleCloseRequest(closedByError: MutableState<Boolean>) {
// Crash dispatch — bypass user-facing policy and exit; outer loop will restart.
if (closedByError.value) {
exitApplication()
return
}
val pref = ChatController.appPrefs.closeBehavior
when (pref.get()) {
CloseBehavior.Quit -> exitApplication()
CloseBehavior.MinimizeToTray -> if (trayIsAvailable) {
simplexWindowState.windowVisible.value = false
} else exitApplication()
CloseBehavior.Ask -> if (trayIsAvailable) {
requestCloseBehavior()
} else {
// Tray unavailable — Minimize is not a real option; remember Quit and exit.
pref.set(CloseBehavior.Quit)
exitApplication()
}
}
}
class SimplexWindowState {
lateinit var windowState: WindowState
val backstack = mutableStateListOf<() -> Unit>()
@@ -232,6 +262,7 @@ class SimplexWindowState {
val saveDialog = DialogState<File?>()
val toasts = mutableStateListOf<Pair<String, Long>>()
var windowFocused = mutableStateOf(true)
val windowVisible = mutableStateOf(true)
var window: ComposeWindow? = null
}
apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopTray.kt
+127
View File
@@ -0,0 +1,127 @@
package chat.simplex.common
import SectionItemView
import androidx.compose.foundation.layout.*
import androidx.compose.material.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.window.*
import chat.simplex.common.model.ChatModel
import chat.simplex.common.model.CloseBehavior
import chat.simplex.common.model.ChatController.appPrefs
import chat.simplex.common.platform.Log
import chat.simplex.common.platform.TAG
import chat.simplex.common.ui.theme.isInDarkTheme
import chat.simplex.common.views.helpers.AlertManager
import chat.simplex.common.views.helpers.generalGetString
import chat.simplex.res.MR
import dev.icerock.moko.resources.compose.painterResource
import dev.icerock.moko.resources.compose.stringResource
import java.awt.AWTException
import java.awt.SystemTray
import java.awt.TrayIcon
import java.awt.image.BufferedImage
// Probed once at startup. False on stock GNOME ≥ JDK 21.0.3 per JDK-8322750, and
// also when SystemTray.add() fails despite isSupported() returning true (an older
// JDK pattern Compose-MP does not catch). When false: the Appearance toggle is
// hidden, the first-close dialog is skipped (Ask migrates silently to Quit), and
// the close handler treats MinimizeToTray as Quit.
val trayIsAvailable: Boolean by lazy {
if (!SystemTray.isSupported()) return@lazy false
try {
val tray = SystemTray.getSystemTray()
val probe = TrayIcon(BufferedImage(1, 1, BufferedImage.TYPE_INT_ARGB))
tray.add(probe)
tray.remove(probe)
true
} catch (e: AWTException) {
Log.w(TAG, "SystemTray probe failed: ${e.stackTraceToString()}")
false
} catch (e: SecurityException) {
Log.w(TAG, "SystemTray probe denied: ${e.stackTraceToString()}")
false
}
}
fun showWindow() {
simplexWindowState.windowVisible.value = true
simplexWindowState.window?.toFront()
simplexWindowState.window?.requestFocus()
}
@Composable
fun ApplicationScope.SimplexTray() {
if (!trayIsAvailable) return
if (remember { appPrefs.closeBehavior.state }.value != CloseBehavior.MinimizeToTray) return
// Sum of per-profile unread (UserInfo.unreadCount, the same field UserPicker renders
// per row). Skip muted profiles unless they're the active one.
val unread by remember {
derivedStateOf {
ChatModel.users.sumOf {
if (!it.user.showNtfs && !it.user.activeUser) 0 else it.unreadCount
}
}
}
val iconRes = if (unread > 0) {
if (isInDarkTheme()) MR.images.ic_simplex_tray_dot_light else MR.images.ic_simplex_tray_dot
} else {
if (isInDarkTheme()) MR.images.ic_simplex_tray_light else MR.images.ic_simplex
}
val tooltip =
if (unread > 0) stringResource(MR.strings.tray_tooltip_unread, unread)
else stringResource(MR.strings.tray_tooltip)
Tray(
icon = painterResource(iconRes),
tooltip = tooltip,
onAction = ::showWindow,
menu = {
Item(stringResource(MR.strings.tray_show), onClick = ::showWindow)
Separator()
Item(stringResource(MR.strings.tray_quit), onClick = { exitApplication() })
}
)
}
// Renders in the main app window via AlertManager (same surface as e.g. the link
// previews confirmation). Lambdas close over the calling ApplicationScope; if the
// app crashes while the dialog is open, the crash handler's alert replaces it, so
// stale closures never get clicked.
fun ApplicationScope.requestCloseBehavior() {
val pref = appPrefs.closeBehavior
AlertManager.shared.showAlertDialogButtonsColumn(
title = generalGetString(MR.strings.close_behavior_dialog_title),
text = AnnotatedString(generalGetString(MR.strings.close_behavior_dialog_text)),
buttons = {
Column {
SectionItemView({
AlertManager.shared.hideAlert()
pref.set(CloseBehavior.Quit)
exitApplication()
}) {
Text(
stringResource(MR.strings.close_behavior_dialog_close),
Modifier.fillMaxWidth(),
textAlign = TextAlign.Center,
color = Color.Red
)
}
SectionItemView({
AlertManager.shared.hideAlert()
pref.set(CloseBehavior.MinimizeToTray)
simplexWindowState.windowVisible.value = false
}) {
Text(
stringResource(MR.strings.close_behavior_dialog_minimize),
Modifier.fillMaxWidth(),
textAlign = TextAlign.Center,
color = MaterialTheme.colors.primary
)
}
}
}
)
}
apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/platform/PlatformTextField.desktop.kt
+2 -2
View File
@@ -86,8 +86,8 @@ actual fun PlatformTextField(
// Different padding here is for a text that is considered RTL with non-RTL locale set globally.
// In this case padding from right side should be bigger
val startEndPadding = if (cs.message.text.isEmpty() && showVoiceButton && isRtlByCharacters && isLtrGlobally) 95.dp else 50.dp
val startPadding = if (isRtlByCharacters && isLtrGlobally) startEndPadding else 0.dp
val endPadding = if (isRtlByCharacters && isLtrGlobally) 0.dp else startEndPadding
val startPadding = 0.dp
val endPadding = startEndPadding
val padding = PaddingValues(startPadding, 12.dp, endPadding, 0.dp)
var textFieldValueState by remember { mutableStateOf(TextFieldValue(text = cs.message.text, selection = cs.message.selection)) }
val textFieldValue = textFieldValueState.copy(text = cs.message.text, selection = cs.message.selection)
apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt
+22 -13
View File
@@ -17,6 +17,7 @@ import org.nanohttpd.protocols.http.response.Response.newFixedLengthResponse
import org.nanohttpd.protocols.http.response.Status
import org.nanohttpd.protocols.websockets.*
import java.io.IOException
import java.net.BindException
import java.net.URI
private const val SERVER_HOST = "localhost"
@@ -157,17 +158,18 @@ fun WebRTCController(callCommand: SnapshotStateList<WCallCommand>, onResponse: (
if (call != null) withBGApi { chatModel.callManager.endCall(call) }
}
val server = remember {
try {
uriHandler.openUri("http://${SERVER_HOST}:$SERVER_PORT/simplex/call/")
} catch (e: Exception) {
Log.e(TAG, "Unable to open browser: ${e.stackTraceToString()}")
AlertManager.shared.showAlertMsg(
title = generalGetString(MR.strings.unable_to_open_browser_title),
text = generalGetString(MR.strings.unable_to_open_browser_desc)
)
endCall()
startServer(onResponse).apply {
try {
uriHandler.openUri("http://${SERVER_HOST}:${listeningPort}/simplex/call/")
} catch (e: Exception) {
Log.e(TAG, "Unable to open browser: ${e.stackTraceToString()}")
AlertManager.shared.showAlertMsg(
title = generalGetString(MR.strings.unable_to_open_browser_title),
text = generalGetString(MR.strings.unable_to_open_browser_desc)
)
endCall()
}
}
startServer(onResponse)
}
fun processCommand(cmd: WCallCommand) {
val apiCall = WVAPICall(command = cmd)
@@ -206,8 +208,8 @@ fun WebRTCController(callCommand: SnapshotStateList<WCallCommand>, onResponse: (
}
}
fun startServer(onResponse: (WVAPIMessage) -> Unit): NanoWSD {
val server = object: NanoWSD(SERVER_HOST, SERVER_PORT) {
fun startServer(onResponse: (WVAPIMessage) -> Unit, port: Int = SERVER_PORT): NanoWSD {
val server = object: NanoWSD(SERVER_HOST, port) {
override fun openWebSocket(session: IHTTPSession): WebSocket = MyWebSocket(onResponse, session)
fun resourcesToResponse(path: String): Response {
@@ -231,7 +233,14 @@ fun startServer(onResponse: (WVAPIMessage) -> Unit): NanoWSD {
}
}
}
server.start(60_000_000)
try {
server.start(60_000_000)
} catch (e: BindException) {
if (port == 0) throw e
Log.w(TAG, "Call server port $port is busy, using a random port: ${e.message}")
server.stop()
return startServer(onResponse, port = 0)
}
return server
}
apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/views/usersettings/Appearance.desktop.kt
+23
View File
@@ -3,6 +3,7 @@ package chat.simplex.common.views.usersettings
import SectionBottomSpacer
import SectionDividerSpaced
import SectionSpacer
import SectionTextFooter
import SectionView
import androidx.compose.foundation.*
import androidx.compose.foundation.layout.*
@@ -18,7 +19,9 @@ import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.*
import chat.simplex.common.model.ChatController.appPrefs
import chat.simplex.common.model.ChatModel
import chat.simplex.common.model.CloseBehavior
import chat.simplex.common.model.SharedPreference
import chat.simplex.common.trayIsAvailable
import chat.simplex.common.platform.*
import chat.simplex.common.ui.theme.DEFAULT_PADDING
import chat.simplex.common.views.helpers.*
@@ -65,6 +68,11 @@ fun AppearanceScope.AppearanceLayout(
SectionDividerSpaced()
ThemesSection(systemDarkTheme)
if (trayIsAvailable) {
SectionDividerSpaced()
MinimizeToTraySection()
}
SectionDividerSpaced()
AppToolbarsSection()
@@ -84,6 +92,21 @@ fun AppearanceScope.AppearanceLayout(
}
}
@Composable
private fun MinimizeToTraySection() {
val pref = remember { appPrefs.closeBehavior.state }
val on = pref.value == CloseBehavior.MinimizeToTray
SectionView {
PreferenceToggle(
stringResource(MR.strings.appearance_minimize_to_tray),
checked = on,
) { checked ->
appPrefs.closeBehavior.set(if (checked) CloseBehavior.MinimizeToTray else CloseBehavior.Quit)
}
}
SectionTextFooter(stringResource(MR.strings.appearance_minimize_to_tray_desc))
}
@Composable
fun DensityScaleSection() {
val localDensityScale = remember { mutableStateOf(appPrefs.densityScale.get()) }
apps/multiplatform/spec/services/calls.md
+2 -2
View File
@@ -119,9 +119,9 @@ The `actual` platform implementation of `ActiveCallView()` and supporting compos
Desktop calls run WebRTC in the system browser, not an embedded WebView:
- **NanoWSD server** ([line 209](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L209)): `startServer()` creates a `NanoWSD` instance bound to `localhost:50395`. The server serves `call.html` from JAR resources at `/assets/www/desktop/call.html` for the path `/simplex/call/`. All other paths serve resources from `/assets/www/`.
- **NanoWSD server** ([line 209](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L209)): `startServer()` creates a `NanoWSD` instance bound to `localhost:50395`. If that port is already in use it falls back to an OS-assigned free port (`port 0`); `WebRTCController` reads `server.listeningPort` for the browser URL. The server serves `call.html` from JAR resources at `/assets/www/desktop/call.html` for the path `/simplex/call/`. All other paths serve resources from `/assets/www/`.
- **WebSocket communication** ([line 238](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L238)): `MyWebSocket` handles WebSocket frames from the browser. `onMessage` deserializes JSON into `WVAPIMessage` and forwards to the response handler. `onClose` triggers `WCallResponse.End`.
- **WebRTCController** ([line 153](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L153)): Opens `http://localhost:50395/simplex/call/` via `LocalUriHandler`. Processes `WCallCommand` queue by sending JSON over WebSocket to all active connections. On dispose, sends `WCallCommand.End` and stops the server.
- **WebRTCController** ([line 153](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L153)): Starts the server, then opens `http://localhost:<listeningPort>/simplex/call/` (normally `50395`) via `LocalUriHandler`. Processes `WCallCommand` queue by sending JSON over WebSocket to all active connections. On dispose, sends `WCallCommand.End` and stops the server.
- **SendStateUpdates** ([line 137](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L137)): Sends `WCallCommand.Description` with call state and encryption info text to the browser for display.
- **ActiveCallView** ([line 28](../../common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt#L28)): Handles `WCallResponse` messages identically to Android (same state machine), plus a `WCallCommand.Permission` message on `Capabilities` error for browser permission denial guidance.
apps/simplex-support-bot/bot.test.ts
+204 -4
View File
@@ -1,9 +1,13 @@
import {describe, test, expect, beforeEach, vi} from "vitest"
import {mkdtempSync, writeFileSync} from "fs"
import {tmpdir} from "os"
import {join} from "path"
import {core} from "simplex-chat"
import {SupportBot} from "./src/bot.js"
import {CardManager} from "./src/cards.js"
import {parseConfig} from "./src/config.js"
import {GrokApiClient} from "./src/grok.js"
import {loadGrokContext} from "./src/context.js"
import {welcomeMessage, queueMessage, grokActivatedMessage, teamLockedMessage, teamAlreadyInvitedMessage} from "./src/messages.js"
// Silence console output during tests
@@ -212,13 +216,15 @@ const GROK_LOCAL_GROUP_ID = 200
const CUSTOMER_ID = "customer-1"
// Commands passed into SupportBot; matches what index.ts constructs when
// Grok is enabled. Tests that disable grokApi still pass the full list
// because the ctor doesn't care; the value is pushed to a group's
// groupPreferences on the first sendToGroup() call.
// Grok is enabled. The ctor uses this to decide which `/keyword` messages
// from customers are commands vs. plain text — tests that disable grokApi
// should pass a list that excludes "grok" to mirror production wiring (see
// index.ts where `grokEnabled` gates that entry).
const DESIRED_COMMANDS = [
{type: "command" as const, keyword: "grok", label: "Ask Grok"},
{type: "command" as const, keyword: "team", label: "Switch to team"},
]
const DESIRED_COMMANDS_NO_GROK = [DESIRED_COMMANDS[1]]
// ─── Member factories ───
@@ -729,6 +735,28 @@ describe("Grok Conversation", () => {
expect(grokApi.calls.length).toBe(0)
})
test("Grok answers messages containing a slash mid-word", async () => {
// Regression: an unanchored regex in ciBotCommand once parsed `/read`
// inside "follow/read" as a command, causing Grok to skip the message.
grokApi.willRespond("We post on X and Mastodon.")
await bot.onGrokNewChatItems(grokViewCustomerMessage(
"What social media do you use? Anything I can follow/read for updates?"
))
expect(grokApi.calls.length).toBe(1)
expect(grokApi.calls[0].message).toBe(
"What social media do you use? Anything I can follow/read for updates?"
)
})
test("Grok answers an unknown slash-prefixed message", async () => {
// `/help` is not in desiredCommands, so it should be treated as plain
// text and reach Grok rather than being silently dropped.
grokApi.willRespond("Sure, here's what I can do.")
await bot.onGrokNewChatItems(grokViewCustomerMessage("/help me with groups"))
expect(grokApi.calls.length).toBe(1)
expect(grokApi.calls[0].message).toBe("/help me with groups")
})
test("Grok per-message: history includes prior Grok sent response as assistant", async () => {
addCustomerMessageToHistory("How do I create a group?", GROK_LOCAL_GROUP_ID)
addBotMessage("To create a group, tap + then New Group.", GROK_LOCAL_GROUP_ID)
@@ -866,6 +894,52 @@ describe("Grok Conversation", () => {
})
})
describe("Grok requests /team", () => {
beforeEach(() => setup())
test("Grok per-message reply containing /team → team added, teamAddedMessage sent, reply still sent", async () => {
await reachGrok()
await bot.flush()
grokApi.willRespond("I can't help with billing — please send /team for a human.")
addCustomerMessageToHistory("Can you refund me?", GROK_LOCAL_GROUP_ID)
await bot.onGrokNewChatItems(grokViewCustomerMessage("Can you refund me?"))
expectAnySent("I can't help with billing")
expectMemberAdded(CUSTOMER_GROUP_ID, TEAM_MEMBER_1_ID)
expectMemberAdded(CUSTOMER_GROUP_ID, TEAM_MEMBER_2_ID)
expectSentToGroup(CUSTOMER_GROUP_ID, "We will reply within")
})
test("Grok per-message reply without /team → no team members added", async () => {
await reachGrok()
await bot.flush()
grokApi.willRespond("To create a group, tap +, then New Group.")
addCustomerMessageToHistory("How do I create a group?", GROK_LOCAL_GROUP_ID)
await bot.onGrokNewChatItems(grokViewCustomerMessage("How do I create a group?"))
expect(chat.added.some(a => a.groupId === CUSTOMER_GROUP_ID && a.contactId === TEAM_MEMBER_1_ID)).toBe(false)
})
test("/team in Grok's initial reply after /grok → escalates", async () => {
await reachQueue()
addBotMessage("The team will reply to your message")
// Customer's question visible in Grok's view → activateGrok reads it for the initial reply
chat.groups.set(GROK_LOCAL_GROUP_ID, makeGroupInfo(GROK_LOCAL_GROUP_ID))
addCustomerMessageToHistory("I'm really stuck, please help", GROK_LOCAL_GROUP_ID)
grokApi.willRespond("That sounds urgent — send /team to reach a person.")
const grokJoinPromise = simulateGrokJoinSuccess()
await bot.onNewChatItems(customerMessage("/grok"))
await grokJoinPromise
await bot.flush()
expectAnySent("That sounds urgent")
expectMemberAdded(CUSTOMER_GROUP_ID, TEAM_MEMBER_1_ID)
expectMemberAdded(CUSTOMER_GROUP_ID, TEAM_MEMBER_2_ID)
expectSentToGroup(CUSTOMER_GROUP_ID, "We will reply within")
})
})
describe("/team Activation", () => {
beforeEach(() => setup())
@@ -973,6 +1047,17 @@ describe("One-Way Gate with Grok Disabled", () => {
// Grok should not respond (grokApi is null)
expect(grokApi.calls.length).toBe(0)
})
test("Grok disabled: customer /grok is treated as text and queued", async () => {
// When Grok is disabled, index.ts excludes "grok" from desiredCommands,
// so /grok from a customer parses as an unknown command → routed as
// plain text → first-message-in-WELCOME transitions to QUEUE.
setup()
bot = new SupportBot(chat as any, null, config as any, MAIN_USER_ID, null, DESIRED_COMMANDS_NO_GROK)
bot.cards = cards
await bot.onNewChatItems(customerMessage("/grok"))
expectSentToGroup(CUSTOMER_GROUP_ID, "The team will reply to your message")
})
})
describe("Team Member Lifecycle", () => {
@@ -2427,7 +2512,7 @@ describe("GrokApiClient HTTP timeout", () => {
new Response(JSON.stringify({choices: [{message: {content: "ok"}}]}), {status: 200}),
)
const client = new GrokApiClient("test-key", "system prompt")
const client = new GrokApiClient("test-key", [{role: "system", content: "system prompt"}])
await client.chat([], "hello")
expect(timeoutSpy).toHaveBeenCalledWith(60_000)
@@ -2504,3 +2589,118 @@ describe("Command sync in sendToGroup", () => {
expect(prefs.reactions).toEqual({enable: "on"})
})
})
// loadGrokContext: documented behavior is "plain text → single system
// message". A `.yaml` / `.yml` extension is an undocumented alternative
// that parses the harness transcript format and surfaces only `system`
// and `assistant` turns; `user` entries are dropped so they don't merge
// with the customer's runtime message.
describe("loadGrokContext", () => {
const dir = mkdtempSync(join(tmpdir(), "support-bot-context-"))
const writeFile = (name: string, content: string): string => {
const p = join(dir, name)
writeFileSync(p, content)
return p
}
test("plain text (.txt) → single system message with full file content", () => {
const path = writeFile("ctx.txt", "You are Grok.\n\nBe concise.")
expect(loadGrokContext(path)).toEqual([
{role: "system", content: "You are Grok.\n\nBe concise."},
])
})
test("no extension → treated as plain text", () => {
const path = writeFile("plain", "raw context")
expect(loadGrokContext(path)).toEqual([{role: "system", content: "raw context"}])
})
test(".md → treated as plain text (does not look like YAML)", () => {
const path = writeFile("ctx.md", "# Heading\n\nbody")
expect(loadGrokContext(path)).toEqual([
{role: "system", content: "# Heading\n\nbody"},
])
})
test(".yaml → parses transcript and keeps only system + assistant turns", () => {
const path = writeFile("ctx.yaml",
"- role: system\n message: Be terse.\n" +
"- role: user\n message: What is async?\n" +
"- role: assistant\n message: Cooperative concurrency.\n",
)
expect(loadGrokContext(path)).toEqual([
{role: "system", content: "Be terse."},
{role: "assistant", content: "Cooperative concurrency."},
])
})
test(".yml extension also triggers YAML parsing", () => {
const path = writeFile("ctx.yml",
"- role: system\n message: hi\n",
)
expect(loadGrokContext(path)).toEqual([{role: "system", content: "hi"}])
})
test("YAML parsing is case-insensitive on extension", () => {
const path = writeFile("ctx.YAML",
"- role: system\n message: hi\n",
)
expect(loadGrokContext(path)).toEqual([{role: "system", content: "hi"}])
})
test("YAML preserves multi-line literal block scalars verbatim", () => {
const path = writeFile("multiline.yaml",
"- role: assistant\n message: |\n line one\n line two\n",
)
expect(loadGrokContext(path)).toEqual([
{role: "assistant", content: "line one\nline two\n"},
])
})
test("YAML with only user-role entries → empty array", () => {
const path = writeFile("only-user.yaml",
"- role: user\n message: a\n" +
"- role: user\n message: b\n",
)
expect(loadGrokContext(path)).toEqual([])
})
test("empty YAML file → empty array", () => {
const path = writeFile("empty.yaml", "")
expect(loadGrokContext(path)).toEqual([])
})
test("YAML non-list top level throws", () => {
const path = writeFile("not-list.yaml", "role: system\nmessage: x\n")
expect(() => loadGrokContext(path)).toThrow(/top-level must be a list/)
})
test("YAML entry with unknown role throws", () => {
const path = writeFile("bad-role.yaml", "- role: bogus\n message: x\n")
expect(() => loadGrokContext(path)).toThrow(/entry 0 has invalid role/)
})
test("YAML entry missing role throws", () => {
const path = writeFile("no-role.yaml", "- message: x\n")
expect(() => loadGrokContext(path)).toThrow(/entry 0 has invalid role/)
})
test("YAML entry with non-string message throws", () => {
const path = writeFile("bad-message.yaml", "- role: user\n message: 42\n")
expect(() => loadGrokContext(path)).toThrow(/entry 0 has non-string message/)
})
test("YAML entry that is not a mapping throws", () => {
const path = writeFile("bad-entry.yaml", "- just a string\n- role: user\n message: x\n")
expect(() => loadGrokContext(path)).toThrow(/entry 0 is not a mapping/)
})
test("malformed YAML throws", () => {
const path = writeFile("malformed.yaml", "- role: user\n message: [unclosed\n")
expect(() => loadGrokContext(path)).toThrow(/failed to parse YAML/)
})
test("missing file throws ENOENT", () => {
expect(() => loadGrokContext(join(dir, "does-not-exist.yaml"))).toThrow()
})
})
apps/simplex-support-bot/package-lock.json
Generated
+25 -9
View File
@@ -9,10 +9,11 @@
"version": "0.1.0",
"license": "AGPL-3.0",
"dependencies": {
"@simplex-chat/types": "^0.5.0",
"@simplex-chat/types": "^0.6.0",
"async-mutex": "^0.5.0",
"commander": "^14.0.3",
"simplex-chat": "^6.5.0"
"simplex-chat": "^6.5.1",
"yaml": "^2.8.4"
},
"devDependencies": {
"@types/node": "^22.0.0",
@@ -782,9 +783,9 @@
]
},
"node_modules/@simplex-chat/types": {
"version": "0.5.0",
"resolved": "https://registry.npmjs.org/@simplex-chat/types/-/types-0.5.0.tgz",
"integrity": "sha512-f680CRlf+O8WfIaPb7wxVj3PB8mTIOE+HqmetCSe0NBheVAjU3ovg3+zkrWwDlavrHuCLbb7Gmeu4HyNtjDfog==",
"version": "0.6.0",
"resolved": "https://registry.npmjs.org/@simplex-chat/types/-/types-0.6.0.tgz",
"integrity": "sha512-QVYvaRsS6TnS+IROjNkekZYvhvy8QoA8vKCuGe9E6lplXDVutJo9tdDOSWS9NDdtwxT1wRZ29zN4xEZEEG/NHw==",
"license": "AGPL-3.0",
"dependencies": {
"typescript": "^5.9.2"
@@ -1675,13 +1676,13 @@
}
},
"node_modules/simplex-chat": {
"version": "6.5.0",
"resolved": "https://registry.npmjs.org/simplex-chat/-/simplex-chat-6.5.0.tgz",
"integrity": "sha512-QFGI734HhYJ7trSrEKiZ2mbodI0V8CLDGEv2+yt5zsg0FqftxSpFik6zUSezTRZtN1M8WmSlT44qlEt2a1fXQw==",
"version": "6.5.1",
"resolved": "https://registry.npmjs.org/simplex-chat/-/simplex-chat-6.5.1.tgz",
"integrity": "sha512-1cv91iMCqtP+9R1PQM3NKazocoUInKT2/06pIOuzORD5/VzulR6cMZnEQmaT02Jz+8FVkEKTsaAIJfVP6/tJmw==",
"hasInstallScript": true,
"license": "AGPL-3.0",
"dependencies": {
"@simplex-chat/types": "^0.5.0",
"@simplex-chat/types": "^0.6.0",
"extract-zip": "^2.0.1",
"fast-deep-equal": "^3.1.3",
"node-addon-api": "^8.5.0"
@@ -1995,6 +1996,21 @@
"integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
"license": "ISC"
},
"node_modules/yaml": {
"version": "2.8.4",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.4.tgz",
"integrity": "sha512-ml/JPOj9fOQK8RNnWojA67GbZ0ApXAUlN2UQclwv2eVgTgn7O9gg9o7paZWKMp4g0H3nTLtS9LVzhkpOFIKzog==",
"license": "ISC",
"bin": {
"yaml": "bin.mjs"
},
"engines": {
"node": ">= 14.6"
},
"funding": {
"url": "https://github.com/sponsors/eemeli"
}
},
"node_modules/yauzl": {
"version": "2.10.0",
"resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
apps/simplex-support-bot/package.json
+2 -1
View File
@@ -11,7 +11,8 @@
"@simplex-chat/types": "^0.6.0",
"async-mutex": "^0.5.0",
"commander": "^14.0.3",
"simplex-chat": "^6.5.1"
"simplex-chat": "^6.5.1",
"yaml": "^2.8.4"
},
"devDependencies": {
"@types/node": "^22.0.0",
apps/simplex-support-bot/src/bot.ts
+38 -7
View File
@@ -10,6 +10,22 @@ import {
} from "./messages.js"
import {profileMutex, log, logError, getGroupInfo} from "./util.js"
// Collects the keyword of every "command" entry in the bot's registered
// commands tree, descending into "menu" entries. Used to distinguish real
// commands from arbitrary text that happens to start with `/` (e.g. URLs,
// "/help" the user invented).
function commandKeywords(commands: T.ChatBotCommand[]): Set<string> {
const out = new Set<string>()
const visit = (cmds: T.ChatBotCommand[]): void => {
for (const c of cmds) {
if (c.type === "command") out.add(c.keyword)
else if (c.type === "menu") visit(c.commands)
}
}
visit(commands)
return out
}
// True for any non-terminal status — invited but not yet accepted, through
// connected. Used to decide whether a contact is already in the group so we
// don't trigger a re-invite (the SimpleX API resends the invitation for a
@@ -62,6 +78,11 @@ export class SupportBot {
// send to each group.
private syncedGroups = new Set<number>()
// Keywords from desiredCommands. A customer message is treated as a
// command only when its parsed keyword is in this set; anything else
// (URLs, "/help", arbitrary slashes) is routed as plain text.
private readonly customerKeywords: ReadonlySet<string>
constructor(
private chat: api.ChatApi,
private grokApi: GrokApiClient | null,
@@ -71,6 +92,12 @@ export class SupportBot {
private desiredCommands: T.ChatBotCommand[],
) {
this.cards = new CardManager(chat, config, mainUserId, config.cardFlushSeconds * 1000)
this.customerKeywords = commandKeywords(desiredCommands)
}
private customerCommand(chatItem: T.ChatItem): util.BotCommand | undefined {
const cmd = util.ciBotCommand(chatItem)
return cmd && this.customerKeywords.has(cmd.keyword) ? cmd : undefined
}
private get grokEnabled(): boolean {
@@ -357,7 +384,7 @@ export class SupportBot {
if (chatInfo.type !== "group") continue
if (chatItem.chatDir.type !== "groupRcv") continue
if (!util.ciContentText(chatItem)?.trim()) continue
if (util.ciBotCommand(chatItem)) continue
if (this.customerCommand(chatItem)) continue
const bc = chatInfo.groupInfo.businessChat
if (!bc) continue
if (chatItem.chatDir.groupMember.memberId !== bc.customerId) continue
@@ -444,9 +471,7 @@ export class SupportBot {
// 8. Customer message → derive state and dispatch
const state = await this.cards.deriveState(groupId)
const rawCmd = util.ciBotCommand(chatItem)
// When Grok is disabled, ignore /grok so it behaves like an unknown command
const cmd = rawCmd?.keyword === "grok" && !this.grokEnabled ? null : rawCmd
const cmd = this.customerCommand(chatItem)
const text = util.ciContentText(chatItem)?.trim() || null
switch (state) {
@@ -547,7 +572,7 @@ export class SupportBot {
if (!text) return // ignore non-text
// Ignore bot commands
if (util.ciBotCommand(chatItem)) return
if (this.customerCommand(chatItem)) return
// Only respond in business groups (survives restart without in-memory maps)
const bc = groupInfo.businessChat
@@ -569,7 +594,7 @@ export class SupportBot {
history.push({role: "assistant", content: histText})
} else if (histCi.chatDir.type === "groupRcv"
&& histCi.chatDir.groupMember.memberId === bc.customerId
&& !util.ciBotCommand(histCi)) {
&& !this.customerCommand(histCi)) {
history.push({role: "user", content: histText})
}
}
@@ -587,6 +612,9 @@ export class SupportBot {
await this.withGrokProfile(() =>
this.chat.apiSendTextMessage([T.ChatType.Group, grokGroupId], response)
)
// Grok asked for the team → escalate as if the customer sent /team
if (mainGroupId !== undefined && response.includes("/team")) await this.activateTeam(mainGroupId)
} catch (err) {
logError(`Grok per-message error for grokGroup ${grokGroupId}`, err)
try {
@@ -706,7 +734,7 @@ export class SupportBot {
if (ci.chatDir.type !== "groupRcv") continue
if (!grokBc || ci.chatDir.groupMember.memberId !== grokBc.customerId) continue
const t = util.ciContentText(ci)?.trim()
if (t && !util.ciBotCommand(ci)) customerMessages.push(t)
if (t && !this.customerCommand(ci)) customerMessages.push(t)
}
if (customerMessages.length === 0) {
@@ -722,6 +750,9 @@ export class SupportBot {
await this.withGrokProfile(() =>
this.chat.apiSendTextMessage([T.ChatType.Group, grokLocalGId], response)
)
// Grok asked for the team → escalate as if the customer sent /team
if (response.includes("/team")) await this.activateTeam(groupId)
} catch (err) {
logError(`Grok initial response failed for group ${groupId}`, err)
await this.sendToGroup(groupId, grokUnavailableMessage)
apps/simplex-support-bot/src/context.ts
+59
View File
@@ -0,0 +1,59 @@
import {readFileSync} from "fs"
import {parse as parseYaml} from "yaml"
import {GrokMessage} from "./grok.js"
const ALLOWED_ROLES: ReadonlySet<GrokMessage["role"]> = new Set(["system", "user", "assistant"])
// Roles surfaced from a YAML transcript. `user` entries from the file are
// validated but dropped — the customer's runtime message is the only
// `user` content sent to Grok.
const PREPEND_ROLES: ReadonlySet<GrokMessage["role"]> = new Set(["system", "assistant"])
// Loads --context-file. The flag is documented as "text file with Grok
// system context"; a `.yaml` / `.yml` extension is an undocumented
// alternative that switches to a multi-turn transcript in the harness
// format (a flat list of `{role, message}` entries).
export function loadGrokContext(path: string): GrokMessage[] {
const text = readFileSync(path, "utf-8")
return isYamlPath(path) ? parseYamlTranscript(path, text) : [{role: "system", content: text}]
}
function isYamlPath(path: string): boolean {
const lower = path.toLowerCase()
return lower.endsWith(".yaml") || lower.endsWith(".yml")
}
// Parses the harness transcript format. Returns only `system` and
// `assistant` turns; `user` entries are intentionally excluded so they
// don't merge with the customer's runtime message. Malformed YAML,
// unknown roles, or non-string messages throw — operator-supplied
// configuration should fail-fast at startup, not silently degrade.
function parseYamlTranscript(path: string, text: string): GrokMessage[] {
let raw: unknown
try {
raw = parseYaml(text)
} catch (e) {
throw new Error(`${path}: failed to parse YAML: ${(e as Error).message}`)
}
if (raw === null || raw === undefined) return []
if (!Array.isArray(raw)) {
throw new Error(`${path}: top-level must be a list, got ${typeof raw}`)
}
const context: GrokMessage[] = []
for (let i = 0; i < raw.length; i++) {
const entry = raw[i]
if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
throw new Error(`${path}: entry ${i} is not a mapping`)
}
const {role, message} = entry as {role?: unknown; message?: unknown}
if (typeof role !== "string" || !ALLOWED_ROLES.has(role as GrokMessage["role"])) {
throw new Error(`${path}: entry ${i} has invalid role: ${JSON.stringify(role)}`)
}
if (typeof message !== "string") {
throw new Error(`${path}: entry ${i} has non-string message`)
}
if (PREPEND_ROLES.has(role as GrokMessage["role"])) {
context.push({role: role as GrokMessage["role"], content: message})
}
}
return context
}
apps/simplex-support-bot/src/grok.ts
+6 -6
View File
@@ -7,11 +7,11 @@ export interface GrokMessage {
export class GrokApiClient {
private readonly apiKey: string
private readonly systemPrompt: string
private readonly initialContext: readonly GrokMessage[]
constructor(apiKey: string, systemPrompt: string) {
constructor(apiKey: string, initialContext: readonly GrokMessage[]) {
this.apiKey = apiKey
this.systemPrompt = systemPrompt
this.initialContext = initialContext
}
async chatRaw(messages: GrokMessage[]): Promise<string> {
@@ -22,7 +22,7 @@ export class GrokApiClient {
"Authorization": `Bearer ${this.apiKey}`,
},
body: JSON.stringify({
model: "grok-3-mini",
model: "grok-latest",
messages,
temperature: 0.3,
max_tokens: 1024,
@@ -45,9 +45,9 @@ export class GrokApiClient {
}
async chat(history: GrokMessage[], userMessage: string): Promise<string> {
log(`Grok API call: ${history.length} history msgs, user msg ${userMessage.length} chars`)
log(`Grok API call: ${this.initialContext.length} context msgs, ${history.length} history msgs, user msg ${userMessage.length} chars`)
return this.chatRaw([
{role: "system", content: this.systemPrompt},
...this.initialContext,
...history,
{role: "user", content: userMessage},
])
apps/simplex-support-bot/src/index.ts
+14 -7
View File
@@ -3,7 +3,8 @@ import {api, bot, util} from "simplex-chat"
import {T} from "@simplex-chat/types"
import {parseConfig} from "./config.js"
import {SupportBot} from "./bot.js"
import {GrokApiClient} from "./grok.js"
import {GrokApiClient, GrokMessage} from "./grok.js"
import {loadGrokContext} from "./context.js"
import {welcomeMessage} from "./messages.js"
import {profileMutex, log, logError, getGroupInfo, getContact} from "./util.js"
@@ -319,16 +320,22 @@ async function main(): Promise<void> {
// Load Grok context and build API client only if enabled
let grokApi: GrokApiClient | null = null
if (grokEnabled) {
let contextFile = ""
let initialContext: GrokMessage[] = []
if (config.contextFile) {
try {
contextFile = readFileSync(config.contextFile, "utf-8")
log(`Loaded Grok context: ${contextFile.length} chars from ${config.contextFile}`)
} catch {
log(`Warning: context file not found: ${config.contextFile}`)
initialContext = loadGrokContext(config.contextFile)
log(`Loaded Grok context: ${initialContext.length} message(s) from ${config.contextFile}`)
} catch (err) {
const e = err as NodeJS.ErrnoException
if (e.code === "ENOENT") {
log(`Warning: context file not found: ${config.contextFile}`)
} else {
logError(`Failed to load Grok context file ${config.contextFile}`, err)
throw err
}
}
}
grokApi = new GrokApiClient(config.grokApiKey!, contextFile)
grokApi = new GrokApiClient(config.grokApiKey!, initialContext)
}
// Create SupportBot
apps/simplex-support-bot/test/__mocks__/simplex-chat.js
+1 -1
View File
@@ -9,7 +9,7 @@ function ciContentText(chatItem) {
function ciBotCommand(chatItem) {
const text = ciContentText(chatItem)?.trim()
if (text) {
const r = text.match(/\/([^\s]+)(.*)/)
const r = text.match(/^\/([^\s]+)(.*)/)
if (r && r.length >= 3) return {keyword: r[1], params: r[2].trim()}
}
return undefined
bots/api/COMMANDS.md
+7 -7
View File
@@ -295,7 +295,7 @@ Send messages.
```
```python
'/_send ' + str(sendRef) + (' live=on' if liveMessage else '') + ((' ttl=' + str(ttl)) if ttl is not None else '') + ' json ' + json.dumps(composedMessages) # Python
'/_send ' + ChatRef_cmd_string(sendRef) + (' live=on' if liveMessage else '') + ((' ttl=' + str(ttl)) if ttl is not None else '') + ' json ' + json.dumps(composedMessages) # Python
```
**Responses**:
@@ -335,7 +335,7 @@ Update message.
```
```python
'/_update item ' + str(chatRef) + ' ' + str(chatItemId) + (' live=on' if liveMessage else '') + ' json ' + json.dumps(updatedMessage) # Python
'/_update item ' + ChatRef_cmd_string(chatRef) + ' ' + str(chatItemId) + (' live=on' if liveMessage else '') + ' json ' + json.dumps(updatedMessage) # Python
```
**Responses**:
@@ -382,7 +382,7 @@ Delete message.
```
```python
'/_delete item ' + str(chatRef) + ' ' + ','.join(map(str, chatItemIds)) + ' ' + str(deleteMode) # Python
'/_delete item ' + ChatRef_cmd_string(chatRef) + ' ' + ','.join(map(str, chatItemIds)) + ' ' + str(deleteMode) # Python
```
**Responses**:
@@ -464,7 +464,7 @@ Add/remove message reaction.
```
```python
'/_reaction ' + str(chatRef) + ' ' + str(chatItemId) + ' ' + ('on' if add else 'off') + ' ' + json.dumps(reaction) # Python
'/_reaction ' + ChatRef_cmd_string(chatRef) + ' ' + str(chatItemId) + ' ' + ('on' if add else 'off') + ' ' + json.dumps(reaction) # Python
```
**Responses**:
@@ -1386,7 +1386,7 @@ Connect via prepared SimpleX link. The link can be 1-time invitation link, conta
```
```python
'/_connect ' + str(userId) + ((' ' + str(preparedLink_)) if preparedLink_ is not None else '') # Python
'/_connect ' + str(userId) + ((' ' + CreatedConnLink_cmd_string(preparedLink_)) if preparedLink_ is not None else '') # Python
```
**Responses**:
@@ -1644,7 +1644,7 @@ Get chat previews. Supports time-based pagination — use this instead of APILis
```
```python
'/_get chats ' + str(userId) + (' pcc=on' if pendingConnections else '') + ' ' + str(pagination) + ' ' + json.dumps(query) # Python
'/_get chats ' + str(userId) + (' pcc=on' if pendingConnections else '') + ' ' + PaginationByTime_cmd_string(pagination) + ' ' + json.dumps(query) # Python
```
**Responses**:
@@ -1682,7 +1682,7 @@ Delete chat.
```
```python
'/_delete ' + str(chatRef) + ' ' + str(chatDeleteMode) # Python
'/_delete ' + ChatRef_cmd_string(chatRef) + ' ' + ChatDeleteMode_cmd_string(chatDeleteMode) # Python
```
**Responses**:
bots/api/TYPES.md
+1 -1
View File
@@ -1376,7 +1376,7 @@ ChatType.cmdString(chatType) + chatId + (chatScope ? GroupChatScope.cmdString(ch
```
```python
str(chatType) + str(chatId) + ((str(chatScope)) if chatScope is not None else '') # Python
ChatType_cmd_string(chatType) + str(chatId) + ((GroupChatScope_cmd_string(chatScope)) if chatScope is not None else '') # Python
```
bots/src/API/Docs/Commands.hs
+1
View File
@@ -134,6 +134,7 @@ chatCommandsDocsData =
( "Connection commands",
"These commands may be used to create connections. Most bots do not need to use them - bot users will connect via bot address with auto-accept enabled.",
[ ("APIAddContact", [], "Create 1-time invitation link.", ["CRInvitation", "CRChatCmdError"], [], Just UNInteractive, "/_connect " <> Param "userId" <> OnOffParam "incognito" "incognito" (Just False)),
-- `Maybe` in `connectionLink :: Maybe AConnectionLink` is used to signal link parsing error to the runtime (the handler returns CEInvalidConnReq on Nothing); it is NOT API-level optionality. The parameter is required from callers.
("APIConnectPlan", [], "Determine SimpleX link type and if the bot is already connected via this link.", ["CRConnectionPlan", "CRChatCmdError"], [], Just UNInteractive, "/_connect plan " <> Param "userId" <> " " <> Param "connectionLink"),
("APIConnect", [], "Connect via prepared SimpleX link. The link can be 1-time invitation link, contact address or group link.", ["CRSentConfirmation", "CRContactAlreadyExists", "CRSentInvitation", "CRChatCmdError"], [], Just UNInteractive, "/_connect " <> Param "userId" <> Optional "" (" " <> Param "$0") "preparedLink_"),
("Connect", [], "Connect via SimpleX link as string in the active user profile.", ["CRSentConfirmation", "CRContactAlreadyExists", "CRSentInvitation", "CRChatCmdError"], [], Just UNInteractive, "/connect" <> Optional "" (" " <> Param "$0") "connLink_"),
bots/src/API/Docs/Generate.hs
+1 -1
View File
@@ -74,7 +74,7 @@ syntaxText r syntax =
"\n**Syntax**:\n"
<> "\n```\n" <> docSyntaxText r syntax <> "\n```\n"
<> (if isConst syntax then "" else "\n```javascript\n" <> jsSyntaxText False "" r syntax <> " // JavaScript\n```\n")
<> (if isConst syntax then "" else "\n```python\n" <> pySyntaxText r syntax <> " # Python\n```\n")
<> (if isConst syntax then "" else "\n```python\n" <> pySyntaxText "" r syntax <> " # Python\n```\n")
camelToSpace :: String -> String
camelToSpace [] = []
bots/src/API/Docs/Generate/Python.hs
+322
View File
@@ -0,0 +1,322 @@
{-# LANGUAGE DuplicateRecordFields #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE NamedFieldPuns #-}
{-# LANGUAGE OverloadedStrings #-}
module API.Docs.Generate.Python where
import API.Docs.Commands
import API.Docs.Events
import API.Docs.Generate
import API.Docs.Responses
import API.Docs.Syntax
import API.Docs.Syntax.Types
import API.Docs.Types
import API.TypeInfo
import Data.Char (isAlphaNum, toUpper)
import qualified Data.List.NonEmpty as L
import Data.Text (Text)
import qualified Data.Text as T
commandsCodeFile :: FilePath
commandsCodeFile = "./packages/simplex-chat-python/src/simplex_chat/types/_commands.py"
responsesCodeFile :: FilePath
responsesCodeFile = "./packages/simplex-chat-python/src/simplex_chat/types/_responses.py"
eventsCodeFile :: FilePath
eventsCodeFile = "./packages/simplex-chat-python/src/simplex_chat/types/_events.py"
typesCodeFile :: FilePath
typesCodeFile = "./packages/simplex-chat-python/src/simplex_chat/types/_types.py"
-- | Replace dashes with underscores so Python identifiers stay valid.
pyIdent :: String -> Text
pyIdent = T.replace "-" "_" . T.pack
-- | Python class name for a union member tag.
pyConstrName :: String -> Text
pyConstrName = pyIdent . fstToUpper
commandsCodeText :: Text
commandsCodeText =
("# API Commands\n# " <> autoGenerated <> "\n")
<> "from __future__ import annotations\n"
<> "import json\n"
<> "from typing import NotRequired, TypedDict\n"
<> "from . import _types as T\n"
<> "from . import _responses as CR\n"
<> foldMap commandCatCode chatCommandsDocs
where
commandCatCode CCCategory {categoryName, categoryDescr, commands} =
(T.pack $ "\n# " <> categoryName <> "\n# " <> categoryDescr <> "\n")
<> foldMap commandCode commands
where
commandCode CCDoc {commandType = ATUnionMember tag params, commandDescr, syntax, responses, network} =
("\n# " <> commandDescr <> "\n")
<> ("# Network usage: " <> networkUsage network <> ".\n")
<> classDef
<> (if syntax == "" then "" else cmdStringFunc)
<> respAliasLine
where
constrName = T.pack $ fstToUpper tag
classDef =
("class " <> constrName <> "(TypedDict):\n")
<> bodyOrPass (fieldsCodePy " " "T." params)
<> "\n"
cmdStringFunc =
("\ndef " <> constrName <> "_cmd_string(self: " <> constrName <> ") -> str:\n")
<> " return " <> pySelfSyntaxText "T." (fstToUpper tag, params) syntax <> "\n"
respAliasLine =
"\n" <> constrName <> "_Response = " <> respUnion <> "\n"
respUnion = unionAliasRhs "" (responseRef . responseType) responses
responseRef (ATUnionMember rtag _) = "CR." <> pyConstrName rtag
responsesCodeText :: Text
responsesCodeText =
("# API Responses\n# " <> autoGenerated <> "\n")
<> pythonImports
<> unionTypeCodePy moduleMember "T." "ChatResponse" chatRespConstrs
where
chatRespConstrs = L.fromList $ map responseType chatResponsesDocs
eventsCodeText :: Text
eventsCodeText =
("# API Events\n# " <> autoGenerated <> "\n")
<> pythonImports
<> unionTypeCodePy moduleMember "T." "ChatEvent" chatEventConstrs
where
chatEventConstrs = L.fromList $ concatMap catEvents chatEventsDocs
catEvents CECategory {mainEvents, otherEvents} = map eventType $ mainEvents ++ otherEvents
typesCodeText :: Text
typesCodeText =
("# API Types\n# " <> autoGenerated <> "\n")
<> "from __future__ import annotations\n"
<> "from typing import Literal, NotRequired, TypedDict\n"
<> foldMap typeCode chatTypesDocs
where
typeCode ctd@CTDoc {typeDef = APITypeDef {typeName' = name, typeDef}, typeDescr} =
(if T.null typeDescr then "" else "\n# " <> typeDescr <> "\n")
<> typeDefCode
<> typeCmdStringCode ctd
where
name' = T.pack name
enumValue m = case name of
"ConnectionMode" -> map toUpper m
"FileProtocol" -> map toUpper m
_ -> m
typeDefCode = case typeDef of
ATDRecord fields ->
("\nclass " <> name' <> "(TypedDict):\n")
<> bodyOrPass (fieldsCodePy " " "" fields)
ATDEnum cs ->
"\n" <> name' <> " = Literal["
<> T.intercalate ", " (map (\m -> "\"" <> T.pack (enumValue m) <> "\"") $ L.toList cs)
<> "]\n"
ATDUnion cs -> unionTypeCodePy typeMember "" name cs
-- | For types with non-empty `typeSyntax`, emit a top-level
-- `<TypeName>_cmd_string(self: <TypeName>) -> str` helper that mirrors the
-- Choice/Param expression. Records access fields via `self['<name>']`;
-- enums and unions dispatch on `self` (a literal string) or `self['type']`
-- respectively. Required so generated `_commands.py` produces valid CLI
-- syntax for ChatRef/ChatType/ChatDeleteMode/GroupChatScope/PaginationByTime
-- params instead of stringifying the wire dict.
typeCmdStringCode :: CTDoc -> Text
typeCmdStringCode CTDoc {typeDef = td@APITypeDef {typeName' = name, typeDef}, typeSyntax}
| typeSyntax == "" = ""
| otherwise =
"\n\ndef " <> T.pack name <> "_cmd_string(self: " <> T.pack name <> ") -> str:\n"
<> " return " <> body <> ignore <> "\n"
where
body = pyTypeSyntaxText "" (name, fields) typeSyntax
-- Unions and enums use self/self['type'] to dispatch. Pyright cannot
-- narrow TypedDict access by string-literal key, so suppress per-branch
-- complaints with one ignore on the return.
ignore = case typeDef of
ATDUnion _ -> " # type: ignore[typeddict-item]"
_ -> ""
-- typeFields mirrors TS funcCode: include `self` so Choice "self"
-- resolves; for unions add `type` and flatten member fields.
self = APIRecordField "self" (ATDef td)
fields = case typeDef of
ATDRecord fs -> fs
ATDUnion ms ->
self : APIRecordField "type" tagType : concatMap (\(ATUnionMember _ fs) -> fs) (L.toList ms)
where
tagType = ATDef $ APITypeDef (name <> ".type") $ ATDEnum tags
tags = L.map (\(ATUnionMember tag _) -> tag) ms
ATDEnum _ -> [self]
-- | Like `pySelfSyntaxText` but excludes `self` from the param-rewrite list
-- so `self == 'tag'` (enum dispatch) and `self['type']` (union dispatch)
-- survive verbatim. Used only for type-level cmd_string functions inside
-- @_types.py@, where peer type cmd_string calls don't need a namespace.
pyTypeSyntaxText :: String -> TypeAndFields -> Expr -> Text
pyTypeSyntaxText typeNamespace r expr =
rewriteParams accessors (pySyntaxText typeNamespace r expr)
where
accessors = filter ((/= "self") . fst) (paramAccessors r)
-- | Member class name within the multi-type @_types.py@ module: prefix the
-- tag with the union type name so members from different unions don't
-- collide.
typeMember :: String -> String -> Text
typeMember typeName tag = T.pack typeName <> "_" <> pyIdent tag
-- | Member class name within a single-union module (responses/events): just
-- the PascalCase tag, so commands can reference them as @CR.<Tag>@.
moduleMember :: String -> String -> Text
moduleMember _ tag = pyConstrName tag
-- | Common imports for the responses/events modules.
pythonImports :: Text
pythonImports =
"from __future__ import annotations\n"
<> "from typing import Literal, NotRequired, TypedDict\n"
<> "from . import _types as T\n"
-- | Render a tagged-union type: one TypedDict per member, plus union alias
-- and `<Name>_Tag` Literal alias. The member class names are produced by
-- @memberName@ given the union type name and the member tag.
unionTypeCodePy ::
(String -> String -> Text) ->
Text ->
String ->
L.NonEmpty ATUnionMember ->
Text
unionTypeCodePy memberName typesNamespace name cs =
foldMap memberClass (L.toList cs)
<> "\n" <> name' <> " = " <> unionAliasRhs name' constrTypeRef (L.toList cs)
<> "\n" <> name' <> "_Tag = Literal[" <> tagLiterals <> "]\n"
where
name' = T.pack name
constrTypeRef (ATUnionMember tag _) = memberName name tag
tagLiterals = T.intercalate ", " $ map (\(ATUnionMember tag _) -> "\"" <> T.pack tag <> "\"") $ L.toList cs
memberClass (ATUnionMember tag fields) =
("\nclass " <> memberName name tag <> "(TypedDict):\n")
<> (" type: Literal[\"" <> T.pack tag <> "\"]\n")
<> fieldsCodePy " " typesNamespace fields
-- | Render the right-hand side of a union alias: either inline (one line) or
-- multi-line wrapped in parentheses with `|` separators between alternatives.
unionAliasRhs :: Text -> (a -> Text) -> [a] -> Text
unionAliasRhs lhs constr cs
| T.length (lhs <> " = " <> oneLine) <= 100 = oneLine <> "\n"
| otherwise = "(\n" <> T.intercalate "\n" (map (" " <>) lines') <> "\n)\n"
where
oneLine = T.intercalate " | " cs'
lines' = case cs' of
[] -> []
(h : t) -> h : map ("| " <>) t
cs' = map constr cs
-- | Emit a body of `pass` if there are no fields, otherwise the rendered
-- fields as-is.
bodyOrPass :: Text -> Text
bodyOrPass body
| T.null body = " pass\n"
| otherwise = body
-- | Render record fields for a TypedDict body. Each field becomes
-- `<indent><name>: <type>[ # <comment>]`. Optional fields wrap the type in
-- `NotRequired[...]`.
fieldsCodePy :: Text -> Text -> [APIRecordField] -> Text
fieldsCodePy indent namespace = foldMap render
where
render (APIRecordField name t) =
indent <> T.pack name <> ": " <> wrapOptional t (typeText t) <> typeComment t <> "\n"
wrapOptional t inner = case t of
ATOptional _ -> "NotRequired[" <> inner <> "]"
_ -> inner
typeText = \case
ATPrim (PT t) -> primName t
ATDef (APITypeDef t _) -> quoted (namespace <> T.pack t)
ATRef t -> quoted (namespace <> T.pack t)
ATOptional t -> typeText t
ATArray {elemType} -> "list[" <> typeText elemType <> "]"
ATMap (PT k) v -> "dict[" <> primName k <> ", " <> typeText v <> "]"
primName = \case
TBool -> "bool"
TString -> "str"
TInt -> "int"
TInt64 -> "int"
TWord32 -> "int"
TDouble -> "float"
TJSONObject -> "dict[str, object]"
TUTCTime -> "str"
t -> T.pack t
quoted s = "\"" <> s <> "\""
typeComment t = let c = typeComment' t in if T.null c then "" else " # " <> c
typeComment' = \case
ATPrim (PT t) -> typeComment_ t
ATOptional inner -> typeComment' inner
ATArray {elemType, nonEmpty}
| nonEmpty -> if T.null c then "non-empty" else c <> ", non-empty"
| otherwise -> c
where
c = typeComment' elemType
ATMap (PT k) v ->
let kc = typeComment_ k
vc = typeComment' v
tc t c = if T.null c then t else c
in if T.null kc && T.null vc then "" else tc (primName k) kc <> " : " <> tc (typeText v) vc
_ -> ""
typeComment_ = \case
TInt -> "int"
TInt64 -> "int64"
TWord32 -> "word32"
TDouble -> "double"
TUTCTime -> "ISO-8601 timestamp"
_ -> ""
-- | Wrap `pySyntaxText` so each parameter access uses `self['<name>']`. The
-- output of `pySyntaxText` references params as bare Python identifiers
-- (e.g. `str(userId)`); we rewrite those identifiers — but only outside
-- string literals — into TypedDict subscript accesses. The
-- @typeNamespace@ is prepended to any `<TypeName>_cmd_string(...)` calls
-- emitted for params whose type has its own syntax (e.g. @"T."@ from
-- @_commands.py@, or @""@ from within @_types.py@).
--
-- Unlike the JS variant, we do NOT collapse adjacent string literals via
-- `T.replace "' + '" ""`: that pattern incorrectly matches `' ' + ','`
-- (the space-then-comma sequence between a literal and `','.join(...)`),
-- producing `' ,'.join(...)` which uses ` ,` as the join separator and
-- swallows the leading space. The `intercalate " + "` output is correct
-- without further string fixups.
pySelfSyntaxText :: String -> TypeAndFields -> Expr -> Text
pySelfSyntaxText typeNamespace r expr =
rewriteParams (paramAccessors r) (pySyntaxText typeNamespace r expr)
-- | Map field name to the Python access expression: `self['<name>']` for
-- required fields, `self.get('<name>')` for optional ones (since
-- TypedDict's `NotRequired` allows the key to be absent and `[...]` would
-- raise `KeyError`). Used by the rewriter so the same name is substituted
-- consistently in Optional `is not None` checks and in the value position.
paramAccessors :: TypeAndFields -> [(String, String)]
paramAccessors (_, fields) = map mk fields
where
mk (APIRecordField n t) = (n, accessor n t)
accessor n = \case
ATOptional _ -> "self.get('" ++ n ++ "')"
_ -> "self['" ++ n ++ "']"
-- | Replace bare identifiers (matching a key in @accessors@) with the
-- corresponding accessor expression, skipping characters inside
-- single-quoted string literals and respecting identifier word boundaries.
rewriteParams :: [(String, String)] -> Text -> Text
rewriteParams accessors = T.pack . go False . T.unpack
where
go _ [] = []
-- Toggle in/out of single-quoted string on every unescaped quote.
go inStr ('\'' : rest) = '\'' : go (not inStr) rest
go True (c : rest) = c : go True rest
go False s@(c : rest)
| isIdentStart c = case takeIdent s of
(ident, after) -> case lookup ident accessors of
Just expr -> expr ++ go False after
Nothing -> ident ++ go False after
| otherwise = c : go False rest
isIdentStart c = isAlphaNum c || c == '_'
takeIdent = span (\c -> isAlphaNum c || c == '_')
bots/src/API/Docs/Syntax.hs
+8 -2
View File
@@ -157,8 +157,8 @@ escapeChar c s
| c `elem` s = concatMap (\c' -> if c' == c then ['\\', c] else [c]) s
| otherwise = s
pySyntaxText :: TypeAndFields -> Expr -> Text
pySyntaxText r = T.pack . go Nothing True
pySyntaxText :: String -> TypeAndFields -> Expr -> Text
pySyntaxText typeNamespace r = T.pack . go Nothing True
where
go param top = \case
Concat exs -> intercalate " + " $ map (go param False) $ L.toList exs
@@ -167,7 +167,13 @@ pySyntaxText r = T.pack . go Nothing True
withParamType r param p $ \case
ATPrim (PT TString) -> paramName param p
ATOptional (ATPrim (PT TString)) -> paramName param p
ATDef td -> toStringSyntax td
ATOptional (ATDef td) -> toStringSyntax td
_ -> "str(" <> paramName param p <> ")"
where
toStringSyntax (APITypeDef typeName _)
| typeHasSyntax typeName = typeNamespace <> typeName <> "_cmd_string(" <> paramName param p <> ")"
| otherwise = "str(" <> paramName param p <> ")"
Optional exN exJ p -> open <> "(" <> go (Just p) False exJ <> ") if " <> n <> " is not None else " <> nothing <> close
where
n = paramName param p
docs/protocol/channels-protocol.md
+16
View File
@@ -9,6 +9,7 @@ For architecture, design rationale, security properties, and threat model, see [
- [Protocol](#protocol)
- [Channel creation](#channel-creation)
- [Relay acceptance](#relay-acceptance)
- [Relay addition](#relay-addition)
- [Subscriber connection](#subscriber-connection)
- [Message signing](#message-signing)
- [Message forwarding](#message-forwarding)
@@ -57,6 +58,20 @@ When a relay receives an invitation to serve a channel, it validates the channel
TODO: Periodic monitoring where the relay retrieves channel link data to verify its relay link is still listed is planned but not yet implemented.
### Relay addition
When the owner adds a relay to an existing channel:
1. **Acceptance.** The new relay accepts the invitation following the [Relay acceptance](#relay-acceptance) flow. The owner promotes the relay to active when the channel link's updated relay list is confirmed.
2. **Announce.** If the channel has at least one subscriber, the owner sends `x.grp.relay.new` (carrying the new relay's short link) to every other currently-connected relay of the channel.
3. **Forward.** Each relay forwards `x.grp.relay.new` to its subscribers. The relay does not create a member record for the announced relay — relays do not connect to other relays of the same channel.
4. **Connect.** On receipt, the subscriber resolves the announced short link and connects to the new relay asynchronously.
The announce is an optimisation. When it does not reach a subscriber — because the channel had no subscribers at announce time, because an older client or relay sits in the path, or because of a transient network failure — the subscriber reaches the same end state on the next channel open via its relay sync against the channel's link data.
### Subscriber connection
A subscriber joins a channel through the following flow:
@@ -89,6 +104,7 @@ Messages that alter the channel's roster, profile, or administrative state are c
| `x.grp.mem.del` | Remove member | Required |
| `x.grp.mem.role` | Change member role | Required |
| `x.grp.mem.restrict` | Restrict member | Required |
| `x.grp.relay.new` | Announce new relay to subscribers | Required |
| `x.grp.leave` | Leave channel | Required (unverified allowed between subscribers) |
| `x.info` | Update member profile | Required (unverified allowed between subscribers) |
| `x.msg.new` | Content message | Not signed |
packages/simplex-chat-nodejs/src/util.ts
+1 -1
View File
@@ -78,7 +78,7 @@ export interface BotCommand {
export function ciBotCommand(chatItem: T.ChatItem): BotCommand | undefined {
const msg = ciContentText(chatItem)?.trim()
if (msg) {
const r = msg.match(/\/([^\s]+)(.*)/)
const r = msg.match(/^\/([^\s]+)(.*)/)
if (r && r.length >= 3) {
return {keyword: r[1], params: r[2].trim()}
}
packages/simplex-chat-nodejs/tests/util.test.ts
+37
View File
@@ -0,0 +1,37 @@
import {T} from "@simplex-chat/types"
import {ciBotCommand} from "../src/util"
function rcvText(text: string): T.ChatItem {
return {content: {type: "rcvMsgContent", msgContent: {type: "text", text}}} as T.ChatItem
}
describe("ciBotCommand", () => {
it("parses a command at the start of the message", () => {
expect(ciBotCommand(rcvText("/grok hello"))).toEqual({keyword: "grok", params: "hello"})
})
it("returns undefined for a slash in the middle of a word", () => {
expect(ciBotCommand(rcvText("What follow/read blog posts?"))).toBeUndefined()
})
it("returns undefined for a slash after a space", () => {
expect(ciBotCommand(rcvText("see /home for details"))).toBeUndefined()
})
it("strips leading whitespace before matching", () => {
expect(ciBotCommand(rcvText(" /grok ask this"))).toEqual({keyword: "grok", params: "ask this"})
})
it("returns command with empty params when only the keyword is present", () => {
expect(ciBotCommand(rcvText("/team"))).toEqual({keyword: "team", params: ""})
})
it("returns undefined for plain text without slash", () => {
expect(ciBotCommand(rcvText("hello there"))).toBeUndefined()
})
it("returns undefined for non-text chat item content", () => {
const ci = {content: {type: "rcvDeleted"}} as T.ChatItem
expect(ciBotCommand(ci)).toBeUndefined()
})
})
packages/simplex-chat-python/.gitignore
+22
View File
@@ -0,0 +1,22 @@
# Python build / cache artifacts — never commit these
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
build/
dist/
.pytest_cache/
.ruff_cache/
.mypy_cache/
.pyright_cache/
# Virtual environments
.venv/
.venv-*/
venv/
# Lazy-downloaded native libs (handled at runtime by _native._resolve_libs_dir)
libs/
# Local override for SIMPLEX_LIBS_DIR work, etc.
.env
packages/simplex-chat-python/LICENSE
+661
View File
@@ -0,0 +1,661 @@
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU Affero General Public License is a free, copyleft license for
software and other kinds of works, specifically designed to ensure
cooperation with the community in the case of network server software.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
our General Public Licenses are intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
Developers that use our General Public Licenses protect your rights
with two steps: (1) assert copyright on the software, and (2) offer
you this License which gives you legal permission to copy, distribute
and/or modify the software.
A secondary benefit of defending all users' freedom is that
improvements made in alternate versions of the program, if they
receive widespread use, become available for other developers to
incorporate. Many developers of free software are heartened and
encouraged by the resulting cooperation. However, in the case of
software used on network servers, this result may fail to come about.
The GNU General Public License permits making a modified version and
letting the public access it on a server without ever releasing its
source code to the public.
The GNU Affero General Public License is designed specifically to
ensure that, in such cases, the modified source code becomes available
to the community. It requires the operator of a network server to
provide the source code of the modified version running there to the
users of that server. Therefore, public use of a modified version, on
a publicly accessible server, gives the public access to the source
code of the modified version.
An older license, called the Affero General Public License and
published by Affero, was designed to accomplish similar goals. This is
a different license, not a version of the Affero GPL, but Affero has
released a new version of the Affero GPL which permits relicensing under
this license.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU Affero General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Remote Network Interaction; Use with the GNU General Public License.
Notwithstanding any other provision of this License, if you modify the
Program, your modified version must prominently offer all users
interacting with it remotely through a computer network (if your version
supports such interaction) an opportunity to receive the Corresponding
Source of your version by providing access to the Corresponding Source
from a network server at no charge, through some standard or customary
means of facilitating copying of software. This Corresponding Source
shall include the Corresponding Source for any work covered by version 3
of the GNU General Public License that is incorporated pursuant to the
following paragraph.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the work with which it is combined will remain governed by version
3 of the GNU General Public License.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU Affero General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU Affero General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU Affero General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU Affero General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If your software can interact with users remotely through a computer
network, you should also make sure that it provides a way for users to
get its source. For example, if your program is a web application, its
interface could display a "Source" link that leads users to an archive
of the code. There are many ways you could offer source, and different
solutions will be better for different programs; see section 13 for the
specific requirements.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU AGPL, see
<https://www.gnu.org/licenses/>.
packages/simplex-chat-python/README.md
+70
View File
@@ -0,0 +1,70 @@
# SimpleX Chat Python library
Python 3.11+ client for [SimpleX Chat](https://simplex.chat) bots. Equivalent to the [Node.js library](https://www.npmjs.com/package/simplex-chat).
## Install
```bash
pip install simplex-chat
```
The native `libsimplex` is downloaded lazily on first use. To pre-fetch:
```bash
python -m simplex_chat install # sqlite (default)
python -m simplex_chat install --backend postgres # linux-x86_64 only
```
## Quick start
```python
import re
from simplex_chat import Bot, BotProfile, Message, SqliteDb, TextMessage
bot = Bot(
profile=BotProfile(display_name="Squaring bot"),
db=SqliteDb(file_prefix="./squaring_bot"),
welcome="Send me a number, I'll square it.",
)
@bot.on_message(content_type="text", text=re.compile(r"^-?\d+(\.\d+)?$"))
async def square(msg: TextMessage) -> None:
n = float(msg.text or "0")
await msg.reply(f"{n} * {n} = {n * n}")
@bot.on_message(content_type="text")
async def fallback(msg: Message) -> None:
await msg.reply("Send me a number, like 7 or 3.14.")
if __name__ == "__main__":
bot.run()
```
`bot.run()` blocks. The connection address is logged on startup — paste it into a SimpleX client to talk to the bot. `Ctrl+C` to stop.
Three decorators: `@bot.on_message(...)`, `@bot.on_command(name)`, `@bot.on_event(tag)`. Message handlers are first-match-wins in registration order, so register specific filters first and catch-alls last.
See [`examples/squaring_bot.py`](./examples/squaring_bot.py) for the full example.
## Development
```bash
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'
ruff check && pyright && pytest tests/
```
Wire types under `src/simplex_chat/types/_*.py` are generated. Regenerate with `cabal test simplex-chat-test --test-options='--match Python'`.
## Release
Manual for now. Bump `_version.py:__version__`, build a wheel, upload to PyPI:
```bash
uv build --wheel
uv publish --token "$PYPI_TOKEN"
```
## License
[AGPL-3.0](./LICENSE)
packages/simplex-chat-python/examples/squaring_bot.py
+52
View File
@@ -0,0 +1,52 @@
"""Squaring bot — replies to every number with its square.
Run with the simplex-chat package installed:
python examples/squaring_bot.py
Sends `n * n = ...` for any text message that parses as a number; falls
back to a hint for non-number messages; responds to `/help` with usage.
"""
from __future__ import annotations
import re
from simplex_chat import (
Bot,
BotCommand,
BotProfile,
Message,
ParsedCommand,
SqliteDb,
TextMessage,
)
bot = Bot(
profile=BotProfile(display_name="Squaring bot"),
db=SqliteDb(file_prefix="./squaring_bot"),
welcome="Send me a number, I'll square it.",
commands=[BotCommand(keyword="help", label="Show help")],
)
NUMBER_RE = re.compile(r"^-?\d+(\.\d+)?$")
@bot.on_message(content_type="text", text=NUMBER_RE)
async def square(msg: TextMessage) -> None:
n = float(msg.text or "0")
await msg.reply(f"{n} * {n} = {n * n}")
@bot.on_message(content_type="text")
async def fallback(msg: Message) -> None:
await msg.reply("Send me a number, like 7 or 3.14.")
@bot.on_command("help")
async def help_cmd(msg: Message, _cmd: ParsedCommand) -> None:
await msg.reply("Send a number, I'll square it.")
if __name__ == "__main__":
bot.run()
packages/simplex-chat-python/pyproject.toml
+58
View File
@@ -0,0 +1,58 @@
[build-system]
requires = ["hatchling>=1.24"]
build-backend = "hatchling.build"
[project]
name = "simplex-chat"
description = "SimpleX Chat Python library for chat bots"
readme = "README.md"
license = "AGPL-3.0-only"
authors = [{name = "SimpleX Chat"}]
requires-python = ">=3.11"
keywords = ["simplex", "messenger", "chat", "privacy", "security", "bots"]
classifiers = [
"Development Status :: 4 - Beta",
"License :: OSI Approved :: GNU Affero General Public License v3",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Topic :: Communications :: Chat",
]
dynamic = ["version"]
[project.urls]
Homepage = "https://github.com/simplex-chat/simplex-chat/tree/stable/packages/simplex-chat-python"
Issues = "https://github.com/simplex-chat/simplex-chat/issues"
[project.optional-dependencies]
test = ["pytest>=8", "pytest-asyncio>=0.23"]
dev = ["pytest>=8", "pytest-asyncio>=0.23", "pyright>=1.1.380", "ruff>=0.6"]
[tool.hatch.version]
path = "src/simplex_chat/_version.py"
[tool.hatch.build.targets.wheel]
packages = ["src/simplex_chat"]
[tool.pytest.ini_options]
asyncio_mode = "auto"
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.format]
# `src/simplex_chat/types/*.py` are generated by the Haskell codegen
# (bots/src/API/Docs/Generate/Python.hs). Re-formatting them locally
# would diverge from the generator's output and break `cabal test
# simplex-chat-test --match Python`. Lint still applies — only format
# is suppressed.
exclude = ["src/simplex_chat/types/_*.py"]
[tool.pyright]
# Same rationale: the generated cmd_string helpers use `self.get('x')`
# call pairs that pyright cannot narrow across (`is not None` followed
# by re-access). Hand-written code is still strictly checked.
include = ["src/simplex_chat"]
exclude = ["src/simplex_chat/types/_*.py", "**/__pycache__", "**/.venv*"]
packages/simplex-chat-python/src/simplex_chat/__init__.py
+59
View File
@@ -0,0 +1,59 @@
"""SimpleX Chat — Python client library for chat bots."""
from ._version import __version__
from .api import ChatApi, ChatCommandError, ConnReqType, Db, PostgresDb, SqliteDb
from .bot import (
Bot,
BotCommand,
BotProfile,
ChatMessage,
CommandHandler,
EventHandler,
FileMessage,
ImageMessage,
LinkMessage,
Message,
MessageHandler,
Middleware,
ParsedCommand,
ReportMessage,
TextMessage,
UnknownMessage,
VideoMessage,
VoiceMessage,
)
from .core import ChatAPIError, ChatInitError, CryptoArgs, MigrationConfirmation
from . import util as util # re-export the util namespace
__all__ = [
"__version__",
"Bot",
"BotCommand",
"BotProfile",
"ChatAPIError",
"ChatApi",
"ChatCommandError",
"ChatInitError",
"ChatMessage",
"CommandHandler",
"ConnReqType",
"CryptoArgs",
"Db",
"EventHandler",
"FileMessage",
"ImageMessage",
"LinkMessage",
"Message",
"MessageHandler",
"Middleware",
"MigrationConfirmation",
"ParsedCommand",
"PostgresDb",
"ReportMessage",
"SqliteDb",
"TextMessage",
"UnknownMessage",
"VideoMessage",
"VoiceMessage",
"util",
]
packages/simplex-chat-python/src/simplex_chat/__main__.py
+35
View File
@@ -0,0 +1,35 @@
"""CLI: ``python -m simplex_chat install [--backend=sqlite|postgres]``."""
from __future__ import annotations
import argparse
import sys
from . import _native
def main(argv: list[str] | None = None) -> int:
p = argparse.ArgumentParser(prog="simplex_chat")
sub = p.add_subparsers(dest="command", required=True)
install = sub.add_parser("install", help="Pre-fetch libsimplex into the user cache")
install.add_argument(
"--backend",
choices=["sqlite", "postgres"],
default="sqlite",
help="which libsimplex variant to download (default: sqlite)",
)
args = p.parse_args(argv)
# `args.command` is always set: `add_subparsers(required=True)` makes
# argparse exit before reaching this point if no subcommand is given.
assert args.command == "install"
try:
path = _native._resolve_libs_dir(args.backend)
print(f"libsimplex installed at: {path}")
return 0
except Exception as e:
print(f"install failed: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
packages/simplex-chat-python/src/simplex_chat/_native.py
+257
View File
@@ -0,0 +1,257 @@
"""Native libsimplex loader: platform detection, lazy download, ctypes setup.
Internal — users interact with `Bot` / `ChatApi`, never with this module.
"""
from __future__ import annotations
import ctypes
import errno
import os
import platform
import sys
import tempfile
import threading
import urllib.request
import zipfile
from ctypes import POINTER, c_char_p, c_int, c_uint8, c_void_p
from pathlib import Path
from typing import Literal
from ._version import LIBS_VERSION
Backend = Literal["sqlite", "postgres"]
_GITHUB_REPO = "simplex-chat/simplex-chat-libs"
_PLATFORM_MAP = {
"linux": ("linux", {"x86_64": "x86_64", "aarch64": "aarch64"}),
"darwin": ("macos", {"x86_64": "x86_64", "arm64": "aarch64"}),
"win32": ("windows", {"AMD64": "x86_64", "x86_64": "x86_64"}),
}
_LIBNAME = {"linux": "libsimplex.so", "darwin": "libsimplex.dylib", "win32": "libsimplex.dll"}
SUPPORTED = (
"linux-x86_64",
"linux-aarch64",
"macos-x86_64",
"macos-aarch64",
"windows-x86_64",
)
def _platform_tag() -> str:
info = _PLATFORM_MAP.get(sys.platform)
if not info:
raise RuntimeError(f"Unsupported platform: {sys.platform}")
sysname, archs = info
arch = archs.get(platform.machine())
if not arch:
raise RuntimeError(f"Unsupported architecture: {sys.platform}/{platform.machine()}")
tag = f"{sysname}-{arch}"
if tag not in SUPPORTED:
raise RuntimeError(f"Unsupported combination: {tag}; supported: {SUPPORTED}")
return tag
def _libname() -> str:
return _LIBNAME[sys.platform]
def _libs_url(backend: Backend) -> str:
suffix = "-postgres" if backend == "postgres" else ""
return (
f"https://github.com/{_GITHUB_REPO}/releases/download/"
f"v{LIBS_VERSION}/simplex-chat-libs-{_platform_tag()}{suffix}.zip"
)
def _cache_root() -> Path:
if sys.platform == "darwin":
return Path.home() / "Library" / "Caches" / "simplex-chat"
if sys.platform == "win32":
return Path(os.environ["LOCALAPPDATA"]) / "simplex-chat"
base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
return Path(base) / "simplex-chat"
def _resolve_libs_dir(backend: Backend) -> Path:
if override := os.environ.get("SIMPLEX_LIBS_DIR"):
return Path(override)
if backend == "postgres" and _platform_tag() != "linux-x86_64":
raise RuntimeError(
"postgres backend is only supported on linux-x86_64; "
f"current platform is {_platform_tag()}"
)
target = _cache_root() / f"v{LIBS_VERSION}" / backend
if not (target / _libname()).exists():
_download(target, backend)
return target
_DOWNLOAD_CHUNK = 1 << 16 # 64 KiB
def _stream_to_file(url: str, dest: Path, *, timeout: float = 60.0) -> None:
"""Stream `url` → `dest`, printing a carriage-return progress bar.
`timeout` is per-request; we don't touch `socket.setdefaulttimeout`
so other socket users in the same process aren't affected.
"""
with urllib.request.urlopen(url, timeout=timeout) as resp: # noqa: S310 - https://github.com/...
total = int(resp.headers.get("Content-Length") or 0)
received = 0
with dest.open("wb") as out:
while chunk := resp.read(_DOWNLOAD_CHUNK):
out.write(chunk)
received += len(chunk)
if total > 0:
pct = min(100, received * 100 // total)
msg = f"\r download: {received >> 20} / {total >> 20} MiB ({pct}%)"
else:
msg = f"\r download: {received >> 20} MiB"
print(msg, end="", file=sys.stderr, flush=True)
print("", file=sys.stderr, flush=True) # newline after final progress line
def _download(target: Path, backend: Backend) -> None:
"""Download libs zip → atomic rename into `target`. Concurrent processes safe.
Atomicity strategy: each process extracts to its own sibling tempdir on the same
filesystem, then `os.rename` the `libs/` subdir to `target`. POSIX `os.rename`
onto a NON-EXISTENT path is atomic; if the target exists (another process won
the race), `os.rename` fails on most platforms — we then verify the winner has
what we need and proceed. NEVER rmtree the target: that creates a TOCTOU
window where another process is reading/loading the file we're deleting.
"""
target.parent.mkdir(parents=True, exist_ok=True)
url = _libs_url(backend)
print(
f"Downloading libsimplex ({_platform_tag()}, {backend}) v{LIBS_VERSION} from {url} ...",
file=sys.stderr,
flush=True,
)
with tempfile.TemporaryDirectory(dir=target.parent) as tmp:
zip_path = Path(tmp) / "libs.zip"
_stream_to_file(url, zip_path, timeout=60.0)
with zipfile.ZipFile(zip_path) as zf:
zf.extractall(tmp)
# zip layout: <tmp>/libs/libsimplex.* + libHS*.*
extracted_libs = Path(tmp) / "libs"
if not extracted_libs.is_dir():
raise RuntimeError(f"libs/ missing from {_libs_url(backend)}")
try:
os.rename(extracted_libs, target)
except OSError as e:
# EEXIST / ENOTEMPTY mean another process won the race — fall through
# and check that the winner left a usable libsimplex behind. Anything
# else (ENOSPC, EACCES, EROFS, Windows codes mapped to None) is a real
# failure and must propagate. Same VERSION cached → same content →
# safe to proceed once we've confirmed the file is there.
if e.errno not in (errno.EEXIST, errno.ENOTEMPTY):
raise
if not (target / _libname()).exists():
raise RuntimeError(
f"another process partially populated {target} but libsimplex "
f"is missing; remove the directory manually and retry"
) from e
_lock = threading.Lock()
_lib: ctypes.CDLL | None = None
_libc: ctypes.CDLL | None = None
_backend: Backend | None = None
def _load_libc() -> ctypes.CDLL:
if sys.platform == "win32":
return ctypes.CDLL("msvcrt")
return ctypes.CDLL(None) # libc on POSIX is the process's own symbol table
def _setup_signatures(lib: ctypes.CDLL) -> None:
"""Declare argtypes/restype for the 8 chat_* functions exported by libsimplex.
All result strings come back as raw c_void_p so the caller can free them
after copying — matches HandleCResult in cpp/simplex.cc:157-165.
"""
lib.chat_migrate_init.argtypes = [c_char_p, c_char_p, c_char_p, POINTER(c_void_p)]
lib.chat_migrate_init.restype = c_void_p
lib.chat_close_store.argtypes = [c_void_p]
lib.chat_close_store.restype = c_void_p
lib.chat_send_cmd.argtypes = [c_void_p, c_char_p]
lib.chat_send_cmd.restype = c_void_p
lib.chat_recv_msg_wait.argtypes = [c_void_p, c_int]
lib.chat_recv_msg_wait.restype = c_void_p
# chat_write_file's payload is treated read-only by libsimplex; passing
# `bytes` via c_char_p avoids the from_buffer_copy doubling. ctypes pins
# the bytes buffer for the duration of the call.
lib.chat_write_file.argtypes = [c_void_p, c_char_p, c_char_p, c_int]
lib.chat_write_file.restype = c_void_p
lib.chat_read_file.argtypes = [c_char_p, c_char_p, c_char_p]
lib.chat_read_file.restype = POINTER(c_uint8)
lib.chat_encrypt_file.argtypes = [c_void_p, c_char_p, c_char_p]
lib.chat_encrypt_file.restype = c_void_p
lib.chat_decrypt_file.argtypes = [c_char_p, c_char_p, c_char_p, c_char_p]
lib.chat_decrypt_file.restype = c_void_p
def _hs_init(lib: ctypes.CDLL) -> None:
"""Initialize the Haskell runtime exactly once. Mirrors cpp/simplex.cc:13-32."""
if sys.platform == "win32":
argv_strs = [b"simplex", b"+RTS", b"-A64m", b"-H64m", b"--install-signal-handlers=no"]
else:
argv_strs = [
b"simplex",
b"+RTS",
b"-A64m",
b"-H64m",
b"-xn",
b"--install-signal-handlers=no",
]
argc = c_int(len(argv_strs))
arr = (c_char_p * (len(argv_strs) + 1))(*argv_strs, None)
arr_ptr = ctypes.byref(ctypes.cast(arr, POINTER(c_char_p)))
lib.hs_init_with_rtsopts.argtypes = [POINTER(c_int), POINTER(POINTER(c_char_p))]
lib.hs_init_with_rtsopts.restype = None
lib.hs_init_with_rtsopts(ctypes.byref(argc), arr_ptr)
def lib_for(backend: Backend) -> ctypes.CDLL:
"""Resolve, load, and initialize libsimplex for the given backend.
Idempotent for the same backend; raises if called with a different backend.
Concurrent calls serialize on the module-level lock.
"""
global _lib, _libc, _backend
with _lock:
if _lib is not None:
if _backend != backend:
raise RuntimeError(
f"libsimplex already loaded with backend={_backend!r}; "
f"cannot switch to {backend!r} in the same process"
)
return _lib
libs_dir = _resolve_libs_dir(backend)
lib = ctypes.CDLL(str(libs_dir / _libname()))
_setup_signatures(lib)
_hs_init(lib)
_libc = _load_libc()
_lib = lib
_backend = backend
return lib
def libc() -> ctypes.CDLL:
"""libc — needed by `core` to free Haskell-allocated result strings."""
if _libc is None:
raise RuntimeError("lib_for() must be called before libc()")
return _libc
def lib() -> ctypes.CDLL:
"""Loaded libsimplex handle. Raises if `lib_for()` has not been called."""
if _lib is None:
raise RuntimeError("lib_for() must be called before lib()")
return _lib
packages/simplex-chat-python/src/simplex_chat/_version.py
+9
View File
@@ -0,0 +1,9 @@
"""Single source of truth for both the Python package version and the
simplex-chat-libs release tag we depend on.
Bump both together for normal releases. For wrapper-only fixes use a PEP 440
post-release: __version__ = "6.5.1.post1", LIBS_VERSION unchanged.
"""
__version__ = "6.5.1" # PEP 440 — read by hatchling for wheel metadata
LIBS_VERSION = "6.5.1" # simplex-chat-libs release tag (no 'v' prefix)
packages/simplex-chat-python/src/simplex_chat/api.py
+704
View File
@@ -0,0 +1,704 @@
"""Low-level escape-hatch API. Most users go through `Bot` instead."""
from __future__ import annotations
import json
from dataclasses import dataclass
from typing import Any, Literal
from . import _native, core, util
from .core import MigrationConfirmation
from .types import CC, CEvt, CR, T
# Mirrors Node `ConnReqType` enum (api.ts:15-18) — the two possible outcomes
# of `api_connect` / `api_connect_active_user` depending on the link kind.
ConnReqType = Literal["invitation", "contact"]
@dataclass(slots=True)
class SqliteDb:
file_prefix: str
encryption_key: str | None = None
@dataclass(slots=True)
class PostgresDb:
connection_string: str
schema_prefix: str | None = None
Db = SqliteDb | PostgresDb
def _db_to_migrate_args(db: Db) -> tuple[str, str, _native.Backend]:
"""Returns (path-or-prefix, key-or-conn, backend)."""
if isinstance(db, SqliteDb):
return (db.file_prefix, db.encryption_key or "", "sqlite")
if isinstance(db, PostgresDb):
return (db.schema_prefix or "", db.connection_string, "postgres")
raise TypeError(f"Unknown db: {db!r}")
class ChatCommandError(Exception):
def __init__(self, message: str, response: CR.ChatResponse):
super().__init__(message)
self.response = response
class ChatApi:
def __init__(self, ctrl: int):
self._ctrl: int | None = ctrl
self._started = False
@classmethod
async def init(
cls,
db: Db,
confirm: MigrationConfirmation = MigrationConfirmation.YES_UP,
) -> "ChatApi":
path_or_prefix, key_or_conn, backend = _db_to_migrate_args(db)
# Trigger lazy lib load with the right backend BEFORE chat_migrate_init.
_native.lib_for(backend)
ctrl = await core.chat_migrate_init(path_or_prefix, key_or_conn, confirm)
return cls(ctrl)
@property
def ctrl(self) -> int:
"""Opaque controller pointer. Raises if `close()` has been called."""
if self._ctrl is None:
raise RuntimeError("ChatApi controller not initialized (close() called?)")
return self._ctrl
@property
def initialized(self) -> bool:
"""True until `close()` is called. Mirrors Node `ChatApi.initialized`."""
return self._ctrl is not None
@property
def started(self) -> bool:
"""True between `start_chat()` and the next `stop_chat()` / `close()`."""
return self._started
async def start_chat(self) -> None:
r = await self.send_chat_cmd(
CC.StartChat_cmd_string({"mainApp": True, "enableSndFiles": True})
)
if r.get("type") not in ("chatStarted", "chatRunning"):
raise ChatCommandError("error starting chat", r)
self._started = True
async def stop_chat(self) -> None:
r = await self.send_chat_cmd("/_stop")
if r.get("type") != "chatStopped":
raise ChatCommandError("error stopping chat", r)
self._started = False
async def close(self) -> None:
await core.chat_close_store(self.ctrl)
self._ctrl = None
self._started = False
async def send_chat_cmd(self, cmd: str) -> CR.ChatResponse:
return await core.chat_send_cmd(self.ctrl, cmd)
async def recv_chat_event(self, wait_us: int = 500_000) -> CEvt.ChatEvent | None:
return await core.chat_recv_msg_wait(self.ctrl, wait_us)
# ------------------------------------------------------------------ #
# Address commands
# ------------------------------------------------------------------ #
async def api_create_user_address(self, user_id: int) -> T.CreatedConnLink:
r = await self.send_chat_cmd(CC.APICreateMyAddress_cmd_string({"userId": user_id}))
if r["type"] == "userContactLinkCreated":
return r["connLinkContact"]
raise ChatCommandError("error creating user address", r)
async def api_delete_user_address(self, user_id: int) -> None:
r = await self.send_chat_cmd(CC.APIDeleteMyAddress_cmd_string({"userId": user_id}))
if r["type"] != "userContactLinkDeleted":
raise ChatCommandError("error deleting user address", r)
async def api_get_user_address(self, user_id: int) -> T.UserContactLink | None:
try:
r = await self.send_chat_cmd(CC.APIShowMyAddress_cmd_string({"userId": user_id}))
if r["type"] == "userContactLink":
return r["contactLink"]
raise ChatCommandError("error loading user address", r)
except core.ChatAPIError as e:
ce = e.chat_error
if (
ce is not None
and ce.get("type") == "errorStore"
and ce.get("storeError", {}).get("type") == "userContactLinkNotFound"
):
return None
raise
async def api_set_profile_address(
self, user_id: int, enable: bool
) -> T.UserProfileUpdateSummary:
r = await self.send_chat_cmd(
CC.APISetProfileAddress_cmd_string({"userId": user_id, "enable": enable})
)
if r["type"] == "userProfileUpdated":
return r["updateSummary"]
raise ChatCommandError("error setting profile address", r)
async def api_set_address_settings(self, user_id: int, settings: T.AddressSettings) -> None:
r = await self.send_chat_cmd(
CC.APISetAddressSettings_cmd_string({"userId": user_id, "settings": settings})
)
if r["type"] != "userContactLinkUpdated":
raise ChatCommandError("error changing user contact address settings", r)
# ------------------------------------------------------------------ #
# Message commands
# ------------------------------------------------------------------ #
async def api_send_messages(
self,
chat: list | T.ChatRef | T.ChatInfo,
messages: list[T.ComposedMessage],
live_message: bool = False,
) -> list[T.AChatItem]:
if isinstance(chat, list):
send_ref: T.ChatRef = {"chatType": chat[0], "chatId": chat[1]}
elif "chatType" in chat and "chatId" in chat:
send_ref = chat
else:
ref = util.chat_info_ref(chat)
if ref is None:
raise ValueError("api_send_messages: can't send messages to this chat")
send_ref = ref
r = await self.send_chat_cmd(
CC.APISendMessages_cmd_string(
{
"sendRef": send_ref,
"composedMessages": messages,
"liveMessage": live_message,
}
)
)
if r["type"] == "newChatItems":
return r["chatItems"]
raise ChatCommandError("unexpected response", r)
async def api_send_text_message(
self,
chat: list | T.ChatRef | T.ChatInfo,
text: str,
in_reply_to: int | None = None,
) -> list[T.AChatItem]:
msg: T.ComposedMessage = {"msgContent": {"type": "text", "text": text}, "mentions": {}}
if in_reply_to is not None:
msg["quotedItemId"] = in_reply_to
return await self.api_send_messages(chat, [msg])
async def api_send_text_reply(self, chat_item: T.AChatItem, text: str) -> list[T.AChatItem]:
return await self.api_send_text_message(
chat_item["chatInfo"], text, chat_item["chatItem"]["meta"]["itemId"]
)
async def api_update_chat_item(
self,
chat_type: T.ChatType,
chat_id: int,
chat_item_id: int,
msg_content: T.MsgContent,
live_message: bool = False,
) -> T.ChatItem:
r = await self.send_chat_cmd(
CC.APIUpdateChatItem_cmd_string(
{
"chatRef": {"chatType": chat_type, "chatId": chat_id},
"chatItemId": chat_item_id,
"liveMessage": live_message,
"updatedMessage": {"msgContent": msg_content, "mentions": {}},
}
)
)
if r["type"] == "chatItemUpdated":
return r["chatItem"]["chatItem"]
raise ChatCommandError("error updating chat item", r)
async def api_delete_chat_items(
self,
chat_type: T.ChatType,
chat_id: int,
chat_item_ids: list[int],
delete_mode: T.CIDeleteMode,
) -> list[T.ChatItemDeletion]:
r = await self.send_chat_cmd(
CC.APIDeleteChatItem_cmd_string(
{
"chatRef": {"chatType": chat_type, "chatId": chat_id},
"chatItemIds": chat_item_ids,
"deleteMode": delete_mode,
}
)
)
if r["type"] == "chatItemsDeleted":
return r["chatItemDeletions"]
raise ChatCommandError("error deleting chat item", r)
async def api_delete_member_chat_item(
self, group_id: int, chat_item_ids: list[int]
) -> list[T.ChatItemDeletion]:
r = await self.send_chat_cmd(
CC.APIDeleteMemberChatItem_cmd_string(
{"groupId": group_id, "chatItemIds": chat_item_ids}
)
)
if r["type"] == "chatItemsDeleted":
return r["chatItemDeletions"]
raise ChatCommandError("error deleting member chat item", r)
async def api_chat_item_reaction(
self,
chat_type: T.ChatType,
chat_id: int,
chat_item_id: int,
add: bool,
reaction: T.MsgReaction,
) -> T.ACIReaction:
r = await self.send_chat_cmd(
CC.APIChatItemReaction_cmd_string(
{
"chatRef": {"chatType": chat_type, "chatId": chat_id},
"chatItemId": chat_item_id,
"add": add,
"reaction": reaction,
}
)
)
if r["type"] == "chatItemReaction":
return r["reaction"]
raise ChatCommandError("error setting item reaction", r)
# ------------------------------------------------------------------ #
# File commands
# ------------------------------------------------------------------ #
async def api_receive_file(self, file_id: int) -> T.AChatItem:
r = await self.send_chat_cmd(
CC.ReceiveFile_cmd_string({"fileId": file_id, "userApprovedRelays": True})
)
if r["type"] == "rcvFileAccepted":
return r["chatItem"]
raise ChatCommandError("error receiving file", r)
async def api_cancel_file(self, file_id: int) -> None:
r = await self.send_chat_cmd(CC.CancelFile_cmd_string({"fileId": file_id}))
if r["type"] not in ("sndFileCancelled", "rcvFileCancelled"):
raise ChatCommandError("error canceling file", r)
# ------------------------------------------------------------------ #
# Group commands
# ------------------------------------------------------------------ #
async def api_add_member(
self, group_id: int, contact_id: int, member_role: T.GroupMemberRole
) -> T.GroupMember:
r = await self.send_chat_cmd(
CC.APIAddMember_cmd_string(
{"groupId": group_id, "contactId": contact_id, "memberRole": member_role}
)
)
if r["type"] == "sentGroupInvitation":
return r["member"]
raise ChatCommandError("error adding member", r)
async def api_join_group(self, group_id: int) -> T.GroupInfo:
r = await self.send_chat_cmd(CC.APIJoinGroup_cmd_string({"groupId": group_id}))
if r["type"] == "userAcceptedGroupSent":
return r["groupInfo"]
raise ChatCommandError("error joining group", r)
async def api_accept_member(
self, group_id: int, group_member_id: int, member_role: T.GroupMemberRole
) -> T.GroupMember:
r = await self.send_chat_cmd(
CC.APIAcceptMember_cmd_string(
{"groupId": group_id, "groupMemberId": group_member_id, "memberRole": member_role}
)
)
if r["type"] == "memberAccepted":
return r["member"]
raise ChatCommandError("error accepting member", r)
async def api_set_members_role(
self, group_id: int, group_member_ids: list[int], member_role: T.GroupMemberRole
) -> None:
r = await self.send_chat_cmd(
CC.APIMembersRole_cmd_string(
{"groupId": group_id, "groupMemberIds": group_member_ids, "memberRole": member_role}
)
)
if r["type"] != "membersRoleUser":
raise ChatCommandError("error setting members role", r)
async def api_block_members_for_all(
self, group_id: int, group_member_ids: list[int], blocked: bool
) -> None:
r = await self.send_chat_cmd(
CC.APIBlockMembersForAll_cmd_string(
{"groupId": group_id, "groupMemberIds": group_member_ids, "blocked": blocked}
)
)
if r["type"] != "membersBlockedForAllUser":
raise ChatCommandError("error blocking members", r)
async def api_remove_members(
self, group_id: int, member_ids: list[int], with_messages: bool = False
) -> list[T.GroupMember]:
r = await self.send_chat_cmd(
CC.APIRemoveMembers_cmd_string(
{"groupId": group_id, "groupMemberIds": member_ids, "withMessages": with_messages}
)
)
if r["type"] == "userDeletedMembers":
return r["members"]
raise ChatCommandError("error removing member", r)
async def api_leave_group(self, group_id: int) -> T.GroupInfo:
r = await self.send_chat_cmd(CC.APILeaveGroup_cmd_string({"groupId": group_id}))
if r["type"] == "leftMemberUser":
return r["groupInfo"]
raise ChatCommandError("error leaving group", r)
async def api_list_members(self, group_id: int) -> list[T.GroupMember]:
r = await self.send_chat_cmd(CC.APIListMembers_cmd_string({"groupId": group_id}))
if r["type"] == "groupMembers":
return r["group"]["members"]
raise ChatCommandError("error getting group members", r)
async def api_new_group(self, user_id: int, group_profile: T.GroupProfile) -> T.GroupInfo:
r = await self.send_chat_cmd(
CC.APINewGroup_cmd_string(
{"userId": user_id, "groupProfile": group_profile, "incognito": False}
)
)
if r["type"] == "groupCreated":
return r["groupInfo"]
raise ChatCommandError("error creating group", r)
async def api_update_group_profile(
self, group_id: int, group_profile: T.GroupProfile
) -> T.GroupInfo:
r = await self.send_chat_cmd(
CC.APIUpdateGroupProfile_cmd_string(
{"groupId": group_id, "groupProfile": group_profile}
)
)
if r["type"] == "groupUpdated":
return r["toGroup"]
raise ChatCommandError("error updating group", r)
# ------------------------------------------------------------------ #
# Group link commands
# ------------------------------------------------------------------ #
async def api_create_group_link(self, group_id: int, member_role: T.GroupMemberRole) -> str:
r = await self.send_chat_cmd(
CC.APICreateGroupLink_cmd_string({"groupId": group_id, "memberRole": member_role})
)
if r["type"] == "groupLinkCreated":
link = r["groupLink"]["connLinkContact"]
return link.get("connShortLink") or link["connFullLink"]
raise ChatCommandError("error creating group link", r)
async def api_set_group_link_member_role(
self, group_id: int, member_role: T.GroupMemberRole
) -> None:
r = await self.send_chat_cmd(
CC.APIGroupLinkMemberRole_cmd_string({"groupId": group_id, "memberRole": member_role})
)
if r["type"] != "groupLink":
raise ChatCommandError("error setting group link member role", r)
async def api_delete_group_link(self, group_id: int) -> None:
r = await self.send_chat_cmd(CC.APIDeleteGroupLink_cmd_string({"groupId": group_id}))
if r["type"] != "groupLinkDeleted":
raise ChatCommandError("error deleting group link", r)
async def api_get_group_link(self, group_id: int) -> T.GroupLink:
r = await self.send_chat_cmd(CC.APIGetGroupLink_cmd_string({"groupId": group_id}))
if r["type"] == "groupLink":
return r["groupLink"]
raise ChatCommandError("error getting group link", r)
async def api_get_group_link_str(self, group_id: int) -> str:
link = (await self.api_get_group_link(group_id))["connLinkContact"]
return link.get("connShortLink") or link["connFullLink"]
# ------------------------------------------------------------------ #
# Connection commands
# ------------------------------------------------------------------ #
async def api_create_link(self, user_id: int) -> str:
r = await self.send_chat_cmd(
CC.APIAddContact_cmd_string({"userId": user_id, "incognito": False})
)
if r["type"] == "invitation":
link = r["connLinkInvitation"]
return link.get("connShortLink") or link["connFullLink"]
raise ChatCommandError("error creating link", r)
async def api_connect_plan(
self, user_id: int, connection_link: str
) -> tuple[T.ConnectionPlan, T.CreatedConnLink]:
r = await self.send_chat_cmd(
CC.APIConnectPlan_cmd_string(
{"userId": user_id, "connectionLink": connection_link, "resolveKnown": False}
)
)
if r["type"] == "connectionPlan":
return (r["connectionPlan"], r["connLink"])
raise ChatCommandError("error getting connect plan", r)
async def api_connect(
self,
user_id: int,
incognito: bool,
prepared_link: T.CreatedConnLink | None = None,
) -> ConnReqType:
args: CC.APIConnect = {"userId": user_id, "incognito": incognito}
if prepared_link is not None:
args["preparedLink_"] = prepared_link
r = await self.send_chat_cmd(CC.APIConnect_cmd_string(args))
return self._handle_connect_result(r)
async def api_connect_active_user(self, conn_link: str) -> ConnReqType:
r = await self.send_chat_cmd(
CC.Connect_cmd_string({"incognito": False, "connLink_": conn_link})
)
return self._handle_connect_result(r)
def _handle_connect_result(self, r: CR.ChatResponse) -> ConnReqType:
if r["type"] == "sentConfirmation":
return "invitation"
if r["type"] == "sentInvitation":
return "contact"
if r["type"] == "contactAlreadyExists":
raise ChatCommandError("contact already exists", r)
raise ChatCommandError("connection error", r)
async def api_accept_contact_request(self, contact_req_id: int) -> T.Contact:
r = await self.send_chat_cmd(
CC.APIAcceptContact_cmd_string({"contactReqId": contact_req_id})
)
if r["type"] == "acceptingContactRequest":
return r["contact"]
raise ChatCommandError("error accepting contact request", r)
async def api_reject_contact_request(self, contact_req_id: int) -> None:
r = await self.send_chat_cmd(
CC.APIRejectContact_cmd_string({"contactReqId": contact_req_id})
)
if r["type"] != "contactRequestRejected":
raise ChatCommandError("error rejecting contact request", r)
# ------------------------------------------------------------------ #
# Chat commands
# ------------------------------------------------------------------ #
async def api_list_contacts(self, user_id: int) -> list[T.Contact]:
r = await self.send_chat_cmd(CC.APIListContacts_cmd_string({"userId": user_id}))
if r["type"] == "contactsList":
return r["contacts"]
raise ChatCommandError("error listing contacts", r)
async def api_list_groups(
self,
user_id: int,
contact_id: int | None = None,
search: str | None = None,
) -> list[T.GroupInfo]:
args: CC.APIListGroups = {"userId": user_id}
if contact_id is not None:
args["contactId_"] = contact_id
if search is not None:
args["search"] = search
r = await self.send_chat_cmd(CC.APIListGroups_cmd_string(args))
if r["type"] == "groupsList":
return r["groups"]
raise ChatCommandError("error listing groups", r)
async def api_get_chats(
self,
user_id: int,
pagination: T.PaginationByTime,
query: T.ChatListQuery | None = None,
pending_connections: bool = False,
) -> list[T.AChat]:
if query is None:
query = {"type": "filters", "favorite": False, "unread": False}
r = await self.send_chat_cmd(
CC.APIGetChats_cmd_string(
{
"userId": user_id,
"pendingConnections": pending_connections,
"pagination": pagination,
"query": query,
}
)
)
if r["type"] == "apiChats":
return r["chats"]
raise ChatCommandError("error getting chats", r)
async def api_delete_chat(
self,
chat_type: T.ChatType,
chat_id: int,
delete_mode: T.ChatDeleteMode | None = None,
) -> None:
if delete_mode is None:
delete_mode = {"type": "full", "notify": True}
r = await self.send_chat_cmd(
CC.APIDeleteChat_cmd_string(
{
"chatRef": {"chatType": chat_type, "chatId": chat_id},
"chatDeleteMode": delete_mode,
}
)
)
if chat_type == "direct" and r["type"] == "contactDeleted":
return
if chat_type == "group" and r["type"] == "groupDeletedUser":
return
raise ChatCommandError("error deleting chat", r)
async def api_set_group_custom_data(
self, group_id: int, custom_data: dict[str, object] | None = None
) -> None:
args: CC.APISetGroupCustomData = {"groupId": group_id}
if custom_data is not None:
args["customData"] = custom_data
r = await self.send_chat_cmd(CC.APISetGroupCustomData_cmd_string(args))
if r["type"] != "cmdOk":
raise ChatCommandError("error setting group custom data", r)
async def api_set_contact_custom_data(
self, contact_id: int, custom_data: dict[str, object] | None = None
) -> None:
args: CC.APISetContactCustomData = {"contactId": contact_id}
if custom_data is not None:
args["customData"] = custom_data
r = await self.send_chat_cmd(CC.APISetContactCustomData_cmd_string(args))
if r["type"] != "cmdOk":
raise ChatCommandError("error setting contact custom data", r)
async def api_set_auto_accept_member_contacts(self, user_id: int, on_off: bool) -> None:
r = await self.send_chat_cmd(
CC.APISetUserAutoAcceptMemberContacts_cmd_string({"userId": user_id, "onOff": on_off})
)
if r["type"] != "cmdOk":
raise ChatCommandError("error setting auto-accept member contacts", r)
async def api_get_chat(self, chat_type: T.ChatType, chat_id: int, count: int) -> dict[str, Any]:
ref = T.ChatType_cmd_string(chat_type) + str(chat_id)
r = await self.send_chat_cmd(f"/_get chat {ref} count={count}")
if r["type"] == "apiChat":
return r["chat"]
raise ChatCommandError("error getting chat", r)
# ------------------------------------------------------------------ #
# User profile commands
# ------------------------------------------------------------------ #
async def api_get_active_user(self) -> T.User | None:
try:
r = await self.send_chat_cmd(CC.ShowActiveUser_cmd_string({}))
if r["type"] == "activeUser":
return r["user"]
raise ChatCommandError("unexpected response", r)
except core.ChatAPIError as e:
ce = e.chat_error
if (
ce is not None
and ce.get("type") == "error"
and ce.get("errorType", {}).get("type") == "noActiveUser"
):
return None
raise
async def api_create_active_user(self, profile: T.Profile | None = None) -> T.User:
new_user: T.NewUser = {"pastTimestamp": False, "userChatRelay": False}
if profile is not None:
new_user["profile"] = profile
r = await self.send_chat_cmd(CC.CreateActiveUser_cmd_string({"newUser": new_user}))
if r["type"] == "activeUser":
return r["user"]
raise ChatCommandError("unexpected response", r)
async def api_list_users(self) -> list[T.UserInfo]:
r = await self.send_chat_cmd(CC.ListUsers_cmd_string({}))
if r["type"] == "usersList":
return r["users"]
raise ChatCommandError("error listing users", r)
async def api_set_active_user(self, user_id: int, view_pwd: str | None = None) -> T.User:
args: CC.APISetActiveUser = {"userId": user_id}
if view_pwd is not None:
args["viewPwd"] = view_pwd
r = await self.send_chat_cmd(CC.APISetActiveUser_cmd_string(args))
if r["type"] == "activeUser":
return r["user"]
raise ChatCommandError("error setting active user", r)
async def api_delete_user(
self, user_id: int, del_smp_queues: bool, view_pwd: str | None = None
) -> None:
args: CC.APIDeleteUser = {"userId": user_id, "delSMPQueues": del_smp_queues}
if view_pwd is not None:
args["viewPwd"] = view_pwd
r = await self.send_chat_cmd(CC.APIDeleteUser_cmd_string(args))
if r["type"] != "cmdOk":
raise ChatCommandError("error deleting user", r)
async def api_update_profile(
self, user_id: int, profile: T.Profile
) -> T.UserProfileUpdateSummary | None:
r = await self.send_chat_cmd(
CC.APIUpdateProfile_cmd_string({"userId": user_id, "profile": profile})
)
if r["type"] == "userProfileNoChange":
return None
if r["type"] == "userProfileUpdated":
return r["updateSummary"]
raise ChatCommandError("error updating profile", r)
async def api_set_contact_prefs(self, contact_id: int, preferences: T.Preferences) -> None:
r = await self.send_chat_cmd(
CC.APISetContactPrefs_cmd_string({"contactId": contact_id, "preferences": preferences})
)
if r["type"] != "contactPrefsUpdated":
raise ChatCommandError("error setting contact prefs", r)
# ------------------------------------------------------------------ #
# Member contact commands
# ------------------------------------------------------------------ #
async def api_create_member_contact(self, group_id: int, group_member_id: int) -> T.Contact:
r = await self.send_chat_cmd(f"/_create member contact #{group_id} {group_member_id}")
if r["type"] == "newMemberContact":
return r["contact"]
raise ChatCommandError("error creating member contact", r)
async def api_send_member_contact_invitation(
self,
contact_id: int,
message: T.MsgContent | str | None = None,
) -> T.Contact:
cmd = f"/_invite member contact @{contact_id}"
if message is not None:
if isinstance(message, str):
cmd += f" text {message}"
else:
cmd += f" json {json.dumps(message)}"
r = await self.send_chat_cmd(cmd)
if r["type"] == "newMemberContactSentInv":
return r["contact"]
raise ChatCommandError("error sending member contact invitation", r)
packages/simplex-chat-python/src/simplex_chat/bot.py
+727
View File
@@ -0,0 +1,727 @@
"""User-facing `Bot` API: decorators, filters, Message wrapper, lifecycle."""
from __future__ import annotations
import asyncio
import logging
import os
import signal as _signal
from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from typing import Any, Generic, Literal, TypeVar, overload
from . import util
from .api import ChatApi, Db
from .core import ChatAPIError, MigrationConfirmation
from .filters import compile_message_filter
from .types import CEvt, T
log = logging.getLogger("simplex_chat")
C = TypeVar("C", bound="T.MsgContent")
@dataclass(slots=True)
class BotProfile:
display_name: str
full_name: str = ""
short_descr: str | None = None
image: str | None = None
@dataclass(slots=True)
class BotCommand:
keyword: str
label: str
@dataclass(slots=True, frozen=True)
class ParsedCommand:
keyword: str
args: str
@dataclass(slots=True, frozen=True)
class Message(Generic[C]):
chat_item: T.AChatItem
content: C
bot: "Bot"
@property
def chat_info(self) -> T.ChatInfo:
return self.chat_item["chatInfo"]
@property
def text(self) -> str | None:
c = self.content
if isinstance(c, dict):
return c.get("text") # type: ignore[return-value]
return None
async def reply(self, text: str) -> "Message[T.MsgContent]":
items = await self.bot.api.api_send_text_reply(self.chat_item, text)
ci = items[0]
content = ci["chatItem"]["content"]
# content is CIContent — snd variant has msgContent; cast for type safety.
msg_content: T.MsgContent = content["msgContent"] # type: ignore[index]
return Message(chat_item=ci, content=msg_content, bot=self.bot)
async def reply_content(self, content: T.MsgContent) -> "Message[T.MsgContent]":
items = await self.bot.api.api_send_messages(
self.chat_info, [{"msgContent": content, "mentions": {}}]
)
ci = items[0]
ci_content = ci["chatItem"]["content"]
msg_content: T.MsgContent = ci_content["msgContent"] # type: ignore[index]
return Message(chat_item=ci, content=msg_content, bot=self.bot)
# Concrete narrowed aliases — one per MsgContent_<tag> variant in _types.py.
TextMessage = Message[T.MsgContent_text]
LinkMessage = Message[T.MsgContent_link]
ImageMessage = Message[T.MsgContent_image]
VideoMessage = Message[T.MsgContent_video]
VoiceMessage = Message[T.MsgContent_voice]
FileMessage = Message[T.MsgContent_file]
ReportMessage = Message[T.MsgContent_report]
ChatMessage = Message[T.MsgContent_chat]
UnknownMessage = Message[T.MsgContent_unknown]
MessageHandler = Callable[[Message[Any]], Awaitable[None]]
CommandHandler = Callable[[Message[Any], ParsedCommand], Awaitable[None]]
EventHandler = Callable[[CEvt.ChatEvent], Awaitable[None]]
class Middleware:
"""Override `__call__` to wrap message handlers with cross-cutting logic.
`handler` is the next stage in the chain — call it with `(message, data)`
to continue, or skip the call to short-circuit. `data` is a per-dispatch
dict that middleware can use to pass values down the chain.
"""
async def __call__(
self,
handler: Callable[[Message[Any], dict[str, object]], Awaitable[None]],
message: Message[Any],
data: dict[str, object],
) -> None:
await handler(message, data)
class Bot:
def __init__(
self,
*,
profile: BotProfile,
db: Db,
welcome: str | T.MsgContent | None = None,
commands: list[BotCommand] | None = None,
confirm_migrations: MigrationConfirmation = MigrationConfirmation.YES_UP,
create_address: bool = True,
update_address: bool = True,
update_profile: bool = True,
auto_accept: bool = True,
business_address: bool = False,
allow_files: bool = False,
use_bot_profile: bool = True,
log_contacts: bool = True,
log_network: bool = False,
) -> None:
self._profile = profile
self._db = db
self._welcome = welcome
self._commands = commands or []
self._confirm_migrations = confirm_migrations
self._opts = {
"create_address": create_address,
"update_address": update_address,
"update_profile": update_profile,
"auto_accept": auto_accept,
"business_address": business_address,
"allow_files": allow_files,
"use_bot_profile": use_bot_profile,
"log_contacts": log_contacts,
"log_network": log_network,
}
self._api: ChatApi | None = None
self._serving = False
self._stop_event = asyncio.Event()
self._message_handlers: list[tuple[Callable[[Message[Any]], bool], MessageHandler]] = []
self._command_handlers: list[
tuple[tuple[str, ...], Callable[[Message[Any]], bool], CommandHandler]
] = []
self._event_handlers: dict[str, list[EventHandler]] = {}
self._middleware: list[Middleware] = []
# Track default-handler registration so __aenter__ on a re-used bot
# doesn't accumulate duplicate log/error handlers.
self._defaults_registered = False
@property
def api(self) -> ChatApi:
if self._api is None:
raise RuntimeError("Bot not initialized — call bot.run() or use `async with bot:`")
return self._api
# ------------------------------------------------------------------ #
# Decorators
# ------------------------------------------------------------------ #
@overload
def on_message(
self, *, content_type: Literal["text"], **rest: Any
) -> Callable[
[Callable[[TextMessage], Awaitable[None]]],
Callable[[TextMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["link"], **rest: Any
) -> Callable[
[Callable[[LinkMessage], Awaitable[None]]],
Callable[[LinkMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["image"], **rest: Any
) -> Callable[
[Callable[[ImageMessage], Awaitable[None]]],
Callable[[ImageMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["video"], **rest: Any
) -> Callable[
[Callable[[VideoMessage], Awaitable[None]]],
Callable[[VideoMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["voice"], **rest: Any
) -> Callable[
[Callable[[VoiceMessage], Awaitable[None]]],
Callable[[VoiceMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["file"], **rest: Any
) -> Callable[
[Callable[[FileMessage], Awaitable[None]]],
Callable[[FileMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["report"], **rest: Any
) -> Callable[
[Callable[[ReportMessage], Awaitable[None]]],
Callable[[ReportMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["chat"], **rest: Any
) -> Callable[
[Callable[[ChatMessage], Awaitable[None]]],
Callable[[ChatMessage], Awaitable[None]],
]: ...
@overload
def on_message(
self, *, content_type: Literal["unknown"], **rest: Any
) -> Callable[
[Callable[[UnknownMessage], Awaitable[None]]],
Callable[[UnknownMessage], Awaitable[None]],
]: ...
@overload
def on_message(self, **rest: Any) -> Callable[[MessageHandler], MessageHandler]: ...
def on_message(self, **filter_kw: Any) -> Callable[[MessageHandler], MessageHandler]:
predicate = compile_message_filter(filter_kw)
def deco(fn: MessageHandler) -> MessageHandler:
self._message_handlers.append((predicate, fn))
return fn
return deco
def on_command(
self, name: str | tuple[str, ...], **filter_kw: Any
) -> Callable[[CommandHandler], CommandHandler]:
names = (name,) if isinstance(name, str) else tuple(name)
predicate = compile_message_filter(filter_kw)
def deco(fn: CommandHandler) -> CommandHandler:
self._command_handlers.append((names, predicate, fn))
return fn
return deco
def on_event(self, event: CEvt.ChatEvent_Tag, /) -> Callable[[EventHandler], EventHandler]:
def deco(fn: EventHandler) -> EventHandler:
self._event_handlers.setdefault(event, []).append(fn)
return fn
return deco
def use(self, middleware: Middleware) -> None:
self._middleware.append(middleware)
# ------------------------------------------------------------------ #
# Lifecycle
# ------------------------------------------------------------------ #
async def __aenter__(self) -> "Bot":
# Order matters: libsimplex `/_start` requires an active user, so
# ensure (or create) the user first, THEN start the chat, THEN
# do address + profile sync. Mirrors Node bot.ts:48-64.
self._api = await ChatApi.init(self._db, self._confirm_migrations)
user = await self._ensure_active_user()
await self._api.start_chat()
await self._sync_address_and_profile(user)
self._register_log_handlers()
return self
async def __aexit__(self, *exc_info: object) -> None:
self.stop()
if self._api is not None:
try:
await self._api.stop_chat()
finally:
await self._api.close()
self._api = None
def run(self) -> None:
"""Blocking entry: runs serve_forever() with SIGINT/SIGTERM handlers installed.
Configures `logging.basicConfig(level=INFO)` if the root logger has no
handlers yet, so the bot's startup messages and the announced address
are visible without callers having to set up logging. Embedders that
manage logging themselves are unaffected (basicConfig is a no-op when
handlers already exist).
"""
if not logging.getLogger().handlers:
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
async def _main() -> None:
async with self:
loop = asyncio.get_running_loop()
# First Ctrl+C → graceful stop (~500ms, bounded by the
# receive-loop poll interval). Second Ctrl+C → force-exit
# immediately (in case stop_chat / close hang on a wedged
# FFI call). Standard CLI UX (jupyter, ipython, …).
sigint_count = 0
def on_interrupt() -> None:
nonlocal sigint_count
sigint_count += 1
if sigint_count == 1:
log.info("stopping bot... (press Ctrl+C again to force exit)")
self.stop()
else:
os._exit(130) # 128 + SIGINT
if hasattr(_signal, "SIGINT"):
try:
loop.add_signal_handler(_signal.SIGINT, on_interrupt)
loop.add_signal_handler(_signal.SIGTERM, self.stop)
except NotImplementedError: # Windows
_signal.signal(_signal.SIGINT, lambda *_: on_interrupt())
await self.serve_forever()
asyncio.run(_main())
async def serve_forever(self) -> None:
if self._serving:
raise RuntimeError("already serving")
self._serving = True
self._stop_event.clear()
try:
await self._receive_loop()
finally:
self._serving = False
def stop(self) -> None:
self._stop_event.set()
async def _receive_loop(self) -> None:
# Catch broad Exception so a single malformed event or transient
# native error doesn't crash the whole bot. CancelledError must
# always re-raise so `bot.stop()` and asyncio cancellation work.
# `wait_us=500_000` (500ms) bounds the worst-case Ctrl+C latency:
# the C call blocks the worker thread until timeout, and the loop
# only checks `_stop_event` between polls.
while not self._stop_event.is_set():
try:
event = await self.api.recv_chat_event(wait_us=500_000)
except asyncio.CancelledError:
raise
except ChatAPIError as e:
# Async chat errors emitted via the Haskell `eToView` path —
# routine soft errors (stale connections after a peer deletes
# a chat, file cleanup failures, etc.) intermixed with
# CRITICAL agent failures the operator must see. Mirror the
# desktop policy in SimpleXAPI.kt:3332-3340: escalate
# CRITICAL agent errors, keep everything else at debug.
chat_err: Any = e.chat_error or {}
agent_err: Any = (
chat_err.get("agentError", {}) if chat_err.get("type") == "errorAgent" else {}
)
if agent_err.get("type") == "CRITICAL":
log.error(
"chat agent CRITICAL: %s (offerRestart=%s)",
agent_err.get("criticalErr"),
agent_err.get("offerRestart"),
)
else:
log.debug("chat event error: %s", chat_err.get("type"))
continue
except Exception:
log.exception("recv_chat_event failed")
# Bound the spin rate when the FFI is wedged on a persistent
# error (vs the timeout path, which already paces itself).
await asyncio.sleep(0.5)
continue
if event is None:
continue
try:
await self._dispatch_event(event)
except asyncio.CancelledError:
raise
except Exception:
log.exception("dispatch_event failed for tag=%s", event.get("type"))
# ------------------------------------------------------------------ #
# Dispatch
# ------------------------------------------------------------------ #
async def _dispatch_event(self, event: CEvt.ChatEvent) -> None:
tag = event["type"]
for h in self._event_handlers.get(tag, []):
try:
await h(event)
except Exception:
log.exception("on_event handler failed")
if tag == "newChatItems":
evt: CEvt.NewChatItems = event # type: ignore[assignment]
for ci in evt["chatItems"]:
content = ci["chatItem"]["content"]
if content["type"] != "rcvMsgContent":
continue
msg_content = content["msgContent"] # type: ignore[index]
msg: Message[T.MsgContent] = Message(chat_item=ci, content=msg_content, bot=self)
await self._dispatch_message(msg)
async def _dispatch_message(self, msg: Message[Any]) -> None:
# First-match-wins. The squaring bot's `@on_message(text=NUMBER_RE)`
# and catch-all `@on_message(content_type="text")` both match a number
# like "1"; we want only the first to fire. Registration order is the
# priority order — register the most-specific filters first.
#
# Slash-commands are tried first against command handlers; if no
# command handler matches, fall through to message handlers (so
# `@on_message` can still catch unknown slash-commands).
cmd = self._parse_command(msg)
if cmd is not None:
for names, predicate, handler in self._command_handlers:
if cmd.keyword in names and predicate(msg):
await self._invoke_command_with_middleware(handler, msg, cmd)
return
for predicate, handler in self._message_handlers:
if predicate(msg):
await self._invoke_with_middleware(handler, msg)
return
async def _invoke_with_middleware(self, handler: MessageHandler, message: Message[Any]) -> None:
# Fast path: most bots register no middleware. Skip the closure-chain
# construction and the empty-data dict on every dispatch.
if not self._middleware:
try:
await handler(message)
except Exception:
log.exception("message handler failed")
return
async def call(m: Message[Any], _data: dict[str, object]) -> None:
await handler(m)
chain: Callable[[Message[Any], dict[str, object]], Awaitable[None]] = call
for mw in reversed(self._middleware):
inner = chain
async def _wrapped(
m: Message[Any],
d: dict[str, object],
mw: Middleware = mw,
inner: Callable[[Message[Any], dict[str, object]], Awaitable[None]] = inner,
) -> None:
await mw(inner, m, d)
chain = _wrapped
try:
await chain(message, {})
except Exception:
log.exception("message handler failed")
async def _invoke_command_with_middleware(
self, handler: CommandHandler, message: Message[Any], cmd: ParsedCommand
) -> None:
if not self._middleware:
try:
await handler(message, cmd)
except Exception:
log.exception("command handler failed")
return
async def call(m: Message[Any], _data: dict[str, object]) -> None:
await handler(m, cmd)
chain: Callable[[Message[Any], dict[str, object]], Awaitable[None]] = call
for mw in reversed(self._middleware):
inner = chain
async def _wrapped(
m: Message[Any],
d: dict[str, object],
mw: Middleware = mw,
inner: Callable[[Message[Any], dict[str, object]], Awaitable[None]] = inner,
) -> None:
await mw(inner, m, d)
chain = _wrapped
try:
await chain(message, {})
except Exception:
log.exception("command handler failed")
@staticmethod
def _parse_command(msg: Message[Any]) -> ParsedCommand | None:
parsed = util.ci_bot_command(msg.chat_item["chatItem"])
if parsed is None:
return None
keyword, args = parsed
return ParsedCommand(keyword=keyword, args=args)
# ------------------------------------------------------------------ #
# Profile + address sync
# ------------------------------------------------------------------ #
async def _ensure_active_user(self) -> T.User:
"""Get or create the active user. Must run before `start_chat`.
Mirrors Node `createBotUser` (bot.ts:158-166). The chat controller
won't accept `/_start` without a user, so this phase has to land
before lifecycle proceeds.
"""
api = self.api
user = await api.api_get_active_user()
if user is None:
log.info("No active user in database, creating...")
user = await api.api_create_active_user(self._bot_profile_to_wire())
log.info("Bot user: %s", user["profile"]["displayName"])
return user
async def _sync_address_and_profile(self, user: T.User) -> None:
"""Address + profile sync. Runs after `start_chat` (mirrors bot.ts:57-63)."""
api = self.api
user_id = user["userId"]
# 2. Address (numbered to match bot.ts comments — phase 1 was user creation).
address = await api.api_get_user_address(user_id)
if address is None:
if self._opts["create_address"]:
log.info("Bot has no address, creating...")
await api.api_create_user_address(user_id)
address = await api.api_get_user_address(user_id)
if address is None:
raise RuntimeError("Failed reading newly created user address")
else:
log.warning("Bot has no address")
# Always announce the address — matches Node bot.ts:60.
link: str | None = None
if address is not None:
link = util.contact_address_str(address["connLinkContact"])
log.info("Bot address: %s", link)
# 3. Address settings (auto-accept + welcome message). Mirrors bot.ts:185-194.
# autoAccept present → accept; absent → no auto-accept (mirrors Node bot.ts).
if address is not None and self._opts["update_address"]:
desired: T.AddressSettings = {"businessAddress": self._opts["business_address"]}
if self._opts["auto_accept"]:
desired["autoAccept"] = {"acceptIncognito": False}
if self._welcome is not None:
desired["autoReply"] = (
{"type": "text", "text": self._welcome}
if isinstance(self._welcome, str)
else self._welcome
)
if address["addressSettings"] != desired:
log.info("Bot address settings changed, updating...")
await api.api_set_address_settings(user_id, desired)
# 4. Profile update. Mirrors Node `updateBotUserProfile` (bot.ts:199-214).
# Field-by-field comparison: user["profile"] is LocalProfile (has extra
# fields profileId, localAlias, preferences, peerType) so a full-dict
# equality would always differ.
new_profile = self._bot_profile_to_wire()
if link is not None and self._opts["use_bot_profile"]:
# Mirrors bot.ts:62 — embed the connection link in the bot's profile
# so contacts that resolve the bot via stored profile data see the
# current address.
new_profile["contactLink"] = link
cur = user["profile"]
changed = (
cur["displayName"] != new_profile["displayName"]
or cur.get("fullName", "") != new_profile.get("fullName", "")
or cur.get("shortDescr") != new_profile.get("shortDescr")
or cur.get("image") != new_profile.get("image")
or cur.get("preferences") != new_profile.get("preferences")
or cur.get("peerType") != new_profile.get("peerType")
or cur.get("contactLink") != new_profile.get("contactLink")
)
if changed and self._opts["update_profile"]:
log.info("Bot profile changed, updating...")
await api.api_update_profile(user_id, new_profile)
def _bot_profile_to_wire(self) -> T.Profile:
"""Construct wire-format Profile, applying bot conventions when use_bot_profile=True.
Mirrors Node mkBotProfile (bot.ts:88-102): bots get peerType="bot",
calls/voice prefs disabled, files gated on `allow_files`, and any
registered `commands` embedded in the profile preferences.
"""
p: T.Profile = {
"displayName": self._profile.display_name,
"fullName": self._profile.full_name,
}
if self._profile.short_descr is not None:
p["shortDescr"] = self._profile.short_descr
if self._profile.image is not None:
p["image"] = self._profile.image
if self._opts["use_bot_profile"]:
prefs: T.Preferences = {
"calls": {"allow": "no"},
"voice": {"allow": "no"},
"files": {"allow": "yes" if self._opts["allow_files"] else "no"},
}
if self._commands:
prefs["commands"] = [
{"type": "command", "keyword": c.keyword, "label": c.label}
for c in self._commands
]
p["preferences"] = prefs
p["peerType"] = "bot"
elif self._commands:
raise ValueError(
"use_bot_profile=False but commands were passed; commands are "
"only sent when use_bot_profile=True (they're embedded in the "
"user profile preferences)."
)
return p
# ------------------------------------------------------------------ #
# Log subscriptions (mirror Node subscribeLogEvents bot.ts:142-156)
# ------------------------------------------------------------------ #
def _register_log_handlers(self) -> None:
# Idempotent: a Bot reused across multiple `__aenter__` cycles must
# not stack duplicate log handlers. Always-on error handlers run
# regardless of log_contacts/log_network so messageError/chatError/
# chatErrors don't disappear into the void.
if self._defaults_registered:
return
self._defaults_registered = True
self._event_handlers.setdefault("messageError", []).append(self._log_message_error)
self._event_handlers.setdefault("chatError", []).append(self._log_chat_error)
self._event_handlers.setdefault("chatErrors", []).append(self._log_chat_errors)
if self._opts["log_contacts"]:
self._event_handlers.setdefault("contactConnected", []).append(
self._log_contact_connected
)
self._event_handlers.setdefault("contactDeletedByContact", []).append(
self._log_contact_deleted
)
if self._opts["log_network"]:
self._event_handlers.setdefault("hostConnected", []).append(self._log_host_connected)
self._event_handlers.setdefault("hostDisconnected", []).append(
self._log_host_disconnected
)
self._event_handlers.setdefault("subscriptionStatus", []).append(
self._log_subscription_status
)
@staticmethod
async def _log_contact_connected(evt: CEvt.ChatEvent) -> None:
log.info("%s connected", evt["contact"]["profile"]["displayName"]) # type: ignore[index]
@staticmethod
async def _log_contact_deleted(evt: CEvt.ChatEvent) -> None:
log.info(
"%s deleted connection with bot",
evt["contact"]["profile"]["displayName"], # type: ignore[index]
)
@staticmethod
async def _log_host_connected(evt: CEvt.ChatEvent) -> None:
log.info("connected server %s", evt["transportHost"]) # type: ignore[index]
@staticmethod
async def _log_host_disconnected(evt: CEvt.ChatEvent) -> None:
log.info("disconnected server %s", evt["transportHost"]) # type: ignore[index]
@staticmethod
async def _log_subscription_status(evt: CEvt.ChatEvent) -> None:
log.info(
"%d subscription(s) %s",
len(evt["connections"]), # type: ignore[index]
evt["subscriptionStatus"]["type"], # type: ignore[index]
)
@staticmethod
async def _log_message_error(evt: CEvt.ChatEvent) -> None:
log.warning("messageError: %s", evt.get("severity", "?")) # type: ignore[union-attr]
@staticmethod
async def _log_chat_error(evt: CEvt.ChatEvent) -> None:
err = evt.get("chatError") # type: ignore[union-attr]
log.error("chatError: %s", err.get("type") if isinstance(err, dict) else err)
@staticmethod
async def _log_chat_errors(evt: CEvt.ChatEvent) -> None:
errs = evt.get("chatErrors") or [] # type: ignore[union-attr]
log.error("chatErrors: %d errors", len(errs))
# Suppress unused-import warnings for re-exported names used only at type-check time.
__all__ = [
"Bot",
"BotCommand",
"BotProfile",
"ChatMessage",
"FileMessage",
"ImageMessage",
"LinkMessage",
"Message",
"MessageHandler",
"CommandHandler",
"EventHandler",
"Middleware",
"ParsedCommand",
"ReportMessage",
"TextMessage",
"UnknownMessage",
"VideoMessage",
"VoiceMessage",
]
packages/simplex-chat-python/src/simplex_chat/core.py
+200
View File
@@ -0,0 +1,200 @@
"""Internal typed async wrapper around libsimplex's 8 C ABI functions.
Users interact with `Bot` / `ChatApi`. This module is exposed as
`simplex_chat.core` for tests and the api.ChatApi class only.
"""
from __future__ import annotations
import asyncio
import ctypes
import json
from enum import StrEnum
from typing import Any, TypedDict
from . import _native
from .types import T, CR, CEvt
class ChatAPIError(Exception):
"""Raised when chat_send_cmd / chat_recv_msg_wait returns a chat error."""
def __init__(self, message: str, chat_error: T.ChatError | None = None):
super().__init__(message)
self.chat_error = chat_error
class ChatInitError(Exception):
"""Raised when chat_migrate_init returns a DBMigrationResult error."""
def __init__(self, message: str, db_migration_error: dict[str, Any]):
super().__init__(message)
self.db_migration_error = db_migration_error
class MigrationConfirmation(StrEnum):
YES_UP = "yesUp"
YES_UP_DOWN = "yesUpDown"
CONSOLE = "console"
ERROR = "error"
class CryptoArgs(TypedDict): # wire-format JSON; camelCase fields
fileKey: str
fileNonce: str
def _read_and_free(ptr: int | None) -> str:
"""Copy a Haskell-allocated null-terminated UTF-8 string and free its buffer.
Mirrors HandleCResult in packages/simplex-chat-nodejs/cpp/simplex.cc:157-165.
"""
if not ptr:
raise RuntimeError("null pointer returned from libsimplex")
try:
return ctypes.string_at(ptr).decode("utf-8")
finally:
_native.libc().free(ctypes.c_void_p(ptr))
async def chat_send_cmd(ctrl: int, cmd: str) -> CR.ChatResponse:
def _call() -> str:
ptr = _native.lib().chat_send_cmd(ctrl, cmd.encode("utf-8"))
return _read_and_free(ptr)
raw = await asyncio.to_thread(_call)
parsed = json.loads(raw)
if "result" in parsed and isinstance(parsed["result"], dict):
return parsed["result"] # type: ignore[return-value]
err = parsed.get("error")
if isinstance(err, dict):
raise ChatAPIError(f"chat command error: {err.get('type')}", err) # type: ignore[arg-type]
raise ChatAPIError(f"invalid chat command result: {raw[:200]}")
async def chat_recv_msg_wait(ctrl: int, wait_us: int = 500_000) -> CEvt.ChatEvent | None:
def _call() -> str:
# On timeout, the C side returns a non-NULL pointer to a single NUL byte
# (see Mobile.hs `fromMaybe ""`), so `_read_and_free` returns "" — no
# NULL-pointer guard is needed here.
ptr = _native.lib().chat_recv_msg_wait(ctrl, wait_us)
return _read_and_free(ptr)
raw = await asyncio.to_thread(_call)
if not raw:
return None
parsed = json.loads(raw)
if "result" in parsed and isinstance(parsed["result"], dict):
return parsed["result"] # type: ignore[return-value]
err = parsed.get("error")
if isinstance(err, dict):
raise ChatAPIError(f"chat event error: {err.get('type')}", err) # type: ignore[arg-type]
raise ChatAPIError(f"invalid chat event: {raw[:200]}")
async def chat_migrate_init(db_path: str, db_key: str, confirm: MigrationConfirmation) -> int:
"""Initialize chat controller. Returns opaque ctrl pointer as Python int."""
def _call() -> tuple[int, str]:
ctrl = ctypes.c_void_p()
ptr = _native.lib().chat_migrate_init(
db_path.encode("utf-8"),
db_key.encode("utf-8"),
confirm.encode("utf-8"),
ctypes.byref(ctrl),
)
return (ctrl.value or 0, _read_and_free(ptr))
ctrl_val, raw = await asyncio.to_thread(_call)
parsed = json.loads(raw)
if parsed.get("type") == "ok":
if not ctrl_val:
# ABI invariant: type=="ok" → out-param written. Defensive guard so a
# broken libsimplex doesn't hand us a NULL controller that would only
# crash on first use much later.
raise RuntimeError("chat_migrate_init returned ok but did not set ctrl pointer")
return ctrl_val
raise ChatInitError(
"Database or migration error (see db_migration_error)",
parsed,
)
async def chat_close_store(ctrl: int) -> None:
def _call() -> str:
ptr = _native.lib().chat_close_store(ctrl)
return _read_and_free(ptr)
res = await asyncio.to_thread(_call)
if res:
raise RuntimeError(res)
async def chat_write_file(ctrl: int, path: str, data: bytes) -> CryptoArgs:
def _call() -> str:
ptr = _native.lib().chat_write_file(ctrl, path.encode("utf-8"), data, len(data))
return _read_and_free(ptr)
raw = await asyncio.to_thread(_call)
return _crypto_args_result(raw)
async def chat_read_file(path: str, args: CryptoArgs) -> bytes:
def _call() -> bytes:
ptr = _native.lib().chat_read_file(
path.encode("utf-8"),
args["fileKey"].encode("utf-8"),
args["fileNonce"].encode("utf-8"),
)
if not ptr:
raise RuntimeError("chat_read_file returned null")
addr = ctypes.cast(ptr, ctypes.c_void_p).value
assert addr is not None # `if not ptr` above already filtered NULL
try:
status = ctypes.cast(addr, ctypes.POINTER(ctypes.c_uint8))[0]
if status == 1:
msg = ctypes.string_at(addr + 1).decode("utf-8")
raise RuntimeError(msg)
if status != 0:
raise RuntimeError(f"unexpected status {status} from chat_read_file")
# `addr + 1` is unaligned for a uint32 read. On the supported platforms
# (linux-x86_64, linux-aarch64, macos-aarch64, windows-x86_64) this is
# silently handled; matches the Node.js binding (cpp/simplex.cc:344).
length = ctypes.cast(addr + 1, ctypes.POINTER(ctypes.c_uint32))[0]
return ctypes.string_at(addr + 5, length)
finally:
_native.libc().free(ctypes.c_void_p(addr))
return await asyncio.to_thread(_call)
async def chat_encrypt_file(ctrl: int, src: str, dst: str) -> CryptoArgs:
def _call() -> str:
ptr = _native.lib().chat_encrypt_file(ctrl, src.encode("utf-8"), dst.encode("utf-8"))
return _read_and_free(ptr)
return _crypto_args_result(await asyncio.to_thread(_call))
async def chat_decrypt_file(src: str, args: CryptoArgs, dst: str) -> None:
def _call() -> str:
ptr = _native.lib().chat_decrypt_file(
src.encode("utf-8"),
args["fileKey"].encode("utf-8"),
args["fileNonce"].encode("utf-8"),
dst.encode("utf-8"),
)
return _read_and_free(ptr)
res = await asyncio.to_thread(_call)
if res:
raise RuntimeError(res)
def _crypto_args_result(raw: str) -> CryptoArgs:
parsed = json.loads(raw)
if parsed.get("type") == "result":
return parsed["cryptoArgs"]
if parsed.get("type") == "error":
raise RuntimeError(parsed.get("writeError", "unknown write error"))
raise RuntimeError(f"unexpected result: {raw[:200]}")
packages/simplex-chat-python/src/simplex_chat/filters.py
+45
View File
@@ -0,0 +1,45 @@
"""Compile kwarg-based message filters into a single predicate."""
from __future__ import annotations
import re
from typing import Any, Callable
def compile_message_filter(kw: dict[str, Any]) -> Callable[[Any], bool]:
"""Compile filter kwargs into a single predicate function.
Multiple kwargs combine with AND; tuples within a kwarg combine with OR.
`when` is the last predicate evaluated.
"""
predicates: list[Callable[[Any], bool]] = []
if (ct := kw.get("content_type")) is not None:
ct_set = (ct,) if isinstance(ct, str) else tuple(ct)
predicates.append(lambda m: m.content.get("type") in ct_set)
if (t := kw.get("text")) is not None:
if isinstance(t, re.Pattern):
predicates.append(lambda m: bool(t.search(m.content.get("text", "") or "")))
else:
predicates.append(lambda m: m.content.get("text") == t)
if (cht := kw.get("chat_type")) is not None:
cht_set = (cht,) if isinstance(cht, str) else tuple(cht)
predicates.append(lambda m: m.chat_item["chatInfo"]["type"] in cht_set)
if (gid := kw.get("group_id")) is not None:
gid_set: tuple[int, ...] = (gid,) if isinstance(gid, int) else tuple(gid)
def gid_match(m: Any) -> bool:
ci = m.chat_item["chatInfo"]
return ci["type"] == "group" and ci["groupInfo"]["groupId"] in gid_set
predicates.append(gid_match)
if (when := kw.get("when")) is not None:
predicates.append(when)
if not predicates:
return lambda _m: True
return lambda m: all(p(m) for p in predicates)
packages/simplex-chat-python/src/simplex_chat/py.typed
View File
packages/simplex-chat-python/src/simplex_chat/types/__init__.py
+16
View File
@@ -0,0 +1,16 @@
"""SimpleX Chat wire types — auto-generated from Haskell.
Re-exports the four generated modules as namespaces:
- ``T`` — :mod:`._types` (records, enums, discriminated unions)
- ``CC`` — :mod:`._commands` (command TypedDicts + ``<Cmd>_cmd_string`` helpers)
- ``CR`` — :mod:`._responses` (``ChatResponse`` and member TypedDicts)
- ``CEvt`` — :mod:`._events` (``ChatEvent`` and member TypedDicts)
"""
from . import _commands as CC
from . import _events as CEvt
from . import _responses as CR
from . import _types as T
__all__ = ["T", "CC", "CR", "CEvt"]
packages/simplex-chat-python/src/simplex_chat/types/_commands.py
+705
View File
@@ -0,0 +1,705 @@
# API Commands
# This file is generated automatically.
from __future__ import annotations
import json
from typing import NotRequired, TypedDict
from . import _types as T
from . import _responses as CR
# Address commands
# Bots can use these commands to automatically check and create address when initialized
# Create bot address.
# Network usage: interactive.
class APICreateMyAddress(TypedDict):
userId: int # int64
def APICreateMyAddress_cmd_string(self: APICreateMyAddress) -> str:
return '/_address ' + str(self['userId'])
APICreateMyAddress_Response = CR.UserContactLinkCreated | CR.ChatCmdError
# Delete bot address.
# Network usage: background.
class APIDeleteMyAddress(TypedDict):
userId: int # int64
def APIDeleteMyAddress_cmd_string(self: APIDeleteMyAddress) -> str:
return '/_delete_address ' + str(self['userId'])
APIDeleteMyAddress_Response = CR.UserContactLinkDeleted | CR.ChatCmdError
# Get bot address and settings.
# Network usage: no.
class APIShowMyAddress(TypedDict):
userId: int # int64
def APIShowMyAddress_cmd_string(self: APIShowMyAddress) -> str:
return '/_show_address ' + str(self['userId'])
APIShowMyAddress_Response = CR.UserContactLink | CR.ChatCmdError
# Add address to bot profile.
# Network usage: interactive.
class APISetProfileAddress(TypedDict):
userId: int # int64
enable: bool
def APISetProfileAddress_cmd_string(self: APISetProfileAddress) -> str:
return '/_profile_address ' + str(self['userId']) + ' ' + ('on' if self['enable'] else 'off')
APISetProfileAddress_Response = CR.UserProfileUpdated | CR.ChatCmdError
# Set bot address settings.
# Network usage: interactive.
class APISetAddressSettings(TypedDict):
userId: int # int64
settings: "T.AddressSettings"
def APISetAddressSettings_cmd_string(self: APISetAddressSettings) -> str:
return '/_address_settings ' + str(self['userId']) + ' ' + json.dumps(self['settings'])
APISetAddressSettings_Response = CR.UserContactLinkUpdated | CR.ChatCmdError
# Message commands
# Commands to send, update, delete, moderate messages and set message reactions
# Send messages.
# Network usage: background.
class APISendMessages(TypedDict):
sendRef: "T.ChatRef"
liveMessage: bool
ttl: NotRequired[int] # int
composedMessages: list["T.ComposedMessage"] # non-empty
def APISendMessages_cmd_string(self: APISendMessages) -> str:
return '/_send ' + T.ChatRef_cmd_string(self['sendRef']) + (' live=on' if self['liveMessage'] else '') + ((' ttl=' + str(self.get('ttl'))) if self.get('ttl') is not None else '') + ' json ' + json.dumps(self['composedMessages'])
APISendMessages_Response = CR.NewChatItems | CR.ChatCmdError
# Update message.
# Network usage: background.
class APIUpdateChatItem(TypedDict):
chatRef: "T.ChatRef"
chatItemId: int # int64
liveMessage: bool
updatedMessage: "T.UpdatedMessage"
def APIUpdateChatItem_cmd_string(self: APIUpdateChatItem) -> str:
return '/_update item ' + T.ChatRef_cmd_string(self['chatRef']) + ' ' + str(self['chatItemId']) + (' live=on' if self['liveMessage'] else '') + ' json ' + json.dumps(self['updatedMessage'])
APIUpdateChatItem_Response = CR.ChatItemUpdated | CR.ChatItemNotChanged | CR.ChatCmdError
# Delete message.
# Network usage: background.
class APIDeleteChatItem(TypedDict):
chatRef: "T.ChatRef"
chatItemIds: list[int] # int64, non-empty
deleteMode: "T.CIDeleteMode"
def APIDeleteChatItem_cmd_string(self: APIDeleteChatItem) -> str:
return '/_delete item ' + T.ChatRef_cmd_string(self['chatRef']) + ' ' + ','.join(map(str, self['chatItemIds'])) + ' ' + str(self['deleteMode'])
APIDeleteChatItem_Response = CR.ChatItemsDeleted | CR.ChatCmdError
# Moderate message. Requires Moderator role (and higher than message author's).
# Network usage: background.
class APIDeleteMemberChatItem(TypedDict):
groupId: int # int64
chatItemIds: list[int] # int64, non-empty
def APIDeleteMemberChatItem_cmd_string(self: APIDeleteMemberChatItem) -> str:
return '/_delete member item #' + str(self['groupId']) + ' ' + ','.join(map(str, self['chatItemIds']))
APIDeleteMemberChatItem_Response = CR.ChatItemsDeleted | CR.ChatCmdError
# Add/remove message reaction.
# Network usage: background.
class APIChatItemReaction(TypedDict):
chatRef: "T.ChatRef"
chatItemId: int # int64
add: bool
reaction: "T.MsgReaction"
def APIChatItemReaction_cmd_string(self: APIChatItemReaction) -> str:
return '/_reaction ' + T.ChatRef_cmd_string(self['chatRef']) + ' ' + str(self['chatItemId']) + ' ' + ('on' if self['add'] else 'off') + ' ' + json.dumps(self['reaction'])
APIChatItemReaction_Response = CR.ChatItemReaction | CR.ChatCmdError
# File commands
# Commands to receive and to cancel files. Files are sent as part of the message, there are no separate commands to send files.
# Receive file.
# Network usage: no.
class ReceiveFile(TypedDict):
fileId: int # int64
userApprovedRelays: bool
storeEncrypted: NotRequired[bool]
fileInline: NotRequired[bool]
filePath: NotRequired[str]
def ReceiveFile_cmd_string(self: ReceiveFile) -> str:
return '/freceive ' + str(self['fileId']) + (' approved_relays=on' if self['userApprovedRelays'] else '') + ((' encrypt=' + ('on' if self.get('storeEncrypted') else 'off')) if self.get('storeEncrypted') is not None else '') + ((' inline=' + ('on' if self.get('fileInline') else 'off')) if self.get('fileInline') is not None else '') + ((' ' + self.get('filePath')) if self.get('filePath') is not None else '')
ReceiveFile_Response = CR.RcvFileAccepted | CR.RcvFileAcceptedSndCancelled | CR.ChatCmdError
# Cancel file.
# Network usage: background.
class CancelFile(TypedDict):
fileId: int # int64
def CancelFile_cmd_string(self: CancelFile) -> str:
return '/fcancel ' + str(self['fileId'])
CancelFile_Response = CR.SndFileCancelled | CR.RcvFileCancelled | CR.ChatCmdError
# Group commands
# Commands to manage and moderate groups. These commands can be used with business chats as well - they are groups. E.g., a common scenario would be to add human agents to business chat with the customer who connected via business address.
# Add contact to group. Requires bot to have Admin role.
# Network usage: interactive.
class APIAddMember(TypedDict):
groupId: int # int64
contactId: int # int64
memberRole: "T.GroupMemberRole"
def APIAddMember_cmd_string(self: APIAddMember) -> str:
return '/_add #' + str(self['groupId']) + ' ' + str(self['contactId']) + ' ' + str(self['memberRole'])
APIAddMember_Response = CR.SentGroupInvitation | CR.ChatCmdError
# Join group.
# Network usage: interactive.
class APIJoinGroup(TypedDict):
groupId: int # int64
def APIJoinGroup_cmd_string(self: APIJoinGroup) -> str:
return '/_join #' + str(self['groupId'])
APIJoinGroup_Response = CR.UserAcceptedGroupSent | CR.ChatCmdError
# Accept group member. Requires Admin role.
# Network usage: background.
class APIAcceptMember(TypedDict):
groupId: int # int64
groupMemberId: int # int64
memberRole: "T.GroupMemberRole"
def APIAcceptMember_cmd_string(self: APIAcceptMember) -> str:
return '/_accept member #' + str(self['groupId']) + ' ' + str(self['groupMemberId']) + ' ' + str(self['memberRole'])
APIAcceptMember_Response = CR.MemberAccepted | CR.ChatCmdError
# Set members role. Requires Admin role.
# Network usage: background.
class APIMembersRole(TypedDict):
groupId: int # int64
groupMemberIds: list[int] # int64, non-empty
memberRole: "T.GroupMemberRole"
def APIMembersRole_cmd_string(self: APIMembersRole) -> str:
return '/_member role #' + str(self['groupId']) + ' ' + ','.join(map(str, self['groupMemberIds'])) + ' ' + str(self['memberRole'])
APIMembersRole_Response = CR.MembersRoleUser | CR.ChatCmdError
# Block members. Requires Moderator role.
# Network usage: background.
class APIBlockMembersForAll(TypedDict):
groupId: int # int64
groupMemberIds: list[int] # int64, non-empty
blocked: bool
def APIBlockMembersForAll_cmd_string(self: APIBlockMembersForAll) -> str:
return '/_block #' + str(self['groupId']) + ' ' + ','.join(map(str, self['groupMemberIds'])) + ' blocked=' + ('on' if self['blocked'] else 'off')
APIBlockMembersForAll_Response = CR.MembersBlockedForAllUser | CR.ChatCmdError
# Remove members. Requires Admin role.
# Network usage: background.
class APIRemoveMembers(TypedDict):
groupId: int # int64
groupMemberIds: list[int] # int64, non-empty
withMessages: bool
def APIRemoveMembers_cmd_string(self: APIRemoveMembers) -> str:
return '/_remove #' + str(self['groupId']) + ' ' + ','.join(map(str, self['groupMemberIds'])) + (' messages=on' if self['withMessages'] else '')
APIRemoveMembers_Response = CR.UserDeletedMembers | CR.ChatCmdError
# Leave group.
# Network usage: background.
class APILeaveGroup(TypedDict):
groupId: int # int64
def APILeaveGroup_cmd_string(self: APILeaveGroup) -> str:
return '/_leave #' + str(self['groupId'])
APILeaveGroup_Response = CR.LeftMemberUser | CR.ChatCmdError
# Get group members.
# Network usage: no.
class APIListMembers(TypedDict):
groupId: int # int64
def APIListMembers_cmd_string(self: APIListMembers) -> str:
return '/_members #' + str(self['groupId'])
APIListMembers_Response = CR.GroupMembers | CR.ChatCmdError
# Create group.
# Network usage: no.
class APINewGroup(TypedDict):
userId: int # int64
incognito: bool
groupProfile: "T.GroupProfile"
def APINewGroup_cmd_string(self: APINewGroup) -> str:
return '/_group ' + str(self['userId']) + (' incognito=on' if self['incognito'] else '') + ' ' + json.dumps(self['groupProfile'])
APINewGroup_Response = CR.GroupCreated | CR.ChatCmdError
# Create public group.
# Network usage: interactive.
class APINewPublicGroup(TypedDict):
userId: int # int64
incognito: bool
relayIds: list[int] # int64, non-empty
groupProfile: "T.GroupProfile"
def APINewPublicGroup_cmd_string(self: APINewPublicGroup) -> str:
return '/_public group ' + str(self['userId']) + (' incognito=on' if self['incognito'] else '') + ' ' + ','.join(map(str, self['relayIds'])) + ' ' + json.dumps(self['groupProfile'])
APINewPublicGroup_Response = CR.PublicGroupCreated | CR.PublicGroupCreationFailed | CR.ChatCmdError
# Get group relays.
# Network usage: no.
class APIGetGroupRelays(TypedDict):
groupId: int # int64
def APIGetGroupRelays_cmd_string(self: APIGetGroupRelays) -> str:
return '/_get relays #' + str(self['groupId'])
APIGetGroupRelays_Response = CR.GroupRelays | CR.ChatCmdError
# Add relays to group.
# Network usage: interactive.
class APIAddGroupRelays(TypedDict):
groupId: int # int64
relayIds: list[int] # int64, non-empty
def APIAddGroupRelays_cmd_string(self: APIAddGroupRelays) -> str:
return '/_add relays #' + str(self['groupId']) + ' ' + ','.join(map(str, self['relayIds']))
APIAddGroupRelays_Response = CR.GroupRelaysAdded | CR.GroupRelaysAddFailed | CR.ChatCmdError
# Update group profile.
# Network usage: background.
class APIUpdateGroupProfile(TypedDict):
groupId: int # int64
groupProfile: "T.GroupProfile"
def APIUpdateGroupProfile_cmd_string(self: APIUpdateGroupProfile) -> str:
return '/_group_profile #' + str(self['groupId']) + ' ' + json.dumps(self['groupProfile'])
APIUpdateGroupProfile_Response = CR.GroupUpdated | CR.ChatCmdError
# Group link commands
# These commands can be used by bots that manage multiple public groups
# Create group link.
# Network usage: interactive.
class APICreateGroupLink(TypedDict):
groupId: int # int64
memberRole: "T.GroupMemberRole"
def APICreateGroupLink_cmd_string(self: APICreateGroupLink) -> str:
return '/_create link #' + str(self['groupId']) + ' ' + str(self['memberRole'])
APICreateGroupLink_Response = CR.GroupLinkCreated | CR.ChatCmdError
# Set member role for group link.
# Network usage: no.
class APIGroupLinkMemberRole(TypedDict):
groupId: int # int64
memberRole: "T.GroupMemberRole"
def APIGroupLinkMemberRole_cmd_string(self: APIGroupLinkMemberRole) -> str:
return '/_set link role #' + str(self['groupId']) + ' ' + str(self['memberRole'])
APIGroupLinkMemberRole_Response = CR.GroupLink | CR.ChatCmdError
# Delete group link.
# Network usage: background.
class APIDeleteGroupLink(TypedDict):
groupId: int # int64
def APIDeleteGroupLink_cmd_string(self: APIDeleteGroupLink) -> str:
return '/_delete link #' + str(self['groupId'])
APIDeleteGroupLink_Response = CR.GroupLinkDeleted | CR.ChatCmdError
# Get group link.
# Network usage: no.
class APIGetGroupLink(TypedDict):
groupId: int # int64
def APIGetGroupLink_cmd_string(self: APIGetGroupLink) -> str:
return '/_get link #' + str(self['groupId'])
APIGetGroupLink_Response = CR.GroupLink | CR.ChatCmdError
# Connection commands
# These commands may be used to create connections. Most bots do not need to use them - bot users will connect via bot address with auto-accept enabled.
# Create 1-time invitation link.
# Network usage: interactive.
class APIAddContact(TypedDict):
userId: int # int64
incognito: bool
def APIAddContact_cmd_string(self: APIAddContact) -> str:
return '/_connect ' + str(self['userId']) + (' incognito=on' if self['incognito'] else '')
APIAddContact_Response = CR.Invitation | CR.ChatCmdError
# Determine SimpleX link type and if the bot is already connected via this link.
# Network usage: interactive.
class APIConnectPlan(TypedDict):
userId: int # int64
connectionLink: NotRequired[str]
resolveKnown: bool
linkOwnerSig: NotRequired["T.LinkOwnerSig"]
def APIConnectPlan_cmd_string(self: APIConnectPlan) -> str:
return '/_connect plan ' + str(self['userId']) + ' ' + self.get('connectionLink')
APIConnectPlan_Response = CR.ConnectionPlan | CR.ChatCmdError
# Connect via prepared SimpleX link. The link can be 1-time invitation link, contact address or group link.
# Network usage: interactive.
class APIConnect(TypedDict):
userId: int # int64
incognito: bool
preparedLink_: NotRequired["T.CreatedConnLink"]
def APIConnect_cmd_string(self: APIConnect) -> str:
return '/_connect ' + str(self['userId']) + ((' ' + T.CreatedConnLink_cmd_string(self.get('preparedLink_'))) if self.get('preparedLink_') is not None else '')
APIConnect_Response = CR.SentConfirmation | CR.ContactAlreadyExists | CR.SentInvitation | CR.ChatCmdError
# Connect via SimpleX link as string in the active user profile.
# Network usage: interactive.
class Connect(TypedDict):
incognito: bool
connLink_: NotRequired[str]
def Connect_cmd_string(self: Connect) -> str:
return '/connect' + ((' ' + self.get('connLink_')) if self.get('connLink_') is not None else '')
Connect_Response = CR.SentConfirmation | CR.ContactAlreadyExists | CR.SentInvitation | CR.ChatCmdError
# Accept contact request.
# Network usage: interactive.
class APIAcceptContact(TypedDict):
contactReqId: int # int64
def APIAcceptContact_cmd_string(self: APIAcceptContact) -> str:
return '/_accept ' + str(self['contactReqId'])
APIAcceptContact_Response = CR.AcceptingContactRequest | CR.ChatCmdError
# Reject contact request. The user who sent the request is **not notified**.
# Network usage: no.
class APIRejectContact(TypedDict):
contactReqId: int # int64
def APIRejectContact_cmd_string(self: APIRejectContact) -> str:
return '/_reject ' + str(self['contactReqId'])
APIRejectContact_Response = CR.ContactRequestRejected | CR.ChatCmdError
# Chat commands
# Commands to list and delete conversations.
# Get contacts.
# Network usage: no.
class APIListContacts(TypedDict):
userId: int # int64
def APIListContacts_cmd_string(self: APIListContacts) -> str:
return '/_contacts ' + str(self['userId'])
APIListContacts_Response = CR.ContactsList | CR.ChatCmdError
# Get groups.
# Network usage: no.
class APIListGroups(TypedDict):
userId: int # int64
contactId_: NotRequired[int] # int64
search: NotRequired[str]
def APIListGroups_cmd_string(self: APIListGroups) -> str:
return '/_groups ' + str(self['userId']) + ((' @' + str(self.get('contactId_'))) if self.get('contactId_') is not None else '') + ((' ' + self.get('search')) if self.get('search') is not None else '')
APIListGroups_Response = CR.GroupsList | CR.ChatCmdError
# Get chat previews. Supports time-based pagination — use this instead of APIListContacts / APIListGroups when scanning at scale (those load every record into memory and fail on large databases).
# Network usage: no.
class APIGetChats(TypedDict):
userId: int # int64
pendingConnections: bool
pagination: "T.PaginationByTime"
query: "T.ChatListQuery"
def APIGetChats_cmd_string(self: APIGetChats) -> str:
return '/_get chats ' + str(self['userId']) + (' pcc=on' if self['pendingConnections'] else '') + ' ' + T.PaginationByTime_cmd_string(self['pagination']) + ' ' + json.dumps(self['query'])
APIGetChats_Response = CR.ApiChats | CR.ChatCmdError
# Delete chat.
# Network usage: background.
class APIDeleteChat(TypedDict):
chatRef: "T.ChatRef"
chatDeleteMode: "T.ChatDeleteMode"
def APIDeleteChat_cmd_string(self: APIDeleteChat) -> str:
return '/_delete ' + T.ChatRef_cmd_string(self['chatRef']) + ' ' + T.ChatDeleteMode_cmd_string(self['chatDeleteMode'])
APIDeleteChat_Response = CR.ContactDeleted | CR.ContactConnectionDeleted | CR.GroupDeletedUser | CR.ChatCmdError
# Set group custom data.
# Network usage: no.
class APISetGroupCustomData(TypedDict):
groupId: int # int64
customData: NotRequired[dict[str, object]]
def APISetGroupCustomData_cmd_string(self: APISetGroupCustomData) -> str:
return '/_set custom #' + str(self['groupId']) + ((' ' + json.dumps(self.get('customData'))) if self.get('customData') is not None else '')
APISetGroupCustomData_Response = CR.CmdOk | CR.ChatCmdError
# Set contact custom data.
# Network usage: no.
class APISetContactCustomData(TypedDict):
contactId: int # int64
customData: NotRequired[dict[str, object]]
def APISetContactCustomData_cmd_string(self: APISetContactCustomData) -> str:
return '/_set custom @' + str(self['contactId']) + ((' ' + json.dumps(self.get('customData'))) if self.get('customData') is not None else '')
APISetContactCustomData_Response = CR.CmdOk | CR.ChatCmdError
# Set auto-accept member contacts.
# Network usage: no.
class APISetUserAutoAcceptMemberContacts(TypedDict):
userId: int # int64
onOff: bool
def APISetUserAutoAcceptMemberContacts_cmd_string(self: APISetUserAutoAcceptMemberContacts) -> str:
return '/_set accept member contacts ' + str(self['userId']) + ' ' + ('on' if self['onOff'] else 'off')
APISetUserAutoAcceptMemberContacts_Response = CR.CmdOk | CR.ChatCmdError
# User profile commands
# Most bots don't need to use these commands, as bot profile can be configured manually via CLI or desktop client. These commands can be used by bots that need to manage multiple user profiles (e.g., the profiles of support agents).
# Get active user profile.
# Network usage: no.
class ShowActiveUser(TypedDict):
pass
def ShowActiveUser_cmd_string(self: ShowActiveUser) -> str:
return '/user'
ShowActiveUser_Response = CR.ActiveUser | CR.ChatCmdError
# Create new user profile.
# Network usage: no.
class CreateActiveUser(TypedDict):
newUser: "T.NewUser"
def CreateActiveUser_cmd_string(self: CreateActiveUser) -> str:
return '/_create user ' + json.dumps(self['newUser'])
CreateActiveUser_Response = CR.ActiveUser | CR.ChatCmdError
# Get all user profiles.
# Network usage: no.
class ListUsers(TypedDict):
pass
def ListUsers_cmd_string(self: ListUsers) -> str:
return '/users'
ListUsers_Response = CR.UsersList | CR.ChatCmdError
# Set active user profile.
# Network usage: no.
class APISetActiveUser(TypedDict):
userId: int # int64
viewPwd: NotRequired[str]
def APISetActiveUser_cmd_string(self: APISetActiveUser) -> str:
return '/_user ' + str(self['userId']) + ((' ' + json.dumps(self.get('viewPwd'))) if self.get('viewPwd') is not None else '')
APISetActiveUser_Response = CR.ActiveUser | CR.ChatCmdError
# Delete user profile.
# Network usage: background.
class APIDeleteUser(TypedDict):
userId: int # int64
delSMPQueues: bool
viewPwd: NotRequired[str]
def APIDeleteUser_cmd_string(self: APIDeleteUser) -> str:
return '/_delete user ' + str(self['userId']) + ' del_smp=' + ('on' if self['delSMPQueues'] else 'off') + ((' ' + json.dumps(self.get('viewPwd'))) if self.get('viewPwd') is not None else '')
APIDeleteUser_Response = CR.CmdOk | CR.ChatCmdError
# Update user profile.
# Network usage: background.
class APIUpdateProfile(TypedDict):
userId: int # int64
profile: "T.Profile"
def APIUpdateProfile_cmd_string(self: APIUpdateProfile) -> str:
return '/_profile ' + str(self['userId']) + ' ' + json.dumps(self['profile'])
APIUpdateProfile_Response = CR.UserProfileUpdated | CR.UserProfileNoChange | CR.ChatCmdError
# Configure chat preference overrides for the contact.
# Network usage: background.
class APISetContactPrefs(TypedDict):
contactId: int # int64
preferences: "T.Preferences"
def APISetContactPrefs_cmd_string(self: APISetContactPrefs) -> str:
return '/_set prefs @' + str(self['contactId']) + ' ' + json.dumps(self['preferences'])
APISetContactPrefs_Response = CR.ContactPrefsUpdated | CR.ChatCmdError
# Chat management
# These commands should not be used with CLI-based bots
# Start chat controller.
# Network usage: no.
class StartChat(TypedDict):
mainApp: bool
enableSndFiles: bool
def StartChat_cmd_string(self: StartChat) -> str:
return '/_start'
StartChat_Response = CR.ChatStarted | CR.ChatRunning
# Stop chat controller.
# Network usage: no.
class APIStopChat(TypedDict):
pass
def APIStopChat_cmd_string(self: APIStopChat) -> str:
return '/_stop'
APIStopChat_Response = CR.ChatStopped
packages/simplex-chat-python/src/simplex_chat/types/_events.py
+379
View File
@@ -0,0 +1,379 @@
# API Events
# This file is generated automatically.
from __future__ import annotations
from typing import Literal, NotRequired, TypedDict
from . import _types as T
class ContactConnected(TypedDict):
type: Literal["contactConnected"]
user: "T.User"
contact: "T.Contact"
userCustomProfile: NotRequired["T.Profile"]
class ContactUpdated(TypedDict):
type: Literal["contactUpdated"]
user: "T.User"
fromContact: "T.Contact"
toContact: "T.Contact"
class ContactDeletedByContact(TypedDict):
type: Literal["contactDeletedByContact"]
user: "T.User"
contact: "T.Contact"
class ReceivedContactRequest(TypedDict):
type: Literal["receivedContactRequest"]
user: "T.User"
contactRequest: "T.UserContactRequest"
chat_: NotRequired["T.AChat"]
class NewMemberContactReceivedInv(TypedDict):
type: Literal["newMemberContactReceivedInv"]
user: "T.User"
contact: "T.Contact"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
class ContactSndReady(TypedDict):
type: Literal["contactSndReady"]
user: "T.User"
contact: "T.Contact"
class NewChatItems(TypedDict):
type: Literal["newChatItems"]
user: "T.User"
chatItems: list["T.AChatItem"]
class ChatItemReaction(TypedDict):
type: Literal["chatItemReaction"]
user: "T.User"
added: bool
reaction: "T.ACIReaction"
class ChatItemsDeleted(TypedDict):
type: Literal["chatItemsDeleted"]
user: "T.User"
chatItemDeletions: list["T.ChatItemDeletion"]
byUser: bool
timed: bool
class ChatItemUpdated(TypedDict):
type: Literal["chatItemUpdated"]
user: "T.User"
chatItem: "T.AChatItem"
class GroupChatItemsDeleted(TypedDict):
type: Literal["groupChatItemsDeleted"]
user: "T.User"
groupInfo: "T.GroupInfo"
chatItemIDs: list[int] # int64
byUser: bool
member_: NotRequired["T.GroupMember"]
class ChatItemsStatusesUpdated(TypedDict):
type: Literal["chatItemsStatusesUpdated"]
user: "T.User"
chatItems: list["T.AChatItem"]
class ReceivedGroupInvitation(TypedDict):
type: Literal["receivedGroupInvitation"]
user: "T.User"
groupInfo: "T.GroupInfo"
contact: "T.Contact"
fromMemberRole: "T.GroupMemberRole"
memberRole: "T.GroupMemberRole"
class UserJoinedGroup(TypedDict):
type: Literal["userJoinedGroup"]
user: "T.User"
groupInfo: "T.GroupInfo"
hostMember: "T.GroupMember"
class GroupUpdated(TypedDict):
type: Literal["groupUpdated"]
user: "T.User"
fromGroup: "T.GroupInfo"
toGroup: "T.GroupInfo"
member_: NotRequired["T.GroupMember"]
msgSigned: NotRequired["T.MsgSigStatus"]
class JoinedGroupMember(TypedDict):
type: Literal["joinedGroupMember"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
class MemberRole(TypedDict):
type: Literal["memberRole"]
user: "T.User"
groupInfo: "T.GroupInfo"
byMember: "T.GroupMember"
member: "T.GroupMember"
fromRole: "T.GroupMemberRole"
toRole: "T.GroupMemberRole"
msgSigned: NotRequired["T.MsgSigStatus"]
class DeletedMember(TypedDict):
type: Literal["deletedMember"]
user: "T.User"
groupInfo: "T.GroupInfo"
byMember: "T.GroupMember"
deletedMember: "T.GroupMember"
withMessages: bool
msgSigned: NotRequired["T.MsgSigStatus"]
class LeftMember(TypedDict):
type: Literal["leftMember"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
msgSigned: NotRequired["T.MsgSigStatus"]
class DeletedMemberUser(TypedDict):
type: Literal["deletedMemberUser"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
withMessages: bool
msgSigned: NotRequired["T.MsgSigStatus"]
class GroupDeleted(TypedDict):
type: Literal["groupDeleted"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
msgSigned: NotRequired["T.MsgSigStatus"]
class ConnectedToGroupMember(TypedDict):
type: Literal["connectedToGroupMember"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
memberContact: NotRequired["T.Contact"]
class MemberAcceptedByOther(TypedDict):
type: Literal["memberAcceptedByOther"]
user: "T.User"
groupInfo: "T.GroupInfo"
acceptingMember: "T.GroupMember"
member: "T.GroupMember"
class MemberBlockedForAll(TypedDict):
type: Literal["memberBlockedForAll"]
user: "T.User"
groupInfo: "T.GroupInfo"
byMember: "T.GroupMember"
member: "T.GroupMember"
blocked: bool
msgSigned: NotRequired["T.MsgSigStatus"]
class GroupMemberUpdated(TypedDict):
type: Literal["groupMemberUpdated"]
user: "T.User"
groupInfo: "T.GroupInfo"
fromMember: "T.GroupMember"
toMember: "T.GroupMember"
class GroupLinkDataUpdated(TypedDict):
type: Literal["groupLinkDataUpdated"]
user: "T.User"
groupInfo: "T.GroupInfo"
groupLink: "T.GroupLink"
groupRelays: list["T.GroupRelay"]
relaysChanged: bool
class GroupRelayUpdated(TypedDict):
type: Literal["groupRelayUpdated"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
groupRelay: "T.GroupRelay"
class RcvFileDescrReady(TypedDict):
type: Literal["rcvFileDescrReady"]
user: "T.User"
chatItem: "T.AChatItem"
rcvFileTransfer: "T.RcvFileTransfer"
rcvFileDescr: "T.RcvFileDescr"
class RcvFileComplete(TypedDict):
type: Literal["rcvFileComplete"]
user: "T.User"
chatItem: "T.AChatItem"
class SndFileCompleteXFTP(TypedDict):
type: Literal["sndFileCompleteXFTP"]
user: "T.User"
chatItem: "T.AChatItem"
fileTransferMeta: "T.FileTransferMeta"
class RcvFileStart(TypedDict):
type: Literal["rcvFileStart"]
user: "T.User"
chatItem: "T.AChatItem"
class RcvFileSndCancelled(TypedDict):
type: Literal["rcvFileSndCancelled"]
user: "T.User"
chatItem: "T.AChatItem"
rcvFileTransfer: "T.RcvFileTransfer"
class RcvFileAccepted(TypedDict):
type: Literal["rcvFileAccepted"]
user: "T.User"
chatItem: "T.AChatItem"
class RcvFileError(TypedDict):
type: Literal["rcvFileError"]
user: "T.User"
chatItem_: NotRequired["T.AChatItem"]
agentError: "T.AgentErrorType"
rcvFileTransfer: "T.RcvFileTransfer"
class RcvFileWarning(TypedDict):
type: Literal["rcvFileWarning"]
user: "T.User"
chatItem_: NotRequired["T.AChatItem"]
agentError: "T.AgentErrorType"
rcvFileTransfer: "T.RcvFileTransfer"
class SndFileError(TypedDict):
type: Literal["sndFileError"]
user: "T.User"
chatItem_: NotRequired["T.AChatItem"]
fileTransferMeta: "T.FileTransferMeta"
errorMessage: str
class SndFileWarning(TypedDict):
type: Literal["sndFileWarning"]
user: "T.User"
chatItem_: NotRequired["T.AChatItem"]
fileTransferMeta: "T.FileTransferMeta"
errorMessage: str
class AcceptingContactRequest(TypedDict):
type: Literal["acceptingContactRequest"]
user: "T.User"
contact: "T.Contact"
class AcceptingBusinessRequest(TypedDict):
type: Literal["acceptingBusinessRequest"]
user: "T.User"
groupInfo: "T.GroupInfo"
class ContactConnecting(TypedDict):
type: Literal["contactConnecting"]
user: "T.User"
contact: "T.Contact"
class BusinessLinkConnecting(TypedDict):
type: Literal["businessLinkConnecting"]
user: "T.User"
groupInfo: "T.GroupInfo"
hostMember: "T.GroupMember"
fromContact: "T.Contact"
class JoinedGroupMemberConnecting(TypedDict):
type: Literal["joinedGroupMemberConnecting"]
user: "T.User"
groupInfo: "T.GroupInfo"
hostMember: "T.GroupMember"
member: "T.GroupMember"
class SentGroupInvitation(TypedDict):
type: Literal["sentGroupInvitation"]
user: "T.User"
groupInfo: "T.GroupInfo"
contact: "T.Contact"
member: "T.GroupMember"
class GroupLinkConnecting(TypedDict):
type: Literal["groupLinkConnecting"]
user: "T.User"
groupInfo: "T.GroupInfo"
hostMember: "T.GroupMember"
class HostConnected(TypedDict):
type: Literal["hostConnected"]
protocol: str
transportHost: str
class HostDisconnected(TypedDict):
type: Literal["hostDisconnected"]
protocol: str
transportHost: str
class SubscriptionStatus(TypedDict):
type: Literal["subscriptionStatus"]
server: str
subscriptionStatus: "T.SubscriptionStatus"
connections: list[str]
class MessageError(TypedDict):
type: Literal["messageError"]
user: "T.User"
severity: str
errorMessage: str
class ChatError(TypedDict):
type: Literal["chatError"]
chatError: "T.ChatError"
class ChatErrors(TypedDict):
type: Literal["chatErrors"]
chatErrors: list["T.ChatError"]
ChatEvent = (
ContactConnected
| ContactUpdated
| ContactDeletedByContact
| ReceivedContactRequest
| NewMemberContactReceivedInv
| ContactSndReady
| NewChatItems
| ChatItemReaction
| ChatItemsDeleted
| ChatItemUpdated
| GroupChatItemsDeleted
| ChatItemsStatusesUpdated
| ReceivedGroupInvitation
| UserJoinedGroup
| GroupUpdated
| JoinedGroupMember
| MemberRole
| DeletedMember
| LeftMember
| DeletedMemberUser
| GroupDeleted
| ConnectedToGroupMember
| MemberAcceptedByOther
| MemberBlockedForAll
| GroupMemberUpdated
| GroupLinkDataUpdated
| GroupRelayUpdated
| RcvFileDescrReady
| RcvFileComplete
| SndFileCompleteXFTP
| RcvFileStart
| RcvFileSndCancelled
| RcvFileAccepted
| RcvFileError
| RcvFileWarning
| SndFileError
| SndFileWarning
| AcceptingContactRequest
| AcceptingBusinessRequest
| ContactConnecting
| BusinessLinkConnecting
| JoinedGroupMemberConnecting
| SentGroupInvitation
| GroupLinkConnecting
| HostConnected
| HostDisconnected
| SubscriptionStatus
| MessageError
| ChatError
| ChatErrors
)
ChatEvent_Tag = Literal["contactConnected", "contactUpdated", "contactDeletedByContact", "receivedContactRequest", "newMemberContactReceivedInv", "contactSndReady", "newChatItems", "chatItemReaction", "chatItemsDeleted", "chatItemUpdated", "groupChatItemsDeleted", "chatItemsStatusesUpdated", "receivedGroupInvitation", "userJoinedGroup", "groupUpdated", "joinedGroupMember", "memberRole", "deletedMember", "leftMember", "deletedMemberUser", "groupDeleted", "connectedToGroupMember", "memberAcceptedByOther", "memberBlockedForAll", "groupMemberUpdated", "groupLinkDataUpdated", "groupRelayUpdated", "rcvFileDescrReady", "rcvFileComplete", "sndFileCompleteXFTP", "rcvFileStart", "rcvFileSndCancelled", "rcvFileAccepted", "rcvFileError", "rcvFileWarning", "sndFileError", "sndFileWarning", "acceptingContactRequest", "acceptingBusinessRequest", "contactConnecting", "businessLinkConnecting", "joinedGroupMemberConnecting", "sentGroupInvitation", "groupLinkConnecting", "hostConnected", "hostDisconnected", "subscriptionStatus", "messageError", "chatError", "chatErrors"]
packages/simplex-chat-python/src/simplex_chat/types/_responses.py
+360
View File
@@ -0,0 +1,360 @@
# API Responses
# This file is generated automatically.
from __future__ import annotations
from typing import Literal, NotRequired, TypedDict
from . import _types as T
class AcceptingContactRequest(TypedDict):
type: Literal["acceptingContactRequest"]
user: "T.User"
contact: "T.Contact"
class ActiveUser(TypedDict):
type: Literal["activeUser"]
user: "T.User"
class ChatItemNotChanged(TypedDict):
type: Literal["chatItemNotChanged"]
user: "T.User"
chatItem: "T.AChatItem"
class ChatItemReaction(TypedDict):
type: Literal["chatItemReaction"]
user: "T.User"
added: bool
reaction: "T.ACIReaction"
class ChatItemUpdated(TypedDict):
type: Literal["chatItemUpdated"]
user: "T.User"
chatItem: "T.AChatItem"
class ChatItemsDeleted(TypedDict):
type: Literal["chatItemsDeleted"]
user: "T.User"
chatItemDeletions: list["T.ChatItemDeletion"]
byUser: bool
timed: bool
class ChatRunning(TypedDict):
type: Literal["chatRunning"]
class ChatStarted(TypedDict):
type: Literal["chatStarted"]
class ChatStopped(TypedDict):
type: Literal["chatStopped"]
class CmdOk(TypedDict):
type: Literal["cmdOk"]
user_: NotRequired["T.User"]
class ChatCmdError(TypedDict):
type: Literal["chatCmdError"]
chatError: "T.ChatError"
class ConnectionPlan(TypedDict):
type: Literal["connectionPlan"]
user: "T.User"
connLink: "T.CreatedConnLink"
connectionPlan: "T.ConnectionPlan"
class ContactAlreadyExists(TypedDict):
type: Literal["contactAlreadyExists"]
user: "T.User"
contact: "T.Contact"
class ContactConnectionDeleted(TypedDict):
type: Literal["contactConnectionDeleted"]
user: "T.User"
connection: "T.PendingContactConnection"
class ContactDeleted(TypedDict):
type: Literal["contactDeleted"]
user: "T.User"
contact: "T.Contact"
class ContactPrefsUpdated(TypedDict):
type: Literal["contactPrefsUpdated"]
user: "T.User"
fromContact: "T.Contact"
toContact: "T.Contact"
class ContactRequestRejected(TypedDict):
type: Literal["contactRequestRejected"]
user: "T.User"
contactRequest: "T.UserContactRequest"
contact_: NotRequired["T.Contact"]
class ContactsList(TypedDict):
type: Literal["contactsList"]
user: "T.User"
contacts: list["T.Contact"]
class GroupDeletedUser(TypedDict):
type: Literal["groupDeletedUser"]
user: "T.User"
groupInfo: "T.GroupInfo"
msgSigned: bool
class GroupLink(TypedDict):
type: Literal["groupLink"]
user: "T.User"
groupInfo: "T.GroupInfo"
groupLink: "T.GroupLink"
class GroupLinkCreated(TypedDict):
type: Literal["groupLinkCreated"]
user: "T.User"
groupInfo: "T.GroupInfo"
groupLink: "T.GroupLink"
class GroupLinkDeleted(TypedDict):
type: Literal["groupLinkDeleted"]
user: "T.User"
groupInfo: "T.GroupInfo"
class GroupCreated(TypedDict):
type: Literal["groupCreated"]
user: "T.User"
groupInfo: "T.GroupInfo"
class PublicGroupCreated(TypedDict):
type: Literal["publicGroupCreated"]
user: "T.User"
groupInfo: "T.GroupInfo"
groupLink: "T.GroupLink"
groupRelays: list["T.GroupRelay"]
class PublicGroupCreationFailed(TypedDict):
type: Literal["publicGroupCreationFailed"]
user: "T.User"
addRelayResults: list["T.AddRelayResult"]
class GroupRelays(TypedDict):
type: Literal["groupRelays"]
user: "T.User"
groupInfo: "T.GroupInfo"
groupRelays: list["T.GroupRelay"]
class GroupRelaysAdded(TypedDict):
type: Literal["groupRelaysAdded"]
user: "T.User"
groupInfo: "T.GroupInfo"
groupLink: "T.GroupLink"
groupRelays: list["T.GroupRelay"]
class GroupRelaysAddFailed(TypedDict):
type: Literal["groupRelaysAddFailed"]
user: "T.User"
addRelayResults: list["T.AddRelayResult"]
class GroupMembers(TypedDict):
type: Literal["groupMembers"]
user: "T.User"
group: "T.Group"
class GroupUpdated(TypedDict):
type: Literal["groupUpdated"]
user: "T.User"
fromGroup: "T.GroupInfo"
toGroup: "T.GroupInfo"
member_: NotRequired["T.GroupMember"]
msgSigned: bool
class GroupsList(TypedDict):
type: Literal["groupsList"]
user: "T.User"
groups: list["T.GroupInfo"]
class Invitation(TypedDict):
type: Literal["invitation"]
user: "T.User"
connLinkInvitation: "T.CreatedConnLink"
connection: "T.PendingContactConnection"
class LeftMemberUser(TypedDict):
type: Literal["leftMemberUser"]
user: "T.User"
groupInfo: "T.GroupInfo"
class MemberAccepted(TypedDict):
type: Literal["memberAccepted"]
user: "T.User"
groupInfo: "T.GroupInfo"
member: "T.GroupMember"
class MembersBlockedForAllUser(TypedDict):
type: Literal["membersBlockedForAllUser"]
user: "T.User"
groupInfo: "T.GroupInfo"
members: list["T.GroupMember"]
blocked: bool
msgSigned: bool
class MembersRoleUser(TypedDict):
type: Literal["membersRoleUser"]
user: "T.User"
groupInfo: "T.GroupInfo"
members: list["T.GroupMember"]
toRole: "T.GroupMemberRole"
msgSigned: bool
class NewChatItems(TypedDict):
type: Literal["newChatItems"]
user: "T.User"
chatItems: list["T.AChatItem"]
class RcvFileAccepted(TypedDict):
type: Literal["rcvFileAccepted"]
user: "T.User"
chatItem: "T.AChatItem"
class RcvFileAcceptedSndCancelled(TypedDict):
type: Literal["rcvFileAcceptedSndCancelled"]
user: "T.User"
rcvFileTransfer: "T.RcvFileTransfer"
class RcvFileCancelled(TypedDict):
type: Literal["rcvFileCancelled"]
user: "T.User"
chatItem_: NotRequired["T.AChatItem"]
rcvFileTransfer: "T.RcvFileTransfer"
class SentConfirmation(TypedDict):
type: Literal["sentConfirmation"]
user: "T.User"
connection: "T.PendingContactConnection"
customUserProfile: NotRequired["T.Profile"]
class SentGroupInvitation(TypedDict):
type: Literal["sentGroupInvitation"]
user: "T.User"
groupInfo: "T.GroupInfo"
contact: "T.Contact"
member: "T.GroupMember"
class SentInvitation(TypedDict):
type: Literal["sentInvitation"]
user: "T.User"
connection: "T.PendingContactConnection"
customUserProfile: NotRequired["T.Profile"]
class SndFileCancelled(TypedDict):
type: Literal["sndFileCancelled"]
user: "T.User"
chatItem_: NotRequired["T.AChatItem"]
fileTransferMeta: "T.FileTransferMeta"
sndFileTransfers: list["T.SndFileTransfer"]
class UserAcceptedGroupSent(TypedDict):
type: Literal["userAcceptedGroupSent"]
user: "T.User"
groupInfo: "T.GroupInfo"
hostContact: NotRequired["T.Contact"]
class UserContactLink(TypedDict):
type: Literal["userContactLink"]
user: "T.User"
contactLink: "T.UserContactLink"
class UserContactLinkCreated(TypedDict):
type: Literal["userContactLinkCreated"]
user: "T.User"
connLinkContact: "T.CreatedConnLink"
class UserContactLinkDeleted(TypedDict):
type: Literal["userContactLinkDeleted"]
user: "T.User"
class UserContactLinkUpdated(TypedDict):
type: Literal["userContactLinkUpdated"]
user: "T.User"
contactLink: "T.UserContactLink"
class UserDeletedMembers(TypedDict):
type: Literal["userDeletedMembers"]
user: "T.User"
groupInfo: "T.GroupInfo"
members: list["T.GroupMember"]
withMessages: bool
msgSigned: bool
class UserProfileUpdated(TypedDict):
type: Literal["userProfileUpdated"]
user: "T.User"
fromProfile: "T.Profile"
toProfile: "T.Profile"
updateSummary: "T.UserProfileUpdateSummary"
class UserProfileNoChange(TypedDict):
type: Literal["userProfileNoChange"]
user: "T.User"
class UsersList(TypedDict):
type: Literal["usersList"]
users: list["T.UserInfo"]
class ApiChats(TypedDict):
type: Literal["apiChats"]
user: "T.User"
chats: list["T.AChat"]
ChatResponse = (
AcceptingContactRequest
| ActiveUser
| ChatItemNotChanged
| ChatItemReaction
| ChatItemUpdated
| ChatItemsDeleted
| ChatRunning
| ChatStarted
| ChatStopped
| CmdOk
| ChatCmdError
| ConnectionPlan
| ContactAlreadyExists
| ContactConnectionDeleted
| ContactDeleted
| ContactPrefsUpdated
| ContactRequestRejected
| ContactsList
| GroupDeletedUser
| GroupLink
| GroupLinkCreated
| GroupLinkDeleted
| GroupCreated
| PublicGroupCreated
| PublicGroupCreationFailed
| GroupRelays
| GroupRelaysAdded
| GroupRelaysAddFailed
| GroupMembers
| GroupUpdated
| GroupsList
| Invitation
| LeftMemberUser
| MemberAccepted
| MembersBlockedForAllUser
| MembersRoleUser
| NewChatItems
| RcvFileAccepted
| RcvFileAcceptedSndCancelled
| RcvFileCancelled
| SentConfirmation
| SentGroupInvitation
| SentInvitation
| SndFileCancelled
| UserAcceptedGroupSent
| UserContactLink
| UserContactLinkCreated
| UserContactLinkDeleted
| UserContactLinkUpdated
| UserDeletedMembers
| UserProfileUpdated
| UserProfileNoChange
| UsersList
| ApiChats
)
ChatResponse_Tag = Literal["acceptingContactRequest", "activeUser", "chatItemNotChanged", "chatItemReaction", "chatItemUpdated", "chatItemsDeleted", "chatRunning", "chatStarted", "chatStopped", "cmdOk", "chatCmdError", "connectionPlan", "contactAlreadyExists", "contactConnectionDeleted", "contactDeleted", "contactPrefsUpdated", "contactRequestRejected", "contactsList", "groupDeletedUser", "groupLink", "groupLinkCreated", "groupLinkDeleted", "groupCreated", "publicGroupCreated", "publicGroupCreationFailed", "groupRelays", "groupRelaysAdded", "groupRelaysAddFailed", "groupMembers", "groupUpdated", "groupsList", "invitation", "leftMemberUser", "memberAccepted", "membersBlockedForAllUser", "membersRoleUser", "newChatItems", "rcvFileAccepted", "rcvFileAcceptedSndCancelled", "rcvFileCancelled", "sentConfirmation", "sentGroupInvitation", "sentInvitation", "sndFileCancelled", "userAcceptedGroupSent", "userContactLink", "userContactLinkCreated", "userContactLinkDeleted", "userContactLinkUpdated", "userDeletedMembers", "userProfileUpdated", "userProfileNoChange", "usersList", "apiChats"]
packages/simplex-chat-python/src/simplex_chat/types/_types.py
+3506
View File
File diff suppressed because it is too large Load Diff
packages/simplex-chat-python/src/simplex_chat/util.py
+128
View File
@@ -0,0 +1,128 @@
"""Reusable helpers for working with chat events, types, and message content.
Mirrors the Node `util.ts` exports — provides the same primitives bot
authors typically reach for: command parsing, sender display strings,
message-content extraction, profile field cleanup, and ChatRef extraction
from a ChatInfo (handy when echoing into a different chat).
"""
from __future__ import annotations
import re
from typing import Any
from .types import T
def chat_info_ref(c_info: T.ChatInfo) -> T.ChatRef | None:
"""Extract a wire-format `ChatRef` from a `ChatInfo`.
Returns `None` for non-chat infos (contactRequest, contactConnection)
that can't be the target of `api_send_messages`. For groups, the
`memberSupport` scope is forwarded so messages land in the right
thread; other scopes are dropped (matches Node `util.chatInfoRef`).
"""
t = c_info["type"]
if t == "direct":
return {"chatType": "direct", "chatId": c_info["contact"]["contactId"]} # type: ignore[index]
if t == "group":
ref: T.ChatRef = {"chatType": "group", "chatId": c_info["groupInfo"]["groupId"]} # type: ignore[index]
scope = c_info.get("groupChatScope") # type: ignore[union-attr]
if scope and scope.get("type") == "memberSupport":
member = scope.get("groupMember_")
ms_scope: T.GroupChatScope_memberSupport = {"type": "memberSupport"}
if member is not None:
ms_scope["groupMemberId_"] = member["groupMemberId"]
ref["chatScope"] = ms_scope
return ref
return None
def chat_info_name(c_info: T.ChatInfo) -> str:
"""Display string for a chat: `@Alice`, `#GroupName`, `private notes`, etc."""
t = c_info["type"]
if t == "direct":
return f"@{c_info['contact']['profile']['displayName']}" # type: ignore[index]
if t == "group":
scope = c_info.get("groupChatScope") # type: ignore[union-attr]
if scope and scope.get("type") == "memberSupport":
member = scope.get("groupMember_")
scope_name = f" {member['memberProfile']['displayName']}" if member else ""
return f"#{c_info['groupInfo']['groupProfile']['displayName']}(support{scope_name})" # type: ignore[index]
return f"#{c_info['groupInfo']['groupProfile']['displayName']}" # type: ignore[index]
if t == "local":
return "private notes"
if t == "contactRequest":
return f"request from @{c_info['contactRequest']['profile']['displayName']}" # type: ignore[index]
if t == "contactConnection":
alias = c_info["contactConnection"].get("localAlias") # type: ignore[index]
return f"pending connection ({alias})" if alias else "pending connection"
return f"<{t}>"
def sender_name(c_info: T.ChatInfo, chat_dir: T.CIDirection) -> str:
"""Sender display: chat name plus group sender suffix when applicable."""
base = chat_info_name(c_info)
if chat_dir["type"] == "groupRcv":
sender = chat_dir["groupMember"]["memberProfile"]["displayName"] # type: ignore[index]
return f"{base} @{sender}"
return base
def contact_address_str(link: T.CreatedConnLink) -> str:
"""Prefer the short link, fall back to the full link."""
return link.get("connShortLink") or link["connFullLink"]
def from_local_profile(local: T.LocalProfile) -> T.Profile:
"""Strip extra LocalProfile fields (profileId, localAlias) and undefined values."""
p: dict[str, Any] = {}
for key in (
"displayName",
"fullName",
"shortDescr",
"image",
"contactLink",
"preferences",
"peerType",
):
v = local.get(key) # type: ignore[misc]
if v is not None:
p[key] = v
return p # type: ignore[return-value]
def ci_content_text(chat_item: T.ChatItem) -> str | None:
"""Extract the message text from a sent or received message item, if any."""
content = chat_item["content"]
if content["type"] in ("sndMsgContent", "rcvMsgContent"):
msg = content.get("msgContent", {}) # type: ignore[union-attr]
return msg.get("text")
return None
_BOT_COMMAND_RE = re.compile(r"^/([^\s]+)(.*)$")
def ci_bot_command(chat_item: T.ChatItem) -> tuple[str, str] | None:
"""Parse a `/keyword args...` slash-command from a chat item.
Returns `(keyword, trimmed_params)` or `None` if the message isn't a
slash command. Mirrors Node `util.ciBotCommand` semantics.
"""
text = ci_content_text(chat_item)
if not text:
return None
text = text.strip()
m = _BOT_COMMAND_RE.match(text)
if not m:
return None
return m.group(1), m.group(2).strip()
def reaction_text(reaction: T.ACIReaction) -> str:
"""Format an `ACIReaction` as the emoji character or tag string."""
r = reaction["chatReaction"]["reaction"] # type: ignore[index]
if r["type"] == "emoji":
return r["emoji"] # type: ignore[index]
return r.get("tag", "") # type: ignore[union-attr]
packages/simplex-chat-python/tests/test_bot_registration.py
+357
View File
@@ -0,0 +1,357 @@
import pytest
from simplex_chat import Bot, BotCommand, BotProfile, Middleware, SqliteDb
from simplex_chat.api import ChatApi
def _bot() -> Bot:
return Bot(profile=BotProfile(display_name="x"), db=SqliteDb(file_prefix="/tmp/test"))
def test_decorator_registers_message_handler():
bot = _bot()
@bot.on_message(content_type="text")
async def h(msg):
pass
assert len(bot._message_handlers) == 1
def test_decorator_registers_command_handler():
bot = _bot()
@bot.on_command("ping")
async def h(msg, cmd):
pass
assert len(bot._command_handlers) == 1
assert bot._command_handlers[0][0] == ("ping",)
def test_decorator_registers_event_handler():
bot = _bot()
@bot.on_event("newChatItems")
async def h(evt):
pass
assert "newChatItems" in bot._event_handlers
assert len(bot._event_handlers["newChatItems"]) == 1
def test_api_property_raises_before_init():
bot = _bot()
with pytest.raises(RuntimeError, match="not initialized"):
_ = bot.api
def test_command_keyword_tuple():
bot = _bot()
@bot.on_command(("p", "ping"))
async def h(msg, cmd):
pass
assert bot._command_handlers[0][0] == ("p", "ping")
def test_bot_profile_to_wire_default():
"""use_bot_profile=True (default) sets peerType=bot and disables calls/voice."""
bot = _bot()
p = bot._bot_profile_to_wire()
assert p["displayName"] == "x"
assert p.get("peerType") == "bot"
prefs = p.get("preferences") or {}
assert prefs.get("calls", {}).get("allow") == "no"
assert prefs.get("voice", {}).get("allow") == "no"
assert prefs.get("files", {}).get("allow") == "no" # allow_files defaults to False
def test_bot_profile_to_wire_allow_files():
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
allow_files=True,
)
prefs = bot._bot_profile_to_wire().get("preferences") or {}
assert prefs.get("files", {}).get("allow") == "yes"
def test_bot_profile_to_wire_with_commands():
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
commands=[BotCommand(keyword="ping", label="Ping bot"), BotCommand("help", "Show help")],
)
cmds = bot._bot_profile_to_wire().get("preferences", {}).get("commands") or []
assert len(cmds) == 2
assert cmds[0] == {"type": "command", "keyword": "ping", "label": "Ping bot"}
assert cmds[1] == {"type": "command", "keyword": "help", "label": "Show help"}
def test_bot_profile_to_wire_no_bot_profile():
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
use_bot_profile=False,
)
p = bot._bot_profile_to_wire()
assert "peerType" not in p
assert "preferences" not in p
def test_commands_without_bot_profile_raises():
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
use_bot_profile=False,
commands=[BotCommand("ping", "Ping bot")],
)
with pytest.raises(ValueError, match="use_bot_profile=False"):
bot._bot_profile_to_wire()
def test_dispatch_message_first_match_wins():
"""Two matching message handlers — only the first registered fires."""
import asyncio
import re
bot = _bot()
calls: list[str] = []
@bot.on_message(content_type="text", text=re.compile(r"^\d+$"))
async def number(_msg):
calls.append("number")
@bot.on_message(content_type="text")
async def fallback(_msg):
calls.append("fallback")
class M:
pass
m = M()
m.content = {"type": "text", "text": "42"}
m.chat_item = {
"chatItem": {
"content": {"type": "rcvMsgContent", "msgContent": {"type": "text", "text": "42"}}
},
"chatInfo": {"type": "direct"},
}
m.text = "42"
asyncio.run(bot._dispatch_message(m)) # type: ignore[arg-type]
assert calls == ["number"], f"expected only 'number' for '42', got {calls}"
def test_dispatch_message_falls_to_second_when_first_doesnt_match():
"""If the first handler's filter doesn't match, the second one fires."""
import asyncio
import re
bot = _bot()
calls: list[str] = []
@bot.on_message(content_type="text", text=re.compile(r"^\d+$"))
async def number(_msg):
calls.append("number")
@bot.on_message(content_type="text")
async def fallback(_msg):
calls.append("fallback")
class M:
pass
m = M()
m.content = {"type": "text", "text": "hello"}
m.chat_item = {
"chatItem": {
"content": {"type": "rcvMsgContent", "msgContent": {"type": "text", "text": "hello"}}
},
"chatInfo": {"type": "direct"},
}
m.text = "hello"
asyncio.run(bot._dispatch_message(m)) # type: ignore[arg-type]
assert calls == ["fallback"], f"expected 'fallback' for 'hello', got {calls}"
def test_register_log_handlers_idempotent():
"""Calling _register_log_handlers twice doesn't duplicate handlers."""
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
log_contacts=True,
log_network=True,
)
bot._register_log_handlers()
counts1 = {tag: len(hs) for tag, hs in bot._event_handlers.items()}
bot._register_log_handlers()
counts2 = {tag: len(hs) for tag, hs in bot._event_handlers.items()}
assert counts1 == counts2, f"handler count changed across calls: {counts1} -> {counts2}"
def test_default_error_handlers_always_registered():
"""messageError/chatError/chatErrors get default loggers regardless of opts."""
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
log_contacts=False,
log_network=False,
)
bot._register_log_handlers()
assert "messageError" in bot._event_handlers
assert "chatError" in bot._event_handlers
assert "chatErrors" in bot._event_handlers
def test_dispatch_command_suppresses_matching_message_handlers():
"""A `/help` message routed to a command handler must NOT also fire the
generic on_message text handler."""
import asyncio
bot = _bot()
calls: list[str] = []
@bot.on_message(content_type="text")
async def fallback(_msg):
calls.append("message")
@bot.on_command("help")
async def help_cmd(_msg, _cmd):
calls.append("command")
# Build a minimal Message-shaped object (handlers only inspect chat_item / text).
class M:
pass
m = M()
m.content = {"type": "text", "text": "/help"}
m.chat_item = {
"chatItem": {
"content": {
"type": "rcvMsgContent",
"msgContent": {"type": "text", "text": "/help"},
}
},
"chatInfo": {"type": "direct"},
}
m.text = "/help"
asyncio.run(bot._dispatch_message(m)) # type: ignore[arg-type]
assert calls == ["command"], f"expected only 'command' to fire for /help, got {calls}"
def test_dispatch_unknown_command_falls_through_to_message_handlers():
"""A `/unknown` slash-command with no handler should still fire on_message."""
import asyncio
bot = _bot()
calls: list[str] = []
@bot.on_message(content_type="text")
async def fallback(_msg):
calls.append("message")
@bot.on_command("help")
async def help_cmd(_msg, _cmd):
calls.append("command")
class M:
pass
m = M()
m.content = {"type": "text", "text": "/unknown"}
m.chat_item = {
"chatItem": {
"content": {
"type": "rcvMsgContent",
"msgContent": {"type": "text", "text": "/unknown"},
}
},
"chatInfo": {"type": "direct"},
}
m.text = "/unknown"
asyncio.run(bot._dispatch_message(m)) # type: ignore[arg-type]
assert calls == ["message"], f"expected message fallback to fire for /unknown, got {calls}"
def test_chat_api_status_properties():
"""`initialized` and `started` reflect lifecycle state without invoking the FFI."""
api = ChatApi(ctrl=12345)
assert api.initialized is True
assert api.started is False
assert api.ctrl == 12345
# Simulate close: ctrl wiped, both properties false.
api._ctrl = None
api._started = False
assert api.initialized is False
assert api.started is False
with pytest.raises(RuntimeError, match="not initialized"):
_ = api.ctrl
def test_log_contacts_registers_handlers():
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
log_contacts=True,
log_network=False,
)
bot._register_log_handlers()
assert "contactConnected" in bot._event_handlers
assert "contactDeletedByContact" in bot._event_handlers
assert "hostConnected" not in bot._event_handlers
def test_log_network_registers_handlers():
bot = Bot(
profile=BotProfile(display_name="x"),
db=SqliteDb(file_prefix="/tmp/test"),
log_contacts=False,
log_network=True,
)
bot._register_log_handlers()
assert "hostConnected" in bot._event_handlers
assert "hostDisconnected" in bot._event_handlers
assert "subscriptionStatus" in bot._event_handlers
assert "contactConnected" not in bot._event_handlers
def test_middleware_registration_and_invocation_order():
"""Middleware registered first wraps middleware registered later (outer first)."""
bot = _bot()
calls: list[str] = []
class Outer(Middleware):
async def __call__(self, handler, message, data):
calls.append("outer-before")
await handler(message, data)
calls.append("outer-after")
class Inner(Middleware):
async def __call__(self, handler, message, data):
calls.append("inner-before")
await handler(message, data)
calls.append("inner-after")
bot.use(Outer())
bot.use(Inner())
assert len(bot._middleware) == 2
async def handler(msg):
calls.append("handler")
import asyncio
asyncio.run(bot._invoke_with_middleware(handler, message=object())) # type: ignore[arg-type]
assert calls == [
"outer-before",
"inner-before",
"handler",
"inner-after",
"outer-after",
]
packages/simplex-chat-python/tests/test_codegen.py
+41
View File
@@ -0,0 +1,41 @@
"""Sanity checks on auto-generated wire types — catches generator regressions."""
import typing
from simplex_chat.types import CC, CEvt, CR, T
def test_types_module_imports():
"""Every generated module imports cleanly with no SyntaxError."""
assert T is not None and CC is not None and CR is not None and CEvt is not None
def test_chat_type_is_literal_enum():
"""ChatType should be a Literal of expected member set."""
args = typing.get_args(T.ChatType)
assert "direct" in args
assert "group" in args
assert "local" in args
def test_known_command_has_cmd_string():
s = CC.APICreateMyAddress_cmd_string({"userId": 1})
assert s == "/_address 1"
def test_chat_response_tag_alias_present():
"""ChatResponse_Tag union of literals exists."""
assert hasattr(CR, "ChatResponse_Tag")
def test_chat_event_tag_alias_present():
"""ChatEvent_Tag exists; covers the on_event Literal annotation."""
assert hasattr(CEvt, "ChatEvent_Tag")
args = typing.get_args(CEvt.ChatEvent_Tag)
assert "newChatItems" in args
def test_chat_ref_cmd_string_direct():
"""Sanity check the codegen fix for ChatRef-bearing commands."""
assert T.ChatRef_cmd_string({"chatType": "direct", "chatId": 7}) == "@7"
assert T.ChatRef_cmd_string({"chatType": "group", "chatId": 42}) == "#42"
packages/simplex-chat-python/tests/test_filters.py
+83
View File
@@ -0,0 +1,83 @@
import re
from simplex_chat.filters import compile_message_filter
def _msg(content_type="text", text=None, chat_type="direct", group_id=None):
"""Build a minimal mock Message-like object for filter testing."""
class M:
pass
m = M()
m.content = {"type": content_type, "text": text} if text is not None else {"type": content_type}
m.chat_item = {
"chatInfo": {
"type": chat_type,
**({"groupInfo": {"groupId": group_id}} if chat_type == "group" else {}),
}
}
return m
def test_no_filters_matches_all():
f = compile_message_filter({})
assert f(_msg(content_type="text"))
assert f(_msg(content_type="image"))
def test_content_type_singular():
f = compile_message_filter({"content_type": "text"})
assert f(_msg(content_type="text"))
assert not f(_msg(content_type="image"))
def test_content_type_tuple_or():
f = compile_message_filter({"content_type": ("text", "image")})
assert f(_msg(content_type="text"))
assert f(_msg(content_type="image"))
assert not f(_msg(content_type="voice"))
def test_text_exact():
f = compile_message_filter({"text": "hello"})
assert f(_msg(text="hello"))
assert not f(_msg(text="world"))
def test_text_regex():
f = compile_message_filter({"text": re.compile(r"^\d+$")})
assert f(_msg(text="123"))
assert not f(_msg(text="abc"))
def test_when_callable():
f = compile_message_filter({"when": lambda m: m.content["type"] == "voice"})
assert f(_msg(content_type="voice"))
assert not f(_msg(content_type="text"))
def test_combined_and():
f = compile_message_filter({"content_type": "text", "text": re.compile(r"\d")})
assert f(_msg(content_type="text", text="abc123"))
assert not f(_msg(content_type="text", text="abc"))
assert not f(_msg(content_type="image"))
def test_chat_type_filter():
f = compile_message_filter({"chat_type": "group"})
assert f(_msg(chat_type="group", group_id=1))
assert not f(_msg(chat_type="direct"))
def test_group_id_filter():
f = compile_message_filter({"group_id": 42})
assert f(_msg(chat_type="group", group_id=42))
assert not f(_msg(chat_type="group", group_id=99))
assert not f(_msg(chat_type="direct"))
def test_group_id_tuple_or():
f = compile_message_filter({"group_id": (1, 2, 3)})
assert f(_msg(chat_type="group", group_id=2))
assert not f(_msg(chat_type="group", group_id=99))
packages/simplex-chat-python/tests/test_native_cache.py
+92
View File
@@ -0,0 +1,92 @@
import zipfile
from pathlib import Path
import pytest
from simplex_chat._native import _cache_root, _resolve_libs_dir, _download
def test_cache_root_linux(tmp_path, monkeypatch):
monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
monkeypatch.setattr("sys.platform", "linux")
assert _cache_root() == tmp_path / "simplex-chat"
def test_cache_root_macos(tmp_path, monkeypatch):
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
assert _cache_root() == tmp_path / "Library" / "Caches" / "simplex-chat"
def test_override_via_env(tmp_path, monkeypatch):
# _resolve_libs_dir intentionally does not validate the override directory —
# it returns it verbatim; the eventual ctypes.CDLL call surfaces any mistake.
monkeypatch.setenv("SIMPLEX_LIBS_DIR", str(tmp_path))
monkeypatch.setattr("sys.platform", "linux")
assert _resolve_libs_dir("sqlite") == tmp_path
def test_resolve_downloads_when_missing(tmp_path, monkeypatch):
monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
monkeypatch.setattr("sys.platform", "linux")
monkeypatch.setattr("simplex_chat._native._platform_tag", lambda: "linux-x86_64")
called = {}
def fake_download(target_root: Path, backend: str) -> None:
called["target"] = target_root
called["backend"] = backend
target_root.mkdir(parents=True, exist_ok=True)
(target_root / "libsimplex.so").touch()
monkeypatch.setattr("simplex_chat._native._download", fake_download)
libs_dir = _resolve_libs_dir("sqlite")
assert libs_dir == tmp_path / "simplex-chat" / "v6.5.1" / "sqlite"
assert called["backend"] == "sqlite"
assert (libs_dir / "libsimplex.so").exists()
def test_resolve_uses_cache_on_second_call(tmp_path, monkeypatch):
monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
monkeypatch.setattr("sys.platform", "linux")
cached = tmp_path / "simplex-chat" / "v6.5.1" / "sqlite"
cached.mkdir(parents=True)
(cached / "libsimplex.so").touch()
# Should NOT call _download — use the cached file.
monkeypatch.setattr(
"simplex_chat._native._download", lambda *a: pytest.fail("download should not be called")
)
assert _resolve_libs_dir("sqlite") == cached
def test_postgres_on_macos_rejected(monkeypatch):
monkeypatch.setattr("sys.platform", "darwin")
monkeypatch.setattr("simplex_chat._native._platform_tag", lambda: "macos-aarch64")
with pytest.raises(RuntimeError, match="postgres.*linux-x86_64"):
_resolve_libs_dir("postgres")
def test_atomic_install(tmp_path, monkeypatch):
"""Build a fake libs zip, mock _stream_to_file, verify extraction + atomic rename."""
# Build zip: libs/libsimplex.so + libs/libHS-stub.so
src = tmp_path / "src" / "libs"
src.mkdir(parents=True)
(src / "libsimplex.so").write_text("fake-so")
(src / "libHS-stub.so").write_text("fake-hs")
zip_path = tmp_path / "fake-libs.zip"
with zipfile.ZipFile(zip_path, "w") as zf:
for f in src.iterdir():
zf.write(f, f"libs/{f.name}")
def fake_stream(url, dest, *, timeout=60.0):
import shutil
shutil.copy(zip_path, dest)
monkeypatch.setattr("simplex_chat._native._stream_to_file", fake_stream)
monkeypatch.setattr("simplex_chat._native._platform_tag", lambda: "linux-x86_64")
target = tmp_path / "out"
_download(target, "sqlite")
assert (target / "libsimplex.so").read_text() == "fake-so"
assert (target / "libHS-stub.so").read_text() == "fake-hs"
packages/simplex-chat-python/tests/test_native_url.py
+55
View File
@@ -0,0 +1,55 @@
from unittest.mock import patch
import pytest
from simplex_chat._native import _platform_tag, _libs_url, _libname
@patch("sys.platform", "linux")
@patch("platform.machine", return_value="x86_64")
def test_platform_linux_x64(_):
assert _platform_tag() == "linux-x86_64"
@patch("sys.platform", "darwin")
@patch("platform.machine", return_value="arm64")
def test_platform_macos_arm64(_):
assert _platform_tag() == "macos-aarch64"
@patch("sys.platform", "win32")
@patch("platform.machine", return_value="AMD64")
def test_platform_windows_x64(_):
assert _platform_tag() == "windows-x86_64"
@patch("sys.platform", "freebsd")
@patch("platform.machine", return_value="x86_64")
def test_platform_unsupported(_):
with pytest.raises(RuntimeError, match="Unsupported"):
_platform_tag()
def test_libname_per_platform():
with patch("sys.platform", "linux"):
assert _libname() == "libsimplex.so"
with patch("sys.platform", "darwin"):
assert _libname() == "libsimplex.dylib"
with patch("sys.platform", "win32"):
assert _libname() == "libsimplex.dll"
@patch("simplex_chat._native._platform_tag", return_value="linux-x86_64")
def test_url_sqlite(_):
assert (
_libs_url("sqlite")
== "https://github.com/simplex-chat/simplex-chat-libs/releases/download/"
"v6.5.1/simplex-chat-libs-linux-x86_64.zip"
)
@patch("simplex_chat._native._platform_tag", return_value="linux-x86_64")
def test_url_postgres(_):
assert (
_libs_url("postgres")
== "https://github.com/simplex-chat/simplex-chat-libs/releases/download/"
"v6.5.1/simplex-chat-libs-linux-x86_64-postgres.zip"
)
packages/simplex-chat-python/tests/test_util.py
+175
View File
@@ -0,0 +1,175 @@
from simplex_chat import util
def test_chat_info_ref_direct():
ci = {"type": "direct", "contact": {"contactId": 7}}
assert util.chat_info_ref(ci) == {"chatType": "direct", "chatId": 7}
def test_chat_info_ref_group():
ci = {"type": "group", "groupInfo": {"groupId": 42}}
assert util.chat_info_ref(ci) == {"chatType": "group", "chatId": 42}
def test_chat_info_ref_group_with_member_support_scope():
ci = {
"type": "group",
"groupInfo": {"groupId": 42},
"groupChatScope": {"type": "memberSupport", "groupMember_": {"groupMemberId": 99}},
}
ref = util.chat_info_ref(ci)
assert ref == {
"chatType": "group",
"chatId": 42,
"chatScope": {"type": "memberSupport", "groupMemberId_": 99},
}
def test_chat_info_ref_group_with_member_support_scope_no_member():
ci = {
"type": "group",
"groupInfo": {"groupId": 42},
"groupChatScope": {"type": "memberSupport"},
}
ref = util.chat_info_ref(ci)
# No groupMember_ → no groupMemberId_ in the wire scope.
assert ref == {
"chatType": "group",
"chatId": 42,
"chatScope": {"type": "memberSupport"},
}
def test_chat_info_ref_returns_none_for_non_targets():
assert util.chat_info_ref({"type": "contactRequest"}) is None
assert util.chat_info_ref({"type": "contactConnection"}) is None
def test_chat_info_name_direct():
ci = {"type": "direct", "contact": {"profile": {"displayName": "Alice"}}}
assert util.chat_info_name(ci) == "@Alice"
def test_chat_info_name_group():
ci = {"type": "group", "groupInfo": {"groupProfile": {"displayName": "MyGroup"}}}
assert util.chat_info_name(ci) == "#MyGroup"
def test_chat_info_name_group_with_member_support():
ci = {
"type": "group",
"groupInfo": {"groupProfile": {"displayName": "MyGroup"}},
"groupChatScope": {
"type": "memberSupport",
"groupMember_": {"memberProfile": {"displayName": "Carol"}},
},
}
assert util.chat_info_name(ci) == "#MyGroup(support Carol)"
def test_chat_info_name_local():
assert util.chat_info_name({"type": "local"}) == "private notes"
def test_chat_info_name_contact_request():
ci = {"type": "contactRequest", "contactRequest": {"profile": {"displayName": "Eve"}}}
assert util.chat_info_name(ci) == "request from @Eve"
def test_chat_info_name_contact_connection():
assert util.chat_info_name({"type": "contactConnection", "contactConnection": {}}) == (
"pending connection"
)
assert (
util.chat_info_name({"type": "contactConnection", "contactConnection": {"localAlias": "X"}})
== "pending connection (X)"
)
def test_sender_name_direct_uses_chat_name():
ci = {"type": "direct", "contact": {"profile": {"displayName": "Alice"}}}
chat_dir = {"type": "directRcv"}
assert util.sender_name(ci, chat_dir) == "@Alice"
def test_sender_name_group_appends_member():
ci = {"type": "group", "groupInfo": {"groupProfile": {"displayName": "MyGroup"}}}
chat_dir = {"type": "groupRcv", "groupMember": {"memberProfile": {"displayName": "Bob"}}}
assert util.sender_name(ci, chat_dir) == "#MyGroup @Bob"
def test_contact_address_str_prefers_short():
assert util.contact_address_str({"connFullLink": "full", "connShortLink": "short"}) == "short"
def test_contact_address_str_falls_back_to_full():
assert util.contact_address_str({"connFullLink": "full"}) == "full"
def test_from_local_profile_strips_extras_and_undefined():
local = {
"displayName": "x",
"fullName": "X Y",
"shortDescr": None,
"image": "data:image/png;base64,...",
"contactLink": None,
"preferences": {},
"peerType": "bot",
"profileId": 99, # extra LocalProfile field
"localAlias": "alias", # extra LocalProfile field
}
p = util.from_local_profile(local)
assert p == {
"displayName": "x",
"fullName": "X Y",
"image": "data:image/png;base64,...",
"preferences": {},
"peerType": "bot",
}
def test_ci_content_text_rcv():
ci = {"content": {"type": "rcvMsgContent", "msgContent": {"type": "text", "text": "hello"}}}
assert util.ci_content_text(ci) == "hello"
def test_ci_content_text_snd():
ci = {"content": {"type": "sndMsgContent", "msgContent": {"type": "text", "text": "world"}}}
assert util.ci_content_text(ci) == "world"
def test_ci_content_text_other():
ci = {"content": {"type": "rcvGroupEvent"}}
assert util.ci_content_text(ci) is None
def test_ci_bot_command_match():
ci = {"content": {"type": "rcvMsgContent", "msgContent": {"type": "text", "text": "/ping"}}}
assert util.ci_bot_command(ci) == ("ping", "")
def test_ci_bot_command_with_args():
ci = {
"content": {"type": "rcvMsgContent", "msgContent": {"type": "text", "text": "/echo hi "}}
}
assert util.ci_bot_command(ci) == ("echo", "hi")
def test_ci_bot_command_not_a_command():
ci = {"content": {"type": "rcvMsgContent", "msgContent": {"type": "text", "text": "hello"}}}
assert util.ci_bot_command(ci) is None
def test_ci_bot_command_no_text():
ci = {"content": {"type": "rcvGroupEvent"}}
assert util.ci_bot_command(ci) is None
def test_reaction_text_emoji():
r = {"chatReaction": {"reaction": {"type": "emoji", "emoji": "🎉"}}}
assert util.reaction_text(r) == "🎉"
def test_reaction_text_tag():
r = {"chatReaction": {"reaction": {"type": "unknown", "tag": "thumbs_up"}}}
assert util.reaction_text(r) == "thumbs_up"
plans/2026-05-07-desktop-rtl-composer-fix.md
+390
View File
@@ -0,0 +1,390 @@
# Fix #4137 — desktop: RTL text rendering under send button
Target file:
`apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/platform/PlatformTextField.desktop.kt`
---
## 1. Problem statement
### 1.1 Symptom
On desktop, when the user types right-to-left text (Arabic, Hebrew,
Persian) in the chat composer **while the global system locale is LTR**,
the first characters of the typed text are rendered **under the send
button** at the bottom-right corner and become invisible while typing.
The same defect places the voice-preview / disabled-state
`ComposeOverlay` text on the wrong horizontal side in this configuration.
### 1.2 Configurations affected
Tested 4 combinations of (global locale × typed-text direction):
| Global locale | Typed text | Behavior |
|---------------|------------|----------|
| LTR | LTR | OK |
| LTR | RTL | **broken** — text under send button |
| RTL | LTR | OK |
| RTL | RTL | OK |
Only the LTR-locale + RTL-text combination is broken. This is the
configuration where the **inner text rendering direction** (forced RTL by
`decorationBox`) **disagrees** with the **outer layout direction** (LTR).
### 1.3 Why it matters
- Persian/Arabic/Hebrew users on a non-localized OS (very common: most
desktop installs default to English) cannot see the start of their own
message until it grows past the send button.
- The composer is the most-used input in the app; this is a daily
papercut for the affected user population.
---
## 2. Root cause
A direction-resolution decoupling introduced by an unrelated refactor.
Two commits matter:
### 2.1 The original RTL fix — #4675 (`2ae5a8bff`, Aug 2024)
Added padding logic *inside* a forced-RTL scope:
```kotlin
CompositionLocalProvider(LocalLayoutDirection provides Rtl) {
Column(Modifier.weight(1f).padding(start = startPadding, end = endPadding)) {
TextFieldDecorationBox(...)
}
}
```
Inside that scope `start` resolves to the **right** edge. So setting
`startPadding = 50.dp` for the RTL-text + LTR-locale case correctly
reserved 50dp on the visual right — same side as the send button.
**The padding side and button side were aligned by accident.** `start`
tracked the forced-RTL direction in the same way that `Alignment.BottomEnd`
in `SendMsgView.kt:120` tracked the global direction — and the two
happened to coincide *as long as those directions were the same.* The
pre-existing rule expressed in code was effectively "padding follows
typed-text direction," which was equivalent to "padding follows button
side" only when the inner forced direction and the outer global direction
agreed.
### 2.2 The breaking refactor — #5051 edge-to-edge (`4162bccc4`, Nov 2024)
The padding modifier was lifted **out** of the forced-RTL scope onto the
outer `BasicTextField` (the wrapping `Column` and `Row` were removed).
The outer modifier now resolves `start`/`end` against the **global**
layout direction, but `decorationBox` still forces
`LayoutDirection.Rtl` for RTL characters internally.
In LTR-global + RTL-text:
- `padding(start = 50.dp)` → 50dp reserved on visual **left**
- Text right-aligned by forced-RTL `decorationBox` → renders against
visual **right**
- 0dp on the right → text under the send button (which is at
`Alignment.BottomEnd` in LTR global = visual right)
The compensation logic written for the inner-scope semantics silently
became wrong when the modifier moved outward. Code compiled, tests passed,
behavior diverged.
### 2.3 The actual invariant the layout obeys
Reading the layout call graph (`SendMsgView` → `PlatformTextField`):
- `SendMsgView.kt:120` — `Box(Modifier.align(Alignment.BottomEnd)...)`
places the send button using the **global** layout direction.
- `PlatformTextField.desktop.kt` — `BasicTextField` modifier chain is
applied in the **global** layout direction.
The constraint is therefore exactly one rule:
> **The textfield must reserve space on the global layout direction's
> `end` — the same side `Alignment.BottomEnd` resolves to in the parent
> `Box`.**
Pre-PR code expressed a different (wrong) rule — "padding follows
typed-text direction" — which agreed with the actual invariant only when
no RTL-text/LTR-locale mismatch existed. The 4 of 4 case failure → 1 of 4
case failure shape is the signature of this kind of accidental alignment.
### 2.4 Why this is structural, not a typo
The defect is not a missing case — it is the **wrong rule**. Adding a
new branch (e.g. "if RTL-text + LTR-locale, swap padding sides
*again*") would silence the symptom while leaving the wrong rule in
place. The fix is to delete the wrong rule and write the actual
invariant.
---
## 3. Solution summary
Make the two conditional assignments that compute `startPadding` and
`endPadding` unconditional, taking the values they already produced in
the `else` branch:
```kotlin
val startPadding = 0.dp
val endPadding = startEndPadding
```
The surrounding code is unchanged — `startEndPadding`'s computation,
the `PaddingValues(startPadding, 12.dp, endPadding, 0.dp)` construction,
the `.padding(start = startPadding, end = endPadding)` modifier call,
and the original two-line comment all stay verbatim.
Master's `if (isRtlByCharacters && isLtrGlobally)` predicate split each
of `startPadding` and `endPadding` into two branches. In cases 1, 3, 4
the predicate is `false` and master takes the `else` branch — exactly
the values the surgical version produces unconditionally. Only case 2
(the bug) takes the `then` branch, and that branch reserves space on
the wrong horizontal side. Removing the predicate removes only case 2's
wrong values; cases 1/3/4 are byte-identical to master.
The 95dp/50dp distinction is preserved verbatim through `startEndPadding`,
which is unchanged.
`ComposeOverlay` (called twice at the bottom of `PlatformTextField`)
reuses the same `padding` value — its placement is corrected for the
same reason without an extra change.
**Net effect**: 2 lines changed.
---
## 4. Detailed technical design
### 4.1 Behavior matrix (post-fix)
| Case | Locale | Text | Master `(start, end)` | Surgical `(start, end)` | Button side |
|------|--------|------|-----------------------|-------------------------|-------------|
| 1 | LTR | LTR | `(0, 50)` | `(0, 50)` | right ✓ same |
| 2 | LTR | RTL | `(50, 0)` | `(0, 50)` | right ✓ **fix** |
| 2′ | LTR | RTL + empty + voice | `(95, 0)` | `(0, 95)` | right ✓ **fix** |
| 3 | RTL | LTR | `(0, 50)` | `(0, 50)` | left ✓ same |
| 4 | RTL | RTL | `(0, 50)` | `(0, 50)` | left ✓ same |
Three of the four pre-PR cases are byte-identical to the new code.
Only the broken case (LTR locale + RTL text) flips from `(50, 0)` to
`(0, 50)`, which matches the side where the send button resolves.
### 4.2 Why the 95dp condition stays exactly as-is
The 95dp special case fires only in RTL-text + LTR-locale + empty +
voice-button. In every other configuration, the placeholder text
either left-aligns (no collision with the right-side voice button row)
or sits on the visual side opposite to the buttons (RTL global puts
buttons on the left while forced-RTL placeholder displays on visual
right).
Only the RTL-text + LTR-global case puts a right-aligned placeholder
on the same side as the wider voice-button row. The condition is
intrinsic to the architecture (forced-RTL inside `decorationBox` while
the outer layout is global LTR), not a bug — it must be preserved.
### 4.3 What is *not* changed
Out of scope for #4137 — listed for clarity:
- The `CompositionLocalProvider` inside `decorationBox` that forces
`LayoutDirection.Rtl` for RTL-by-characters input (the BiDi-detection
workaround from #4675 itself).
- `lastTimeWasRtlByCharacters` state and `isRtl` detection on the first
50 characters of the message.
- The `ComposeOverlay` composable — it inherits the corrected
`padding`.
- `SendMsgView`, the `Alignment.BottomEnd` send button placement, and
the voice-button row layout.
- The Android implementation (`PlatformTextField.android.kt`) — uses
a native Android `EditText` with `setPaddingRelative`, which
resolves against the view's own layout direction; behavior is
unaffected and out of scope.
### 4.4 Properties of the resulting code
- The two adjacent conditional assignments dispatching on
`isRtlByCharacters && isLtrGlobally` (one for `startPadding`, one for
`endPadding`) become unconditional. The predicate is removed; the
`else` branch's values are lifted to the bare assignments.
- All four locals (`startEndPadding`, `startPadding`, `endPadding`,
`padding`) keep the same names and continue to exist.
- The `PaddingValues(startPadding, 12.dp, endPadding, 0.dp)` call and
the `.padding(start = startPadding, end = endPadding)` modifier are
unchanged.
- The original two-line comment is unchanged. "padding from right side
should be bigger" remains accurate — `endPadding` is still `95.dp`
vs `50.dp` under the same condition as before, just consistently on
the global end side.
- No behavior is removed: RTL detection, the `decorationBox` direction
override, overlay rendering, and the empty-text/voice-button 95dp
expansion are all retained verbatim.
- Diff size: 2 lines changed, one file. No reformatting of unrelated
code.
### 4.5 Risk surface
- **Compose 1.7.x BiDi engine** — unchanged; we still rely on
`decorationBox`'s forced direction for right-alignment of typed RTL
text. No new BiDi dependency.
- **Padding API** — `Modifier.padding(end = X.dp)` and
`PaddingValues(start, top, end, bottom)` are stable Compose APIs.
- **Direction resolution** — `Modifier.padding`'s start/end have
resolved against the enclosing `LocalLayoutDirection` since Compose
Foundation 1.0; no version-sensitive behavior.
- **Cross-platform** — Android implementation uses a native
`EditText`; no shared change required.
---
## 5. Detailed implementation plan
### 5.1 The exact edit
File:
`apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/platform/PlatformTextField.desktop.kt`
**Lines 89–90 — replace 2 lines:**
```kotlin
// remove
val startPadding = if (isRtlByCharacters && isLtrGlobally) startEndPadding else 0.dp
val endPadding = if (isRtlByCharacters && isLtrGlobally) 0.dp else startEndPadding
// add
val startPadding = 0.dp
val endPadding = startEndPadding
```
No other lines change. No imports added or removed. The comment, the
`startEndPadding` computation, the `PaddingValues` construction, and
the `.padding(start = startPadding, end = endPadding)` modifier are
all preserved verbatim.
### 5.2 Steps
1. Edit `PlatformTextField.desktop.kt` at the site above (lines 89–90).
2. Build desktop module:
`cd apps/multiplatform && ./gradlew :common:desktopMainClasses`
3. Run desktop app on an LTR system locale; type
`متن راست به چپ` in the composer; verify all characters visible.
4. Type ASCII; verify no regression.
5. Switch system locale to Arabic/Persian/Hebrew; repeat both inputs;
verify send button and reservation flip together to the visual
left, with no overlap.
6. Trigger voice preview / disabled-state placeholder in each
configuration; verify the overlay text is on the side opposite
the send button.
7. Commit on a topic branch (`nd/fix-RTL`); PR title:
`desktop: fix RTL text rendering under the send button`; reference
`Fixes #4137`.
### 5.3 Test matrix to verify manually
| # | Locale | Typed text | Empty + voice? | Expectation |
|---|--------|-----------|----------------|-------------|
| 1 | LTR | ASCII | n/a | unchanged from current |
| 2 | LTR | RTL chars | no | chars visible, no overlap with right-side button |
| 3 | LTR | empty | yes | placeholder + voice-button row both visible |
| 4 | LTR | (was RTL) → empty | yes | placeholder clears 95dp on right (sticky `lastTimeWasRtlByCharacters`) |
| 5 | RTL | ASCII | no | unchanged |
| 6 | RTL | RTL chars | no | unchanged |
| 7 | RTL | empty | yes | unchanged |
### 5.4 Rollback
Revert is one commit and one file. Behavior reverts cleanly.
---
## 6. Alternative approaches considered
### 6.1 Chosen approach — drop the buggy `then` branch (§3)
The 2-line surgical change. Removes the predicate from the
`startPadding` and `endPadding` assignments, keeping the (correct)
`else` branch values as the unconditional definition. Smallest
possible diff; preserves all variable names, the comment, the
`PaddingValues` call, and the `.padding(start, end)` modifier.
Fixes the overlay placement as a free byproduct.
### 6.2 Re-couple padding to inner forced direction by wrapping `BasicTextField`
Move the `CompositionLocalProvider(LocalLayoutDirection = Rtl)` *outside*
`BasicTextField` rather than inside `decorationBox`. The outer
`.padding(start, end)` would then resolve in the same direction as the
inner text, restoring the pre-#5051 invariant and letting the
historical `start = 50.dp / end = 0.dp` swap work again.
**Pros**: padding-vs-text consistency at the source.
**Cons**: also flips `fillMaxWidth`, `focusRequester`, `onPreviewKeyEvent`,
and the parent `Box`'s `Alignment.BottomEnd` resolution direction is
**still global** — so the textfield and the button align against
different directions, moving the mismatch instead of removing it.
Bigger refactor, broader test surface, no net gain. **Rejected.**
### 6.3 Remove the forced-RTL override; rely on Compose BiDi
Delete the `CompositionLocalProvider` inside `decorationBox`. Let
Compose's BiDi engine right-align RTL paragraphs without forcing a
paragraph direction. Then `start`/`end` resolve consistently against
the global direction everywhere; `isRtlByCharacters`,
`lastTimeWasRtlByCharacters`, and the 95dp special case can all be
deleted.
**Pros**: largest simplification — eliminates the entire BiDi-detection
state machine and the 95dp branch.
**Cons**: depends on Compose Desktop 1.7.x BiDi engine matching what
#4675 originally needed to enforce. If automatic BiDi is insufficient
(e.g. mixed Latin-RTL paragraphs, neutral characters at paragraph start,
numbers in RTL paragraphs), regressions reappear. Requires manual
verification across all the cases #4675 originally fixed. Out of scope
for #4137. **Reasonable follow-up; not part of this fix.**
### 6.4 Derive padding from measured button-row width
Refactor `SendMsgView` so the textfield's reservation comes from the
**measured** width of the button row (via `SubcomposeLayout` or shared
state), instead of hard-coded 50/95dp. The textfield would reserve
exactly as much as the buttons need, regardless of direction or button
configuration.
**Pros**: removes the 50/95dp magic numbers and the
`showVoiceButton`-dependent branch. Self-correcting if the button row
ever changes.
**Cons**: significantly larger refactor; `SubcomposeLayout` adds cost
to a frequently-recomposing view; doesn't fix the bug at hand any
better than §6.1. **Reasonable longer-term cleanup; not part of this
fix.**
### 6.5 Add a third special case for the failing combination
`if isRtlByCharacters && isLtrGlobally then padding(end=50) else
padding(start=startPadding, end=endPadding)`.
**Pros**: one-line behavior fix.
**Cons**: leaves the wrong rule in place plus a workaround on top.
Three branches where one suffices, and the underlying defect — padding
following typed-text direction instead of button side — is preserved
and now harder to spot. **Rejected as a workaround.**
---
## 7. Recommendation
Implement §3 (the chosen approach). It is the minimal structural
root-cause fix, also corrects the overlay placement as a free byproduct,
and removes the wrong-side `then` branch from both `startPadding` and
`endPadding`.
Defer §6.3 and §6.4 to separate PRs if desired — both are reasonable
cleanups but are not necessary to fix #4137 and would expand the blast
radius beyond the bug.
plans/2026-05-07-fullscreen-viewer-wrong-image.md
+135
View File
@@ -0,0 +1,135 @@
# Fullscreen image viewer: opens the wrong image
Design doc for the fix shipped in PR #6869.
## Problem
The fullscreen image viewer occasionally opened the chat's oldest media
instead of the image the user tapped. Reproductions were intermittent —
the gating condition turned out to be the runtime state of the
*immediately-older* sibling of the tapped item.
## Background — pager state model
`providerForGallery` (`apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatView.kt:3537`)
backs the fullscreen viewer with a virtual pager of 10000 pages. The
pager's state is two variables, captured in a closure:
- `initialIndex` — pager page that maps to the anchor item; starts at 5000.
- `initialChatId` — id of the anchored chat item; starts at the tapped item.
Invariant: page `initialIndex` always shows item `initialChatId`. Other
pages are computed by walking `chatItems` older / newer from the anchor
via the local `item()` helper.
`scrollToStart()` is called by `ImageFullScreenView.kt` to lock the
pager's leftward boundary at the user's current item, in two situations:
- **Init probe** (`ImageFullScreenView.kt:48-55`) — at viewer open, if
`getMedia(initialIndex - 1) == null` (no older sibling reachable),
reposition so the tapped item becomes page 0.
- **Runtime branch** (`ImageFullScreenView.kt:97-112`) — during scroll,
if `getMedia(index) == null` while the user is at `index + 1`, lock
the pager so the null page isn't reachable.
Both callers want the same outcome: **page 0 = the user's current
anchor item**, leftward = unreachable.
## Root cause
Pre-fix body of `scrollToStart`:
```kotlin
override fun scrollToStart() {
initialIndex = 0
initialChatId = chatItems.firstOrNull { canShowMedia(it) }?.id ?: return
}
```
The second line rewrote `initialChatId` to the chat's *oldest showable
media* — not the user's current anchor. This mismatched what both
callers wanted. It happened to coincide with the correct behavior when
the anchor already was the chat's oldest showable, which is why the bug
masked itself for years.
The bug surfaced when the init probe fired for a non-boundary reason:
- The immediately-older sibling existed and passed `canShowMedia` (file
marked loaded; file path resolved or remote was connected).
- But `getLoadedImage` returned `null` at decode time (undecodable
bytes, missing file on disk, crypto error).
- `getMedia(initialIndex - 1)` therefore returned `null`.
- The probe misread that null as "no older sibling exists" and called
`scrollToStart()`.
- `scrollToStart` rewrote `initialChatId` to the chat's oldest showable.
- Page 0 of the pager rendered that oldest item — the wrong image.
## Fix
Delete the second line. `scrollToStart` becomes:
```kotlin
override fun scrollToStart() {
initialIndex = 0
}
```
`initialChatId` is preserved across the call. Page 0 now maps to the
current anchor — exactly what both callers wanted from the start.
## Why this is correct for both callers
- **Init probe.** Before the call, `initialChatId` is the tapped item.
After the call, page 0 = tapped item. ✓
- **Runtime branch.** Before the call, `currentPageChanged` has already
updated `initialChatId` to the user's currently visible item. After
the call, page 0 = current item; the user's view is preserved with no
visible jump. (Pre-fix the user got teleported to the chat's oldest
media when a null sibling tripped this branch — a latent UX bug
resolved by the same one-line change.)
## Why a wider structural change is not in scope here
`getMedia` returns `null` for two distinct conditions: (a) navigation
found no showable item, (b) navigation found one but decode failed. A
deeper refactor would let consumers distinguish these. That refactor is
deliberately out of scope for this fix:
- The user-visible bug (wrong image) is fully resolved by the one-line
change. No additional code is required to address the report.
- The remaining symptom — locking the user out of older loadable items
behind one that fails to decode — is mild, pre-existing, and not part
of the report. If it becomes user-visible, address it in a follow-up.
- A wider refactor would expand the diff, the review surface, and the
regression risk for a fix that needs to ship promptly.
- `good-code-v5.md`: *"Find the minimal change. The smallest structural
modification that achieves the goal."* The smallest modification that
resolves the reported bug is the deletion of one line.
## Verification
`apps/multiplatform/common/src/commonTest/kotlin/chat/simplex/app/ProviderForGalleryTest.kt`:
- `testScrollToStartPreservesAnchor` — drives the public provider
interface: moves the anchor off `cItemId` via `currentPageChanged`,
calls `scrollToStart`, then reads the anchor back through `onDismiss`'s
`scrollTo` callback. Pre-fix would observe `scrollTo(2)` (the chat's
oldest); post-fix `scrollTo(1)` (anchor preserved).
- `testOnDismissOnActiveItemDoesNotScroll` — pins the `onDismiss`
early-return contract that the regression test reads through.
Manual sanity (Android + desktop): tap newest / oldest / a middle image
in a chat with multiple media — fullscreen opens on the tapped image in
each case; swipe in both directions still works.
## Alternatives considered and rejected
- **Distinguish "no item" from "load failed" inside `getMedia`.**
Requires either a return-type redesign (sealed result type) or an
added query method on the interface. Both expand the diff well beyond
what the user-visible bug requires. Deferred to a possible follow-up
if the milder remaining symptom is reported.
- **Hoist the local `item()` helper to a top-level testable function.**
The regression test exercises the public provider interface and
reads the anchor back via `onDismiss`'s `scrollTo` callback, so no
internal extraction is needed for testability.
plans/2026-05-07-simplex-chat-python-design.md
+575
View File
@@ -0,0 +1,575 @@
# SimpleX Chat Python library design
## Table of contents
- [What](#what)
- [Why](#why)
- [How](#how)
- [Architecture](#architecture)
- [Type generation](#type-generation)
- [Native lib loading](#native-lib-loading)
- [Public API](#public-api)
- [Distribution and CI](#distribution-and-ci)
- [Testing](#testing)
- [Open questions](#open-questions)
## What
A Python 3 client library `simplex-chat` on PyPI for SimpleX bots. Same capability as the Node.js library at `packages/simplex-chat-nodejs/`.
The user writes a Python script with decorator-registered handlers; the library does the rest:
```python
from simplex_chat import Bot, BotProfile, SqliteDb, TextMessage
bot = Bot(profile=BotProfile(display_name="Squarer"),
db=SqliteDb(file_prefix="./bot"),
welcome="Send a number, I'll square it.")
@bot.on_message(content_type="text")
async def square(msg: TextMessage) -> None:
try:
n = float(msg.text)
await msg.reply(f"{n} * {n} = {n * n}")
except ValueError:
await msg.reply("Not a number.")
if __name__ == "__main__":
bot.run()
```
`pip install simplex-chat`, run the script, done.
## Why
SimpleX has a Node.js library (`simplex-chat`) and Haskell-built native lib (`libsimplex.{so,dylib,dll}`) but no Python equivalent. Python is the dominant language for bot scripting, automation, and data integration. Without a Python client, those users either can't use SimpleX or have to bridge through Node.
The native `libsimplex` already exists as prebuilt artifacts (`simplex-chat/simplex-chat-libs` GitHub releases, one zip per platform/backend). The Haskell type metadata that drives the Node lib's TypeScript types is already in `bots/src/API/Docs/`. Both can be reused — adding Python bindings is mostly wiring, not a new system.
## How
Three pieces:
1. **Extend the existing Haskell type generator** in `bots/src/API/Docs/Generate/` to emit a Python types module alongside the existing TypeScript one. The metadata is the same; only the rendering changes. Already includes `pySyntaxText` (used today in COMMANDS.md docs) — just needs a Python codegen module.
2. **A new Python package** `packages/simplex-chat-python/` that wraps the prebuilt `libsimplex.*` via `ctypes`, downloading it on first use from the existing GitHub release. Async-only (`asyncio`), Python 3.11+. Single `Bot` class with decorator-registered handlers.
3. **One small CI job** appended to `.github/workflows/build.yml`, after the existing `release-nodejs-libs` job, that publishes the Python package to PyPI on each release tag. ~15 lines of YAML.
No new infrastructure: no separate libs build, no per-platform wheels, no PyPI size waiver, no second CI workflow. The libs zips that already exist for the Node lib are reused unchanged.
## Architecture
```
┌────────────────────────────────────────────────────────────┐
│ bots/src/API/Docs/ (Haskell, existing) │
│ ├── Types/Commands/Events/Responses │
│ ├── Syntax.hs (already has pySyntaxText) │
│ ├── Generate/TypeScript.hs (existing) │
│ └── Generate/Python.hs ← new │
└────────────────────┬───────────────────────────────────────┘
│ tests/APIDocs.hs runs both generators
▼ writes auto-gen Python type files
┌────────────────────────────────────────────────────────────┐
│ packages/simplex-chat-python/ (new) │
│ │
│ Bot ←── public API: decorators, lifecycle │
│ └── ChatApi ← escape hatch: raw command access │
│ └── core ← internal: typed FFI wrapper │
│ └── _native ← internal: ctypes + lazy DL │
│ ↓ │
│ libsimplex.{so,dylib,dll} │
│ downloaded from simplex-chat-libs releases │
└────────────────────────────────────────────────────────────┘
```
The split lets each layer be tested independently: `Bot`'s filter-routing without a real libsimplex (mock `api`), `core`'s JSON handling without ctypes (mock `_native`), `_native`'s download/ctypes work with a stub `.so`. Same shape as the Node lib (`bot.ts` → `api.ts` → `core.ts` → `simplex.cc`).
## Type generation
### New module: `bots/src/API/Docs/Generate/Python.hs`
Mirrors `Generate/TypeScript.hs` line-for-line. Reuses the existing data sources (`chatCommandsDocs`, `chatResponsesDocs`, `chatEventsDocs`, `chatTypesDocs`) and `pySyntaxText` from `Syntax.hs`. Output goes to `packages/simplex-chat-python/src/simplex_chat/types/` as four files: `_types.py`, `_commands.py`, `_responses.py`, `_events.py`.
### Type representation
Wire types are `TypedDict` + `Literal` discriminators (matches Node lib semantics — just shapes, no runtime cost; pyright narrows tagged unions correctly).
| Haskell | Python |
|---|---|
| `STRecord` | `class Foo(TypedDict)`; optional fields use `NotRequired[...]`. |
| `STUnion` / `STUnion1` | One `class Foo_<Tag>(TypedDict)` per member with `type: Literal["<tag>"]` discriminator. Type alias `Foo = Foo_A \| Foo_B \| …`. Tag alias `Foo_Tag = Literal["<tagA>", "<tagB>", …]`. |
| `STEnum` / `STEnum1` / `STEnum'` | Type alias `Foo = Literal["a", "b", "c"]`. |
| `ATPrim TBool` | `bool` |
| `ATPrim TString` | `str` |
| `ATPrim TInt`/`TInt64`/`TWord32` | `int` |
| `ATPrim TDouble` | `float` |
| `ATPrim TJSONObject` | `dict[str, object]` |
| `ATPrim TUTCTime` | `str` (ISO-8601, comment-annotated) |
| `ATOptional t` | `NotRequired[<t>]` in TypedDict fields; `<t> \| None` elsewhere |
| `ATArray {nonEmpty=False}` | `list[<elem>]` |
| `ATArray {nonEmpty=True}` | `list[<elem>]` with trailing `# non-empty` comment |
| `ATMap (PT k) v` | `dict[<k>, <v>]` |
| `ATDef` / `ATRef` | type name as forward-string reference `"<name>"` |
### Command serialization
Each command becomes a `TypedDict` plus a `<Type>_cmd_string(self) -> str` function. The function body is produced by `pySyntaxText` (which already emits Python expressions for the existing Markdown docs):
```python
class APICreateMyAddress(TypedDict):
userId: int
def APICreateMyAddress_cmd_string(self: APICreateMyAddress) -> str:
return '/_address ' + str(self['userId'])
APICreateMyAddress_Response = CR.UserContactLinkCreated | CR.ChatCmdError
```
### Field-naming convention
| Where | Style | Why |
|---|---|---|
| Auto-generated `types/_*.py` | **camelCase** | Round-trips JSON to/from libsimplex; the keys are the wire format. |
| Hand-written user-facing types (`SqliteDb`, `BotProfile`, `Message`, …) | **snake_case** | These are Python-side configs and wrappers, never reach `chat_send_cmd` directly. |
| `CryptoArgs` (`fileKey`, `fileNonce`) | **camelCase** | Returned by `chat_write_file` as JSON; round-trips wire format. |
| Method names | **snake_case** | PEP 8. |
| Type names | **PascalCase** | PEP 8 + Haskell parity. |
Generator must emit field names verbatim from `APIRecordField.fieldName'` — never transform.
### Wiring
Extend `tests/APIDocs.hs` with four `testGenerate` calls:
```haskell
describe "Python" $ do
it "generate python commands" $ testGenerate Py.commandsCodeFile Py.commandsCodeText
it "generate python responses" $ testGenerate Py.responsesCodeFile Py.responsesCodeText
it "generate python events" $ testGenerate Py.eventsCodeFile Py.eventsCodeText
it "generate python types" $ testGenerate Py.typesCodeFile Py.typesCodeText
```
`cabal test` regenerates all eight files (4 TS + 4 PY) and fails on drift — same enforcement loop that already governs the TypeScript files.
Add `API.Docs.Generate.Python` to `simplex-chat.cabal:572-580`.
## Native lib loading
### Approach: lazy download on first use
Single pure-Python wheel on PyPI (`simplex-chat`, ~100 KB). On first `Bot(...)` / `ChatApi.init(...)`, the library downloads the matching `libsimplex` zip from `simplex-chat/simplex-chat-libs` releases into a user cache, then `ctypes.CDLL`s it. Subsequent runs read from cache.
**Why not platform wheels?** Two reasons. First, simpler CI: one `python -m build` job vs a 5-platform matrix that has to download libs zips and rebuild wheels per platform. Second, the libs are already published as the source of truth (existing `release-nodejs-libs` job) — wheels would be a wrapper around those, adding nothing but build complexity. Tradeoff: first run requires internet; air-gap users set `SIMPLEX_LIBS_DIR=/path/to/libs`.
### Cache layout
```
~/.cache/simplex-chat/ # XDG_CACHE_HOME on Linux
└── v6.5.1/ # = LIBS_VERSION
├── sqlite/libsimplex.so + libHS*.so
└── postgres/libsimplex.so + libHS*.so
```
Platform-specific cache base: Linux `$XDG_CACHE_HOME`, macOS `~/Library/Caches/`, Windows `%LOCALAPPDATA%`.
### Version pinning
`src/simplex_chat/_version.py`:
```python
__version__ = "6.5.1" # PEP 440 — bumped with each Python package release
LIBS_VERSION = "6.5.1" # simplex-chat-libs release tag (no 'v' prefix)
```
`__version__` is read by hatchling for wheel metadata. `LIBS_VERSION` is read by `_native.py` for the download URL. Wrapper-only patch releases use a post-suffix (`__version__ = "6.5.1.post1"`, `LIBS_VERSION` unchanged). Same pattern as Node lib's `RELEASE_TAG = 'v6.5.1'`.
### `_native.py` responsibilities
1. **Detect platform.** `sys.platform` × `platform.machine()` → `linux-x86_64`, `linux-aarch64`, `macos-x86_64`, `macos-aarch64`, `windows-x86_64`. Unsupported combos raise immediately.
2. **Resolve backend** from the `Db` instance (`isinstance(db, SqliteDb)` → sqlite, `PostgresDb` → postgres). Module-level `threading.Lock` guards selection — first call wins for the process; subsequent call with a different backend raises (one libsimplex variant per process — Haskell RTS constraint).
3. **Resolve libs path.** If `SIMPLEX_LIBS_DIR` env is set, use it directly. Otherwise: `~/.cache/simplex-chat/v{LIBS_VERSION}/{backend}/`, downloading if missing.
4. **Download URL** (`LIBS_VERSION` is stored without 'v' prefix; URL re-adds it):
```
https://github.com/simplex-chat/simplex-chat-libs/releases/download/v{LIBS_VERSION}/simplex-chat-libs-{platform}-{arch}{-postgres?}.zip
```
5. **Atomic install.** Download to sibling tempdir → `zipfile.extractall` → `os.replace` the `libs/` subdir into cache. The libs zip contains only regular files (no symlinks — `build.yml:751-781` builds it via `cp *.so` which resolves them), so plain `extractall` is sufficient. Two processes racing safely both extract; whichever rename lands first wins, contents identical.
6. **Load and init.** `ctypes.CDLL(libs_dir / libname)` once per process; declare `restype`/`argtypes` for the 8 FFI functions; call `hs_init_with_rtsopts` exactly once with `+RTS -A64m -H64m -xn --install-signal-handlers=no` (or without `-xn` on Windows — matches `cpp/simplex.cc:13-32`).
7. **Buffer ownership.** Haskell allocates result strings; caller must `free()` after copying. Declare `restype = c_void_p` (NOT `c_char_p`, which auto-converts to bytes and discards the pointer needed for free):
```python
ptr = lib.chat_send_cmd(ctrl, cmd_bytes)
if not ptr: raise RuntimeError("null result")
try: result = ctypes.string_at(ptr).decode("utf-8")
finally: libc.free(ptr)
```
`libc` is `ctypes.CDLL(None)` on Linux/macOS, `ctypes.CDLL("msvcrt")` on Windows. Mirrors `HandleCResult` in `cpp/simplex.cc:157-165`.
### Override / pre-fetch
```bash
# Skip download — for Docker / air-gapped
SIMPLEX_LIBS_DIR=/opt/simplex/libs python my_bot.py
# Pre-fetch in Dockerfile RUN step (avoids redundant download per container start)
python -m simplex_chat install --backend=sqlite
python -m simplex_chat install --backend=postgres
```
### Failure modes
| Condition | Behavior |
|---|---|
| Unsupported platform/arch | Raise on first FFI call with explicit list of supported combinations. |
| Postgres on non-Linux-x86_64 | Raise — matches existing constraint in `download-libs.js:15-18`. |
| Download network/HTTP error | Propagate `urllib.error.URLError` with the URL. |
| Two processes downloading simultaneously | Both extract to sibling temp dirs; rename is atomic; identical contents → safe. |
| Two `Bot()` / `ChatApi.init()` calls in same process with different backends | Second raises — one libsimplex variant per process. |
| Two `Bot()` instances same backend, same process | Permitted — each has its own controller (`chat_ctrl`). |
## Public API
See the [Architecture](#architecture) section for the layering. This section specifies each layer's surface.
### Construction
User-facing config types are `@dataclass(slots=True)`, snake_case fields.
```python
@dataclass(slots=True)
class SqliteDb:
file_prefix: str
encryption_key: str | None = None
@dataclass(slots=True)
class PostgresDb:
connection_string: str
schema_prefix: str | None = None
Db = SqliteDb | PostgresDb # discriminated by isinstance()
@dataclass(slots=True)
class BotProfile:
display_name: str
full_name: str = ""
short_descr: str | None = None
image: str | None = None
@dataclass(slots=True)
class BotCommand:
keyword: str
label: str
class Bot:
def __init__(
self, *,
profile: BotProfile,
db: Db,
welcome: str | T.MsgContent | None = None,
commands: list[BotCommand] | None = None, # None → []
confirm_migrations: MigrationConfirmation = MigrationConfirmation.YES_UP,
# behavioral toggles — mirror BotOptions in Node lib
create_address: bool = True,
update_address: bool = True,
update_profile: bool = True,
auto_accept: bool = True,
business_address: bool = False,
allow_files: bool = False,
use_bot_profile: bool = True,
log_contacts: bool = True,
log_network: bool = False,
) -> None: ...
@property
def api(self) -> ChatApi: ...
```
### Handler registration
Three decorators. Filters are kwargs combined with **AND**; tuples within a kwarg are **OR**; arbitrary predicates use `when=`.
```python
class Bot:
def on_message(self, *,
content_type: T.MsgContent_Tag | tuple[T.MsgContent_Tag, ...] | None = None,
text: str | re.Pattern | None = None, # exact match or regex.search()
chat_type: T.ChatType | tuple[T.ChatType, ...] | None = None, # direct/group/local
from_role: T.GroupMemberRole | tuple[T.GroupMemberRole, ...] | None = None,
from_contact_id: int | tuple[int, ...] | None = None,
from_member_id: int | tuple[int, ...] | None = None,
group_id: int | tuple[int, ...] | None = None,
when: Callable[[Message], bool] | None = None,
) -> Callable[[MessageHandler], MessageHandler]: ...
def on_command(self, name: str | tuple[str, ...], *,
args: str | re.Pattern | None = None, # match command argument string
chat_type: T.ChatType | tuple[T.ChatType, ...] | None = None,
from_role: T.GroupMemberRole | tuple[T.GroupMemberRole, ...] | None = None,
from_contact_id: int | tuple[int, ...] | None = None,
group_id: int | tuple[int, ...] | None = None,
when: Callable[[Message], bool] | None = None,
) -> Callable[[CommandHandler], CommandHandler]: ...
# Multiple handlers per tag dispatch in registration order.
def on_event(self, event: CEvt.Tag, /,
) -> Callable[[EventHandler], EventHandler]: ...
def use(self, middleware: Middleware) -> None: ...
MessageHandler = Callable[[Message], Awaitable[None] | None]
CommandHandler = Callable[[Message, ParsedCommand], Awaitable[None] | None]
EventHandler = Callable[[CEvt.ChatEvent], Awaitable[None] | None]
```
`from_role` on direct chats: silent skip (not a runtime error).
### Message wrapper and content-narrowed types
`Message[C]` is generic in its content variant; concrete subclass aliases (`TextMessage`, `ImageMessage`, …) bind to the auto-generated `T.MsgContent_*` types. Decorator overloads narrow the handler parameter when `content_type` is a single `Literal`, so pyright sees the right concrete type.
```python
C = TypeVar("C", bound=T.MsgContent) # bound covers the unparameterized case
@dataclass(slots=True, frozen=True)
class Message(Generic[C]):
chat_item: T.AChatItem # raw wire object — fields below this point are camelCase
content: C # narrowed when filter pins content_type
bot: Bot
@property
def chat_info(self) -> T.ChatInfo: ... # shortcut for chat_item["chatInfo"]
@property
def text(self) -> str | None: ... # shortcut; non-Optional for TextMessage
async def reply(self, text: str) -> Message: ...
async def reply_content(self, content: T.MsgContent) -> Message: ...
async def react(self, emoji: str) -> None: ...
async def delete(self) -> None: ...
async def forward(self, to: T.ChatRef) -> Message: ...
# Concrete narrowed aliases — exported from simplex_chat/__init__.py
TextMessage = Message[T.MsgContent_Text]
ImageMessage = Message[T.MsgContent_Image]
FileMessage = Message[T.MsgContent_File]
VoiceMessage = Message[T.MsgContent_Voice]
# … one per MsgContent variant
@dataclass(slots=True, frozen=True)
class ParsedCommand:
keyword: str
args: str
```
Decorator overloads (one per `T.MsgContent_*` variant — ~15 lines, hand-written in `bot.py`):
```python
class Bot:
@overload
def on_message(self, *, content_type: Literal["text"], **rest: Any
) -> Callable[[Callable[[TextMessage], Awaitable[None] | None]], ...]: ...
@overload
def on_message(self, *, content_type: Literal["image"], **rest: Any
) -> Callable[[Callable[[ImageMessage], Awaitable[None] | None]], ...]: ...
# … one overload per MsgContent variant …
@overload
def on_message(self, *, content_type: tuple[T.MsgContent_Tag, ...] | None = None,
**rest: Any) -> Callable[[Callable[[Message], Awaitable[None] | None]], ...]: ...
```
`@bot.on_message(content_type="text")` → handler typed as `TextMessage`, so `msg.text: str` (non-Optional).
**Field-naming boundary in `Message`.** Wrapper properties (`msg.chat_info`, `msg.content`, `msg.text`) are snake_case. Descending into raw wire data via `msg.chat_item[...]` reverts to camelCase — same as accessing `T.AChatItem` returned by `bot.api`. Property shortcuts cover the common paths so most handlers never touch `chat_item` directly.
### Lifecycle
```python
class Bot:
# Blocking convenience — runs asyncio.run(self.serve_forever()), installs SIGINT
# via loop.add_signal_handler() (POSIX) or signal.signal() (Windows). Recommended for scripts.
def run(self) -> None: ...
# Embedding form — caller owns the loop and signal handling.
async def __aenter__(self) -> Bot: ...
async def __aexit__(self, *exc_info: object) -> None: ...
# Concurrent calls raise RuntimeError("already serving"). Re-callable after a clean stop().
async def serve_forever(self) -> None: ...
# Marks bot for shutdown. Safe from signal handler, another coroutine, or another thread.
def stop(self) -> None: ...
```
### Middleware
aiogram pattern. A class with `async __call__(handler, message, data)` wraps every **handler invocation** (per-message-per-matching-handler). `data: dict[str, object]` is the cross-cutting injection channel.
```python
class Middleware:
async def __call__(self,
handler: Callable[[Message, dict[str, object]], Awaitable[None]],
message: Message,
data: dict[str, object]) -> None:
await handler(message, data)
```
- **Invocation count.** A `newChatItems` event with N items × M matching handlers triggers N×M middleware calls. Per-event hooks should use `on_event`.
- **Exception propagation.** Handler exceptions propagate outward through the middleware stack. The outermost middleware can catch and swallow. Uncaught exceptions are logged via `logging.getLogger("simplex_chat")` and the chain moves to the next handler — the bot does not stop on individual handler errors. The receive loop only stops on a fatal `_native`/`core` error or explicit `bot.stop()`.
- **Order.** Registered via `bot.use(...)`. Called in registration order (first registered = outermost wrap).
### Event-loop semantics
`Bot` runs one event-receiver coroutine looping `chat_recv_msg_wait` (in `asyncio.to_thread`):
1. All `on_event(tag)` handlers for the event's `type` field — registration order, sequentially.
2. If event is `newChatItems`: for each chat item, run **all matching message handlers** (each through the middleware stack, in registration order). For each command-parseable text item, also run matching command handlers.
Handlers run **sequentially within an event**. Events are processed **sequentially**. Long-running work that shouldn't block the next event must `asyncio.create_task(...)` explicitly.
`bot.api.api_xxx(...)` calls are safe during `serve_forever` — same controller, serialized through `chat_send_cmd`. Calling them from inside a handler is the normal pattern (`msg.reply()` does exactly this).
### `ChatApi` (escape hatch)
Reached via `bot.api`. ~40 async methods, one per Node `apiXxx` (api.ts:344-958). Full enumeration deferred to implementation; representative examples:
```python
class ChatApi:
@classmethod
async def init(cls, db: Db,
confirm: MigrationConfirmation = MigrationConfirmation.YES_UP) -> ChatApi: ...
async def start_chat(self) -> None: ...
async def stop_chat(self) -> None: ...
async def close(self) -> None: ...
async def send_chat_cmd(self, cmd: str) -> CR.ChatResponse: ...
async def recv_chat_event(self, wait_us: int = 5_000_000) -> CEvt.ChatEvent | None: ...
async def api_create_user_address(self, user_id: int) -> T.CreatedConnLink: ...
async def api_send_text_message(self, chat: T.ChatRef, text: str,
in_reply_to: int | None = None) -> list[T.AChatItem]: ...
async def api_get_chats(self, user_id: int, pagination: T.PaginationByTime,
query: T.ChatListQuery | None = None) -> list[T.AChat]: ...
# ... etc
```
TS `apiCreateUserAddress` → Python `api_create_user_address` (PEP 8). Wire-format type names (`T.AChatItem`, `T.UserContactLink`, …) keep their Haskell/TS spelling to match JSON keys.
### Embedding example
```python
import asyncio
from simplex_chat import Bot, BotProfile, SqliteDb
async def main():
async with Bot(profile=..., db=...) as bot:
@bot.on_message(content_type="text")
async def echo(msg):
await msg.reply(msg.text)
await asyncio.gather(bot.serve_forever(), other_task())
asyncio.run(main())
```
## Distribution and CI
### Project layout
```
packages/simplex-chat-python/
├── pyproject.toml # hatchling, requires-python >= 3.11, no runtime deps
├── README.md
├── LICENSE # AGPL-3.0
├── src/simplex_chat/
│ ├── __init__.py # exports Bot, BotProfile, BotCommand, SqliteDb, PostgresDb,
│ │ # Message + TextMessage/ImageMessage/… aliases, ParsedCommand,
│ │ # ChatApi, MigrationConfirmation, Middleware, ChatAPIError
│ ├── _version.py # __version__ + LIBS_VERSION
│ ├── _native.py # ctypes + lazy lib download (internal)
│ ├── __main__.py # python -m simplex_chat install ...
│ ├── core.py # internal typed FFI wrapper
│ ├── api.py # ChatApi class — escape hatch
│ ├── bot.py # Bot class, decorators, Message wrapper, lifecycle
│ ├── filters.py # filter kwarg compilation; predicate combinators
│ ├── util.py # stateless helpers (chat_info_ref, ci_content_text, reaction_text, …)
│ ├── py.typed # PEP 561 marker
│ └── types/
│ ├── __init__.py # re-exports T, CC, CR, CEvt
│ ├── _types.py # AUTOGEN
│ ├── _commands.py # AUTOGEN
│ ├── _responses.py # AUTOGEN
│ └── _events.py # AUTOGEN
├── examples/
│ └── squaring_bot.py
└── tests/
```
### `pyproject.toml`
```toml
[build-system]
requires = ["hatchling>=1.24"]
build-backend = "hatchling.build"
[project]
name = "simplex-chat"
description = "SimpleX Chat Python library for chat bots"
license = "AGPL-3.0"
authors = [{name = "SimpleX Chat"}]
requires-python = ">=3.11"
dynamic = ["version"]
[tool.hatch.version]
path = "src/simplex_chat/_version.py"
[tool.hatch.build.targets.wheel]
packages = ["src/simplex_chat"]
```
No runtime Python dependencies (ctypes, urllib, zipfile are stdlib).
### CI publishing
One job appended to `.github/workflows/build.yml`, after `release-nodejs-libs`:
```yaml
publish-python:
needs: [release-nodejs-libs]
if: startsWith(github.ref, 'refs/tags/v')
runs-on: ubuntu-latest
permissions: { id-token: write } # OIDC, no API key
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v5
with: { python-version: "3.11" }
- run: pip install build && python -m build --wheel
working-directory: packages/simplex-chat-python
- uses: pypa/gh-action-pypi-publish@release/v1
with: { packages-dir: packages/simplex-chat-python/dist }
```
Triggered by the same `vX.Y.Z` tag that already drives the desktop and libs releases.
### One-time setup
1. Verify PyPI package name `simplex-chat` is available; register it.
2. On PyPI project page, configure trusted publisher → repo `simplex-chat/simplex-chat`, workflow `build.yml`, job `publish-python`.
## Testing
Three levels:
1. **Codegen drift** — `tests/APIDocs.hs` adds Python generators alongside TypeScript. Same `testGenerate` mechanism enforces that committed `_types.py` etc. equal the generator output.
2. **Python unit tests** — `pytest`, no real libsimplex needed:
- `test_native.py`: mock `urllib.request.urlretrieve` + `zipfile.ZipFile`; assert correct URL, atomic rename, cache hit on second call, override-env behavior, postgres-on-mac rejection.
- `test_codegen.py`: import every type from `simplex_chat.types`, sanity-check that `T.ChatType` is `Literal[...]` of expected size, etc. Catches generator regressions.
- `test_smoke.py`: build a fake `.so` (small C file with stub `chat_send_cmd` returning canned JSON, compiled per-test), point `SIMPLEX_LIBS_DIR` at it, run `Bot.__aenter__` → handler dispatch. Verifies FFI plumbing without real Haskell.
3. **Integration** — `examples/squaring_bot.py` runs against real libsimplex. Not in CI (needs network + persistent state).
## Open questions
1. **Linux ARM64.** Existing `simplex-chat-libs` releases ship `linux-x86_64`, `macos-x86_64`, `macos-aarch64`, `windows-x86_64` — no `linux-aarch64`. Python lib will fail with a clear message there. Adding it requires changes to the existing `release-nodejs-libs` job in `build.yml` (out of scope for this spec).
2. **`asyncio.to_thread` pool sizing.** Long-blocking `chat_recv_msg_wait` calls (default 5 s) pin executor threads. The default asyncio pool is unbounded but recycled. Bots running many concurrent chats may need a custom executor — first-pass uses `asyncio.to_thread`; document recommended pool sizing in README if it becomes a problem.
plans/2026-05-07-simplex-chat-python-implementation.md
+2348
View File
File diff suppressed because it is too large Load Diff
plans/2026-05-08-desktop-text-selection-id-anchored.md
+145
View File
@@ -0,0 +1,145 @@
# Desktop Text Selection — Anchor by Item Id
## 1. The bug
`SelectionRange` stored two **positional** indices into the reversed merged-items list:
```kotlin
data class SelectionRange(
val startIndex: Int,
val startOffset: Int,
val endIndex: Int,
val endOffset: Int
)
```
`reversedChatItems` grows from the front: a new message is prepended at index 0, every existing item shifts +1. Selection indices were never adjusted, so once the user had a selection on a message and another message arrived (or was sent), the indices kept pointing to the same numerical positions while the items at those positions had changed. The highlight (and the copy result) silently moved onto neighbouring messages.
Same root cause for the deletion case: removing an item from the list left selection indices pointing into a different item.
## 2. Root cause
Selection is **about items**, not positions. Storing positions into a list whose front grows is structurally wrong. The data structure must encode the stable identity (`ChatItem.id`), not the volatile position.
Two ingredients are mandatory for any correct fix:
1. **Remember which items** are anchor and focus (their stable `ChatItem.id`s).
2. **Update the positional indices** when the list mutates, so that everything downstream that reads `range.startIndex` / `range.endIndex` (highlight rendering, copy iteration, snap, copy-button placement, anchor/focus detection in `setupItemSelection` / `setupEmojiSelection`, drag direction in `SelectionCopyButton`) stays correct.
Anything beyond this is structural overreach.
## 3. Approaches considered
| # | Approach | Note |
|---|----------|------|
| A | Replace positional indices with ids in `SelectionRange`; cache items on the manager via `mutableStateOf`; expose indices via `derivedStateOf`; rename every reader from `range?.startIndex` to `manager.startIndex`; move top-level `selectedRange` into the manager as a method. | Structurally clean (single source of truth = ids), but renames every reader and moves a function for no behaviour reason. Ripples through `setupItemSelection`, `setupEmojiSelection`, `SelectionCopyButton`, `getSelectedCopiedText`, `snapSelection`, `copyButtonOffset`. |
| B | Same as A but replace the cached `var items` with `var mergedItemsState: State<MergedItems>?` (mirrors the existing `listState` field; eliminates duplicated state and the items-sync line in `SideEffect`). | Marginal improvement; the cost is still the renames and the function move, neither of which the bug requires. |
| C | **Final** — keep positional indices in `SelectionRange`, **add** `startItemId, endItemId` alongside them; resync the indices to the items they were anchored to on every recomposition via a `SideEffect`. | Every existing reader of `range.startIndex` / `range.endIndex` keeps working unchanged. The fix is a pure addition. |
Approach C accepts one piece of structural duplication that A and B do not have: anchor ids and positional indices coexist in `SelectionRange`, kept consistent by `resyncIndices`. For a bug-fix change, the trade-off favours diff minimality — migrating to a single source of truth (ids only, indices derived) is a separate refactor that should not be bundled with a fix.
## 4. Final implementation
### 4.1 `SelectionRange` — two new fields
```kotlin
data class SelectionRange(
val startIndex: Int,
val startItemId: Long, // NEW — stable anchor for the selection start
val startOffset: Int,
val endIndex: Int,
val endItemId: Long, // NEW — stable anchor for the selection focus
val endOffset: Int,
)
```
Existing `r.copy(startOffset = …)`, `r.copy(endOffset = …)`, `r.copy(startOffset = …, endOffset = …)` calls in `setAnchorOffset` / `updateFocusOffset` / `snapSelection` automatically preserve the new fields (data-class `copy` semantics). No change to those methods.
### 4.2 `SelectionManager` — one new field, two body additions, one new method
```kotlin
var mergedItemsState: State<MergedItems>? = null // mirrors existing listState
```
`startSelection` looks up the id once at click time:
```kotlin
fun startSelection(startIndex: Int, anchorY: Float, anchorX: Float) {
val id = mergedItemsState?.value?.items?.getOrNull(startIndex)?.newest()?.item?.id ?: return
range = SelectionRange(startIndex, id, -1, startIndex, id, -1)
selectionState = SelectionState.Selecting
anchorWindowY = anchorY
anchorWindowX = anchorX
}
```
`updateFocusIndex` updates `endItemId` whenever it updates `endIndex` (called both from `updateDragFocus` and from the scroll snapshotFlow — both paths covered by this single method):
```kotlin
fun updateFocusIndex(index: Int) {
val r = range ?: return
val id = mergedItemsState?.value?.items?.getOrNull(index)?.newest()?.item?.id ?: return
range = r.copy(endIndex = index, endItemId = id)
}
```
New method:
```kotlin
fun resyncIndices() {
val r = range ?: return
val items = mergedItemsState?.value?.items ?: return
val newStartIndex = items.indexOfFirst { it.newest().item.id == r.startItemId }
val newEndIndex = items.indexOfFirst { it.newest().item.id == r.endItemId }
if (newStartIndex < 0 || newEndIndex < 0) clearSelection()
else range = r.copy(startIndex = newStartIndex, endIndex = newEndIndex)
}
```
### 4.3 `SelectionHandler` — three new lines
```kotlin
manager.listState = listState
manager.mergedItemsState = mergedItems // NEW — wires items into the manager
manager.onCopySelection = { … }
// Resync after the items list mutates (new message arrives, item deleted).
SideEffect { manager.resyncIndices() } // NEW — the trigger
```
### 4.4 What is *not* changed
- `selectedRange(range, index)` — still a top-level function with its existing signature.
- `getSelectedCopiedText(items, revealedItems, linkMode)` — same signature, same body.
- `snapSelection(items, linkMode)` — same signature, same body.
- `copyButtonOffset(...)` — uses `r.endIndex` directly; no change.
- `setupItemSelection`, `setupEmojiSelection`, `SelectionCopyButton` — every `range?.startIndex` / `range?.endIndex` reference is preserved verbatim.
- `startDragSelection`, `updateDragFocus`, `startSelection` (signature), `updateFocusIndex` (signature) — unchanged. `mergedItemsState` is reached via the manager's own field, so callers don't thread items.
This is the structural property that compresses the diff: callers see no API change, and the file's structure (top-level `selectedRange`, top-level `selectedItemCopiedText`, top-level `snapOffset`, top-level extension helpers) is untouched.
## 5. Why this works in Compose
`SideEffect { manager.resyncIndices() }` runs after every successful composition of `SelectionHandler`. `SelectionHandler` returns a `Modifier` (non-Unit return → non-skippable), so it re-runs whenever its caller (`ChatView`) re-runs, which `ChatView` does whenever `mergedItems.value` changes (it iterates the items list directly). Within the same Compose frame, the `SideEffect` mutation of `range` invalidates the children that read `range`, and Compose re-runs them to convergence before commit. Net visible result: the selection highlight stays on the originally selected items on the same frame the new message arrives — same fidelity as a `derivedStateOf`-based approach, no observable lag.
`mergedItemsState` is a plain `var` (not `mutableStateOf`) — this is fine because (a) it is reassigned on every recomposition of `SelectionHandler` to the same `State<MergedItems>` reference, and (b) the values inside it are read through `State.value`, which Compose tracks. The pattern is identical to the existing `var listState: State<LazyListState>? = null` field on the manager.
## 6. Behaviour changes — full inventory
1. **Selection follows the original messages when the items list mutates.** This is the bug fix.
2. **Selection clears if either anchor item is removed from the list** (e.g. message deleted from another session). Previously, indices silently slid onto neighbouring messages. The new behaviour is `clearSelection()` when `indexOfFirst` returns -1. This is a side-effect of anchoring by id — once the anchor is gone, "the selection" is no longer well-defined. It is the same class of bug as #6.1 and is fixed by the same mechanism.
3. **Defensive `?: return` in `startSelection` and `updateFocusIndex`** when the id lookup fails. In practice this branch is unreachable: `mergedItemsState` is wired before any user input; the index passed in always comes from `resolveIndexAtY` (which only returns visible-item indices); `newest().item` is non-null for any merged item. No observable change, but worth flagging for completeness.
Nothing else changes. Verified by reading the diff against master line-by-line.
## 7. Verification
1. **Linux desktop build** succeeded end-to-end, producing `SimpleX_Chat-x86_64.AppImage`. No compilation errors, no Compose runtime issues from the new field on the manager or the new fields on `SelectionRange`.
2. **Manual flow against the test plan**: selection persists across `new-message-arrives`, `new-message-sent`, multi-item span; deletion clears (see §6.2); drag-select & copy button behaviour preserved.
## 8. Trade-offs and follow-ups
The two pieces of structural debt this change knowingly leaves in place:
1. **Anchor ids and positional indices coexist in `SelectionRange`.** Single source of truth would store only ids and derive indices on read. The cost of unifying is the rename and function-move churn, which is independent of this bug. A follow-up could collapse these into ids-only without behaviour change, scoped to its own commit.
2. **`resyncIndices` runs on every recomposition of `SelectionHandler`.** The two `indexOfFirst` calls are O(n) on the items list. If profiling ever shows this on a hot path, the cheap fix is to gate on the pointer identity of the items list (`if (lastResyncedItems !== items) { … }`) — one extra field, one branch. Not worth doing speculatively.
plans/2026-05-08-fix-select-in-reports.md
+182
View File
@@ -0,0 +1,182 @@
# Fix copying selected text in reports
PR: [#6863](https://github.com/simplex-chat/simplex-chat/pull/6863) · branch `nd/fix-select-in-reports` · final commit `96d6f3222`
## 1. Problem statement
Report items in desktop render as a red italic *reason prefix* followed by the user's comment, e.g. `Spam: hi @alice`. The user reported that selecting `Spam: test` and pressing Ctrl-C / clicking the copy button placed only `test` on the clipboard — the `Spam: ` prefix was silently dropped. Selecting *only* the prefix produced an empty clipboard.
A second symptom existed for any report whose comment contained a transformed segment (mention with `localAlias`, link with `showText`): dragging a selection boundary inside that segment snapped to the wrong character on release, then copy emitted the wrong text.
Both symptoms have a single cause and the bug is desktop-only because the touch UI does not use this selection path.
## 2. Solution summary
`MarkdownText` builds the on-screen `AnnotatedString` as `[prefix][body]` (one composable, one layout). Compose's `layout.getOffsetForPosition(...)` therefore returns selection offsets in **display-text space**, which includes the prefix. Pre-PR, `selectedItemCopiedText` and `snapOffset` walked `ci.formattedText` from `displayOffset = 0` — i.e. they treated those offsets as **prefix-excluded body offsets**. Every offset for a report was off by `prefix.length`.
The fix is one structural realisation: the prefix is the **leading display-space segment**, so the loop that walks `ci.formattedText` must start at `displayOffset = prefix.length`, and any portion of the selection that falls in `[0, prefix.length)` must be emitted by appending a slice of the prefix string before the loop runs.
To prevent the same silent decoupling from re-emerging, the prefix string itself is extracted into a single source of truth — `itemPrefixText(ci)` — used by every call site that either renders or measures the prefix.
## 3. Detailed tech design
### 3.1 Where the offsets come from
```
Compose layout
└─> SelectableText / ClickableText (TextItemView.kt)
└─> getOffsetForPosition(localPos) // returns display-space offset
└─> SelectionManager.setAnchorOffset / updateFocusOffset
└─> selectedRange(...) → IntRange in display space
└─> selectedItemCopiedText(ci, sel, linkMode) // FIX site #1
└─> snapOffset(ci, off, linkMode, expandRight) // FIX site #2
```
`MarkdownText` (TextItemView.kt) builds the `AnnotatedString` in this order:
```
inlineContent — never present for report items
appendSender(...) — null for the CIMarkdownText path
prefix (AnnotatedString) — "${reason}: " for reports, null otherwise
text / formatted segments — the body
typingIndicator (live only) — past selectableEnd
reserve (timestamp space) — past selectableEnd
```
For non-report items the prefix is null and the existing identity `displayOffset = 0` holds. For reports, the body's first character lives at display offset `prefix.length`.
### 3.2 The minimal structural change
Pre-PR loop:
```kotlin
var displayOffset = 0
for (ft in formattedText) {
val segDisplay = itemSegmentDisplayText(ft, ci, linkMode)
val displayEnd = displayOffset + segDisplay.length
val overlapStart = maxOf(displayOffset, sel.first)
val overlapEnd = minOf(displayEnd, sel.last + 1)
if (overlapStart < overlapEnd) { /* emit */ }
displayOffset = displayEnd
}
```
Two changes only:
1. **Seed with prefix length.** `var displayOffset = prefix.length` (or `itemPrefixText(ci).length` for `snapOffset`). Loop body is otherwise byte-for-byte identical to pre-PR. For non-reports `prefix.length == 0`, so the non-report path is unchanged.
2. **Emit the prefix slice.** Before the loop, append the portion of `prefix` covered by the selection:
```kotlin
if (sel.first < prefix.length) {
sb.append(prefix, sel.first, minOf(prefix.length, sel.last + 1))
}
```
`selectedRange()` guarantees `sel.first ≥ 0`, so no clamping is needed at this site.
3. **Handle the `formattedText == null` branch.** Reports with empty body have null `formattedText`, but the prefix selection still has to be returned. The early-return in the pre-PR null branch is replaced by the same `StringBuilder` path so prefix-only selections work:
```kotlin
val formattedText = ci.formattedText ?: run {
val start = (sel.first - prefix.length).coerceAtLeast(0).coerceAtMost(ci.text.length)
val end = (sel.last + 1 - prefix.length).coerceAtMost(ci.text.length)
if (start < end) sb.append(ci.text, start, end)
return sb.toString()
}
```
`coerceAtLeast(0)` on `start` is required here because `sel.first - prefix.length` is negative when the selection lies entirely inside the prefix.
### 3.3 Single source of truth
Pre-PR, the prefix expression `if (mc.text.isEmpty()) mc.reason.text else "${mc.reason.text}: "` lived inline at two render sites:
- `FramedItemView.kt:368` — the actual report row
- `ChatPreviewView.kt:262` — the chat list preview
Re-introducing it inline in `TextSelection.kt` would have re-created exactly the silent coupling that produced the bug — a future change to the separator (e.g. localised colon) at the renderer would silently break copy/snap. The fix factors the expression into:
```kotlin
// TextItemView.kt
fun itemPrefixText(ci: ChatItem): String = when (val mc = ci.content.msgContent) {
is MsgContent.MCReport -> if (mc.text.isEmpty()) mc.reason.text else "${mc.reason.text}: "
else -> ""
}
```
Both renderers and both selection-side functions now derive the string from this one definition.
### 3.4 Edge cases verified
| Case | Pre-PR | Post-PR |
|---|---|---|
| Non-report, fmt non-null (markdown) | works | byte-identical loop, works |
| Non-report, fmt null (plain text) | substring fast path | StringBuilder path, value-equivalent |
| Non-report, sel out of bounds | clamped to `[L, L]` → `""` | same |
| Report, full sel `Spam: test` | returns `test` (BUG) | returns `Spam: test` |
| Report, prefix-only sel | returns `""` (BUG) | returns prefix slice |
| Report, body-only sel | returns body (offset shift was hidden by `Int.MAX_VALUE` clamp at `sel.last+1`) | returns body |
| Report, sel.first == prefix.length | works coincidentally | works |
| Report, empty body, prefix-only sel | returns `""` | returns prefix |
| Report with mention having `localAlias` (transformed) | snap snapped to wrong char (BUG) | snaps correctly |
| Multi-item interior sel (`sel.last = MAX-1`) | works | no overflow on `+1 - prefix.length` |
### 3.5 What was deliberately not done
- **Performance restoration of the non-report null-fmt path.** Pre-PR returned `ci.text.substring(...)` directly (1 allocation). Post-PR uses `StringBuilder` (3 allocations). `selectedItemCopiedText` runs once per selected item per copy action — never on a hot path. Restoring the pre-PR fast path with an `if (prefix.isEmpty() && formattedText == null)` early return adds 4 lines of branching for negligible gain. Not worth it.
- **Migrating `ChatPreviewView.kt` was kept** because it crossed the 3-site extraction threshold (FramedItemView + ChatPreviewView + 2× TextSelection) and the bug we are fixing is exactly the failure mode of duplicating this expression. ChatPreviewView is not a selection site, so no behaviour change — it shifts to the same single source of truth.
## 4. Detailed implementation plan
### 4.1 Files touched (final state)
| File | Δ | Purpose |
|---|---|---|
| `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/TextItemView.kt` | +7 / 0 | new `itemPrefixText(ci)` helper next to `itemDisplayText` |
| `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/FramedItemView.kt` | +1 / −1 | report branch delegates to `itemPrefixText(ci)` |
| `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chatlist/ChatPreviewView.kt` | +2 / −2 | preview row delegates; drops unused `val mc =` |
| `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/TextSelection.kt` | +16 / −8 | the actual fix in `selectedItemCopiedText` and `snapOffset`, plus import |
Total: 4 files, +26 / −11.
### 4.2 Step-by-step (final commit `96d6f3222`)
1. **Add `itemPrefixText(ci)`** in `TextItemView.kt` next to `itemDisplayText` / `itemSegmentDisplayText`. Returns `""` for non-reports.
2. **`FramedItemView.kt:365-372`** (`MCReport` branch): replace inline expression with `append(itemPrefixText(ci))`. The surrounding `withStyle(SpanStyle(color = Red, italic))` is preserved — visual rendering unchanged.
3. **`ChatPreviewView.kt:258-264`**: replace inline expression with `append(itemPrefixText(ci))`. Drop the now-unused `val mc =` from `when (val mc = ci.content.msgContent)` (the discriminator becomes `when (ci.content.msgContent)`).
4. **`TextSelection.kt`**:
- Add `import chat.simplex.common.views.chat.item.itemPrefixText`.
- In `selectedItemCopiedText`:
- Compute `val prefix = itemPrefixText(ci)` and `val sb = StringBuilder()` first.
- Emit prefix slice if `sel.first < prefix.length`.
- Modify the `formattedText ?: ...` early-return to a `?: run { … }` block that adds the body slice (offsets shifted by `-prefix.length`, clamped) to `sb` and returns `sb.toString()`.
- Seed the formattedText loop with `var displayOffset = prefix.length`. Loop body unchanged.
- In `snapOffset`: change `var displayOffset = 0` to `var displayOffset = itemPrefixText(ci).length`. Loop body unchanged.
- Update the docstring on `selectedItemCopiedText` to note that display-text space includes any leading `itemPrefixText`.
### 4.3 Verification
- `./gradlew :common:compileKotlinDesktop` — passes (warnings are pre-existing).
- `bash /home/user/build/linux.sh` — full Linux x86_64 AppImage produced (`SimpleX_Chat-x86_64-fix-select-in-reports.AppImage`).
- Manual test plan, all in desktop:
1. Open a chat with a report whose rendered form is `Spam: test`. Select across the whole line + Ctrl-C → clipboard reads `Spam: test`.
2. Select only the red prefix → clipboard reads the prefix.
3. Select only the comment → clipboard reads the comment.
4. Report comment containing `@alice (Bob)` (mention with localAlias). Drag a selection boundary into the mention → on release, highlight snaps to mention boundaries.
5. Plain (non-report) messages: full-line, partial, mention, link selections — clipboard contents unchanged from pre-PR.
6. Multi-item selection across non-report and report rows — prefixes appear inline at the correct positions.
### 4.4 Risk and rollback
- **Blast radius** is the desktop selection-copy code path. iOS / Android use separate selection mechanisms and are unaffected.
- The non-report selection path's inner loop body is byte-for-byte identical to pre-PR (the `displayOffset = 0` initialisation is unchanged when `prefix.length == 0`), so regressions on non-reports would require the prefix expression itself to fail — which is impossible because `itemPrefixText` returns `""` for any `msgContent` other than `MCReport`.
- Rollback is `git revert 96d6f3222 e97dd7bf4 6aacfa4d2` (three commits) and a force-push, restoring the pre-PR copy behaviour with the original bug.
## 5. Why this specific shape
- Recognising the prefix as the *first* display-space segment turns the bug into a one-line seed change. No special-cased report branch in copy/snap; the existing loop handles both.
- The inner loop of `selectedItemCopiedText` and `snapOffset` is byte-for-byte identical to pre-PR. Only the seed value of `displayOffset` and the pre-/post-amble change.
- Four sites need the prefix string (FramedItemView, ChatPreviewView, and two in TextSelection). `itemPrefixText` becomes their single point of change, closing the silent-coupling gap that produced the bug.
- `selectedRange()` guarantees `sel.first ≥ 0`, so no `coerceAtLeast(0)` is added at the prefix-slice append. The one `coerceAtLeast(0)` that survives (on the `formattedText == null` body branch) is reachable when the selection lies entirely inside the prefix and is needed.
- Final PR is 4 files, +26 / −11. The inner loop body changes by zero lines.
plans/2026-05-08-relay-announce-impl.md
+695
View File
@@ -0,0 +1,695 @@
# Implementation plan: owner-pushed relay announcement (`XGrpRelayNew`)
Companion to `/workspace/plans/2026-05-08-relay-announce.md` (overview). This file is the
file-and-symbol-level diff guide. Read the overview first.
All file/line references are against the working tree at the start of the implementation;
they will drift slightly as edits land. Cite this plan when something looks unfamiliar.
---
## 1. Step ordering and commit shape
Compilation must hold after every step. The order below is the smallest reviewable
sequence; steps S1–S5 are intentionally split into two PRs: a wire-format-only PR and a
behaviour PR, so reviewers can evaluate the new event in isolation.
PR 1 — wire format (compiles, no behaviour change)
- S1 `Protocol.hs`: add `XGrpRelayNew` constructor, tag `x.grp.relay.new`,
`toCMEventTag`, JSON encode/parse, `isForwardedGroupMsg` row.
- S2 `Protocol.hs`: extend `requiresSignature` to include `XGrpRelayNew_`.
- S3 `docs/protocol/channels-protocol.md`: signing-table row + new "Relay addition"
subsection.
PR 2 — receive + send + forward (one logical change)
- S4 `Store/Groups.hs`: add active-status filter in place to the inner
`getGroupMemberByRelayLink` lookup inside `getCreateRelayForMember`.
- S5 `Library/Internal.hs`: introduce `connectToRelayAsync`. Move `syncSubscriberRelays`
from `Commands.hs` to `Internal.hs` and pivot its add-half to `connectToRelayAsync`.
- S6 `Library/Commands.hs`: drop the now-unused sync `connectToRelay`; `APIConnectPreparedGroup`
keeps the existing sync call (see §6 — left in place); update import of
`syncSubscriberRelays`. Keep `retryRelayConnectionAsync` as-is.
- S7 `Library/Subscriber.hs`: add forward-only case to `processEvent`, add
`XGrpRelayNew` case to `processForwardedMsg`, add owner send at end of LINK callback.
- S8 Tests in `tests/ChatTests/Channels.hs` (or split across files per §11).
S1–S3 land in PR 1; S4–S8 in PR 2. PR 2 must not be split: the owner-side send and the
subscriber-side handler must ship together to avoid asymmetry where one direction is
emitted but not consumed.
---
## 2. `Protocol.hs` — wire format (S1, S2)
### 2.1 GADT constructor (Protocol.hs:443-445)
Add at line 446 (immediately after `XGrpRelayTest`, before `XGrpMemNew`):
```
XGrpRelayNew :: ShortLinkContact -> ChatMsgEvent 'Json
```
Rationale: keeps the relay-related events grouped. Single `ShortLinkContact` field, no
record syntax, mirrors `XGrpRelayAcpt :: ShortLinkContact -> ChatMsgEvent 'Json` at
Protocol.hs:444. **Do not** introduce a record wrapper or `RelayInfo` envelope — the
overview locked the shape to a single field; the receiver looks the link up locally.
### 2.2 Tag GADT and string encoding (Protocol.hs:986-988, 1043-1045, 1101-1103)
- Insert `XGrpRelayNew_ :: CMEventTag 'Json` after `XGrpRelayTest_` (line 988).
- In `strEncode`, add `XGrpRelayNew_ -> "x.grp.relay.new"` after `XGrpRelayTest_` (line 1045).
- In `strDecode` map (line 1103), add `"x.grp.relay.new" -> XGrpRelayNew_` after
`"x.grp.relay.test" -> XGrpRelayTest_`.
The `_` -> `XUnknown_` fallback at line 1129 already gives correct old-client behaviour;
no change there.
### 2.3 `toCMEventTag` (Protocol.hs:1133-1184)
Add `XGrpRelayNew _ -> XGrpRelayNew_` after the `XGrpRelayTest` line (1157).
### 2.4 JSON parse / encode (Protocol.hs:1308-1314, 1378-1382)
- `appJsonToCM`/`msg` parser (1271-1344): add
`XGrpRelayNew_ -> XGrpRelayNew <$> p "relayLink"`
immediately after `XGrpRelayAcpt_` (line 1309). Field name `"relayLink"` matches the
`XGrpRelayAcpt` precedent (1309) — do not invent a new key.
- `chatToAppMessage`/`params` encoder (1354-1410): add
`XGrpRelayNew relayLink -> o ["relayLink" .= relayLink]`
after the `XGrpRelayAcpt` clause (1379). Same key.
### 2.5 `isForwardedGroupMsg` (Protocol.hs:484-503)
Add a single case `XGrpRelayNew _ -> True` in the listed group of `True` cases (e.g.
between `XGrpMemNew {} -> True` (495) and `XGrpMemRole {} -> True` (496)). Rationale:
relays must forward this event to subscribers; it is the entire point. The comment
above the function (line 482) already says actual filtering happens in `processEvent`;
the listing here is for the send-side `memberSendAction` decisions about pre-member
forwarding (Internal.hs:2202), which we want to behave the same as `XGrpMemNew`.
### 2.6 `requiresSignature` (Protocol.hs:1221-1231)
Add `XGrpRelayNew_ -> True` to the list. Rationale: this is an administrative event;
must reuse the existing required-signature gate. Without this, `withVerifiedMsg`
(Subscriber.hs:3385-3407) would treat a missing signature as acceptable
(`signatureOptional` becomes `True`), breaking the threat model from
`channels-protocol.md` §"Message signing".
### 2.7 What NOT to change
- Do not touch `hasNotification` or `hasDeliveryReceipt` — relay-add is administrative,
not a notification surface for the user. The relay's delivery pipeline (delivery_task /
delivery_job) already handles forwarding without an entry in either table.
- Do not touch `unverifiedAllowed` (Protocol.hs:1240-1249). Owners always know their own
key; subscribers always have the owner key from link data. The "no key" branch is for
member-to-member events, not for owner-signed administrative events.
---
## 3. `Store/Groups.hs` — active-status filter on relay-link lookup (S4)
### 3.1 The current shape (Store/Groups.hs:1376-1407)
`getCreateRelayForMember` runs `getGroupMemberByRelayLink` (an inner `let` at 1380-1385),
falls back to `createRelayMember`. The inner SQL filters on `group_id = ? AND relay_link
= ?` only — no status filter. The schema permits multiple rows with the same
`(group_id, relay_link)` over time: when a relay is removed by the owner, its row is
preserved with `GSMemLeft` (this drives the "removed by operator" UI on the subscriber
side). For the existing subscriber-join flow (`APIConnectPreparedGroup → connectToRelay`,
Commands.hs:2141 / 3597-3613) the unfiltered lookup happens to work because rows in that
path are recent and active. For the new subscriber receive path we must filter to *active*
rows so that a re-add after a `GSMemLeft` creates a fresh row instead of resurrecting the
historical one.
### 3.2 The change
Add an active-status filter in place to the existing inner `let`. No extraction, no new
top-level function:
```
getGroupMemberByRelayLink =
maybeFirstRow (toContactMember vr user) $
DB.query
db
(groupMemberQuery <> " WHERE m.group_id = ? AND m.relay_link = ? AND m.member_status IN (?,?,?,?,?,?,?)")
( (groupId, relayLink)
:. (GSMemIntroduced, GSMemIntroInvited, GSMemAccepted, GSMemAnnounced)
:. (GSMemConnected, GSMemComplete, GSMemCreator)
)
```
The seven statuses are the `memberCurrent'`-true set from Types.hs:1318-1334:
`GSMemIntroduced`, `GSMemIntroInvited`, `GSMemAccepted`, `GSMemAnnounced`,
`GSMemConnected`, `GSMemComplete`, `GSMemCreator`. Tuple shape is illustrative — match the
existing `:.` chaining convention used elsewhere in the module.
Justification for SQL-level filter (vs. Haskell post-filter): `maybeFirstRow` returns
whatever row the engine yields first. With `GSMemLeft` history rows preserved alongside
active rows, an unfiltered query is non-deterministic without `ORDER BY`. Filtering in
SQL eliminates the ambiguity at the query level. The list of statuses is tiny and
stable.
### 3.3 Existing call site unaffected
`getCreateRelayForMember`'s lone existing caller is `connectToRelay` (Commands.hs:3597-3613),
invoked from `APIConnectPreparedGroup` (Commands.hs:2141). Rows it creates are inserted
with `GSMemAccepted` (line 1403), which is `memberCurrent`. The filtered lookup still
finds them on retry, so the subscriber-join flow's reuse-on-retry behaviour is preserved.
No signature or call-site change is needed in `Commands.hs`.
### 3.4 What NOT to change
- Do not extract `getGroupMemberByRelayLink` to a top-level function. The
filter-in-place shape is the minimal diff; both call sites (existing
`APIConnectPreparedGroup → connectToRelay` and new `connectToRelayAsync`) share one
definition by going through `getCreateRelayForMember`.
- Do not modify `getGroupMember`, `getGroupMembers`, or other lookups. The change is
scoped to the relay-link lookup inside `getCreateRelayForMember`.
- Do not delete the historical `GSMemLeft` row when re-adding a relay. The
delete-or-update logic in `syncSubscriberRelays` removes only when the link is no
longer in the channel's link data (Commands.hs:3623-3633); on re-add it remains in
link data, so the historical row stays untouched and is filtered out by the new
lookup.
---
## 4. `Library/Internal.hs` — `connectToRelayAsync` and moved `syncSubscriberRelays` (S5)
### 4.1 New helper
Place near the existing relay/group plumbing (e.g. after `setGroupLinkDataAsync` at
Internal.hs:1316-1322) so that all relay-link async helpers cluster together.
```
connectToRelayAsync :: User -> GroupInfo -> ShortLinkContact -> CM ()
```
Body — described, not coded:
1. `vr <- chatVersionRange`.
2. `gVar <- asks random` — needed by `getCreateRelayForMember` via the create branch.
3. `relayMember <- withFastStore $ \db -> getCreateRelayForMember db vr gVar user gInfo relayLink`.
With the active-status filter from §3.2, this atomically returns the existing active
row (if any) or creates a fresh `GSMemAccepted` row. `GSMemLeft` history rows are
invisible to the lookup, so re-add after removal creates a new row beside the
historical one.
4. Idempotence check on `activeConn relayMember`:
- `Just _` → `pure ()` (skip; an earlier path already bound a connection on this
row. The agent layer handles transient failures internally; permanent-failure
recovery is deferred to explicit retry paths and channel re-join.)
- `Nothing` → either a freshly created row or a leftover row from an attempt that
never bound a connection; proceed to step 5.
5. `subMode <- chatReadVar subscriptionMode`.
6. `newConnIds <- getAgentConnShortLinkAsync user CFGetRelayDataJoin Nothing relayLink`
(Commands.hs:2479 — already returns `(CommandId, ConnId)` for binding).
7. `withFastStore' $ \db -> createRelayMemberConnectionAsync db user gInfo relayMember relayLink newConnIds subMode`
(Direct.hs:225-244).
8. Return. Continuation is the existing `CFGetRelayDataJoin` LDATA callback at
Subscriber.hs:1131-1160 — unchanged.
Store-call conventions: `getCreateRelayForMember` is `ExceptT StoreError IO`, so use
`withFastStore`. `createRelayMemberConnectionAsync` is `IO`, so `withFastStore'`. Both
match what `retryRelayConnectionAsync` (Commands.hs:2168-2174) and `connectToRelay`
(Commands.hs:3597-3613) already use.
### 4.2 Locking argument
`connectToRelayAsync` is called from two sites (after this PR):
- The forwarded `XGrpRelayNew` handler in `processForwardedMsg`. The entire receive path
is wrapped in `withEntityLock "processAgentMessage" lockEntity` (Subscriber.hs:117) and
the lock entity for any group connection is `CLGroup groupId` (Connections.hs:51-72).
- `syncSubscriberRelays`, called from `APIGetUpdatedGroupLinkData` inside
`withGroupLock "syncSubscriberRelays" groupId` (Commands.hs:1787) — also `CLGroup groupId`.
Both paths therefore hold the same lock for the same group. The `getCreateRelayForMember`
call (lookup-or-create, atomic within its own transaction) and the `activeConn` check on
its result are performed under that lock, and any subsequent agent commands
(`getAgentConnShortLinkAsync`, `createRelayMemberConnectionAsync`) only persist state
that will be observed under the same lock by the next event's check. No additional lock
is needed. No `justCreated` flag, no per-link mutex.
### 4.3 Move `syncSubscriberRelays` from `Commands.hs:3614-3633` to `Internal.hs`
Place right below `connectToRelayAsync`. Body changes:
- Replace the single `connectToRelay` call inside the `forM_ newRelayLinks` loop
(Commands.hs:3621-3622) with `connectToRelayAsync user gInfo rlnk`. Keep the
per-relay `void . tryAllErrors` wrapping verbatim — equivalent to the existing
pattern at Commands.hs:3621-3622 with only the connect helper substituted:
```
forM_ newRelayLinks $ \rlnk -> void . tryAllErrors $
connectToRelayAsync user gInfo rlnk
```
`connectToRelayAsync` can fail at three local operations
(`getCreateRelayForMember` → store error if creating; `getAgentConnShortLinkAsync`
→ agent error; `createRelayMemberConnectionAsync` → store error). Per-relay error
isolation costs nothing and ensures a failure on relay R1 does not short-circuit
attempts for R2, R3 in the same batch. The outer `void . tryAllErrors` (3615) is
preserved as well; it remains the catch-all for the whole sync operation.
- Remove half: keep verbatim — `deleteMemberConnection`, `deleteOrUpdateMemberRecord`
calls (3631-3632), the `null activeRelayMembers` guard (3629), and the
`localRelayMembers` filter (3617).
Type signature after move (matches current except for module location):
```
syncSubscriberRelays :: User -> GroupInfo -> [ShortLinkContact] -> CM ()
```
### 4.4 Imports / exports
- `Internal.hs` likely already imports the relevant `Store.Groups`/`Store.Direct`
symbols; if `getCreateRelayForMember` or `createRelayMemberConnectionAsync` are not
imported, add them.
- Export `connectToRelayAsync` and `syncSubscriberRelays` from `Internal.hs` (it is a
module without an explicit export list — see "module Simplex.Chat.Library.Internal where"
near top — so any new top-level binding is automatically exported).
### 4.5 What NOT to change
- Do not change `connectToRelay` (sync, Commands.hs:3597-3613) signature. PR 2 keeps it
alive for the subscriber's initial channel-join — see §5.1.
- Do not touch `retryRelayConnectionAsync` (Commands.hs:2168-2174). Its retry semantics
are tied to the subscriber's initial channel-join (`APIConnectPreparedGroup`,
Commands.hs:2108-2161) and remain on that path.
- Do not introduce any new `withGroupLock` inside `connectToRelayAsync`. The caller's
lock is sufficient (see §4.2).
---
## 5. `Library/Commands.hs` — drop unused sync helper, fix imports (S6)
### 5.1 Decide what to delete
Audit `connectToRelay` callers: only `APIConnectPreparedGroup` (Commands.hs:2108-2161)
uses it. That command is the **subscriber's** initial channel-join entry point
(not owner channel creation — owner-side relay invitation flows through
`APIAddGroupRelays` and `x.grp.relay.inv`/`x.grp.relay.acpt`, see channels-protocol.md
§"Relay acceptance"). At join time, the subscriber does
`mapConcurrently (connectToRelay user gInfo') relays` (Commands.hs:2141) to connect to
all relays in parallel during the join handshake.
The sync flow is intentional there:
- the user is on a "joining channel" spinner;
- failures must surface immediately to UI so the user sees a meaningful error
instead of a stuck spinner;
- the existing flow already chains async retry via `retryRelayConnectionAsync`
(Commands.hs:2159) for the relays that fail with temporary errors — sync handles
the immediate-feedback path, async handles tail recovery.
**Default; reviewer to confirm**: keep `connectToRelay` for the
`APIConnectPreparedGroup` path. The overview's "deletable once event-driven path is
wired" was conditional ("once no caller remains"). Subscriber join has different UX
semantics from event-driven relay sync; convergence onto async-only is a separate
concern and is out of scope for this PR.
### 5.2 Move `syncSubscriberRelays` reference
`APIGetUpdatedGroupLinkData` at Commands.hs:1787-1788 currently references
`syncSubscriberRelays` as a local where-binding inside `processChatCommand` (it is the
inner `where`-defined function at 3614). After moving it to `Internal.hs`, the call site
at 1788 unchanged but the local binding at 3614-3633 deleted. Imports auto-rerouted via
`Simplex.Chat.Library.Internal` (already imported at the top of Commands.hs).
### 5.3 What NOT to change
- Do not change `APIGetUpdatedGroupLinkData`'s `withGroupLock` wrapper or the `gInfo'`
it passes to the sync function. The lock and the link-data refresh are still required.
- Do not change `retryRelayConnectionAsync`. It is the right primitive for the
subscriber-join retry use case (`APIConnectPreparedGroup` tail recovery,
Commands.hs:2159); the new event-driven path is independent.
---
## 6. `Library/Subscriber.hs` — owner send, relay forward, subscriber receive (S7)
### 6.1 Owner — send site in LINK callback (Subscriber.hs:1300-1333)
The relevant block:
```
LINK _link auData ->
withCompletedCommand conn agentMsg $ \CommandData {cmdFunction} ->
case cmdFunction of
CFSetShortLink ->
case (ucGroupId_, auData) of
(Just groupId, UserContactLinkData UserContactData {relays = relayLinks}) -> do
(gInfo, gLink, relays, relaysChanged) <- withStore $ \db -> do
gInfo <- getGroupInfo db vr user groupId
gLink <- getGroupLink db user gInfo
relays <- liftIO $ getGroupRelays db gInfo
(relays', changed) <- liftIO $ foldrM (updateRelay db) ([], False) relays
liftIO $ setGroupInProgressDone db gInfo
pure (gInfo, gLink, relays', changed)
toView $ CEvtGroupLinkDataUpdated user gInfo gLink relays relaysChanged
where
updateRelay db relay@GroupRelay {relayLink, relayStatus} (acc, changed) =
case relayLink of
Just rLink
| rLink `elem` relayLinks && relayStatus == RSAccepted -> do
relay' <- updateRelayStatus db relay RSActive
pure (relay' : acc, True)
...
```
Plan:
1. Extend the `updateRelay` accumulator from `([GroupRelay], Bool)` to
`([GroupRelay], Bool, [ShortLinkContact])`: keep the existing `Bool` for the
`CEvtGroupLinkDataUpdated`'s `relaysChanged` flag, and add a new
`[ShortLinkContact]` collecting the links of relays that just transitioned
`RSAccepted → RSActive`. In the `RSAccepted → RSActive` branch, replace
`pure (relay' : acc, True)` with `pure (relay' : acc, True, rLink : newlyActiveLinks)`.
In the `RSActive → RSInactive` branch (which also sets `changed = True` today,
line 1330), keep the `Bool` flip but pass `newlyActiveLinks` through unchanged
— removals are explicitly out of scope for the announce push (overview
§"Owner — send site"). Other branches pass both extra fields through unchanged.
2. Bind `(gInfo, gLink, relays, relaysChanged, newlyActiveLinks)` from the `withStore`
block; pass `relaysChanged` to the existing `CEvtGroupLinkDataUpdated` `toView`
call so its semantics are preserved exactly; pass `newlyActiveLinks` to the new
send block in step 3.
3. After the `toView`, add (still inside `(Just groupId, UserContactLinkData ...)`
case). The send block fetches all relay members and filters inline (see §6.2):
```
let newlyActiveLinks = ... -- collected from the fold accumulator
forM_ (L.nonEmpty newlyActiveLinks) $ \newlyActive -> do
allRelayMembers <- withFastStore' $ \db -> getGroupRelayMembers db vr user gInfo
let recipients = filter
(\m -> memberStatus m == GSMemConnected && relayLink m `notElem` newlyActiveLinks)
allRelayMembers
events = XGrpRelayNew <$> newlyActive
unless (null recipients) $
void $ sendGroupMessages user gInfo Nothing False recipients events
```
- `sendGroupMessages` signature (Internal.hs:2049): `User -> GroupInfo -> Maybe
GroupChatScope -> ShowGroupAsSender -> [GroupMember] -> NonEmpty (ChatMsgEvent e) -> CM (NonEmpty (Either ChatError SndMessage), GroupSndResult)`.
- `Nothing` for `Maybe GroupChatScope`: this is administrative, not scoped to a
support side-channel. Justified by `XGrpInfo` / `XGrpPrefs` send patterns elsewhere
where signed admin events use `Nothing`.
- `False` for `ShowGroupAsSender`: this is signed by the owner; relays must verify
the owner signature via `withVerifiedMsg` (Subscriber.hs:3385). `asGroup = True`
uses `CBChannel` binding (channels-protocol.md §"Channel-as-sender"), which has no
member ID and is not what we want — verification needs the owner's member ID.
- `void` discards the per-member result; logging is handled by the existing send
pipeline.
### 6.2 Recipients query
No new Store helper. Inline the filter in the LINK callback:
- After the `withStore` block that runs the fold, call
`withFastStore' $ \db -> getGroupRelayMembers db vr user gInfo` to get
`[GroupMember]` (Store/Groups.hs:1185-1191).
- Filter in Haskell:
`filter (\m -> memberStatus m == GSMemConnected && relayLink m \`notElem\` newlyActiveLinks)`.
- `memberStatus == GSMemConnected` already implies `memberCurrent` (Types.hs:1318-1334);
do not add a redundant `memberCurrent` check.
- Pass the filtered list as the recipients argument to `sendGroupMessages`.
Justification: one-shot use, low frequency (LINK callback only), no benefit
to introducing a new Store function. `vr` and `user` are already in scope at
the LINK callback (Subscriber.hs:1306, inside `processContactConnMessage`).
### 6.3 Defensive batching
Per overview, the receive-loop group lock serializes `XGrpRelayAcpt` handling (which
calls `setGroupLinkDataAsync`) so each LINK callback typically sees a single
`RSAccepted → RSActive` transition. Coding the send as `NonEmpty (XGrpRelayNew _)` keeps
the path correct if the agent ever consolidates `setConnShortLink` writes. The
`L.nonEmpty newlyActive` guard handles the empty case (no transition this callback).
### 6.4 Relay — `processEvent` case (Subscriber.hs:990-1032)
Insert this case before the catch-all `_ -> Nothing <$ messageError ...` at 1032:
```
XGrpRelayNew _ -> pure $ Just (DeliveryTaskContext (DJSGroup {jobSpec = DJDeliveryJob {includePending = False}}) False)
```
Justification by precedent:
- `XMsgNew` (991) → `newGroupContentMessage` returns `Just (ctx js)` where `ctx` is
`DeliveryTaskContext js False` (line 983). The `False` is the "don't include in
history" flag — relay forwards but doesn't snapshot.
- `XGrpMemNew` (1011) → `xGrpMemNew` returns `Just (ctx (DJSGroup {…}))`. We want
identical broadcast scope (all subscribers, no support-only channel).
- `XGrpDel` (1022) is the only event that uses `DJRelayRemoved`; that is for
relay-removal-by-owner, not relevant here.
`DJDeliveryJob {includePending = False}` matches `XMsgNew`'s default (search
`Delivery.hs` for `DJDeliveryJob` constructor — `includePending = False` is the
non-administrative-state-change default; `XGrpInfo` uses `True` because it changes
group profile state and pending members must learn it on accept). The relay
**stores no member record for the announced relay** (overview §"Relay — forward
only"), so subscribers entering pending state later will instead learn via on-open
`syncSubscriberRelays`. `includePending = False` is correct.
What NOT to do:
- Do not add an `xGrpRelayNew` handler on the relay side — the relay is forward-only.
- Do not create a `GroupMember` record for the announced relay on the relay. Departure
from `XGrpMemNew` semantics is intentional; relays don't connect to other relays of
the same channel.
### 6.5 Subscriber — `processForwardedMsg` case (Subscriber.hs:3354-3383)
Add to the inner `case event of` (just before the catch-all `_ -> messageError ...` at
3378):
```
XGrpRelayNew rl -> withAuthor XGrpRelayNew_ $ \_author -> connectToRelayAsync user gInfo rl
```
Notes:
- `withAuthor` (3380-3383) requires `author_ :: Maybe GroupMember` to be `Just` —
enforces the "must be attributable to a signing owner" invariant. `FwdChannel` (3351
via `processForwardedMsg (VMUnsigned chatMsg) Nothing`) makes `author_ = Nothing`,
which `withAuthor` rejects with `messageError`. This is the desired behaviour: the
event must be owner-signed and attributed.
- Signature verification happens upstream in `withVerifiedMsg` (3385-3407) before
`processForwardedMsg` is invoked (3348-3349). With `requiresSignature` returning
`True` for `XGrpRelayNew_` (§2.6), an unsigned forwarded `XGrpRelayNew` triggers the
bad-signature path at 3389-3391.
- The `_author` is used only as an authorisation token here. The connect helper does
not need the author identity — the author is the owner whose link data already
carried the relay key, and the relay member's keys/profile are fetched from the
relay's own short link.
### 6.6 `xGrpMsgForward` — no change needed
Already validates the forwarder is a relay (`isMemberGrpFwdRelay`, 3340) and dispatches
to `processForwardedMsg`. Adding the new event tag inside that switch is the entirety
of the receive-side change.
### 6.7 What NOT to change in `Subscriber.hs`
- Do not touch the `CFGetRelayDataJoin` LDATA callback (1131-1160). Its end state
(subscriber-side) is exactly the continuation we want; the helper hands off to it.
- Do not touch the `CON` handler at 823-865 for relay members. The `firstConnectedHost`
branch (855-859) handles the first-connected-relay UI events; subsequent relays go
through 859. After `XGrpRelayNew`-driven connect, the new relay's `CON` will land in
this same handler and get `firstConnectedHost = False` (because at least one relay is
already connected), which is correct.
- Do not modify the `CONF`/`XGrpRelayAcpt` path at 768-772. That is owner-side.
---
## 7. `docs/protocol/channels-protocol.md` updates (S3)
### 7.1 Signing-required table
Section: `## Protocol → ### Message signing → "Which messages require signatures:"`
table (lines 84-97). Add a row after `x.grp.mem.restrict`:
```
| `x.grp.relay.new` | Announce new relay to subscribers | Required |
```
Phrasing matches existing `Description` cells (verb + object).
### 7.2 New subsection "Relay addition"
Insert after the existing `### Relay acceptance` subsection (lines 42-58). Heading
level `###`, four short paragraphs:
1. **Owner-side trigger.** When the owner has accepted a relay (existing flow,
`x.grp.relay.acpt` at line 36) and the agent confirms the link-data update by
delivering the LINK event, the owner promotes the relay locally to active and
sends `x.grp.relay.new` to every other currently-connected relay of the channel
(excluding the relay being announced).
2. **Wire format.** Single-field JSON object: `{"relayLink": "<short link>"}`.
Owner-signed via the same `CBGroup` binding prefix used for all administrative
events (see [Message signing](#message-signing)).
3. **Relay forwarding semantics.** Each relay forwards `x.grp.relay.new` verbatim to
all of its subscribers via the standard delivery pipeline (delivery_task /
delivery_job, see [Delivery pipeline](#delivery-pipeline)). The relay does **not**
create a member record for the announced relay — relays do not connect to other
relays of the same channel.
4. **Subscriber receive semantics.** The subscriber resolves the announced short link
asynchronously, creates a relay-member row (or reuses an existing active row), and
binds the resulting agent connection without blocking the receive loop. If the
subscriber's client doesn't recognise the event (older version), it is parsed as
`XUnknown` and ignored; the next `APIGetUpdatedGroupLinkData` (channel open) reaches
the same end state via `syncSubscriberRelays`.
5. **Idempotence.** The receive loop wraps each agent message in a per-group entity
lock (`CLGroup groupId`); the same lock is held by `APIGetUpdatedGroupLinkData`.
A duplicate `x.grp.relay.new` arriving from a second relay finds an active row +
active connection and is a no-op.
### 7.3 What NOT to change
- Do not renumber existing sections.
- Do not modify the `Binary batch format` section — `x.grp.relay.new` is a
`signedElement` like every other administrative event; no new ABNF.
- Do not touch the `Channel-as-sender messages` section — `XGrpRelayNew` is owner-bound,
`CBGroup`, never `CBChannel`.
---
## 8. Test plan (S8)
All tests live under `tests/ChatTests/Channels.hs` (or a dedicated
`tests/ChatTests/Channels/RelayAnnounce.hs` if the file is getting unwieldy — confirm
with reviewer). Each test maps to a row in the overview's "Test surface".
| Overview test | Concrete test name | Harness |
|---|---|---|
| Owner adds relay → subscribers receive `XGrpRelayNew` and connect without channel open | `testRelayAnnounceOnlineSubscriber` | uses `testChat3` (owner + relay + subscriber); after channel is up, owner adds a second relay; assert subscriber's relay-member count for that group becomes 2 with both `GSMemConnected`, no `APIGetUpdatedGroupLinkData` invoked. |
| Two relays forward the announce; subscriber connects exactly once | `testRelayAnnounceDedupes` | `testChat4` (owner + 2 existing relays + subscriber); owner adds third relay; both existing relays forward; assert exactly one new relay-member row, exactly one connection. Inspect via `withCCStore (getGroupRelayMembers …)`. |
| Race vs. `APIGetUpdatedGroupLinkData` for same relay | `testRelayAnnounceRaceWithSync` | drive `APIGetUpdatedGroupLinkData` and `XGrpRelayNew` concurrently; assert no double row; rely on the existing `withGroupLock` to serialize. |
| `GSMemLeft` row preserved on re-add | `testRelayAnnounceReAddPreservesHistory` | owner adds relay, removes it, adds again with same link; assert two `GroupMember` rows for that link (one `GSMemLeft`, one current); the historical row is what drives the "removed by operator" UI. |
| Old subscriber ignores | `testRelayAnnounceOldSubscriber` | use `chatVersionRange` overrides to simulate an older subscriber; assert event is logged as unknown but produces no error item; `syncSubscriberRelays` invocation on next channel open creates the row. |
| Old relay drops | `testRelayAnnounceOldRelay` | inverse: relay's `chatVersionRange` does not include `XGrpRelayNew_` → `processEvent` default `messageError "unsupported"`. Subscribers fall back to on-open sync. |
| Bad signature | `testRelayAnnounceBadSignature` | inject an unsigned (or wrong-signed) `XGrpRelayNew` directly via the test SMP harness; assert `RGEMsgBadSignature` chat item is created on subscriber. |
Helpers reused: `withSmpServer`, `testChat`, `testChat3`, `testChat4`, `awaitListChat`,
`withCCStore`, `getGroupRelayMembers`. Add a small helper in the test module
`assertRelayMemberCount :: TestCC -> GroupId -> Int -> IO ()` if not already present.
For the dedup test specifically, assertion shape:
```
m <- getGroupRelayMembers db vr user gInfo
let relayRows = filter (\GM -> relayLink GM == Just newRl && memberCurrent GM) m
length relayRows `shouldBe` 1
length (filter (isJust . activeConn) relayRows) `shouldBe` 1
```
---
## 9. Risk register
1. **Race: event arrives during channel open.** The receive loop and
`APIGetUpdatedGroupLinkData` share `CLGroup groupId`. Whichever path runs first
creates/uses the row; the second sees an active row + active conn (or creates one
if not yet) and is a no-op. Tested via `testRelayAnnounceRaceWithSync`.
2. **Agent coalescing of `setConnShortLink` writes.** Today the receive-loop group lock
serializes `XGrpRelayAcpt` handling, so each LINK callback sees one transition. If
the agent ever batches multiple writes into one callback, the `NonEmpty
(XGrpRelayNew _)` send path stays correct: every newly-active relay gets announced.
No fix needed; defensive shape is already there.
3. **Old relay between owner and subscriber.** Old relay's `processEvent` default branch
drops the event with `messageError "unsupported"`. Subscribers behind that relay
recover via on-open `syncSubscriberRelays`. Documented in the protocol doc and
covered by `testRelayAnnounceOldRelay`.
4. **Malformed signature.** `requiresSignature XGrpRelayNew_ = True` causes
`withVerifiedMsg` to reject and produce `RGEMsgBadSignature`. Standard path; tested.
5. **Agent error during `getAgentConnShortLinkAsync` (step 3 of
`connectToRelayAsync`).** If the failure happens before
`createRelayMemberConnectionAsync` runs, `activeConn` is `Nothing`
and the next trigger retries automatically. If the call succeeds
but a later async step (LDATA, CONF, CON) stalls, `activeConn`
exists in a non-`ConnReady` state; the chat layer does not retry
by design (Option A simple skip). The agent layer's internal
retries on subscription resume drive recovery for transient
network failures. Permanent stalls are recovered via explicit
retry paths (`retryRelayConnectionAsync`, channel re-join).
6. **Link-data fetch failure after pre-created member row.** Two
sub-cases. (a) `createRelayMemberConnectionAsync` not yet run:
`activeConn = Nothing`, next trigger retries (`XGrpRelayNew`
arrival from another relay or channel re-open via
`syncSubscriberRelays`). (b) Connection record exists but LDATA
failed: `activeConn = Just _`, chat layer skips by Option A;
agent layer retries internally on subscription resume.
7. **Active-status filter on lookup breaks other call sites.** The filter is added in
place on `getCreateRelayForMember`'s inner lookup. Its lone existing caller is the
subscriber-join path (`APIConnectPreparedGroup` → `connectToRelay`, Commands.hs:2141
/ 3597-3613); rows there are created with `GSMemAccepted`, which is `memberCurrent`,
so the filtered lookup still finds them on retry. Observable behaviour unchanged for
the existing caller. Audit done in §3.3; reviewer to confirm.
8. **Multiple owners (future).** `LINK` callback only fires for the local owner's own
`setConnShortLink` calls (per existing TODO at Subscriber.hs:1327-1329). A second
owner adding a relay won't trigger the event from this owner — the second owner
would emit it themselves. Out of scope for current single-owner channels.
---
## 10. Backward compatibility
- **No schema migration.** The plan adds zero columns and zero tables. The new lookup
uses an existing column (`group_members.relay_link`) with an existing index path.
- **No protocol-version bump in the chat versioning.** The new tag is parsed as
`XUnknown` by clients that do not recognise `"x.grp.relay.new"` (Protocol.hs:1129
default branch in `strDecode`). `XUnknown` is silently ignored when reached by
`processEvent` (Subscriber.hs:1032 catch-all `messageError`); since this is on the
receive side of an old client, the message is logged as unsupported and the channel
state is unaffected.
- **No serialization-compat shim.** The single-field JSON form means old clients fall
through to `XUnknown_` cleanly without any optional-field hand-rolling.
---
## 11. Out of scope
- **Owner authorization-chain pushes.** Adding/removing owners is governed by the
multi-owner roadmap (channels-overview.md §"Governance evolution"). `XGrpRelayNew`
does not carry owner-chain payload.
- **Profile pushes.** Subscriber profile changes are out of scope; relay profile
arrives via the relay's own link data in the existing `CFGetRelayDataJoin` LDATA
flow.
- **Content batching beyond the LINK callback.** The `NonEmpty` shape is defensive
for agent-side coalescing, not a general batching mechanism.
- **Retry-on-failure semantics for the new async path.** Existing
`retryRelayConnectionAsync` (Commands.hs:2168-2174) covers the subscriber-join
retry of failed initial connects (`APIConnectPreparedGroup` tail recovery). For
event-driven re-attempts, on-open `syncSubscriberRelays` is the recovery mechanism;
per-link retry timers are not added.
- **Deletion of `connectToRelay` (sync).** Default kept. The lone caller is
`APIConnectPreparedGroup` (subscriber's initial channel-join flow,
Commands.hs:2108-2161), not owner channel creation. Deletion is a reviewer-confirmed
follow-up if subscriber-join is converged onto async — see §5.1 for why the sync
flow is intentional there.
---
## 12. Concerns with overview
- **Overview §"Files touched" lists "remove sync `connectToRelay`".** After tracing
Commands.hs:2141 (`mapConcurrently (connectToRelay user gInfo') relays` inside
`APIConnectPreparedGroup`), the sync helper still has a real caller — the
**subscriber's initial channel-join** (not owner setup). Deleting it now would
either break that path or force `APIConnectPreparedGroup` onto the async helper,
which is a separate concern (different UX expectations: spinner-blocking immediate
feedback vs. fire-and-forget). Plan defers this to a follow-up. Reviewer to confirm.
- **Overview §"Subscriber — receive" mentions `withAuthor XGrpRelayNew_`.** That
function name (the tag) does not currently exist in `Protocol.hs`; it lands in §2.2
of this plan. Naming preserved verbatim.
- **Overview §"Test surface" "Owner with old relay → relay drops the event".** The
current `processEvent` default branch is at Subscriber.hs:1032. Verified: the
default `_ -> Nothing <$ messageError ("unsupported message: " <> tshow event)`
drops the event after logging. This matches the overview's expectation.
plans/2026-05-08-relay-announce.md
+119
View File
@@ -0,0 +1,119 @@
# Plan: owner-pushed relay announcement (`XGrpRelayNew`)
## Goal
Subscribers learn of newly added relays immediately via an owner-pushed event,
rather than only on next channel open via `syncSubscriberRelays`.
## Wire-format
- New event: `XGrpRelayNew :: ShortLinkContact -> ChatMsgEvent 'Json`, tag `x.grp.relay.new`.
- Add to `isForwardedGroupMsg` in `Protocol.hs`.
- Add to required-signed-by-owner table in `docs/protocol/channels-protocol.md`.
Reuses existing `CBGroup`-prefixed signing infrastructure.
## Owner — send site
- In LINK callback at `Subscriber.hs:1305-1322`, after the fold over relays
that drives `RSAccepted → RSActive` transitions.
- Collect `relayLink` for every relay that transitioned to Active in this callback.
- If non-empty, build `events = XGrpRelayNew rl1 :| [XGrpRelayNew rl2, ...]`
and call `sendGroupMessages user gInfo Nothing False otherRelays events`.
- Recipients: channel's currently-connected relays minus the newly-active ones
(the announced relays don't need self-announcement).
- Batched shape is defensive, not load-bearing. The receive-loop group lock
serializes `XGrpRelayAcpt` handling and the subsequent
`setGroupLinkDataAsync` → LINK chain, so each LINK callback typically
transitions at most one relay. Coding the send as a `NonEmpty` of
`XGrpRelayNew` events keeps the path correct if the agent ever consolidates
link-data writes.
## Relay — forward only
- `processEvent` (Subscriber.hs:980-1032) gets a new case:
`XGrpRelayNew _ -> pure $ Just (DeliveryTaskContext (DJSGroup ...) False)`.
- No local handler — relay does NOT create a member record for the announced
relay (departure from `XGrpMemNew` semantics; relays don't connect to other
relays of the same channel).
- Forwarding is verbatim through binary-batch format, signature preserved.
- Old relay (no tag): `_ -> messageError "unsupported"` path drops the message.
Fallback: subscriber's on-open `syncSubscriberRelays` still works.
## Subscriber — receive
- Add case in `processForwardedMsg` (Subscriber.hs:3357-3378):
`XGrpRelayNew rl -> withAuthor XGrpRelayNew_ $ \author -> connectToRelayAsync user gInfo rl`.
- Author resolution + signature verification via existing `withAuthor` /
`withVerifiedMsg` machinery — same boundary as `XGrpInfo` etc. today.
- `FwdChannel` (channel-as-sender) is NOT valid for this event — it is
administrative and must be attributed to a signing owner.
## Subscriber — `connectToRelayAsync` helper
Place in `Internal.hs`. Both event handler and `syncSubscriberRelays` call it.
Body:
1. Look up active (`memberCurrent`) relay-member row by `relay_link`.
- If found AND has active connection → skip (already in flight or done).
- If found but no active connection → use it; proceed.
- If not found → create new relay-member row (with `relay_link`, role
`GRRelay`, status `GSMemAccepted`, no member-id/key/profile yet).
2. `getAgentConnShortLinkAsync user CFGetRelayDataJoin Nothing relayLink`
→ returns `(cmdId, agentConnId)`.
3. `createRelayMemberConnectionAsync` binds those to the relay-member.
4. Return. Continuation is the existing `CFGetRelayDataJoin` LDATA callback
at Subscriber.hs:1131-1160 (updates relay-member with member-id/key/profile,
calls `joinAgentConnectionAsync` → eventual `CON` flips status to
`GSMemConnected`).
A `GSMemLeft` historical row for the same `relay_link` is left in place
(displays "removed by operator"). Lookup must filter to `memberCurrent`.
## Idempotence and races
- Receive loop wraps each agent message in `withEntityLock` keyed by the
connection's lock entity (Subscriber.hs:115-117). Relay-member connections
resolve to `CLGroup groupId` (Store/Connections.hs:51-65).
- `APIGetUpdatedGroupLinkData` already uses `withGroupLock "syncSubscriberRelays" groupId`.
- Same key on both paths → event handler and open-channel command cannot
interleave for a given group_id. No additional lock needed.
- Inside the lock, "active row + active conn" check is sufficient. No
`justCreated` flag, no per-link mutex.
## `syncSubscriberRelays` migration
- Move from `Commands.hs` to `Internal.hs`.
- "Add" half: replace synchronous `connectToRelay` with `connectToRelayAsync`.
- "Remove" half (Commands.hs:3623-3633): unchanged.
- `connectToRelay` (sync) deletable once event-driven path is wired and
no caller remains.
## Old client compatibility
- Old subscriber: parses `XGrpRelayNew` as `XUnknown`, ignores. On-open
`syncSubscriberRelays` is the fallback path.
- Old relay: drops the message in `processEvent`'s default branch. Subscribers
on those relays fall back to on-open sync. Acceptable graceful degradation.
## Test surface
- Owner adds relay → existing subscribers (online) receive `XGrpRelayNew` and
connect without channel open.
- Channel with two existing relays: owner adds a third relay; both existing
relays forward `XGrpRelayNew` for the new relay to subscribers in parallel
→ shared-msg-id dedup leaves only one copy reaching the helper; subscriber
connects to the announced relay exactly once.
- `XGrpRelayNew` arrives while subscriber is mid-`APIGetUpdatedGroupLinkData`
for the same relay → group lock serializes; no double connection.
- Subscriber re-add scenario: previous `GSMemLeft` row for same `relay_link`
→ new active row created, old row preserved for history.
- Old subscriber receives forwarded `XGrpRelayNew` → ignored, channel-open
sync still recovers.
- Owner with old relay → relay drops the event; subscribers learn on open.
- Bad signature on `XGrpRelayNew` → rejected with bad-signature event.
## Files touched (anticipated)
- `src/Simplex/Chat/Protocol.hs` — event constructor, tag, JSON encode/parse,
`isForwardedGroupMsg`.
- `src/Simplex/Chat/Library/Internal.hs` — `connectToRelayAsync` helper,
`syncSubscriberRelays` moved here.
- `src/Simplex/Chat/Library/Subscriber.hs` — owner send (LINK callback),
relay forward-only `processEvent` case, subscriber forwarded
`processForwardedMsg` case.
- `src/Simplex/Chat/Library/Commands.hs` — remove sync `connectToRelay`,
`APIGetUpdatedGroupLinkData` calls async helper.
- `src/Simplex/Chat/Store/Groups.hs` — adjust relay-member lookup to filter
on `memberCurrent`.
- `docs/protocol/channels-protocol.md` — signing-required table row,
relay-addition subsection.
- `tests/ChatTests/...` — tests per "Test surface" above.
plans/2026-05-09-desktop-tray-implementation.md
+422
View File
@@ -0,0 +1,422 @@
# Desktop tray icon — implementation plan
Companion to the design at `plans/2026-05-09-desktop-tray.md`. Read that first.
## What
Seven small commits that build the feature incrementally. After each commit the build is green and the app still runs; only the last commit makes the feature visible to the user end-to-end.
## Why
We split the work this way so each commit is reviewable on its own and revertable without unwinding others. The order keeps the build green throughout (no commit introduces a reference to something the next commit will define).
## How
### Pre-flight
- Pull the branch `sh/tray` (current branch). It is at `stable`.
- Confirm dev environment can build desktop: `cd apps/multiplatform && ./gradlew :common:desktopMainClasses` — should succeed before any change.
- Read `plans/2026-05-09-desktop-tray.md` end to end. The implementation steps below assume that design is settled.
---
### Task 1 — `CloseBehavior` enum + preference
**Files**
- `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt`
**What to add.** The enum lives next to other small enums in this file (search for `enum class LAMode` for placement convention). The preference goes in `class AppPreferences` next to `notificationsMode`.
Match the existing pattern (use `values().firstOrNull { it.name == this }`, not `entries`, to stay consistent with `LAMode` and others in this file):
```kotlin
enum class CloseBehavior {
Ask, Quit, MinimizeToTray;
companion object { val default = Ask }
}
// In AppPreferences:
val closeBehavior: SharedPreference<CloseBehavior> =
mkSafeEnumPreference(SHARED_PREFS_DESKTOP_CLOSE_BEHAVIOR, CloseBehavior.default)
```
Add the constant at the bottom of `AppPreferences` next to other `SHARED_PREFS_*` constants:
```kotlin
private const val SHARED_PREFS_DESKTOP_CLOSE_BEHAVIOR = "DesktopCloseBehavior"
```
**Verify.** Build: `./gradlew :common:desktopMainClasses` — succeeds. No behavior change yet.
**Commit.** `desktop: add CloseBehavior preference`
---
### Task 2 — Window-visibility state + branching close handler (no dialog, no tray yet)
**(Note: a `Task 2 — Add ComposeNativeTray dependency` is removed. We now use Compose Multiplatform's built-in `androidx.compose.ui.window.Tray`, already on the classpath via the `org.jetbrains.compose` plugin. No new dep.)**
**Files**
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt`
**What to change.**
1. Add `windowVisible` to `SimplexWindowState` (the class at line 227):
```kotlin
class SimplexWindowState {
// ...existing fields...
val windowVisible = mutableStateOf(true)
}
```
2. In `AppWindow`, pass it to `Window`:
```kotlin
Window(
state = windowState,
visible = simplexWindowState.windowVisible.value,
icon = painterResource(MR.images.ic_simplex),
onCloseRequest = { handleCloseRequest(closedByError) },
// ...rest unchanged...
)
```
3. Add the handler at file scope (or near `showApp`). Temporarily make `Ask` fall through to `Quit` — the dialog comes in Task 3:
```kotlin
private fun ApplicationScope.handleCloseRequest(closedByError: MutableState<Boolean>) {
if (closedByError.value) { closedByError.value = false; exitApplication(); return }
when (appPrefs.closeBehavior.get()) {
CloseBehavior.Quit, CloseBehavior.Ask -> {
closedByError.value = false
exitApplication()
}
CloseBehavior.MinimizeToTray -> {
simplexWindowState.windowVisible.value = false
}
}
}
```
The `MinimizeToTray` branch will get a tray-availability guard in Task 5 (defensive: a user could have set the pref on a different machine where tray works).
(Imports: `chat.simplex.common.model.CloseBehavior`, `chat.simplex.common.model.ChatController.appPrefs`.)
**Verify.** Build + run desktop:
```
./gradlew :desktop:run
```
Click X — app exits exactly as today. No dialog, no tray. (Internal preference is `Ask`, branch falls through to Quit.)
**Commit.** `desktop: branch close handler on CloseBehavior preference`
---
### Task 3 — First-close dialog
**Files**
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopTray.kt` *(new)*
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt`
- `apps/multiplatform/common/src/commonMain/resources/MR/base/strings.xml`
**Strings.** Add to `strings.xml`:
```xml
<string name="close_behavior_dialog_title">Minimize to tray?</string>
<string name="close_behavior_dialog_text">If you choose Close, messages won\'t be received.\nYou can change it later in Appearance settings.</string>
<string name="close_behavior_dialog_close">Close the app</string>
<string name="close_behavior_dialog_minimize">Minimize to tray</string>
```
**`DesktopTray.kt` — dialog only.** A `mutableStateOf<Pair<onClose, onMinimize>?>` global, and a Composable that, when set, renders a non-dismissible `Dialog` with the two buttons. Skeleton:
```kotlin
package chat.simplex.common
import androidx.compose.foundation.layout.*
import androidx.compose.material.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.*
import chat.simplex.res.MR
import dev.icerock.moko.resources.compose.stringResource
private val pendingCloseChoice = mutableStateOf<CloseChoice?>(null)
private data class CloseChoice(val onClose: () -> Unit, val onMinimize: () -> Unit)
fun requestCloseBehavior(onClose: () -> Unit, onMinimize: () -> Unit) {
pendingCloseChoice.value = CloseChoice(onClose, onMinimize)
}
@Composable
fun CloseBehaviorDialog() {
val choice = pendingCloseChoice.value ?: return
Dialog(
onCloseRequest = { /* swallow — non-dismissible */ },
state = rememberDialogState(width = 420.dp, height = 220.dp),
title = stringResource(MR.strings.close_behavior_dialog_title),
resizable = false,
) {
Column(Modifier.padding(24.dp)) {
Text(stringResource(MR.strings.close_behavior_dialog_text))
Spacer(Modifier.height(24.dp))
Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
Button(
onClick = { pendingCloseChoice.value = null; choice.onClose() },
colors = ButtonDefaults.buttonColors(backgroundColor = MaterialTheme.colors.error),
) { Text(stringResource(MR.strings.close_behavior_dialog_close)) }
// Hide the Minimize button when tray isn't supported (stock GNOME).
// The dialog still asks once so the user gets a definitive Quit answer
// and doesn't see the dialog again. trayIsAvailable is defined in Task 5;
// until then, the button is always shown.
Button(
onClick = { pendingCloseChoice.value = null; choice.onMinimize() },
colors = ButtonDefaults.buttonColors(backgroundColor = MaterialTheme.colors.primary),
) { Text(stringResource(MR.strings.close_behavior_dialog_minimize)) }
}
}
}
}
```
**Wire it up in `DesktopApp.kt`.** Inside `application(exitProcessOnExit = false) { … }`, render `CloseBehaviorDialog()` alongside `AppWindow`. Update `handleCloseRequest`'s `Ask` branch:
```kotlin
CloseBehavior.Ask -> requestCloseBehavior(
onClose = {
appPrefs.closeBehavior.set(CloseBehavior.Quit)
closedByError.value = false
exitApplication()
},
onMinimize = {
appPrefs.closeBehavior.set(CloseBehavior.MinimizeToTray)
simplexWindowState.windowVisible.value = false
}
)
```
**Verify.** Run, click X — dialog appears with the exact text and button colors. Click "Close the app" → exits. Reopen, click X — exits without dialog (preference is `Quit`).
To reset the preference for re-testing, delete the SimpleX Chat desktop preferences file:
- Linux: `~/.config/simplex/SimpleXChatDesktop.properties`
- macOS: `~/Library/Preferences/SimpleXChatDesktop.properties`
- Windows: `%AppData%\SimpleX\SimpleXChatDesktop.properties`
Click "Minimize to tray" → window hides; the app process keeps running but is invisible (no tray icon yet — that's Task 6). Kill the JVM with Ctrl-C in the terminal to recover.
**Commit.** `desktop: first-close dialog for tray choice`
---
### Task 4 — Tray icon resources
**Files**
- `apps/multiplatform/common/src/commonMain/resources/MR/images/ic_simplex_tray_dot.svg`
- `apps/multiplatform/common/src/commonMain/resources/MR/base/strings.xml`
**Icons.** Reuse the existing `MR.images.ic_simplex` for the no-unread case and add a single new asset for the unread case:
- `ic_simplex_tray_dot` — copy of `ic_simplex.svg` with a small red filled circle added in the bottom-right (~6px radius in the 40×40 viewBox).
Drop the SVG into `MR/images/`. Moko picks it up; refer to as `MR.images.ic_simplex_tray_dot`. Run a build to check generation: `./gradlew :common:generateMRcommonMain`.
**Strings.** Tray menu items + tooltip strings:
```xml
<string name="tray_show">Show SimpleX</string>
<string name="tray_quit">Quit SimpleX</string>
<string name="tray_tooltip">SimpleX</string>
<string name="tray_tooltip_unread">SimpleX — %d unread</string>
```
**Verify.** Build succeeds; the generated `MR.images.ic_simplex_tray_dot` and `MR.strings.tray_*` symbols compile when referenced from a temporary scratch file (delete after).
**Commit.** `desktop: tray icon assets and menu strings`
---
### Task 5 — Tray composable (no unread indicator yet)
**Files**
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopTray.kt`
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt`
**Add to `DesktopTray.kt`.** Tray-availability probe, functions to show window and quit, the Tray composable itself.
```kotlin
import androidx.compose.ui.window.ApplicationScope
import androidx.compose.ui.window.Tray
import androidx.compose.ui.window.MenuBar
import dev.icerock.moko.resources.compose.painterResource
import dev.icerock.moko.resources.compose.stringResource
import java.awt.SystemTray
// Probed once at startup. Performs a real add/remove of a transparent TrayIcon
// because SystemTray.isSupported() can return true while add() throws (JDK-8322750).
val trayIsAvailable: Boolean by lazy {
if (!SystemTray.isSupported()) return@lazy false
try {
val tray = SystemTray.getSystemTray()
val probe = TrayIcon(BufferedImage(1, 1, BufferedImage.TYPE_INT_ARGB))
tray.add(probe); tray.remove(probe); true
} catch (e: AWTException) { false } catch (e: SecurityException) { false }
}
fun showWindow() {
simplexWindowState.windowVisible.value = true
simplexWindowState.window?.toFront()
simplexWindowState.window?.requestFocus()
}
@Composable
fun ApplicationScope.SimplexTray(closedByError: MutableState<Boolean>) {
if (!trayIsAvailable) return
if (appPrefs.closeBehavior.state.value != CloseBehavior.MinimizeToTray) return
Tray(
icon = painterResource(MR.images.ic_simplex_tray),
tooltip = stringResource(MR.strings.tray_tooltip),
onAction = ::showWindow,
menu = {
Item(stringResource(MR.strings.tray_show), onClick = ::showWindow)
Separator()
Item(stringResource(MR.strings.tray_quit), onClick = {
closedByError.value = false
exitApplication()
})
}
)
}
```
(Note: this uses Compose Multiplatform's built-in `androidx.compose.ui.window.Tray`. The API is `icon: Painter`, `onAction` (not `primaryAction`), menu DSL uses `Separator()` (not `Divider()`).)
**Update `DesktopApp.kt`'s close handler** to add the defensive tray-availability check from Task 2's TODO:
```kotlin
CloseBehavior.MinimizeToTray -> {
if (trayIsAvailable) {
simplexWindowState.windowVisible.value = false
} else {
closedByError.value = false
exitApplication()
}
}
```
**Wire into `DesktopApp.kt`.** Inside `application(exitProcessOnExit = false) { … }`:
```kotlin
SimplexTray(closedByError)
CloseBehaviorDialog()
AppWindow(closedByError)
```
The order doesn't affect rendering — the tray and dialog are top-level surfaces.
**Verify.** Run; in the dialog pick "Minimize to tray". Window hides; tray icon appears. Left-click tray — window restores. Right-click tray — menu has "Show SimpleX" and "Quit SimpleX". Both work. Quit, restart — preference persists; clicking X hides directly without dialog. Tray icon appears at app startup (because the preference is now `MinimizeToTray`).
**Commit.** `desktop: system tray icon with show/quit menu`
---
### Task 6 — Unread indicator + tooltip count
**Files**
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopTray.kt`
**Change `SimplexTray`.** Replace the static icon and tooltip with reactive ones:
```kotlin
// UserInfo.unreadCount is incremented only when ntfsEnabled(item) — see SimpleXAPI.kt:2781-2783.
val unread by remember {
derivedStateOf { ChatModel.users.sumOf { it.unreadCount } }
}
val iconRes = if (unread > 0) MR.images.ic_simplex_tray_dot else MR.images.ic_simplex
val tooltip =
if (unread > 0) stringResource(MR.strings.tray_tooltip_unread, unread)
else stringResource(MR.strings.tray_tooltip)
Tray(
icon = painterResource(iconRes),
tooltip = tooltip,
// onAction + menu unchanged
)
```
**Verify.**
1. With "Minimize to tray" enabled, hide the window.
2. Trigger a notification (have another account/contact send you a message; or open a direct chat with notifications enabled and post from another device).
3. Tray icon switches to the red-dot variant; tooltip shows "SimpleX — 1 unread" (or higher).
4. Click tray, view the message in the relevant chat. Icon reverts to the plain variant; tooltip becomes "SimpleX".
**Commit.** `desktop: unread indicator on tray icon`
---
### Task 7 — Appearance settings toggle
**Files**
- `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/views/usersettings/Appearance.desktop.kt`
- `apps/multiplatform/common/src/commonMain/resources/MR/base/strings.xml`
**Strings.**
```xml
<string name="appearance_minimize_to_tray">Minimize to tray when closing window</string>
<string name="appearance_minimize_to_tray_desc">Keep SimpleX running in the background to receive messages.</string>
```
**UI row.** In `AppearanceLayout` (the Composable around line ~38), add a new section row using the existing `SectionItemView` / `SettingsActionItemWithContent` / similar patterns visible in this file. The entire row is gated on `trayIsAvailable` — if the OS has no tray host, the toggle is omitted. Read the surrounding rows for the exact convention; the snippet below is illustrative:
```kotlin
if (trayIsAvailable) {
val pref = remember { appPrefs.closeBehavior.state }
val on = pref.value == CloseBehavior.MinimizeToTray
SectionItemView {
Row(verticalAlignment = Alignment.CenterVertically) {
Column(Modifier.weight(1f)) {
Text(stringResource(MR.strings.appearance_minimize_to_tray))
Text(
stringResource(MR.strings.appearance_minimize_to_tray_desc),
style = MaterialTheme.typography.caption,
color = MaterialTheme.colors.onSurface.copy(alpha = 0.7f)
)
}
Switch(
checked = on,
onCheckedChange = { checked ->
appPrefs.closeBehavior.set(if (checked) CloseBehavior.MinimizeToTray else CloseBehavior.Quit)
}
)
}
}
}
```
Place the row in the existing `AppearanceLayout` Composable, after the theme/dark-mode rows and before the language selector — that grouping is for general window-and-display preferences and the new toggle fits there. Match the styling of nearby rows. If a clearer section emerges during implementation, add a new `SectionView` with a "Window" header instead.
**Verify.** Open Appearance settings; toggle the row off — tray icon disappears; click X exits with no dialog. Toggle back on — tray icon reappears (Compose recomposes the gated `Tray` composable). Window-close behavior still depends on the toggle.
**Commit.** `desktop: Appearance toggle for minimize-to-tray`
---
### Final manual test pass
Run the full test plan from the spec on each platform you can reach (Linux KDE, Windows 11, macOS):
1. Fresh install (clear `~/.config/simplex/` or per-OS data dir). Click X → dialog with the right text and button colors. Esc / outside-tap do nothing.
2. Pick Close → exits. Reopen → click X → exits with no dialog.
3. Reset, pick Minimize to tray → window hides, tray icon shows.
4. Receive a message → red-dot variant + tooltip count.
5. Click tray → window restores and focuses (acceptable if focus is best-effort per spec).
6. Right-click tray → Show / Quit both work.
7. Appearance toggle off → tray vanishes, X exits without dialog.
8. Appearance toggle on → tray reappears.
If anything fails, file follow-ups; the spec's "out of scope" list catches the expected omissions (autostart, number-on-icon, etc.).
plans/2026-05-09-desktop-tray.md
+197
View File
@@ -0,0 +1,197 @@
# Desktop tray icon — minimize to tray on close
## What
Add a system tray icon (Windows notification area, Linux StatusNotifierItem, macOS menu bar) to the SimpleX desktop app, with a "minimize to tray" close behavior gated on first-time user choice.
Three pieces:
1. **First-close dialog** — the first time the user clicks the window's close (X) button, a modal asks whether to close the app or minimize it to the tray. The choice is remembered.
2. **Tray icon** — when the user has chosen "minimize to tray", the app installs a tray icon with a small right-click menu (Show / Quit) and an unread indicator. Clicking the icon restores the window.
3. **Appearance setting** — a "Minimize to tray when closing window" toggle in Appearance settings lets the user change their mind later.
Scope: Linux + Windows + macOS. No autostart. No number-on-icon unread badge. No profile switcher in the tray menu.
## Why
Today, closing the SimpleX desktop window quits the process and the user stops receiving messages until they reopen the app. There is no way to keep the app running quietly in the background, which is the standard expectation for a chat client.
We want this to be opt-in rather than a behavior change for existing users — hence the dialog on first close. Users who prefer the current quit-on-close behavior get exactly that with one click and never see the dialog again. Users who want background message delivery get it with one click and can manage it from settings.
We are using Compose Multiplatform's built-in `androidx.compose.ui.window.Tray` rather than a third-party library. It works cleanly on Windows, macOS, and Linux desktops with a system tray host (KDE Plasma, XFCE, Cinnamon, MATE, GNOME with the AppIndicator extension). The trade-off is that on stock GNOME the JDK deliberately returns `false` from `SystemTray.isSupported()` (per JDK-8322750), so we **probe at startup and disable the feature entirely** when the OS reports no tray support — the dialog hides the "Minimize to tray" option and the Appearance toggle is hidden too. Users with a working tray get the feature; users without never see broken/invisible UI.
All tray-specific code lives in `desktopMain` only. The Android target compiles none of it — there are no expect/actual surfaces calling into tray functionality from `commonMain`.
Users upgrading from a prior version will see the dialog on their first window-close after the update — that is intentional. The dialog is the chosen mechanism for getting consent before keeping a process running in the background, and an existing user has no way to give that consent in advance.
## How
### Close behavior — preference and flow
Add an enum preference:
```kotlin
enum class CloseBehavior { Ask, Quit, MinimizeToTray }
// in AppPreferences:
val closeBehavior: SharedPreference<CloseBehavior> =
mkSafeEnumPreference(SHARED_PREFS_DESKTOP_CLOSE_BEHAVIOR, CloseBehavior.default)
```
`Ask` is the default for fresh installs and for users upgrading from a version that did not have this preference.
Replace the inline close handler in `DesktopApp.kt` (currently `onCloseRequest = { closedByError.value = false; exitApplication() }`) with a function that branches on the preference:
- **Crash recovery first.** If `closedByError.value == true`, exit immediately with no dialog, no minimize. The crash handler at `DesktopApp.kt:46-47` dispatches `WINDOW_CLOSING` and depends on the application loop ending so it can re-enter. Honouring `closedByError` is what keeps that path working.
- `Quit` → exit immediately, as today.
- `MinimizeToTray` → set `simplexWindowState.windowVisible.value = false` and return.
- `Ask` → show the first-close dialog. The dialog's button writes the preference and then performs the corresponding action.
The same handler is invoked for the X button, Alt+F4 on Windows, and the macOS red traffic-light close — Compose routes all three through `onCloseRequest`. **macOS Cmd+Q is not routed through `onCloseRequest`**: it goes through the application menu's Quit and calls `exitApplication()` directly. We accept that as "always quit" — Cmd+Q is an explicit user intent to quit the application and should not be intercepted by the dialog. Programmatic `WindowEvent.WINDOW_CLOSING` (e.g. from the crash handler) reaches `onCloseRequest` and is handled by the `closedByError` branch above.
The dialog is non-dismissible (no Esc, no outside-tap) so the user must choose. Wording verbatim:
> **Minimize to tray?**
>
> If you choose Close, messages won't be received.
> You can change it later in Appearance settings.
>
> [ Close the app ] [ Minimize to tray ]
The "Close the app" button uses `MaterialTheme.colors.error` (red); "Minimize to tray" uses `MaterialTheme.colors.primary` (blue). The dialog is implemented bespoke (not via the existing `AlertManager`), because `AlertManager` does not support the non-dismissible + custom-button-color combination needed here.
The Compose application loop already runs with `exitProcessOnExit = false`, so hiding the window does not exit the process. No restructuring of `showApp()` is needed.
### Tray icon
No new dependency. We use `androidx.compose.ui.window.Tray` (built into Compose Multiplatform, already on the classpath). It wraps `java.awt.SystemTray` under the hood — works wherever AWT's tray works, returns silently when it doesn't.
**Tray availability probe.** `java.awt.SystemTray.isSupported()` alone is not reliable — there is a JDK pattern where it returns `true` but `SystemTray.add()` then throws `AWTException` (and Compose-MP does not catch it). We expose a `desktopMain` value that runs a real add/remove of a transparent `TrayIcon` inside a `try/catch` and caches the result:
```kotlin
val trayIsAvailable: Boolean by lazy {
if (!SystemTray.isSupported()) return@lazy false
try {
val tray = SystemTray.getSystemTray()
val probe = TrayIcon(BufferedImage(1, 1, BufferedImage.TYPE_INT_ARGB))
tray.add(probe)
tray.remove(probe)
true
} catch (e: AWTException) { false }
catch (e: SecurityException) { false }
}
```
The probe is force-evaluated at the top of `showApp()` (off the EDT) so the JDK-8322750 GNOME detection subprocess does not block composition. When `false`: the Appearance toggle is hidden, the first-close dialog is skipped (`Ask` migrates silently to `Quit`), and the close handler treats `MinimizeToTray` as `Quit` (in case the preference was carried over from a tray-capable machine).
The tray composable lives next to `AppWindow` inside `application(exitProcessOnExit = false) { … }` in `showApp()`. It is gated by the preference AND by tray availability:
```kotlin
if (trayIsAvailable && appPrefs.closeBehavior.state.value == CloseBehavior.MinimizeToTray) {
// UserInfo.unreadCount is the pre-aggregated, ntfs-filtered counter — see SimpleXAPI.kt:2781-2783.
val unread by remember { derivedStateOf {
ChatModel.users.sumOf { it.unreadCount }
} }
val iconRes = if (unread > 0) MR.images.ic_simplex_tray_dot else MR.images.ic_simplex
val tooltip = if (unread > 0)
stringResource(MR.strings.tray_tooltip_unread, unread)
else
stringResource(MR.strings.tray_tooltip)
Tray(
icon = painterResource(iconRes),
tooltip = tooltip,
onAction = ::showWindow,
menu = {
Item(stringResource(MR.strings.tray_show), onClick = ::showWindow)
Separator()
Item(stringResource(MR.strings.tray_quit), onClick = { exitApplication() })
}
)
}
```
Note: Compose's `Tray` takes `icon: Painter` (not `iconContent`), `onAction` (not `primaryAction`), and the menu DSL uses `Separator()` (not `Divider()`). These are the right names for the built-in API.
`showWindow()` sets `windowVisible.value = true` and calls `window?.toFront()` + `window?.requestFocus()`. Quitting from the tray menu just calls `exitApplication()` — `closedByError` is already `false` in the non-crash path, so the outer loop in `showApp()` terminates cleanly.
**Unread indicator.** Icon swap based on `hasUnread`: reuse `ic_simplex` when zero, `ic_simplex_tray_dot` (same icon with a red dot overlay in the bottom-right) otherwise. Compose passes the `Painter` into AWT via `Painter.toAwtImage(density, layoutDirection, size)` — a single bitmap per state. One new image resource is enough:
- `MR.images.ic_simplex_tray_dot` — base icon with the red-dot overlay.
**Icon size.** Compose `Tray` rasterises the `Painter` once at a per-platform target size: Linux 22×22, Windows 16×16, macOS 22×22 (with retina 2×). It's a single bitmap, so we source the painter at a comfortable size (e.g. via a `painterResource(MR.images.ic_simplex)` from the 40×40 SVG already shipped) and let the conversion handle the scale. We accept the slight scaling cost on 16×16 Windows panels rather than ship multiple size variants.
**Tooltip.** Plain "SimpleX" when unread is zero; "SimpleX — N unread" otherwise.
**Window restore is best-effort.** Compose Multiplatform issue [#4231](https://github.com/JetBrains/compose-multiplatform/issues/4231) documents that `toFront()` does not always pull the restored window above other windows on Linux/Windows — the OS may flash the taskbar entry instead. Acceptable for v1; if it bites users we can add the `isAlwaysOnTop = true; toFront(); isAlwaysOnTop = false` workaround in a follow-up.
**No collision with the existing notification path.** `NtfManager.desktop.kt:178-188` contains an `java.awt.SystemTray` hack inside a private helper that turns out to be unreachable — the live notification path is `displayNotificationViaLib` (TwoSlices). The hack will not fire and cannot conflict with our tray icon. Cleaning up that dead code is out of scope here.
**Toggling at runtime.** The `Tray { … }` composable is gated on `closeBehavior.state.value == MinimizeToTray`; Compose's recomposition lifecycle handles install/uninstall when the user flips the setting. No `LaunchedEffect` is needed.
**Android isolation.** All tray code (the `Tray` composable, the close-behavior dialog, `showWindow`, the `trayIsAvailable` probe) lives in `desktopMain` only. The Android target compiles none of it — there are no expect/actual surfaces from `commonMain` calling into tray functionality. The only shared piece is the `CloseBehavior` enum + `closeBehavior` preference in `SimpleXAPI.kt`, which is plain data and never references tray APIs.
### Appearance settings row
In `Appearance.desktop.kt`, add one row to the existing settings section — **only when `trayIsAvailable`**:
> ☑ **Minimize to tray when closing window**
> *Keep SimpleX running in the background to receive messages.*
The toggle maps to the preference:
- `MinimizeToTray` → on.
- `Quit` or `Ask` → off.
Flipping on writes `MinimizeToTray`. Flipping off writes `Quit`. Touching the toggle resolves the `Ask` state to a definitive value — so a fresh-install user who opens Appearance settings, flips the row off, and then closes the window will *not* see the dialog (their preference is now `Quit`). This matches the user's apparent intent (they made a choice in settings) and avoids the surprise of a dialog appearing for a setting they thought they had already configured.
When `trayIsAvailable` is `false` (stock GNOME without AppIndicator extension), the entire row is omitted from Appearance settings, the first-close dialog is skipped (`Ask` migrates silently to `Quit`), and the close handler treats `MinimizeToTray` as `Quit` (in case the user previously enabled it on a different machine).
The wording "Minimize to tray" is used uniformly across all platforms, including macOS where the more native term would be "menu bar". A consistent in-app term is more important here than per-platform purity.
### Files changed
| File | Change |
|---|---|
| `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt` | Add `CloseBehavior` enum, `closeBehavior` preference, `SHARED_PREFS_DESKTOP_CLOSE_BEHAVIOR` constant. *(already in this branch as commit 1)* |
| `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopApp.kt` | Replace inline `onCloseRequest`; add `windowVisible` to `SimplexWindowState`; wire `Window(visible = …)`; host the `Tray` composable conditionally on `trayIsAvailable && closeBehavior == MinimizeToTray`. |
| `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/DesktopTray.kt` *(new)* | `trayIsAvailable` probe, `requestCloseBehavior` + `CloseBehaviorDialog`, `SimplexTray` composable, `showWindow` helper. |
| `apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/views/usersettings/Appearance.desktop.kt` | Add the toggle row (gated on `trayIsAvailable`). |
| `apps/multiplatform/common/src/commonMain/resources/MR/base/strings.xml` | Add 8 new strings (dialog title/body/buttons, settings row, tray menu). |
| `apps/multiplatform/common/src/commonMain/resources/MR/images/` | Add `ic_simplex_tray` + `ic_simplex_tray_dot`. |
No `build.gradle.kts` change — Compose's `Tray` is already on the classpath via the existing `org.jetbrains.compose` plugin.
### New strings
```xml
<string name="close_behavior_dialog_title">Minimize to tray?</string>
<string name="close_behavior_dialog_text">If you choose Close, messages won\'t be received.\nYou can change it later in Appearance settings.</string>
<string name="close_behavior_dialog_close">Close the app</string>
<string name="close_behavior_dialog_minimize">Minimize to tray</string>
<string name="appearance_minimize_to_tray">Minimize to tray when closing window</string>
<string name="appearance_minimize_to_tray_desc">Keep SimpleX running in the background to receive messages.</string>
<string name="tray_show">Show SimpleX</string>
<string name="tray_quit">Quit SimpleX</string>
```
### Out of scope
The following are deliberately not in this PR:
- **Run on system startup / autostart entries.** Per-platform integration (Windows registry Run key, Linux `~/.config/autostart/*.desktop`, macOS LaunchAgents) is its own design.
- **Number-on-icon unread badges.** Cross-platform text rendering on tray icons is fragile across DPIs and macOS menu bar tinting.
- **Per-profile switcher / mute / mark-all-read** in the tray menu. Keep the menu to Show / Quit for now.
- **macOS template (auto-tinting) icon.** Compose `Tray` doesn't expose `NSImage.setTemplate:`; the tray icon will be a colored bitmap on macOS. Acceptable initial cost.
- **GNOME workaround documentation.** Users on stock GNOME won't see the option at all (probe returns false). We don't bundle or recommend the AppIndicator extension from the app itself; if we want to surface that guidance, it goes in the website/help docs, not in this PR.
### Test plan
Verified manually on at least one Linux (KDE Plasma), Windows 11, and macOS host:
1. Fresh install. Click X on the window. Dialog appears with the exact text and button colors. Dialog cannot be dismissed by Esc or outside-click.
2. Click "Close the app". App exits. Reopen, click X — app exits with no dialog (preference is now `Quit`).
3. Reset preference (or fresh install). Click X, click "Minimize to tray". Window hides. Tray icon appears.
4. Send a message to yourself / receive one. Tray icon switches to the red-dot variant; tooltip updates with unread count.
5. Click tray icon (left-click). Window restores and gains focus. Unread is cleared on viewing the chat.
6. Right-click tray icon. Menu shows "Show SimpleX" and "Quit SimpleX". Both work.
7. Open Appearance settings, flip "Minimize to tray when closing window" off. Tray icon disappears. Click X — app exits with no dialog.
8. Flip the toggle back on. Tray icon appears immediately (the composable is gated on the preference, so installation/removal follows the toggle).
plans/2026-05-09-fix-image-text-overlap.md
+83
View File
@@ -0,0 +1,83 @@
# Fix tall image preview overlapping caption text
Branch: `nd/fix-image-text-overlap` · commit `0a3dcd249` · analogous to iOS PR [#6732](https://github.com/simplex-chat/simplex-chat/pull/6732).
## 1. Problem statement
For a tall image (height/width ≳ 2.33), the chat-bubble caption text was rendered on top of the bottom of the image instead of cleanly below it. The image looked like it had a semi-transparent text watermark across its lower section. Reproduced on Android and desktop with any sufficiently tall image; never reproduced on images with `height ≤ 2.33 × width`.
iOS already had the analogous fix (PR #6732, commit `b24d003a8`); Android/desktop did not.
## 2. Solution summary
One line in `apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/chat/item/CIImageView.kt`. The image preview Box's `Modifier.aspectRatio(width / height)` is wrapped with `.coerceAtLeast(1f / 2.33f)` so the aspect ratio cannot go below the floor at which the layout starts to break.
```diff
- Modifier.width(w).aspectRatio(previewBitmap.width.toFloat() / previewBitmap.height.toFloat())
+ Modifier.width(w).aspectRatio((previewBitmap.width.toFloat() / previewBitmap.height.toFloat()).coerceAtLeast(1f / 2.33f))
```
Total diff: 1 file, +1 / −1.
## 3. Root cause
`PriorityLayout` (`FramedItemView.kt:480`, added in #6726) caps image-region height at `constraints.maxWidth × 2.33f` and passes that as `maxHeight` to its image child:
```kotlin
val maxImageHeight = (constraints.maxWidth * 2.33f).toInt().coerceAtMost(constraints.maxHeight)
val imageConstraints = constraints.copy(maxHeight = maxImageHeight)
val imagePlaceable = … .measure(imageConstraints)
```
The image child is `CIImageView`'s outer Box, modified (line 185 pre-fix) by `Modifier.width(w).aspectRatio(previewBitmap.width / previewBitmap.height)`. Compose's `aspectRatio` modifier picks a layout size satisfying both the parent's constraints AND the requested ratio — by trying `tryMaxWidth`, `tryMaxHeight`, `tryMinWidth`, `tryMinHeight` in order and returning the first satisfying `IntSize`.
When the natural ratio is below `1/2.33`, every candidate violates one bound:
- `tryMaxWidth`: implied `height = W / ratio > W × 2.33 = parentMaxHeight` → fails the height cap.
- `tryMaxHeight`: implied `width = parentMaxHeight × ratio < W` → fails the fixed `.width(W)` lower bound.
- `tryMinWidth` / `tryMinHeight`: same failures.
`findSize()` returns `IntSize.Zero`, and `aspectRatio` falls through to passing the parent's UNBOUNDED-height-shape constraints down (`wrappedConstraints = constraints` — see Compose Foundation's `AspectRatioNode`). The inner `Image` (`.width(W).contentScale=FillWidth`) then sizes itself by intrinsic aspect, with `height = W × imgH/imgW`, drawing past the layout box `clipToBounds` would have given it. The text below then renders on the same vertical strip as the painter's overflow — visible as overlap.
`PriorityLayout`'s height cap (added in #6726) prevents the original crash but does not, on its own, prevent this visual overflow, because the cap propagates through `imageConstraints` to a modifier that silently drops it.
## 4. The fix in detail
`coerceAtLeast(1f / 2.33f)` raises the ratio's floor to exactly the value where Compose's `tryMaxWidth` succeeds:
- At `ratio = 1/2.33`, implied `height = W / (1/2.33) = W × 2.33 ≤ parentMaxHeight` (since `W ≤ parentMaxWidth` and `parentMaxHeight = parentMaxWidth × 2.33`).
- `findSize` returns `(W, W × 2.33)`. `wrappedConstraints` becomes `Constraints.fixed(W, W × 2.33)` — both dimensions fixed.
- Inner `Image`'s `paint` modifier sees `hasFixedDimens=true` and returns the constraints unchanged. Image bounds = `(W, W × 2.33)`.
- `Image`'s built-in `clipToBounds` clips the painter's `FillWidth` overflow to the bounded layout. `PriorityLayout` reads `imagePlaceable.measuredHeight = W × 2.33` and places the caption text immediately below.
For images at or above the floor (ratio ≥ 1/2.33), `coerceAtLeast` is a no-op — the ratio is unchanged, the layout is unchanged, no behavioural diff. The change only takes effect for images that triggered the bug.
`coerceAtLeast` (not `maxOf`) matches the idiom already used at `FramedItemView.kt:480` (`.coerceAtMost(constraints.maxHeight)`) — both clamp at the bound where the layout starts to break. Reads as "ensure the ratio is at least 1/2.33".
## 5. Why this specific shape
- **Why preserve the existing expression untouched.** The pre-fix `previewBitmap.width.toFloat() / previewBitmap.height.toFloat()` is the aspect-ratio computation. Wrapping it `(...).coerceAtLeast(1f / 2.33f)` makes the diff purely additive — a reviewer reading the patch sees "the existing ratio is now floored", with zero risk that the inner expression silently changed. Diff is one line, character-minimal.
- **Why no `MAX_IMAGE_HEIGHT_RATIO` constant.** Two use sites of `2.33f` after the fix (`PriorityLayout` line 480 and the new clamp). `good-code-v5.md`: *"Three similar lines are better than a premature abstraction."* If a third site appears (link preview, video preview, etc.) the constant earns its place. Until then, local duplication mirrors the convention already in `PriorityLayout`.
- **Why no edit to `CIVideoView`.** The screenshot showed only the image-preview bug. iOS PR #6732 also touched `CIVideoView` and `CILinkView`, but on Android/desktop the video preview's outer Box has no `aspectRatio` modifier at all — it is sized by its inner `VideoPreviewImageView`'s `.width(width).FillWidth`, which is paint-clamped by `imageConstraints.maxHeight` and reports a correct layout size. If a tall-video overlap is actually reported in the wild, the fix is a separate commit; speculatively replicating the iOS scope would expand the diff and review surface beyond what the bug requires.
- **Why no `fillMaxSize + ContentScale.Crop` rewrite of the inner `Image`.** A previous iteration of this fix did that to mirror iOS's `scaledToFill` change. It works, but is structurally redundant: once the outer Box's `aspectRatio` is bounded, the inner `Image`'s existing `paint` modifier (`hasFixedDimens=true → return constraints`) and `clipToBounds` already produce the same visual result. The rewrite was extra structure, not bug-fix; reverted.
- **Why no `PriorityLayout` constant rename.** `2.33f` is already inline at line 480 and works as-is. Extracting it to `MAX_IMAGE_HEIGHT_RATIO` would be a rename bundled with a bugfix — `good-code-v5.md`: *"a rename in a diff signals a meaningful change to the reviewer — a gratuitous rename wastes reviewer attention and can mask real changes."* Out of scope.
- **Why `coerceAtLeast(1f / 2.33f)` and not `coerceAtLeast(0.43f)`.** The form `1f / 2.33f` makes the relationship to `PriorityLayout`'s `2.33f` height multiplier visually explicit. `0.43f` would be opaque and would drift independently if either value changed.
## 6. Verification
Manual sanity (Android debug APK):
- Send a tall screenshot (height ≫ width) with a caption → caption now sits below the cropped image preview, no overlap.
- Send an image where `height ≤ 2.33 × width` → preview unchanged from pre-fix (the clamp is a no-op for these).
- Tap the cropped preview → fullscreen viewer opens the full image at native aspect (the clamp only affects the inline preview, not the viewer).
## 7. Risk and rollback
- **Blast radius** is the single-Box modifier in `CIImageView` for non-`smallView` mode. `smallView` (used by `ChatPreviewView` thumbnails) takes the `else Modifier` branch and is untouched.
- The clamp is a no-op for images that did not trigger the bug, so regression risk on non-tall images is zero by construction.
- Rollback: `git revert 0a3dcd249` and force-push the branch (or just drop the commit before merge).
plans/2026-05-11-channel-owner-unlimited-delete.md
+36
View File
@@ -0,0 +1,36 @@
# Channel owner unlimited delete
## Problem
Channel owners cannot delete content older than 24 hours. The limit makes sense in p2p groups (no authority, each member holds independent copy). In channels, the owner is the authority - their content, their right to remove it.
## Changes
### PR 1 - subscriber side (release first)
**Subscriber.hs:2168** - `rcvItemDeletable` check on `CIGroupRcv` path. When the sender has editorial role in a channel (`useRelays' gInfo && memberRole' mem >= GRModerator`), skip the time check.
**Subscriber.hs:1912** - `rcvItemDeletable` itself doesn't need to change - the caller skips it.
### PR 2 - owner side (release after subscribers update)
**Messages.hs:535** - `deletable'` returns `True` without time check when the item is in a channel where the user's role >= GRModerator. Needs group context threaded in, or a separate check at the call site.
**Commands.hs:790** - `assertDeletable` for `APIDeleteChatItem` - skip time check for channel editorial roles (>= GRModerator).
**UI (iOS + Kotlin)** - remove the "delete for me / delete for everyone" question for channel owners/admins/moderators. In channels, editorial deletion is always for everyone. The "delete for me only" option makes no sense for a publication.
### Strings
`group_members_can_delete_channel` - "(24 hours)" should note that this limit applies to subscribers, not owners. Owners can delete at any time.
Other `(24 hours)` strings are for direct chats and p2p groups - unchanged.
### Scope
In channels, owners/admins/moderators (role >= GRModerator) get unlimited delete of their own content - they are the editorial team. Members/subscribers stay on 24-hour limit. Moderation of others' content is already unlimited (separate code path, no time check).
## Release order
1. PR 1 ships. Old owners can't send old deletions yet, so nothing changes for subscribers. New subscribers are ready.
2. PR 2 ships. Owners can now delete old content. New subscribers honor it. Old subscribers silently ignore (message stays - acceptable degradation, not an error after PR 1).
plans/2026-05-11-fix-call-bind-port.md
+168
View File
@@ -0,0 +1,168 @@
# Desktop call server: pick a free port when `localhost:50395` is busy
Branch: `nd/fix-call-bind-port` · code commit `587b79779` · PR [#6963](https://github.com/simplex-chat/simplex-chat/pull/6963).
## 1. Problem statement
On Desktop, a WebRTC call runs in the system browser, served by an embedded `NanoWSD` HTTP+WebSocket server. `startServer()` bound that server to a hard-coded port, `SERVER_PORT = 50395` (`apps/multiplatform/common/src/desktopMain/kotlin/chat/simplex/common/views/call/CallView.desktop.kt:23`). If port 50395 was already in use — another instance of the app, a leftover server thread, or any unrelated process — `NanoHTTPD.start()` propagated the bind failure and the call could not start:
```
java.net.BindException: Address already in use: bind
at java.base/sun.nio.ch.Net.bind0(Native Method)
at java.base/sun.nio.ch.Net.bind(Unknown Source)
at java.base/sun.nio.ch.Net.bind(Unknown Source)
at java.base/sun.nio.ch.NioSocketImpl.bind(Unknown Source)
at java.base/java.net.ServerSocket.bind(Unknown Source)
at java.base/java.net.ServerSocket.bind(Unknown Source)
at org.nanohttpd.protocols.http.ServerRunnable.run(ServerRunnable.java:63)
at java.base/java.lang.Thread.run(Unknown Source)
```
A call should not be a single point of contention on one fixed TCP port. When 50395 is taken, the call should bind a different port and proceed.
Scope: Desktop only. Android renders the call in an in-process `WebView` via `WebViewAssetLoader` — no local server, no port — and is unaffected.
## 2. Solution summary
Three changes, all in `CallView.desktop.kt`, plus a one-line spec note. Total diff: 2 files, +24 / −15.
1. **`startServer` retries on a free port.** It gains a `port: Int = SERVER_PORT` parameter (used only by the retry; the single existing call site is unchanged by the default). `server.start()` is wrapped: on `BindException`, log a warning, stop the half-initialised server, and recurse once with `port = 0` — which makes the OS assign any free port. The recursion terminates because `port == 0` rethrows (the kernel does not hand out a busy ephemeral port).
2. **`WebRTCController` opens the browser at the port actually bound.** Previously it opened `http://localhost:50395/simplex/call/` *before* calling `startServer`; now it starts the server first and uses `server.listeningPort` for the URL — which equals `50395` in the normal case, and equals the OS-assigned port after a fallback.
3. **Spec note** in `apps/multiplatform/spec/services/calls.md` describing the fallback.
```diff
+import java.net.BindException
val server = remember {
- try {
- uriHandler.openUri("http://${SERVER_HOST}:$SERVER_PORT/simplex/call/")
- } catch (e: Exception) {
- ... endCall() ...
- }
- startServer(onResponse)
+ startServer(onResponse).apply {
+ try {
+ uriHandler.openUri("http://${SERVER_HOST}:${listeningPort}/simplex/call/")
+ } catch (e: Exception) {
+ ... endCall() ...
+ }
+ }
}
-fun startServer(onResponse: (WVAPIMessage) -> Unit): NanoWSD {
- val server = object: NanoWSD(SERVER_HOST, SERVER_PORT) { /* unchanged */ }
- server.start(60_000_000)
+fun startServer(onResponse: (WVAPIMessage) -> Unit, port: Int = SERVER_PORT): NanoWSD {
+ val server = object: NanoWSD(SERVER_HOST, port) { /* unchanged */ }
+ try {
+ server.start(60_000_000)
+ } catch (e: BindException) {
+ if (port == 0) throw e
+ Log.w(TAG, "Call server port $port is busy, using a random port: ${e.message}")
+ server.stop()
+ return startServer(onResponse, port = 0)
+ }
return server
}
```
The `NanoWSD` object body (request handling, resource serving) is untouched.
## 3. Root cause / how NanoHTTPD binds
`startServer()` builds an anonymous `NanoWSD(SERVER_HOST, SERVER_PORT)` and calls `server.start(60_000_000)`. Inside `NanoHTTPD.start(timeout)`:
```java
this.myServerSocket = this.getServerSocketFactory().create();
this.myServerSocket.setReuseAddress(true);
ServerRunnable serverRunnable = createServerRunnable(timeout);
this.myThread = new Thread(serverRunnable);
this.myThread.start();
while (!serverRunnable.hasBinded() && serverRunnable.getBindException() == null) { Thread.sleep(10L); }
if (serverRunnable.getBindException() != null) throw serverRunnable.getBindException();
```
`ServerRunnable.run()` does the actual `myServerSocket.bind(new InetSocketAddress(hostname, myPort))` on its own thread; if that throws (port in use → `java.net.BindException`, a subclass of `IOException`), it stores the exception, returns, and the accept loop is never entered. `start()` observes the stored exception and rethrows it — which is why the stack trace in the report shows `ServerRunnable.run` rather than `NanoHTTPD.start`: it is the same exception object, captured at the failed `bind`.
`setReuseAddress(true)` already handles the benign case (a just-closed server in `TIME_WAIT`), so the only way `start()` fails this way is a genuine conflict: something else is listening on `50395`. Pre-fix that exception escaped `startServer` → escaped the `remember {}` initialiser in `WebRTCController` → the call view could not establish its control channel.
A fixed port is also unnecessary on the wire. The browser page only ever connects back to *the origin it was served from*: `apps/multiplatform/common/src/commonMain/resources/assets/www/desktop/ui.js` opens `new WebSocket(`ws://${location.host}`)`, and `call.html` references its assets with root-relative paths (`/desktop/style.css`, `/call.js`, …). So the page follows whatever host:port the Kotlin side opened in the browser — there is no second place that hard-codes `50395`.
## 4. The fix in detail
### 4.1 Retry on `port = 0`
`NanoHTTPD`/`NanoWSD` accept port `0`, the standard "let the OS pick a free ephemeral port" convention; after `start()`, `getListeningPort()` (Kotlin: `listeningPort`) returns the concrete port the kernel assigned. So the retry needs no port-scanning loop and no arbitrary range — one fallback attempt, guaranteed to find a free port if one exists at all.
```kotlin
fun startServer(onResponse: (WVAPIMessage) -> Unit, port: Int = SERVER_PORT): NanoWSD {
val server = object: NanoWSD(SERVER_HOST, port) { /* unchanged */ }
try {
server.start(60_000_000)
} catch (e: BindException) {
if (port == 0) throw e
Log.w(TAG, "Call server port $port is busy, using a random port: ${e.message}")
server.stop()
return startServer(onResponse, port = 0)
}
return server
}
```
- `port: Int = SERVER_PORT` — the parameter exists for the recursive retry. `startServer` has exactly one caller in the tree (`WebRTCController`), and the default keeps that call site byte-identical. A default-valued parameter used for internal recursion is a routine Kotlin idiom (`fun f(x, acc = init)`).
- `catch (e: BindException)` — deliberately narrower than `IOException`. The reported failure mode is specifically "address already in use"; any *other* `start()` failure (e.g. an I/O error creating the socket) is not something a different port fixes, so it propagates exactly as before. Surgical: handle the bug, nothing else.
- `if (port == 0) throw e` — terminates the recursion. If even the OS-assigned port fails to bind, that is a pathological condition (no ephemeral ports at all); rethrow rather than loop, preserving the original "give up" behaviour on the second failure.
- `server.stop()` — `start()` assigns `myServerSocket` (an unbound `ServerSocket`) and `myThread` (which has already exited, having caught the bind error) *before* failing. `stop()` closes that orphaned socket and joins the dead thread. Pre-fix this leak was transient (the exception terminated the call attempt); now that the call *recovers* instead of failing, the half-initialised server must be released explicitly. `stop()` is the same call the existing `onDispose` already makes on the live server.
### 4.2 Start the server before opening the browser
The browser URL must carry the port the server actually bound, which is only known after `start()`. So the order in `WebRTCController`'s `remember {}` is inverted: `startServer` first, then `uriHandler.openUri`.
```kotlin
val server = remember {
startServer(onResponse).apply {
try {
uriHandler.openUri("http://${SERVER_HOST}:${listeningPort}/simplex/call/")
} catch (e: Exception) {
Log.e(TAG, "Unable to open browser: ${e.stackTraceToString()}")
AlertManager.shared.showAlertMsg(
title = generalGetString(MR.strings.unable_to_open_browser_title),
text = generalGetString(MR.strings.unable_to_open_browser_desc)
)
endCall()
}
}
}
```
- `.apply { … }` keeps the whole thing one memoized expression that yields the `NanoWSD` (as before), with no `val server = …; …; server` shadowing, and reads as "start the server, then (side effect) open the browser at its port". `listeningPort` resolves on the `apply` receiver.
- In the normal case `listeningPort == 50395`, so the opened URL is character-for-character what it was pre-fix — the browser keeps its per-origin permissions (camera/mic are granted to `localhost:50395`). Only a fallback changes the origin, and only for that call.
- Side benefit: pre-fix the browser was launched *before* the server's `start()` returned, so the page could (briefly) hit a not-yet-listening socket and rely on its own retry; now the server is provably listening before the browser is told about it. Strictly safer ordering.
- The error handling (alert + `endCall()`) is preserved verbatim; only its position moved.
### 4.3 Spec note
`apps/multiplatform/spec/services/calls.md` (the file the code links back to) gains one sentence on the NanoWSD bullet — "If that port is already in use it falls back to an OS-assigned free port (`port 0`); `WebRTCController` reads `server.listeningPort` for the browser URL" — and the WebRTCController bullet now reads "Starts the server, then opens `http://localhost:<listeningPort>/simplex/call/` (normally `50395`)".
## 5. Why this specific shape — alternatives considered
- **Always bind `port = 0`, drop the fixed port.** Simplest possible code, no retry. Rejected: browser permissions (camera/mic, autoplay) are scoped per *origin* = `scheme://host:port`. A port that changes every call would re-prompt the user for camera/mic on every call. Keeping `50395` as the primary value preserves the granted permission; `0` is the *fallback*, used only on conflict.
- **Scan a fixed range (`50395, 50396, … 50404`).** More "predictable-ish" than an ephemeral port, but it can still be exhausted, needs a loop with an off-by-one boundary, and re-introduces the very problem (a finite set of fixed ports) in miniature. `port = 0` delegates the search to the kernel — one call, can't be exhausted while any port is free. Standard idiom; NanoHTTPD supports it directly.
- **Catch `IOException` instead of `BindException`.** Broader than the bug. A non-bind `start()` failure isn't fixed by retrying on another port; let it propagate. A narrow catch makes the diff describe exactly the failure it handles.
- **Extract the `NanoWSD` object into a local `fun newServer(port)` and `try { newServer(SERVER_PORT)… } catch { newServer(0)… }`.** Functionally equivalent, but it re-indents the ~25-line object body for no behavioural reason — a noisier diff. The default-parameter + tail-recursion form leaves the object body byte-identical and adds only the retry wrapper.
- **Move the browser-open into a `LaunchedEffect`.** Cleaner separation of "construct" vs "side effect", but it defers the launch past first composition (a behaviour change beyond the bug) and adds an effect to reason about. The pre-fix code already opened the browser inside `remember {}`; `.apply { }` keeps that timing while removing the only real wart (the open ran *before* the server existed).
- **Update every doc that mentions `localhost:50395`** (`product/flows/calling.md`, `product/glossary.md`, `product/rules.md`, `product/views/call.md`). Out of scope here: `50395` is still the primary port and those are higher-level narrative docs; only `spec/services/calls.md` (which the code references and which describes the exact mechanism) is updated. A follow-up can sweep the rest if desired.
## 6. Verification
- `./gradlew :common:compileKotlinDesktop` → `BUILD SUCCESSFUL` (only pre-existing deprecation warnings; nothing in the changed file).
- A full Linux x86_64 AppImage was built from this branch and launched (Compose software renderer in the test VM); the desktop app starts normally.
- Manual, normal path: starting a call opens the system browser at `http://localhost:50395/simplex/call/` exactly as before; the WebSocket connects and the call proceeds.
- Manual, fallback path: occupy the port first (e.g. `python3 -m http.server 50395`, or `nc -l 50395`) and then start a call → the log shows `Call server port 50395 is busy, using a random port: …`, the browser is opened at the OS-assigned port, the page's `ws://${location.host}` WebSocket connects to that same port, and the call proceeds.
## 7. Risk and rollback
- **Blast radius**: `startServer` and the `remember {}` initialiser in `WebRTCController`, Desktop only. Android (WebView, no server) is untouched; iOS is unrelated.
- The fallback branch executes only when `50395` is genuinely occupied — rare. The common path is unchanged except for the start-then-open ordering, which is strictly safer.
- Per-origin browser permissions are preserved on the common path (port unchanged); a fallback resets them for that one call — a clear improvement over the call failing outright.
- **Rollback**: `git revert 587b79779` (and drop the commit before merge if desired). No data, schema, or protocol surface is touched.
plans/2026-05-11-link-tracking-whitelist.md
+85
View File
@@ -0,0 +1,85 @@
# "Remove link tracking" strips whitelisted query parameters (`?list=` in YouTube links, github `ref`)
Design doc for the fix in PR #6965 (`nd/fix-list-in-link` → `master`).
## Problem — what prompted this
With **"remove link tracking"** enabled (Settings → Privacy & security), sending a message
with a YouTube link that has a `list` query parameter — `https://www.youtube.com/playlist?list=PL...`
or a video-in-playlist link `https://www.youtube.com/watch?v=...&list=PL...` — sent the URL
with `?list=...` removed, so the recipient got a plain (non-playlist) link instead of the
playlist. Fixing that `?list=` stripping is the immediate purpose of this change.
iOS, Android and desktop are all affected — the URI sanitiser lives in the shared Haskell
core (`src/Simplex/Chat/Markdown.hs`).
## Cause
"Remove link tracking" on send uses *safe mode* of `sanitizeUri`:
`ComposeView.sanitizeMessage` → `parseSanitizeUri(_, safe = true)` → `chatParseUri 1` →
`sanitizeUri True`.
`sanitizeUri` has three branches that pick which query parameters to keep; two of them
already consult `qsWhitelist` (the list of parameter names known *not* to be tracking — `q`,
`search`, `list`, `page`, youtube's `v`/`t`, github's `ref`, …):
```haskell
let sanitizedQS
| safe = filter (not . isSafeBlacklisted . fst) originalQS -- ← whitelist NOT consulted
| isNamePath = case originalQS of
p@(n, _) : ps -> (if isWhitelisted n || not (isBlacklisted n) then (p :) else id) $ filter (isWhitelisted . fst) ps
[] -> []
| otherwise = filter (isWhitelisted . fst) originalQS
...
isSafeBlacklisted p = any (`B.isPrefixOf` p) qsSafeBlacklist
qsSafeBlacklist = [ "ad", "af", ..., "li", ..., "ref", ... ] -- name *prefixes*; "li" → LinkedIn (li_fat_id, lipi, licu)
```
The safe-mode branch is the odd one out: it drops a parameter whenever its name *starts
with* a known tracking prefix, and never looks at `qsWhitelist`. So `list` was dropped
because `"li"` is a tracking prefix, and github's whitelisted `ref` was dropped because
`"ref"` is itself a tracking prefix — even though both are explicitly listed as non-tracking
and are kept by every other branch.
## Fix
Make the safe-mode branch apply the same "whitelisted *or* not blacklisted" rule the other
branches already use:
```haskell
| safe = filter (\(n, _) -> isWhitelisted n || not (isSafeBlacklisted n)) originalQS
```
This *removes* a special case rather than adding one — `list` is no longer handled
differently from any other whitelisted parameter; `qsWhitelist` becomes authoritative in all
three branches. Effects relative to the previous behaviour:
- `list` is kept everywhere (the reported `?list=` bug);
- github's `ref` is kept on `github.com` in safe mode too (it was already kept in eager
mode — it's in the whitelist for exactly that reason);
- nothing else changes: of all whitelist entries, only `list` (vs the `"li"` prefix) and
`ref` (vs the `"ref"` prefix) collide with a `qsSafeBlacklist` prefix today;
- every actual tracking parameter is still stripped — `qsWhitelist` does not contain
`li_fat_id`, `lipi`, `licu`, `utm*`, etc., and `ref` on any non-github host stays stripped.
Regression tests added in `testSanitizeUri` (`tests/MarkdownTests.hs`):
```haskell
it "should keep whitelisted parameters in safe mode even if they match a blacklist prefix" $ do
"https://example.com/playlist?list=abc" `sanitized` Nothing -- "list" is whitelisted, "li" is blacklisted
"https://example.com/playlist?list=abc&si=def" `sanitized` Just "https://example.com/playlist?list=abc"
"https://github.com/owner/repo?ref=main" `sanitized` Nothing -- "ref" is whitelisted for github.com
```
Verified: full library + test rebuild, then `cabal run simplex-chat-test -- --match /sanitizeUri/`
→ 4 examples, 0 failures (the new block plus the three pre-existing `sanitizeUri` cases).
## Alternatives considered
- **Special-case `list`** (`isSafeBlacklisted p = p /= "list" && …`). Smallest possible diff,
provably zero collateral, but it hard-codes one parameter name into a predicate and leaves
the structural inconsistency (safe mode ignoring the whitelist) in place — a fix by
exception rather than by rule. (This was the first version; replaced.)
- **Narrow the `"li"` blacklist entry to `"li_"`.** Fixes `list` but stops matching `lipi`
and `licu` (real LinkedIn email-link params), i.e. changes more than `list` while still
not addressing `ref` or the underlying inconsistency.
simplex-chat.cabal
+1
View File
@@ -574,6 +574,7 @@ test-suite simplex-chat-test
API.Docs.Commands
API.Docs.Events
API.Docs.Generate
API.Docs.Generate.Python
API.Docs.Generate.TypeScript
API.Docs.Responses
API.Docs.Syntax
src/Simplex/Chat.hs
+1 -2
View File
@@ -117,8 +117,7 @@ defaultChatConfig =
deliveryWorkerDelay = 0,
deliveryBucketSize = 10000,
channelSubscriberRole = GRObserver,
relayChecksInitialDelay = 30 * 1000000, -- 30 seconds
relayChecksInterval = 30 * 60, -- 30 minutes
relayChecksInterval = 15 * 60, -- 15 minutes
relayInactiveTTL = nominalDay,
relayRequestRetryInterval = RetryInterval {initialInterval = 5_000000, increaseAfter = 0, maxInterval = 600_000000},
relayRequestExpiry = (10, nominalDay),
src/Simplex/Chat/Controller.hs
-1
View File
@@ -159,7 +159,6 @@ data ChatConfig = ChatConfig
deliveryWorkerDelay :: Int64, -- microseconds
deliveryBucketSize :: Int,
channelSubscriberRole :: GroupMemberRole, -- TODO [relays] starting role should be communicated in protocol from owner to relays
relayChecksInitialDelay :: Int64,
relayChecksInterval :: NominalDiffTime,
relayInactiveTTL :: NominalDiffTime,
relayRequestRetryInterval :: RetryInterval,
src/Simplex/Chat/Library/Commands.hs
+34 -37
View File
@@ -2138,7 +2138,8 @@ processChatCommand vr nm = \case
_ -> Nothing
void $ createLinkOwnerMember db vr user gInfo' ctId_ (MemberId ownerId) ownerKey
pure gInfo'
rs <- mapConcurrently (connectToRelay user gInfo') relays
rs <- withGroupLock "connectPreparedGroup" groupId $
mapConcurrently (connectToRelay user gInfo') relays
let relayFailed = \case (_, _, Left _) -> True; _ -> False
(failed, succeeded) = partition relayFailed rs
if null succeeded
@@ -3619,7 +3620,7 @@ processChatCommand vr nm = \case
localRelayLinks = mapMaybe memberRelayLink activeRelayMembers
newRelayLinks = filter (`notElem` localRelayLinks) currentRelayLinks
forM_ newRelayLinks $ \rlnk -> void . tryAllErrors $
connectToRelay user gInfo rlnk
connectToRelayAsync user gInfo rlnk
forM_ localRelayMembers $ \m ->
case memberRelayLink m of
-- Remove relay if its link is no longer in the current link data.
@@ -3631,7 +3632,6 @@ processChatCommand vr nm = \case
deleteMemberConnection m
deleteOrUpdateMemberRecord user gInfo m
_ -> pure ()
prepareContact :: User -> ConnReqContact -> PQSupport -> CM (ConnId, VersionChat)
prepareContact user cReq pqSup = do
-- 0) toggle disabled - PQSupportOff
@@ -3944,38 +3944,36 @@ processChatCommand vr nm = \case
mapConcurrently addRelay relays
where
addRelay :: UserChatRelay -> CM (UserChatRelay, Either ChatError GroupRelay)
addRelay relay@UserChatRelay {address} = do
r <- tryAllErrors $ do
(FixedLinkData {linkConnReq = cReq}, _cData) <- getShortLinkConnReq nm user address
lift (withAgent' $ \a -> connRequestPQSupport a PQSupportOff cReq) >>= \case
Nothing -> throwChatError CEInvalidConnReq
Just (agentV, _) -> do
let chatV = agentToChatVersion agentV
gVar <- asks random
subMode <- chatReadVar subscriptionMode
connId <- withAgent $ \a -> prepareConnectionToJoin a (aUserId user) True cReq PQSupportOff
(relayMember, conn, groupRelay) <- withFastStore $ \db -> do
relayMember <- createRelayForOwner db vr gVar user gInfo relay
groupRelay <- createGroupRelayRecord db gInfo relayMember relay
conn <- createRelayConnection db vr user (groupMemberId' relayMember) connId ConnPrepared chatV subMode
pure (relayMember, conn, groupRelay)
let GroupMember {memberRole = userRole, memberId = userMemberId} = membership
allowSimplexLinks = groupFeatureUserAllowed SGFSimplexLinks gInfo
membershipProfile = redactedMemberProfile allowSimplexLinks $ fromLocalProfile $ memberProfile membership
GroupMember {memberId = relayMemberId} = relayMember
relayInv = GroupRelayInvitation {
fromMember = MemberIdRole userMemberId userRole,
fromMemberProfile = membershipProfile,
relayMemberId,
groupLink = groupSLink
}
dm <- encodeConnInfo $ XGrpRelayInv relayInv
(sqSecured, _serviceId) <- withAgent $ \a -> joinConnection a nm (aUserId user) (aConnId conn) True cReq dm PQSupportOff subMode
let newConnStatus = if sqSecured then ConnSndReady else ConnJoined
withFastStore' $ \db -> do
void $ updateConnectionStatusFromTo db conn ConnPrepared newConnStatus
updateRelayStatusFromTo db groupRelay RSNew RSInvited
pure (relay, r)
addRelay relay@UserChatRelay {address} = fmap (relay,) . tryAllErrors $ do
(FixedLinkData {linkConnReq = cReq}, _cData) <- getShortLinkConnReq nm user address
lift (withAgent' $ \a -> connRequestPQSupport a PQSupportOff cReq) >>= \case
Nothing -> throwChatError CEInvalidConnReq
Just (agentV, _) -> do
let chatV = agentToChatVersion agentV
gVar <- asks random
subMode <- chatReadVar subscriptionMode
connId <- withAgent $ \a -> prepareConnectionToJoin a (aUserId user) True cReq PQSupportOff
(relayMember, conn, groupRelay) <- withFastStore $ \db -> do
relayMember <- createRelayForOwner db vr gVar user gInfo relay
groupRelay <- createGroupRelayRecord db gInfo relayMember relay
conn <- createRelayConnection db vr user (groupMemberId' relayMember) connId ConnPrepared chatV subMode
pure (relayMember, conn, groupRelay)
let GroupMember {memberRole = userRole, memberId = userMemberId} = membership
allowSimplexLinks = groupFeatureUserAllowed SGFSimplexLinks gInfo
membershipProfile = redactedMemberProfile allowSimplexLinks $ fromLocalProfile $ memberProfile membership
GroupMember {memberId = relayMemberId} = relayMember
relayInv = GroupRelayInvitation {
fromMember = MemberIdRole userMemberId userRole,
fromMemberProfile = membershipProfile,
relayMemberId,
groupLink = groupSLink
}
dm <- encodeConnInfo $ XGrpRelayInv relayInv
(sqSecured, _serviceId) <- withAgent $ \a -> joinConnection a nm (aUserId user) (aConnId conn) True cReq dm PQSupportOff subMode
let newConnStatus = if sqSecured then ConnSndReady else ConnJoined
withFastStore' $ \db -> do
void $ updateConnectionStatusFromTo db conn ConnPrepared newConnStatus
updateRelayStatusFromTo db groupRelay RSNew RSInvited
privateGetUser :: UserId -> CM User
privateGetUser userId =
tryAllErrors (withStore (`getUser` userId)) >>= \case
@@ -4783,9 +4781,8 @@ deleteInProgressGroup user gInfo = do
runRelayGroupLinkChecks :: User -> CM ()
runRelayGroupLinkChecks user = do
initialDelay <- asks (relayChecksInitialDelay . config)
liftIO $ threadDelay' initialDelay
interval <- asks (relayChecksInterval . config)
liftIO $ threadDelay' $ diffToMicroseconds interval
forever $ do
flip catchAllErrors eToView $ do
lift waitChatStartedAndActivated
src/Simplex/Chat/Library/Internal.hs
+12
View File
@@ -1321,6 +1321,18 @@ setGroupLinkDataAsync user gInfo gLink = do
let (userLinkData, crClientData) = groupLinkData gInfo gLink groupRelays
setAgentConnShortLinkAsync user conn userLinkData (Just crClientData)
connectToRelayAsync :: User -> GroupInfo -> ShortLinkContact -> CM ()
connectToRelayAsync user gInfo relayLink = do
vr <- chatVersionRange
gVar <- asks random
relayMember@GroupMember {activeConn} <- withFastStore $ \db -> getCreateRelayForMember db vr gVar user gInfo relayLink
case activeConn of
Just _ -> pure ()
Nothing -> do
subMode <- chatReadVar subscriptionMode
newConnIds <- getAgentConnShortLinkAsync user CFGetRelayDataJoin Nothing relayLink
withFastStore' $ \db -> createRelayMemberConnectionAsync db user gInfo relayMember relayLink newConnIds subMode
updatePublicGroupData :: User -> GroupInfo -> CM GroupInfo
updatePublicGroupData user gInfo
| useRelays' gInfo && memberRole' (membership gInfo) == GROwner = do
src/Simplex/Chat/Library/Subscriber.hs
+35 -10
View File
@@ -1008,6 +1008,7 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
XInfo p -> fmap ctx <$> xInfoMember gInfo' m'' p msg brokerTs
XGrpLinkMem p -> Nothing <$ xGrpLinkMem gInfo' m'' conn' p
XGrpLinkAcpt acceptance role memberId -> Nothing <$ xGrpLinkAcpt gInfo' m'' acceptance role memberId msg brokerTs
XGrpRelayNew rl -> fmap ctx <$> xGrpRelayNew gInfo' m'' rl
XGrpMemNew memInfo msgScope -> fmap ctx <$> xGrpMemNew gInfo' m'' memInfo msgScope msg brokerTs
XGrpMemIntro memInfo memRestrictions_ -> Nothing <$ xGrpMemIntro gInfo' m'' memInfo memRestrictions_
XGrpMemInv memId introInv -> Nothing <$ xGrpMemInv gInfo' m'' memId introInv
@@ -1303,23 +1304,38 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
CFSetShortLink ->
case (ucGroupId_, auData) of
(Just groupId, UserContactLinkData UserContactData {relays = relayLinks}) -> do
(gInfo, gLink, relays, relaysChanged) <- withStore $ \db -> do
(gInfo, gLink, relays, relaysChanged, newlyActiveLinks) <- withStore $ \db -> do
gInfo <- getGroupInfo db vr user groupId
gLink <- getGroupLink db user gInfo
relays <- liftIO $ getGroupRelays db gInfo
(relays', changed) <- liftIO $ foldrM (updateRelay db) ([], False) relays
(relays', changed, newlyActive) <- liftIO $ foldrM (updateRelay db) ([], False, []) relays
liftIO $ setGroupInProgressDone db gInfo
pure (gInfo, gLink, relays', changed)
pure (gInfo, gLink, relays', changed, newlyActive)
toView $ CEvtGroupLinkDataUpdated user gInfo gLink relays relaysChanged
let GroupSummary {publicMemberCount} = groupSummary gInfo
-- Owner is counted in publicMemberCount; > 1 means at least one subscriber.
-- TODO [relays] multi-owner: with N owners, threshold should be > N (or use a
-- dedicated subscriber count).
when (fromMaybe 0 publicMemberCount > 1) $
forM_ (L.nonEmpty newlyActiveLinks) $ \newlyActive -> do
allRelayMembers <- withFastStore' $ \db -> getGroupRelayMembers db vr user gInfo
let recipients =
filter
(\GroupMember {memberStatus, relayLink} ->
memberStatus == GSMemConnected && relayLink `notElem` map Just newlyActiveLinks)
allRelayMembers
events = XGrpRelayNew <$> newlyActive
unless (null recipients) $
void $ sendGroupMessages user gInfo Nothing False recipients events
where
updateRelay :: DB.Connection -> GroupRelay -> ([GroupRelay], Bool) -> IO ([GroupRelay], Bool)
updateRelay db relay@GroupRelay {relayLink, relayStatus} (acc, changed) =
updateRelay :: DB.Connection -> GroupRelay -> ([GroupRelay], Bool, [ShortLinkContact]) -> IO ([GroupRelay], Bool, [ShortLinkContact])
updateRelay db relay@GroupRelay {relayLink, relayStatus} (acc, changed, newlyActive) =
case relayLink of
Just rLink
| rLink `elem` relayLinks && relayStatus == RSAccepted -> do
relay' <- updateRelayStatus db relay RSActive
pure (relay' : acc, True)
| rLink `elem` relayLinks -> pure (relay : acc, changed)
pure (relay' : acc, True, rLink : newlyActive)
| rLink `elem` relayLinks -> pure (relay : acc, changed, newlyActive)
| relayStatus == RSActive -> do
-- Relay link absent from link data — deactivate.
-- RSAccepted relays are not deactivated: their own link data update
@@ -1328,8 +1344,8 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
-- TODO the SMP server, but this owner won't receive a LINK callback for it
-- TODO (LINK only fires in response to own setConnShortLink calls).
relay' <- updateRelayStatus db relay RSInactive
pure (relay' : acc, True)
_ -> pure (relay : acc, changed)
pure (relay' : acc, True, newlyActive)
_ -> pure (relay : acc, changed, newlyActive)
_ -> throwChatError $ CECommandError "LINK event expected for a group link only"
_ -> throwChatError $ CECommandError "unexpected cmdFunction"
MERR _ err -> do
@@ -2165,7 +2181,7 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
in case sndMemberId_ of
-- regular deletion
Nothing
| sameMemberId memberId mem && rcvItemDeletable ci brokerTs ->
| sameMemberId memberId mem && (publicGroupItemDeletable mem || rcvItemDeletable ci brokerTs) ->
delete cci False Nothing
| otherwise ->
messageError "x.msg.del: member attempted invalid message delete" $> Nothing
@@ -2201,6 +2217,7 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
messageError ("x.msg.del: channel message not found, " <> tshow e) $> Nothing
where
isOwner = maybe True (\m -> memberRole' m == GROwner) m_
publicGroupItemDeletable mem = useRelays' gInfo && memberRole' mem >= GRModerator
RcvMessage {msgId} = rcvMsg
findItem = do
let tryMemberLookup mId =
@@ -3246,6 +3263,13 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
let cd = CDGroupRcv g'' scopeInfo m'
createGroupFeatureChangedItems user cd CIRcvGroupFeature g g''
xGrpRelayNew :: GroupInfo -> GroupMember -> ShortLinkContact -> CM (Maybe DeliveryJobScope)
xGrpRelayNew gInfo GroupMember {memberRole} rl
| memberRole < GROwner = messageError "x.grp.relay.new with insufficient member permissions" $> Nothing
| otherwise = do
unless (isUserGrpFwdRelay gInfo) $ connectToRelayAsync user gInfo rl
pure $ Just DJSGroup {jobSpec = DJDeliveryJob {includePending = False}}
xGrpDirectInv :: GroupInfo -> GroupMember -> Connection -> ConnReqInvitation -> Maybe MsgContent -> RcvMessage -> UTCTime -> CM ()
xGrpDirectInv g@GroupInfo {groupId, groupProfile = gp} m mConn@Connection {connId = mConnId} connReq mContent_ msg brokerTs
| not (groupFeatureMemberAllowed SGFDirectMessages m g) = messageError "x.grp.direct.inv: direct messages not allowed"
@@ -3367,6 +3391,7 @@ processAgentMessageConn vr user@User {userId} corrId agentConnId agentMessage =
XMsgReact sharedMsgId memId scope_ reaction add -> withAuthor XMsgReact_ $ \author -> void $ groupMsgReaction gInfo author sharedMsgId memId scope_ reaction add rcvMsg msgTs
XFileCancel sharedMsgId -> void $ xFileCancelGroup gInfo author_ sharedMsgId
XInfo p -> withAuthor XInfo_ $ \author -> void $ xInfoMember gInfo author p rcvMsg msgTs
XGrpRelayNew rl -> withAuthor XGrpRelayNew_ $ \author -> void $ xGrpRelayNew gInfo author rl
XGrpMemNew memInfo msgScope -> withAuthor XGrpMemNew_ $ \author -> void $ xGrpMemNew gInfo author memInfo msgScope rcvMsg msgTs
XGrpMemRole memId memRole -> withAuthor XGrpMemRole_ $ \author -> void $ xGrpMemRole gInfo author memId memRole rcvMsg msgTs
XGrpMemRestrict memId memRestrictions -> withAuthor XGrpMemRestrict_ $ \author -> void $ xGrpMemRestrict gInfo author memId memRestrictions rcvMsg msgTs
src/Simplex/Chat/Markdown.hs
+1 -1
View File
@@ -360,7 +360,7 @@ parseUri s = case U.parseURI U.laxURIParserOptions s of
sanitizeUri :: Bool -> U.URI -> Maybe U.URI
sanitizeUri safe uri@U.URI {uriAuthority, uriPath, uriQuery = U.Query originalQS} =
let sanitizedQS
| safe = filter (not . isSafeBlacklisted . fst) originalQS
| safe = filter (\(n, _) -> isWhitelisted n || not (isSafeBlacklisted n)) originalQS
| isNamePath = case originalQS of
p@(n, _) : ps -> (if isWhitelisted n || not (isBlacklisted n) then (p :) else id) $ filter (isWhitelisted . fst) ps
[] -> []
src/Simplex/Chat/Protocol.hs
+9
View File
@@ -443,6 +443,7 @@ data ChatMsgEvent (e :: MsgEncoding) where
XGrpRelayInv :: GroupRelayInvitation -> ChatMsgEvent 'Json
XGrpRelayAcpt :: ShortLinkContact -> ChatMsgEvent 'Json
XGrpRelayTest :: ByteString -> Maybe ByteString -> ChatMsgEvent 'Json
XGrpRelayNew :: ShortLinkContact -> ChatMsgEvent 'Json
XGrpMemNew :: MemberInfo -> Maybe MsgScope -> ChatMsgEvent 'Json
XGrpMemIntro :: MemberInfo -> Maybe MemberRestrictions -> ChatMsgEvent 'Json
XGrpMemInv :: MemberId -> IntroInvitation -> ChatMsgEvent 'Json
@@ -492,6 +493,7 @@ isForwardedGroupMsg ev = case ev of
XMsgReact {} -> True
XFileCancel _ -> True
XInfo _ -> True
XGrpRelayNew _ -> True
XGrpMemNew {} -> True
XGrpMemRole {} -> True
XGrpMemRestrict {} -> True
@@ -986,6 +988,7 @@ data CMEventTag (e :: MsgEncoding) where
XGrpRelayInv_ :: CMEventTag 'Json
XGrpRelayAcpt_ :: CMEventTag 'Json
XGrpRelayTest_ :: CMEventTag 'Json
XGrpRelayNew_ :: CMEventTag 'Json
XGrpMemNew_ :: CMEventTag 'Json
XGrpMemIntro_ :: CMEventTag 'Json
XGrpMemInv_ :: CMEventTag 'Json
@@ -1043,6 +1046,7 @@ instance MsgEncodingI e => StrEncoding (CMEventTag e) where
XGrpRelayInv_ -> "x.grp.relay.inv"
XGrpRelayAcpt_ -> "x.grp.relay.acpt"
XGrpRelayTest_ -> "x.grp.relay.test"
XGrpRelayNew_ -> "x.grp.relay.new"
XGrpMemNew_ -> "x.grp.mem.new"
XGrpMemIntro_ -> "x.grp.mem.intro"
XGrpMemInv_ -> "x.grp.mem.inv"
@@ -1101,6 +1105,7 @@ instance StrEncoding ACMEventTag where
"x.grp.relay.inv" -> XGrpRelayInv_
"x.grp.relay.acpt" -> XGrpRelayAcpt_
"x.grp.relay.test" -> XGrpRelayTest_
"x.grp.relay.new" -> XGrpRelayNew_
"x.grp.mem.new" -> XGrpMemNew_
"x.grp.mem.intro" -> XGrpMemIntro_
"x.grp.mem.inv" -> XGrpMemInv_
@@ -1155,6 +1160,7 @@ toCMEventTag msg = case msg of
XGrpRelayInv _ -> XGrpRelayInv_
XGrpRelayAcpt _ -> XGrpRelayAcpt_
XGrpRelayTest {} -> XGrpRelayTest_
XGrpRelayNew _ -> XGrpRelayNew_
XGrpMemNew {} -> XGrpMemNew_
XGrpMemIntro _ _ -> XGrpMemIntro_
XGrpMemInv _ _ -> XGrpMemInv_
@@ -1227,6 +1233,7 @@ requiresSignature = \case
XGrpMemRole_ -> True
XGrpMemRestrict_ -> True
XGrpLeave_ -> True
XGrpRelayNew_ -> True
XInfo_ -> True
_ -> False
@@ -1311,6 +1318,7 @@ appJsonToCM AppMessageJson {v, msgId, event, params} = do
B64UrlByteString challenge <- p "challenge"
sig_ <- fmap (\(B64UrlByteString s) -> s) <$> opt "signature"
pure $ XGrpRelayTest challenge sig_
XGrpRelayNew_ -> XGrpRelayNew <$> p "relayLink"
XGrpMemNew_ -> XGrpMemNew <$> p "memberInfo" <*> opt "scope"
XGrpMemIntro_ -> XGrpMemIntro <$> p "memberInfo" <*> opt "memberRestrictions"
XGrpMemInv_ -> XGrpMemInv <$> p "memberId" <*> p "memberIntro"
@@ -1380,6 +1388,7 @@ chatToAppMessage chatMsg@ChatMessage {chatVRange, msgId, chatMsgEvent} = case en
XGrpRelayTest challenge sig_ -> o $
("signature" .=? (B64UrlByteString <$> sig_))
["challenge" .= B64UrlByteString challenge]
XGrpRelayNew relayLink -> o ["relayLink" .= relayLink]
XGrpMemNew memInfo scope -> o $ ("scope" .=? scope) ["memberInfo" .= memInfo]
XGrpMemIntro memInfo memRestrictions -> o $ ("memberRestrictions" .=? memRestrictions) ["memberInfo" .= memInfo]
XGrpMemInv memId memIntro -> o ["memberId" .= memId, "memberIntro" .= memIntro]
src/Simplex/Chat/Store/Groups.hs
+12 -7
View File
@@ -1381,7 +1381,12 @@ getCreateRelayForMember db vr gVar user@User {userId, userContactId} GroupInfo {
maybeFirstRow (toContactMember vr user) $
DB.query
db
(groupMemberQuery <> " WHERE m.group_id = ? AND m.relay_link = ?")
#if defined(dbPostgres)
(groupMemberQuery <> " WHERE m.group_id = ? AND m.relay_link = ? AND is_current_member(m.member_status)")
#else
-- skips GSMemLeft historical rows so re-add allocates a fresh row instead of resurrecting
(groupMemberQuery <> " JOIN group_member_status_predicates sp ON m.member_status = sp.member_status WHERE m.group_id = ? AND m.relay_link = ? AND sp.current_member = 1")
#endif
(groupId, relayLink)
createRelayMember = do
currentTs <- liftIO getCurrentTime
@@ -1839,12 +1844,12 @@ updatePublicMemberCount db vr user GroupInfo {groupId} = do
relayCount <- fromMaybe 0 <$> maybeFirstRow fromOnly
(DB.query
db
[sql|
SELECT COUNT(1) FROM group_members
WHERE group_id = ? AND member_role = ?
AND member_status IN (?,?,?,?,?,?,?)
|]
(groupId, GRRelay, GSMemIntroduced, GSMemIntroInvited, GSMemAccepted, GSMemAnnounced, GSMemConnected, GSMemComplete, GSMemCreator))
#if defined(dbPostgres)
"SELECT COUNT(1) FROM group_members WHERE group_id = ? AND member_role = ? AND is_current_member(member_status)"
#else
"SELECT COUNT(1) FROM group_members m JOIN group_member_status_predicates sp ON m.member_status = sp.member_status WHERE m.group_id = ? AND m.member_role = ? AND sp.current_member = 1"
#endif
(groupId, GRRelay))
let publicCount = max 0 (totalCount - relayCount) :: Int64
currentTs <- getCurrentTime
DB.execute db "UPDATE groups SET public_member_count = ?, updated_at = ? WHERE group_id = ?" (publicCount, currentTs, groupId)
src/Simplex/Chat/Store/SQLite/Migrations/agent_query_plans.txt
+4 -37
View File
@@ -273,16 +273,6 @@ Query:
Plan:
SEARCH connections USING PRIMARY KEY (conn_id=?)
Query:
SELECT user_id FROM users u
WHERE u.deleted = ?
AND NOT EXISTS (SELECT c.conn_id FROM connections c WHERE c.user_id = u.user_id)
Plan:
SCAN u
CORRELATED SCALAR SUBQUERY 1
SEARCH c USING COVERING INDEX idx_connections_user (user_id=?)
Query:
SELECT user_id FROM users u
WHERE u.user_id = ?
@@ -535,21 +525,6 @@ Query:
Plan:
SEARCH conn_confirmations USING COVERING INDEX idx_conn_confirmations_conn_id (conn_id=?)
Query:
DELETE FROM encrypted_rcv_message_hashes
WHERE encrypted_rcv_message_hash_id IN (
SELECT encrypted_rcv_message_hash_id
FROM encrypted_rcv_message_hashes
WHERE created_at < ?
ORDER BY created_at ASC
LIMIT ?
)
Plan:
SEARCH encrypted_rcv_message_hashes USING INTEGER PRIMARY KEY (rowid=?)
LIST SUBQUERY 1
SEARCH encrypted_rcv_message_hashes USING COVERING INDEX idx_encrypted_rcv_message_hashes_created_at (created_at<?)
Query:
INSERT INTO connections
(user_id, conn_id, conn_mode, smp_agent_version, enable_ntfs, pq_support, duplex_handshake) VALUES (?,?,?,?,?,?,?)
@@ -1110,14 +1085,6 @@ Query: SELECT conn_id FROM connections WHERE deleted = 0
Plan:
SCAN connections
Query: SELECT conn_id FROM connections WHERE deleted = ?
Plan:
SCAN connections
Query: SELECT conn_id FROM connections WHERE deleted_at_wait_delivery IS NOT NULL
Plan:
SCAN connections
Query: SELECT conn_id FROM connections WHERE user_id = ?
Plan:
SEARCH connections USING COVERING INDEX idx_connections_user (user_id=?)
@@ -1230,6 +1197,10 @@ Query: UPDATE connections SET smp_agent_version = ? WHERE conn_id = ?
Plan:
SEARCH connections USING PRIMARY KEY (conn_id=?)
Query: UPDATE deleted_snd_chunk_replicas SET delay = ?, retries = retries + 1, updated_at = ? WHERE deleted_snd_chunk_replica_id = ?
Plan:
SEARCH deleted_snd_chunk_replicas USING INTEGER PRIMARY KEY (rowid=?)
Query: UPDATE messages SET msg_body = x'' WHERE conn_id = ? AND internal_id = ?
Plan:
SEARCH messages USING PRIMARY KEY (conn_id=? AND internal_id=?)
@@ -1238,10 +1209,6 @@ Query: UPDATE ratchets SET ratchet_state = ? WHERE conn_id = ?
Plan:
SEARCH ratchets USING PRIMARY KEY (conn_id=?)
Query: UPDATE rcv_file_chunk_replicas SET delay = ?, retries = retries + 1, updated_at = ? WHERE rcv_file_chunk_replica_id = ?
Plan:
SEARCH rcv_file_chunk_replicas USING INTEGER PRIMARY KEY (rowid=?)
Query: UPDATE rcv_file_chunk_replicas SET received = 1, updated_at = ? WHERE rcv_file_chunk_replica_id = ?
Plan:
SEARCH rcv_file_chunk_replicas USING INTEGER PRIMARY KEY (rowid=?)
src/Simplex/Chat/Store/SQLite/Migrations/chat_query_plans.txt
+1 -1
View File
@@ -7152,7 +7152,7 @@ Query: UPDATE groups SET public_member_count = ?, updated_at = ? WHERE group_id
Plan:
SEARCH groups USING INTEGER PRIMARY KEY (rowid=?)
Query: UPDATE groups SET relay_own_status = ?, updated_at = ? WHERE group_id = ?
Query: UPDATE groups SET relay_own_status = ?, relay_inactive_at = ?, updated_at = ? WHERE group_id = ?
Plan:
SEARCH groups USING INTEGER PRIMARY KEY (rowid=?)
tests/APIDocs.hs
+6
View File
@@ -8,6 +8,7 @@ module APIDocs where
import API.Docs.Commands
import API.Docs.Events
import API.Docs.Generate
import qualified API.Docs.Generate.Python as Py
import qualified API.Docs.Generate.TypeScript as TS
import API.Docs.Responses
import API.Docs.Types
@@ -42,6 +43,11 @@ apiDocsTest = do
it "generate typescript responses code" $ testGenerate TS.responsesCodeFile TS.responsesCodeText
it "generate typescript events code" $ testGenerate TS.eventsCodeFile TS.eventsCodeText
it "generate typescript types code" $ testGenerate TS.typesCodeFile TS.typesCodeText
describe "Python" $ do
it "generate python commands code" $ testGenerate Py.commandsCodeFile Py.commandsCodeText
it "generate python responses code" $ testGenerate Py.responsesCodeFile Py.responsesCodeText
it "generate python events code" $ testGenerate Py.eventsCodeFile Py.eventsCodeText
it "generate python types code" $ testGenerate Py.typesCodeFile Py.typesCodeText
documentedCmds :: [String]
documentedCmds = concatMap (map consName' . commands) chatCommandsDocs
tests/ChatTests/Groups.hs
-3
View File
@@ -9734,9 +9734,6 @@ testChannelAddRelay ps =
threadDelay 100000
-- existing subscriber discovers and connects to new relay
dan ##> "/_get group link data #1"
dan <## "group ID: 1"
void $ getTermLine dan -- subscribers: N
concurrentlyN_
[ do
dan <## "#team: joining the group (connecting to relay cath)..."
tests/MarkdownTests.hs
+4
View File
@@ -416,6 +416,10 @@ testSanitizeUri = describe "sanitizeUri" $ do
"https://example.com/page/a123?source=abc" `safeSanitized` Nothing -- source is in unsafe blacklist
"https://example.com/page/a123?name=abc" `eagerSanitized` Just "https://example.com/page/a123"
"https://example.com/page/a123?name=abc" `safeSanitized` Nothing -- name is not in a whitelist
it "should keep whitelisted parameters in safe mode even if they match a blacklist prefix" $ do
"https://example.com/playlist?list=abc" `sanitized` Nothing -- "list" is whitelisted, "li" is blacklisted
"https://example.com/playlist?list=abc&si=def" `sanitized` Just "https://example.com/playlist?list=abc"
"https://github.com/owner/repo?ref=main" `sanitized` Nothing -- "ref" is whitelisted for github.com
where
s `eagerSanitized` res = sanitized_ False s res
s `safeSanitized` res = sanitized_ True s res