Documentation improvements

2026-05-01 19:12:57 +02:00 · 2026-04-17 00:38:50 -07:00
parent 6f00e857c2
commit 71da6841c1
6 changed files with 32 additions and 34 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -346,6 +346,7 @@ All endpoints are prefixed with `/api` (e.g., `/api/health`).
 | POST | `/api/contacts/{public_key}/repeater/radio-settings` | Fetch repeater radio config via CLI |
 | POST | `/api/contacts/{public_key}/repeater/advert-intervals` | Fetch advert intervals |
 | POST | `/api/contacts/{public_key}/repeater/owner-info` | Fetch owner info |
+| GET | `/api/contacts/{public_key}/repeater/telemetry-history` | Stored telemetry history for a repeater (read-only, no radio access) |
 | POST | `/api/contacts/{public_key}/room/login` | Log in to a room server |
 | POST | `/api/contacts/{public_key}/room/status` | Fetch room-server status telemetry |
 | POST | `/api/contacts/{public_key}/room/lpp-telemetry` | Fetch room-server CayenneLPP sensor data |
@@ -375,6 +376,7 @@ All endpoints are prefixed with `/api` (e.g., `/api/health`).
 | POST | `/api/settings/blocked-keys/toggle` | Toggle blocked key |
 | POST | `/api/settings/blocked-names/toggle` | Toggle blocked name |
 | POST | `/api/settings/tracked-telemetry/toggle` | Toggle tracked telemetry repeater |
+| GET | `/api/settings/tracked-telemetry/schedule` | Current telemetry scheduling derivation and next-run-at timestamp |
 | GET | `/api/fanout` | List all fanout configs |
 | POST | `/api/fanout` | Create new fanout config |
 | PATCH | `/api/fanout/{id}` | Update fanout config (triggers module reload) |
@@ -387,6 +389,8 @@ All endpoints are prefixed with `/api` (e.g., `/api/health`).
 | PATCH | `/api/push/subscriptions/{id}` | Update subscription label or filter preferences |
 | DELETE | `/api/push/subscriptions/{id}` | Delete a push subscription |
 | POST | `/api/push/subscriptions/{id}/test` | Send a test push notification |
+| GET | `/api/push/conversations` | Global list of push-enabled conversation state keys |
+| POST | `/api/push/conversations/toggle` | Add or remove a conversation from the global push list |
 | WS | `/api/ws` | Real-time updates |

 ## Key Concepts
@@ -498,7 +502,7 @@ mc.subscribe(EventType.ACK, handler)
 | `MESHCORE_ENABLE_MESSAGE_POLL_FALLBACK` | `false` | Switch the always-on radio audit task from hourly checks to aggressive 10-second polling; the audit checks both missed message drift and channel-slot cache drift |
 | `MESHCORE_FORCE_CHANNEL_SLOT_RECONFIGURE` | `false` | Disable channel-slot reuse and force `set_channel(...)` before every channel send, even on serial/BLE |

-**Note:** Runtime app settings are stored in the database (`app_settings` table), not environment variables. These include `max_radio_contacts`, `auto_decrypt_dm_on_advert`, `advert_interval`, `last_advert_time`, `last_message_times`, `flood_scope`, `blocked_keys`, `blocked_names`, `discovery_blocked_types`, `tracked_telemetry_repeaters`, and `auto_resend_channel`. `max_radio_contacts` is the configured radio contact capacity baseline used by background maintenance: favorites reload first, non-favorite fill targets about 80% of that value, and full offload/reload triggers around 95% occupancy. They are configured via `GET/PATCH /api/settings`. MQTT, bot, webhook, Apprise, and SQS configs are stored in the `fanout_configs` table, managed via `/api/fanout`. If the radio's channel slots appear unstable or another client is mutating them underneath this app, operators can force the old always-reconfigure send path with `MESHCORE_FORCE_CHANNEL_SLOT_RECONFIGURE=true`.
+**Note:** Runtime app settings are stored in the database (`app_settings` table), not environment variables. These include `max_radio_contacts`, `auto_decrypt_dm_on_advert`, `advert_interval`, `last_advert_time`, `last_message_times`, `flood_scope`, `blocked_keys`, `blocked_names`, `discovery_blocked_types`, `tracked_telemetry_repeaters`, `auto_resend_channel`, and `telemetry_interval_hours`. `max_radio_contacts` is the configured radio contact capacity baseline used by background maintenance: favorites reload first, non-favorite fill targets about 80% of that value, and full offload/reload triggers around 95% occupancy. They are configured via `GET/PATCH /api/settings`. MQTT, bot, webhook, Apprise, and SQS configs are stored in the `fanout_configs` table, managed via `/api/fanout`. If the radio's channel slots appear unstable or another client is mutating them underneath this app, operators can force the old always-reconfigure send path with `MESHCORE_FORCE_CHANNEL_SLOT_RECONFIGURE=true`.

 Byte-perfect channel retries are user-triggered via `POST /api/messages/channel/{message_id}/resend` and are allowed for 30 seconds after the original send.

