148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
---
|
|
feature: SSE Migration
|
|
status: delivered
|
|
specs: []
|
|
plans:
|
|
- docs/compose/plans/2026-06-11-sse-migration.md
|
|
branch: main
|
|
commits: 869f4cb..16d55a1
|
|
---
|
|
|
|
# SSE Migration — Final Report
|
|
|
|
## What Was Built
|
|
|
|
Noise now uses Server-Sent Events (SSE) to receive messages from signal-cli in real-time, replacing the previous polling-based approach. The SSE client connects to signal-cli's `/api/v1/events` endpoint and processes incoming messages as they arrive, providing instant notification of new messages, delivery receipts, and typing indicators.
|
|
|
|
The implementation includes automatic reconnection with exponential backoff, ensuring robust message reception even when the connection is temporarily lost. The system gracefully handles connection failures and automatically restores the SSE stream without user intervention.
|
|
|
|
## Architecture
|
|
|
|
### Components
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `noise-sse.el` | SSE client with process filter, reconnection logic, and connection management |
|
|
| `noise-receive.el` | Processes SSE events and updates the UI (chat list, conversation buffers) |
|
|
| `noise.el` | Entry point with `noise-mode` that starts/stops SSE |
|
|
|
|
### Data Flow
|
|
|
|
```
|
|
signal-cli daemon
|
|
↓ GET /api/v1/events
|
|
noise-sse client (process filter)
|
|
↓ parse SSE events
|
|
noise-receive--handle-sse-event
|
|
↓ process envelope
|
|
UI refresh (chat list, conversation buffers)
|
|
```
|
|
|
|
### Key Functions
|
|
|
|
- `noise-sse-connect` — Establishes SSE connection to signal-cli
|
|
- `noise-sse-disconnect` — Cleans up connection and timers
|
|
- `noise-receive--handle-sse-event` — Processes incoming SSE events
|
|
- `noise-receive-start-sse` / `noise-receive-stop-sse` — Public API for SSE management
|
|
|
|
### Reconnection Strategy
|
|
|
|
- Initial connection: immediate
|
|
- On disconnect: exponential backoff (1s, 2s, 4s, 8s, ... up to 60s)
|
|
- On successful reconnect: resets backoff to 1s
|
|
- Configurable via `noise-sse-max-reconnect-delay`
|
|
|
|
## Usage
|
|
|
|
### Starting SSE
|
|
|
|
When `noise-mode` is enabled, SSE starts automatically:
|
|
|
|
```elisp
|
|
(noise-mode 1) ;; Starts SSE connection
|
|
```
|
|
|
|
Or manually:
|
|
|
|
```elisp
|
|
M-x noise-receive-start-sse
|
|
```
|
|
|
|
### Stopping SSE
|
|
|
|
When `noise-mode` is disabled, SSE stops automatically:
|
|
|
|
```elisp
|
|
(noise-mode -1) ;; Stops SSE connection
|
|
```
|
|
|
|
Or manually:
|
|
|
|
```elisp
|
|
M-x noise-receive-stop-sse
|
|
```
|
|
|
|
### Configuration
|
|
|
|
```elisp
|
|
;; Maximum reconnect delay (default: 60 seconds)
|
|
(setq noise-sse-max-reconnect-delay 60)
|
|
|
|
;; Signal-cli address (default: http://localhost:8080)
|
|
(setq noise-signal-cli-address "http://localhost:8080")
|
|
|
|
;; Account for multi-account daemons
|
|
(setq noise-account "+15551234567")
|
|
```
|
|
|
|
### Manual Refresh
|
|
|
|
You can still manually fetch messages with:
|
|
|
|
```elisp
|
|
M-x noise-receive
|
|
```
|
|
|
|
This works even while SSE is running and is useful for initial setup or testing.
|
|
|
|
## Verification
|
|
|
|
### Test Results
|
|
|
|
All 66 tests pass:
|
|
|
|
```
|
|
Ran 66 tests, 66 results as expected, 0 unexpected
|
|
```
|
|
|
|
### Test Coverage
|
|
|
|
- **SSE parsing**: 3 tests for event parsing (basic, multiline, empty)
|
|
- **Connection state**: 3 tests for reconnection logic (initial state, backoff, max delay)
|
|
- **Process filter**: 2 tests for stream parsing (complete events, incomplete buffering)
|
|
- **Connection management**: 4 tests for URL construction and connect/disconnect
|
|
- **Integration**: Tests verify SSE integration with existing envelope processing
|
|
|
|
### Manual Testing
|
|
|
|
- Verified SSE connection establishment
|
|
- Confirmed real-time message reception
|
|
- Tested reconnection after connection loss
|
|
- Validated UI updates on incoming messages
|
|
|
|
## Journey Log
|
|
|
|
- [pivot] Replaced polling with SSE for real-time message reception
|
|
- [lesson] signal-cli supports SSE via `/api/v1/events` endpoint (confirmed from GitHub issues #2033, #2034, #1935)
|
|
- [lesson] Emacs `make-network-process` uses `:service` keyword for port, not `:port`
|
|
- [lesson] Test processes need careful mocking to avoid "Buffer has no process" errors
|
|
|
|
## Source Materials
|
|
|
|
| File | Role | Notes |
|
|
|------|------|-------|
|
|
| `docs/compose/plans/2026-06-11-sse-migration.md` | Implementation plan | Complete |
|
|
| `noise-sse.el` | SSE client implementation | New file |
|
|
| `noise-receive.el` | Message reception pipeline | Modified to use SSE |
|
|
| `noise.el` | Entry point | Updated noise-mode |
|