Skip to content

Sync body measurements from NutriTrace - #123

Open
kgenerozov wants to merge 2 commits into
TraceApps:devfrom
kgenerozov:feat/nutritrace-body-sync
Open

kgenerozov wants to merge 2 commits into
TraceApps:devfrom
kgenerozov:feat/nutritrace-body-sync

Conversation

@kgenerozov

@kgenerozov kgenerozov commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

NutriTrace already records weight and body fat from a scale or Health Connect, so the same numbers can fill LiftTrace's body stats without being typed again. This adds an opt-in import from one exact NutriTrace source and hardens the connection and persistence around it: a connection is one atomic server transition with a monotonic compare-and-set version, the import provenance is server-owned, and a device, tab or offline queue can no longer leave the two half-saved.

Two commits, rebased onto dev@97b5da1 (v1.5.0-dev01-4-g97b5da1):

  • 48d436b Sync body measurements from NutriTrace
  • 0a42225 Persist NutriTrace federation state immediately

What changes

Body-measurement import (opt-in)

  • GET /api/nt/body-composition is a narrow proxy to NutriTrace's native read API (mcp:read, NutriTrace must run with PUBLIC_API_ENABLED=1). Only start, end and source are forwarded; the bearer token stays on the server.
  • Every successful read answers with a single-use receipt header X-LT-Nt-Read-Id (10 minutes, per account, in-process). The import must present it when it claims the provenance.
  • The first import fixes which NutriTrace connection and source own the imported history, with a server-side compare-and-set (BEGIN IMMEDIATE). A later different source or connection is refused with the fixed pair.
  • Only weight and body fat are written, as partial body-stat updates: manual circumferences and every other LiftTrace field stay as they are. Values that are not a measurement — null, an empty string, booleans, structures, 0, and out-of-range numbers — are never written as 0 kg or 0%.
  • The client keeps a per-account cache of the server's provenance. It is rebuilt from the server record on every settings pull and from the native pull field (below), and Clear Data clears it together with the six-hour throttle, so a wipe always allows choosing another source.
  • One FIFO queue serialises a connection change and an import; both re-check the signed-in account before each side effect.

Connection persistence

  • PUT /api/nt/federation-connection verifies the address and token and writes URL, token, identity, scopes and enabled in one SQLite transaction. Either the server holds the whole new connection or the whole previous one — two tabs can no longer interleave into one Save's address with another's identity, and a failed step cannot leave a new token behind an old address.
  • GET /api/nt/federation-connection returns the saved connection without the token, for the Settings page and for a client whose Save answer was lost.
  • A connection saved before identities existed keeps its URL, token placeholder and workout-federation switch; only body measurements wait for a new verification, and the page shows a warning instead of clearing the connection. Workouts keep reaching NutriTrace, while the body proxy stays fail-closed until Save/Verify runs.
  • Two values travel with the connection and answer different questions:
    • fingerprint (address + write-only token + identity) says whether the stored identity still belongs to the stored credentials. The token never reaches the client, so a separate settings write cannot forge it; the connection fails closed until it is saved again.
    • version is a monotonic, server-owned counter bumped by every transition, including OFF and A -> B -> A. It is the compare-and-set value: a Save names the version it started from (ifVersion), so a tab that still shows an older connection is refused instead of turning federation back on or replacing a newer Save. Because the counter is server-owned, a settings write cannot rewind it.
  • A 409 connection-changed carries the current connection. The page reconciles through GET on a 409 or any indeterminate answer (lost reply, timeout, offline ambiguity), publishing what the server actually saved instead of assuming failure. The token is never rolled back locally: the server never sends it, so the page keeps the placeholder.
  • Every Save names the version it started from, including 0 and with no identity: a tab opened before the first connection cannot turn federation on unconditionally after another tab connected and then switched it off. A direct settings write of a connection field, and Clear All Settings deleting the connection, both bump the version, so a Save that was already on its way cannot pass the compare-and-set. Only a client from before the field (no ifVersion) is still accepted, for compatibility.
  • Nothing is published locally until the server confirms, and every post-await publication re-checks the signed-in account. A response that arrives after A signed out can no longer write A's URL, identity or "Connected as" into B's settings.
  • The transition and the body-sync switch/source are network-only. Queued/offline answers are failures, the web outbox does not queue these keys, and a write already queued by an older client is dropped from the replay instead of being applied later (an offline toggle would otherwise silently turn body sync on when the connection returns).
  • The same applies to the native queue: _flushQueue() deletes old ntFederationEnabled / ntBodySyncEnabled writes instead of sending them, so an upgrade cannot replay a decision the user was told had failed.
  • NutriTrace replies are read inside the whole-exchange deadline with the shared 1 MiB body ceiling, so a slow or endless reply cannot hang the proxy or fill memory.
  • GET /api/sync/pull carries nt_body_provenance as its own field, null included. An Android foreground pull therefore rebuilds the device cache from the server, or clears the markers and the six-hour throttle when Clear Data on another device released the claim. Clear Data also deletes the throttle row on the server.
  • ntConnectionVersion and ntConnectionScopes are server-owned: 403 reserved-setting on the generic settings API and never device-pushed.

