Skip to content

Commit 9bc191b

Browse files
Minimize catch-up bytes: afterSequence from warm cache + HTTP shell snapshot
Part 1 (thread warm-cache): persist the snapshot sequence alongside the cached thread (StoredThreadSnapshot v2) so a re-opened thread resumes from the cached sequence via afterSequence — receiving only events since then — instead of re-downloading its full body. Cold cache still loads the full snapshot over HTTP. Part 2 (shell): the shell subscription now resumes the same way. Added an afterSequence input to subscribeShell (server replays shell events after the cursor, buffering live events before the catch-up replay, as in the thread path) and a GET /api/orchestration/shell endpoint so a cold-cache full shell rides HTTP instead of the socket. The client passes the cached/loaded shell sequence. Shared the environment auth-header builder across the thread and shell HTTP loaders. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent 6731ade commit 9bc191b

16 files changed

Lines changed: 490 additions & 143 deletions

File tree

‎apps/mobile/src/connection/runtime.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { Connection } from "@t3tools/client-runtime/connection";
2+
import { shellSnapshotLoaderLayer } from "@t3tools/client-runtime/state/shell";
23
import { threadSnapshotLoaderLayer } from "@t3tools/client-runtime/state/threads";
34
import * as Layer from "effect/Layer";
45
import { Atom } from "effect/unstable/reactivity";
@@ -10,13 +11,15 @@ const providedConnectionPlatformLayer = connectionPlatformLayer.pipe(
1011
Layer.provide(runtimeContextLayer),
1112
);
1213

14+
const snapshotLoaderLayer = Layer.merge(threadSnapshotLoaderLayer, shellSnapshotLoaderLayer);
15+
1316
type ConnectionLayerSource =
1417
| typeof Connection.layer
15-
| typeof threadSnapshotLoaderLayer
18+
| typeof snapshotLoaderLayer
1619
| typeof runtimeContextLayer
1720
| typeof connectionPlatformLayer;
1821

19-
const connectionLayer = Layer.merge(Connection.layer, threadSnapshotLoaderLayer).pipe(
22+
const connectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
2023
Layer.provideMerge(Layer.mergeAll(runtimeContextLayer, providedConnectionPlatformLayer)),
2124
);
2225

‎apps/mobile/src/connection/storage.ts‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ import {
1616
} from "@t3tools/client-runtime/connection";
1717
import {
1818
EnvironmentId,
19-
OrchestrationThread,
2019
OrchestrationShellSnapshot,
20+
OrchestrationThreadDetailSnapshot,
2121
ThreadId,
2222
} from "@t3tools/contracts";
2323
import * as Context from "effect/Context";
@@ -32,7 +32,10 @@ import { makeCatalogStore, type SecureCatalogStorage } from "./catalog-store";
3232
const SHELL_SNAPSHOT_CACHE_SCHEMA_VERSION = 1;
3333
const SHELL_SNAPSHOT_CACHE_DIRECTORY = "connection-shell-snapshots";
3434
const LEGACY_SHELL_SNAPSHOT_CACHE_DIRECTORY = "shell-snapshots";
35-
const THREAD_SNAPSHOT_CACHE_SCHEMA_VERSION = 1;
35+
// v2 stores the snapshot sequence alongside the thread so a warm cache can
36+
// resume via `afterSequence` instead of re-downloading the full thread body.
37+
// Older v1 entries (no sequence) fail to decode and are treated as a cold cache.
38+
const THREAD_SNAPSHOT_CACHE_SCHEMA_VERSION = 2;
3639
const THREAD_SNAPSHOT_CACHE_DIRECTORY = "connection-thread-snapshots";
3740

