akanjs 3.0.0-alpha.70 → 3.0.0-alpha.71

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.
Files changed (79) hide show
  1. package/client/router.ts +7 -7
  2. package/common/Logger.ts +280 -67
  3. package/common/deepObjectify.ts +3 -2
  4. package/common/index.ts +24 -1
  5. package/common/logContext.ts +27 -0
  6. package/common/plainFieldsOf.ts +13 -0
  7. package/constant/crystalize.ts +59 -39
  8. package/constant/dateSlot.ts +62 -0
  9. package/constant/getDefault.ts +16 -11
  10. package/constant/hydrationPlan.ts +72 -0
  11. package/constant/immerify.ts +4 -6
  12. package/constant/index.ts +2 -0
  13. package/constant/via.ts +14 -14
  14. package/fetch/client/fetchClient.ts +30 -12
  15. package/local/apps/serverLifecycle/serverLifecycle-local.db-shm +0 -0
  16. package/local/apps/serverLifecycle/serverLifecycle-local_solid.db-shm +0 -0
  17. package/package.json +11 -1
  18. package/server/akanApp.ts +84 -93
  19. package/server/akanServer.ts +84 -10
  20. package/server/console.ts +102 -1
  21. package/server/consoleSession.ts +49 -5
  22. package/server/logging/childOutputReader.ts +137 -0
  23. package/server/logging/hubFileSink.ts +39 -0
  24. package/server/logging/logControlSocket.ts +173 -0
  25. package/server/logging/logForwarder.ts +131 -0
  26. package/server/logging/logHub.ts +0 -0
  27. package/server/logging/logQuery.ts +130 -0
  28. package/server/logging/logStdoutWriter.ts +39 -0
  29. package/server/logging/logStreamRoute.ts +87 -0
  30. package/server/logging/logTailClient.ts +161 -0
  31. package/server/mcp/McpAuth.ts +4 -15
  32. package/server/mcp/McpDispatcher.ts +12 -8
  33. package/server/mcp/McpEventStream.ts +8 -60
  34. package/server/resolver/signal.resolver.ts +80 -53
  35. package/server/routing/apiRouter.ts +5 -3
  36. package/server/routing/eventStream.ts +93 -0
  37. package/server/routing/soloAppRoutes.ts +5 -1
  38. package/server/rscWorker.tsx +27 -9
  39. package/server/rscWorkerHost.ts +59 -8
  40. package/server/webRouter.ts +9 -0
  41. package/service/ipcTypes.ts +5 -0
  42. package/service/predefinedAdaptor/logging.adaptor.ts +1 -1
  43. package/signal/signalContext.ts +48 -15
  44. package/signal/trace.ts +268 -9
  45. package/store/action.ts +5 -6
  46. package/test/testServer.ts +6 -6
  47. package/types/common/Logger.d.ts +88 -6
  48. package/types/common/index.d.ts +3 -1
  49. package/types/common/logContext.d.ts +17 -0
  50. package/types/common/plainFieldsOf.d.ts +6 -0
  51. package/types/constant/crystalize.d.ts +3 -0
  52. package/types/constant/dateSlot.d.ts +14 -0
  53. package/types/constant/getDefault.d.ts +8 -0
  54. package/types/constant/hydrationPlan.d.ts +24 -0
  55. package/types/constant/index.d.ts +2 -0
  56. package/types/dictionary/base.dictionary.d.ts +1 -1
  57. package/types/dictionary/dictionary.d.ts +8 -8
  58. package/types/server/console.d.ts +10 -0
  59. package/types/server/consoleSession.d.ts +10 -0
  60. package/types/server/logging/childOutputReader.d.ts +40 -0
  61. package/types/server/logging/hubFileSink.d.ts +18 -0
  62. package/types/server/logging/logControlSocket.d.ts +60 -0
  63. package/types/server/logging/logForwarder.d.ts +37 -0
  64. package/types/server/logging/logHub.d.ts +70 -0
  65. package/types/server/logging/logQuery.d.ts +31 -0
  66. package/types/server/logging/logStdoutWriter.d.ts +35 -0
  67. package/types/server/logging/logStreamRoute.d.ts +20 -0
  68. package/types/server/logging/logTailClient.d.ts +42 -0
  69. package/types/server/mcp/McpAuth.d.ts +2 -6
  70. package/types/server/mcp/McpEventStream.d.ts +4 -5
  71. package/types/server/routing/eventStream.d.ts +23 -0
  72. package/types/server/routing/soloAppRoutes.d.ts +3 -1
  73. package/types/server/rscWorkerHost.d.ts +4 -1
  74. package/types/server/webRouter.d.ts +3 -1
  75. package/types/service/ipcTypes.d.ts +11 -0
  76. package/types/signal/signalContext.d.ts +16 -3
  77. package/types/signal/trace.d.ts +52 -2
  78. package/ui/Model/EditModal.tsx +1 -1
  79. package/ui/System/Client.tsx +1 -1