--- a/4
+++ b/4
@@ -13,7 +13,7 @@ RUN VITE_COMMIT_HASH=${COMMIT_HASH} npm run build


 # Stage 2: Python runtime
-FROM python:3.12-slim
+FROM python:3.13-slim

 ARG COMMIT_HASH=unknown

@@ -22,7 +22,7 @@ WORKDIR /app
 ENV COMMIT_HASH=${COMMIT_HASH}

 # Install uv
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY --from=ghcr.io/astral-sh/uv:0.6 /uv /usr/local/bin/uv

 # Copy dependency files first for layer caching
 COPY pyproject.toml uv.lock ./
--- a/app/AGENTS.md
+++ b/app/AGENTS.md
@@ -27,10 +27,10 @@ app/
 ├── config.py            # Env-driven runtime settings
 ├── channel_constants.py # Public/default channel constants shared across sync/send logic
 ├── database.py          # SQLite connection + base schema + migration runner
-├── migrations.py        # Schema migrations (SQLite user_version)
+├── migrations/          # Schema migrations (SQLite user_version, per-version modules)
 ├── models.py            # Pydantic request/response models and typed write contracts (for example ContactUpsert)
 ├── version_info.py      # Unified version/build metadata resolution for debug + startup surfaces
-├── repository/          # Data access layer (contacts, channels, messages, raw_packets, settings, fanout)
+├── repository/          # Data access layer (contacts, channels, messages, raw_packets, settings, fanout, push_subscriptions, repeater_telemetry)
 ├── services/            # Shared orchestration/domain services
 │   ├── messages.py              # Shared message creation, dedup, ACK application
 │   ├── message_send.py          # Direct send, channel send, resend workflows
@@ -55,7 +55,7 @@ app/
 │   ├── send.py                  # pywebpush wrapper (async via thread executor)
 │   └── manager.py               # Push dispatch: filter, build payload, concurrent send
 ├── fanout/              # Fanout bus: MQTT, bots, webhooks, Apprise, SQS (see fanout/AGENTS_fanout.md)
-├── dependencies.py      # Shared FastAPI dependency providers
+├── telemetry_interval.py # Shared telemetry interval math for tracked-repeater scheduler
 ├── path_utils.py        # Path hex rendering and hop-width helpers
 ├── region_scope.py      # Normalize/validate regional flood-scope values
 ├── keystore.py          # Ephemeral private/public key storage for DM decryption
@@ -70,7 +70,7 @@ app/
    ├── packets.py
    ├── read_state.py
    ├── rooms.py
-    ├── server_control.py
+    ├── server_control.py   # Shared helpers for repeater/room CLI flows (not an APIRouter)
    ├── settings.py
    ├── fanout.py
    ├── repeaters.py
@@ -140,8 +140,9 @@ app/

 ### Echo/repeat dedup

