tabletcommand-logger 3.2.7 → 4.0.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.
Files changed (70) hide show
  1. package/.cspell/project-words.txt +28 -0
  2. package/CLAUDE.md +150 -0
  3. package/README.md +111 -1
  4. package/build/index.js +11 -3
  5. package/build/index.js.map +1 -1
  6. package/build/logger-types.js +3 -0
  7. package/build/logger-types.js.map +1 -0
  8. package/build/middleware/logger.js +94 -149
  9. package/build/middleware/logger.js.map +1 -1
  10. package/build/middleware/status-logger.js.map +1 -1
  11. package/build/otel.js +54 -0
  12. package/build/otel.js.map +1 -0
  13. package/build/pino-logger.js +97 -0
  14. package/build/pino-logger.js.map +1 -0
  15. package/build/redaction.js +351 -0
  16. package/build/redaction.js.map +1 -0
  17. package/build/test/logger-factory.js +207 -0
  18. package/build/test/logger-factory.js.map +1 -0
  19. package/build/test/middleware-logger.js +282 -0
  20. package/build/test/middleware-logger.js.map +1 -1
  21. package/build/test/middleware-status-logger.js.map +1 -1
  22. package/build/test/otel-mixin.js +139 -0
  23. package/build/test/otel-mixin.js.map +1 -0
  24. package/build/test/redaction.js +293 -0
  25. package/build/test/redaction.js.map +1 -0
  26. package/build/test/signature.js +111 -0
  27. package/build/test/signature.js.map +1 -0
  28. package/build/winston-logger.js +18 -47
  29. package/build/winston-logger.js.map +1 -1
  30. package/definitions/index.d.ts +5 -2
  31. package/definitions/index.d.ts.map +1 -1
  32. package/definitions/logger-types.d.ts +38 -0
  33. package/definitions/logger-types.d.ts.map +1 -0
  34. package/definitions/middleware/logger.d.ts +4 -6
  35. package/definitions/middleware/logger.d.ts.map +1 -1
  36. package/definitions/middleware/status-logger.d.ts +2 -2
  37. package/definitions/middleware/status-logger.d.ts.map +1 -1
  38. package/definitions/otel.d.ts +8 -0
  39. package/definitions/otel.d.ts.map +1 -0
  40. package/definitions/pino-logger.d.ts +6 -0
  41. package/definitions/pino-logger.d.ts.map +1 -0
  42. package/definitions/redaction.d.ts +25 -0
  43. package/definitions/redaction.d.ts.map +1 -0
  44. package/definitions/test/logger-factory.d.ts +2 -0
  45. package/definitions/test/logger-factory.d.ts.map +1 -0
  46. package/definitions/test/otel-mixin.d.ts +2 -0
  47. package/definitions/test/otel-mixin.d.ts.map +1 -0
  48. package/definitions/test/redaction.d.ts +2 -0
  49. package/definitions/test/redaction.d.ts.map +1 -0
  50. package/definitions/test/signature.d.ts +2 -0
  51. package/definitions/test/signature.d.ts.map +1 -0
  52. package/definitions/winston-logger.d.ts +2 -13
  53. package/definitions/winston-logger.d.ts.map +1 -1
  54. package/eslint.config.mjs +1 -0
  55. package/package.json +17 -5
  56. package/src/index.ts +6 -3
  57. package/src/logger-types.ts +50 -0
  58. package/src/middleware/logger.ts +101 -164
  59. package/src/middleware/status-logger.ts +2 -4
  60. package/src/otel.ts +57 -0
  61. package/src/pino-logger.ts +110 -0
  62. package/src/redaction.ts +368 -0
  63. package/src/test/logger-factory.ts +216 -0
  64. package/src/test/middleware-logger.ts +321 -2
  65. package/src/test/middleware-status-logger.ts +2 -2
  66. package/src/test/otel-mixin.ts +119 -0
  67. package/src/test/redaction.ts +409 -0
  68. package/src/test/signature.ts +126 -0
  69. package/src/winston-logger.ts +2 -72
  70. package/tabletcommand-logger-4.0.0.tgz +0 -0
