From 80605df8620758dee9c53957016bc68133dcac61 Mon Sep 17 00:00:00 2001 From: Markus Ressel Date: Sat, 14 Nov 2026 03:46:48 +0100 Subject: [PATCH] Add a REST client for the revision history Models follow a real backend answer: authors who are not accounts come with empty strings, and times carry the committer's offset. Co-Authored-By: Claude Opus 5.5 --- .../mkdocsrestclient/DummyMkDocsRestClient.kt | 13 ++++ .../mkdocsrestclient/IMkDocsRestClient.kt | 4 +- .../mkdocsrestclient/MkDocsRestClient.kt | 6 +- .../mkdocsrestclient/history/HistoryApi.kt | 69 +++++++++++++++++ .../mkdocsrestclient/history/HistoryModels.kt | 38 +++++++++ .../history/HistoryModelsTest.kt | 77 +++++++++++++++++++ 6 files changed, 205 insertions(+), 2 deletions(-) create mode 100644 rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryApi.kt create mode 100644 rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryModels.kt create mode 100644 rest/src/test/java/de/markusressel/mkdocsrestclient/history/HistoryModelsTest.kt diff --git a/rest/src/main/java/de/markusressel/mkdocsrestclient/DummyMkDocsRestClient.kt b/rest/src/main/java/de/markusressel/mkdocsrestclient/DummyMkDocsRestClient.kt index 252a831d..7a62e9a0 100644 --- a/rest/src/main/java/de/markusressel/mkdocsrestclient/DummyMkDocsRestClient.kt +++ b/rest/src/main/java/de/markusressel/mkdocsrestclient/DummyMkDocsRestClient.kt @@ -3,6 +3,7 @@ package de.markusressel.mkdocsrestclient import de.markusressel.mkdocsrestclient.dashboard.FeedPageModel +import de.markusressel.mkdocsrestclient.history.HistoryEntryModel import de.markusressel.mkdocsrestclient.dashboard.PinScope import de.markusressel.mkdocsrestclient.dashboard.PinsModel import de.markusressel.mkdocsrestclient.reference.AuthorshipModel @@ -275,6 +276,18 @@ class DummyMkDocsRestClient : IMkDocsRestClient { override suspend fun getFeed(before: String?, limit: Int): Result = Result.success(FeedPageModel()) + override suspend fun getDocumentHistory(documentId: String, limit: Int): Result, FuelError> = + Result.success(emptyList()) + + override suspend fun getDocumentRevisionContent(documentId: String, revision: String): Result = + Result.success("") + + override suspend fun getDocumentRevisionDiff(documentId: String, from: String, to: String): Result = + Result.success("") + + override suspend fun restoreDocumentRevision(documentId: String, revision: String): Result = + Result.success("") + override suspend fun getQrCode(key: String, scan: Boolean): Result = Result.error(FuelError.wrap(UnsupportedOperationException("not in the demo"))) diff --git a/rest/src/main/java/de/markusressel/mkdocsrestclient/IMkDocsRestClient.kt b/rest/src/main/java/de/markusressel/mkdocsrestclient/IMkDocsRestClient.kt index c5463eea..cccbbe25 100644 --- a/rest/src/main/java/de/markusressel/mkdocsrestclient/IMkDocsRestClient.kt +++ b/rest/src/main/java/de/markusressel/mkdocsrestclient/IMkDocsRestClient.kt @@ -4,6 +4,7 @@ import com.github.kittinunf.fuel.core.FuelError import com.github.kittinunf.result.Result import de.markusressel.mkdocsrestclient.dashboard.DashboardApi import de.markusressel.mkdocsrestclient.document.DocumentApi +import de.markusressel.mkdocsrestclient.history.HistoryApi import de.markusressel.mkdocsrestclient.mkdocs.MkDocsApi import de.markusressel.mkdocsrestclient.qr.QrCodeApi import de.markusressel.mkdocsrestclient.reference.ReferenceApi @@ -11,7 +12,8 @@ import de.markusressel.mkdocsrestclient.resource.ResourceApi import de.markusressel.mkdocsrestclient.section.SectionApi import de.markusressel.mkdocsrestclient.section.SectionModel -interface IMkDocsRestClient : MkDocsApi, SectionApi, DocumentApi, ResourceApi, ReferenceApi, DashboardApi, QrCodeApi { +interface IMkDocsRestClient : MkDocsApi, SectionApi, DocumentApi, ResourceApi, ReferenceApi, DashboardApi, QrCodeApi, + HistoryApi { /** * Check if the server is alive and reachable diff --git a/rest/src/main/java/de/markusressel/mkdocsrestclient/MkDocsRestClient.kt b/rest/src/main/java/de/markusressel/mkdocsrestclient/MkDocsRestClient.kt index 87994de7..0dd9b082 100644 --- a/rest/src/main/java/de/markusressel/mkdocsrestclient/MkDocsRestClient.kt +++ b/rest/src/main/java/de/markusressel/mkdocsrestclient/MkDocsRestClient.kt @@ -7,6 +7,8 @@ import de.markusressel.mkdocsrestclient.dashboard.DashboardApi import de.markusressel.mkdocsrestclient.dashboard.DashboardApiImpl import de.markusressel.mkdocsrestclient.document.DocumentApi import de.markusressel.mkdocsrestclient.document.DocumentApiImpl +import de.markusressel.mkdocsrestclient.history.HistoryApi +import de.markusressel.mkdocsrestclient.history.HistoryApiImpl import de.markusressel.mkdocsrestclient.mkdocs.MkDocsApi import de.markusressel.mkdocsrestclient.mkdocs.MkDocsApiImpl import de.markusressel.mkdocsrestclient.qr.QrCodeApi @@ -33,6 +35,7 @@ class MkDocsRestClient constructor( referenceApi: ReferenceApi = ReferenceApiImpl(requestManager), dashboardApi: DashboardApi = DashboardApiImpl(requestManager), qrCodeApi: QrCodeApi = QrCodeApiImpl(requestManager), + historyApi: HistoryApi = HistoryApiImpl(requestManager), ) : IMkDocsRestClient, MkDocsApi by mkDocsApi, SectionApi by sectionApi, @@ -40,7 +43,8 @@ class MkDocsRestClient constructor( ResourceApi by resourceApi, ReferenceApi by referenceApi, DashboardApi by dashboardApi, - QrCodeApi by qrCodeApi { + QrCodeApi by qrCodeApi, + HistoryApi by historyApi { override suspend fun isHostAlive(): Result { return requestManager.doStatusRequest("/alive/", Method.GET) diff --git a/rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryApi.kt b/rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryApi.kt new file mode 100644 index 00000000..31480688 --- /dev/null +++ b/rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryApi.kt @@ -0,0 +1,69 @@ +package de.markusressel.mkdocsrestclient.history + +import com.github.kittinunf.fuel.core.FuelError +import com.github.kittinunf.fuel.core.Method +import com.github.kittinunf.result.Result +import com.github.kittinunf.result.map +import de.markusressel.mkdocsrestclient.RequestKind +import de.markusressel.mkdocsrestclient.RequestManager + +/** Names the live text of a document in a diff */ +const val REVISION_CURRENT = "current" + +/** + * The revision history of a document, from the git history of its file. A backend without `git.enabled` answers 404. + */ +interface HistoryApi { + + /** + * @param limit 1 to 1000 + * @return the commits that touched the document, newest first + */ + suspend fun getDocumentHistory(documentId: String, limit: Int = 100): Result, FuelError> + + /** @return the text of the document at [revision] */ + suspend fun getDocumentRevisionContent(documentId: String, revision: String): Result + + /** + * @param from a revision or [REVISION_CURRENT] + * @param to a revision or [REVISION_CURRENT] + * @return a unified diff, empty if both texts are equal + */ + suspend fun getDocumentRevisionDiff( + documentId: String, + from: String, + to: String = REVISION_CURRENT, + ): Result + + /** Sets the live text to the one of [revision], as an edit of the signed in account. Editors and admins only. */ + suspend fun restoreDocumentRevision(documentId: String, revision: String): Result +} + +class HistoryApiImpl( + private val requestManager: RequestManager, +) : HistoryApi { + + override suspend fun getDocumentHistory(documentId: String, limit: Int): Result, FuelError> = + requestManager.doRequest>( + url = "/document/$documentId/history/", + urlParameters = listOf("limit" to limit), + method = Method.GET, + ).map { it.toList() } + + override suspend fun getDocumentRevisionContent(documentId: String, revision: String): Result = + requestManager.doRequest(url = "/document/$documentId/history/$revision/content/", method = Method.GET) + + override suspend fun getDocumentRevisionDiff(documentId: String, from: String, to: String): Result = + requestManager.doRequest( + url = "/document/$documentId/history/diff/", + urlParameters = listOf("from" to from, "to" to to), + method = Method.GET, + ) + + override suspend fun restoreDocumentRevision(documentId: String, revision: String): Result = + requestManager.doRequest( + url = "/document/$documentId/history/$revision/restore/", + method = Method.POST, + kind = RequestKind.LongAction, + ) +} diff --git a/rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryModels.kt b/rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryModels.kt new file mode 100644 index 00000000..44b99fae --- /dev/null +++ b/rest/src/main/java/de/markusressel/mkdocsrestclient/history/HistoryModels.kt @@ -0,0 +1,38 @@ +package de.markusressel.mkdocsrestclient.history + +import com.squareup.moshi.JsonClass +import java.util.Date + +/** + * An author of a commit. The backend sends empty strings, not null, for an author who is not an account, like the + * initial import. + * + * @param username the current username of the account + */ +@JsonClass(generateAdapter = true) +data class HistoryAuthorModel( + val name: String, + val email: String, + val username: String = "", + val accountId: String = "", +) { + val isAccount: Boolean get() = accountId.isNotEmpty() +} + +/** + * A commit that touched a document, from `GET /document/{id}/history/` + * + * @param revision the full commit hash + * @param path the path of the file in that commit, which differs from today's after a rename + * @param appTokens the names of the app tokens (AI agents) the changes were made with + */ +@JsonClass(generateAdapter = true) +data class HistoryEntryModel( + val revision: String, + val time: Date, + val author: HistoryAuthorModel, + val coAuthors: List = emptyList(), + val message: String, + val path: String, + val appTokens: List = emptyList(), +) diff --git a/rest/src/test/java/de/markusressel/mkdocsrestclient/history/HistoryModelsTest.kt b/rest/src/test/java/de/markusressel/mkdocsrestclient/history/HistoryModelsTest.kt new file mode 100644 index 00000000..38b2daa2 --- /dev/null +++ b/rest/src/test/java/de/markusressel/mkdocsrestclient/history/HistoryModelsTest.kt @@ -0,0 +1,77 @@ +package de.markusressel.mkdocsrestclient.history + +import de.markusressel.mkdocsrestclient.toEntity +import java.time.Instant +import java.util.Date +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertTrue + +class HistoryModelsTest { + + /** the answer of a real backend (TestHistory setup in MkDocsEditor-Backend), only the account ids changed */ + private val history = """ + [ + { + "revision": "bfc59905fcb742f8160345f1047b33056386ff17", + "time": "2026-11-14T03:45:33+01:00", + "author": { + "name": "alice", + "email": "alice@mkdocseditor.invalid", + "username": "alice", + "accountId": "a1" + }, + "coAuthors": [ + { + "name": "bob", + "email": "bob@mkdocseditor.invalid", + "username": "bob", + "accountId": "a2" + } + ], + "message": "Update guide/setup.md", + "path": "guide/setup.md", + "appTokens": ["Claude Code"] + }, + { + "revision": "9d8af80923338d9e86ebbdf016f547b96089cc07", + "time": "2026-11-14T03:45:32+01:00", + "author": { + "name": "Test", + "email": "test@example.com", + "username": "", + "accountId": "" + }, + "coAuthors": [], + "message": "Initial", + "path": "guide/setup.md", + "appTokens": [] + } + ] + """.trimIndent() + + @Test + fun `a history of the backend is read with all its fields`() { + val entries = history.toEntity>().toList() + + val update = entries[0] + assertEquals("bfc59905fcb742f8160345f1047b33056386ff17", update.revision) + assertEquals(Date.from(Instant.parse("2026-11-14T02:45:33Z")), update.time) + assertEquals("alice", update.author.username) + assertTrue(update.author.isAccount) + assertEquals(listOf("bob"), update.coAuthors.map { it.username }) + assertEquals(listOf("Claude Code"), update.appTokens) + assertEquals("guide/setup.md", update.path) + } + + @Test + fun `an author who is not an account comes with empty strings`() { + val initial = history.toEntity>()[1] + + assertFalse(initial.author.isAccount) + assertEquals("", initial.author.username) + assertEquals(emptyList(), initial.coAuthors) + assertEquals(emptyList(), initial.appTokens) + } +}