@hydranium/protocol 1.0.0-next.267 → 1.0.0-next.269

package/src/logger.ts

@@ -39,15 +39,15 @@ let fileLevel: LogThreshold | undefined;
  * and every `for` / `sub` / `with` derivation preserves the implementation type.
  */
 export interface Logger {
-   /** Log a message at error level. */
+   /** Requested work failed; logged once, by the code that ends the failure, not by one that rethrows it. */
    error(message?: string, ...args: unknown[]): this;
-   /** Log a message at warn level. */
+   /** An anomaly that was handled, or work declined by design, such as a conflict or a cap; a clean run logs none. */
    warn(message?: string, ...args: unknown[]): this;
-   /** Log a message at info level. */
+   /** A milestone the person running the server would recognise without knowing the internals. */
    info(message?: string, ...args: unknown[]): this;
-   /** Log a message at debug level. */
+   /** Diagnosis; its level decides whether the line is built, never which code runs. */
    debug(message?: string, ...args: unknown[]): this;
-   /** High-volume diagnostic lines, only emitted at the `'trace'` threshold. */
+   /** High-volume diagnosis, emitted only at the `'trace'` threshold; as for `debug`, no code runs only for it. */
    trace(message?: string, ...args: unknown[]): this;
    /** Log a message at info-level threshold with a `Log` label (rather than `Info`). */
    log(message?: string, ...args: unknown[]): this;

package/src/messages/primitives.ts

@@ -236,11 +236,41 @@ export function resolvedFromResponseError(error: ResponseError<unknown>): Resolv
  * to pass as a parameter for the same reason a number is: it is not itself
  * translatable text, so it needs no code of its own. A PROSE fragment is not,
  * and must become one code per value instead.
+ *
+ * For a reader of the client; the log takes {@link describeErrorWithStack}.
  */
 export function describeError(error: unknown): string {
    return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * An error for the log: its stack where it has one, which names where it was
+ * thrown, and its causes, which name what failed when an error wraps another.
+ * Never for the client, whose reader cannot act on a stack.
+ */
+export function describeErrorWithStack(error: unknown): string {
+   // A cause chain may loop back on itself.
+   return describeChain(error, new Set());
+}
+
+function describeChain(error: unknown, seen: Set<unknown>): string {
+   const lines: string[] = [];
+   let current: unknown = error;
+   let prefix = '';
+   do {
+      seen.add(current);
+      lines.push(prefix + (current instanceof Error ? (current.stack ?? current.message) : String(current)));
+      // Node fails a connect to several addresses with one, whose own message is empty.
+      if (current instanceof AggregateError) {
+         const errors: unknown[] = current.errors;
+         lines.push(...errors.filter(inner => !seen.has(inner)).map(inner => `Including: ${describeChain(inner, seen)}`));
+      }
+      current = current instanceof Error ? current.cause : undefined;
+      prefix = 'Caused by: ';
+   } while (current !== undefined && current !== null && !seen.has(current));
+   return lines.join('\n');
+}
+
 /**
  * Recognises a declaration among a barrel's exports. The `format` check is what
  * discriminates: a `code` + `text` pair alone admits any object that happens to

package/src/tracer.ts

@@ -12,6 +12,7 @@ import { Format, Logger, type LogThreshold } from './logger';
 import { NoopLogger } from './noop-logger';
 import { DefaultProfileSession, type ProfileSession } from './profile-session';
 import { Disposable } from './util';
+import { describeErrorWithStack } from './messages/primitives';
 
 /** Module-global so nested timers don't reuse ids. */
 let nextTimerId = 0;
@@ -183,7 +184,7 @@ export class DefaultTracer implements Tracer {
          if (status === 'failed') {
             // Reporting the failure is the caller's, who receives it: a line at
             // warn here would exist only while `logLevel` is enabled.
-            const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+            const detail = describeErrorWithStack(error);
             this.logger.debug(`${label} [#${id}] failed: ${detail}`);
          }
       };