@frondruntime/devtools 0.3.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/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +123 -0
- package/dist/chunk-8xwbnbvs.js +164 -0
- package/dist/chunk-8xwbnbvs.js.map +10 -0
- package/dist/index.d.ts +1062 -0
- package/dist/index.js +705 -0
- package/dist/index.js.map +18 -0
- package/dist/node.d.ts +48 -0
- package/dist/node.js +45 -0
- package/dist/node.js.map +10 -0
- package/package.json +73 -0
- package/src/attach.ts +256 -0
- package/src/attachDevtools.ts +221 -0
- package/src/cause.ts +369 -0
- package/src/descriptors.ts +107 -0
- package/src/encode.ts +154 -0
- package/src/full.ts +232 -0
- package/src/index.ts +15 -0
- package/src/node.ts +110 -0
- package/src/policy.ts +37 -0
- package/src/protocol.ts +458 -0
- package/src/shape.ts +161 -0
- package/src/snapshot.ts +229 -0
package/src/attach.ts
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
import type { Runtime } from "@frondruntime/core";
|
|
2
|
+
import { Clock, Effect, Layer, Stream } from "effect";
|
|
3
|
+
import { RpcClient, RpcSerialization } from "effect/unstable/rpc";
|
|
4
|
+
import { Socket } from "effect/unstable/socket";
|
|
5
|
+
import { encodeRecord } from "./encode.ts";
|
|
6
|
+
import { type EncodePolicy, resolvePolicy } from "./policy.ts";
|
|
7
|
+
import {
|
|
8
|
+
type AttachmentInfo,
|
|
9
|
+
type EncodedEventRecord,
|
|
10
|
+
FrondHubRpcs,
|
|
11
|
+
HUB_PROTOCOL_VERSION,
|
|
12
|
+
type HubCommand,
|
|
13
|
+
type QueryOutcome,
|
|
14
|
+
type ValuePolicy,
|
|
15
|
+
} from "./protocol.ts";
|
|
16
|
+
import { encodeGraphSnapshot } from "./snapshot.ts";
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* How many encoded records are held between flushes.
|
|
20
|
+
*
|
|
21
|
+
* When this fills, further records are counted and discarded rather than
|
|
22
|
+
* buffered without bound: an attached app must never be slowed down, let alone
|
|
23
|
+
* grow unboundedly, because a devtools consumer stopped reading. The count
|
|
24
|
+
* travels as `droppedSince`, so the hub always knows a gap happened.
|
|
25
|
+
*/
|
|
26
|
+
const MAX_BUFFERED_RECORDS = 4096;
|
|
27
|
+
|
|
28
|
+
const FLUSH_INTERVAL = "250 millis";
|
|
29
|
+
|
|
30
|
+
export type AttachOptions = {
|
|
31
|
+
readonly runtime: Runtime.Runtime;
|
|
32
|
+
readonly attachUrl: string;
|
|
33
|
+
/** Human label for the hub's list, e.g. the host app's package name. */
|
|
34
|
+
readonly name: string;
|
|
35
|
+
readonly platform: string;
|
|
36
|
+
/**
|
|
37
|
+
* The most this app will ever disclose, whatever the hub asks for.
|
|
38
|
+
*
|
|
39
|
+
* `"shape"` by default: structure, key names, lengths and types, but no
|
|
40
|
+
* values. Sending real values is a decision worth making per app rather than
|
|
41
|
+
* inheriting — the runtimes worth debugging are the ones holding tokens and
|
|
42
|
+
* account state, and a default that ships them is a default that ships them
|
|
43
|
+
* the first time someone forgets.
|
|
44
|
+
*/
|
|
45
|
+
readonly values?: ValuePolicy | undefined;
|
|
46
|
+
/**
|
|
47
|
+
* Stable identity for this attachment, unique across processes.
|
|
48
|
+
*
|
|
49
|
+
* Defaults to a fresh UUID, which is right for an ordinary app. The hub sets
|
|
50
|
+
* it explicitly so it can recognise its own self-attachment in the list it
|
|
51
|
+
* serves — `runtimeId` cannot do that job, because it comes from a
|
|
52
|
+
* per-process counter and every runtime's first one is `runtime-1`.
|
|
53
|
+
*
|
|
54
|
+
* Minted per *call*, not per attempt: `attachDevtools` reuses one across
|
|
55
|
+
* reconnects, so an app that outlives a hub restart comes back as itself.
|
|
56
|
+
*/
|
|
57
|
+
readonly instanceId?: string;
|
|
58
|
+
/** How many times this runtime has already attached. See `AttachmentInfo`. */
|
|
59
|
+
readonly generation?: number;
|
|
60
|
+
/**
|
|
61
|
+
* Called once the hub has accepted this attempt.
|
|
62
|
+
*
|
|
63
|
+
* Exists so the caller can count reconnections without having to guess from
|
|
64
|
+
* the outside which attempts got as far as being accepted.
|
|
65
|
+
*/
|
|
66
|
+
readonly onAttached?: (() => void) | undefined;
|
|
67
|
+
/**
|
|
68
|
+
* Return false to leave a record out of the stream entirely.
|
|
69
|
+
*
|
|
70
|
+
* Distinct from the drop counter below, and the difference matters: a drop is
|
|
71
|
+
* a gap the hub must be told about, because an agent reading the feed has to
|
|
72
|
+
* be able to tell "did not happen" from "was lost". A record excluded here
|
|
73
|
+
* was never in scope, so it is not a gap and is not counted as one.
|
|
74
|
+
*
|
|
75
|
+
* Exists for one caller — the hub, which observes the runtime it is also
|
|
76
|
+
* writing into and would otherwise feed itself forever. An ordinary app has
|
|
77
|
+
* no reason to pass this.
|
|
78
|
+
*/
|
|
79
|
+
readonly include?: (record: Runtime.RuntimeEventRecord) => boolean;
|
|
80
|
+
};
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Transport for one attachment.
|
|
84
|
+
*
|
|
85
|
+
* Exported because the hub dials itself over exactly this layer — same
|
|
86
|
+
* protocol, same serialization, same socket code path as a real app. If
|
|
87
|
+
* self-attach works, the transport works.
|
|
88
|
+
*/
|
|
89
|
+
export function attachLayer(attachUrl: string): Layer.Layer<RpcClient.Protocol> {
|
|
90
|
+
return RpcClient.layerProtocolSocket().pipe(
|
|
91
|
+
Layer.provide(Socket.layerWebSocket(attachUrl)),
|
|
92
|
+
Layer.provide(Socket.layerWebSocketConstructorGlobal),
|
|
93
|
+
Layer.provide(RpcSerialization.layerNdjson)
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Streams a runtime's events to a hub for as long as the connection lives.
|
|
99
|
+
*
|
|
100
|
+
* The returned Effect does not settle while attached — it *is* the attachment.
|
|
101
|
+
* Fork it into a scope and close the scope to detach; the hub learns about the
|
|
102
|
+
* detachment from the socket dying, which is the only mechanism that also works
|
|
103
|
+
* when the app crashes.
|
|
104
|
+
*/
|
|
105
|
+
export const attachRuntime = Effect.fnUntraced(function* (options: AttachOptions) {
|
|
106
|
+
const client = yield* RpcClient.make(FrondHubRpcs);
|
|
107
|
+
|
|
108
|
+
const ceiling: ValuePolicy = options.values ?? "shape";
|
|
109
|
+
|
|
110
|
+
let buffer: Array<EncodedEventRecord> = [];
|
|
111
|
+
let dropped = 0;
|
|
112
|
+
// Events fire between the socket opening and the `Attached` command arriving,
|
|
113
|
+
// and the conservative reading of an unanswered negotiation is the narrow
|
|
114
|
+
// one. Still clamped, so a ceiling of `"none"` holds from the first record.
|
|
115
|
+
let policy: EncodePolicy = resolvePolicy("shape", ceiling);
|
|
116
|
+
let attachmentId: string | undefined;
|
|
117
|
+
|
|
118
|
+
// Encoding happens here, at observe time, not at flush time: a
|
|
119
|
+
// `RuntimeEventRecord` carries live references that keep mutating after the
|
|
120
|
+
// record is handed out, so a record buffered raw would describe the graph as
|
|
121
|
+
// it is when flushed, not as it was when the event fired.
|
|
122
|
+
const subscription = options.runtime.observe((record) => {
|
|
123
|
+
// Before the buffer check, so an excluded record cannot be counted as a
|
|
124
|
+
// drop, and before encoding, so it costs nothing to exclude one.
|
|
125
|
+
if (options.include !== undefined && !options.include(record)) {
|
|
126
|
+
return;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
if (buffer.length >= MAX_BUFFERED_RECORDS) {
|
|
130
|
+
dropped += 1;
|
|
131
|
+
return;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
buffer.push(encodeRecord(record, policy));
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
yield* Effect.addFinalizer(() => Effect.sync(() => subscription.unsubscribe()));
|
|
138
|
+
|
|
139
|
+
const info: AttachmentInfo = {
|
|
140
|
+
protocolVersion: HUB_PROTOCOL_VERSION,
|
|
141
|
+
instanceId: options.instanceId ?? crypto.randomUUID(),
|
|
142
|
+
runtimeId: options.runtime.getSnapshotSync().runtimeId,
|
|
143
|
+
generation: options.generation ?? 0,
|
|
144
|
+
name: options.name,
|
|
145
|
+
platform: options.platform,
|
|
146
|
+
startedAt: yield* Clock.currentTimeMillis,
|
|
147
|
+
// Advertised so the hub can show what it is going to get. Advisory only:
|
|
148
|
+
// `resolvePolicy` below is what actually enforces it, because a ceiling a
|
|
149
|
+
// sender merely announces is one the sender can forget to apply.
|
|
150
|
+
values: ceiling,
|
|
151
|
+
};
|
|
152
|
+
|
|
153
|
+
const flushOnce = Effect.gen(function* () {
|
|
154
|
+
yield* Effect.sleep(FLUSH_INTERVAL);
|
|
155
|
+
|
|
156
|
+
const id = attachmentId;
|
|
157
|
+
|
|
158
|
+
if (id === undefined || (buffer.length === 0 && dropped === 0)) {
|
|
159
|
+
return;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
// Swapped, not drained: `observe` runs on whatever fiber produced the
|
|
163
|
+
// event, so anything appended during the send lands in the next batch
|
|
164
|
+
// instead of being lost to a splice race.
|
|
165
|
+
const records = buffer;
|
|
166
|
+
const droppedSince = dropped;
|
|
167
|
+
buffer = [];
|
|
168
|
+
dropped = 0;
|
|
169
|
+
|
|
170
|
+
yield* client["Frond.Ingest"]({ attachmentId: id, records, droppedSince });
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
yield* Effect.forkScoped(Effect.forever(flushOnce));
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Answers one query, on its own fiber.
|
|
177
|
+
*
|
|
178
|
+
* Forked rather than awaited inline because this runs on the command stream:
|
|
179
|
+
* a snapshot of a large graph is the most expensive thing this client does,
|
|
180
|
+
* and blocking here would stall the heartbeat and every query behind it
|
|
181
|
+
* behind one slow answer.
|
|
182
|
+
*
|
|
183
|
+
* Nothing in here is allowed to fail outward. A query that throws comes back
|
|
184
|
+
* as `Failed`, because the alternative is an error escaping into the stream
|
|
185
|
+
* handler and taking down an attachment over a question that was only ever
|
|
186
|
+
* advisory.
|
|
187
|
+
*/
|
|
188
|
+
const answer = (command: Extract<HubCommand, { readonly _tag: "Query" }>) =>
|
|
189
|
+
Effect.gen(function* () {
|
|
190
|
+
const id = attachmentId;
|
|
191
|
+
|
|
192
|
+
if (id === undefined) {
|
|
193
|
+
return;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
const capturedAt = yield* Clock.currentTimeMillis;
|
|
197
|
+
|
|
198
|
+
const outcome = yield* Effect.map(
|
|
199
|
+
Effect.exit(
|
|
200
|
+
Effect.sync(() => {
|
|
201
|
+
// Clamped against the ceiling, not against the stream's policy. A
|
|
202
|
+
// deliberate read may ask for more than the firehose gets, and may
|
|
203
|
+
// never ask for more than the app agreed to disclose.
|
|
204
|
+
const requested = resolvePolicy(command.values, ceiling);
|
|
205
|
+
|
|
206
|
+
return encodeGraphSnapshot(options.runtime.getSnapshotSync(), {
|
|
207
|
+
policy: requested,
|
|
208
|
+
capturedAt,
|
|
209
|
+
nodeId: command.query._tag === "Node" ? command.query.nodeId : undefined,
|
|
210
|
+
});
|
|
211
|
+
})
|
|
212
|
+
),
|
|
213
|
+
(exit): QueryOutcome =>
|
|
214
|
+
exit._tag === "Success"
|
|
215
|
+
? { _tag: "Snapshot", snapshot: exit.value }
|
|
216
|
+
: { _tag: "Failed", reason: failureReason(exit.cause) }
|
|
217
|
+
);
|
|
218
|
+
|
|
219
|
+
yield* Effect.ignore(
|
|
220
|
+
client["Frond.Reply"]({ attachmentId: id, requestId: command.requestId, outcome })
|
|
221
|
+
);
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
yield* Stream.runForEach(client["Frond.Attach"]({ info }), (command) => {
|
|
225
|
+
if (command._tag === "Attached") {
|
|
226
|
+
return Effect.sync(() => {
|
|
227
|
+
attachmentId = command.attachmentId;
|
|
228
|
+
policy = resolvePolicy(command.values, ceiling);
|
|
229
|
+
options.onAttached?.();
|
|
230
|
+
});
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
if (command._tag === "Query") {
|
|
234
|
+
return Effect.forkScoped(answer(command));
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
return Effect.void;
|
|
238
|
+
});
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* A reason string for a query that could not be answered.
|
|
243
|
+
*
|
|
244
|
+
* Deliberately thin. This travels to a hub that will show it to whoever asked,
|
|
245
|
+
* and the useful cases — an unstarted runtime, a node id that does not resolve —
|
|
246
|
+
* already say so in their message. Serializing a cause chain here would mean a
|
|
247
|
+
* second, competing account of failures next to the one the event stream
|
|
248
|
+
* already carries.
|
|
249
|
+
*/
|
|
250
|
+
function failureReason(cause: unknown): string {
|
|
251
|
+
if (cause instanceof Error) {
|
|
252
|
+
return cause.message === "" ? cause.name : cause.message;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
return String(cause);
|
|
256
|
+
}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import type { Runtime } from "@frondruntime/core";
|
|
2
|
+
import { Cause, Data, Effect, Fiber } from "effect";
|
|
3
|
+
import { attachLayer, attachRuntime } from "./attach.ts";
|
|
4
|
+
import { HUB_DEFAULT_ATTACH_URL, HubRejection, type ValuePolicy } from "./protocol.ts";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* How long to wait before dialing again.
|
|
8
|
+
*
|
|
9
|
+
* Fixed rather than backing off: the hub is a process on the same machine that
|
|
10
|
+
* a developer starts and stops by hand, and an app that had backed off to
|
|
11
|
+
* thirty seconds would spend most of a debugging session not yet reconnected.
|
|
12
|
+
* Two seconds of an idle loopback socket costs nothing worth measuring.
|
|
13
|
+
*/
|
|
14
|
+
const RETRY_DELAY = "2 seconds";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Ends the retry loop.
|
|
18
|
+
*
|
|
19
|
+
* A second error rather than reusing `HubRejection`, because the two travel in
|
|
20
|
+
* opposite directions through the same code: `HubRejection` arrives from the
|
|
21
|
+
* hub into an attempt that swallows everything, and this one has to get back
|
|
22
|
+
* *out* of that swallowing. Keeping them distinct is what lets the loop stop for
|
|
23
|
+
* exactly one thing.
|
|
24
|
+
*/
|
|
25
|
+
class AttachRefused extends Data.TaggedError("AttachRefused")<{
|
|
26
|
+
readonly reason: string;
|
|
27
|
+
}> {}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The hub's refusal, picked out of whatever else an attempt failed with.
|
|
31
|
+
*
|
|
32
|
+
* Matched on the error value's own identity, not on message text: a refusal is
|
|
33
|
+
* the one outcome that stops the loop forever, and "the message looked like a
|
|
34
|
+
* rejection" is not a property worth betting that on.
|
|
35
|
+
*
|
|
36
|
+
* The refusal is a typed failure here rather than a defect or a closed stream
|
|
37
|
+
* because the RPC roles are inverted from who dials — the app is the *client*,
|
|
38
|
+
* so the hub's `Attach` error channel is this side's error channel, and the
|
|
39
|
+
* decoded `HubRejection` lands as an ordinary `Fail` on the cause.
|
|
40
|
+
*/
|
|
41
|
+
function refusal(cause: Cause.Cause<unknown>): HubRejection | undefined {
|
|
42
|
+
for (const reason of cause.reasons) {
|
|
43
|
+
if (Cause.isFailReason(reason) && reason.error instanceof HubRejection) {
|
|
44
|
+
return reason.error;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
return undefined;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export type DevtoolsOptions = {
|
|
52
|
+
readonly runtime: Runtime.Runtime;
|
|
53
|
+
/** Human label for the hub's list, e.g. the host app's package name. */
|
|
54
|
+
readonly name: string;
|
|
55
|
+
/**
|
|
56
|
+
* Where to dial. Defaults to the hub's own default port on loopback.
|
|
57
|
+
*
|
|
58
|
+
* Worth setting for a non-default port, and required for anything that is not
|
|
59
|
+
* on the same host as the hub — a real iOS device or an Android emulator
|
|
60
|
+
* cannot reach `127.0.0.1`, and needs the developer machine's LAN address.
|
|
61
|
+
*/
|
|
62
|
+
readonly url?: string | undefined;
|
|
63
|
+
/** Free-form origin hint. Guessed from the environment when omitted. */
|
|
64
|
+
readonly platform?: string | undefined;
|
|
65
|
+
/** See {@link import("./attach.ts").AttachOptions.values}. Defaults to `"shape"`. */
|
|
66
|
+
readonly values?: ValuePolicy | undefined;
|
|
67
|
+
readonly instanceId?: string | undefined;
|
|
68
|
+
/** Return false to leave a record out of the stream entirely. */
|
|
69
|
+
readonly include?: ((record: Runtime.RuntimeEventRecord) => boolean) | undefined;
|
|
70
|
+
/**
|
|
71
|
+
* Called instead of failing, on every attempt that ends badly.
|
|
72
|
+
*
|
|
73
|
+
* Silent by default, and that is the right default: not being able to reach
|
|
74
|
+
* the hub is the *normal* state of an app whose developer has not started one
|
|
75
|
+
* yet, and a devtools client that logged about it once every two seconds
|
|
76
|
+
* would be a worse citizen of the console than one that says nothing.
|
|
77
|
+
*
|
|
78
|
+
* The one exception is a hub that *refuses* the attachment, which is terminal
|
|
79
|
+
* rather than normal. Supplying this takes ownership of reporting it: the
|
|
80
|
+
* console fallback below fires only when this is absent.
|
|
81
|
+
*/
|
|
82
|
+
readonly onError?: ((cause: unknown) => void) | undefined;
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Streams a runtime's events to a local hub for as long as the app lives.
|
|
87
|
+
*
|
|
88
|
+
* The plain-function front door, as opposed to {@link attachRuntime}: a host
|
|
89
|
+
* app's entry file is not an Effect program, and making one the price of
|
|
90
|
+
* admission would put this behind a rewrite nobody is going to do.
|
|
91
|
+
*
|
|
92
|
+
* Three properties make it safe to leave in an entry file behind nothing but a
|
|
93
|
+
* dev check. It never throws and never rejects, so a devtools client cannot
|
|
94
|
+
* take down the app it is observing. It retries forever, so the hub can be
|
|
95
|
+
* started, stopped and restarted underneath a running app. And it returns
|
|
96
|
+
* before it connects, so it costs the startup path nothing.
|
|
97
|
+
*
|
|
98
|
+
* "Forever" has one deliberate exception. A hub that *refuses* the attachment —
|
|
99
|
+
* today, only a protocol version mismatch — is answering a question about this
|
|
100
|
+
* build, and every retry would ask it again and get the same answer. So a
|
|
101
|
+
* refusal stops the loop and says so out loud, because the alternative is what
|
|
102
|
+
* this used to do: reconnect every two seconds, silently, for the whole life of
|
|
103
|
+
* a process that was never going to attach.
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* ```ts
|
|
107
|
+
* if (import.meta.env.DEV) {
|
|
108
|
+
* attachDevtools({ runtime, name: "checkout-web" });
|
|
109
|
+
* }
|
|
110
|
+
* ```
|
|
111
|
+
*
|
|
112
|
+
* @returns A function that detaches. Idempotent, and safe to ignore.
|
|
113
|
+
*/
|
|
114
|
+
export function attachDevtools(options: DevtoolsOptions): () => void {
|
|
115
|
+
const url = options.url ?? HUB_DEFAULT_ATTACH_URL;
|
|
116
|
+
|
|
117
|
+
// Minted here rather than per attempt, so a hub restart underneath a running
|
|
118
|
+
// app brings back the same runtime instead of an apparent stranger. Paired
|
|
119
|
+
// with `generation` below, which is what says how many times that happened.
|
|
120
|
+
const instanceId = options.instanceId ?? crypto.randomUUID();
|
|
121
|
+
|
|
122
|
+
let generation = 0;
|
|
123
|
+
|
|
124
|
+
// Deferred so each attempt reads the counter as it stands, and bumped only
|
|
125
|
+
// when the hub accepted — a hub that is simply not running yet must not
|
|
126
|
+
// inflate this every two seconds.
|
|
127
|
+
const session = Effect.suspend(() =>
|
|
128
|
+
attachRuntime({
|
|
129
|
+
runtime: options.runtime,
|
|
130
|
+
attachUrl: url,
|
|
131
|
+
name: options.name,
|
|
132
|
+
platform: options.platform ?? detectPlatform(),
|
|
133
|
+
instanceId,
|
|
134
|
+
generation,
|
|
135
|
+
onAttached: () => {
|
|
136
|
+
generation += 1;
|
|
137
|
+
},
|
|
138
|
+
...(options.values === undefined ? {} : { values: options.values }),
|
|
139
|
+
...(options.include === undefined ? {} : { include: options.include }),
|
|
140
|
+
})
|
|
141
|
+
).pipe(
|
|
142
|
+
Effect.scoped,
|
|
143
|
+
Effect.provide(attachLayer(url)),
|
|
144
|
+
// `catchCause`, not `catch`: a defect in the transport is exactly as much
|
|
145
|
+
// the host app's problem as a failure is, which is to say none.
|
|
146
|
+
Effect.catchCause((cause) => {
|
|
147
|
+
options.onError?.(cause);
|
|
148
|
+
|
|
149
|
+
const refused = refusal(cause);
|
|
150
|
+
|
|
151
|
+
// Every other ending is worth another attempt — a hub not started yet, a
|
|
152
|
+
// socket dropped, a port moved — and retrying them is the behavior this
|
|
153
|
+
// whole loop exists for. A refusal is not one of those: the next attempt
|
|
154
|
+
// sends the same version and earns the same answer, so it leaves as a
|
|
155
|
+
// failure, which is the one thing `forever` below does not swallow.
|
|
156
|
+
return refused === undefined ? Effect.void : new AttachRefused({ reason: refused.reason });
|
|
157
|
+
})
|
|
158
|
+
);
|
|
159
|
+
|
|
160
|
+
// `forever` over a *caught* attempt rather than `retry` over a failing one,
|
|
161
|
+
// so the loop is reached by both outcomes. A hub that closes the stream
|
|
162
|
+
// cleanly on shutdown is a success, and a success that stopped reconnecting
|
|
163
|
+
// would leave the app permanently detached from the next hub.
|
|
164
|
+
const fiber = Effect.runFork(
|
|
165
|
+
Effect.forever(Effect.andThen(session, Effect.sleep(RETRY_DELAY))).pipe(
|
|
166
|
+
Effect.catchTag("AttachRefused", (refused) =>
|
|
167
|
+
Effect.sync(() => {
|
|
168
|
+
// Reached at most once per call, and that is structural rather than
|
|
169
|
+
// guarded by a flag: getting here at all means the loop has stopped.
|
|
170
|
+
//
|
|
171
|
+
// Written to the console only when nobody asked for the causes. An
|
|
172
|
+
// app that passed `onError` has already been told, in the handler it
|
|
173
|
+
// supplied, and owns what it does with it; an app that did not would
|
|
174
|
+
// otherwise be left with devtools that will never connect and nothing
|
|
175
|
+
// anywhere saying so — which is the exact failure this whole change
|
|
176
|
+
// is about, and a silent default would only move it one layer down.
|
|
177
|
+
if (options.onError === undefined) {
|
|
178
|
+
console.error(`[frond] devtools attach refused: ${refused.reason}`);
|
|
179
|
+
}
|
|
180
|
+
})
|
|
181
|
+
)
|
|
182
|
+
)
|
|
183
|
+
);
|
|
184
|
+
|
|
185
|
+
return () => {
|
|
186
|
+
Effect.runFork(Fiber.interrupt(fiber));
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** What `detectPlatform` reads. Everything on it is assumed absent. */
|
|
191
|
+
type PlatformGlobals = {
|
|
192
|
+
readonly document?: unknown;
|
|
193
|
+
readonly navigator?: { readonly product?: string };
|
|
194
|
+
readonly process?: { readonly versions?: { readonly bun?: string } };
|
|
195
|
+
};
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* A best-effort origin hint for the hub's list.
|
|
199
|
+
*
|
|
200
|
+
* Read off `globalThis` rather than referenced directly, for two reasons: a
|
|
201
|
+
* bare `process` in a browser is a ReferenceError rather than `undefined`, and
|
|
202
|
+
* naming it directly would drag `@types/node` into an entry point whose whole
|
|
203
|
+
* claim is that it does not depend on Node.
|
|
204
|
+
*/
|
|
205
|
+
function detectPlatform(): string {
|
|
206
|
+
const globals = globalThis as PlatformGlobals;
|
|
207
|
+
|
|
208
|
+
if (globals.document !== undefined) {
|
|
209
|
+
return "web";
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
if (globals.navigator?.product === "ReactNative") {
|
|
213
|
+
return "react-native";
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
if (globals.process !== undefined) {
|
|
217
|
+
return globals.process.versions?.bun === undefined ? "node" : "bun";
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
return "unknown";
|
|
221
|
+
}
|