Data Synchronization

How files, profiles, and databases are synchronized across federated instances.

File Synchronization

When an inbound action carries file attachments, those files are pulled from the source instance during action processing. Files are content-addressed: a file’s ID is the hash of its descriptor, so integrity can be checked by recomputing the hash after download.

For each attachment that isn’t already held locally, the receiver:

  1. Fetches the descriptor at GET /api/files/{file_id}/descriptor and verifies that its hash matches the file_id. A mismatch aborts the sync.
  2. Parses the descriptor to discover the file’s variants (e.g. image resolutions) and downloads each one it needs from GET /api/files/variant/{variant_id}.
  3. Fetches file metadata from GET /api/files/{file_id}/metadata and stores it.

Attachment sync is atomic per action: if any attachment fails, the inbound action stays pending and the verifier task retries with exponential backoff until every attachment is synced. Already-present files are skipped, so deliveries don’t re-download content.

Profile Synchronization

Remote profiles are mirrored locally so they can be displayed without a round trip on every request. A profile is synced the first time it is referenced (the ensure_profile path creates it from the remote /api/me response if it isn’t already held).

To keep mirrors fresh, a background refresh batch re-fetches profiles whose local copy is older than 24 hours. If a profile’s source instance keeps failing to respond, the profile is eventually marked Suspended (after ~1 day of failures) and refresh attempts stop after ~7 days. There is no push mechanism — profile data is always pulled.

See Also