loro-repo 0.21.1 → 0.21.2

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 CHANGED
@@ -605,3 +605,10 @@ Set `LORO_WEBSOCKET_E2E=1` when running websocket end-to-end specs.
605
605
  ## Contributing
606
606
 
607
607
  Follow Conventional Commits, run `pnpm --filter loro-repo check` before opening a PR, and keep `prd/` docs aligned with behavior changes.
608
+
609
+ ## Streams synchronization diagnostics
610
+
611
+ Streams transport errors expose `streamsCode`, `streamsContext`, `failureKind`
612
+ and the upstream `retryable` policy on `RepoTransportError`. Read the
613
+ [consumer contract](../../docs/streams-error-context.md) for trusted fields,
614
+ single/multiple transport reports, join/wait errors and diagnostic logging.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as RepoTransportErrorCode, A as RepoFlockDocHandle, B as RepoRoomPhase, C as RepoDocSnapshot, D as RepoEventKind, E as RepoEventFilter, F as RepoReconnectOptions, G as RepoRoomWaitStatus, H as RepoRoomSubscription, I as RepoResourceLease, J as RepoSyncError, K as RepoStorageError, L as RepoRoomAttachmentEntry, M as RepoFlockDocMeta, N as RepoFlockDocSnapshot, O as RepoEventListener, P as RepoHealthSnapshot, Q as RepoTransportError, R as RepoRoomDescriptor, S as RepoDocObservation, T as RepoEventBy, U as RepoRoomWaitOptions, V as RepoRoomRoute, W as RepoRoomWaitResult, X as RepoSyncOutcome, Y as RepoSyncOptions, Z as RepoSyncReport, _ as RepoDiagnosticSink, _t as TransportSyncRequest, a as JsonObject, at as RepoTransportRoomSubscription, b as RepoDocLease, c as ListFlockDocQuery, ct as RepoWatchHandle, d as META_ROOM_ID, dt as SyncScope, et as RepoTransportHealth, f as ObserveDocsOptions, ft as TransportAdapter, g as RepoDiagnosticEvent, gt as TransportSubscription, h as RepoAttachmentReport, ht as TransportRoomStatus, i as EvictDocOptions, it as RepoTransportRoomStatus, j as RepoFlockDocLease, k as RepoEventType, l as LoadedFlockReplica, lt as StorageAdapter, m as ReplicaCheckpointTarget, mt as TransportJoinParams, n as DeleteDocOptions, nt as RepoTransportPhase, o as JsonValue, ot as RepoTransportSyncFailure, p as RemoveTransportOptions, pt as TransportConnectionStatus, q as RepoStorageErrorCode, r as EphemeralTransportCapability, rt as RepoTransportRoomEntry, s as ListDocQuery, st as RepoTransportSyncReport, t as DEFAULT_TRANSPORT_ID, tt as RepoTransportOptions, u as LoroRepoOptions, ut as StorageSavePayload, v as RepoDocExistenceState, vt as TransportSyncResult, w as RepoEvent, x as RepoDocMeta, y as RepoDocHandle, yt as supportsEphemeralRooms, z as RepoRoomKind } from "./types.cjs";
1
+ import { $ as RepoTransportError, A as RepoFlockDocHandle, B as RepoRoomPhase, C as RepoDocSnapshot, D as RepoEventKind, E as RepoEventFilter, F as RepoReconnectOptions, G as RepoRoomWaitStatus, H as RepoRoomSubscription, I as RepoResourceLease, J as RepoStreamsErrorContext, K as RepoStorageError, L as RepoRoomAttachmentEntry, M as RepoFlockDocMeta, N as RepoFlockDocSnapshot, O as RepoEventListener, P as RepoHealthSnapshot, Q as RepoSyncReport, R as RepoRoomDescriptor, S as RepoDocObservation, T as RepoEventBy, U as RepoRoomWaitOptions, V as RepoRoomRoute, W as RepoRoomWaitResult, X as RepoSyncOptions, Y as RepoSyncError, Z as RepoSyncOutcome, _ as RepoDiagnosticSink, _t as TransportRoomStatus, a as JsonObject, at as RepoTransportRoomEntry, b as RepoDocLease, bt as TransportSyncResult, c as ListFlockDocQuery, ct as RepoTransportSyncFailure, d as META_ROOM_ID, dt as StorageAdapter, et as RepoTransportErrorCode, f as ObserveDocsOptions, ft as StorageSavePayload, g as RepoDiagnosticEvent, gt as TransportJoinParams, h as RepoAttachmentReport, ht as TransportConnectionStatus, i as EvictDocOptions, it as RepoTransportPhase, j as RepoFlockDocLease, k as RepoEventType, l as LoadedFlockReplica, lt as RepoTransportSyncReport, m as ReplicaCheckpointTarget, mt as TransportAdapter, n as DeleteDocOptions, nt as RepoTransportHealth, o as JsonValue, ot as RepoTransportRoomStatus, p as RemoveTransportOptions, pt as SyncScope, q as RepoStorageErrorCode, r as EphemeralTransportCapability, rt as RepoTransportOptions, s as ListDocQuery, st as RepoTransportRoomSubscription, t as DEFAULT_TRANSPORT_ID, tt as RepoTransportFailureKind, u as LoroRepoOptions, ut as RepoWatchHandle, v as RepoDocExistenceState, vt as TransportSubscription, w as RepoEvent, x as RepoDocMeta, xt as supportsEphemeralRooms, y as RepoDocHandle, yt as TransportSyncRequest, z as RepoRoomKind } from "./types.cjs";
2
2
  import { RemoteCursorStore } from "@loro-dev/streams-crdt";
3
3
  import { Flock } from "@loro-dev/flock-wasm";
4
4
  import { EphemeralStore, LoroDoc } from "loro-crdt";
@@ -262,5 +262,5 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
262
262
  destroy(): Promise<void>;
263
263
  }
264
264
  //#endregion
