mirror of
https://github.com/permissionlesstech/bitchat.git
synced 2026-07-24 23:45:18 +00:00
Add comprehensive documentation for delivery confirmation feature
- Complete implementation guide - Test checklist with expected logs - Explanation of how ephemeral peer IDs are handled - Visual indicator reference
This commit is contained in:
jack
@@ -0,0 +1,66 @@
|
||||
# Delivery Confirmation - Complete Implementation
|
||||
|
||||
## The Journey
|
||||
We implemented a full delivery confirmation system with read receipts. The feature went through several iterations to handle edge cases and the ephemeral nature of peer IDs.
|
||||
|
||||
## Key Challenges Solved
|
||||
|
||||
### 1. Deadlock Issues
|
||||
- **Problem**: Nested lock acquisition causing macOS app to freeze
|
||||
- **Solution**: Restructured DeliveryTracker to release locks before calling methods that acquire the same lock
|
||||
|
||||
### 2. Message ID Preservation
|
||||
- **Problem**: ACKs referenced wrong message IDs
|
||||
- **Solution**: Fixed BinaryProtocol to properly preserve message IDs during decoding
|
||||
|
||||
### 3. Race Condition with Status Updates
|
||||
- **Problem**: Read receipts would briefly show blue checkmarks, then revert to green when ACK arrived
|
||||
- **Solution**: Added logic to prevent downgrading from 'read' to 'delivered' status
|
||||
|
||||
### 4. Ephemeral Peer IDs
|
||||
- **Problem**: Peer IDs change between sessions, breaking read receipts for existing messages
|
||||
- **Solution**:
|
||||
- Match messages by sender nickname in addition to peer ID
|
||||
- Send read receipts to the CURRENT peer ID, not the old one from the message
|
||||
- Removed requirement for senderPeerID to exist
|
||||
|
||||
## How It Works Now
|
||||
|
||||
### Sending a Message
|
||||
1. Alice sends message to Bob
|
||||
2. Message shows gray circle (○) - "sending"
|
||||
3. Message is transmitted and shows gray checkmark (✓) - "sent"
|
||||
4. Bob receives and sends ACK
|
||||
5. Alice sees green double checkmarks (✓✓) - "delivered"
|
||||
|
||||
### Reading Messages
|
||||
1. When Bob opens/views the chat with Alice
|
||||
2. System checks all messages from Alice with "delivered" status
|
||||
3. Sends read receipts for those messages
|
||||
4. Alice sees blue double checkmarks (✓✓) - "read"
|
||||
|
||||
### Key Code Components
|
||||
- `DeliveryTracker.swift` - Manages delivery confirmations and timeouts
|
||||
- `BitchatProtocol.swift` - Defines delivery status enum and ACK/receipt structures
|
||||
- `BluetoothMeshService.swift` - Handles sending/receiving ACKs and receipts
|
||||
- `ChatViewModel.swift` - Updates UI and manages read receipt logic
|
||||
- `ContentView.swift` - Displays delivery status indicators
|
||||
|
||||
## Visual Indicators
|
||||
- ○ Gray circle = Sending
|
||||
- ✓ Gray single check = Sent
|
||||
- ✓✓ Green double checks = Delivered
|
||||
- ✓✓ Blue double checks (bold) = Read
|
||||
- ⚠ Red triangle = Failed
|
||||
|
||||
## Privacy Features
|
||||
- All ACKs and read receipts are end-to-end encrypted
|
||||
- Only the original sender can decrypt delivery confirmations
|
||||
- No message content is included in confirmations
|
||||
|
||||
## Testing the Feature
|
||||
1. Send a message between two devices
|
||||
2. Watch status progression on sender's device
|
||||
3. Open chat on receiver's device
|
||||
4. Sender should see blue checkmarks
|
||||
5. Works even if receiver was offline when message was sent
|
||||
@@ -1,37 +0,0 @@
|
||||
# Delivery Confirmation Feature - Current Status
|
||||
|
||||
## What's Working
|
||||
1. ✅ Delivery confirmations (green double checkmarks) work correctly
|
||||
2. ✅ Read receipts are sent and received properly
|
||||
3. ✅ Blue checkmarks appear for messages that are read while both users are in the chat
|
||||
4. ✅ Status updates are preserved (read status won't downgrade to delivered)
|
||||
|
||||
## Remaining Issue
|
||||
When Jack opens a chat with Rick, the first message (that was already delivered before Jack opened the chat) doesn't get a read receipt sent. Only new messages that arrive while the chat is open get read receipts.
|
||||
|
||||
### Root Cause
|
||||
The `markPrivateMessagesAsRead` function is being called when Jack opens the chat, but:
|
||||
1. It looks for messages with status "sent" or "delivered"
|
||||
2. Messages from Rick are stored with Rick's senderPeerID (which changes between sessions)
|
||||
3. The peer ID mismatch might prevent finding the right messages
|
||||
|
||||
### Solution Needed
|
||||
Jack needs to send read receipts for ALL unread messages from Rick when opening the chat, regardless of their current peer ID.
|
||||
|
||||
## Test Scenario
|
||||
1. Rick sends message to Jack while Jack is offline/not in chat
|
||||
2. Message shows green checkmarks (delivered) on Rick's side
|
||||
3. Jack opens the chat with Rick
|
||||
4. **Expected**: Rick's message should turn blue
|
||||
5. **Actual**: Message stays green until a new message is sent
|
||||
|
||||
## Logs Showing the Issue
|
||||
```
|
||||
Mac (Rick):
|
||||
- Message F4D69DB6... shows "delivered to jack" (stays green)
|
||||
- Never receives read receipt for this first message
|
||||
|
||||
Phone (Jack):
|
||||
- Opens chat but doesn't send read receipt for existing messages
|
||||
- Only sends read receipts for new messages received while chat is open
|
||||
```
|
||||
@@ -0,0 +1,37 @@
|
||||
# Test Checklist for Delivery Confirmation
|
||||
|
||||
## Quick Test
|
||||
1. **Rick sends to Jack** (while Jack is not in the chat)
|
||||
- ✓ Rick sees gray circle → gray check → green double checks
|
||||
|
||||
2. **Jack opens chat with Rick**
|
||||
- ✓ Jack should see Rick's message
|
||||
- ✓ Rick should see blue double checks (this is what we fixed!)
|
||||
|
||||
3. **Jack sends reply to Rick** (while Rick is viewing)
|
||||
- ✓ Jack sees gray circle → gray check → green double checks → blue double checks
|
||||
|
||||
## Debug Logs to Watch For
|
||||
|
||||
**On Jack's device when opening chat:**
|
||||
```
|
||||
[UI] Selected private chat peer changed to [peer-id]
|
||||
[UI] Triggering markPrivateMessagesAsRead for peer [peer-id]
|
||||
[Delivery] Checking N messages in chat with peer [peer-id] (rick) for read receipts
|
||||
[Delivery] Message [id] from rick, senderPeerID: [old-id], currentPeerID: [new-id], myNickname: jack, status: Delivered to jack
|
||||
[Delivery] Sending read receipt for message [id] from rick to current peer [peer-id]
|
||||
[DeliveryTracker] Broadcasting read receipt packet to [peer-id]
|
||||
```
|
||||
|
||||
**On Rick's device when receiving read receipt:**
|
||||
```
|
||||
[Delivery] Received READ receipt for message [id] from jack
|
||||
[Delivery] Updating message [id] to status: read(by: "jack", at: [timestamp])
|
||||
[UI] Showing BLUE checkmarks for read status by jack
|
||||
```
|
||||
|
||||
## What to Check
|
||||
- Messages sent before opening chat should turn blue when chat is opened
|
||||
- Peer ID changes between sessions shouldn't break read receipts
|
||||
- No race conditions - blue checkmarks should stay blue
|
||||
- Read receipts work for both real-time and delayed chat opening
|
||||
Reference in New Issue
Block a user