Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

feat(kafka): let the message browser start reading at a time

弈秋8cdfb89296c8
diff --git a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java b/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java
index b3aaa844bd..b389d052dd 100644
--- a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java
+++ b/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java
@@ -1635,7 +1635,8 @@ public final class KafkaAgent {
int count = validatedPeekCount(intOrDefault(params, "count", 10));
PeekStartPosition startPosition = peekStartPosition(params);
boolean explicitStartPosition = stringOrNull(params, "startPosition") != null;
- validatePeekRequest(startPosition, explicitStartPosition, partition, offset);
+ Long startTimestamp = longOrNull(params, "timestamp");
+ validatePeekRequest(startPosition, explicitStartPosition, partition, offset, startTimestamp);
boolean legacyOffsetRequest = !explicitStartPosition && offset != null;
JsonObject conn = activeConnection;
@@ -1658,14 +1659,25 @@ public final class KafkaAgent {
Map<TopicPartition, Long> endOffsets =
consumer.endOffsets(candidatePartitions, requestTimeout);
+ Map<TopicPartition, Long> timestampOffsets = Collections.emptyMap();
+ if (startPosition == PeekStartPosition.TIMESTAMP) {
+ Map<TopicPartition, Long> byTime = new LinkedHashMap<>();
+ for (TopicPartition tp : candidatePartitions) {
+ byTime.put(tp, startTimestamp);
+ }
+ timestampOffsets = peekTimestampOffsets(consumer.offsetsForTimes(byTime, requestTimeout));
+ }
+
List<TopicPartition> readablePartitions = new ArrayList<>();
Map<TopicPartition, Long> seekOffsets = new LinkedHashMap<>();
for (TopicPartition tp : candidatePartitions) {
long beginningOffset = beginningOffsets.getOrDefault(tp, 0L);
long endOffset = endOffsets.getOrDefault(tp, beginningOffset);
- Long requestedOffset = requestedPeekOffset(
- startPosition, offset, legacyOffsetRequest, beginningOffset, endOffset
- );
+ Long requestedOffset = startPosition == PeekStartPosition.TIMESTAMP
+ ? timestampOffsets.get(tp)
+ : requestedPeekOffset(
+ startPosition, offset, legacyOffsetRequest, beginningOffset, endOffset
+ );
if (requestedOffset == null) {
continue;
}
@@ -2147,6 +2159,7 @@ public final class KafkaAgent {
EARLIEST,
LATEST,
OFFSET,
+ TIMESTAMP,
}
/** Omitting startPosition preserves the old earliest default (or explicit legacy offset) behavior. */
@@ -2159,16 +2172,47 @@ public final class KafkaAgent {
case "earliest" -> PeekStartPosition.EARLIEST;
case "latest" -> PeekStartPosition.LATEST;
case "offset" -> PeekStartPosition.OFFSET;
+ case "timestamp" -> PeekStartPosition.TIMESTAMP;
default -> throw new IllegalArgumentException("Unsupported peek startPosition: " + value);
};
}
+ /**
+ * First offset whose batch timestamp is &gt;= {@code timestamp}, per partition. Kafka
+ * answers null for a partition whose newest record is older than the requested time;
+ * that partition is simply left out of the read rather than silently falling back to
+ * its tail, so a time window never shows data from outside itself.
+ */
+ static Map<TopicPartition, Long> peekTimestampOffsets(
+ Map<TopicPartition, OffsetAndTimestamp> located
+ ) {
+ Map<TopicPartition, Long> resolved = new LinkedHashMap<>();
+ located.forEach((tp, offsetAndTimestamp) -> {
+ if (offsetAndTimestamp != null) {
+ resolved.put(tp, offsetAndTimestamp.offset());
+ }
+ });
+ return resolved;
+ }
+
static void validatePeekRequest(
PeekStartPosition startPosition,
boolean explicitStartPosition,
Integer partition,
- Long offset
+ Long offset,
+ Long timestamp
) {
+ if (startPosition != PeekStartPosition.TIMESTAMP && timestamp != null) {
+ throw new IllegalArgumentException("timestamp is only supported when startPosition is timestamp");
+ }
+ if (startPosition == PeekStartPosition.TIMESTAMP) {
+ if (timestamp == null) {
+ throw new IllegalArgumentException("timestamp is required when startPosition is timestamp");
+ }
+ if (timestamp < 0) {
+ throw new IllegalArgumentException("timestamp must be a non-negative epoch millisecond value");
+ }
+ }
if (partition != null && partition < 0) {
throw new IllegalArgumentException("partition must be non-negative");
}
@@ -2203,6 +2247,8 @@ public final class KafkaAgent {
return switch (startPosition) {
case LATEST -> endOffset > beginningOffset ? beginningOffset : null;
case OFFSET -> offset;
+ // Resolved per partition through offsetsForTimes before this is reached.
+ case TIMESTAMP -> null;
case EARLIEST -> legacyOffsetRequest ? offset : beginningOffset;
};
}
diff --git a/agents/drivers/kafka/src/test/java/com/dbx/agent/kafka/KafkaAgentTest.java b/agents/drivers/kafka/src/test/java/com/dbx/agent/kafka/KafkaAgentTest.java
index 0507f4b628..aba0408099 100644
--- a/agents/drivers/kafka/src/test/java/com/dbx/agent/kafka/KafkaAgentTest.java
+++ b/agents/drivers/kafka/src/test/java/com/dbx/agent/kafka/KafkaAgentTest.java
@@ -39,6 +39,8 @@ import javax.net.ssl.X509TrustManager;
import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.apache.kafka.clients.consumer.ConsumerRecords;
import org.apache.kafka.clients.consumer.OffsetAndMetadata;
+import org.apache.kafka.clients.consumer.OffsetAndTimestamp;
+import java.util.LinkedHashMap;
import org.apache.kafka.clients.producer.ProducerConfig;
import org.apache.kafka.clients.admin.AlterConfigOp;
import org.apache.kafka.clients.admin.Admin;
@@ -948,21 +950,21 @@ class KafkaAgentTest {
@Test
void offsetStartPositionAllowsAllPartitionsButRequiresANonNegativeOffset() {
assertDoesNotThrow(() ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, null, 0L));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, null, 0L, null));
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, 0, null));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, 0, null, null));
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, -1, 0L));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, -1, 0L, null));
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, 0, -1L));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.OFFSET, true, 0, -1L, null));
}
@Test
void nonOffsetStartPositionsRejectAnOffset() {
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.LATEST, true, 0, 7L));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.LATEST, true, 0, 7L, null));
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.EARLIEST, true, 0, 7L));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.EARLIEST, true, 0, 7L, null));
}
@Test
@@ -975,14 +977,14 @@ class KafkaAgentTest {
@Test
void everyStartPositionRejectsNegativePartitions() {
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.LATEST, true, -1, null));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.LATEST, true, -1, null, null));
assertThrows(IllegalArgumentException.class, () ->
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.EARLIEST, true, -1, null));
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.EARLIEST, true, -1, null, null));
}
@Test
void legacyOffsetWithoutStartPositionKeepsTheExistingReadBehavior() {
- KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.EARLIEST, false, null, 7L);
+ KafkaAgent.validatePeekRequest(KafkaAgent.PeekStartPosition.EARLIEST, false, null, 7L, null);
assertEquals(7L, KafkaAgent.requestedPeekOffset(
KafkaAgent.PeekStartPosition.EARLIEST, 7L, true, 0L, 10L
));
@@ -1671,4 +1673,36 @@ class KafkaAgentTest {
}
}
}
+
+ @Test
+ void peekAcceptsTimestampStartPosition() {
+ assertEquals(
+ KafkaAgent.PeekStartPosition.TIMESTAMP,
+ KafkaAgent.peekStartPosition(JsonParser.parseString("{\"startPosition\":\"timestamp\"}").getAsJsonObject())
+ );
+ assertDoesNotThrow(() -> KafkaAgent.validatePeekRequest(
+ KafkaAgent.PeekStartPosition.TIMESTAMP, true, null, null, 1_700_000_000_000L));
+ assertThrows(IllegalArgumentException.class, () -> KafkaAgent.validatePeekRequest(
+ KafkaAgent.PeekStartPosition.TIMESTAMP, true, null, null, null));
+ assertThrows(IllegalArgumentException.class, () -> KafkaAgent.validatePeekRequest(
+ KafkaAgent.PeekStartPosition.TIMESTAMP, true, null, null, -1L));
+ assertThrows(IllegalArgumentException.class, () -> KafkaAgent.validatePeekRequest(
+ KafkaAgent.PeekStartPosition.EARLIEST, true, null, null, 1_700_000_000_000L));
+ }
+
+ @Test
+ void peekTimestampOffsetsDropsPartitionsWithoutAMatch() {
+ // Kafka answers null for a partition whose newest record is older than the requested
+ // time. Dropping it keeps a time window from silently showing data from outside itself.
+ TopicPartition withData = new TopicPartition("t", 0);
+ TopicPartition tooOld = new TopicPartition("t", 1);
+ Map<TopicPartition, OffsetAndTimestamp> located = new LinkedHashMap<>();
+ located.put(withData, new OffsetAndTimestamp(42L, 1_700_000_000_000L));
+ located.put(tooOld, null);
+
+ Map<TopicPartition, Long> resolved = KafkaAgent.peekTimestampOffsets(located);
+
+ assertEquals(42L, resolved.get(withData));
+ assertFalse(resolved.containsKey(tooOld));
+ }
}
diff --git a/apps/desktop/src/components/mq/MessageBrowser.vue b/apps/desktop/src/components/mq/MessageBrowser.vue
index 447674b16e..559d036b4c 100644
--- a/apps/desktop/src/components/mq/MessageBrowser.vue
+++ b/apps/desktop/src/components/mq/MessageBrowser.vue
@@ -41,11 +41,13 @@ const advancedExpanded = ref(false);
const messageSearchQuery = ref("");
type KafkaPeekStartPosition = NonNullable<PeekMessagesOptions["startPosition"]>;
const kafkaStartPosition = ref<KafkaPeekStartPosition>("latest");
+const kafkaStartTimestamp = ref("");
const kafkaMessageDisplayOrder = ref<KafkaMessageDisplayOrder>("newest");
let messageRequestVersion = 0;
const isKafka = computed(() => props.mqSystemKind === "kafka");
const isKafkaOffsetMode = computed(() => kafkaStartPosition.value === "offset");
+const isKafkaTimestampMode = computed(() => kafkaStartPosition.value === "timestamp");
const isMonitoring = computed(() => props.appearance === "monitoring");
const normalizedMessageSearchQuery = computed(() => normalizeKafkaMessageSearchQuery(messageSearchQuery.value));
const searchableMessages = computed(() =>
@@ -95,6 +97,11 @@ async function loadMessages() {
options.offset = parsedOffset;
offset.value = String(parsedOffset);
}
+ if (isKafkaTimestampMode.value) {
+ const parsedTime = Date.parse(String(kafkaStartTimestamp.value));
+ if (!Number.isFinite(parsedTime)) throw new Error(t("mqMessages.timestampRequired"));
+ options.timestamp = parsedTime;
+ }
} else {
if (partitionText !== "") {
const parsedPartition = parseNonNegativeSafeInteger(partitionText);
@@ -223,9 +230,14 @@ watch(kafkaStartPosition, () => {
<SelectItem value="latest">{{ t("mqMessages.kafkaLatest") }}</SelectItem>
<SelectItem value="earliest">{{ t("mqMessages.kafkaEarliest") }}</SelectItem>
<SelectItem value="offset">{{ t("mqMessages.kafkaOffset") }}</SelectItem>
+ <SelectItem value="timestamp">{{ t("mqMessages.kafkaTimestamp") }}</SelectItem>
</SelectContent>
</Select>
</label>
+ <label v-if="isKafka && isKafkaTimestampMode && !isMonitoring">
+ <span>{{ t("mqMessages.startTimestamp") }}</span>
+ <input v-model="kafkaStartTimestamp" data-testid="kafka-peek-start-timestamp" type="datetime-local" step="1" :disabled="loading" />
+ </label>
<label v-if="isKafka">
<span>{{ t("mqMessages.timeOrder") }}</span>
<Select v-model="kafkaMessageDisplayOrder">
diff --git a/apps/desktop/src/i18n/locales/az.ts b/apps/desktop/src/i18n/locales/az.ts
index faa8118487..77602d0e1b 100644
--- a/apps/desktop/src/i18n/locales/az.ts
+++ b/apps/desktop/src/i18n/locales/az.ts
@@ -9626,6 +9626,9 @@ export default withEnglishFallback({
kafkaLatest: "Son N mesaj (standart)",
kafkaEarliest: "Ən erkən mesajlar",
kafkaOffset: "Sürüşmədən başlayaraq",
+ kafkaTimestamp: "Vaxtdan oxu",
+ startTimestamp: "Başlanğıc vaxtı",
+ timestampRequired: "Bir başlanğıc vaxtı seçin və ya başqa başlanğıc mövqe göstərin.",
timeOrder: "Vaxta görə sıralama",
newestFirst: "Əvvəlcə ən yenilər",
oldestFirst: "Əvvəlcə ən köhnələr",
diff --git a/apps/desktop/src/i18n/locales/en.ts b/apps/desktop/src/i18n/locales/en.ts
index c190ac1249..b069805d14 100644
--- a/apps/desktop/src/i18n/locales/en.ts
+++ b/apps/desktop/src/i18n/locales/en.ts
@@ -11688,6 +11688,9 @@ export default {
kafkaLatest: "Recent N messages (default)",
kafkaEarliest: "Earliest messages",
kafkaOffset: "From offset",
+ kafkaTimestamp: "From time",
+ startTimestamp: "Start time",
+ timestampRequired: "Choose a start time, or pick another start position.",
timeOrder: "Time order",
newestFirst: "Newest first",
oldestFirst: "Oldest first",
diff --git a/apps/desktop/src/i18n/locales/es.ts b/apps/desktop/src/i18n/locales/es.ts
index 01029d230c..4e0dd931d4 100644
--- a/apps/desktop/src/i18n/locales/es.ts
+++ b/apps/desktop/src/i18n/locales/es.ts
@@ -10917,6 +10917,9 @@ export default withEnglishFallback({
kafkaLatest: "Últimos N mensajes (predeterminado)",
kafkaEarliest: "Mensajes más antiguos",
kafkaOffset: "Desde offset",
+ kafkaTimestamp: "Desde la hora",
+ startTimestamp: "Hora de inicio",
+ timestampRequired: "Elige una hora de inicio u otra posición inicial.",
timeOrder: "Orden temporal",
newestFirst: "Más recientes primero",
oldestFirst: "Más antiguos primero",
diff --git a/apps/desktop/src/i18n/locales/id.ts b/apps/desktop/src/i18n/locales/id.ts
index 2de375dba3..55048c1d16 100644
--- a/apps/desktop/src/i18n/locales/id.ts
+++ b/apps/desktop/src/i18n/locales/id.ts
@@ -10467,6 +10467,9 @@ export default withEnglishFallback({
kafkaLatest: "N pesan terbaru (default)",
kafkaEarliest: "Pesan paling awal",
kafkaOffset: "Dari offset",
+ kafkaTimestamp: "Dari waktu",
+ startTimestamp: "Waktu mulai",
+ timestampRequired: "Pilih waktu mulai atau posisi mulai lain.",
timeOrder: "Urutan waktu",
newestFirst: "Terbaru lebih dulu",
oldestFirst: "Terlama lebih dulu",
diff --git a/apps/desktop/src/i18n/locales/it.ts b/apps/desktop/src/i18n/locales/it.ts
index e0bda17f7a..8967c9c6e0 100644
--- a/apps/desktop/src/i18n/locales/it.ts
+++ b/apps/desktop/src/i18n/locales/it.ts
@@ -10665,6 +10665,9 @@ export default withEnglishFallback({
kafkaLatest: "Ultimi N messaggi (predefinito)",
kafkaEarliest: "Primi messaggi",
kafkaOffset: "Da offset",
+ kafkaTimestamp: "Dall’ora",
+ startTimestamp: "Ora di inizio",
+ timestampRequired: "Scegli un’ora di inizio o un’altra posizione iniziale.",
timeOrder: "Ordine temporale",
newestFirst: "Più recenti prima",
oldestFirst: "Meno recenti prima",
diff --git a/apps/desktop/src/i18n/locales/ja.ts b/apps/desktop/src/i18n/locales/ja.ts
index 40577d6942..cf5d7bfd1c 100644
--- a/apps/desktop/src/i18n/locales/ja.ts
+++ b/apps/desktop/src/i18n/locales/ja.ts
@@ -10701,6 +10701,9 @@ export default withEnglishFallback({
kafkaLatest: "最新 N 件(デフォルト)",
kafkaEarliest: "最も古いメッセージ",
kafkaOffset: "Offset から読み取る",
+ kafkaTimestamp: "時刻から読み取り",
+ startTimestamp: "開始時刻",
+ timestampRequired: "開始時刻を選択するか、別の開始位置を選んでください。",
timeOrder: "時刻順",
newestFirst: "新しい順",
oldestFirst: "古い順",
diff --git a/apps/desktop/src/i18n/locales/ko.ts b/apps/desktop/src/i18n/locales/ko.ts
index ddf678e7e9..8cb3278c11 100644
--- a/apps/desktop/src/i18n/locales/ko.ts
+++ b/apps/desktop/src/i18n/locales/ko.ts
@@ -10385,6 +10385,9 @@ export default withEnglishFallback({
kafkaLatest: "최근 N개 메시지(기본값)",
kafkaEarliest: "가장 이른 메시지",
kafkaOffset: "오프셋부터 읽기",
+ kafkaTimestamp: "시각부터 읽기",
+ startTimestamp: "시작 시각",
+ timestampRequired: "시작 시각을 선택하거나 다른 시작 위치를 지정하세요.",
timeOrder: "시간 순서",
newestFirst: "최신순",
oldestFirst: "오래된순",
diff --git a/apps/desktop/src/i18n/locales/pt-BR.ts b/apps/desktop/src/i18n/locales/pt-BR.ts
index ba5bc24b6b..938d276782 100644
--- a/apps/desktop/src/i18n/locales/pt-BR.ts
+++ b/apps/desktop/src/i18n/locales/pt-BR.ts
@@ -10661,6 +10661,9 @@ export default withEnglishFallback({
kafkaLatest: "Últimas N mensagens (padrão)",
kafkaEarliest: "Mensagens mais antigas",
kafkaOffset: "A partir do offset",
+ kafkaTimestamp: "Do horário",
+ startTimestamp: "Horário de início",
+ timestampRequired: "Escolha um horário de início ou outra posição inicial.",
timeOrder: "Ordem temporal",
newestFirst: "Mais recentes primeiro",
oldestFirst: "Mais antigas primeiro",
diff --git a/apps/desktop/src/i18n/locales/ru.ts b/apps/desktop/src/i18n/locales/ru.ts
index 6768af4138..f3162bd8ad 100644
--- a/apps/desktop/src/i18n/locales/ru.ts
+++ b/apps/desktop/src/i18n/locales/ru.ts
@@ -11881,6 +11881,9 @@ export default withEnglishFallback({
kafkaLatest: "Последние N сообщений (по умолчанию)",
kafkaEarliest: "Самые ранние сообщения",
kafkaOffset: "С указанного смещения",
+ kafkaTimestamp: "С времени",
+ startTimestamp: "Время начала",
+ timestampRequired: "Выберите время начала или другую стартовую позицию.",
timeOrder: "Порядок по времени",
newestFirst: "Сначала новые",
oldestFirst: "Сначала старые",
diff --git a/apps/desktop/src/i18n/locales/th.ts b/apps/desktop/src/i18n/locales/th.ts
index 232747dd2b..3a84aedcf1 100644
--- a/apps/desktop/src/i18n/locales/th.ts
+++ b/apps/desktop/src/i18n/locales/th.ts
@@ -12262,6 +12262,9 @@ export default withEnglishFallback({
kafkaLatest: "ข้อความ N รายการล่าสุด (ค่าเริ่มต้น)",
kafkaEarliest: "ข้อความแรกสุด",
kafkaOffset: "จาก Offset",
+ kafkaTimestamp: "จากเวลา",
+ startTimestamp: "เวลาเริ่มต้น",
+ timestampRequired: "เลือกเวลาเริ่มต้น หรือเลือกตำแหน่งเริ่มอื่น",
timeOrder: "ลำดับเวลา",
newestFirst: "ใหม่สุดก่อน",
oldestFirst: "เก่าสุดก่อน",
diff --git a/apps/desktop/src/i18n/locales/tr.ts b/apps/desktop/src/i18n/locales/tr.ts
index 1711afee34..a0487686f6 100644
--- a/apps/desktop/src/i18n/locales/tr.ts
+++ b/apps/desktop/src/i18n/locales/tr.ts
@@ -9510,6 +9510,9 @@ export default withEnglishFallback({
kafkaLatest: "Son N mesaj (varsayılan)",
kafkaEarliest: "En eski mesajlar",
kafkaOffset: "Konumdan itibaren",
+ kafkaTimestamp: "Saatten oku",
+ startTimestamp: "Başlangıç zamanı",
+ timestampRequired: "Bir başlangıç zamanı seçin veya başka bir başlangıç konumu belirleyin.",
timeOrder: "Zaman sırası",
newestFirst: "Önce en yeni",
oldestFirst: "Önce en eski",
diff --git a/apps/desktop/src/i18n/locales/zh-CN.ts b/apps/desktop/src/i18n/locales/zh-CN.ts
index 4b37d9db86..1b18311bee 100644
--- a/apps/desktop/src/i18n/locales/zh-CN.ts
+++ b/apps/desktop/src/i18n/locales/zh-CN.ts
@@ -11651,6 +11651,9 @@ export default withEnglishFallback({
kafkaLatest: "最近 N 条(默认)",
kafkaEarliest: "最早消息",
kafkaOffset: "从指定 Offset 读取",
+ kafkaTimestamp: "从指定时间读取",
+ startTimestamp: "起始时间",
+ timestampRequired: "请选择起始时间,或改用其他起始位置。",
timeOrder: "时间顺序",
newestFirst: "最新优先",
oldestFirst: "最早优先",
diff --git a/apps/desktop/src/i18n/locales/zh-TW.ts b/apps/desktop/src/i18n/locales/zh-TW.ts
index c950a96bce..6921dd9d6d 100644
--- a/apps/desktop/src/i18n/locales/zh-TW.ts
+++ b/apps/desktop/src/i18n/locales/zh-TW.ts
@@ -10670,6 +10670,9 @@ export default withEnglishFallback({
kafkaLatest: "最近 N 則(預設)",
kafkaEarliest: "最早訊息",
kafkaOffset: "從指定 Offset 讀取",
+ kafkaTimestamp: "從指定時間讀取",
+ startTimestamp: "起始時間",
+ timestampRequired: "請選擇起始時間,或改用其他起始位置。",
timeOrder: "時間順序",
newestFirst: "最新優先",
oldestFirst: "最早優先",
diff --git a/apps/desktop/src/types/mq.ts b/apps/desktop/src/types/mq.ts
index 818d635836..510b7f8328 100644
--- a/apps/desktop/src/types/mq.ts
+++ b/apps/desktop/src/types/mq.ts
@@ -365,7 +365,9 @@ export interface PeekMessagesResult {
export interface PeekMessagesOptions {
/** Kafka only. Omitted starts at earliest unless a legacy caller supplies offset. */
- startPosition?: "latest" | "earliest" | "offset";
+ startPosition?: "latest" | "earliest" | "offset" | "timestamp";
+ /** Epoch milliseconds; Kafka resolves the first record batch at or after this time per partition. */
+ timestamp?: number;
partition?: number;
offset?: number;
}
diff --git a/crates/dbx-core/src/admin/mq/adapters/kafka.rs b/crates/dbx-core/src/admin/mq/adapters/kafka.rs
index e7998cf47b..c6536bf8e0 100644
--- a/crates/dbx-core/src/admin/mq/adapters/kafka.rs
+++ b/crates/dbx-core/src/admin/mq/adapters/kafka.rs
@@ -688,6 +688,9 @@ fn peek_messages_params(
if let Some(offset) = options.offset {
params["offset"] = serde_json::json!(offset);
}
+ if let Some(timestamp) = options.timestamp {
+ params["timestamp"] = serde_json::json!(timestamp);
+ }
params
}
@@ -903,6 +906,7 @@ mod tests {
start_position: Some(PeekStartPosition::Offset),
partition: Some(2),
offset: Some(17),
+ timestamp: None,
},
);
@@ -984,7 +988,7 @@ mod tests {
&cfg,
&topic_ref(),
20,
- PeekMessagesOptions { start_position: None, partition: None, offset: Some(17) },
+ PeekMessagesOptions { start_position: None, partition: None, offset: Some(17), timestamp: None },
);
assert!(params.get("startPosition").is_none());
diff --git a/crates/dbx-core/src/admin/mq/types.rs b/crates/dbx-core/src/admin/mq/types.rs
index d291044824..c941872a6d 100644
--- a/crates/dbx-core/src/admin/mq/types.rs
+++ b/crates/dbx-core/src/admin/mq/types.rs
@@ -858,6 +858,7 @@ pub enum PeekStartPosition {
Latest,
Earliest,
Offset,
+ Timestamp,
}
/// Optional hints for reading messages. Non-Kafka adapters ignore
@@ -866,6 +867,8 @@ pub enum PeekStartPosition {
/// earliest available message unless an older caller supplies `offset`.
/// `start_position: Offset` requires a non-negative offset. When no partition
/// is supplied, Kafka reads forward from that offset in every topic partition.
+/// `start_position: Timestamp` requires a non-negative epoch-millisecond
+/// `timestamp` and reads from the first record at or after it.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PeekMessagesOptions {
@@ -877,6 +880,10 @@ pub struct PeekMessagesOptions {
pub partition: Option<i32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub offset: Option<i64>,
+ /// Epoch milliseconds; used only with `start_position: Timestamp`, where
+ /// the agent resolves the first offset at or after this time per partition.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub timestamp: Option<i64>,
}
// ---------------------------------------------------------------------------
@@ -1595,6 +1602,32 @@ mod tests {
assert_eq!(json.get("startPosition").and_then(|value| value.as_str()), Some("latest"));
}
+ #[test]
+ fn peek_options_round_trip_timestamp_start_position() {
+ let timestamp: super::PeekMessagesOptions =
+ serde_json::from_str(r#"{"startPosition":"timestamp","timestamp":1700000000000}"#)
+ .expect("timestamp peek options");
+ assert_eq!(timestamp.start_position, Some(super::PeekStartPosition::Timestamp));
+ assert_eq!(timestamp.timestamp, Some(1_700_000_000_000));
+ let json = serde_json::to_value(&timestamp).expect("serialize timestamp peek options");
+ assert_eq!(json.get("startPosition").and_then(|value| value.as_str()), Some("timestamp"));
+ assert_eq!(json.get("timestamp").and_then(|value| value.as_i64()), Some(1_700_000_000_000));
+
+ // Every other start position still parses and carries no timestamp.
+ let earliest: super::PeekMessagesOptions =
+ serde_json::from_str(r#"{"startPosition":"earliest"}"#).expect("earliest peek options");
+ assert_eq!(earliest.start_position, Some(super::PeekStartPosition::Earliest));
+ assert_eq!(earliest.timestamp, None);
+
+ // Requests without a timestamp keep omitting the field, and unknown
+ // start positions still fail here instead of reaching the agent.
+ let legacy: super::PeekMessagesOptions =
+ serde_json::from_str(r#"{"partition":1}"#).expect("legacy peek options");
+ let json = serde_json::to_value(&legacy).expect("serialize legacy peek options");
+ assert!(json.get("timestamp").is_none());
+ assert!(serde_json::from_str::<super::PeekMessagesOptions>(r#"{"startPosition":"whenever"}"#).is_err());
+ }
+
#[test]
fn peek_result_serializes_completion_status_and_accepts_legacy_responses() {
let complete = super::PeekMessagesResult::complete(Vec::new());
diff --git a/crates/dbx-mcp/src/backend.rs b/crates/dbx-mcp/src/backend.rs
index 7043e38163..bc500f89ab 100644
--- a/crates/dbx-mcp/src/backend.rs
+++ b/crates/dbx-mcp/src/backend.rs
@@ -3644,6 +3644,7 @@ mod tests {
start_position: Some(PeekStartPosition::Offset),
partition: Some(2),
offset: Some(17),
+ timestamp: None,
},
)
.await
diff --git a/crates/dbx-mcp/src/server.rs b/crates/dbx-mcp/src/server.rs
index 4aae8662c5..cb407faf46 100644
--- a/crates/dbx-mcp/src/server.rs
+++ b/crates/dbx-mcp/src/server.rs
@@ -2618,6 +2618,7 @@ impl DbxMcpServer {
start_position: Some(start_position),
partition: request.partition,
offset: request.offset,
+ timestamp: None,
};
match self.backend.peek_messages(&resolved.connection, topic, count, options).await {
Ok(result) => text(format_peek_messages_result(result, count as usize)),