265
- export { DEFAULT_TRANSPORT_ID, DeleteDocOptions, EphemeralTransportCapability, EvictDocOptions, JsonObject, JsonValue, ListDocQuery, ListFlockDocQuery, LoadedFlockReplica, LoroRepo, LoroRepoOptions, META_ROOM_ID, ObserveDocsOptions, RemoveTransportOptions, ReplicaCheckpointTarget, RepoAttachmentReport, RepoDiagnosticEvent, RepoDiagnosticSink, RepoDocExistenceState, RepoDocHandle, RepoDocLease, RepoDocMeta, RepoDocObservation, RepoDocSnapshot, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoFlockDocHandle, RepoFlockDocLease, RepoFlockDocMeta, RepoFlockDocSnapshot, RepoHealthSnapshot, RepoReconnectOptions, RepoResourceLease, RepoRoomAttachmentEntry, RepoRoomDescriptor, RepoRoomKind, RepoRoomPhase, RepoRoomRoute, RepoRoomSubscription, RepoRoomWaitOptions, RepoRoomWaitResult, RepoRoomWaitStatus, RepoStorageError, RepoStorageErrorCode, RepoSyncError, RepoSyncOptions, RepoSyncOutcome, RepoSyncReport, RepoTransportError, RepoTransportErrorCode, RepoTransportHealth, RepoTransportOptions, RepoTransportPhase, RepoTransportRoomEntry, RepoTransportRoomStatus, RepoTransportRoomSubscription, RepoTransportSyncFailure, RepoTransportSyncReport, RepoWatchHandle, ResourceBusyError, StaleReplicaError, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportConnectionStatus, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncRequest, TransportSyncResult, supportsEphemeralRooms };
265
+ export { DEFAULT_TRANSPORT_ID, DeleteDocOptions, EphemeralTransportCapability, EvictDocOptions, JsonObject, JsonValue, ListDocQuery, ListFlockDocQuery, LoadedFlockReplica, LoroRepo, LoroRepoOptions, META_ROOM_ID, ObserveDocsOptions, RemoveTransportOptions, ReplicaCheckpointTarget, RepoAttachmentReport, RepoDiagnosticEvent, RepoDiagnosticSink, RepoDocExistenceState, RepoDocHandle, RepoDocLease, RepoDocMeta, RepoDocObservation, RepoDocSnapshot, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoFlockDocHandle, RepoFlockDocLease, RepoFlockDocMeta, RepoFlockDocSnapshot, RepoHealthSnapshot, RepoReconnectOptions, RepoResourceLease, RepoRoomAttachmentEntry, RepoRoomDescriptor, RepoRoomKind, RepoRoomPhase, RepoRoomRoute, RepoRoomSubscription, RepoRoomWaitOptions, RepoRoomWaitResult, RepoRoomWaitStatus, RepoStorageError, RepoStorageErrorCode, RepoStreamsErrorContext, RepoSyncError, RepoSyncOptions, RepoSyncOutcome, RepoSyncReport, RepoTransportError, RepoTransportErrorCode, RepoTransportFailureKind, RepoTransportHealth, RepoTransportOptions, RepoTransportPhase, RepoTransportRoomEntry, RepoTransportRoomStatus, RepoTransportRoomSubscription, RepoTransportSyncFailure, RepoTransportSyncReport, RepoWatchHandle, ResourceBusyError, StaleReplicaError, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportConnectionStatus, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncRequest, TransportSyncResult, supportsEphemeralRooms };
266
266
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as RepoTransportErrorCode, A as RepoFlockDocHandle, B as RepoRoomPhase, C as RepoDocSnapshot, D as RepoEventKind, E as RepoEventFilter, F as RepoReconnectOptions, G as RepoRoomWaitStatus, H as RepoRoomSubscription, I as RepoResourceLease, J as RepoSyncError, K as RepoStorageError, L as RepoRoomAttachmentEntry, M as RepoFlockDocMeta, N as RepoFlockDocSnapshot, O as RepoEventListener, P as RepoHealthSnapshot, Q as RepoTransportError, R as RepoRoomDescriptor, S as RepoDocObservation, T as RepoEventBy, U as RepoRoomWaitOptions, V as RepoRoomRoute, W as RepoRoomWaitResult, X as RepoSyncOutcome, Y as RepoSyncOptions, Z as RepoSyncReport, _ as RepoDiagnosticSink, _t as TransportSyncRequest, a as JsonObject, at as RepoTransportRoomSubscription, b as RepoDocLease, c as ListFlockDocQuery, ct as RepoWatchHandle, d as META_ROOM_ID, dt as SyncScope, et as RepoTransportHealth, f as ObserveDocsOptions, ft as TransportAdapter, g as RepoDiagnosticEvent, gt as TransportSubscription, h as RepoAttachmentReport, ht as TransportRoomStatus, i as EvictDocOptions, it as RepoTransportRoomStatus, j as RepoFlockDocLease, k as RepoEventType, l as LoadedFlockReplica, lt as StorageAdapter, m as ReplicaCheckpointTarget, mt as TransportJoinParams, n as DeleteDocOptions, nt as RepoTransportPhase, o as JsonValue, ot as RepoTransportSyncFailure, p as RemoveTransportOptions, pt as TransportConnectionStatus, q as RepoStorageErrorCode, r as EphemeralTransportCapability, rt as RepoTransportRoomEntry, s as ListDocQuery, st as RepoTransportSyncReport, t as DEFAULT_TRANSPORT_ID, tt as RepoTransportOptions, u as LoroRepoOptions, ut as StorageSavePayload, v as RepoDocExistenceState, vt as TransportSyncResult, w as RepoEvent, x as RepoDocMeta, y as RepoDocHandle, yt as supportsEphemeralRooms, z as RepoRoomKind } from "./types.js";
1
+ import { $ as RepoTransportError, A as RepoFlockDocHandle, B as RepoRoomPhase, C as RepoDocSnapshot, D as RepoEventKind, E as RepoEventFilter, F as RepoReconnectOptions, G as RepoRoomWaitStatus, H as RepoRoomSubscription, I as RepoResourceLease, J as RepoStreamsErrorContext, K as RepoStorageError, L as RepoRoomAttachmentEntry, M as RepoFlockDocMeta, N as RepoFlockDocSnapshot, O as RepoEventListener, P as RepoHealthSnapshot, Q as RepoSyncReport, R as RepoRoomDescriptor, S as RepoDocObservation, T as RepoEventBy, U as RepoRoomWaitOptions, V as RepoRoomRoute, W as RepoRoomWaitResult, X as RepoSyncOptions, Y as RepoSyncError, Z as RepoSyncOutcome, _ as RepoDiagnosticSink, _t as TransportRoomStatus, a as JsonObject, at as RepoTransportRoomEntry, b as RepoDocLease, bt as TransportSyncResult, c as ListFlockDocQuery, ct as RepoTransportSyncFailure, d as META_ROOM_ID, dt as StorageAdapter, et as RepoTransportErrorCode, f as ObserveDocsOptions, ft as StorageSavePayload, g as RepoDiagnosticEvent, gt as TransportJoinParams, h as RepoAttachmentReport, ht as TransportConnectionStatus, i as EvictDocOptions, it as RepoTransportPhase, j as RepoFlockDocLease, k as RepoEventType, l as LoadedFlockReplica, lt as RepoTransportSyncReport, m as ReplicaCheckpointTarget, mt as TransportAdapter, n as DeleteDocOptions, nt as RepoTransportHealth, o as JsonValue, ot as RepoTransportRoomStatus, p as RemoveTransportOptions, pt as SyncScope, q as RepoStorageErrorCode, r as EphemeralTransportCapability, rt as RepoTransportOptions, s as ListDocQuery, st as RepoTransportRoomSubscription, t as DEFAULT_TRANSPORT_ID, tt as RepoTransportFailureKind, u as LoroRepoOptions, ut as RepoWatchHandle, v as RepoDocExistenceState, vt as TransportSubscription, w as RepoEvent, x as RepoDocMeta, xt as supportsEphemeralRooms, y as RepoDocHandle, yt as TransportSyncRequest, z as RepoRoomKind } from "./types.js";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { EphemeralStore, LoroDoc } from "loro-crdt";
4
4
  import { RemoteCursorStore } from "@loro-dev/streams-crdt";
