@loro-dev/streams-crdt 0.11.1 → 0.12.1

package/README.md

@@ -54,6 +54,7 @@ if (!result.ok) {
       break;
     case "network_error":
     case "timeout":
+    case "initial_sync_timeout":
       // Transient — safe to retry.
       break;
     case "protocol_error":
@@ -101,6 +102,7 @@ if (err.code === "server_error") {
 | `gone`                 | 410      | yes       | yes    | —                              |
 | `server_error`         | 5xx      | yes       | yes    | `requestId?`, `retryAfterMs?`  |
 | `timeout`              | —        | yes       | —      | `phase: "connect" \| "poll"`   |
+| `initial_sync_timeout` | —        | yes       | —      | `operation`, `timeoutMs`, `elapsedMs` |
 | `network_error`        | —        | yes       | —      | —                              |
 | `auth_provider_error`  | —        | yes       | —      | `cause?` (original thrown value) |
 | `internal_error`       | —        | yes       | —      | —                              |
@@ -120,6 +122,33 @@ if (err.code === "server_error") {
   call `transport.rejoin()` after fixing the cause (e.g., refreshing the auth
   token) to reset retry state and reconnect.
 
+#### Initial sync deadlines
+
+Initial bootstrap/catch-up work is allowed to run longer than ordinary request
+connect and poll deadlines. The transport uses `reconnectConfig` for this:
+
+```ts
+const transport = new StreamsCrdt({
+  streamUrl,
+  adapter,
+  auth,
+  reconnectConfig: {
+    // Logs a debug diagnostic when initial sync is still pending; does not abort.
+    initialSyncSlowAfterMs: 30_000,
+    // Aborts initial bootstrap/catch-up with `initial_sync_timeout`.
+    initialSyncHardTimeoutMs: 120_000,
+  },
+});
+```
+
+`join()`, `sync()`, pull-only `catchup()`, and 410 bootstrap recovery all use
+the initial-sync deadline path when they need to bootstrap or catch up from a
+stored cursor. In `StreamsCrdt` constructor options, set
+`initialSyncHardTimeoutMs` to `0` or `Infinity` to disable the hard cap. Because
+constructor `reconnectConfig` is merged over defaults, omitting the field keeps
+the default hard cap. Set `initialSyncSlowAfterMs` the same way to disable the
+slow diagnostic.
+
 > **Why `Result` instead of `throw`?** Transport failures (network errors,
 > auth expiry, missing streams) are expected at runtime, not exceptional.
 > Wrapping them in `Result` makes the error path explicit in the type system
@@ -141,8 +170,8 @@ Only adjust if any of these apply:
   `stream_not_found` now requires `status: 404` + `message`; `gone` now
   requires `status: 410`. TypeScript will flag these.
 - **You exhaustively switch on `code` with a `: never` default.** Add a case
-  for `auth_provider_error` (and optionally `server_error` if you handled
-  5xx via `unknown`/`internal_error` before).
+  for `auth_provider_error` and `initial_sync_timeout` (and optionally
+  `server_error` if you handled 5xx via `unknown`/`internal_error` before).
 - **You used `"message" in error` to defensively narrow.** All variants now
   carry `message`; the guard is no longer needed.
 
@@ -164,6 +193,8 @@ const transport = new StreamsCrdt({
   }),
   auth: async () => "<gateway-jwt>",
   adapter: createLoroDocAdapter(doc),
+  // Optional TTL applied when the stream is created.
+  streamTtlSeconds: 60 * 60 * 24 * 30,
   // Enable automatic snapshot upload so new readers bootstrap faster.
   snapshotUpload: { canUpload: async () => true },
 });
@@ -205,16 +236,20 @@ const transport = new StreamsCrdt({
   adapter: createLoroDocAdapter(doc),
   shardUrls: {
     bootstrap: [
-      "https://control-a.streams-api-proxy.loro.dev",
-      "https://control-b.streams-api-proxy.loro.dev",
+      "https://control-a.api.streams-api-x.loro.dev",
+      "https://control-b.api.streams-api-x.loro.dev",
     ],
     catchup: [
-      "https://control-a.streams-api-proxy.loro.dev",
-      "https://control-b.streams-api-proxy.loro.dev",
+      "https://control-a.api.streams-api-x.loro.dev",
+      "https://control-b.api.streams-api-x.loro.dev",
     ],
     largePost: [
-      "https://write-a.streams-api-proxy.loro.dev",
-      "https://write-b.streams-api-proxy.loro.dev",
+      "https://write-a.api.streams-api-x.loro.dev",
+      "https://write-b.api.streams-api-x.loro.dev",
+    ],
+    other: [
+      "https://live-a.api.streams-api-x.loro.dev",
+      "https://live-b.api.streams-api-x.loro.dev",
     ],
     largePostMinBytes: 64 * 1024,
   },
@@ -225,12 +260,14 @@ Shard entries must be origin URLs with no path, query, or hash. Each transport
 instance rotates through the configured origins per operation, with a randomized
 starting point so multiple tabs are less likely to all begin on the same shard.
 Bootstrap applies to `GET <stream>/bootstrap`; catch-up applies to non-SSE
-offset reads, including long-poll fallback; SSE live reads stay on the original
-`streamUrl`. `largePost` applies to non-empty append POST bodies at or above
-`largePostMinBytes` bytes. The default threshold is `0`, so every non-empty
-append POST can use `largePost` when that pool is configured. Verify actual
-connection separation with browser NetLog: browsers may coalesce compatible
-HTTP/2 or HTTP/3 origins when DNS, certificate, and transport settings allow it.
+offset reads, including long-poll fallback. `largePost` applies to non-empty
+append POST bodies at or above `largePostMinBytes` bytes. `other` applies when
+no operation-specific pool routes the request, covering live SSE, create/delete,
+head, snapshot upload, and append POSTs not routed by `largePost`. The default
+threshold is `0`, so every non-empty append POST can use `largePost` when that
+pool is configured. Verify actual connection separation with browser NetLog:
+browsers may coalesce compatible HTTP/2 or HTTP/3 origins when DNS, certificate,
+and transport settings allow it.
 
 ### Loro pending imports and cursor safety
 
@@ -1050,6 +1087,7 @@ const transport = new StreamsCrdt({
   result types used to report incomplete imports such as Loro pending updates
 - `Result` — Rust-style `Ok | Err` result
 - `StreamsAuthProvider` — auth callback type
+- `StreamsCrdtShardUrlsOptions` — optional origin pools for request routing
 - `TransportError` — discriminated error union
   `apply_incomplete` is returned when remote data was read but the CRDT adapter
   still has unresolved dependencies and the cursor cannot be saved.
@@ -1105,6 +1143,9 @@ const transport = new StreamsCrdt({
 ## Notes
 
 - `createStreamIfMissing` defaults to `false` and only affects the initial sync/join bootstrap
+- `streamTtlSeconds` is a non-negative safe integer in seconds. It is sent only
+  when the transport creates the stream, either through `createStream()` or
+  automatic creation with `createStreamIfMissing`.
 - `deleteStream()` returns `{ deleted: false }` when the target stream is already missing
 - `sync()` and `join()` return `Result` objects instead of implicitly creating missing streams
 - `join()` resolves only after the initial replay has succeeded; without a stored remote cursor it bootstraps once, then prefers ordinary live SSE and falls back sticky to long-poll

package/dist/flock.d.ts

@@ -1,4 +1,4 @@
-import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DAAMJlvT.js";
+import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DJYQlTE2.js";
 import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 } from "@loro-dev/flock-wasm";
 
 //#region src/flock.d.ts

package/dist/flock.js

@@ -1,4 +1,4 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-fOF9ZqCH.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-D-UirMkk.js";
 import { Flock } from "@loro-dev/flock-wasm";
 //#region src/flock.ts
 function isAfter(entry, current) {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DAAMJlvT.js";
+import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DJYQlTE2.js";
 export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-fOF9ZqCH.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-D-UirMkk.js";
 export { PayloadProtectionError as E2eeError, PayloadProtectionError, EphemeralStreamCrdt, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, StreamsCrdt, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/loro.d.ts

@@ -1,4 +1,4 @@
-import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DAAMJlvT.js";
+import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DJYQlTE2.js";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/loro.d.ts

package/dist/loro.js

@@ -1,4 +1,4 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-fOF9ZqCH.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-D-UirMkk.js";
 import { LoroDoc, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 //#region src/loro.ts
 function batchImportUpdates(doc, updates) {