@@ -1,190 +1,127 @@
1
- import _ from "lodash";
2
- import { Logger } from "winston";
1
+ import { NextFunction, Request, Response } from "express";
2
+ import pino from "pino";
3
+ import pinoHttp from "pino-http";
4
+ import { StrictLogger } from "../logger-types";
3
5
  import {
4
- NextFunction,
5
- Request,
6
- Response,
7
- } from "express";
8
- import { Query } from "express-serve-static-core";
9
-
10
- // Each of these authenticates a request on its own, so a log line that keeps the whole
11
- // value is a live credential. The header stays, cut to a 7-character prefix: enough to
12
- // tell two keys apart, not enough to replay one. Node lowercases incoming header names.
13
- const keyHeaders = [
14
- "authorization",
15
- "apikey",
16
- "personnelapikey",
17
- "x-tc-auth-token",
18
- ];
19
-
20
- // tabletcommand-session reads each of these from the query string when the header is
21
- // absent, and accepts either spelling. signupKey only ever arrives in the query.
22
- const keyParams = [
23
- "apikey",
24
- "personnelapikey",
25
- "signupkey",
26
- ];
27
-
28
- // A route can wrap a key name in a longer parameter name, such as deviceApiKey, so match
29
- // the name loosely. Cutting a parameter that holds no credential costs nothing.
30
- function isKeyParam(name: string): boolean {
31
- const lower = decodeName(name).toLowerCase();
32
- return keyParams.some((keyParam) => lower.includes(keyParam));
33
- }
34
-
35
- // Express decodes the name before tabletcommand-session reads it, so api%6Bey
36
- // authenticates as apikey and has to be matched the same way. decodeURIComponent throws
37
- // on a malformed escape, and this runs in a res "finish" listener where a throw ends the
38
- // process.
39
- function decodeName(name: string): string {
40
- try {
41
- return decodeURIComponent(name.replace(/\+/g, " "));
42
- } catch {
43
- return name;
44
- }
45
- }
46
-
47
- const redacted = "<redacted>";
48
-
49
- function keepPrefix(value: string): string {
50
- return value.substring(0, 7);
51
- }
52
-
53
- // Every scheme this service accepts is a short word, such as Bearer or Basic.
54
- const schemePattern = /^[A-Za-z]{1,20}$/;
55
-
56
- // A scheme fills the whole prefix on its own, so keep it and take the prefix from the
57
- // credential behind it. A first word that is not a scheme is part of the credential, so
58
- // cut the value whole rather than keep that word.
59
- function redactAuthorization(value: string): string {
60
- const [scheme, ...rest] = value.split(" ");
61
- if (rest.length === 0 || !schemePattern.test(scheme)) {
62
- return keepPrefix(value);
6
+ redactHeaders,
7
+ redactOriginalURL,
8
+ redactQuery,
9
+ redactSecrets,
10
+ } from "../redaction";
11
+
12
+ export { redactHeaders, redactOriginalURL, redactQuery };
13
+
14
+ export default function loggerMiddleware(logger?: StrictLogger | null) {
15
+ if (!logger) {
16
+ return function noopMiddleware(_req: Request, _res: Response, next: NextFunction) {
17
+ return next();
18
+ };
63
19
  }
64
- return `${scheme} ${keepPrefix(rest.join(" "))}`;
65
- }
66
-
67
- // Cookie names answer "did the caller send a session at all", so they stay and the values go.
68
- function redactCookie(value: string): string {
69
- return value
70
- .split(";")
71
- .map((pair) => pair.split("=")[0].trim())
72
- .filter((name) => name !== "")
73
- .map((name) => `${name}=${redacted}`)
74
- .join("; ");
75
- }
76
-
77
- function redactorFor(name: string): (value: string) => string {
78
- if (name === "cookie") {
79
- return redactCookie;
80
- }
81
- if (name === "authorization") {
82
- return redactAuthorization;
83
- }
84
- return keepPrefix;
85
- }
86
20
 
87
- // Node only gives a string or an array of strings, so anything else means other
88
- // middleware wrote to req.headers. Drop it rather than throw: this runs in a res
89
- // "finish" listener, where an exception ends the process.
90
- function redactHeaderValue(name: string, value: unknown): string | string[] {
91
- const redact = redactorFor(name);
92
- if (_.isArray(value)) {
93
- return value.map((entry: unknown) => _.isString(entry) ? redact(entry) : redacted);
94
- }
95
- if (!_.isString(value)) {
96
- return redacted;
97
- }
98
- return redact(value);
99
- }
21
+ type ExtendedLogger = StrictLogger & {
22
+ child?: (bindings?: Record<string, unknown>) => StrictLogger;
23
+ [key: symbol]: unknown;
24
+ };
25
+ const anyLog = logger as ExtendedLogger;
26
+ const asJson = (pino.symbols as Record<string, symbol>).asJsonSym;
27
+ const isPinoInstance = typeof (anyLog as Record<symbol, unknown>)[asJson] === "function";
28
+
29
+ if (isPinoInstance) {
30
+ // pino-http binds `req` (and customProps) to a child logger when the request arrives,
31
+ // before body parsers run, and calls customProps again on finish. Binding there loses
32
+ // req.body and writes every custom field twice. Instead keep the arrival child quiet
33
+ // (reqId only) and build the whole access line once, when the response finishes.
34
+ const accessFields = (req: Request, res: Response) => ({
35
+ remoteAddress: req.ip || req.socket?.remoteAddress,
36
+ method: req.method,
37
+ url: redactOriginalURL(req.originalUrl || req.url || ""),
38
+ protocol: req.protocol,
39
+ hostname: req.hostname,
40
+ httpVersion: req.httpVersionMajor
41
+ ? `${req.httpVersionMajor}.${req.httpVersionMinor}`
42
+ : req.httpVersion,
43
+ userAgent: req.headers ? req.headers["user-agent"] : undefined,
44
+ req,
45
+ status: res.statusCode ? res.statusCode : 0,
46
+ });
100
47
 
101
- export function redactHeaders(headers: Request["headers"]): Request["headers"] {
102
- const clean = { ...headers };
103
- for (const [name, value] of Object.entries(clean)) {
104
- const lower = name.toLowerCase();
105
- if (_.isUndefined(value) || (lower !== "cookie" && !keyHeaders.includes(lower))) {
106
- continue;
107
- }
108
- clean[name] = redactHeaderValue(lower, value);
109
- }
110
- return clean;
111
- }
48
+ const pHttp = pinoHttp({
49
+ logger: anyLog as unknown as pino.Logger,
50
+ quietReqLogger: true,
51
+ quietResLogger: true,
52
+ customSuccessObject: (req: unknown, res: unknown, val: Record<string, unknown>) => ({
53
+ ...accessFields(req as Request, res as Response),
54
+ ...val,
55
+ }),
56
+ customErrorObject: (req: unknown, res: unknown, _err: unknown, val: Record<string, unknown>) => ({
57
+ ...accessFields(req as Request, res as Response),
58
+ ...val,
59
+ }),
60
+ serializers: {
61
+ req: (req: unknown) => {
62
+ const r = req as Request & { raw?: Request };
63
+ const originalUrl = r.raw?.originalUrl || r.originalUrl || r.url || "";
64
+ return {
65
+ body: redactSecrets(r.raw?.body ?? r.body),
66
+ headers: redactHeaders(r.headers || {}),
67
+ method: r.method,
68
+ originalUrl: redactOriginalURL(originalUrl),
69
+ };
70
+ },
71
+ // pino-http hands this the already serialized error.
72
+ err: (err: unknown) => redactSecrets(err && typeof err === "object" ? { ...err } : err),
73
+ res: (res: unknown) => {
74
+ const r = res as Response & {
75
+ getHeaders?: () => Record<string, unknown>;
76
+ raw?: { getHeaders?: () => Record<string, unknown> };
77
+ };
78
+ const rawRes = r.raw || r;
79
+ let headers: Record<string, unknown> = {};
80
+ if (typeof rawRes.getHeaders === "function") {
81
+ headers = rawRes.getHeaders();
82
+ } else if (typeof r.getHeaders === "function") {
83
+ headers = r.getHeaders();
84
+ }
85
+ return {
86
+ statusCode: r.statusCode,
87
+ headers: redactHeaders(headers as Request["headers"]),
88
+ };
89
+ },
90
+ },
91
+ });
112
92
 
113
- function redactQueryValue(value: Query[string]): Query[string] {
114
- if (_.isString(value)) {
115
- return keepPrefix(value);
93
+ return function accessLogMiddleware(req: Request, res: Response, next: NextFunction) {
94
+ return pHttp(req, res, next);
95
+ };
116
96
  }
117
- if (_.isArray(value)) {
118
- return value.map((entry: unknown) => _.isString(entry) ? keepPrefix(entry) : redacted);
119
- }
120
- return redacted;
121
- }
122
97
 
123
- export function redactQuery(query: Query): Query {
124
- const clean: Query = { ...query };
125
- for (const [name, value] of Object.entries(clean)) {
126
- if (_.isUndefined(value) || !isKeyParam(name)) {
127
- continue;
98
+ // Fallback for mocks or custom logger implementations
99
+ return function accessLogMiddleware(req: Request, res: Response, next: NextFunction) {
100
+ if (typeof anyLog.child === "function" && !req.log) {
101
+ req.log = anyLog.child({}) as unknown as pino.Logger;
128
102
  }
129
- clean[name] = redactQueryValue(value);
130
- }
131
- return clean;
132
- }
133
103
 
134
- function redactParamPair(pair: string): string {
135
- const split = pair.indexOf("=");
136
- if (split < 0 || !isKeyParam(pair.substring(0, split))) {
137
- return pair;
138
- }
139
- return pair.substring(0, split + 1) + keepPrefix(pair.substring(split + 1));
140
- }
141
-
142
- // req.originalUrl is relative, so this splits the string rather than parsing a URL. A
143
- // regex over the whole string backtracks for as long as the url, and the url comes from
144
- // the caller. Splitting on "?" as well as "&" reaches a nested url in a parameter value.
145
- export function redactOriginalURL(maybeURL?: string): string {
146
- if (!_.isString(maybeURL) || maybeURL === "") {
147
- return "";
148
- }
149
-
150
- const queryStart = maybeURL.indexOf("?");
151
- if (queryStart < 0) {
152
- return maybeURL;
153
- }
154
-
155
- const path = maybeURL.substring(0, queryStart + 1);
156
- const parts = maybeURL.substring(queryStart + 1).split(/([?&])/);
157
-
158
- return path + parts.map((part, index) => index % 2 === 0 ? redactParamPair(part) : part).join("");
159
- }
160
-
161
- export default function loggerMiddleware(logger?: Logger) {
162
- return function accessLogMiddleware(req: Request, res: Response, next: NextFunction) {
163
- // This doesn't fire the log immediately, but waits until the response is finished
164
- // This means we have a chance of logging the response code
165
104
  res.on("finish", () => {
166
- // Skip this if no logger is set
167
- if (!logger) {
168
- return;
169
- }
170
105
  logger.info({
171
106
  remoteAddress: req.ip,
172
107
  method: req.method,
173
108
  url: redactOriginalURL(req.originalUrl),
174
109
  protocol: req.protocol,
175
110
  hostname: req.hostname,
176
- httpVersion: `${req.httpVersionMajor}.${req.httpVersionMinor}`,
177
- userAgent: req.headers["user-agent"],
178
- // Added as compatibility
111
+ httpVersion: req.httpVersionMajor
112
+ ? `${req.httpVersionMajor}.${req.httpVersionMinor}`
113
+ : req.httpVersion,
114
+ userAgent: req.headers ? req.headers["user-agent"] : undefined,
179
115
  req: {
180
116
  body: req.body as unknown,
181
117
  headers: redactHeaders(req.headers),
182
118
  method: req.method,
183
- originalUrl: redactOriginalURL(req.originalUrl)
119
+ originalUrl: redactOriginalURL(req.originalUrl),
184
120
  },
185
- status: res.statusCode ? res.statusCode : 0
121
+ status: res.statusCode ? res.statusCode : 0,
186
122
  });
187
123
  });
124
+
188
125
  return next();
189
126
  };
190
127
  }
@@ -1,12 +1,10 @@
1
- import { Logger } from "winston";
2
-
3
1
  import {
4
2
  NextFunction,
5
3
  Request,
6
4
  Response,
7
5
  } from "express";
8
6
  import _ from "lodash";
9
-
7
+ import { StrictLogger } from "../logger-types";
10
8
  import { redactHeaders, redactOriginalURL, redactQuery } from "./logger";
11
9
 
12
10
  export { redactQuery };
@@ -41,7 +39,7 @@ export function requestDuration(endTime: Date, startTime?: Date): number {
41
39
  return endTime.valueOf() - startTime.valueOf();
42
40
  }
43
41
 
44
- export default function statusLogger(logger?: Logger) {
42
+ export default function statusLogger(logger?: StrictLogger | null) {
45
43
  return function requestLogger(req: Request, res: Response, next: NextFunction) {
46
44
  if (!_.isObject(req._startTime)) {
47
45
  req._startTime = new Date();
package/src/otel.ts ADDED
@@ -0,0 +1,57 @@
1
+ export interface OtelSpanContext {
2
+ trace_id?: string;
3
+ span_id?: string;
4
+ trace_flags?: string;
5
+ }
6
+
7
+ // Cached module reference so we only require once
8
+ let otelLoaded = false;
9
+ let otelTrace: typeof import("@opentelemetry/api").trace | null = null;
10
+
11
+ function getOtelTrace(): typeof import("@opentelemetry/api").trace | null {
12
+ if (!otelLoaded) {
13
+ otelLoaded = true;
14
+ try {
15
+ const otel = require("@opentelemetry/api") as typeof import("@opentelemetry/api");
16
+ otelTrace = otel?.trace ?? null;
17
+ } catch {
18
+ otelTrace = null;
19
+ }
20
+ }
21
+ return otelTrace;
22
+ }
23
+
24
+ export function resetOtelForTesting(): void {
25
+ otelLoaded = false;
26
+ otelTrace = null;
27
+ }
28
+
29
+ export function getOtelTraceContext(): OtelSpanContext {
30
+ try {
31
+ const trace = getOtelTrace();
32
+ if (!trace) {
33
+ return {};
34
+ }
35
+ const span = trace.getActiveSpan();
36
+ if (!span) {
37
+ return {};
38
+ }
39
+ const spanContext = span.spanContext();
40
+ const isValid =
41
+ typeof trace.isSpanContextValid === "function"
42
+ ? trace.isSpanContextValid(spanContext)
43
+ : spanContext?.traceId !== "00000000000000000000000000000000" &&
44
+ spanContext?.spanId !== "0000000000000000";
45
+
46
+ if (spanContext && spanContext.traceId && spanContext.spanId && isValid) {
47
+ return {
48
+ trace_id: spanContext.traceId,
49
+ span_id: spanContext.spanId,
50
+ ...(spanContext.traceFlags !== undefined ? { trace_flags: String(spanContext.traceFlags) } : {}),
51
+ };
52
+ }
53
+ } catch {
54
+ // Optional dependency, ignore any errors
55
+ }
56
+ return {};
57
+ }
@@ -0,0 +1,110 @@
1
+ import pino, { LoggerOptions, DestinationStream } from "pino";
2
+ import { LoggerConfig, StrictLogger, LoggerModule } from "./logger-types";
3
+ import { redactSecrets } from "./redaction";
4
+ import { getOtelTraceContext } from "./otel";
5
+
6
+ export { LoggerConfig, StrictLogger, LoggerModule };
7
+
8
+ export function isPinoPrettyAvailable(): boolean {
9
+ try {
10
+ require.resolve("pino-pretty");
11
+ return true;
12
+ } catch {
13
+ try {
14
+ require.resolve("pino-pretty", { paths: [process.cwd()] });
15
+ return true;
16
+ } catch {
17
+ return false;
18
+ }
19
+ }
20
+ }
21
+
22
+ export default function logger(
23
+ config: LoggerConfig,
24
+ customDestination?: DestinationStream
25
+ ): StrictLogger | null {
26
+ // v4 always writes to stdout. Only return null when the caller explicitly
27
+ // turns every sink off (back-compat with the old winston "no transports" case).
28
+ const explicitlyAllOff =
29
+ config.logToConsole === false &&
30
+ config.logToFile !== true &&
31
+ config.logToDatadog !== true;
32
+ const loggingEnabled = !explicitlyAllOff;
33
+
34
+ if (!loggingEnabled) {
35
+ return null;
36
+ }
37
+
38
+ const envPretty =
39
+ process.env.PINO_PRETTY !== undefined
40
+ ? process.env.PINO_PRETTY === "true"
41
+ : undefined;
42
+
43
+ // Pretty output is opt-in: an unset NODE_ENV must not turn production logs into
44
+ // colorized text that the Datadog Agent cannot parse.
45
+ const isDev = process.env.NODE_ENV === "development" && !process.env.CI;
46
+ const wantPretty = config.pretty ?? envPretty ?? isDev;
47
+ const usePretty = wantPretty && isPinoPrettyAvailable();
48
+
49
+ const base: Record<string, unknown> = {
50
+ ...config.extraMeta,
51
+ service: config.name,
52
+ };
53
+
54
+ const options: LoggerOptions = {
55
+ level: config.level || process.env.LOG_LEVEL || "info",
56
+ base,
57
+ // Redaction walks each log object and each set of child bindings once, matching key
58
+ // names without case. pino's redact paths match one exact key per path, and the
59
+ // wildcard paths needed to reach nested bodies cost ~85µs a line.
60
+ formatters: {
61
+ level: (label: string) => ({ level: label }),
62
+ log: (obj: Record<string, unknown>) => redactSecrets(obj),
63
+ bindings: (bindings: pino.Bindings) => redactSecrets(bindings),
64
+ },
65
+ // formatters.log runs before serializers, so a serialized error is redacted here.
66
+ serializers: {
67
+ // stdSerializers.err builds on a prototype object, so copy its fields to a plain
68
+ // object for the walk to enter.
69
+ err: (err: Error) => redactSecrets({ ...pino.stdSerializers.err(err) }),
70
+ },
71
+ timestamp: pino.stdTimeFunctions.isoTime,
72
+ mixin() {
73
+ return getOtelTraceContext();
74
+ },
75
+ };
76
+
77
+ // pino-pretty runs in a worker thread, so a failure there surfaces asynchronously and
78
+ // cannot be caught here. isPinoPrettyAvailable() above is the guard that matters.
79
+ if (usePretty && !customDestination) {
80
+ return redactChildBindings(pino({
81
+ ...options,
82
+ transport: {
83
+ target: "pino-pretty",
84
+ options: {
85
+ colorize: true,
86
+ },
87
+ },
88
+ }));
89
+ }
90
+
91
+ const pinoInstance = customDestination
92
+ ? pino(options, customDestination)
93
+ : pino(options, process.stdout);
94
+
95
+ return redactChildBindings(pinoInstance);
96
+ }
97
+
98
+ // pino applies formatters.bindings to the root logger only; child() resets it. A child is
99
+ // created with Object.create(parent), so overriding child once here covers every
100
+ // descendant, including the ones pino-http creates per request.
101
+ type ChildFn = (this: pino.Logger, bindings: pino.Bindings, options?: pino.ChildLoggerOptions) => pino.Logger;
102
+
103
+ function redactChildBindings(instance: pino.Logger): StrictLogger {
104
+ const pinoChild = instance.child as unknown as ChildFn;
105
+ const child: ChildFn = function child(bindings, childOptions) {
106
+ return pinoChild.call(this, redactSecrets(bindings), childOptions);
107
+ };
108
+ instance.child = child as unknown as pino.Logger["child"];
109
+ return instance as unknown as StrictLogger;
110
+ }