mirror of
https://github.com/permissionlesstech/bitchat.git
synced 2026-07-25 02:25:20 +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