3841
const StoredShellSnapshot = Schema.Struct({
@@ -45,7 +48,7 @@ const StoredThreadSnapshot = Schema.Struct({
4548
schemaVersion: Schema.Literal(THREAD_SNAPSHOT_CACHE_SCHEMA_VERSION),
4649
environmentId: EnvironmentId,
4750
threadId: ThreadId,
48-
thread: OrchestrationThread,
51+
snapshot: OrchestrationThreadDetailSnapshot,
4952
});
5053

5154
const LegacyStoredShellSnapshot = Schema.Struct({
@@ -355,18 +358,18 @@ export const connectionStorageLayer = Layer.effectContext(
355358
Schema.decodeUnknownResult(StoredThreadSnapshot)(parsed),
356359
).pipe(Effect.mapError((cause) => shellPersistenceError("load-thread", cause)));
357360
return stored.environmentId === environmentId && stored.threadId === threadId
358-
? Option.some(stored.thread)
361+
? Option.some(stored.snapshot)
359362
: Option.none();
360363
}),
361-
saveThread: (environmentId, thread) =>
364+
saveThread: (environmentId, snapshot) =>
362365
Effect.gen(function* () {
363-
const file = yield* threadSnapshotFile(environmentId, thread.id, "save-thread");
366+
const file = yield* threadSnapshotFile(environmentId, snapshot.thread.id, "save-thread");
364367
const encoded = yield* Effect.fromResult(
365368
Schema.encodeUnknownResult(StoredThreadSnapshot)({
366369
schemaVersion: THREAD_SNAPSHOT_CACHE_SCHEMA_VERSION,
367370
environmentId,
368-
threadId: thread.id,
369-
thread,
371+
threadId: snapshot.thread.id,
372+
snapshot,
370373
}),
371374
).pipe(Effect.mapError((cause) => shellPersistenceError("save-thread", cause)));
372375
yield* Effect.try({

‎apps/server/src/orchestration/http.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,20 @@ export const orchestrationHttpApiLayer = HttpApiBuilder.group(
4040
);
4141
}),
4242
)
43+
.handle(
44+
"shellSnapshot",
45+
Effect.fn("environment.orchestration.shellSnapshot")(function* (args) {
46+
yield* annotateEnvironmentRequest(args.endpoint.name);
47+
yield* requireEnvironmentScope(AuthOrchestrationReadScope);
48+
return yield* projectionSnapshotQuery
49+
.getShellSnapshot()
50+
.pipe(
51+
Effect.catch((cause) =>
52+
failEnvironmentInternal("orchestration_snapshot_failed", cause),
53+
),
54+
);
55+
}),
56+
)
4357
.handle(
4458
"threadSnapshot",
4559
Effect.fn("environment.orchestration.threadSnapshot")(function* (args) {

‎apps/server/src/ws.ts‎

Lines changed: 46 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ import {
3030
OrchestrationDispatchCommandError,
3131
type OrchestrationEvent,
3232
type OrchestrationShellStreamEvent,
33+
type OrchestrationShellStreamItem,
3334
type OrchestrationThreadStreamItem,
3435
OrchestrationGetFullThreadDiffError,
3536
OrchestrationGetSnapshotError,
@@ -1060,10 +1061,54 @@ const makeWsRpcLayer = (
10601061
),
10611062
{ "rpc.aggregate": "orchestration" },
10621063
),
1063-
[ORCHESTRATION_WS_METHODS.subscribeShell]: (_input) =>
1064+
[ORCHESTRATION_WS_METHODS.subscribeShell]: (input) =>
10641065
observeRpcStreamEffect(
10651066
ORCHESTRATION_WS_METHODS.subscribeShell,
10661067
Effect.gen(function* () {
1068+
const liveStream = orchestrationEngine.streamDomainEvents.pipe(
1069+
Stream.mapEffect(toShellStreamEvent),
1070+
Stream.flatMap((event) =>
1071+
Option.isSome(event) ? Stream.succeed(event.value) : Stream.empty,
1072+
),
1073+
);
1074+
1075+
// When the client already holds a shell snapshot (cached, or loaded
1076+
// over HTTP) it passes that snapshot's sequence, and we resume by
1077+
// replaying shell events after it instead of re-sending the whole
1078+
// projects/threads list over the socket. As in the thread path, the
1079+
// live subscription is attached (into a scope-bound buffer) before
1080+
// draining the catch-up replay so no event published during the
1081+
// replay window is lost; overlapping events are deduped by sequence
1082+
// on the client. The full range is read (not the store's default
1083+
// page limit) since the shell filter runs after reading.
1084+
if (input.afterSequence !== undefined) {
1085+
const afterSequence = input.afterSequence;
1086+
return Stream.unwrap(
1087+
Effect.gen(function* () {
1088+
const liveBuffer = yield* Queue.unbounded<OrchestrationShellStreamItem>();
1089+
yield* Effect.forkScoped(
1090+
liveStream.pipe(Stream.runForEach((item) => Queue.offer(liveBuffer, item))),
1091+
);
1092+
const catchUpStream = orchestrationEngine
1093+
.readEvents(afterSequence, Number.MAX_SAFE_INTEGER)
1094+
.pipe(
1095+
Stream.mapEffect(toShellStreamEvent),
1096+
Stream.flatMap((event) =>
1097+
Option.isSome(event) ? Stream.succeed(event.value) : Stream.empty,
1098+
),
1099+
Stream.mapError(
1100+
(cause) =>
1101+
new OrchestrationGetSnapshotError({
1102+
message: "Failed to replay orchestration shell events",
1103+
cause,
1104+
}),
1105+
),
1106+
);
1107+
return Stream.concat(catchUpStream, Stream.fromQueue(liveBuffer));
1108+
}),
1109+
);
1110+
}
1111+
10671112
const snapshot = yield* projectionSnapshotQuery.getShellSnapshot().pipe(
10681113
Effect.tapError((cause) =>
10691114
Effect.logError("orchestration shell snapshot load failed", { cause }),
@@ -1077,13 +1122,6 @@ const makeWsRpcLayer = (
10771122
),
10781123
);
10791124

1080-
const liveStream = orchestrationEngine.streamDomainEvents.pipe(
1081-
Stream.mapEffect(toShellStreamEvent),
1082-
Stream.flatMap((event) =>
1083-
Option.isSome(event) ? Stream.succeed(event.value) : Stream.empty,
1084-
),
1085-
);
1086-
10871125
return Stream.concat(
10881126
Stream.make({
10891127
kind: "snapshot" as const,

‎apps/web/src/connection/runtime.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { Connection } from "@t3tools/client-runtime/connection";
2+
import { shellSnapshotLoaderLayer } from "@t3tools/client-runtime/state/shell";
23
import { threadSnapshotLoaderLayer } from "@t3tools/client-runtime/state/threads";
34
import * as Layer from "effect/Layer";
45
import { Atom } from "effect/unstable/reactivity";
@@ -10,13 +11,15 @@ const providedConnectionPlatformLayer = connectionPlatformLayer.pipe(
1011
Layer.provide(runtimeContextLayer),
1112
);
1213

14+
const snapshotLoaderLayer = Layer.merge(threadSnapshotLoaderLayer, shellSnapshotLoaderLayer);
15+
1316
type ConnectionLayerSource =
1417
| typeof Connection.layer
15-
| typeof threadSnapshotLoaderLayer
18+
| typeof snapshotLoaderLayer
1619
| typeof runtimeContextLayer
1720
| typeof connectionPlatformLayer;
1821

19-
const connectionLayer = Layer.merge(Connection.layer, threadSnapshotLoaderLayer).pipe(
22+
const connectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
2023
Layer.provideMerge(Layer.mergeAll(runtimeContextLayer, providedConnectionPlatformLayer)),
2124
);
2225

‎apps/web/src/connection/storage.ts‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import {
2020
import {
2121
EnvironmentId,
2222
OrchestrationShellSnapshot,
23-
OrchestrationThread,
23+
OrchestrationThreadDetailSnapshot,
2424
ThreadId,
2525
} from "@t3tools/contracts";
2626
import * as Context from "effect/Context";
@@ -45,11 +45,14 @@ const StoredShellSnapshot = Schema.Struct({
4545
snapshot: OrchestrationShellSnapshot,
4646
});
4747
const StoredShellSnapshotJson = Schema.fromJsonString(StoredShellSnapshot);
48+
// v2 stores the snapshot sequence alongside the thread so a warm cache can
49+
// resume via `afterSequence` instead of re-downloading the full thread body.
50+
// Older v1 entries (no sequence) fail to decode and are treated as a cold cache.
4851
const StoredThreadSnapshot = Schema.Struct({
49-
schemaVersion: Schema.Literal(1),
52+
schemaVersion: Schema.Literal(2),
5053
environmentId: EnvironmentId,
5154
threadId: ThreadId,
52-
thread: OrchestrationThread,
55+
snapshot: OrchestrationThreadDetailSnapshot,
5356
});
5457
const StoredThreadSnapshotJson = Schema.fromJsonString(StoredThreadSnapshot);
5558
const ConnectionCatalogDocumentJson = Schema.fromJsonString(ConnectionCatalogDocument);
@@ -473,7 +476,7 @@ export const connectionStorageLayer = Layer.effectContext(
473476
Effect.mapError((cause) => persistenceError("load-thread", cause)),
474477
Effect.map((stored) =>
475478
stored.environmentId === environmentId && stored.threadId === threadId
476-
? Option.some(stored.thread)
479+
? Option.some(stored.snapshot)
477480
: Option.none(),
478481
),
479482
);
@@ -484,18 +487,18 @@ export const connectionStorageLayer = Layer.effectContext(
484487
: persistenceError("load-thread", cause),
485488
),
486489
),
487-
saveThread: (environmentId, thread) =>
490+
saveThread: (environmentId, snapshot) =>
488491
Effect.gen(function* () {
489492
const encoded = yield* encodeStoredThreadSnapshot({
490-
schemaVersion: 1,
493+
schemaVersion: 2,
491494
environmentId,
492-
threadId: thread.id,
493-
thread,
495+
threadId: snapshot.thread.id,
496+
snapshot,
494497
}).pipe(Effect.mapError((cause) => persistenceError("save-thread", cause)));
495498
yield* writeDatabaseValue(
496499
database,
497500
THREAD_STORE_NAME,
498-
threadCacheKey(environmentId, thread.id),
501+
threadCacheKey(environmentId, snapshot.thread.id),
499502
encoded,
500503
);
501504
}).pipe(

‎packages/client-runtime/src/platform/persistence.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import {
22
type EnvironmentId,
3-
type OrchestrationThread,
43
type OrchestrationShellSnapshot,
4+
type OrchestrationThreadDetailSnapshot,
55
type ThreadId,
66
} from "@t3tools/contracts";
77
import * as Context from "effect/Context";
@@ -60,10 +60,13 @@ export class EnvironmentCacheStore extends Context.Service<
6060
readonly loadThread: (
6161
environmentId: EnvironmentId,
6262
threadId: ThreadId,
63-
) => Effect.Effect<Option.Option<OrchestrationThread>, ConnectionPersistenceError>;
63+
) => Effect.Effect<
64+
Option.Option<OrchestrationThreadDetailSnapshot>,
65+
ConnectionPersistenceError
66+
>;
6467
readonly saveThread: (
6568
environmentId: EnvironmentId,
66-
thread: OrchestrationThread,
69+
snapshot: OrchestrationThreadDetailSnapshot,
6770
) => Effect.Effect<void, ConnectionPersistenceError>;
6871
readonly removeThread: (
6972
environmentId: EnvironmentId,
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
import * as Effect from "effect/Effect";
2+
import * as Option from "effect/Option";
3+
import type { HttpMethod } from "effect/unstable/http";
4+
5+
import type { PreparedHttpAuthorization } from "../connection/model.ts";
6+
import type { ManagedRelayDpopSigner } from "../relay/managedRelay.ts";
7+
import { RemoteEnvironmentAuthFetchError } from "../rpc/http.ts";
8+
9+
export interface EnvironmentHttpAuthHeaders {
10+
readonly authorization?: string;
11+
readonly dpop?: string;
12+
}
13+
14+
/**
15+
* Build the authorization headers for an authenticated environment HTTP
16+
* request, matching the credential the connection was prepared with:
17+
* - primary/local connections carry no credential,
18+
* - bearer connections send a static `Bearer` token,
19+
* - relay connections send a `DPoP` access token with a freshly signed proof
20+
* bound to this request's method and URL.
21+
*
22+
* The DPoP signer is passed in (not resolved from context) and is only required
23+
* for relay/DPoP connections, so bearer/primary connections work even when no
24+
* signer is available.
25+
*/
26+
export const buildEnvironmentAuthHeaders = (
27+
authorization: PreparedHttpAuthorization | null,
28+
method: HttpMethod.HttpMethod,
29+
url: string,
30+
signer: Option.Option<ManagedRelayDpopSigner["Service"]>,
31+
): Effect.Effect<EnvironmentHttpAuthHeaders, RemoteEnvironmentAuthFetchError> =>
32+
Effect.gen(function* () {
33+
if (authorization === null) {
34+
return {};
35+
}
36+
if (authorization._tag === "Bearer") {
37+
return { authorization: `Bearer ${authorization.token}` };
38+
}
39+
if (Option.isNone(signer)) {
40+
return yield* new RemoteEnvironmentAuthFetchError({
41+
message: "No DPoP signer is available to authorize the environment request.",
42+
cause: authorization._tag,
43+
});
44+
}
45+
const proof = yield* signer.value
46+
.createProof({ method, url, accessToken: authorization.accessToken })
47+
.pipe(
48+
Effect.mapError(
49+
(cause) =>
50+
new RemoteEnvironmentAuthFetchError({
51+
message: "Could not create the environment request authorization proof.",
52+
cause,
53+
}),
54+
),
55+
);
56+
return { authorization: `DPoP ${authorization.accessToken}`, dpop: proof };
57+
});

0 commit comments

Comments
 (0)