Historical safety

  • The server never mixes provenance: the first claim wins, every imported body-stat write carries the claim, and a write with another claim is refused before the row is touched.
  • A read is tied to the exact saved configuration by the receipt fingerprint and version. Switching the connection away and back, rotating the token, or an OFF/ON transition between the read and the claim is refused, so measurements can never be attributed to the other NutriTrace account.
  • The import never rewrites manual measurements and never clears fields it did not map.
  • The NutriTrace token stays server-side (write-only). Saving the dots keeps it, clearing it clears it, and changing the address requires the token to be entered again. A failed transition leaves the old token, URL, identity, enabled flag and version exactly as they were.
  • Clear Data releases the server claim with the imported history and clears the device cache and throttle, so the next import may choose another source.
  • The provenance keys (ntBodyProvenance and the legacy pair) are refused by the generic settings API (403 reserved-setting) and are not device-synced.
  • The compatibility extension nutritrace_body_composition_sync and the one-way alias normalisation (bodyFat/body_fat) are unchanged.

Validation

On the rebased tree (97b5da1 + two commits):

  • npm test — 2000 tests, 1999 pass, 1 skipped (SQLite driver), 0 fail
  • npm run i18n:check — OK (English source has 2304 keys; other locales remain informational)
  • npm run build — OK (Vite + PWA precache)
  • git diff --check — clean
  • git apply --check of the artifact on a clean 97b5da1 — OK; the focused federation/offline/secret tests on that clean apply — 184 pass, 0 fail.
  • New behaviour suite scripts/nt-federation-routes.test.js against the real server and a NutriTrace stub:
    • two interleaved Saves never return a mixed address/identity, and GET never exposes the token
    • a Save with an older version is refused; OFF then a stale ON stays off; A -> B -> A does not make an old A Save current; an explicitly typed token at a new address is refused without touching the saved connection
    • a version-0 Save (tab opened before the first connection) is refused after another Save + OFF; a direct settings write and Clear All Settings both bump the version
    • a connection saved before identities still sends workouts, keeps enabled, and refuses body reads until it is verified again
    • an old native queue holding ntFederationEnabled / ntBodySyncEnabled is dropped, not replayed, after the update
    • a write-only token is reused only for its own address; a refused token leaves the previous connection and version whole
    • connections are per account; reserved server-owned keys return 403
    • a receipt is single-use, per account, expires, and refuses token rotation; it fails closed across a restart; Clear Data then allows another source
    • the pull carries the claim (and null after Clear Data), and the server throttle row is gone
    • a read that sends headers and stalls, or sends more than the ceiling, is refused

Not covered / still consciously limited:

  • The second commit message still describes the earlier key-by-key transition; it is kept verbatim as requested and the implementation is the atomic endpoint described above.
  • The legacy ntBodySyncedSource / ntBodySyncedConnectionIdentity rows from earlier revisions of this PR are still adopted as the first claim. Removing that would drop the safety net for anyone who ran an earlier build; it can be a follow-up once the branch has shipped.
  • GET /api/settings remains readable for the connection identity/version; only writes, device sync and receipts are guarded. A client can read the current identity, but the fingerprint cannot be forged without the write-only token.
  • The connection settings are read without a read transaction. A commit landing between those reads makes the fingerprint or version mismatch, so the proxy and the claim fail closed (connection-unverified / connection-mismatch / read-identity-mismatch) rather than using a mixed pair; only the failure mode is racy, not the attribution.
  • The body-sync switch and source are now network-only: changing them offline reports a failure instead of queueing. That is intentional, but it is a behaviour change for a device that used to queue every setting.
  • Reconcile decides that a lost Save succeeded by the saved URL and enabled (plus an identity), not by comparing the typed token or a revision. This is the known minor noted by review and was left untouched.
  • A 409 carries connection and the API client propagates it, but the page still reconciles with a fresh GET rather than using that body directly. This is the known minor noted by review and was left untouched.

@kgenerozov
kgenerozov marked this pull request as draft September 26, 2026 16:50
@kgenerozov
kgenerozov force-pushed the feat/nutritrace-body-sync branch from bf66885 to 043996b Compare September 26, 2026 17:25
@kgenerozov
kgenerozov marked this pull request as ready for review September 26, 2026 17:30
@kgenerozov
kgenerozov marked this pull request as draft September 29, 2026 14:09
@kgenerozov
kgenerozov force-pushed the feat/nutritrace-body-sync branch from 49c68da to b1b7497 Compare September 29, 2026 14:35
@kgenerozov
kgenerozov marked this pull request as ready for review September 30, 2026 04:17
@kgenerozov
kgenerozov force-pushed the feat/nutritrace-body-sync branch from b1b7497 to 1d23e1a Compare October 5, 2026 04:20
@kgenerozov
kgenerozov force-pushed the feat/nutritrace-body-sync branch from 1d23e1a to 1f6612f Compare November 13, 2026 06:37
NutriTrace already records weight and body fat from a scale or Health
Connect, so the same numbers can fill LiftTrace's body stats without being
typed again. The import is opt-in, reads only through NutriTrace's
body-composition API, and asks for one exact source: measurements from two
providers are never combined.

The source is fixed on the server by the first import and every imported
write carries it, so a second tab, a connection switch or an older client
cannot move the history to another provider. Manual circumference values
and every other field the user keeps in LiftTrace are left as they are.
A connection test saved its URL, token and verified flag through the
debounced settings store, so opening the Diary or another tab within 600 ms
could read the old values: a body import could be attributed to the
connection that was replaced, or a workout could go to the wrong instance.

A tested connection is now written one key at a time, disabled first and
enabled last, and the save is awaited before the page reports success.
Connection changes and the body import share one queue, and every write
re-checks the signed-in account, so neither can act on the other's state or
on the next account's settings.
@kgenerozov
kgenerozov force-pushed the feat/nutritrace-body-sync branch from 1f6612f to 0a42225 Compare November 13, 2026 06:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant