Skip to content

feat(client-sync): add home-server settings sync - #1573

Draft
hmans wants to merge 17 commits into
mainfrom
hmans/choose-next-task
Draft

feat(client-sync): add home-server settings sync#1573
hmans wants to merge 17 commits into
mainfrom
hmans/choose-next-task

Conversation

@hmans

@hmans hmans commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Why

Chatto's multi-server client needs a portable, instance-independent home for
personal settings and the known-server directory before it can ship cleanly as
a standalone web, desktop, or mobile client. A new device should be able to
restore those settings naturally from a Chatto server the user already trusts,
without asking them to configure a separate sync URL.

What changed

  • adds an operator-opt-in client-sync capability advertised through server
    discovery and exposed through the dedicated public
    chatto.clientsync.api.v1 ConnectRPC package
  • stores persisted client-sync documents in the separate
    chatto.clientsync.v1 package at
    client_sync.{userId}.{preferences,servers} in the existing backed-up
    RUNTIME_STATE KV bucket; this data does not enter EVT
  • adds a visible, protected home server: the sole eligible authenticated server
    is selected automatically, while multiple eligible servers require an
    explicit choice
  • adds a server-independent /settings screen and app-header gear for theme,
    language, timezone/time format, and notification sounds
  • keeps theme and sound device-local, while syncing locale, timezone, time
    format, and up to 100 public known-server records
  • reconciles server directories by canonical URL origin without ever syncing
    passwords, cookies, bearer tokens, passkeys, or sessions
  • restores known servers without credentials and requires authentication before
    connecting or following a remote home-server redirect
  • makes home moves non-destructive and rolls the local choice back if the
    destination cannot accept the transfer
  • keeps pending-home recovery reactive and bound to the source account, while
    leaving an explicit path to keep the current capable home
  • preserves edits made while the initial remote load is in flight and waits for
    discovery to settle before automatically choosing a home
  • fences client-sync writes before account deletion, purges both user records,
    and continuously retries durable pending cleanup on every replica; a
    post-write fence check prevents concurrent mutations from recreating erased
    data
  • validates synced timezones for browser compatibility and constrains the
    settings back link to parsed same-origin paths
  • replaces the clipped outline house with a compact filled home-server medallion
    and an accessible label
  • documents the design in ADR-051 and FDR-031 and updates the glossary, runtime
    inventory, configuration reference, generated API docs, and translations

Compatibility, security, and operations

  • this is additive public API and discovery surface; 0.4 servers and servers
    with client sync disabled simply remain ineligible as a home server
  • client sync is disabled by default and enabled with
    [client_sync].enabled or CHATTO_CLIENT_SYNC_ENABLED
  • disabled API calls return UNIMPLEMENTED, allowing mixed-version clients to
    fail soft and retain device-local settings
  • server origins are canonicalised (including IDNs and ports) and unique; synced
    metadata cannot replace an authenticated local origin or redirect its token
  • caches, baselines, and pending moves are scoped to the authenticated home
    account to avoid shared-device cross-account leakage
  • backups already include RUNTIME_STATE; the renamed keys and API are
    unreleased, so no storage migration is required

Test plan

  • mise codegen-proto
  • mise x -- buf lint --path proto/chatto/clientsync --path proto/chatto/discovery/v1/server.proto proto
  • mise lint-frontend — Svelte check: 0 errors and 0 warnings; ESLint clean
  • frontend unit/component suite — 260 files, 2,214 tests passed
  • focused client-sync, home-marker, and navigation suite — 55 tests passed
  • mise test-cli — production frontend build and all Go packages passed
  • docs website production build
  • REUSE 3.3 lint — all 2,206 files compliant (run with the missing
    charset-normalizer extra because the repository wrapper's isolated install
    currently lacks an encoding detector)
  • iterative adversarial code review; all findings fixed and covered by
    regression tests before the final clean pass

Interactive in-app browser control was unavailable in this environment;
browser-mounted Vitest coverage supplied runtime UI verification. The home
marker remains worth a quick manual aesthetic check before merge.

Closes #1565.
Closes #148.

@hmans hmans changed the title feat: add home-server personal data sync feat(client-sync): add home-server settings sync Jul 15, 2026
@hmans hmans added the draft Needs refinement before starting label Jul 15, 2026
hmans added 2 commits July 15, 2026 22:33
* origin/main:
  feat: add native social post previews (#1569)
  feat(frontend): add server and room context menus (#1580)

# Conflicts:
#	apps/frontend/src/lib/ServerIcon.svelte
* origin/main:
  fix(api): batch presence hydration (#1597)
  fix(frontend): scope thread click-outside dismissal (#1595)
  fix(release): make next prerelease alpha (#1596)
  docs(api): rewrite compatibility guidance (#1593)
  docs: expand operator CLI guide (#1590)
  feat(api): add client-server compatibility discovery (#1586)
  fix(frontend): enforce server description limit (#1587)
  fix(core): forbid threads in direct messages (#1583)
  refactor(core): lease snapshot work per pass (#1581)

# Conflicts:
#	apps/docs-website/src/content/docs/reference/connectrpc-api/index.mdx
#	apps/docs-website/src/content/docs/reference/connectrpc-api/server-discovery.mdx
#	apps/docs-website/src/content/docs/reference/connectrpc-api/types.mdx
#	apps/docs-website/src/generated/connectrpc-api/discovery.raw.mdx
#	apps/frontend/src/lib/ServerIcon.svelte
#	apps/frontend/src/lib/ServerSidebarEntry.svelte
#	apps/frontend/src/lib/api-client-tests/server.spec.ts
#	apps/frontend/src/lib/state/server/store.svelte.spec.ts
#	apps/frontend/src/routes/layout.svelte.spec.ts
#	cli/internal/connectapi/server.go
#	cli/internal/pb/chatto/discovery/v1/server.pb.go
#	docs/architecture/runtime-components.md
#	docs/fdr/INDEX.md
#	packages/api-types/src/chatto/discovery/v1/server_pb.ts
#	proto/chatto/discovery/v1/server.proto
#	tools/split-connectrpc-docs.mjs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

draft Needs refinement before starting

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Move user preferences from localStorage to KV storage Add a home server and personal-data sync

1 participant