@@ -262,5 +262,5 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
262
262
  destroy(): Promise<void>;
263
263
  }
264
264
  //#endregion
265
- export { DEFAULT_TRANSPORT_ID, DeleteDocOptions, EphemeralTransportCapability, EvictDocOptions, JsonObject, JsonValue, ListDocQuery, ListFlockDocQuery, LoadedFlockReplica, LoroRepo, LoroRepoOptions, META_ROOM_ID, ObserveDocsOptions, RemoveTransportOptions, ReplicaCheckpointTarget, RepoAttachmentReport, RepoDiagnosticEvent, RepoDiagnosticSink, RepoDocExistenceState, RepoDocHandle, RepoDocLease, RepoDocMeta, RepoDocObservation, RepoDocSnapshot, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoFlockDocHandle, RepoFlockDocLease, RepoFlockDocMeta, RepoFlockDocSnapshot, RepoHealthSnapshot, RepoReconnectOptions, RepoResourceLease, RepoRoomAttachmentEntry, RepoRoomDescriptor, RepoRoomKind, RepoRoomPhase, RepoRoomRoute, RepoRoomSubscription, RepoRoomWaitOptions, RepoRoomWaitResult, RepoRoomWaitStatus, RepoStorageError, RepoStorageErrorCode, RepoSyncError, RepoSyncOptions, RepoSyncOutcome, RepoSyncReport, RepoTransportError, RepoTransportErrorCode, RepoTransportHealth, RepoTransportOptions, RepoTransportPhase, RepoTransportRoomEntry, RepoTransportRoomStatus, RepoTransportRoomSubscription, RepoTransportSyncFailure, RepoTransportSyncReport, RepoWatchHandle, ResourceBusyError, StaleReplicaError, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportConnectionStatus, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncRequest, TransportSyncResult, supportsEphemeralRooms };
265
+ export { DEFAULT_TRANSPORT_ID, DeleteDocOptions, EphemeralTransportCapability, EvictDocOptions, JsonObject, JsonValue, ListDocQuery, ListFlockDocQuery, LoadedFlockReplica, LoroRepo, LoroRepoOptions, META_ROOM_ID, ObserveDocsOptions, RemoveTransportOptions, ReplicaCheckpointTarget, RepoAttachmentReport, RepoDiagnosticEvent, RepoDiagnosticSink, RepoDocExistenceState, RepoDocHandle, RepoDocLease, RepoDocMeta, RepoDocObservation, RepoDocSnapshot, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoFlockDocHandle, RepoFlockDocLease, RepoFlockDocMeta, RepoFlockDocSnapshot, RepoHealthSnapshot, RepoReconnectOptions, RepoResourceLease, RepoRoomAttachmentEntry, RepoRoomDescriptor, RepoRoomKind, RepoRoomPhase, RepoRoomRoute, RepoRoomSubscription, RepoRoomWaitOptions, RepoRoomWaitResult, RepoRoomWaitStatus, RepoStorageError, RepoStorageErrorCode, RepoStreamsErrorContext, RepoSyncError, RepoSyncOptions, RepoSyncOutcome, RepoSyncReport, RepoTransportError, RepoTransportErrorCode, RepoTransportFailureKind, RepoTransportHealth, RepoTransportOptions, RepoTransportPhase, RepoTransportRoomEntry, RepoTransportRoomStatus, RepoTransportRoomSubscription, RepoTransportSyncFailure, RepoTransportSyncReport, RepoWatchHandle, ResourceBusyError, StaleReplicaError, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportConnectionStatus, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncRequest, TransportSyncResult, supportsEphemeralRooms };
266
266
  //# sourceMappingURL=index.d.ts.map
