Fix "list quarantined media" API to have semi-stable ordering #19308

turt2live · 2025-12-16T05:13:24Z

Note: This cleans up previous code introduced by #19268

When first writing the API, "unquarantining" media was not properly considered. If media was unquarantined and an application was treating from tokens as long-lived when listing quarantined media, the endpoint could skip rows like so:

Media A is quarantined
Media B is quarantined
Application lists quarantined media, caches from=2
Media A is unquarantined, shifting B from row 1 to 0
Media C is quarantined, becoming the new row 1
Media D is quarantined
Application lists media with from=2, gets [D]

To fix this, we invent a pagination token which uses time and a relative index. It's not super stable still because the relative index can still change, but it's likely stable enough for most usage (iterate as fast as possible to the end).

If an application requires a proper time-based stable token, it can generate a timestamp then append -0 to it to set the relative position to the zeroth row. This may return rows the application has already seen, as described by the admin API docs. This particular method of generating the timestamp manually is not documented because it's not as stable as relying on the last seen next_batch's internal timestamp.

This PR doesn't shift the whole endpoint to timestamp-only tokens because the prior PR populates rows with 0 for a timestamp, which may span thousands (or millions) of rows, breaking the ability to use limit properly.

Pull Request Checklist

Pull request is based on the develop branch
Pull request includes a changelog file. The entry should:
- Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
- Use markdown where necessary, mostly for code blocks.
- End with either a period (.) or an exclamation mark (!).
- Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
Code style is correct (run the linters)

https://github.com/element-hq/synapse/pull/19268/changes#r2614217300 wasn't applied and the migration had copy/paste artifacts. PR: #19268

synapse/rest/admin/media.py

turt2live · 2025-12-16T05:19:22Z

docs/admin_api/media_admin_api.md

+`from` and `limit` are optional parameters, and default to the first page and `100` respectively. `from` is the `next_batch`
+token returned by a previous request and `limit` is the number of rows to return. Note that `next_batch` is not intended 
+to survive longer than about a minute and may produce inconsistent results if used after that time. Neither `from` or 
+`limit` is a timestamp, though `from` does encode a timestamp.
+
+If you require a long-lived `from` token, split `next_batch` on `-` and combine the first part with a `0`, separated by
+a `-` again. For example: `1234-5678` becomes `1234-0`. Your application will need to deduplicate `media` rows it has 
+already seen if using this method.


I do accept that this is custom, weird, and not-quite how pagination works. My defence is I have a custom, weird, not-quite-paginating use case 😇