package/server/akanApp.ts CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  import { mkdir, readdir, rm } from "node:fs/promises";
4
4
  import path from "node:path";
5
- import { Logger } from "akanjs/common";
5
+ import { Logger, logSeverity } from "akanjs/common";
6
6
  import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
7
7
  import { isTraceEnabled } from "../signal/trace";
8
8
  import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
@@ -11,6 +11,11 @@ import { resolveEncodedSidecar } from "./assetEncoding";
11
11
  import { compressResponse } from "./contentEncoding";
12
12
  import { isPortInUseError } from "./lifecycle/portInUse";
13
13
  import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
14
+ import { ChildOutputReader } from "./logging/childOutputReader";
15
+ import { HubFileSink } from "./logging/hubFileSink";
16
+ import { LogControlSocket } from "./logging/logControlSocket";
17
+ import { LogHub } from "./logging/logHub";
18
+ import { LogStreamRoute } from "./logging/logStreamRoute";
14
19
  import { RotatingLogWriter } from "./logging/rotatingLogWriter";
15
20
  import { ProcessMetricsCollector } from "./processMetricsCollector";
16
21
  import { getWebConfigFromEnv } from "./types";
@@ -137,9 +142,10 @@ export class AkanApp {
137
142
  #metricsTimer: Timer | null = null;
138
143
  #logWriter: RotatingLogWriter | null = null;
139
144
  #removeLogSink: (() => void) | null = null;
140
- readonly #childOutputBuffers = new Map<string, string>();
141
- readonly #childStderrBlockBuffers = new Map<string, string[]>();
142
- readonly #childStderrBlockTimers = new Map<string, ReturnType<typeof setTimeout>>();
145
+ #logHub: LogHub | null = null;
146
+ #logControl: LogControlSocket | null = null;
147
+ #hubFileSink: HubFileSink | null = null;
148
+ #logStream: LogStreamRoute | null = null;
143
149
  static readonly #ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
144
150
  #gatewayMetrics: AkanMetricsReport = {};
145
151
  #proxyHopCount = 0;
@@ -160,6 +166,7 @@ export class AkanApp {
160
166
  this.#openapi = resolvedOptions.openapi;
161
167
  this.#modules = resolvedOptions.modules ?? [];
162
168
  this.#solo = AkanApp.#resolveSolo(resolvedOptions, this.#replica);
169
+ this.#logHub = LogHub.attach();
163
170
  }
164
171
 
165
172
  /**
@@ -255,7 +262,9 @@ export class AkanApp {
255
262
 
256
263
  async start() {
257
264
  if (this.#solo) return await this.#startSolo();
265
+ Logger.role = "gateway";
258
266
  await this.#prepareRuntimeDir();
267
+ await this.#startLogHub();
259
268
  this.#startFileLogging();
260
269
  for (let idx = 0; idx < this.#replica.total; idx++) this.#spawn(idx);
261
270
  try {
@@ -334,6 +343,7 @@ export class AkanApp {
334
343
  for (const child of stragglers) child.proc.kill("SIGKILL");
335
344
  await Promise.all(stragglers.map((child) => child.proc.exited.catch(() => undefined)));
336
345
  this.#children.clear();
346
+ await this.#stopLogHub();
337
347
  await this.#stopFileLogging();
338
348
  this.#resolveStopped?.();
339
349
  this.#resolveStopped = null;
@@ -402,8 +412,12 @@ export class AkanApp {
402
412
  lastRestartReason: previous?.lastRestartReason,
403
413
  });
404
414
  this.#invalidateFederationChildCache();
405
- this.#pipeOutput(idx, role, proc.stdout, "stdout");
406
- this.#pipeOutput(idx, role, proc.stderr, "stderr");
415
+ const output = new ChildOutputReader({
416
+ onLine: (line) => this.#writeChildLine(idx, role, proc.pid, "stdout", line),
417
+ onBlock: (lines) => this.#writeChildStderrBlock(idx, role, proc.pid, lines),
418
+ });
419
+ void output.pipe(proc.stdout, "stdout");
420
+ void output.pipe(proc.stderr, "stderr");
407
421
  proc.exited.then((code) => this.#handleChildExit(idx, proc, code));
408
422
  }
409
423
 
@@ -553,7 +567,7 @@ export class AkanApp {
553
567
  const entries = await readdir(this.#runtimeDir).catch(() => []);
554
568
  await Promise.all(
555
569
  entries
556
- .filter((name) => /^akan-child-.*\.sock$/.test(name))
570
+ .filter((name) => /^akan-(child-.*|control)\.sock$/.test(name))
557
571
  .map((name) => rm(path.join(this.#runtimeDir, name), { force: true }).catch(() => undefined)),
558
572
  );
559
573
  }
@@ -569,6 +583,13 @@ export class AkanApp {
569
583
  #startFileLogging() {
570
584
  this.#logWriter = RotatingLogWriter.fromRuntimeDir(this.#runtimeDir);
571
585
  if (!this.#logWriter) return;
586
+ if (this.#logHub && Logger.isNdjson) {
587
+ this.#hubFileSink = new HubFileSink(this.#logHub, this.#logWriter, {
588
+ minSev: logSeverity[Logger.fileLevel],
589
+ json: Logger.format === "ndjson-only",
590
+ });
591
+ return;
592
+ }
572
593
  this.#removeLogSink = Logger.addSink((entry) => {
573
594
  this.#logWriter?.write("gateway", entry.plainMessage);
574
595
  });
@@ -577,11 +598,38 @@ export class AkanApp {
577
598
  async #stopFileLogging() {
578
599
  this.#removeLogSink?.();
579
600
  this.#removeLogSink = null;
601
+ this.#hubFileSink?.close();
602
+ this.#hubFileSink = null;
580
603
  const writer = this.#logWriter;
581
604
  this.#logWriter = null;
582
605
  await writer?.close();
583
606
  }
584
607
 
608
+ /** The journal every child forwards into, and the socket `akan logs` reads it from. Additive to the text file. */
609
+ async #startLogHub() {
610
+ const hub = LogHub.attach();
611
+ this.#logHub = hub;
612
+ hub.onFloorChange((minSev) => this.#fanoutToAll({ type: "log.level", minSev }));
613
+ this.#logStream = LogStreamRoute.fromEnv(() => this.#logHub);
614
+ const control = new LogControlSocket(hub, this.#runtimeDir);
615
+ try {
616
+ await control.start();
617
+ this.#logControl = control;
618
+ } catch (error) {
619
+ this.logger.warn(
620
+ `Log control socket unavailable at ${control.path}: ${error instanceof Error ? error.message : String(error)}`,
621
+ );
622
+ }
623
+ }
624
+
625
+ async #stopLogHub() {
626
+ await this.#logControl?.stop();
627
+ this.#logControl = null;
628
+ this.#logStream = null;
629
+ this.#logHub?.close();
630
+ this.#logHub = null;
631
+ }
632
+
585
633
  #listen() {
586
634
  this.#server = Bun.serve({
587
635
  idleTimeout: 0,
@@ -605,6 +653,7 @@ export class AkanApp {
605
653
  const url = new URL(req.url);
606
654
  if (url.pathname === "/_akan/app/health") return Response.json(this.#getHealthStatus());
607
655
  if (url.pathname === "/_akan/app/metrics") return Response.json(this.#getMetricsStatus());
656
+ if (url.pathname === LogStreamRoute.path && this.#logStream) return this.#logStream.handle(req);
608
657
  if (url.pathname === "/_akan/bench/ping") return new Response("ok");
609
658
  if (this.#isWebSocketPath(url.pathname)) return this.#upgradeWebSocket(req, server);
610
659
  const assetResponse = await this.#serveImmutableArtifact(req, url);
@@ -1051,6 +1100,10 @@ export class AkanApp {
1051
1100
  case "metrics.report":
1052
1101
  this.#updateMetrics(idx, message.metrics);
1053
1102
  return;
1103
+ case "log.records":
1104
+ this.#logHub?.ingestMany(message.records);
1105
+ if (message.dropped) this.logger.warn(`Child ${idx} dropped ${message.dropped} log records (ipc backpressure)`);
1106
+ return;
1054
1107
  case "health.pong":
1055
1108
  this.#markHealthy(idx);
1056
1109
  return;
@@ -1097,6 +1150,9 @@ export class AkanApp {
1097
1150
  child.healthPath = message.healthPath;
1098
1151
  child.lastPongAtMono = performance.now();
1099
1152
  child.restartAttempts = 0;
1153
+
1154
+ if (this.#logHub && this.#logHub.floor !== null)
1155
+ this.#sendToChild(child, { type: "log.level", minSev: this.#logHub.floor });
1100
1156
  child.restartPending = false;
1101
1157
  child.lastErrorMessage = undefined;
1102
1158
  this.#invalidateFederationChildCache();
@@ -1289,6 +1345,10 @@ export class AkanApp {
1289
1345
  }
1290
1346
  }
1291
1347
 
1348
+ #fanoutToAll(message: AkanIpcMessage) {
1349
+ for (const child of this.#children.values()) this.#sendToChild(child, message);
1350
+ }
1351
+
1292
1352
  #fanoutToBatch(message: AkanIpcMessage) {
1293
1353
  for (const child of this.#children.values()) {
1294
1354
  if (child.role === "batch" || child.role === "all") {
@@ -1314,99 +1374,30 @@ export class AkanApp {
1314
1374
  }
1315
1375
  }
1316
1376
 
1317
- async #pipeOutput(
1318
- idx: number,
1319
- role: AkanChildRole,
1320
- stream: ReadableStream<Uint8Array> | null,
1321
- type: "stdout" | "stderr",
1322
- ) {
1323
- if (!stream) return;
1324
- const bufferKey = `${idx}:${type}`;
1325
- const reader = stream.getReader();
1326
- const decoder = new TextDecoder();
1327
- try {
1328
- for (;;) {
1329
- const { done, value } = await reader.read();
1330
- if (done) break;
1331
- const text = decoder.decode(value, { stream: true });
1332
- this.#writeChildOutput(idx, role, type, bufferKey, text);
1333
- }
1334
- const remaining = decoder.decode();
1335
- if (remaining) this.#writeChildOutput(idx, role, type, bufferKey, remaining);
1336
- } finally {
1337
- this.#flushChildOutput(idx, role, type, bufferKey);
1338
- if (type === "stderr") this.#flushChildStderrBlock(idx, role, AkanApp.#childStderrBlockKey(idx, role));
1339
- }
1340
- }
1341
-
1342
- #writeChildOutput(idx: number, role: AkanChildRole, type: "stdout" | "stderr", bufferKey: string, text: string) {
1343
- let buffered = `${this.#childOutputBuffers.get(bufferKey) ?? ""}${text}`;
1344
- for (;;) {
1345
- const newlineIdx = buffered.indexOf("\n");
1346
- if (newlineIdx === -1) break;
1347
- const line = buffered.slice(0, newlineIdx + 1);
1348
- buffered = buffered.slice(newlineIdx + 1);
1349
- this.#writeChildOutputLine(idx, role, type, line);
1377
+ #writeChildLine(idx: number, role: AkanChildRole, pid: number | null, type: "stdout" | "stderr", line: string) {
1378
+ if (Logger.isNdjson) {
1379
+ this.#logHub?.ingest(ChildOutputReader.toRecord({ type, text: line, name: "child", role, replicaIdx: idx, pid }));
1380
+ return;
1350
1381
  }
1351
- if (buffered) this.#childOutputBuffers.set(bufferKey, buffered);
1352
- else this.#childOutputBuffers.delete(bufferKey);
1353
- }
1354
-
1355
- #flushChildOutput(idx: number, role: AkanChildRole, type: "stdout" | "stderr", bufferKey: string) {
1356
- const buffered = this.#childOutputBuffers.get(bufferKey);
1357
- if (!buffered) return;
1358
- this.#childOutputBuffers.delete(bufferKey);
1359
- this.#writeChildOutputLine(idx, role, type, `${buffered}\n`);
1360
- }
1361
-
1362
- #writeChildOutputLine(idx: number, role: AkanChildRole, type: "stdout" | "stderr", line: string) {
1363
- if (type === "stderr" && this.#bufferChildStderrLine(idx, role, line)) return;
1364
- this.#writeChildOutputLineRaw(idx, role, type, line);
1365
- }
1366
-
1367
- #writeChildOutputLineRaw(idx: number, role: AkanChildRole, type: "stdout" | "stderr", line: string) {
1368
1382
  const prefixedLine = `[child:${idx} ${role}] [${type}] ${line}`;
1369
1383
  if (type === "stdout" || this.#printChildStderr) process[type].write(prefixedLine);
1370
1384
  this.#logWriter?.write(`${idx}-${role}`, AkanApp.#stripAnsi(prefixedLine));
1371
1385
  }
1372
1386
 
1373
- #bufferChildStderrLine(idx: number, role: AkanChildRole, line: string): boolean {
1374
- const key = AkanApp.#childStderrBlockKey(idx, role);
1375
- const block = this.#childStderrBlockBuffers.get(key) ?? [];
1376
- block.push(line);
1377
- this.#childStderrBlockBuffers.set(key, block);
1378
-
1379
- const existingTimer = this.#childStderrBlockTimers.get(key);
1380
- if (existingTimer) clearTimeout(existingTimer);
1381
-
1382
- if (line.trim() === "" || block.length >= 64) {
1383
- this.#flushChildStderrBlock(idx, role, key);
1384
- return true;
1385
- }
1386
-
1387
- this.#childStderrBlockTimers.set(
1388
- key,
1389
- setTimeout(() => this.#flushChildStderrBlock(idx, role, key), 50),
1390
- );
1391
- return true;
1392
- }
1393
-
1394
- #flushChildStderrBlock(idx: number, role: AkanChildRole, key: string) {
1395
- const timer = this.#childStderrBlockTimers.get(key);
1396
- if (timer) clearTimeout(timer);
1397
- this.#childStderrBlockTimers.delete(key);
1398
-
1399
- const block = this.#childStderrBlockBuffers.get(key);
1400
- if (!block?.length) return;
1401
- this.#childStderrBlockBuffers.delete(key);
1402
-
1403
- const text = block.join("");
1387
+ /**
1388
+ * In ndjson mode a stack trace is one record, and `AKAN_CHILD_STDERR` does not apply: the line that killed a
1389
+ * child is the one the collector must not miss.
1390
+ */
1391
+ #writeChildStderrBlock(idx: number, role: AkanChildRole, pid: number | null, lines: string[]) {
1392
+ const text = lines.join("");
1404
1393
  if (AkanApp.#isBenignRsdwConnectionClosedBlock(text)) return;
1405
- for (const blockLine of block) this.#writeChildOutputLineRaw(idx, role, "stderr", blockLine);
1406
- }
1407
-
1408
- static #childStderrBlockKey(idx: number, role: AkanChildRole): string {
1409
- return `${idx}:${role}:stderr`;
1394
+ if (Logger.isNdjson) {
1395
+ this.#logHub?.ingest(
1396
+ ChildOutputReader.toRecord({ type: "stderr", text, name: "child", role, replicaIdx: idx, pid }),
1397
+ );
1398
+ return;
1399
+ }
1400
+ for (const line of lines) this.#writeChildLine(idx, role, pid, "stderr", line);
1410
1401
  }
1411
1402
 
1412
1403
  static #isBenignRsdwConnectionClosedBlock(text: string): boolean {
@@ -1,6 +1,6 @@
1
1
  import type { AkanWebConfig, AkanWebOption } from "akanjs";
2
2
  import { type BackendEnv, type BaseEnv, getEnv } from "akanjs/base";
3
- import { Logger, websocketBinaryFrameContract } from "akanjs/common";
3
+ import { Logger, logSeverity, websocketBinaryFrameContract } from "akanjs/common";
4
4
  import { DictionaryLookup } from "akanjs/dictionary";
5
5
  import type {
6
6
  Adaptor,
@@ -26,6 +26,11 @@ import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
26
26
  import { isPortInUseError } from "./lifecycle/portInUse";
27
27
  import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
28
28
  import { ShutdownManager } from "./lifecycle/shutdownManager";
29
+ import { HubFileSink } from "./logging/hubFileSink";
30
+ import { LogControlSocket } from "./logging/logControlSocket";
31
+ import { LogForwarder } from "./logging/logForwarder";
32
+ import { LogHub } from "./logging/logHub";
33
+ import { LogStreamRoute } from "./logging/logStreamRoute";
29
34
  import { RotatingLogWriter } from "./logging/rotatingLogWriter";
30
35
  import { type McpAuthOption, McpRouter } from "./mcp";
31
36
  import { ProcessMetricsCollector } from "./processMetricsCollector";
@@ -165,6 +170,11 @@ export class AkanServer {
165
170
  readonly #solo = !process.env.AKAN_CHILD_SOCKET;
166
171
  #logWriter: RotatingLogWriter | null = null;
167
172
  #removeLogSink: (() => void) | null = null;
173
+ #logHub: LogHub | null = null;
174
+ #logControl: LogControlSocket | null = null;
175
+ #logForwarder: LogForwarder | null = null;
176
+ #hubFileSink: HubFileSink | null = null;
177
+ #logStream: LogStreamRoute | null = null;
168
178
  #lastMetrics: AkanMetricsReport = {};
169
179
  constructor(
170
180
  name = "AkanServer",
@@ -351,6 +361,8 @@ export class AkanServer {
351
361
  throw new Error("AkanServer is not able to listen. Call `init` first.");
352
362
  }
353
363
  this.status = "starting";
364
+ Logger.role = this.serverMode;
365
+ await this.#startLogTransport();
354
366
  this.#startFileLogging();
355
367
  const port = process.env.AKAN_CHILD_SOCKET
356
368
  ? undefined
@@ -469,9 +481,11 @@ export class AkanServer {
469
481
  if (websocket) SignalResolver.setLocalPublish((roomId, data) => this.#localPublish?.(roomId, data), websocket);
470
482
  this.status = "running";
471
483
  if (!isNoListenCommand) {
484
+ Logger.role = this.serverMode;
472
485
  this.#startMetricsReporting();
473
486
  this.#di.registerSchedule(this.serverMode);
474
487
  this.#registerParentIpc();
488
+ await this.#startLogTransport();
475
489
  process.send?.({
476
490
  type: "ready",
477
491
  pid: process.pid,
@@ -506,10 +520,12 @@ export class AkanServer {
506
520
 
507
521
  this.#prepared?.webRouter?.dispose();
508
522
  await this.#withShutdownTimeout(this.#di.destroyAll());
509
- await this.#stopFileLogging();
510
523
  this.#prepared = null;
511
524
  this.status = "stopped";
512
525
  this.logger.info(`Shutdown completed successfully in ${Date.now() - now}ms`);
526
+
527
+ await this.#stopLogTransport();
528
+ await this.#stopFileLogging();
513
529
  } catch (error) {
514
530
  this.logger.error(`Error during shutdown: ${error instanceof Error ? error.message : String(error)}`);
515
531
  this.status = "stopped";
@@ -545,7 +561,10 @@ export class AkanServer {
545
561
  sentAt: message.sentAt,
546
562
  pid: process.pid,
547
563
  } satisfies AkanIpcMessage);
548
- else if (message.type === "shutdown") {
564
+ else if (message.type === "log.level") {
565
+ this.#logForwarder?.setMinSev(message.minSev);
566
+ this.#prepared?.webRouter?.setLogLevel(message.minSev);
567
+ } else if (message.type === "shutdown") {
549
568
  void this.stop()
550
569
  .then(() => process.exit(0))
551
570
  .catch(() => process.exit(1));
@@ -621,14 +640,18 @@ export class AkanServer {
621
640
  })
622
641
  : null;
623
642
  const mcpRoutes: HttpRoutes = mcpRouter?.createRoutes() ?? {};
643
+ this.#logStream ??= this.#solo ? LogStreamRoute.fromEnv(() => this.#logHub) : null;
624
644
  const soloRoutes: HttpRoutes = this.#solo
625
- ? createSoloAppRoutes(() => ({
626
- role: this.serverMode,
627
- running: this.status === "running",
628
- status: this.status,
629
- port: this.#server?.port ?? null,
630
- metrics: this.#lastMetrics,
631
- }))
645
+ ? createSoloAppRoutes(
646
+ () => ({
647
+ role: this.serverMode,
648
+ running: this.status === "running",
649
+ status: this.status,
650
+ port: this.#server?.port ?? null,
651
+ metrics: this.#lastMetrics,
652
+ }),
653
+ this.#logStream,
654
+ )
632
655
  : {};
633
656
 
634
657
  mcpRouter?.report();
@@ -650,6 +673,13 @@ export class AkanServer {
650
673
  if (!this.#solo || this.#logWriter) return;
651
674
  this.#logWriter = RotatingLogWriter.fromRuntimeDir(resolveRuntimeDir());
652
675
  if (!this.#logWriter) return;
676
+ if (this.#logHub && Logger.isNdjson) {
677
+ this.#hubFileSink = new HubFileSink(this.#logHub, this.#logWriter, {
678
+ minSev: logSeverity[Logger.fileLevel],
679
+ json: Logger.format === "ndjson-only",
680
+ });
681
+ return;
682
+ }
653
683
  this.#removeLogSink = Logger.addSink((entry) => {
654
684
  this.#logWriter?.write(this.serverMode, entry.plainMessage);
655
685
  });
@@ -658,11 +688,55 @@ export class AkanServer {
658
688
  async #stopFileLogging() {
659
689
  this.#removeLogSink?.();
660
690
  this.#removeLogSink = null;
691
+ this.#hubFileSink?.close();
692
+ this.#hubFileSink = null;
661
693
  const writer = this.#logWriter;
662
694
  this.#logWriter = null;
663
695
  await writer?.close();
664
696
  }
665
697
 
698
+ /**
699
+ * Solo owns the hub and the control socket the gateway would have owned; a spawned child forwards its own
700
+ * records — and the RSC worker's, which reach it over the worker IPC — up to the gateway instead.
701
+ */
702
+ async #startLogTransport() {
703
+ if (this.#logHub || this.#logForwarder) return;
704
+ const webRouter = this.#prepared?.webRouter ?? null;
705
+ if (this.#solo) {
706
+ const hub = LogHub.attach();
707
+ this.#logHub = hub;
708
+ hub.onFloorChange((minSev) => webRouter?.setLogLevel(minSev));
709
+ webRouter?.onLogRecords((records, dropped) => {
710
+ hub.ingestMany(records);
711
+ if (dropped) this.logger.warn(`RSC worker dropped ${dropped} log records (ipc backpressure)`);
712
+ });
713
+ const control = new LogControlSocket(hub, resolveRuntimeDir());
714
+ try {
715
+ await control.start();
716
+ this.#logControl = control;
717
+ } catch (error) {
718
+ this.logger.warn(
719
+ `Log control socket unavailable at ${control.path}: ${error instanceof Error ? error.message : String(error)}`,
720
+ );
721
+ }
722
+ return;
723
+ }
724
+
725
+ if (Logger.isNdjson) Logger.consoleOutput = false;
726
+ const forwarder = new LogForwarder((message) => process.send?.(message));
727
+ this.#logForwarder = forwarder;
728
+ webRouter?.onLogRecords((records) => forwarder.pushMany(records));
729
+ }
730
+
731
+ async #stopLogTransport() {
732
+ await this.#logControl?.stop();
733
+ this.#logControl = null;
734
+ this.#logHub?.close();
735
+ this.#logHub = null;
736
+ this.#logForwarder?.close();
737
+ this.#logForwarder = null;
738
+ }
739
+
666
740
  /**
667
741
  * Rebuilt per request rather than cached on the instance: libs register their dictionaries at module-evaluation
668
742
  * time, and the document itself is already re-serialized per request, so a stale snapshot would be the only
package/server/console.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  import type { BaseEnv } from "akanjs/base";
2
+ import { Logger } from "akanjs/common";
2
3
  import type { Adaptor, Service } from "akanjs/service";
3
4
  import type { ServerSignal } from "akanjs/signal";
4
5
  import type { AkanServer } from "./akanServer";
5
- import { AkanConsoleSession } from "./consoleSession";
6
+ import { type AkanConsoleCommand, AkanConsoleSession } from "./consoleSession";
7
+ import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
8
+ import { LogControlUnavailableError, LogTailClient } from "./logging/logTailClient";
6
9
 
7
10
  export * from "./consoleEvaluator";
8
11
 
@@ -11,8 +14,105 @@ export interface AkanConsoleOptions {
11
14
  globals?: Record<string, unknown>;
12
15
  input?: typeof process.stdin;
13
16
  output?: typeof process.stdout;
17
+ /** Where the running server keeps `akan-control.sock`; the console is its own process and has to be told. */
18
+ runtimeDir?: string;
14
19
  }
15
20
 
21
+ /** `level=warn grep="payment failed" endpoint=mutation:*` → a query object the socket parses. */
22
+ export const parseAkanConsoleQuery = (args: string): Record<string, string> => {
23
+ const query: Record<string, string> = {};
24
+ for (const match of args.matchAll(/([A-Za-z]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g)) {
25
+ const [, key, doubleQuoted, singleQuoted, bare] = match;
26
+ if (key) query[key] = doubleQuoted ?? singleQuoted ?? bare ?? "";
27
+ }
28
+ return query;
29
+ };
30
+
31
+ /**
32
+ * `.tail` and `.trace` attach to the *running* server's control socket — the console booted its own
33
+ * `listen: false` server, whose logs are not the ones anybody is looking for.
34
+ */
35
+ export const createAkanConsoleLogCommands = (
36
+ appName: string,
37
+ runtimeDir: string,
38
+ ): Record<string, AkanConsoleCommand> => {
39
+ const socketPath = LogTailClient.socketPath(runtimeDir);
40
+ let tail: { client: LogTailClient; id: string; summary: string } | null = null;
41
+ const connect = async (
42
+ session: AkanConsoleSession,
43
+ onRecord: (record: Parameters<typeof Logger.render>[0]) => void,
44
+ ) => {
45
+ try {
46
+ return await LogTailClient.connect(socketPath, {
47
+ onRecord: (entry) => onRecord(entry.record),
48
+ onEvent: (response) => {
49
+ if (response.type === "dropped") session.write(`tail: ${response.count} records dropped (slow reader)\n`);
50
+ },
51
+ onClose: () => {
52
+ if (tail) session.write("tail: connection closed\n");
53
+ tail = null;
54
+ },
55
+ });
56
+ } catch (error) {
57
+ if (error instanceof LogControlUnavailableError) {
58
+ session.write(`${appName} is not running (no akan-control.sock in ${runtimeDir})\n`);
59
+ return null;
60
+ }
61
+ throw error;
62
+ }
63
+ };
64
+ const stopTail = () => {
65
+ const current = tail;
66
+ tail = null;
67
+ current?.client.close();
68
+ };
69
+ return {
70
+ ".tail": {
71
+ desc: "Follow the running server: .tail level=warn grep=payment endpoint=mutation:* | .tail off",
72
+ run: async (args, session) => {
73
+ if (args === "off") {
74
+ if (!tail) session.write("tail: not running\n");
75
+ stopTail();
76
+ return;
77
+ }
78
+ if (!args) {
79
+ session.write(tail ? `tail: following ${tail.summary}\n` : "tail: not running; try .tail level=warn\n");
80
+ return;
81
+ }
82
+ stopTail();
83
+ const client = await connect(session, (record) => session.write(Logger.render(record)));
84
+ if (!client) return;
85
+ const query = parseAkanConsoleQuery(args);
86
+ const subscribed = await client.subscribe(query);
87
+ tail = { client, id: subscribed.id, summary: args };
88
+ session.onClose(stopTail);
89
+ session.write(`tail: following ${args} (${LogTailClient.describeCoverage(subscribed.coverage)})\n`);
90
+ if (query.endpoint)
91
+ session.write("tail: primitive query fast-path requests carry no endpoint and are not shown\n");
92
+ },
93
+ },
94
+ ".trace": {
95
+ desc: "Print every buffered record of one request: .trace <traceId>",
96
+ run: async (args, session) => {
97
+ if (!args) {
98
+ session.write("usage: .trace <traceId>\n");
99
+ return;
100
+ }
101
+ const client = await connect(session, () => undefined);
102
+ if (!client) return;
103
+ try {
104
+ const { entries, coverage } = await client.history({ trace: args });
105
+ if (!entries.length)
106
+ session.write(`no records for trace ${args} (${LogTailClient.describeCoverage(coverage)})\n`);
107
+ for (const entry of entries) session.write(Logger.render(entry.record));
108
+ } finally {
109
+ client.close();
110
+ }
111
+ },
112
+ },
113
+ };
114
+ };
115
+
16
116
  export interface AkanConsoleContext extends Record<string, unknown> {
17
117
  server: AkanServer;
18
118
  env: AkanServer["env"];
@@ -92,6 +192,7 @@ export const startAkanConsole = async (server: AkanServer, options: AkanConsoleO
92
192
  banner: `Akan console started for ${server.name}. Type .help for commands.\n`,
93
193
  input: options.input,
94
194
  output: options.output,
195
+ commands: createAkanConsoleLogCommands(server.name, options.runtimeDir ?? resolveRuntimeDir()),
95
196
  });
96
197
  await session.run();
97
198
  };