@@ -1,4 +1,4 @@
1
- import { lt as StorageAdapter, ut as StorageSavePayload } from "../types.cjs";
1
+ import { dt as StorageAdapter, ft as StorageSavePayload } from "../types.cjs";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { LoroDoc } from "loro-crdt";
4
4
 
@@ -1,4 +1,4 @@
1
- import { lt as StorageAdapter, ut as StorageSavePayload } from "../types.js";
1
+ import { dt as StorageAdapter, ft as StorageSavePayload } from "../types.js";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { LoroDoc } from "loro-crdt";
4
4
 
@@ -1,4 +1,4 @@
1
- import { K as RepoStorageError, l as LoadedFlockReplica, lt as StorageAdapter, q as RepoStorageErrorCode, ut as StorageSavePayload } from "../types.cjs";
1
+ import { K as RepoStorageError, dt as StorageAdapter, ft as StorageSavePayload, l as LoadedFlockReplica, q as RepoStorageErrorCode } from "../types.cjs";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { LoroDoc } from "loro-crdt";
4
4
 
@@ -1,4 +1,4 @@
1
- import { K as RepoStorageError, l as LoadedFlockReplica, lt as StorageAdapter, q as RepoStorageErrorCode, ut as StorageSavePayload } from "../types.js";
1
+ import { K as RepoStorageError, dt as StorageAdapter, ft as StorageSavePayload, l as LoadedFlockReplica, q as RepoStorageErrorCode } from "../types.js";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { LoroDoc } from "loro-crdt";
4
4
 
@@ -1,4 +1,4 @@
1
- import { lt as StorageAdapter } from "../types.cjs";
1
+ import { dt as StorageAdapter } from "../types.cjs";
2
2
  import { JsonObject, RemoteCursorStore } from "@loro-dev/streams-crdt";
3
3
  import { Database } from "better-sqlite3";
4
4
 
@@ -1,4 +1,4 @@
1
- import { lt as StorageAdapter } from "../types.js";
1
+ import { dt as StorageAdapter } from "../types.js";
2
2
  import { Database } from "better-sqlite3";
3
3
  import { JsonObject, RemoteCursorStore } from "@loro-dev/streams-crdt";
4
4
 
@@ -1,4 +1,4 @@
1
- import { ft as TransportAdapter, gt as TransportSubscription, mt as TransportJoinParams, vt as TransportSyncResult } from "../types.cjs";
1
+ import { bt as TransportSyncResult, gt as TransportJoinParams, mt as TransportAdapter, vt as TransportSubscription } from "../types.cjs";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { EphemeralStore, LoroDoc } from "loro-crdt";
4
4
 
@@ -1,4 +1,4 @@
1
- import { ft as TransportAdapter, gt as TransportSubscription, mt as TransportJoinParams, vt as TransportSyncResult } from "../types.js";
1
+ import { bt as TransportSyncResult, gt as TransportJoinParams, mt as TransportAdapter, vt as TransportSubscription } from "../types.js";
2
2
  import { Flock } from "@loro-dev/flock-wasm";
3
3
  import { EphemeralStore, LoroDoc } from "loro-crdt";
4
4
 
@@ -37,8 +37,178 @@ function resolveStreamsCrdtPayloadProtection(config) {
37
37
  };
38
38
  }
39
39
 
