feat(model-client): history interval query for given list of split points

Author: slisson

model-client/src/commonMain/kotlin/org/modelix/model/client2/IModelClientV2.kt

@@ -1,7 +1,7 @@
 package org.modelix.model.client2
 
 import io.ktor.http.Url
-import kotlinx.datetime.Instant
+import org.modelix.datastructures.history.IHistoryQueries
 import org.modelix.datastructures.objects.ObjectHash
 import org.modelix.kotlin.utils.DeprecationInfo
 import org.modelix.model.IVersion
@@ -13,8 +13,6 @@ import org.modelix.model.lazy.BranchReference
 import org.modelix.model.lazy.RepositoryId
 import org.modelix.model.server.api.RepositoryConfig
 import org.modelix.modelql.core.IMonoStep
-import kotlin.time.Duration
-import kotlin.time.Duration.Companion.minutes
 
 /**
  * This interface is meant exclusively for model client usage.
@@ -110,58 +108,5 @@ interface IModelClientV2 {
 
     fun getFrontendUrl(branch: BranchReference): Url
 
-    /**
-     * Splits the history between versions where the time difference is greater or equal to [delay].
-     *
-     * @param headVersion starting point for history computations.
-     * @param timeRange return versions in this time range only
-     * @param delay time between two changes after which it is considered to be a new session
-     */
-    suspend fun getHistorySessions(
-        repositoryId: RepositoryId,
-        headVersion: ObjectHash,
-        timeRange: ClosedRange<Instant>? = null,
-        delay: Duration = 5.minutes,
-    ): List<HistoryInterval>
-
-    /**
-     *
-     * @param headVersion starting point for history computations.
-     * @param timeRange return versions in this time range only
-     * @param interval splits the timeline into equally sized intervals and returns a summary of the contained versions
-     */
-    suspend fun getHistoryIntervals(
-        repositoryId: RepositoryId,
-        headVersion: ObjectHash,
-        timeRange: ClosedRange<Instant>?,
-        interval: Duration,
-    ): List<HistoryInterval>
-
-    /**
-     * A paginated view on the list of all versions in the history sorted by their timestamp. Latest version first.
-     * @param headVersion starting point for history computations. For a paginated view this value should be the same
-     *        and the value for [skip] should be incremented instead. Only then it's guaranteed that the returned list
-     *        is complete.
-     */
-    suspend fun getHistoryRange(
-        repositoryId: RepositoryId,
-        headVersion: ObjectHash,
-        skip: Long = 0L,
-        limit: Long = 1000L,
-    ): List<IVersion>
+    fun queryHistory(repositoryId: RepositoryId, headVersion: ObjectHash): IHistoryQueries
 }
-
-/**
- * A summary of a range of versions.
- */
-data class HistoryInterval(
-    val firstVersionHash: ObjectHash,
-    val lastVersionHash: ObjectHash,
-    /**
-     * Number of versions contained in this interval.
-     */
-    val size: Long,
-    val minTime: Instant,
-    val maxTime: Instant,
-    val authors: Set<String>,
-)

model-client/src/commonMain/kotlin/org/modelix/model/client2/ModelClientV2.kt

@@ -36,9 +36,10 @@ import kotlinx.coroutines.flow.emptyFlow
 import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
-import kotlinx.datetime.Instant
 import mu.KotlinLogging
-import org.modelix.datastructures.model.HistoryIndexNode
+import org.modelix.datastructures.history.HistoryIndexNode
+import org.modelix.datastructures.history.HistoryQueries
+import org.modelix.datastructures.history.IHistoryQueries
 import org.modelix.datastructures.objects.IObjectGraph
 import org.modelix.datastructures.objects.Object
 import org.modelix.datastructures.objects.ObjectHash
@@ -92,8 +93,6 @@ import org.modelix.model.server.api.v2.toMap
 import org.modelix.modelql.client.ModelQLClient
 import org.modelix.modelql.core.IMonoStep
 import org.modelix.streams.IExecutableStream
-import org.modelix.streams.getSuspending
-import org.modelix.streams.iterateSuspending
 import kotlin.time.Duration
 import kotlin.time.Duration.Companion.seconds
 
@@ -333,102 +332,11 @@ class ModelClientV2(
         }
     }
 
