Skip to content

Commit 7e8db37

Browse files
author
DavidQ
committed
centralize network debug helpers
1 parent e1f9e76 commit 7e8db37

9 files changed

Lines changed: 139 additions & 106 deletions

File tree

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Execute BUILD_PR_SHARED_EXTRACTION_32_IS_OBJECT_BATCH.md exactly.
1+
Execute BUILD_PR_SHARED_EXTRACTION_33_NETWORK_DEBUG_HELPERS_BATCH.md exactly.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
centralize isObject
1+
centralize network debug helpers

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Next: network helpers batch
1+
Next: state system alignment

‎docs/dev/reports/change_summary.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
isObject centralized
1+
network debug helpers centralized

‎docs/pr/BUILD_PR_SHARED_EXTRACTION_33_NETWORK_DEBUG_HELPERS_BATCH.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# BUILD_PR_SHARED_EXTRACTION_33_NETWORK_DEBUG_HELPERS_BATCH
2+
3+
Centralize network debug helpers:
4+
5+
- toNetworkSnapshot
6+
- getCommandSnapshot
7+
- commandLinesForTrace
8+
9+
Create:
10+
src/shared/utils/networkDebugUtils.js
11+
12+
Update network_sample debug files only.
13+
14+
Constraints:
15+
- no behavior change
16+
- no engine edits

‎games/network_sample_a/debug/networkSampleADebug.js‎

Lines changed: 17 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ networkSampleADebug.js
77

88
import { createNetworkDebugPluginDefinition } from "../../../engine/debug/network/index.js";
99
import { asArray, asObject } from "../../../src/engine/debug/inspectors/shared/inspectorUtils.js";
10+
import {
11+
commandLinesForTrace,
12+
getCommandSnapshot,
13+
toNetworkSnapshot
14+
} from "../../../src/shared/utils/networkDebugUtils.js";
15+
16+
const NETWORK_SAMPLE_KEY = "networkSampleA";
1017