- Message uniqueness: `(type, conversation_key, text, sender_timestamp)`.
- Duplicate insert is treated as an echo/repeat: the new path (if any) is appended, and the ACK count is incremented only for outgoing channel messages. Incoming direct messages with the same conversation/text/sender timestamp also collapse onto one stored row, with later observations merging path data instead of creating a second DM.
+- Channel message uniqueness: `(type, conversation_key, text, sender_timestamp)`.
+- Incoming PRIV message uniqueness: `(type, conversation_key, text, COALESCE(sender_timestamp, 0), COALESCE(sender_key, ''))` — `sender_key` was added in migration 056 to distinguish room-server posts from different senders in the same second.
+- Duplicate insert is treated as an echo/repeat: the new path (if any) is appended, and the ACK count is incremented only for outgoing channel messages. Incoming direct messages with the same dedup identity also collapse onto one stored row, with later observations merging path data instead of creating a second DM.

 ### Raw packet dedup policy

@@ -224,6 +225,7 @@ Web Push is a standalone subsystem in `app/push/`, separate from the fanout modu
 - `POST /contacts/{public_key}/repeater/radio-settings`
 - `POST /contacts/{public_key}/repeater/advert-intervals`
 - `POST /contacts/{public_key}/repeater/owner-info`
+- `GET /contacts/{public_key}/repeater/telemetry-history` — stored telemetry history for a repeater (read-only, no radio access)
 - `POST /contacts/{public_key}/room/login`
 - `POST /contacts/{public_key}/room/status`
 - `POST /contacts/{public_key}/room/lpp-telemetry`
@@ -263,6 +265,7 @@ Web Push is a standalone subsystem in `app/push/`, separate from the fanout modu
 - `POST /settings/blocked-keys/toggle`
 - `POST /settings/blocked-names/toggle`
 - `POST /settings/tracked-telemetry/toggle`
+- `GET /settings/tracked-telemetry/schedule` — current telemetry scheduling derivation, interval options, and next-run-at timestamp

 ### Fanout
 - `GET /fanout` — list all fanout configs
@@ -281,6 +284,8 @@ Web Push is a standalone subsystem in `app/push/`, separate from the fanout modu
 - `PATCH /push/subscriptions/{id}` — update label or filter preferences
 - `DELETE /push/subscriptions/{id}` — delete subscription
 - `POST /push/subscriptions/{id}/test` — send test notification
+- `GET /push/conversations` — global list of push-enabled conversation state keys
+- `POST /push/conversations/toggle` — add or remove a conversation from the global push list

 ### WebSocket
 - `WS /ws`
@@ -338,6 +343,7 @@ Repository writes should prefer typed models such as `ContactUpsert` over ad hoc
 - `blocked_keys`, `blocked_names`, `discovery_blocked_types`
 - `tracked_telemetry_repeaters`
 - `auto_resend_channel`
+- `telemetry_interval_hours`

 Note: MQTT, community MQTT, and bot configs were migrated to the `fanout_configs` table (migrations 36-38).

--- a/frontend/AGENTS.md
+++ b/frontend/AGENTS.md
@@ -40,7 +40,8 @@ frontend/src/
 ├── styles.css              # Additional global app styles
 ├── themes.css              # Color theme definitions
 ├── contexts/
-│   └── DistanceUnitContext.tsx # Browser-local distance-unit context/provider
+│   ├── DistanceUnitContext.tsx # Browser-local distance-unit context/provider
+│   └── PushSubscriptionContext.tsx # Push subscription state context/provider
 ├── lib/
 │   └── utils.ts            # cn() — clsx + tailwind-merge helper
 ├── hooks/
@@ -92,7 +93,13 @@ frontend/src/
 │   ├── radioPresets.ts            # LoRa radio preset configurations
 │   ├── publicChannel.ts           # Public-channel resolution helpers for routing/hash defaults
 │   ├── fontScale.ts               # Browser-local relative font scale persistence/application
-│   └── theme.ts                   # Theme switching helpers
+│   ├── theme.ts                   # Theme switching helpers
+│   ├── autoFocusInput.ts          # Auto-focus input helper
+│   ├── batteryDisplay.ts          # Battery level display helpers
+│   ├── messageIdentity.ts         # Message identity/dedup helpers
+│   ├── rawPacketInspector.ts      # Raw packet inspection helpers
+│   ├── serverLoginState.ts        # Server login state helpers
+│   └── statusDotPulse.ts          # Status dot pulse animation helpers
 ├── components/
 │   ├── StatusBar.tsx
 │   ├── Sidebar.tsx
