Real-Time Updates

Cloud Share uses Server-Sent Events (SSE) to push queue changes from the sender to the receiver instantly — no polling, no page refresh.

How SSE works in cloud-share

When the receiver UI loads, it opens a persistent HTTP connection to the sender’s event stream endpoint:

  GET /events?secret=<your-secret>

The sender keeps this connection open and pushes newline-delimited JSON events whenever the queue changes. The browser’s native EventSource API (used by Alpine.js) handles reconnection automatically.

SSE event types

The sender emits three types of events:

new_item

Fired when a new item is added to the queue (text shared, file uploaded, zip bundled).

  {
  "type": "new_item",
  "item": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "file",
    "name": "report.pdf",
    "sizeBytes": 204800,
    "status": "Queued",
    "hasZipPassword": false
  }
}

The receiver adds the item to its queue list immediately — without a page refresh.

item_received

Fired when an item has been downloaded by the receiver.

  {
  "type": "item_received",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The receiver updates the item’s status badge to Received in real time. If multiple receiver tabs are open, all of them update simultaneously.

item_deleted

Fired when an item is deleted from the sender queue (either manually by the sender operator, or automatically after a hash mismatch).

  {
  "type": "item_deleted",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The item disappears from the receiver queue immediately.

Real-time queue flow 

sequenceDiagram
    participant S as Sender UI
    participant SQ as Sender Queue
    participant SSE as SSE Stream
    participant R as Receiver UI

    S->>SQ: Encrypt + queue item
    SQ-->>S: Sender queue table updates (local)
    SQ->>SSE: Emit new_item event
    SSE-->>R: { "type": "new_item", "item": {...} }
    R->>R: Receiver queue list updates instantly

📸 Screenshot needed: real-time-sender-share.png Description: Side-by-side of sender and receiver, showing a new item appearing in both queues simultaneously

Auto-reconnect

The SSE connection may drop due to:

  • Network interruptions
  • Dev Tunnel reconnecting
  • The sender being temporarily unreachable

Cloud Share handles this automatically with a 3-second backoff reconnect:

flowchart TD
    A[SSE connection lost] --> B[Wait 3 seconds]
    B --> C["Attempt reconnect\nGET /events?secret=X"]
    C --> D{Connected?}
    D -- Yes --> E[Status badge turns green]
    E --> F["Refresh queue\nGET /queue?secret=X"]
    D -- No --> B

During reconnection, the receiver UI shows a yellow “Reconnecting…” status badge. The queue is refreshed from GET /queue?secret=X after a successful reconnect to catch any items that were queued while disconnected.

📸 Screenshot needed: real-time-reconnecting-badge.png Description: Receiver UI header showing the yellow “Reconnecting…” connection status badge

Connection status badge

The receiver header always shows the current SSE connection state:

StateBadge colorDescription
Connected🟢 GreenEvent stream active, updates arriving in real time
Reconnecting🟡 YellowConnection lost, retry in progress
Disconnected🔴 RedUnable to reach sender (check URL, tunnel status)

📸 Screenshot needed: real-time-connected-badge.png Description: Receiver UI header with green “Connected” badge

Multiple receivers

Multiple browser windows or machines can connect as receivers simultaneously. Each connected client:

  • Maintains its own SSE connection
  • Receives all queue events independently
  • Can receive any item in the queue

ℹ️ Info: If two receivers both click “Receive” on the same item at the same time, only one will succeed — the item is marked as received and the second download attempt will find the item already marked. The queue shows the received status to all connected clients immediately.

Sender-side SSE endpoint

For reference, the SSE endpoint:

  GET /events?secret=<your-secret>
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Events are sent as:

  data: {"type":"new_item","item":{...}}\n\n
data: {"type":"item_received","id":"..."}\n\n
data: {"type":"item_deleted","id":"..."}\n\n

The standard SSE format (each event is data: <json>\n\n) is used, making it compatible with any EventSource-capable client.