(though, if someone more qualified wants to make this use PaginationHandler instead, I'd happily close this PR in favour of that one)

turt2live · 2025-12-16T06:10:08Z

synapse/rest/admin/media.py

+        elif len(start) > 0:
+            start_index = int(start)


We probably don't need this backwards compatibility given the PR which introduced the endpoint has only been on develop for a few days as of writing. I've kept it anyway because I honestly just don't want to fight the unit tests too much. I can be convinced to enter battle, however.

We should get rid of the tech debt

MadLittleMods · 2025-12-23T21:23:16Z

synapse/storage/schema/main/delta/93/04_add_quarantined_ts_to_media.sql

-- Add a timestamp for when the sliding sync connection position was last used,
-- only updated with a small granularity.
--
-- This should be NOT NULL, but we need to consider existing rows. In future we
-- may want to either backfill this or delete all rows with a NULL value (and
-- then make it NOT NULL).


Removed because bad copy-paste (I assume)

MadLittleMods · 2025-12-23T21:26:01Z

docs/admin_api/media_admin_api.md

+If you require a long-lived `from` token, split `next_batch` on `-` and combine the first part with a `0`, separated by
+a `-` again. For example: `1234-5678` becomes `1234-0`. Your application will need to deduplicate `media` rows it has 
+already seen if using this method.


huh, why are we suggesting this? Why is this a use case?

MadLittleMods · 2025-12-23T21:26:51Z

docs/admin_api/media_admin_api.md

+token returned by a previous request and `limit` is the number of rows to return. Note that `next_batch` is not intended 
+to survive longer than about a minute and may produce inconsistent results if used after that time. Neither `from` or 


Where is this limitation coming from?

MadLittleMods · 2025-12-23T21:27:35Z

docs/admin_api/media_admin_api.md

+to survive longer than about a minute and may produce inconsistent results if used after that time. Neither `from` or 
+`limit` is a timestamp, though `from` does encode a timestamp.


Superfluous details. The end user can treat them as opaque.

Suggested change

to survive longer than about a minute and may produce inconsistent results if used after that time. Neither `from` or

`limit` is a timestamp, though `from` does encode a timestamp.

to survive longer than about a minute and may produce inconsistent results if used after that time.

MadLittleMods · 2025-12-23T21:33:36Z

synapse/rest/admin/media.py

+        elif len(start) > 0:
+            start_index = int(start)


We should get rid of the tech debt

MadLittleMods · 2025-12-23T21:34:37Z

synapse/rest/admin/media.py

+            # Batch tokens are structured as `timestamp-index`, where `index` is relative
+            # to the timestamp. This is done to support pages having many records with
+            # the same timestamp (like existing servers having a ton of `ts=0` records).


This is different (partial) from the reason in the PR description

MadLittleMods · 2025-12-23T21:41:03Z

synapse/storage/databases/main/room.py

            # known) to ensure the ordering is stable for established servers.
            if local:
-                sql = "SELECT '' as media_origin, media_id FROM local_media_repository WHERE quarantined_by IS NOT NULL ORDER BY quarantined_ts, media_id ASC LIMIT ? OFFSET ?"
+                sql = "SELECT '' as media_origin, media_id, quarantined_ts FROM local_media_repository WHERE quarantined_by IS NOT NULL AND quarantined_ts >= ? ORDER BY quarantined_ts, media_id ASC LIMIT ? OFFSET ?"


Instead of relying on quarantined_ts and index for pagination (which is still flawed), we could add a new column quarantined_stream_id that is filled in when something is quarantined.

Docs: docs/development/synapse_architecture/streams.md#cheatsheet-for-creating-a-new-stream

A stream feels like way more overhead than we need for this. Is there something lighter weight we can use instead? (like just a simple ID generator?)

I think a stream is the Synapse way to solve this. We only need to do the first few steps from the docs since this isn't something that is going to be part of /sync or the StreamToken.

turt2live added 2 commits December 15, 2025 21:24

Cleanup from previous PR

32ce7a3

https://github.com/element-hq/synapse/pull/19268/changes#r2614217300 wasn't applied and the migration had copy/paste artifacts. PR: #19268

Switch to a semi-stable pagination ordering

a4036bf

turt2live changed the title ~~Travis/fix quarantine list~~ Fix "list quarantined media" API to have semi-stable ordering Dec 16, 2025

changelog

ad230c4

turt2live commented Dec 16, 2025

View reviewed changes

synapse/rest/admin/media.py Outdated Show resolved Hide resolved

turt2live commented Dec 16, 2025

View reviewed changes

turt2live force-pushed the travis/fix-quarantine-list branch from c7ec79d to 1128c59 Compare December 16, 2025 06:28

linting & fix tests

516b740

turt2live force-pushed the travis/fix-quarantine-list branch from 1128c59 to 516b740 Compare December 16, 2025 06:41

turt2live marked this pull request as ready for review December 16, 2025 06:53

turt2live requested a review from a team as a code owner December 16, 2025 06:53

This was referenced Dec 16, 2025

Add a Synapse Quarantined Media exchange matrix-org/hma-matrix#7

Merged

Add indexes for quarantined media lookups #19312

Open

Merge branch 'develop' into travis/fix-quarantine-list

ca8d945

MadLittleMods added the A-Admin-API label Dec 23, 2025

MadLittleMods reviewed Dec 23, 2025

View reviewed changes

		token returned by a previous request and `limit` is the number of rows to return. Note that `next_batch` is not intended
		to survive longer than about a minute and may produce inconsistent results if used after that time. Neither `from` or

		to survive longer than about a minute and may produce inconsistent results if used after that time. Neither `from` or
		`limit` is a timestamp, though `from` does encode a timestamp.

Fix "list quarantined media" API to have semi-stable ordering #19308

Are you sure you want to change the base?

Fix "list quarantined media" API to have semi-stable ordering #19308

Conversation

turt2live commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

turt2live commented Dec 16, 2025 •

edited

Loading

MadLittleMods Dec 23, 2025 •

edited

Loading