@terreno/syncdb 57.17.0 → 57.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/dist/client.d.ts +6 -0
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +1 -0
- package/dist/client.js.map +1 -1
- package/dist/client.test.js +187 -0
- package/dist/client.test.js.map +1 -1
- package/dist/sync/replayCoordinator.test.js +262 -1
- package/dist/sync/replayCoordinator.test.js.map +1 -1
- package/package.json +1 -1
- package/src/client.test.ts +215 -0
- package/src/client.ts +7 -0
- package/src/sync/replayCoordinator.test.ts +313 -1
package/src/client.ts
CHANGED
|
@@ -86,6 +86,12 @@ export interface SyncDbConfig {
|
|
|
86
86
|
baseUrl?: string;
|
|
87
87
|
/** Transport override (tests inject a fake; default is the socket transport). */
|
|
88
88
|
transport?: SyncTransport;
|
|
89
|
+
/**
|
|
90
|
+
* Socket.io transports for the default socket transport, in order. Defaults to polling then
|
|
91
|
+
* websocket. Pass `["websocket"]` for hosts without session affinity, such as Vercel
|
|
92
|
+
* Functions, where a polling request can land on a different instance than its session.
|
|
93
|
+
*/
|
|
94
|
+
socketTransports?: string[];
|
|
89
95
|
/**
|
|
90
96
|
* Optional selected organization id for `X-Organization-Id` on HTTP sync
|
|
91
97
|
* calls and the `organizationId` field on socket mutate payloads. Read at
|
|
@@ -357,6 +363,7 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
|
|
|
357
363
|
// biome-ignore lint/style/noNonNullAssertion: guarded above — no transport implies baseUrl.
|
|
358
364
|
baseUrl: config.baseUrl!,
|
|
359
365
|
organizationIdProvider: config.organizationIdProvider,
|
|
366
|
+
transports: config.socketTransports,
|
|
360
367
|
});
|
|
361
368
|
const httpChannel =
|
|
362
369
|
config.httpChannel ??
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import {describe, expect, it} from "bun:test";
|
|
2
2
|
|
|
3
|
+
import {createSyncDebugLog, type SyncDebugEvent, type SyncDebugLog} from "../debug/debugLog";
|
|
3
4
|
import {getConflict} from "../mutations/conflicts";
|
|
4
5
|
import {createOutbox, type Outbox} from "../mutations/outbox";
|
|
5
6
|
import {createSyncStore, type SyncStore} from "../storage/store";
|
|
@@ -26,7 +27,8 @@ interface Harness {
|
|
|
26
27
|
clock: {value: number};
|
|
27
28
|
}
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
/** Single-send harness (no batch transport), plus optional coordinator overrides. */
|
|
31
|
+
const makeHarness = (overrides: Partial<CreateReplayCoordinatorArgs> = {}): Harness => {
|
|
30
32
|
const store = createSyncStore({collections: ["notes", "todos"]});
|
|
31
33
|
const outbox = createOutbox({store});
|
|
32
34
|
const transport = createFakeTransport();
|
|
@@ -36,6 +38,7 @@ const makeHarness = (): Harness => {
|
|
|
36
38
|
outbox,
|
|
37
39
|
sendMutation: transport.sendMutation,
|
|
38
40
|
store,
|
|
41
|
+
...overrides,
|
|
39
42
|
});
|
|
40
43
|
return {clock, coordinator, outbox, store, transport};
|
|
41
44
|
};
|
|
@@ -1795,4 +1798,313 @@ describe("createReplayCoordinator", () => {
|
|
|
1795
1798
|
expect(harness.outbox.getMutation({mutationId: "m2"})?.status).toBe("acked");
|
|
1796
1799
|
});
|
|
1797
1800
|
});
|
|
1801
|
+
describe("debug event stream", () => {
|
|
1802
|
+
const DEBUG_CLOCK = "2026-01-01T00:00:00.000Z";
|
|
1803
|
+
|
|
1804
|
+
/** Fixed random source: every jittered backoff is half its cap. */
|
|
1805
|
+
const halfRandom = (): number => 0.5;
|
|
1806
|
+
|
|
1807
|
+
const makeDebugLog = (): SyncDebugLog => createSyncDebugLog({clock: () => DEBUG_CLOCK});
|
|
1808
|
+
|
|
1809
|
+
const eventsOfType = (debug: SyncDebugLog, type: SyncDebugEvent["type"]): SyncDebugEvent[] =>
|
|
1810
|
+
debug.getEvents().filter((event) => event.type === type);
|
|
1811
|
+
|
|
1812
|
+
it("a validation nack records a failed event with the parsed mutation body and the reason", async () => {
|
|
1813
|
+
const debug = makeDebugLog();
|
|
1814
|
+
const harness = makeHarness({debug});
|
|
1815
|
+
enqueue(harness, {data: {title: "draft"}, entityId: "t1", mutationId: "m1"});
|
|
1816
|
+
harness.transport.respondWithNack({code: "validation", message: "title too short"});
|
|
1817
|
+
|
|
1818
|
+
await harness.coordinator.replay({userId: USER});
|
|
1819
|
+
|
|
1820
|
+
const [failed] = eventsOfType(debug, "failed");
|
|
1821
|
+
expect(failed).toMatchObject({
|
|
1822
|
+
collection: "todos",
|
|
1823
|
+
detail: {data: {title: "draft"}, reason: "validation"},
|
|
1824
|
+
direction: "inbound",
|
|
1825
|
+
entityId: "t1",
|
|
1826
|
+
label: "failed todos/t1 (validation)",
|
|
1827
|
+
mutationId: "m1",
|
|
1828
|
+
ok: false,
|
|
1829
|
+
operation: "create",
|
|
1830
|
+
});
|
|
1831
|
+
expect(eventsOfType(debug, "failed")).toHaveLength(1);
|
|
1832
|
+
});
|
|
1833
|
+
|
|
1834
|
+
it("records the raw stored args when they are not valid JSON", async () => {
|
|
1835
|
+
const debug = makeDebugLog();
|
|
1836
|
+
const harness = makeHarness({debug});
|
|
1837
|
+
harness.store.upsertEntity({
|
|
1838
|
+
collection: "todos",
|
|
1839
|
+
data: null,
|
|
1840
|
+
id: "t1",
|
|
1841
|
+
pendingMutationId: "m1",
|
|
1842
|
+
});
|
|
1843
|
+
harness.outbox.enqueue({
|
|
1844
|
+
args: {},
|
|
1845
|
+
collection: "todos",
|
|
1846
|
+
entityId: "t1",
|
|
1847
|
+
mutationId: "m1",
|
|
1848
|
+
operation: "create",
|
|
1849
|
+
userId: USER,
|
|
1850
|
+
});
|
|
1851
|
+
harness.store.raw.setCell("_outbox", "m1", "args", "{not json");
|
|
1852
|
+
harness.transport.respondWithNack({code: "validation"});
|
|
1853
|
+
|
|
1854
|
+
await harness.coordinator.replay({userId: USER});
|
|
1855
|
+
|
|
1856
|
+
// The debug stream shows exactly what was stored, so a corrupt row is
|
|
1857
|
+
// visible to whoever is inspecting the failure.
|
|
1858
|
+
expect(eventsOfType(debug, "send")[0]?.detail?.data).toBe("{not json");
|
|
1859
|
+
expect(eventsOfType(debug, "failed")[0]?.detail?.data).toBe("{not json");
|
|
1860
|
+
});
|
|
1861
|
+
|
|
1862
|
+
it("an unauthorized nack records a nack event that marks the drain as paused", async () => {
|
|
1863
|
+
const debug = makeDebugLog();
|
|
1864
|
+
const harness = makeHarness({debug});
|
|
1865
|
+
enqueue(harness, {entityId: "t1", mutationId: "m1"});
|
|
1866
|
+
harness.transport.respondWithNack({code: "unauthorized"});
|
|
1867
|
+
|
|
1868
|
+
const result = await harness.coordinator.replay({userId: USER});
|
|
1869
|
+
|
|
1870
|
+
expect(result).toEqual({paused: "auth"});
|
|
1871
|
+
const nacks = eventsOfType(debug, "nack");
|
|
1872
|
+
expect(nacks).toHaveLength(1);
|
|
1873
|
+
expect(nacks[0]).toMatchObject({
|
|
1874
|
+
detail: {code: "unauthorized", data: {title: "t1"}, paused: true},
|
|
1875
|
+
direction: "inbound",
|
|
1876
|
+
label: "nack todos/t1 (unauthorized)",
|
|
1877
|
+
mutationId: "m1",
|
|
1878
|
+
ok: false,
|
|
1879
|
+
});
|
|
1880
|
+
expect(nacks[0]?.detail).not.toHaveProperty("source");
|
|
1881
|
+
});
|
|
1882
|
+
|
|
1883
|
+
it("an AuthRequiredError from the send channel records an unauthorized nack sourced to HTTP", async () => {
|
|
1884
|
+
const debug = makeDebugLog();
|
|
1885
|
+
const harness = makeHarness({debug});
|
|
1886
|
+
enqueue(harness, {entityId: "t1", mutationId: "m1"});
|
|
1887
|
+
harness.transport.respondWith(() => {
|
|
1888
|
+
throw new AuthRequiredError();
|
|
1889
|
+
});
|
|
1890
|
+
|
|
1891
|
+
const result = await harness.coordinator.replay({userId: USER});
|
|
1892
|
+
|
|
1893
|
+
expect(result).toEqual({paused: "auth"});
|
|
1894
|
+
expect(eventsOfType(debug, "nack")).toEqual([
|
|
1895
|
+
expect.objectContaining({
|
|
1896
|
+
detail: {code: "unauthorized", data: {title: "t1"}, paused: true, source: "http"},
|
|
1897
|
+
label: "nack todos/t1 (unauthorized)",
|
|
1898
|
+
mutationId: "m1",
|
|
1899
|
+
ok: false,
|
|
1900
|
+
}),
|
|
1901
|
+
]);
|
|
1902
|
+
});
|
|
1903
|
+
|
|
1904
|
+
it("an error nack records a retry event with the attempt number and the backoff it armed", async () => {
|
|
1905
|
+
const debug = makeDebugLog();
|
|
1906
|
+
const harness = makeHarness({debug, random: halfRandom});
|
|
1907
|
+
enqueue(harness, {entityId: "t1", mutationId: "m1"});
|
|
1908
|
+
harness.transport.respondWithNack({code: "error"});
|
|
1909
|
+
|
|
1910
|
+
await harness.coordinator.replay({userId: USER});
|
|
1911
|
+
|
|
1912
|
+
const backoffMs = ERROR_NACK_BASE_BACKOFF_MS / 2;
|
|
1913
|
+
expect(eventsOfType(debug, "retry")).toEqual([
|
|
1914
|
+
expect.objectContaining({
|
|
1915
|
+
detail: {attempt: 1, backoffMs, data: {title: "t1"}, reason: "error"},
|
|
1916
|
+
direction: "system",
|
|
1917
|
+
entityId: "t1",
|
|
1918
|
+
label: `retry todos/t1 (error, ${backoffMs}ms)`,
|
|
1919
|
+
mutationId: "m1",
|
|
1920
|
+
operation: "create",
|
|
1921
|
+
}),
|
|
1922
|
+
]);
|
|
1923
|
+
expect(eventsOfType(debug, "failed")).toHaveLength(0);
|
|
1924
|
+
});
|
|
1925
|
+
|
|
1926
|
+
it("a transport failure records a retry event whose attempt count grows on each failure", async () => {
|
|
1927
|
+
const debug = makeDebugLog();
|
|
1928
|
+
const harness = makeHarness({debug, random: halfRandom});
|
|
1929
|
+
enqueue(harness, {entityId: "t1", mutationId: "m1"});
|
|
1930
|
+
harness.transport.setDefaultResponder(() => {
|
|
1931
|
+
throw new Error("timeout");
|
|
1932
|
+
});
|
|
1933
|
+
|
|
1934
|
+
await harness.coordinator.replay({userId: USER});
|
|
1935
|
+
harness.clock.value += MAX_BACKOFF_MS;
|
|
1936
|
+
await harness.coordinator.replay({userId: USER});
|
|
1937
|
+
|
|
1938
|
+
const retries = eventsOfType(debug, "retry");
|
|
1939
|
+
expect(retries.map((event) => event.detail)).toEqual([
|
|
1940
|
+
{attempt: 1, backoffMs: 500, data: {title: "t1"}, reason: "transport"},
|
|
1941
|
+
{attempt: 2, backoffMs: 1_000, data: {title: "t1"}, reason: "transport"},
|
|
1942
|
+
]);
|
|
1943
|
+
expect(retries.map((event) => event.label)).toEqual([
|
|
1944
|
+
"retry todos/t1 (transport, 500ms)",
|
|
1945
|
+
"retry todos/t1 (transport, 1000ms)",
|
|
1946
|
+
]);
|
|
1947
|
+
});
|
|
1948
|
+
|
|
1949
|
+
it("a rate_limited nack records the server's nack, then a retry floored at retryAfterMs", async () => {
|
|
1950
|
+
const debug = makeDebugLog();
|
|
1951
|
+
const harness = makeHarness({debug, random: halfRandom});
|
|
1952
|
+
enqueue(harness, {entityId: "t1", mutationId: "m1"});
|
|
1953
|
+
harness.transport.respondWithNack({
|
|
1954
|
+
code: "rate_limited",
|
|
1955
|
+
message: "slow down",
|
|
1956
|
+
retryAfterMs: 10_000,
|
|
1957
|
+
});
|
|
1958
|
+
|
|
1959
|
+
await harness.coordinator.replay({userId: USER});
|
|
1960
|
+
|
|
1961
|
+
const outcomes = debug
|
|
1962
|
+
.getEvents()
|
|
1963
|
+
.filter((event) => event.type === "nack" || event.type === "retry");
|
|
1964
|
+
expect(outcomes).toEqual([
|
|
1965
|
+
expect.objectContaining({
|
|
1966
|
+
detail: {
|
|
1967
|
+
code: "rate_limited",
|
|
1968
|
+
data: {title: "t1"},
|
|
1969
|
+
message: "slow down",
|
|
1970
|
+
retryAfterMs: 10_000,
|
|
1971
|
+
},
|
|
1972
|
+
direction: "inbound",
|
|
1973
|
+
label: "nack todos/t1 (rate_limited)",
|
|
1974
|
+
ok: false,
|
|
1975
|
+
type: "nack",
|
|
1976
|
+
}),
|
|
1977
|
+
expect.objectContaining({
|
|
1978
|
+
detail: {attempt: 1, backoffMs: 10_000, data: {title: "t1"}, reason: "rate_limited"},
|
|
1979
|
+
label: "retry todos/t1 (rate_limited, 10000ms)",
|
|
1980
|
+
type: "retry",
|
|
1981
|
+
}),
|
|
1982
|
+
]);
|
|
1983
|
+
});
|
|
1984
|
+
|
|
1985
|
+
it("a batched chunk records one send event per mutation, flagged as part of a batch", async () => {
|
|
1986
|
+
const debug = makeDebugLog();
|
|
1987
|
+
const harness = makeBatchHarness({debug});
|
|
1988
|
+
enqueue(harness, {entityId: "e1", mutationId: "m1"});
|
|
1989
|
+
enqueue(harness, {data: {title: "second"}, entityId: "e2", mutationId: "m2"});
|
|
1990
|
+
|
|
1991
|
+
await harness.coordinator.replay({userId: USER});
|
|
1992
|
+
|
|
1993
|
+
expect(harness.transport.sentBatches).toEqual([["m1", "m2"]]);
|
|
1994
|
+
expect(eventsOfType(debug, "send")).toEqual([
|
|
1995
|
+
expect.objectContaining({
|
|
1996
|
+
detail: {attempt: 1, batch: true, data: {title: "e1"}},
|
|
1997
|
+
direction: "outbound",
|
|
1998
|
+
label: "send create todos/e1",
|
|
1999
|
+
mutationId: "m1",
|
|
2000
|
+
}),
|
|
2001
|
+
expect.objectContaining({
|
|
2002
|
+
detail: {attempt: 1, batch: true, data: {title: "second"}},
|
|
2003
|
+
label: "send create todos/e2",
|
|
2004
|
+
mutationId: "m2",
|
|
2005
|
+
}),
|
|
2006
|
+
]);
|
|
2007
|
+
expect(eventsOfType(debug, "ack").map((event) => event.mutationId)).toEqual(["m1", "m2"]);
|
|
2008
|
+
});
|
|
2009
|
+
|
|
2010
|
+
it("a batch transport failure records a transport retry for every mutation in the chunk", async () => {
|
|
2011
|
+
const debug = makeDebugLog();
|
|
2012
|
+
const harness = makeBatchHarness({debug, random: halfRandom});
|
|
2013
|
+
enqueue(harness, {entityId: "e1", mutationId: "m1"});
|
|
2014
|
+
enqueue(harness, {entityId: "e2", mutationId: "m2"});
|
|
2015
|
+
harness.transport.setBatchResponder(() => {
|
|
2016
|
+
throw new Error("socket disconnected mid-batch");
|
|
2017
|
+
});
|
|
2018
|
+
|
|
2019
|
+
await harness.coordinator.replay({userId: USER});
|
|
2020
|
+
|
|
2021
|
+
expect(
|
|
2022
|
+
eventsOfType(debug, "retry").map((event) => [event.mutationId, event.detail?.reason])
|
|
2023
|
+
).toEqual([
|
|
2024
|
+
["m1", "transport"],
|
|
2025
|
+
["m2", "transport"],
|
|
2026
|
+
]);
|
|
2027
|
+
});
|
|
2028
|
+
});
|
|
2029
|
+
|
|
2030
|
+
describe("batch edge cases", () => {
|
|
2031
|
+
it("a mutation with unparseable args still joins the chunk alongside other entities", async () => {
|
|
2032
|
+
const harness = makeBatchHarness();
|
|
2033
|
+
enqueue(harness, {entityId: "e1", mutationId: "m1"});
|
|
2034
|
+
enqueue(harness, {entityId: "e2", mutationId: "m2"});
|
|
2035
|
+
harness.store.raw.setCell("_outbox", "m2", "args", "{not json");
|
|
2036
|
+
|
|
2037
|
+
await harness.coordinator.replay({userId: USER});
|
|
2038
|
+
|
|
2039
|
+
// The reference-blocking scan cannot inspect corrupt args, so it treats
|
|
2040
|
+
// them as referencing nothing rather than holding the mutation back.
|
|
2041
|
+
expect(harness.transport.sentBatches).toEqual([["m1", "m2"]]);
|
|
2042
|
+
expect(harness.outbox.getMutation({mutationId: "m2"})?.status).toBe("acked");
|
|
2043
|
+
});
|
|
2044
|
+
|
|
2045
|
+
it("ignores a batch response that resolves after reset()", async () => {
|
|
2046
|
+
const harness = makeBatchHarness();
|
|
2047
|
+
enqueue(harness, {entityId: "e1", mutationId: "m1"});
|
|
2048
|
+
enqueue(harness, {entityId: "e2", mutationId: "m2"});
|
|
2049
|
+
let release: (() => void) | undefined;
|
|
2050
|
+
harness.transport.respondBatchWith(
|
|
2051
|
+
(request) =>
|
|
2052
|
+
new Promise((resolve) => {
|
|
2053
|
+
release = (): void =>
|
|
2054
|
+
resolve({
|
|
2055
|
+
results: request.mutations.map((mutation, index) => ({
|
|
2056
|
+
ack: {id: mutation.id ?? "", mutationId: mutation.mutationId, seq: index + 1},
|
|
2057
|
+
type: "ack" as const,
|
|
2058
|
+
})),
|
|
2059
|
+
type: "results",
|
|
2060
|
+
});
|
|
2061
|
+
})
|
|
2062
|
+
);
|
|
2063
|
+
|
|
2064
|
+
const replay = harness.coordinator.replay({userId: USER});
|
|
2065
|
+
await Promise.resolve();
|
|
2066
|
+
expect(release).toBeDefined();
|
|
2067
|
+
harness.coordinator.reset();
|
|
2068
|
+
release?.();
|
|
2069
|
+
|
|
2070
|
+
expect(await replay).toEqual({});
|
|
2071
|
+
// The stale acks never land: neither mutation is finalized.
|
|
2072
|
+
expect(harness.outbox.getMutation({mutationId: "m1"})?.status).toBe("inFlight");
|
|
2073
|
+
expect(harness.outbox.getMutation({mutationId: "m2"})?.status).toBe("inFlight");
|
|
2074
|
+
});
|
|
2075
|
+
|
|
2076
|
+
it("ignores a batch transport failure that rejects after reset()", async () => {
|
|
2077
|
+
const harness = makeBatchHarness();
|
|
2078
|
+
enqueue(harness, {entityId: "e1", mutationId: "m1"});
|
|
2079
|
+
enqueue(harness, {entityId: "e2", mutationId: "m2"});
|
|
2080
|
+
let fail: (() => void) | undefined;
|
|
2081
|
+
harness.transport.respondBatchWith(
|
|
2082
|
+
() =>
|
|
2083
|
+
new Promise((_resolve, reject) => {
|
|
2084
|
+
fail = (): void => reject(new Error("socket closed"));
|
|
2085
|
+
})
|
|
2086
|
+
);
|
|
2087
|
+
|
|
2088
|
+
const replay = harness.coordinator.replay({userId: USER});
|
|
2089
|
+
await Promise.resolve();
|
|
2090
|
+
expect(fail).toBeDefined();
|
|
2091
|
+
harness.coordinator.reset();
|
|
2092
|
+
fail?.();
|
|
2093
|
+
|
|
2094
|
+
expect(await replay).toEqual({});
|
|
2095
|
+
// No backoff is armed for the old lifecycle's failure: the rows are left
|
|
2096
|
+
// exactly as the reset found them.
|
|
2097
|
+
expect(harness.outbox.getMutation({mutationId: "m1"})?.status).toBe("inFlight");
|
|
2098
|
+
expect(harness.outbox.getMutation({mutationId: "m1"})?.errorNackCount).toBe(0);
|
|
2099
|
+
});
|
|
2100
|
+
|
|
2101
|
+
it("sends nothing while the host has gated draining off", async () => {
|
|
2102
|
+
const harness = makeHarness({shouldDrain: () => false});
|
|
2103
|
+
enqueue(harness, {entityId: "t1", mutationId: "m1"});
|
|
2104
|
+
|
|
2105
|
+
expect(await harness.coordinator.replay({userId: USER})).toEqual({});
|
|
2106
|
+
expect(harness.transport.sentMutations).toHaveLength(0);
|
|
2107
|
+
expect(harness.outbox.getMutation({mutationId: "m1"})?.status).toBe("queued");
|
|
2108
|
+
});
|
|
2109
|
+
});
|
|
1798
2110
|
});
|