40
+ //#endregion
41
+ //#region src/transport/streams-error-context.ts
42
+ const codes = [
43
+ "stream_not_found",
44
+ "auth_failed",
45
+ "auth_provider_error",
46
+ "protocol_error",
47
+ "payload_too_large",
48
+ "network_error",
49
+ "timeout",
50
+ "initial_sync_timeout",
51
+ "gone",
52
+ "apply_incomplete",
53
+ "server_error",
54
+ "internal_error",
55
+ "unknown",
56
+ "payload_protection_error"
57
+ ];
58
+ const sources = [
59
+ "fetch",
60
+ "http",
61
+ "auth",
62
+ "local",
63
+ "unknown",
64
+ "cursor_store",
65
+ "crdt",
66
+ "durability_hook",
67
+ "payload_protection",
68
+ "deadline"
69
+ ];
70
+ const operations = [
71
+ "sync",
72
+ "join",
73
+ "catchup",
74
+ "create",
75
+ "delete",
76
+ "upload",
77
+ "snapshot",
78
+ "live",
79
+ "unknown"
80
+ ];
81
+ const stages = [
82
+ "bootstrap",
83
+ "catch_up",
84
+ "upload",
85
+ "cursor_load",
86
+ "cursor_save",
87
+ "cursor_delete",
88
+ "durability_hook",
89
+ "crdt_apply",
90
+ "crdt_export",
91
+ "payload_encode",
92
+ "payload_decode",
93
+ "initial_sync",
94
+ "unknown"
95
+ ];
96
+ const requestOperations = [
97
+ "create",
98
+ "delete",
99
+ "append",
100
+ "read-once",
101
+ "live-sse",
102
+ "live-long-poll",
103
+ "head",
104
+ "bucket-metadata",
105
+ "append-cas",
106
+ "read-backward",
107
+ "bootstrap",
108
+ "read-snapshot",
109
+ "put-snapshot",
110
+ "delete-snapshot",
111
+ "unknown"
112
+ ];
113
+ const originalCodes = [
114
+ ...codes,
115
+ "bad_request",
116
+ "unauthorized",
117
+ "forbidden",
118
+ "not_found",
119
+ "conflict",
120
+ "rate_limited"
121
+ ];
122
+ const networkCodes = [
123
+ "ENOTFOUND",
124
+ "EAI_AGAIN",
125
+ "ECONNREFUSED",
126
+ "ECONNRESET",
127
+ "ECONNABORTED",
128
+ "ETIMEDOUT",
129
+ "EHOSTUNREACH",
130
+ "ENETUNREACH",
131
+ "EPIPE",
132
+ "UND_ERR_CONNECT_TIMEOUT",
133
+ "UND_ERR_HEADERS_TIMEOUT",
134
+ "UND_ERR_BODY_TIMEOUT",
135
+ "UND_ERR_SOCKET"
136
+ ];
137
+ function field(value, key) {
138
+ if (value === null || typeof value !== "object") return void 0;
139
+ try {
140
+ return Object.getOwnPropertyDescriptor(value, key)?.value;
141
+ } catch {
142
+ return;
143
+ }
144
+ }
145
+ function member(value, allowed) {
146
+ return typeof value === "string" && allowed.includes(value) ? value : void 0;
147
+ }
148
+ function duration(value) {
149
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
150
+ }
151
+ /** Only call at a structured Streams result/lastError boundary, never for arbitrary exceptions. */
152
+ function projectStreamsError(error) {
153
+ const streamsCode = member(field(error, "code"), [
154
+ ...codes,
155
+ "network",
156
+ "connection_failed",
157
+ "unauthorized",
158
+ "forbidden",
159
+ "not_found",
160
+ "conflict",
161
+ "version_conflict",
162
+ "aborted",
163
+ "cancelled",
164
+ "unsupported"
165
+ ]) ?? "unknown";
166
+ const retry = field(error, "retryable");
167
+ const retryable = typeof retry === "boolean" ? retry : void 0;
168
+ const raw = field(error, "context");
169
+ let streamsContext;
170
+ if (raw !== null && typeof raw === "object") {
171
+ const source = member(field(raw, "source"), sources) ?? "unknown";
172
+ const requestOperation = member(field(raw, "requestOperation"), requestOperations);
173
+ const phase = member(field(raw, "phase"), ["connect", "poll"]);
174
+ const timeoutMs = duration(field(raw, "timeoutMs"));
175
+ const elapsedMs = duration(field(raw, "elapsedMs"));
176
+ const status = field(raw, "status");
177
+ const requestId = field(raw, "requestId");
178
+ const networkCode = source === "fetch" ? member(field(raw, "networkCode"), networkCodes) : void 0;
179
+ streamsContext = Object.freeze({
180
+ source,
181
+ operation: member(field(raw, "operation"), operations) ?? "unknown",
182
+ stage: member(field(raw, "stage"), stages) ?? "unknown",
183
+ originalCode: member(field(raw, "originalCode"), originalCodes) ?? "unknown",
184
+ retryable: retryable ?? field(raw, "retryable") === true,
185
+ ...requestOperation !== void 0 ? { requestOperation } : {},
186
+ ...phase !== void 0 ? { phase } : {},
187
+ ...timeoutMs !== void 0 ? { timeoutMs } : {},
188
+ ...elapsedMs !== void 0 ? { elapsedMs } : {},
189
+ ...typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599 ? { status } : {},
190
+ ...typeof requestId === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(requestId) ? { requestId } : {},
191
+ ...networkCode !== void 0 ? { networkCode } : {}
192
+ });
193
+ }
194
+ let failureKind = "unknown";
195
+ if (streamsCode === "timeout" || streamsCode === "initial_sync_timeout") failureKind = "timeout";
196
+ else if (streamsContext?.source === "fetch") failureKind = "network";
197
+ else if (streamsContext?.source === "http") failureKind = "server";
198
+ else if (streamsContext?.source === "cursor_store" || streamsContext?.source === "durability_hook") failureKind = "local-storage";
199
+ else if (streamsContext?.source === "crdt") failureKind = "local-crdt";
200
+ else if (streamsContext?.source === "local" || streamsContext?.source === "payload_protection" || streamsContext?.source === "auth") failureKind = "local";
201
+ return {
202
+ streamsCode,
203
+ retryable,
204
+ streamsContext,
205
+ failureKind
206
+ };
207
+ }
208
+
40
209
  //#endregion
41
210
  //#region src/transport/streams.ts
211
+ const safeTransportErrors = /* @__PURE__ */ new WeakSet();
42
212
  const debug = require_debug.createDebugLogger("transport:streams");
