feat(etcd): add key TTL synchronization

This commit is contained in:
二丫讲梵 authored and GitHub committed 2026-07-26 11:55:52 +08:00
1 parent 43f73ca4ca
commit f56d3a86c1
32 files changed
+1249 -65

No files matched your search

@@ -0,0 +1,17 @@
import { describe, expect, it } from "vitest";
import { etcdDelete, etcdGet, etcdListPrefix, etcdPut, etcdSupportsTtl, type KvPutOptions } from "@/lib/backend/api";
describe("etcd frontend API contract", () => {
it("exposes TTL capability detection and TTL-aware put options", () => {
const expiring: KvPutOptions = { ttl: 30 };
const preserving: KvPutOptions = { preserveLease: true };
expect(expiring.ttl).toBe(30);
expect(preserving.preserveLease).toBe(true);
expect(typeof etcdSupportsTtl).toBe("function");
expect(typeof etcdListPrefix).toBe("function");
expect(typeof etcdGet).toBe("function");
expect(typeof etcdPut).toBe("function");
expect(typeof etcdDelete).toBe("function");
});
});
@@ -0,0 +1,112 @@
import { describe, expect, it } from "vitest";
import type { KvGetResponse } from "@/lib/backend/api";
import { decideKvMetadataRefresh, knownKvLeaseKeys, KvListRequestGuard, mergeKvKeyMetadata, mergeKvValueRefresh, nextKvLeaseRefreshDelay, removeMissingKvKey, updateKvResponseTtl } from "@/lib/kv/kvMetadataRefresh";
function found(metadata: NonNullable<KvGetResponse["metadata"]>): KvGetResponse {
return {
found: true,
key: "/service",
value: { encoding: "utf8", data: "value" },
metadata,
};
}
describe("decideKvMetadataRefresh", () => {
it("keeps only the latest foreground request current", () => {
const guard = new KvListRequestGuard();
const firstPageRequest = guard.beginForegroundRequest();
expect(guard.isForegroundRequestCurrent(firstPageRequest)).toBe(true);
const loadMoreRequest = guard.beginForegroundRequest();
expect(guard.isForegroundRequestCurrent(firstPageRequest)).toBe(false);
expect(guard.isForegroundRequestCurrent(loadMoreRequest)).toBe(true);
});
it("updates only the TTL when the selected key metadata is unchanged", () => {
const current = found({ modRevision: 10, lease: 20, ttl: 8, valueSize: 5 });
const incoming = found({ modRevision: 10, lease: 20, ttl: 7 });
expect(decideKvMetadataRefresh(current, incoming)).toEqual({ type: "update", ttl: 7 });
});
it("reloads the full value when the revision or lease changes", () => {
const current = found({ modRevision: 10, lease: 20, ttl: 8 });
expect(decideKvMetadataRefresh(current, found({ modRevision: 11, lease: 20, ttl: 7 }))).toEqual({ type: "reload" });
expect(decideKvMetadataRefresh(current, found({ modRevision: 10, lease: 21, ttl: 7 }))).toEqual({ type: "reload" });
});
it("keeps polling without a full reload while etcd finalizes an expired lease", () => {
const current = found({ modRevision: 10, lease: 20, ttl: 1 });
expect(decideKvMetadataRefresh(current, found({ modRevision: 10, lease: 20, ttl: 0 }))).toEqual({ type: "update", ttl: 0 });
expect(decideKvMetadataRefresh(current, found({ modRevision: 10, lease: 20 }))).toEqual({ type: "reload" });
});
it("updates TTL in place without replacing the value response", () => {
const current = found({ modRevision: 10, lease: 20, ttl: 8 });
const value = current.value;
expect(updateKvResponseTtl(current, 7)).toBe(true);
expect(current.metadata?.ttl).toBe(7);
expect(current.value).toBe(value);
});
it("keeps the existing response during a silent full refresh when only TTL changed", () => {
const current = found({ modRevision: 10, lease: 20, ttl: 8 });
const incoming = found({ modRevision: 10, lease: 20, ttl: 7 });
expect(mergeKvValueRefresh(current, incoming)).toBe(current);
expect(current.metadata?.ttl).toBe(7);
});
it("replaces the response when a silent refresh finds a new value revision", () => {
const current = found({ modRevision: 10, lease: 20, ttl: 8 });
const incoming = found({ modRevision: 11, lease: 20, ttl: 7 });
incoming.value = { encoding: "utf8", data: "updated" };
expect(mergeKvValueRefresh(current, incoming)).toBe(incoming);
});
it("stops and exposes a missing key without reloading", () => {
expect(decideKvMetadataRefresh(found({ modRevision: 10, lease: 20, ttl: 1 }), { found: false })).toEqual({ type: "notFound" });
});
it("stops when a metadata refresh cannot be reconciled with the current value", () => {
expect(decideKvMetadataRefresh(null, found({ modRevision: 10, lease: 20, ttl: 1 }))).toEqual({ type: "stop" });
});
it("removes an expired key from the cached key list", () => {
const keys = [{ key: "/dbx/a" }, { key: "/dbx/aaaaa" }, { key: "/test/a" }];
expect(removeMissingKvKey(keys, "/dbx/aaaaa")).toEqual([{ key: "/dbx/a" }, { key: "/test/a" }]);
});
it("tracks only known leased keys and excludes the selected key", () => {
const keys = [{ key: "/no-lease", lease: 0 }, { key: "/leased", lease: 10 }, { key: "/selected", lease: 20 }, { key: "/unknown" }];
expect(knownKvLeaseKeys(keys, "/selected")).toEqual(["/leased"]);
expect(knownKvLeaseKeys(keys, null)).toEqual(["/leased", "/selected"]);
});
it("merges refreshed metadata without replacing the known value size and removes expired keys", () => {
const keys = [
{ key: "/leased", lease: 10, ttl: 4, valueSize: 12 },
{ key: "/expired", lease: 20, ttl: 1 },
];
expect(mergeKvKeyMetadata(keys, "/leased", found({ lease: 11, ttl: 3, modRevision: 5, valueSize: 0 }))).toEqual([
{ key: "/leased", lease: 11, ttl: 3, modRevision: 5, valueSize: 12 },
{ key: "/expired", lease: 20, ttl: 1 },
]);
expect(mergeKvKeyMetadata(keys, "/expired", { found: false })).toEqual([{ key: "/leased", lease: 10, ttl: 4, valueSize: 12 }]);
});
it("backs off after failures and resets after a successful cycle", () => {
expect(nextKvLeaseRefreshDelay(2000, true)).toBe(4000);
expect(nextKvLeaseRefreshDelay(4000, true)).toBe(8000);
expect(nextKvLeaseRefreshDelay(16000, true)).toBe(30000);
expect(nextKvLeaseRefreshDelay(30000, true)).toBe(30000);
expect(nextKvLeaseRefreshDelay(16000, false)).toBe(2000);
});
});
+25
View File
@@ -0,0 +1,25 @@
import { describe, expect, it } from "vitest";
import { parseOptionalTtl } from "@/lib/kv/kvTtl";
describe("parseOptionalTtl", () => {
it("treats an empty TTL as a permanent key", () => {
expect(parseOptionalTtl("")).toEqual({ ok: true, ttl: null });
expect(parseOptionalTtl(" ")).toEqual({ ok: true, ttl: null });
expect(parseOptionalTtl(undefined)).toEqual({ ok: true, ttl: null });
expect(parseOptionalTtl(null)).toEqual({ ok: true, ttl: null });
});
it("accepts positive integer seconds from text and number inputs", () => {
expect(parseOptionalTtl("1")).toEqual({ ok: true, ttl: 1 });
expect(parseOptionalTtl(" 3600 ")).toEqual({ ok: true, ttl: 3600 });
expect(parseOptionalTtl(10)).toEqual({ ok: true, ttl: 10 });
});
it("rejects zero, negative, decimal, and unsafe TTL values", () => {
expect(parseOptionalTtl("0")).toEqual({ ok: false });
expect(parseOptionalTtl("-1")).toEqual({ ok: false });
expect(parseOptionalTtl("1.5")).toEqual({ ok: false });
expect(parseOptionalTtl(1.5)).toEqual({ ok: false });
expect(parseOptionalTtl("9007199254740992")).toEqual({ ok: false });
});
});
+2
View File
@@ -406,6 +406,7 @@ export const redisClusterMasterNodes = forward("redisClusterMasterNodes");
// etcd
export const etcdListPrefix = forward("etcdListPrefix");
export const etcdSupportsTtl = forward("etcdSupportsTtl");
export const etcdGet = forward("etcdGet");
export const etcdPut = forward("etcdPut");
export const etcdDelete = forward("etcdDelete");
@@ -623,6 +624,7 @@ export type {
KvListPrefixResponse,
KvListPrefixOptions,
KvGetResponse,
KvGetOptions,
KvWriteMode,
KvCreateMode,
KvPutOptions,
+18 -4
View File
@@ -76,6 +76,7 @@ import type {
KvListPrefixResponse,
KvListPrefixOptions,
KvGetResponse,
KvGetOptions,
KvPutOptions,
KvPutResponse,
KvDeleteResponse,
@@ -2051,12 +2052,25 @@ export async function etcdListPrefix(connectionId: string, prefix: string, limit
return post("/api/etcd/list-prefix", { connectionId, prefix, limit, continuation });
}
export async function etcdGet(connectionId: string, key: string): Promise<KvGetResponse> {
return post("/api/etcd/get", { connectionId, key });
export async function etcdSupportsTtl(connectionId: string): Promise<boolean> {
return post("/api/etcd/supports-ttl", { connectionId });
}
export async function etcdPut(connectionId: string, key: string, value: KvValue, lease?: number | null): Promise<KvPutResponse> {
return post("/api/etcd/put", { connectionId, key, value, lease });
export async function etcdGet(connectionId: string, key: string, options?: KvGetOptions | null): Promise<KvGetResponse> {
return post("/api/etcd/get", { connectionId, key, metadataOnly: options?.metadataOnly ?? null });
}
export async function etcdPut(connectionId: string, key: string, value: KvValue, options?: KvPutOptions | number | null): Promise<KvPutResponse> {
const legacyLease = typeof options === "number" ? options : null;
const putOptions = typeof options === "object" ? options : null;
return post("/api/etcd/put", {
connectionId,
key,
value,
lease: legacyLease ?? putOptions?.lease ?? null,
ttl: putOptions?.ttl ?? null,
preserveLease: putOptions?.preserveLease ?? null,
});
}
export async function etcdDelete(connectionId: string, key: string): Promise<KvDeleteResponse> {
+25 -4
View File
@@ -1777,6 +1777,7 @@ export interface KvKeyMetadata {
modRevision?: number | null;
version?: number | null;
lease?: number | null;
ttl?: number | null;
valueSize?: number | null;
czxid?: number | null;
mzxid?: number | null;
@@ -1811,6 +1812,10 @@ export interface KvGetResponse {
metadata?: KvKeyMetadata | null;
}
export interface KvGetOptions {
metadataOnly?: boolean | null;
}
export interface KvPutResponse {
revision?: number | null;
version?: number | null;
@@ -1823,6 +1828,9 @@ export type KvWriteMode = "upsert" | "create" | "update";
export type KvCreateMode = "persistent" | "ephemeral" | "persistent_sequential" | "ephemeral_sequential";
export interface KvPutOptions {
lease?: number | null;
ttl?: number | null;
preserveLease?: boolean | null;
writeMode?: KvWriteMode | null;
createMode?: KvCreateMode | null;
}
@@ -1836,12 +1844,25 @@ export async function etcdListPrefix(connectionId: string, prefix: string, limit
return invoke("etcd_list_prefix", { connectionId, prefix, limit, continuation });
}
export async function etcdGet(connectionId: string, key: string): Promise<KvGetResponse> {
return invoke("etcd_get", { connectionId, key });
export async function etcdSupportsTtl(connectionId: string): Promise<boolean> {
return invoke("etcd_supports_ttl", { connectionId });
}
export async function etcdPut(connectionId: string, key: string, value: KvValue, lease?: number | null): Promise<KvPutResponse> {
return invoke("etcd_put", { connectionId, key, value, lease });
export async function etcdGet(connectionId: string, key: string, options?: KvGetOptions | null): Promise<KvGetResponse> {
return invoke("etcd_get", { connectionId, key, metadataOnly: options?.metadataOnly ?? null });
}
export async function etcdPut(connectionId: string, key: string, value: KvValue, options?: KvPutOptions | number | null): Promise<KvPutResponse> {
const legacyLease = typeof options === "number" ? options : null;
const putOptions = typeof options === "object" ? options : null;
return invoke("etcd_put", {
connectionId,
key,
value,
lease: legacyLease ?? putOptions?.lease ?? null,
ttl: putOptions?.ttl ?? null,
preserveLease: putOptions?.preserveLease ?? null,
});
}
export async function etcdDelete(connectionId: string, key: string): Promise<KvDeleteResponse> {
@@ -0,0 +1,65 @@
import type { KvGetResponse, KvKeySummary } from "@/lib/backend/api";
export type KvMetadataRefreshDecision = { type: "notFound" } | { type: "stop" } | { type: "reload" } | { type: "update"; ttl: number };
export class KvListRequestGuard {
private foregroundGeneration = 0;
beginForegroundRequest(): number {
return ++this.foregroundGeneration;
}
isForegroundRequestCurrent(generation: number): boolean {
return generation === this.foregroundGeneration;
}
}
export function decideKvMetadataRefresh(current: KvGetResponse | null, incoming: KvGetResponse): KvMetadataRefreshDecision {
if (!incoming.found) return { type: "notFound" };
if (!current?.found || !incoming.metadata) return { type: "stop" };
if (!current.metadata) return { type: "reload" };
const revisionChanged = current.metadata.modRevision != null && incoming.metadata.modRevision != null && current.metadata.modRevision !== incoming.metadata.modRevision;
const leaseChanged = current.metadata.lease != null && incoming.metadata.lease != null && current.metadata.lease !== incoming.metadata.lease;
const ttl = incoming.metadata.ttl;
if (revisionChanged || leaseChanged || ttl == null) return { type: "reload" };
return { type: "update", ttl: Math.max(0, ttl) };
}
export function updateKvResponseTtl(current: KvGetResponse, ttl: number): boolean {
if (!current.metadata) return false;
current.metadata.ttl = ttl;
return true;
}
export function mergeKvValueRefresh(current: KvGetResponse | null, incoming: KvGetResponse): KvGetResponse {
if (!current?.found || !incoming.found || !current.metadata || !incoming.metadata) return incoming;
const sameValue = current.value?.encoding === incoming.value?.encoding && current.value?.data === incoming.value?.data;
const sameRevision = current.metadata.modRevision === incoming.metadata.modRevision;
const sameLease = current.metadata.lease === incoming.metadata.lease;
if (!sameValue || !sameRevision || !sameLease) return incoming;
if (incoming.metadata.ttl != null) current.metadata.ttl = Math.max(0, incoming.metadata.ttl);
return current;
}
export function removeMissingKvKey(keys: readonly KvKeySummary[], missingKey: string): KvKeySummary[] {
return keys.filter((key) => key.key !== missingKey);
}
export function knownKvLeaseKeys(keys: readonly KvKeySummary[], selectedKey: string | null): string[] {
return keys.filter((key) => key.key !== selectedKey && typeof key.lease === "number" && key.lease > 0).map((key) => key.key);
}
export function mergeKvKeyMetadata(keys: readonly KvKeySummary[], key: string, incoming: KvGetResponse): KvKeySummary[] {
if (!incoming.found) return removeMissingKvKey(keys, key);
if (!incoming.metadata) return [...keys];
return keys.map((item) => (item.key === key ? { ...item, ...incoming.metadata, key: item.key, valueSize: item.valueSize } : item));
}
export function nextKvLeaseRefreshDelay(currentDelayMs: number, failed: boolean, baseDelayMs = 2000, maxDelayMs = 30000): number {
if (!failed) return baseDelayMs;
return Math.min(maxDelayMs, Math.max(baseDelayMs, currentDelayMs) * 2);
}
+13
View File
@@ -0,0 +1,13 @@
export type ParsedOptionalTtl = { ok: true; ttl: number | null } | { ok: false };
export function parseOptionalTtl(value: string | number | null | undefined): ParsedOptionalTtl {
if (value == null) return { ok: true, ttl: null };
const trimmed = String(value).trim();
if (!trimmed) return { ok: true, ttl: null };
if (!/^[1-9]\d*$/.test(trimmed)) return { ok: false };
const ttl = Number(trimmed);
if (!Number.isSafeInteger(ttl)) return { ok: false };
return { ok: true, ttl };
}