1118
function sanitizeText(value) {
1219
return typeof value === "string" ? value.trim() : "";
@@ -16,12 +23,8 @@ function asNumber(value, fallback = 0) {
1623
return Number.isFinite(value) ? Number(value) : fallback;
1724
}
1825

19-
function toNetworkSnapshot(snapshot) {
20-
return asObject(snapshot?.assets?.networkSampleA);
21-
}
22-
2326
function toConnectionLines(snapshot) {
24-
const network = toNetworkSnapshot(snapshot);
27+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
2528
const connection = asObject(network.connection);
2629
return [
2730
`phase=${sanitizeText(connection.phase) || "unknown"}`,
@@ -34,7 +37,7 @@ function toConnectionLines(snapshot) {
3437
}
3538

3639
function toLatencyLines(snapshot) {
37-
const network = toNetworkSnapshot(snapshot);
40+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
3841
const latency = asObject(network.latency);
3942
return [
4043
`status=${sanitizeText(latency.status) || "unknown"}`,
@@ -44,7 +47,7 @@ function toLatencyLines(snapshot) {
4447
}
4548

4649
function toTraceLines(snapshot, maxLines = 8) {
47-
const network = toNetworkSnapshot(snapshot);
50+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
4851
const trace = asObject(network.trace);
4952
const events = asArray(trace.events);
5053
if (events.length === 0) {
@@ -63,12 +66,8 @@ function toTraceLines(snapshot, maxLines = 8) {
6366
});
6467
}
6568

66-
function getCommandSnapshot(context) {
67-
return asObject(context?.assets?.networkSampleA);
68-
}
69-
7069
function commandLinesForStatus(context) {
71-
const snapshot = getCommandSnapshot(context);
70+
const snapshot = getCommandSnapshot(context, NETWORK_SAMPLE_KEY);
7271
const connection = asObject(snapshot.connection);
7372
const replication = asObject(snapshot.replication);
7473
return [
@@ -82,7 +81,7 @@ function commandLinesForStatus(context) {
8281
}
8382

8483
function commandLinesForLatency(context) {
85-
const snapshot = getCommandSnapshot(context);
84+
const snapshot = getCommandSnapshot(context, NETWORK_SAMPLE_KEY);
8685
const latency = asObject(snapshot.latency);
8786
return [
8887
`status=${sanitizeText(latency.status) || "unknown"}`,
@@ -91,37 +90,6 @@ function commandLinesForLatency(context) {
9190
];
9291
}
9392

94-
function commandLinesForTrace(context, args = []) {
95-
const snapshot = getCommandSnapshot(context);
96-
const trace = asObject(snapshot.trace);
97-
const events = asArray(trace.events);
98-
99-
const requestedCount = Number.parseInt(args[0], 10);
100-
const count = Number.isFinite(requestedCount)
101-
? Math.min(20, Math.max(1, requestedCount))
102-
: 8;
103-
104-
if (events.length === 0) {
105-
return ["No network trace events recorded."];
106-
}
107-
108-
return events
109-
.slice(-count)
110-
.reverse()
111-
.map((event) => {
112-
const source = asObject(event);
113-
const details = asObject(source.details);
114-
const detailsPairs = Object.keys(details)
115-
.slice(0, 2)
116-
.map((key) => `${key}=${String(details[key])}`)
117-
.join(" ");
118-
const eventType = sanitizeText(source.type) || "EVENT";
119-
const phase = sanitizeText(source.phase) || "unknown";
120-
const prefix = `${asNumber(source.timestampMs, 0)}ms ${eventType} phase=${phase}`;
121-
return detailsPairs ? `${prefix} ${detailsPairs}` : prefix;
122-
});
123-
}
124-
12593
export function createNetworkSampleADebugPlugin() {
12694
return createNetworkDebugPluginDefinition({
12795
pluginId: "network.sampleA",
@@ -265,7 +233,11 @@ export function createNetworkSampleADebugPlugin() {
265233
return {
266234
status: "ready",
267235
title: "Network Trace",
268-
lines: commandLinesForTrace(context, args),
236+
lines: commandLinesForTrace(context, args, {
237+
sampleKey: NETWORK_SAMPLE_KEY,
238+
sanitizeText,
239+
formatNumber: asNumber
240+
}),
269241
code: "NETWORK_TRACE"
270242
};
271243
}

‎games/network_sample_b/debug/networkSampleBDebug.js‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ networkSampleBDebug.js
77

88
import { createNetworkDebugPluginDefinition } from "../../../engine/debug/network/index.js";
99
import { asArray, asObject } from "../../../src/engine/debug/inspectors/shared/inspectorUtils.js";
10+
import { toNetworkSnapshot } from "../../../src/shared/utils/networkDebugUtils.js";
11+
12+
const NETWORK_SAMPLE_KEY = "networkSampleB";
1013

1114
function sanitizeText(value) {
1215
return typeof value === "string" ? value.trim() : "";
@@ -17,12 +20,8 @@ function asNumber(value, fallback = 0) {
1720
return Number.isFinite(numeric) ? numeric : fallback;
1821
}
1922

20-
function toNetworkSnapshot(snapshot) {
21-
return asObject(snapshot?.assets?.networkSampleB);
22-
}
23-
2423
function toHostStatusLines(snapshot) {
25-
const network = toNetworkSnapshot(snapshot);
24+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
2625
const summary = asObject(network.summary);
2726
const host = asObject(network.host);
2827
return [
@@ -37,7 +36,7 @@ function toHostStatusLines(snapshot) {
3736
}
3837

3938
function toClientStatusLines(snapshot) {
40-
const network = toNetworkSnapshot(snapshot);
39+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
4140
const clients = asArray(network.clients);
4241
if (clients.length === 0) {
4342
return ["No client peer snapshots available."];
@@ -50,7 +49,7 @@ function toClientStatusLines(snapshot) {
5049
}
5150

5251
function toOwnershipLines(snapshot) {
53-
const network = toNetworkSnapshot(snapshot);
52+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
5453
const ownership = asObject(network.ownership);
5554
const rows = asArray(ownership.rows);
5655

@@ -67,7 +66,7 @@ function toOwnershipLines(snapshot) {
6766
}
6867

6968
function toReplicationLines(snapshot) {
70-
const network = toNetworkSnapshot(snapshot);
69+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
7170
const replication = asObject(network.replication);
7271
const clients = asArray(replication.clientSnapshots);
7372

@@ -86,7 +85,7 @@ function toReplicationLines(snapshot) {
8685
}
8786

8887
function commandLinesForConnections(context) {
89-
const snapshot = toNetworkSnapshot(context);
88+
const snapshot = toNetworkSnapshot(context, NETWORK_SAMPLE_KEY);
9089
const summary = asObject(snapshot.summary);
9190
const peers = asArray(snapshot.peers);
9291

@@ -107,7 +106,7 @@ function commandLinesForConnections(context) {
107106
}
108107

109108
function commandLinesForReplication(context) {
110-
const snapshot = toNetworkSnapshot(context);
109+
const snapshot = toNetworkSnapshot(context, NETWORK_SAMPLE_KEY);
111110
const replication = asObject(snapshot.replication);
112111
const clients = asArray(replication.clientSnapshots);
113112

‎games/network_sample_c/debug/networkSampleCDebug.js‎

Lines changed: 22 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ networkSampleCDebug.js
77

88
import { createNetworkDebugPluginDefinition } from "../../../engine/debug/network/index.js";
99
import { asArray, asObject } from "../../../src/engine/debug/inspectors/shared/inspectorUtils.js";
10+
import {
11+
commandLinesForTrace,
12+
getCommandSnapshot,
13+
toNetworkSnapshot
14+
} from "../../../src/shared/utils/networkDebugUtils.js";
15+
16+
const NETWORK_SAMPLE_KEY = "networkSampleC";
1017

1118
function sanitizeText(value) {
1219
return typeof value === "string" ? value.trim() : "";
@@ -34,16 +41,8 @@ function formatEntityLine(entity, options = {}) {
3441
return `${marker}${compactLabel} delta=${frameDelta} status=${status} severity=${severity} align=${alignment}`;
3542
}
3643

37-
function toNetworkSnapshot(snapshot) {
38-
return asObject(snapshot?.assets?.networkSampleC);
39-
}
40-
41-
function getCommandSnapshot(context) {
42-
return asObject(context?.assets?.networkSampleC);
43-
}
44-
4544
function toDivergenceLines(snapshot) {
46-
const network = toNetworkSnapshot(snapshot);
45+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
4746
const scenario = asObject(network.scenario);
4847
const divergence = asObject(network.divergence);
4948
const transport = asObject(network.network);
@@ -78,7 +77,7 @@ function toDivergenceLines(snapshot) {
7877
}
7978

8079
function toTimelineLines(snapshot) {
81-
const network = toNetworkSnapshot(snapshot);
80+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
8281
const timeline = asObject(network.timeline);
8382
const history = asObject(timeline.history);
8483
const entityHistory = asArray(history.entities);
@@ -117,7 +116,7 @@ function toTimelineLines(snapshot) {
117116
}
118117

119118
function toValidationLines(snapshot) {
120-
const network = toNetworkSnapshot(snapshot);
119+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
121120
const validation = asObject(network.validation);
122121
const items = asArray(validation.items);
123122

@@ -135,7 +134,7 @@ function toValidationLines(snapshot) {
135134
}
136135

137136
function toRewindLines(snapshot) {
138-
const network = toNetworkSnapshot(snapshot);
137+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
139138
const rewind = asObject(network.rewindPreparation);
140139
const rewindEntities = asArray(rewind.entities);
141140
const rewindSelected = asArray(rewind.selectedEntityIds);
@@ -171,7 +170,7 @@ function toRewindLines(snapshot) {
171170
}
172171

173172
function toTraceLines(snapshot, maxLines = 10) {
174-
const network = toNetworkSnapshot(snapshot);
173+
const network = toNetworkSnapshot(snapshot, NETWORK_SAMPLE_KEY);
175174
const trace = asObject(network.trace);
176175
const events = asArray(trace.events);
177176

@@ -193,7 +192,7 @@ function toTraceLines(snapshot, maxLines = 10) {
193192
}
194193

195194
function commandLinesForDivergence(context) {
196-
const snapshot = getCommandSnapshot(context);
195+
const snapshot = getCommandSnapshot(context, NETWORK_SAMPLE_KEY);
197196
const scenario = asObject(snapshot.scenario);
198197
const divergence = asObject(snapshot.divergence);
199198
const network = asObject(snapshot.network);
@@ -223,37 +222,8 @@ function commandLinesForDivergence(context) {
223222
return lines;
224223
}
225224

226-
function commandLinesForTrace(context, args = []) {
227-
const snapshot = getCommandSnapshot(context);
228-
const trace = asObject(snapshot.trace);
229-
const events = asArray(trace.events);
230-
231-
const requestedCount = Number.parseInt(args[0], 10);
232-
const count = Number.isFinite(requestedCount)
233-
? Math.min(20, Math.max(1, requestedCount))
234-
: 8;
235-
236-
if (events.length === 0) {
237-
return ["No network trace events recorded."];
238-
}
239-
240-
return events
241-
.slice(-count)
242-
.reverse()
243-
.map((event) => {
244-
const source = asObject(event);
245-
const details = asObject(source.details);
246-
const detailText = Object.keys(details)
247-
.slice(0, 2)
248-
.map((key) => `${key}=${String(details[key])}`)
249-
.join(" ");
250-
const base = `${asNumber(source.timestampMs, 0)}ms ${sanitizeText(source.type) || "EVENT"} phase=${sanitizeText(source.phaseId) || "unknown"}`;
251-
return detailText ? `${base} ${detailText}` : base;
252-
});
253-
}
254-
255225
function commandLinesForValidation(context) {
256-
const snapshot = getCommandSnapshot(context);
226+
const snapshot = getCommandSnapshot(context, NETWORK_SAMPLE_KEY);
257227
const validation = asObject(snapshot.validation);
258228
const items = asArray(validation.items);
259229

@@ -270,7 +240,7 @@ function commandLinesForValidation(context) {
270240
}
271241

272242
function commandLinesForReproduction(context) {
273-
const snapshot = getCommandSnapshot(context);
243+
const snapshot = getCommandSnapshot(context, NETWORK_SAMPLE_KEY);
274244
const reproduction = asObject(snapshot.reproduction);
275245
const steps = asArray(reproduction.steps);
276246

@@ -288,7 +258,7 @@ function commandLinesForReproduction(context) {
288258
}
289259

290260
function commandLinesForRewind(context) {
291-
const snapshot = getCommandSnapshot(context);
261+
const snapshot = getCommandSnapshot(context, NETWORK_SAMPLE_KEY);
292262
const rewind = asObject(snapshot.rewindPreparation);
293263
const rewindEntities = asArray(rewind.entities);
294264
const rewindSelected = asArray(rewind.selectedEntityIds);
@@ -499,7 +469,12 @@ export function createNetworkSampleCDebugPlugin() {
499469
return {
500470
status: "ready",
501471
title: "Network Trace",
502-
lines: commandLinesForTrace(context, args),
472+
lines: commandLinesForTrace(context, args, {
473+
sampleKey: NETWORK_SAMPLE_KEY,
474+
phaseField: "phaseId",
475+
sanitizeText,
476+
formatNumber: asNumber
477+
}),
503478
code: "NETWORK_TRACE"
504479
};
505480
}

0 commit comments

Comments
 (0)