-    /**
-     * Splits the history into intervals where the time difference between two versions is less or equal to [delay].
-     */
-    override suspend fun getHistorySessions(
-        repositoryId: RepositoryId,
-        headVersion: ObjectHash,
-        timeRange: ClosedRange<Instant>?,
-        delay: Duration,
-    ): List<HistoryInterval> {
-        val index: Object<HistoryIndexNode> = getHistoryIndex(repositoryId, headVersion)
-        val sessions = ArrayList<HistoryInterval>()
-        var previousMinTime = Instant.fromEpochSeconds(Long.MAX_VALUE)
-
-        // In the worst case two adjacent intervals contain a single entry directly at the border.
-        // The maximum difference between these two entries is less than two times the interval.
-        val interval = delay / 2
-
-        index.data.splitAtInterval(interval, timeRange).iterateSuspending(index.graph) {
-            if (previousMinTime - it.maxTime >= delay) {
-                sessions += HistoryInterval(
-                    firstVersionHash = it.firstVersion.getHash(),
-                    lastVersionHash = it.lastVersion.getHash(),
-                    size = it.size,
-                    minTime = it.minTime,
-                    maxTime = it.maxTime,
-                    authors = it.authors,
-                )
-            } else {
-                val entry = sessions[sessions.lastIndex]
-                sessions[sessions.lastIndex] = HistoryInterval(
-                    firstVersionHash = it.firstVersion.getHash(),
-                    lastVersionHash = entry.lastVersionHash,
-                    size = entry.size + it.size,
-                    minTime = minOf(entry.minTime, it.minTime),
-                    maxTime = maxOf(entry.maxTime, it.maxTime),
-                    authors = entry.authors + it.authors,
-                )
-            }
-            previousMinTime = it.minTime
-        }
-
-        return sessions
-    }
-
-    override suspend fun getHistoryIntervals(
-        repositoryId: RepositoryId,
-        headVersion: ObjectHash,
-        timeRange: ClosedRange<Instant>?,
-        interval: Duration,
-    ): List<HistoryInterval> {
-        val index: Object<HistoryIndexNode> = getHistoryIndex(repositoryId, headVersion)
-        val mergedEntries = ArrayList<HistoryInterval>()
-        var previousIntervalId: Long = Long.MAX_VALUE
-
-        index.data.splitAtInterval(interval, timeRange).iterateSuspending(index.graph) {
-            val intervalId = it.maxTime.epochSeconds / interval.inWholeSeconds
-            check(intervalId <= previousIntervalId)
-            if (intervalId == previousIntervalId) {
-                val entry = mergedEntries[mergedEntries.lastIndex]
-                mergedEntries[mergedEntries.lastIndex] = HistoryInterval(
-                    firstVersionHash = it.firstVersion.getHash(),
-                    lastVersionHash = entry.lastVersionHash,
-                    size = entry.size + it.size,
-                    minTime = minOf(entry.minTime, it.minTime),
-                    maxTime = maxOf(entry.maxTime, it.maxTime),
-                    authors = entry.authors + it.authors,
-                )
-            } else {
-                previousIntervalId = intervalId
-                mergedEntries += HistoryInterval(
-                    firstVersionHash = it.firstVersion.getHash(),
-                    lastVersionHash = it.lastVersion.getHash(),
-                    size = it.size,
-                    minTime = it.minTime,
-                    maxTime = it.maxTime,
-                    authors = it.authors,
-                )
-            }
-        }
-
-        return mergedEntries
-    }
-
-    override suspend fun getHistoryRange(
+    override fun queryHistory(
         repositoryId: RepositoryId,
         headVersion: ObjectHash,
-        skip: Long,
-        limit: Long,
-    ): List<IVersion> {
-        val index: Object<HistoryIndexNode> = getHistoryIndex(repositoryId, headVersion)
-        return index.data.getRange(skip until (limit + skip))
-            .flatMapOrdered { it.getAllVersionsReversed() }
-            .flatMapOrdered { it.resolve() }
-            .map { CLVersion(it) }
-            .toList()
-            .getSuspending(index.graph)
+    ): IHistoryQueries {
+        return HistoryQueries { getHistoryIndex(repositoryId, headVersion) }
     }
 
     suspend fun getHistoryIndex(

model-client/src/jsMain/kotlin/org/modelix/model/client2/ClientJS.kt

@@ -205,9 +205,10 @@ internal class ClientJSImpl(private val modelClient: ModelClientV2) : ClientJS {
 
     override fun getHistoryRange(repositoryId: String, headVersion: String, skip: Int, limit: Int) =
         GlobalScope.promise {
-            modelClient.getHistoryRange(
+            modelClient.queryHistory(
                 RepositoryId(repositoryId),
                 ObjectHash(headVersion),
+            ).range(
                 skip.toLong(),
                 limit.toLong(),
             )

model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/history/EquidistantIntervalsSpec.kt

@@ -0,0 +1,14 @@
+package org.modelix.datastructures.history
+
+import kotlinx.datetime.Instant
+import kotlin.time.Duration
+
+class EquidistantIntervalsSpec(val duration: Duration) : IntervalsSpec {
+    override fun getIntervalIndex(time: Instant): Long {
+        return time.epochSeconds / duration.inWholeSeconds
+    }
+
+    override fun includes(time: Instant): Boolean = true
+
+    override fun intersects(range: ClosedRange<Instant>): Boolean = true
+}

model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/model/HistoryIndexNode.kt renamed to model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/history/HistoryIndexNode.kt

@@ -1,4 +1,4 @@
-package org.modelix.datastructures.model
+package org.modelix.datastructures.history
 
 import kotlinx.datetime.Instant
 import org.modelix.datastructures.objects.IObjectData
@@ -23,7 +23,6 @@ import org.modelix.streams.plus
 import kotlin.math.abs
 import kotlin.math.max
 import kotlin.math.min
-import kotlin.time.Duration
 
 sealed class HistoryIndexNode : IObjectData {
     abstract val firstVersion: ObjectReference<CPVersion>
@@ -46,7 +45,7 @@ sealed class HistoryIndexNode : IObjectData {
      * For the same interval multiple nodes may be returned.
      * Latest entry is returned first.
      */
-    abstract fun splitAtInterval(interval: Duration, timeRangeFilter: ClosedRange<Instant>?): IStream.Many<HistoryIndexNode>
+    abstract fun splitAtInterval(intervalSpec: IntervalsSpec): IStream.Many<HistoryIndexNode>
 
     fun concat(
         self: Object<HistoryIndexNode>,
@@ -213,8 +212,8 @@ data class HistoryIndexLeafNode(
         }
     }
 
-    override fun splitAtInterval(interval: Duration, timeRangeFilter: ClosedRange<Instant>?): IStream.Many<HistoryIndexNode> {
-        return if (timeRangeFilter == null || timeRangeFilter.contains(time)) IStream.of(this) else IStream.empty()
+    override fun splitAtInterval(intervalSpec: IntervalsSpec): IStream.Many<HistoryIndexNode> {
+        return if (intervalSpec.includes(time)) IStream.of(this) else IStream.empty()
     }
 }
 
@@ -335,17 +334,17 @@ data class HistoryIndexRangeNode(
         }.flatten()
     }
 
-    override fun splitAtInterval(interval: Duration, timeRangeFilter: ClosedRange<Instant>?): IStream.Many<HistoryIndexNode> {
-        if (timeRangeFilter != null && !timeRangeFilter.intersects(timeRange)) return IStream.empty()
+    override fun splitAtInterval(intervalSpec: IntervalsSpec): IStream.Many<HistoryIndexNode> {
+        if (!intervalSpec.intersects(timeRange)) return IStream.empty()
 
-        val intervalIndex1 = timeRange.start.epochSeconds / interval.inWholeSeconds
-        val intervalIndex2 = timeRange.endInclusive.epochSeconds / interval.inWholeSeconds
-        if (intervalIndex1 == intervalIndex2) {
+        val intervalIndex1 = intervalSpec.getIntervalIndex(timeRange.start)
+        val intervalIndex2 = intervalSpec.getIntervalIndex(timeRange.endInclusive)
+        if (intervalIndex1 == intervalIndex2 && intervalIndex1 >= 0) {
             return IStream.of(this)
         } else {
             return IStream.of(child2, child1)
                 .flatMapOrdered { it.resolve() }
-                .flatMapOrdered { it.data.splitAtInterval(interval, timeRangeFilter) }
+                .flatMapOrdered { it.data.splitAtInterval(intervalSpec) }
         }
     }
 
@@ -396,7 +395,7 @@ data class HistoryIndexRangeNode(
 }
 
 private fun LongRange.shift(amount: Long) = first.plus(amount)..last.plus(amount)
-private fun <T : Comparable<T>> ClosedRange<T>.intersects(other: ClosedRange<T>): Boolean {
+fun <T : Comparable<T>> ClosedRange<T>.intersects(other: ClosedRange<T>): Boolean {
     return this.contains(other.start) || this.contains(other.endInclusive) ||
         other.contains(this.start) || other.contains(this.endInclusive)
 }

model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/history/HistoryInterval.kt

@@ -0,0 +1,19 @@
+package org.modelix.datastructures.history
+
+import kotlinx.datetime.Instant
+import org.modelix.datastructures.objects.ObjectHash
+
+/**
+ * A summary of a range of versions.
+ */
+data class HistoryInterval(
+    val firstVersionHash: ObjectHash,
+    val lastVersionHash: ObjectHash,
+    /**
+     * Number of versions contained in this interval.
+     */
+    val size: Long,
+    val minTime: Instant,
+    val maxTime: Instant,
+    val authors: Set<String>,
+)