---
# System prepended metadata

title: Local Mailbox Mode
tags: [architecture]

---

# Local Mailbox Mode

## User Requirements

> Local Mailboxes = desktop Dash Chat app instances with the Local Mailbox Mode enabled that are connected to the same WiFi LAN network

- Users MUST be able to enable a "Local Mailbox Mode" from the Dash Chat app.
- Local Mailboxes MUST be discovered automatically by instances of the Dash Chat mobile app that run in the same LAN, provided they fulfill the requirements described in [WiFi LAN Mesh Networks](https://hackmd.io/E2a4QChlRfWV_CXctjHdxg).
- The Dash Chat app SHOULD automatically use Local Mailboxes discovered in the LAN to store outgoing messages.
- Local Mailboxes MUST be able to store messages sent using the Dash Chat mobile app.
- Local Mailboxes MUST be able to deliver previously stored messages to recipients using the Dash Chat mobile app.
- Local Mailboxes SHOULD relay messages to offline recipients in as many situations as possible given storage, bandwidth and performance constraints.
- Local Mailboxes MUST be able to run in the background, even when its windows are closed.
- Local Mailboxes SHOULD prevent the computer from idling when running.

## Design

The Dash Chat Mailbox Mode will be a mode with the following features:

- Minimal configuration UI.
- Background running service using the [System Tray](https://v2.tauri.app/learn/system-tray/) feature from Tauri.
- The plugin [tauri-plugin-keepawake](https://github.com/thewh1teagle/tauri-plugin-keepawake) will prevent the system from idling or going to sleep while the service is running.
- It will use the [updater plugin](https://v2.tauri.app/plugin/updater/#setup) to automatically update when a new version is available.
- The app will expose an HTTP endpoint with no authentication needed.
    - The HTTP API will be exactly the same as the one in [Toy Mailbox design](https://hackmd.io/RKZc5e3ySJCcmMXV_Sjy1A#Functions).
- The app will announce its internal IP address as a mDNS service in the LAN, using [mdns_sd](https://docs.rs/mdns-sd/latest/mdns_sd/).
- All messages are going to be dropped within a week of being stored.

### Database

Mailbox servers will use Cassandra to store messages. Unfortunately, Cassandra does not support Windows or MacOs, so as per the user requirements we can't just use Cassandra in the local mailboxes as well.

Instead, we have two options:

A) Choose a different database that fulfills both the server and local mailboxes requirements. 
B) Use a different database in local mailboxes, define a common trait that any database that stores messages needs to implement, and implement it for both Cassandra and the local mailboxes database.

I think B) is our best option because:
- We don't lose scalability and performance in the mailbox server, which is one of the main reasons why we need mailboxes in the first place.
- The Mailbox API is simple, it will be easy to build the implementations for each of the databases.
- There are no good options that I have found for databases that fulfill the requirements of both local and server mailboxes:
    - Scalability
    - Cross-platform support
    - Easy to embed in a Tauri app
- There are good options for embeddable databases written in Rust.

Embeddable options:

| Database | Best For | Write Speed | Read Speed | Size | Complexity |
|----------|----------|-------------|------------|------|------------|
| **Redb** | General purpose | Good | Excellent | Small | Low |
| **Fjall** | Write-heavy | Excellent | Good | Medium | Medium |
| **PoloDB** | Document queries | Good | Good | Medium | Low |
| Sled | ❌ Deprecated | Fair | Good | Small | Low |

I think redb is our best option.

## Tasks

### Local Mailbox Mode

- Minimal configuration UI.
- System tray configuration.
- Updater plugin configuration.
- Keepawake plugin configuration.
- Setup redb instance.
- Implementation of Mailbox HTTP API for redb.
- Spawn Mailbox HTTP server.
- Create persistent ID from UUID.
- Announce Mailbox server LAN IP address and persistent ID as `instance_name` using mDNS.
- Garbage collection of messages that are a week old or more.

### Dash Chat Integration

- Discover local mailboxes using mDNS and keep track of them in memory.
    - Using tauri state in backend memory.
    - We drop active mailbox from this list if we don't receive their announcing mDNS message after 1 minute.
- On new messages, send messages to all currently discovered mailboxes. 
- Persistent store to track sequence number sent to each mailbox.
- On new mailbox discovered,  send unsent messages regardless of delivery status, without checking if the message is already present on the server.
- Implement poll policies:
  - Call `get_messages_for_topics` whenever a new local mailbox is discovered.
  - Call `get_messages_for_topics` to all locally discovered mailboxes when joining a new topic in serial.
  - Poll `get_messages_for_topics` every N seconds (~10 without push notifications, higher with push), choose the next mailbox on the list
      - If a request fails, we immediately jump to the next mailbox.
      - If they all fail, we stop the process and wait for the next instance of the polling process
  - When we have it, call `get_messages_for_topics` to all locally discovered mailboxes from `receive_push_notification()` 



## Scope of Work

See the breakdown of times in this section of the spreadsheet:

https://docs.google.com/spreadsheets/d/1TCv7DDNAWYkOwF3bC9jAP4X3VlcAbkFTyosCIvjPfqY/edit?gid=0#gid=0&range=A116

Total amount of days needed: 27


## Design discussion on scalable and reliable Local Mailboxes TTN (Post TT1, N > 1) 

Decisions:

- Peers track the LOG_ID+sequence numbers that they have sent to each mailbox server.
- Nodes track the highest sequence number sent, per mailbox, and send unsent messages regardless of delivery status, without checking if the message is already present on the server (duplicate traffic ok for now)
- Mailboxes store the messages with sequence numbers


### using mailboxes

- LAN operators designate a single trusted mailbox to be announced in the LAN
- LAN operators designate trusted mailboxes to be announced in the LAN
	- do they sync with each other?
- anyone can run a mailbox, and the mailboxes all sync with each other
	- users can use any mailbox and don't need consensus on which mailbox to use because they're all the same
- anyone can run a mailbox, and users sync all of their messages with all mailboxes (the users keep the mailboxes in sync)
    - **This is the more appealing option**
    - Enables storing of messages when switching LANs
    - Every time the user discovers a new mailbox, it synchronizes the messages that have some recipient pending
    - Mailbox synchronizing with each other in the background is compatible with this option
        - First the user stores messages to all available mailboxes
        - Then can run a background process to achieve eventual consistency
        - This allows for mailboxes that were offline when the user stored the messages to eventually store the message
        - Stable identifier of the mailbox server is an encryption key so that MITM attacks are prevented
- anyone can run a mailbox, and users pick a mailbox and stick with it for the duration of their group
    - UX friction: requires each user to approve
    	- not necessarily, the mailbox address can be included in group invitations. but this is still horrible. 
	- catastrophic if the mailbox goes down


### using peer relays

- ~~we just rely on peer relays for robust LAN delivery~~
    - delivery is highly dependent on network characteristics and the availability of users so we can't make strong reliability claims
- nodes can declare themselves as "more reliable relays" and willing to handle more traffic, which peers will prioritize using, to cut down the inefficiency of a fully non-hierarchical mesh
	- a compromise between "just works" and the speed boost provided by centralization


## Strong local mailbox servers

### Requirements 

- All requirements from the first iteration on local mailboxes.
- Local mailboxes MUST synchronize with internet mailboxes when reconnected to the internet after a period of disconnection.
- Local mailboxes MUST be able to synchronize with each other when connected to the same LAN.
- Local mailboxes SHOULD continue working in as many situations as possible even when attacked by a DoS or spam attack.
- Local mailboxes MUST offer a configurable authentication method that is required so the users can use it.

### Tasks

- Password-based authentication in the desktop app.
- Authenticate to local mailboxes from the mobile app.
- Password-based authentication to synchronize with other mailboxes.
- Research and design synchronization engine with other local mailboxes.
- Implement synchronization engine with other local mailboxes.
- Design garbage collection policy
- Implement garbage collection policy
- Detection of internet message servers availability.
- Synchronization with internet based mailboxes on internet reconnection. 
- Settings UI:
    - Authentication
    - Statistics
        - Storage used
        - Messages stored currently
        - Total messages relayed
    - Storage allocated

Please review the tasks estimations here: https://docs.google.com/spreadsheets/d/1TCv7DDNAWYkOwF3bC9jAP4X3VlcAbkFTyosCIvjPfqY/edit?gid=0#gid=0&range=A135