@@ -135,7 +142,8 @@ frontend/src/
 │   │   ├── SettingsDatabaseSection.tsx   # DB size, cleanup, auto-decrypt, local label
 │   │   ├── SettingsStatisticsSection.tsx # Read-only mesh network stats
 │   │   ├── SettingsAboutSection.tsx     # Version, author, license, links
-│   │   └── ThemeSelector.tsx           # Color theme picker
+│   │   ├── ThemeSelector.tsx           # Color theme picker
+│   │   └── BulkDeleteContactsModal.tsx # Bulk contact deletion dialog
 │   ├── repeater/
 │   │   ├── repeaterPaneShared.tsx        # Shared: RepeaterPane, KvRow, format helpers
 │   │   ├── RepeaterTelemetryPane.tsx    # Battery, airtime, packet counts
@@ -145,6 +153,7 @@ frontend/src/
 │   │   ├── RepeaterRadioSettingsPane.tsx # Radio config + advert intervals
 │   │   ├── RepeaterLppTelemetryPane.tsx # CayenneLPP sensor data
 │   │   ├── RepeaterOwnerInfoPane.tsx    # Owner info + guest password
+│   │   ├── RepeaterTelemetryHistoryPane.tsx # Historical telemetry chart/table
 │   │   ├── RepeaterActionsPane.tsx      # Send Advert, Sync Clock, Reboot
 │   │   └── RepeaterConsolePane.tsx      # CLI console with history
 │   └── ui/                     # shadcn/ui primitives
@@ -357,7 +366,7 @@ LocalStorage migration helpers for favorites; canonical favorites are server-sid
 - `blocked_keys`, `blocked_names`, `discovery_blocked_types`
 - `tracked_telemetry_repeaters`
 - `auto_resend_channel`
-
+- `telemetry_interval_hours`

 Note: MQTT, bot, and community MQTT settings were migrated to the `fanout_configs` table (managed via `/api/fanout`). They are no longer part of `AppSettings`.

--- a/pyproject.toml
+++ b/pyproject.toml
@@ -19,14 +19,6 @@ dependencies = [
    "pywebpush>=0.14.0",
 ]

-[project.optional-dependencies]
-test = [
-    "pytest>=8.0.0",
-    "pytest-asyncio>=0.24.0",
-    "pytest-xdist>=3.0",
-    "httpx>=0.27.0",
-]
-
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
--- a/uv.lock
+++ b/uv.lock
@@ -1550,14 +1550,6 @@ dependencies = [
    { name = "uvicorn", extra = ["standard"] },
 ]

-[package.optional-dependencies]
-test = [
-    { name = "httpx" },
-    { name = "pytest" },
-    { name = "pytest-asyncio" },
-    { name = "pytest-xdist" },
-]
-
 [package.dev-dependencies]
 dev = [
    { name = "httpx" },
@@ -1577,18 +1569,13 @@ requires-dist = [
    { name = "boto3", specifier = ">=1.38.0" },
    { name = "fastapi", specifier = ">=0.115.0" },
    { name = "httpx", specifier = ">=0.28.1" },
-    { name = "httpx", marker = "extra == 'test'", specifier = ">=0.27.0" },
    { name = "meshcore", specifier = "==2.3.2" },
    { name = "pycryptodome", specifier = ">=3.20.0" },
    { name = "pydantic-settings", specifier = ">=2.0.0" },
    { name = "pynacl", specifier = ">=1.5.0" },
-    { name = "pytest", marker = "extra == 'test'", specifier = ">=8.0.0" },
-    { name = "pytest-asyncio", marker = "extra == 'test'", specifier = ">=0.24.0" },
-    { name = "pytest-xdist", marker = "extra == 'test'", specifier = ">=3.0" },
    { name = "pywebpush", specifier = ">=0.14.0" },
    { name = "uvicorn", extras = ["standard"], specifier = ">=0.32.0" },
 ]
-provides-extras = ["test"]

 [package.metadata.requires-dev]
 dev = [