mirror of https://github.com/permissionlesstech/bitchat.git synced 2026-07-25 02:05:19 +00:00

Files

T

jack b880c663c2 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

2025-07-06 22:57:03 +02:00

2.6 KiB

Raw Blame History

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

Alice sends message to Bob
Message shows gray circle (○) - "sending"
Message is transmitted and shows gray checkmark (✓) - "sent"
Bob receives and sends ACK
Alice sees green double checkmarks (✓✓) - "delivered"

Reading Messages

When Bob opens/views the chat with Alice
System checks all messages from Alice with "delivered" status
Sends read receipts for those messages
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

Send a message between two devices
Watch status progression on sender's device
Open chat on receiver's device
Sender should see blue checkmarks
Works even if receiver was offline when message was sent

2.6 KiB Raw Blame History