43
213
  function shouldRejoinRoom(status) {
44
214
  return status === "disconnected" || status === "error" || status === "reconnecting";
@@ -86,9 +256,8 @@ function createPersistentFlockAdapter(flock) {
86
256
  /**
87
257
  * Maps a streams-crdt error code onto the repository's coarse taxonomy.
88
258
  *
89
- * Unknown codes become `"internal"` and stay retryable — an unrecognized
90
- * failure is more likely transient than permanent, and the original is kept
91
- * as `cause` either way.
259
+ * Unknown codes become `"internal"`. Retry policy and safe context are
260
+ * carried independently; raw causes never cross this boundary.
92
261
  */
93
262
  function classifyStreamsErrorCode(code) {
94
263
  switch (code) {
@@ -99,7 +268,8 @@ function classifyStreamsErrorCode(code) {
99
268
  case "stream_not_found": return "not-found";
100
269
  case "conflict":
101
270
  case "version_conflict": return "conflict";
102
- case "timeout": return "timeout";
271
+ case "timeout":
272
+ case "initial_sync_timeout": return "timeout";
103
273
  case "aborted":
104
274
  case "cancelled": return "aborted";
105
275
  case "network":
@@ -211,16 +381,7 @@ function createSubscriptionClosedError() {
211
381
  return new SanitizedStreamsRoomError("subscription closed");
212
382
  }
213
383
  function sanitizeStreamsRoomError(error, fallback) {
214
- return error instanceof SanitizedStreamsRoomError ? error : fallback();
215
- }
216
- function createMetaJoinError(error) {
217
- return new SanitizedStreamsRoomError(`Failed to join meta room: ${error?.code ?? "unknown"}`);
218
- }
219
- function createDocJoinError(docId, error) {
220
- return new SanitizedStreamsRoomError(`Failed to join doc room ${docId}: ${error?.code ?? "unknown"}`);
221
- }
222
- function createFlockDocJoinError(flockDocId, error) {
223
- return new SanitizedStreamsRoomError(`Failed to join Flock doc room ${flockDocId}: ${error?.code ?? "unknown"}`);
384
+ return error instanceof SanitizedStreamsRoomError || error instanceof require_types.RepoTransportError && safeTransportErrors.has(error) ? error : fallback();
224
385
  }
225
386
  function createPayloadProtectionConfigurationError() {
226
387
  return new SanitizedStreamsRoomError("Invalid Streams room payload-protection configuration");
@@ -257,18 +418,18 @@ function encodeStreamsRoomAdditionalData(namespace, room, envelopeAdditionalData
257
418
  logicalId,
258
419
  envelopeAdditionalData
259
420
  ];
260
- const totalLength = fields.reduce((total, field) => {
261
- if (field.byteLength > 4294967295) throw createPayloadProtectionConfigurationError();
262
- return total + 4 + field.byteLength;
421
+ const totalLength = fields.reduce((total, field$1) => {
422
+ if (field$1.byteLength > 4294967295) throw createPayloadProtectionConfigurationError();
423
+ return total + 4 + field$1.byteLength;
263
424
  }, 0);
264
425
  const output = new Uint8Array(totalLength);
265
426
  const view = new DataView(output.buffer);
266
427
  let offset = 0;
267
- for (const field of fields) {
268
- view.setUint32(offset, field.byteLength, false);
428
+ for (const field$1 of fields) {
429
+ view.setUint32(offset, field$1.byteLength, false);
269
430
  offset += 4;
270
- output.set(field, offset);
271
- offset += field.byteLength;
431
+ output.set(field$1, offset);
432
+ offset += field$1.byteLength;
272
433
  }
273
434
  return output;
274
435
  }
@@ -443,6 +604,7 @@ var StreamsTransportAdapter = class {
443
604
  ...target,
444
605
  adapter: room.kind === "doc" ? (0, __loro_dev_streams_crdt_loro.createLoroDocAdapter)(new loro_crdt.LoroDoc()) : (0, __loro_dev_streams_crdt_flock.createFlockAdapter)(patchFlockExportJson(new __loro_dev_flock_wasm.Flock())),
445
606
  auth: this.resolveAuth(),
607
+ reconnectConfig: this.options.reconnectConfig,
446
608
  remoteCursorStore: new __loro_dev_streams_crdt.InMemoryRemoteCursorStore(),
447
609
  createStreamIfMissing: false,
448
610
  ...this.resolvePayloadProtection(room)
@@ -470,26 +632,58 @@ var StreamsTransportAdapter = class {
470
632
  } catch {}
471
633
  }
472
634
  transportError(message, options) {
473
- return new require_types.RepoTransportError(message, {
635
+ const error = new require_types.RepoTransportError(message, {
474
636
  ...options,
475
637
  transportId: this.transportLabel
476
638
  });
639
+ safeTransportErrors.add(error);
640
+ return error;
477
641
  }
478
- /**
479
- * Wraps a streams-crdt structured failure.
480
- *
481
- * The message is built from the error *code*, never the underlying
482
- * message: a payload-protection failure can carry key material or provider
483
- * internals, and this adapter's contract is that only a
484
- * `SanitizedStreamsRoomError` message may leave the room boundary. The
485
- * classification is what callers need; the detail stays inside.
486
- */
642
+ /** Project only the safe upstream contract, never legacy message/body/cause. */
487
643
  fromStreamsError(error, ctx) {
488
- return this.transportError(`Streams ${ctx.phase} failed: ${error.code ?? "unknown"}`, {
644
+ const projected = projectStreamsError(error);
645
+ return this.transportError(`Streams ${ctx.phase} failed: ${projected.streamsCode}`, {
489
646
  ...ctx,
490
- code: classifyStreamsErrorCode(error.code)
647
+ ...projected,
648
+ code: classifyStreamsErrorCode(projected.streamsCode)
491
649
  });
492
650
  }
651
+ createMetaJoinError(error) {
652
+ return this.roomJoinError(error, { roomKind: "meta" });
653
+ }
654
+ createDocJoinError(docId, error) {
655
+ return this.roomJoinError(error, {
656
+ roomKind: "doc",
657
+ roomId: docId
658
+ });
659
+ }
660
+ createFlockDocJoinError(flockDocId, error) {
661
+ return this.roomJoinError(error, {
662
+ roomKind: "flock-doc",
663
+ roomId: flockDocId
664
+ });
665
+ }
666
+ roomJoinError(error, ctx) {
667
+ const projected = error === void 0 ? void 0 : projectStreamsError(error);
668
+ const code = projected?.streamsCode ?? "unknown";
669
+ const label = ctx.roomKind === "meta" ? "meta room" : ctx.roomKind === "doc" ? `doc room ${ctx.roomId}` : `Flock doc room ${ctx.roomId}`;
670
+ const typed = this.transportError(`Failed to join ${label}: ${code}`, {
671
+ ...ctx,
672
+ phase: "join",
673
+ code: classifyStreamsErrorCode(code),
674
+ retryable: projected?.retryable ?? false,
675
+ failureKind: projected?.failureKind ?? "unknown",
676
+ ...projected
677
+ });
678
+ this.diagnose({
679
+ level: "warn",
680
+ event: "join.room.failed",
681
+ ...ctx,
682
+ phase: "join",
683
+ error: typed
684
+ });
685
+ return typed;
686
+ }
493
687
  /**
494
688
  * Normalizes a thrown value into a `RepoTransportError`.
495
689
  *
@@ -498,17 +692,21 @@ var StreamsTransportAdapter = class {
498
692
  * classifying a failure never becomes a way to exfiltrate provider detail.
499
693
  */
500
694
  toTransportError(error, ctx) {
501
- if (error instanceof require_types.RepoTransportError) return error;
695
+ if (error instanceof require_types.RepoTransportError && safeTransportErrors.has(error)) return error;
502
696
  if (error instanceof SanitizedStreamsRoomError) return this.transportError(error.message, {
503
697
  ...ctx,
504
- code: "network",
698
+ code: "internal",
699
+ retryable: false,
700
+ failureKind: "unknown",
505
701
  cause: error
506
702
  });
507
703
  const name = error instanceof Error ? error.name : void 0;
508
- const code = name === "TimeoutError" ? "timeout" : name === "AbortError" ? "aborted" : "network";
704
+ const code = name === "TimeoutError" ? "timeout" : name === "AbortError" ? "aborted" : "internal";
509
705
  return this.transportError(`Streams ${ctx.phase} failed`, {
510
706
  ...ctx,
511
- code
707
+ code,
708
+ retryable: code === "timeout",
709
+ failureKind: code === "timeout" ? "timeout" : "unknown"
512
710
  });
513
711
  }
514
712
  /**
@@ -524,7 +722,8 @@ var StreamsTransportAdapter = class {
524
722
  throw this.transportError(`Streams ${ctx.phase} timed out after ${options?.timeout}ms`, {
525
723
  ...ctx,
526
724
  code: "timeout",
527
- retryable: true
725
+ retryable: true,
726
+ failureKind: "timeout"
528
727
  });
529
728
  },
530
729
  onAbort: () => {
@@ -803,6 +1002,7 @@ var StreamsTransportAdapter = class {
803
1002
  const existing = this.metaSession;
804
1003
  const rawSessionPromise = ownership.ready.then(() => this.ensureMetaSession(flock, params?.auth));
805
1004
  return this.createRoomSubscription({
1005
+ roomKind: "meta",
806
1006
  rawSessionPromise,
807
1007
  releaseAcquisition,
808
1008
  initialStatus: existing && existing.flock === flock ? existing.statusEmitter.status : "connecting",
@@ -817,7 +1017,7 @@ var StreamsTransportAdapter = class {
817
1017
  waitForFirstSync: (session) => this.waitForMetaFirstSync(session),
818
1018
  getActiveSubscription: (session) => this.getActiveMetaSubscription(session),
819
1019
  rejoin: (session) => this.rejoinMetaSession(session),
820
- createWaitError: () => createMetaJoinError()
1020
+ createWaitError: (error) => this.createMetaJoinError(error)
821
1021
  });
822
1022
  }
823
1023
  async syncDoc(docId, doc, options) {
@@ -912,6 +1112,8 @@ var StreamsTransportAdapter = class {
912
1112
  const existing = this.docSessions.get(docId);
913
1113
  const rawSessionPromise = ownership.ready.then(() => this.ensureDocSession(docId, doc, params?.auth));
914
1114
  return this.createRoomSubscription({
1115
+ roomKind: "doc",
1116
+ roomId: docId,
915
1117
  rawSessionPromise,
916
1118
  releaseAcquisition,
917
1119
  initialStatus: existing && existing.doc === doc ? existing.statusEmitter.status : "connecting",
@@ -929,7 +1131,7 @@ var StreamsTransportAdapter = class {
929
1131
  waitForFirstSync: (session) => this.waitForDocFirstSync(session),
930
1132
  getActiveSubscription: (session) => this.getActiveDocSubscription(session),
931
1133
  rejoin: (session) => this.rejoinDocSession(session),
932
- createWaitError: () => createDocJoinError(docId)
1134
+ createWaitError: (error) => this.createDocJoinError(docId, error)
933
1135
  });
934
1136
  }
935
1137
  async syncFlockDoc(flockDocId, flock, options) {
@@ -1024,6 +1226,8 @@ var StreamsTransportAdapter = class {
1024
1226
  const existing = this.flockDocSessions.get(flockDocId);
1025
1227
  const rawSessionPromise = ownership.ready.then(() => this.ensureFlockDocSession(flockDocId, flock, params?.auth));
1026
1228
  return this.createRoomSubscription({
1229
+ roomKind: "flock-doc",
1230
+ roomId: flockDocId,
1027
1231
  rawSessionPromise,
1028
1232
  releaseAcquisition,
1029
1233
  initialStatus: existing && existing.flock === flock ? existing.statusEmitter.status : "connecting",
@@ -1041,7 +1245,7 @@ var StreamsTransportAdapter = class {
1041
1245
  waitForFirstSync: (session) => this.waitForFlockDocFirstSync(session),
1042
1246
  getActiveSubscription: (session) => this.getActiveFlockDocSubscription(session),
1043
1247
  rejoin: (session) => this.rejoinFlockDocSession(session),
1044
- createWaitError: () => createFlockDocJoinError(flockDocId)
1248
+ createWaitError: (error) => this.createFlockDocJoinError(flockDocId, error)
1045
1249
  });
1046
1250
  }
1047
1251
  /**
@@ -1095,6 +1299,11 @@ var StreamsTransportAdapter = class {
1095
1299
  }
1096
1300
  createRoomSubscription(options) {
1097
1301
  if (options === void 0) throw createSubscriptionClosedError();
1302
+ const joinContext = {
1303
+ phase: "join",
1304
+ roomKind: options.roomKind,
1305
+ roomId: options.roomId
1306
+ };
1098
1307
  const statusProxy = createStatusEmitter(options.initialStatus);
1099
1308
  let unsubscribed = false;
1100
1309
  let retained = false;
@@ -1140,7 +1349,14 @@ var StreamsTransportAdapter = class {
1140
1349
  releaseAcquisition?.();
1141
1350
  releaseAcquisition = void 0;
1142
1351
  emitStatus(statusProxy, "error");
1143
- throw error;
1352
+ const typed = this.toTransportError(error, joinContext);
1353
+ this.diagnose({
1354
+ level: "warn",
1355
+ event: "join.room.failed",
1356
+ ...joinContext,
1357
+ error: typed
1358
+ });
1359
+ throw typed;
1144
1360
  });
1145
1361
  const requireActiveSession = async () => {
1146
1362
  const activePromise = sessionPromise;
@@ -1197,7 +1413,7 @@ var StreamsTransportAdapter = class {
1197
1413
  try {
1198
1414
  await activeSubscription.waitUntilSynced();
1199
1415
  } catch (error) {
1200
- throw sanitizeStreamsRoomError(error, createError);
1416
+ throw sanitizeStreamsRoomError(error, () => createError(activeSubscription.lastError));
1201
1417
  }
1202
1418
  },
1203
1419
  rejoin: async () => {
@@ -1222,19 +1438,19 @@ var StreamsTransportAdapter = class {
1222
1438
  joinMetaSession(session) {
1223
1439
  return this.joinSession(session, {
1224
1440
  isCurrent: (candidate) => this.metaSession === candidate,
1225
- createJoinError: createMetaJoinError
1441
+ createJoinError: (error) => this.createMetaJoinError(error)
1226
1442
  });
1227
1443
  }
1228
1444
  joinDocSession(session) {
1229
1445
  return this.joinSession(session, {
1230
1446
  isCurrent: (candidate) => this.docSessions.get(candidate.docId) === candidate,
1231
- createJoinError: (error) => createDocJoinError(session.docId, error)
1447
+ createJoinError: (error) => this.createDocJoinError(session.docId, error)
1232
1448
  });
1233
1449
  }
1234
1450
  joinFlockDocSession(session) {
1235
1451
  return this.joinSession(session, {
1236
1452
  isCurrent: (candidate) => this.flockDocSessions.get(candidate.flockDocId) === candidate,
1237
- createJoinError: (error) => createFlockDocJoinError(session.flockDocId, error)
1453
+ createJoinError: (error) => this.createFlockDocJoinError(session.flockDocId, error)
1238
1454
  });
1239
1455
  }
1240
1456
  joinSession(session, options) {
@@ -1255,11 +1471,13 @@ var StreamsTransportAdapter = class {
1255
1471
  } };
1256
1472
  const joinResult = await session.stream.join(joinParams);
1257
1473
  if (!joinResult.ok) {
1474
+ let failure = joinResult.error;
1258
1475
  if (joinResult.error.retryable) {
1259
1476
  const retainedJoin = await session.stream.join(joinParams);
1260
1477
  if (retainedJoin.ok) return this.retainJoinedSubscription(session, retainedJoin.value, options);
1478
+ failure = retainedJoin.error;
1261
1479
  }
1262
- throw options.createJoinError(joinResult.error);
1480
+ throw options.createJoinError(failure);
1263
1481
  }
1264
1482
  return this.retainJoinedSubscription(session, joinResult.value, options);
1265
1483
  } catch (error) {
@@ -1292,45 +1510,45 @@ var StreamsTransportAdapter = class {
1292
1510
  if (session.closed) return Promise.reject(createSubscriptionClosedError());
1293
1511
  if (session.subscription) return Promise.resolve(session.subscription);
1294
1512
  if (session.joinPromise) return session.joinPromise;
1295
- return Promise.reject(session.lastJoinError ?? createMetaJoinError());
1513
+ return Promise.reject(session.lastJoinError ?? this.createMetaJoinError());
1296
1514
  }
1297
1515
  async waitForMetaFirstSync(session) {
1298
1516
  const subscription = await this.joinMetaSession(session);
1299
1517
  try {
1300
1518
  await subscription.waitUntilSynced();
1301
1519
  } catch (error) {
1302
- if (subscription.lastError) throw createMetaJoinError(subscription.lastError);
1303
- throw sanitizeStreamsRoomError(error, () => createMetaJoinError());
1520
+ if (subscription.lastError) throw this.createMetaJoinError(subscription.lastError);
1521
+ throw sanitizeStreamsRoomError(error, () => this.createMetaJoinError());
1304
1522
  }
1305
1523
  }
1306
1524
  getActiveDocSubscription(session) {
1307
1525
  if (session.closed) return Promise.reject(createSubscriptionClosedError());
1308
1526
  if (session.subscription) return Promise.resolve(session.subscription);
1309
1527
  if (session.joinPromise) return session.joinPromise;
1310
- return Promise.reject(session.lastJoinError ?? createDocJoinError(session.docId));
1528
+ return Promise.reject(session.lastJoinError ?? this.createDocJoinError(session.docId));
1311
1529
  }
1312
1530
  async waitForDocFirstSync(session) {
1313
1531
  const subscription = await this.joinDocSession(session);
1314
1532
  try {
1315
1533
  await subscription.waitUntilSynced();
1316
1534
  } catch (error) {
1317
- if (subscription.lastError) throw createDocJoinError(session.docId, subscription.lastError);
1318
- throw sanitizeStreamsRoomError(error, () => createDocJoinError(session.docId));
1535
+ if (subscription.lastError) throw this.createDocJoinError(session.docId, subscription.lastError);
1536
+ throw sanitizeStreamsRoomError(error, () => this.createDocJoinError(session.docId));
1319
1537
  }
1320
1538
  }
1321
1539
  getActiveFlockDocSubscription(session) {
1322
1540
  if (session.closed) return Promise.reject(createSubscriptionClosedError());
1323
1541
  if (session.subscription) return Promise.resolve(session.subscription);
1324
1542
  if (session.joinPromise) return session.joinPromise;
1325
- return Promise.reject(session.lastJoinError ?? createFlockDocJoinError(session.flockDocId));
1543
+ return Promise.reject(session.lastJoinError ?? this.createFlockDocJoinError(session.flockDocId));
1326
1544
  }
1327
1545
  async waitForFlockDocFirstSync(session) {
1328
1546
  const subscription = await this.joinFlockDocSession(session);
1329
1547
  try {
1330
1548
  await subscription.waitUntilSynced();
1331
1549
  } catch (error) {
1332
- if (subscription.lastError) throw createFlockDocJoinError(session.flockDocId, subscription.lastError);
1333
- throw sanitizeStreamsRoomError(error, () => createFlockDocJoinError(session.flockDocId));
1550
+ if (subscription.lastError) throw this.createFlockDocJoinError(session.flockDocId, subscription.lastError);
1551
+ throw sanitizeStreamsRoomError(error, () => this.createFlockDocJoinError(session.flockDocId));
1334
1552
  }
1335
1553
  }
1336
1554
  async rejoinMetaSession(session) {