From 0158ca38d3d1a544f36f1635bdbdb963130061e0 Mon Sep 17 00:00:00 2001 From: Eric Crosson Date: Mon, 23 Jun 2025 17:29:04 -0500 Subject: [PATCH 01/11] feat(opentelemetry): create otel instrumentation for typed-express-router --- package-lock.json | 651 ++++++++++-------- packages/typed-express-router/package.json | 13 +- packages/typed-express-router/src/index.ts | 38 + .../typed-express-router/src/telemetry.ts | 187 +++++ packages/typed-express-router/src/types.ts | 5 + .../test/telemetry.test.ts | 483 +++++++++++++ 6 files changed, 1096 insertions(+), 281 deletions(-) create mode 100644 packages/typed-express-router/src/telemetry.ts create mode 100644 packages/typed-express-router/test/telemetry.test.ts diff --git a/package-lock.json b/package-lock.json index 9fbafb96..1f49ef7b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -49,183 +49,28 @@ "link": true }, "node_modules/@babel/code-frame": { - "version": "7.22.13", - "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.22.13.tgz", - "integrity": "sha512-XktuhWlJ5g+3TJXc5upd9Ks1HutSArik6jf2eAjYFyIOf4ej3RN+184cZbzDvbPnuTJIUhPKKJE3cIsYTiAT3w==", + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz", + "integrity": "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==", "dev": true, "dependencies": { - "@babel/highlight": "^7.22.13", - "chalk": "^2.4.2" + "@babel/helper-validator-identifier": "^7.27.1", + "js-tokens": "^4.0.0", + "picocolors": "^1.1.1" }, "engines": { "node": ">=6.9.0" } }, - "node_modules/@babel/code-frame/node_modules/ansi-styles": { - "version": "3.2.1", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", - "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", - "dev": true, - "dependencies": { - "color-convert": "^1.9.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/@babel/code-frame/node_modules/chalk": { - "version": "2.4.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", - "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", - "dev": true, - "dependencies": { - "ansi-styles": "^3.2.1", - "escape-string-regexp": "^1.0.5", - "supports-color": "^5.3.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/@babel/code-frame/node_modules/color-convert": { - "version": "1.9.3", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", - "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", - "dev": true, - "dependencies": { - "color-name": "1.1.3" - } - }, - "node_modules/@babel/code-frame/node_modules/color-name": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", - "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", - "dev": true - }, - "node_modules/@babel/code-frame/node_modules/escape-string-regexp": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", - "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", - "dev": true, - "engines": { - "node": ">=0.8.0" - } - }, - "node_modules/@babel/code-frame/node_modules/has-flag": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", - "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", - "dev": true, - "engines": { - "node": ">=4" - } - }, - "node_modules/@babel/code-frame/node_modules/supports-color": { - "version": "5.5.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", - "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", - "dev": true, - "dependencies": { - "has-flag": "^3.0.0" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/@babel/helper-validator-identifier": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.20.tgz", - "integrity": "sha512-Y4OZ+ytlatR8AI+8KZfKuL5urKp7qey08ha31L8b3BwewJAoJamTzyvxPR/5D+KkdJCGPq/+8TukHBlY10FX9A==", - "dev": true, - "engines": { - "node": ">=6.9.0" - } - }, - "node_modules/@babel/highlight": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.22.20.tgz", - "integrity": "sha512-dkdMCN3py0+ksCgYmGG8jKeGA/8Tk+gJwSYYlFGxG5lmhfKNoAy004YpLxpS1W2J8m/EK2Ew+yOs9pVRwO89mg==", + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.27.1.tgz", + "integrity": "sha512-D2hP9eA+Sqx1kBZgzxZh0y1trbuU+JoDkiEwqhQ36nodYqJwyEIhPSdMNd7lOm/4io72luTPWH20Yda0xOuUow==", "dev": true, - "dependencies": { - "@babel/helper-validator-identifier": "^7.22.20", - "chalk": "^2.4.2", - "js-tokens": "^4.0.0" - }, "engines": { "node": ">=6.9.0" } }, - "node_modules/@babel/highlight/node_modules/ansi-styles": { - "version": "3.2.1", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", - "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", - "dev": true, - "dependencies": { - "color-convert": "^1.9.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/@babel/highlight/node_modules/chalk": { - "version": "2.4.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", - "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", - "dev": true, - "dependencies": { - "ansi-styles": "^3.2.1", - "escape-string-regexp": "^1.0.5", - "supports-color": "^5.3.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/@babel/highlight/node_modules/color-convert": { - "version": "1.9.3", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", - "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", - "dev": true, - "dependencies": { - "color-name": "1.1.3" - } - }, - "node_modules/@babel/highlight/node_modules/color-name": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", - "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", - "dev": true - }, - "node_modules/@babel/highlight/node_modules/escape-string-regexp": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", - "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", - "dev": true, - "engines": { - "node": ">=0.8.0" - } - }, - "node_modules/@babel/highlight/node_modules/has-flag": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", - "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", - "dev": true, - "engines": { - "node": ">=4" - } - }, - "node_modules/@babel/highlight/node_modules/supports-color": { - "version": "5.5.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", - "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", - "dev": true, - "dependencies": { - "has-flag": "^3.0.0" - }, - "engines": { - "node": ">=4" - } - }, "node_modules/@babel/runtime": { "version": "7.22.10", "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.22.10.tgz", @@ -357,15 +202,15 @@ } }, "node_modules/@jridgewell/sourcemap-codec": { - "version": "1.4.15", - "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.4.15.tgz", - "integrity": "sha512-eF2rxCRulEKXHTRiDrDy6erMYWqNw4LPdQ8UQA4huuxaQsVeRPFl2oM8oDGxMFhJUWZf9McpLtJasDDZb/Bpeg==", + "version": "1.5.4", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.4.tgz", + "integrity": "sha512-VT2+G1VQs/9oz078bLrYbecdZKs912zQlkelYpuf+SXF+QvZDYJlbx/LSx+meSAwdDFnF8FVXW92AVjjkVmgFw==", "dev": true }, "node_modules/@jridgewell/trace-mapping": { - "version": "0.3.19", - "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.19.tgz", - "integrity": "sha512-kf37QtfW+Hwx/buWGMPcR60iF9ziHa6r/CZJIHbmcm4+0qrXiVdxegAH0F6yddEVQ7zdkjcGCgCzUu+BcbhQxw==", + "version": "0.3.29", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.29.tgz", + "integrity": "sha512-uw6guiW/gcAGPDhLmd77/6lW8QLeiV5RUTsAX46Db6oLhGaVj4lhnPwb184s1bkc8kdVg/+h988dro8GRDpmYQ==", "dev": true, "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", @@ -824,6 +669,152 @@ "@octokit/openapi-types": "^18.0.0" } }, + "node_modules/@opentelemetry/api": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz", + "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==", + "dev": true, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/@opentelemetry/context-async-hooks": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/context-async-hooks/-/context-async-hooks-1.30.1.tgz", + "integrity": "sha512-s5vvxXPVdjqS3kTLKMeBMvop9hbWkwzBpu+mUO2M7sZtlkyDJGwFe33wRKnbaYDo8ExRVBIIdwIGrqpxHuKttA==", + "dev": true, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/core": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-1.30.1.tgz", + "integrity": "sha512-OOCM2C/QIURhJMuKaekP3TRBxBKxG/TWWA0TL2J6nXUtDnuCtccy49LUJF8xPFXMX+0LMcxFpCo8M9cGY1W6rQ==", + "dev": true, + "dependencies": { + "@opentelemetry/semantic-conventions": "1.28.0" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/core/node_modules/@opentelemetry/semantic-conventions": { + "version": "1.28.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.28.0.tgz", + "integrity": "sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA==", + "dev": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/@opentelemetry/propagator-b3": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/propagator-b3/-/propagator-b3-1.30.1.tgz", + "integrity": "sha512-oATwWWDIJzybAZ4pO76ATN5N6FFbOA1otibAVlS8v90B4S1wClnhRUk7K+2CHAwN1JKYuj4jh/lpCEG5BAqFuQ==", + "dev": true, + "dependencies": { + "@opentelemetry/core": "1.30.1" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/propagator-jaeger": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/propagator-jaeger/-/propagator-jaeger-1.30.1.tgz", + "integrity": "sha512-Pj/BfnYEKIOImirH76M4hDaBSx6HyZ2CXUqk+Kj02m6BB80c/yo4BdWkn/1gDFfU+YPY+bPR2U0DKBfdxCKwmg==", + "dev": true, + "dependencies": { + "@opentelemetry/core": "1.30.1" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/resources": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-1.30.1.tgz", + "integrity": "sha512-5UxZqiAgLYGFjS4s9qm5mBVo433u+dSPUFWVWXmLAD4wB65oMCoXaJP1KJa9DIYYMeHu3z4BZcStG3LC593cWA==", + "dev": true, + "dependencies": { + "@opentelemetry/core": "1.30.1", + "@opentelemetry/semantic-conventions": "1.28.0" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/resources/node_modules/@opentelemetry/semantic-conventions": { + "version": "1.28.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.28.0.tgz", + "integrity": "sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA==", + "dev": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/@opentelemetry/sdk-trace-base": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-1.30.1.tgz", + "integrity": "sha512-jVPgBbH1gCy2Lb7X0AVQ8XAfgg0pJ4nvl8/IiQA6nxOsPvS+0zMJaFSs2ltXe0J6C8dqjcnpyqINDJmU30+uOg==", + "dev": true, + "dependencies": { + "@opentelemetry/core": "1.30.1", + "@opentelemetry/resources": "1.30.1", + "@opentelemetry/semantic-conventions": "1.28.0" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace-base/node_modules/@opentelemetry/semantic-conventions": { + "version": "1.28.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.28.0.tgz", + "integrity": "sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA==", + "dev": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/@opentelemetry/sdk-trace-node": { + "version": "1.30.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-node/-/sdk-trace-node-1.30.1.tgz", + "integrity": "sha512-cBjYOINt1JxXdpw1e5MlHmFRc5fgj4GW/86vsKFxJCJ8AL4PdVtYH41gWwl4qd4uQjqEL1oJVrXkSy5cnduAnQ==", + "dev": true, + "dependencies": { + "@opentelemetry/context-async-hooks": "1.30.1", + "@opentelemetry/core": "1.30.1", + "@opentelemetry/propagator-b3": "1.30.1", + "@opentelemetry/propagator-jaeger": "1.30.1", + "@opentelemetry/sdk-trace-base": "1.30.1", + "semver": "^7.5.2" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, "node_modules/@oxc-resolver/binding-darwin-arm64": { "version": "1.10.2", "resolved": "https://registry.npmjs.org/@oxc-resolver/binding-darwin-arm64/-/binding-darwin-arm64-1.10.2.tgz", @@ -2186,16 +2177,25 @@ } } }, - "node_modules/call-bind": { - "version": "1.0.7", - "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.7.tgz", - "integrity": "sha512-GHTSNSYICQ7scH7sZ+M2rFopRoLh8t2bLSW6BbgrtLsahOIB5iyAVJf9GjWK3cYTDaMj4XdBpM1cA6pIS0Kv2w==", + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", "dependencies": { - "es-define-property": "^1.0.0", "es-errors": "^1.3.0", - "function-bind": "^1.1.2", - "get-intrinsic": "^1.2.4", - "set-function-length": "^1.2.1" + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/call-bound": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", + "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "get-intrinsic": "^1.3.0" }, "engines": { "node": ">= 0.4" @@ -2787,11 +2787,11 @@ } }, "node_modules/debug": { - "version": "4.3.5", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.5.tgz", - "integrity": "sha512-pt0bNEmneDIvdL1Xsd9oDQ/wrQRkXDT4AUWlNZNPKvW5x/jyO9VFXkJUP07vQ2upmw5PlaITaPKc31jK13V+jg==", + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz", + "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==", "dependencies": { - "ms": "2.1.2" + "ms": "^2.1.3" }, "engines": { "node": ">=6.0" @@ -2845,22 +2845,6 @@ "node": ">=4.0.0" } }, - "node_modules/define-data-property": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/define-data-property/-/define-data-property-1.1.4.tgz", - "integrity": "sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==", - "dependencies": { - "es-define-property": "^1.0.0", - "es-errors": "^1.3.0", - "gopd": "^1.0.1" - }, - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, "node_modules/del": { "version": "6.1.1", "resolved": "https://registry.npmjs.org/del/-/del-6.1.1.tgz", @@ -2987,6 +2971,19 @@ "node": ">=8" } }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, "node_modules/duplexer2": { "version": "0.1.4", "resolved": "https://registry.npmjs.org/duplexer2/-/duplexer2-0.1.4.tgz", @@ -3096,12 +3093,9 @@ } }, "node_modules/es-define-property": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.0.tgz", - "integrity": "sha512-jxayLKShrEqqzJ0eumQbVhTYQM27CfT1T35+gCgDFoL82JLsXqTJ76zv6A0YLOgEnLUMvLzsDsGIrl8NFpT2gQ==", - "dependencies": { - "get-intrinsic": "^1.2.4" - }, + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", "engines": { "node": ">= 0.4" } @@ -3114,10 +3108,21 @@ "node": ">= 0.4" } }, + "node_modules/es-object-atoms": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz", + "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==", + "dependencies": { + "es-errors": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + } + }, "node_modules/escalade": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", - "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", "dev": true, "engines": { "node": ">=6" @@ -3446,12 +3451,12 @@ } }, "node_modules/foreground-child": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.1.1.tgz", - "integrity": "sha512-TMKDUnIte6bfb5nWv7V/caI169OHgvwjb7V4WkeUvbQQdjr5rWKqHFiKWb/fcOwB+CzBT+qbWjvj+DVwRskpIg==", + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz", + "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==", "dev": true, "dependencies": { - "cross-spawn": "^7.0.0", + "cross-spawn": "^7.0.6", "signal-exit": "^4.0.1" }, "engines": { @@ -3603,15 +3608,20 @@ } }, "node_modules/get-intrinsic": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.2.4.tgz", - "integrity": "sha512-5uYhsJH8VJBTv7oslg4BznJYhDoRI6waYCxMmCdnTrcCrHA/fCFKoTFz2JKKE0HdDFUF7/oQuhzumXJK7paBRQ==", + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", - "has-proto": "^1.0.1", - "has-symbols": "^1.0.3", - "hasown": "^2.0.0" + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" }, "engines": { "node": ">= 0.4" @@ -3620,6 +3630,18 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, "node_modules/get-stream": { "version": "6.0.1", "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz", @@ -3699,11 +3721,11 @@ } }, "node_modules/gopd": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.0.1.tgz", - "integrity": "sha512-d65bNlIadxvpb/A2abVdlqKqV563juRnZ1Wtk6s1sIR8uNsXR70xqIzVqxVf1eTqDunwT2MkczEeaezCKTZhwA==", - "dependencies": { - "get-intrinsic": "^1.1.3" + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", + "engines": { + "node": ">= 0.4" }, "funding": { "url": "https://github.com/sponsors/ljharb" @@ -3753,32 +3775,10 @@ "node": ">=8" } }, - "node_modules/has-property-descriptors": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.2.tgz", - "integrity": "sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==", - "dependencies": { - "es-define-property": "^1.0.0" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, - "node_modules/has-proto": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/has-proto/-/has-proto-1.0.3.tgz", - "integrity": "sha512-SJ1amZAJUiZS+PhsVLf5tGydlaVB8EdFpaSO4gmiUKUOxk8qzn5AIy4ZeJUmh22znIdk/uMAUT2pl3FxzVUH+Q==", - "engines": { - "node": ">= 0.4" - }, - "funding": { - "url": "https://github.com/sponsors/ljharb" - } - }, "node_modules/has-symbols": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.0.3.tgz", - "integrity": "sha512-l3LCuF6MgDNwTDKkdYGEihYjt5pRPbEg46rtlmnSPlUbgmB8LOIrKJbYYFBSbnPaJexMKtiPO8hmeRjRz2Td+A==", + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", "engines": { "node": ">= 0.4" }, @@ -4627,6 +4627,14 @@ "url": "https://github.com/chalk/chalk?sponsor=1" } }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "engines": { + "node": ">= 0.4" + } + }, "node_modules/media-typer": { "version": "0.3.0", "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", @@ -4860,9 +4868,9 @@ } }, "node_modules/ms": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", - "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==" + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, "node_modules/multi-semantic-release": { "version": "3.0.2", @@ -11179,9 +11187,9 @@ } }, "node_modules/object-inspect": { - "version": "1.13.2", - "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.2.tgz", - "integrity": "sha512-IRZSRuzJiynemAXPYtPe5BoI/RESNYR7TYm50MC5Mqbd3Jmw5y790sErYw3V6SryFJD64b74qQQs9wn5Bg/k3g==", + "version": "1.13.4", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", + "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", "engines": { "node": ">= 0.4" }, @@ -11583,6 +11591,12 @@ "node": ">=8" } }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "dev": true + }, "node_modules/picomatch": { "version": "2.3.1", "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", @@ -13119,11 +13133,6 @@ "node": ">=4" } }, - "node_modules/send/node_modules/ms": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" - }, "node_modules/serve-static": { "version": "1.16.2", "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.16.2.tgz", @@ -13146,22 +13155,6 @@ "node": ">= 0.8" } }, - "node_modules/set-function-length": { - "version": "1.2.2", - "resolved": "https://registry.npmjs.org/set-function-length/-/set-function-length-1.2.2.tgz", - "integrity": "sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg==", - "dependencies": { - "define-data-property": "^1.1.4", - "es-errors": "^1.3.0", - "function-bind": "^1.1.2", - "get-intrinsic": "^1.2.4", - "gopd": "^1.0.1", - "has-property-descriptors": "^1.0.2" - }, - "engines": { - "node": ">= 0.4" - } - }, "node_modules/setprototypeof": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", @@ -13189,14 +13182,65 @@ } }, "node_modules/side-channel": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.6.tgz", - "integrity": "sha512-fDW/EZ6Q9RiO8eFG8Hj+7u/oW+XrPTIChwCOM2+th2A6OblDtYYIpve9m+KvI9Z4C9qSEXlaGR6bTEYHReuglA==", + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz", + "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==", "dependencies": { - "call-bind": "^1.0.7", "es-errors": "^1.3.0", - "get-intrinsic": "^1.2.4", - "object-inspect": "^1.13.1" + "object-inspect": "^1.13.3", + "side-channel-list": "^1.0.0", + "side-channel-map": "^1.0.1", + "side-channel-weakmap": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-list": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz", + "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-map": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", + "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-weakmap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", + "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3", + "side-channel-map": "^1.0.1" }, "engines": { "node": ">= 0.4" @@ -14504,6 +14548,42 @@ "node": ">=4.2.0" } }, + "packages/opentelemetry-instrumentation-express": { + "name": "@opentelemetry/instrumentation-express", + "version": "0.51.0", + "extraneous": true, + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "^2.0.0", + "@opentelemetry/instrumentation": "^0.202.0", + "@opentelemetry/semantic-conventions": "^1.27.0", + "mocha": "^10.8.2", + "ts-node": "^10.9.2" + }, + "devDependencies": { + "@opentelemetry/api": "^1.3.0", + "@opentelemetry/context-async-hooks": "^2.0.0", + "@opentelemetry/contrib-test-utils": "^0.48.0", + "@opentelemetry/sdk-trace-base": "^2.0.0", + "@opentelemetry/sdk-trace-node": "^2.0.0", + "@types/express": "4.17.21", + "@types/mocha": "10.0.10", + "@types/node": "18.18.14", + "@types/sinon": "17.0.4", + "express": "^5.1.0", + "nyc": "17.1.0", + "rimraf": "5.0.10", + "sinon": "15.2.0", + "test-all-versions": "6.1.0", + "typescript": "5.0.4" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.3.0" + } + }, "packages/response": { "name": "@api-ts/response", "version": "0.0.0-semantically-released", @@ -14579,9 +14659,20 @@ }, "devDependencies": { "@api-ts/superagent-wrapper": "0.0.0-semantically-released", + "@opentelemetry/api": "1.9.0", + "@opentelemetry/sdk-trace-base": "1.30.1", + "@opentelemetry/sdk-trace-node": "1.30.1", "@swc-node/register": "1.10.9", "c8": "10.1.3", "typescript": "4.7.4" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.9.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + } } }, "packages/typed-express-router/node_modules/typescript": { diff --git a/packages/typed-express-router/package.json b/packages/typed-express-router/package.json index 940900fe..552799d4 100644 --- a/packages/typed-express-router/package.json +++ b/packages/typed-express-router/package.json @@ -23,11 +23,22 @@ "fp-ts": "^2.0.0", "io-ts": "2.1.3" }, + "peerDependencies": { + "@opentelemetry/api": "^1.9.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + } + }, "devDependencies": { "@api-ts/superagent-wrapper": "0.0.0-semantically-released", "@swc-node/register": "1.10.9", "c8": "10.1.3", - "typescript": "4.7.4" + "typescript": "4.7.4", + "@opentelemetry/sdk-trace-base": "1.30.1", + "@opentelemetry/sdk-trace-node": "1.30.1", + "@opentelemetry/api": "1.9.0" }, "publishConfig": { "access": "public" diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index 12392ebd..31f8e6cb 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -8,6 +8,15 @@ import * as E from 'fp-ts/Either'; import { pipe } from 'fp-ts/pipeable'; import { defaultOnDecodeError, defaultOnEncodeError } from './errors'; import { apiTsPathToExpress } from './path'; +import { + ApiTsAttributes, + createDecodeSpan, + createSendEncodedSpan, + endSpan, + recordSpanDecodeError, + recordSpanEncodeError, + setSpanAttributes, +} from './telemetry'; import { AddRouteHandler, AddUncheckedRouteHandler, @@ -20,6 +29,8 @@ import { WrappedRouterOptions, } from './types'; +import type { Span } from '@opentelemetry/api'; + export type { AfterEncodedResponseSentFn, OnDecodeErrorFn, @@ -81,12 +92,14 @@ export function wrapRouter( ): AddUncheckedRouteHandler { return (apiName, handlers, options) => { const route: HttpRoute | undefined = spec[apiName]?.[method]; + let decodeSpan: Span | undefined; if (route === undefined) { // Should only happen with an explicit undefined property, which we can only prevent at the // type level with the `exactOptionalPropertyTypes` tsconfig option throw Error(`Method "${method}" at "${apiName}" must not be "undefined"'`); } const wrapReqAndRes: UncheckedRequestHandler = (req, res, next) => { + decodeSpan = createDecodeSpan({ apiName, httpRoute: route }); // Intentionally passing explicit arguments here instead of decoding // req by itself because of issues that arise while using Node 16 // See https://github.com/BitGo/api-ts/pull/394 for more information. @@ -103,6 +116,10 @@ export function wrapRouter( status: keyof (typeof route)['response'], payload: unknown, ) => { + const span = createSendEncodedSpan({ + apiName, + httpRoute: route, + }); try { const codec = route.response[status]; if (!codec) { @@ -112,6 +129,9 @@ export function wrapRouter( typeof status === 'number' ? status : KeyToHttpStatus[status as keyof KeyToHttpStatus]; + setSpanAttributes(span, { + [ApiTsAttributes.API_TS_STATUS_CODE]: statusCode, + }); if (statusCode === undefined) { throw new Error(`unknown HTTP status code for key ${status}`); } else if (!codec.is(payload)) { @@ -126,18 +146,36 @@ export function wrapRouter( res as WrappedResponse, ); } catch (err) { + recordSpanEncodeError(span, err); (options?.onEncodeError ?? onEncodeError)( err, req as WrappedRequest, res as WrappedResponse, ); + } finally { + endSpan(span); } }; next(); }; + const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, _, next) => { + pipe( + req.decoded, + E.matchW( + (errs) => { + recordSpanDecodeError(decodeSpan, errs); + }, + () => {}, // No need to do anything on success + ), + ); + endSpan(decodeSpan); + next(); + }; + const middlewareChain = [ wrapReqAndRes, + endDecodeSpanMiddleware, ...routerMiddleware, ...handlers, ] as express.RequestHandler[]; diff --git a/packages/typed-express-router/src/telemetry.ts b/packages/typed-express-router/src/telemetry.ts new file mode 100644 index 00000000..0171fb65 --- /dev/null +++ b/packages/typed-express-router/src/telemetry.ts @@ -0,0 +1,187 @@ +/* + * @api-ts/typed-express-router + */ + +// This module handles the optional dependency on @opentelemetry/api +// It provides functionality for creating spans for decode and sendEncoded operations + +import { Errors } from 'io-ts'; +import type { SpanMetadata } from './types'; +import type { Attributes, Span, Tracer } from '@opentelemetry/api'; +import * as PathReporter from 'io-ts/lib/PathReporter'; + +let otelApi: any; +let tracer: Tracer | undefined; + +// Try to load @opentelemetry/api if available +try { + otelApi = require('@opentelemetry/api'); + if (otelApi) { + tracer = otelApi.trace.getTracer('typed-express-router'); + } +} catch (e) { + // Optional dependency not available, tracing will be disabled + tracer = undefined; +} + +export const ApiTsAttributes = { + /** + * Route name in the API-TS spec + */ + API_TS_ROUTE_NAME: 'api_ts.route.name', + + /** + * HTTP method for the route + */ + API_TS_ROUTE_METHOD: 'api_ts.route.method', + + /** + * Path for the route + */ + API_TS_ROUTE_PATH: 'api_ts.route.path', + + /** + * Request status code + */ + API_TS_STATUS_CODE: 'api_ts.status_code', +}; + +/** + * Create default attributes for decode spans + * + * @param metadata The metadata for a span + * @returns Record of span attributes + */ +export function createDefaultDecodeAttributes(metadata: SpanMetadata): Attributes { + const attributes: Attributes = {}; + + if (metadata.apiName) { + attributes[ApiTsAttributes.API_TS_ROUTE_NAME] = metadata.apiName; + } + + if (metadata.httpRoute) { + if (metadata.httpRoute.method) { + attributes[ApiTsAttributes.API_TS_ROUTE_METHOD] = metadata.httpRoute.method; + } + if (metadata.httpRoute.path) { + attributes[ApiTsAttributes.API_TS_ROUTE_PATH] = metadata.httpRoute.path; + } + } + + return attributes; +} + +/** + * Create default attributes for encode spans + * + * @param metadata The metadata for a span + * @returns Record of span attributes + */ +export function createDefaultEncodeAttributes(metadata: SpanMetadata): Attributes { + const attributes: Attributes = {}; + + if (metadata.apiName) { + attributes[ApiTsAttributes.API_TS_ROUTE_NAME] = metadata.apiName; + } + + if (metadata.httpRoute) { + if (metadata.httpRoute.method) { + attributes[ApiTsAttributes.API_TS_ROUTE_METHOD] = metadata.httpRoute.method; + } + if (metadata.httpRoute.path) { + attributes[ApiTsAttributes.API_TS_ROUTE_PATH] = metadata.httpRoute.path; + } + } + + return attributes; +} + +/** + * Creates a span for the decode operation if OpenTelemetry is available + * @param metadata The metadata for a span + * @returns A span object or undefined if tracing is disabled + */ +export function createDecodeSpan(metadata: SpanMetadata): Span | undefined { + if (!tracer || !otelApi) { + return undefined; + } + + const span = tracer.startSpan(`typed-express-router.decode`); + const decodeAttributes = createDefaultDecodeAttributes(metadata); + span.setAttributes(decodeAttributes); + + return span; +} + +/** + * Creates a span for the sendEncoded operation if OpenTelemetry is available + * @param metadata The metadata for a span + * @returns A span object or undefined if tracing is disabled + */ +export function createSendEncodedSpan(metadata: SpanMetadata): Span | undefined { + if (!tracer || !otelApi) { + return undefined; + } + + const span = tracer.startSpan(`typed-express-router.encode`); + + const encodeAttributes = createDefaultEncodeAttributes(metadata); + // Add attributes to provide context for the span + span.setAttributes(encodeAttributes); + + return span; +} + +/** + * Records an error on an encode span + * @param span The span to record the error on + * @param error The error to record + */ +export function recordSpanEncodeError(span: Span | undefined, error: unknown): void { + if (!span || !otelApi) { + return; + } + span.recordException(error instanceof Error ? error : new Error(String(error))); + span.setStatus({ code: otelApi.SpanStatusCode.ERROR }); +} + +/** + * Records errors on a decode span + * @param span The span to record the errors on + * @param errors The errors to record + */ +export function recordSpanDecodeError(span: Span | undefined, errors: Errors): void { + if (!span || !otelApi) { + return; + } + const validationErrors = PathReporter.failure(errors); + const validationErrorMessage = validationErrors.join('\n'); + span.recordException(new Error(validationErrorMessage)); + span.setStatus({ code: otelApi.SpanStatusCode.ERROR }); +} + +/** + * Sets a span's attributes if it exists + * @param span The span to modify + * @param errors The attributes to modify the span with + */ +export function setSpanAttributes( + span: Span | undefined, + attributes: Attributes, +): void { + if (!span) { + return; + } + span.setAttributes(attributes); +} + +/** + * Ends a span if it exists + * @param span The span to end + */ +export function endSpan(span: Span | undefined): void { + if (!span) { + return; + } + span.end(); +} diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index fd548dcd..798b79cd 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -204,3 +204,8 @@ export type WrappedRouter = Omit< */ patchUnchecked: AddUncheckedRouteHandler; }; + +export type SpanMetadata = { + apiName?: string; + httpRoute?: HttpRoute; +}; diff --git a/packages/typed-express-router/test/telemetry.test.ts b/packages/typed-express-router/test/telemetry.test.ts new file mode 100644 index 00000000..44e02dd4 --- /dev/null +++ b/packages/typed-express-router/test/telemetry.test.ts @@ -0,0 +1,483 @@ +import * as t from 'io-ts'; +import * as http from 'http'; +import { apiSpec, httpRequest, HttpRoute, httpRoute } from '@api-ts/io-ts-http'; +import type { TypedRequestHandler } from '../src/types'; +import { + InMemorySpanExporter, + SimpleSpanProcessor, +} from '@opentelemetry/sdk-trace-base'; +import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; +import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks'; +import { Span, SpanKind, context, trace } from '@opentelemetry/api'; +import { setRPCMetadata, RPCType } from '@opentelemetry/core'; +import express from 'express'; +import { createRouter } from '../src'; +import assert from 'node:assert'; +import { ApiTsAttributes } from '../src/telemetry'; +import test, { beforeEach, afterEach } from 'node:test'; + +const makeRequest = ( + server: http.Server, + method: string, + path: string, + body?: any, +): Promise<{ statusCode: number; data: string }> => { + return new Promise((resolve, reject) => { + const url = `http://localhost:${(server.address() as any).port}${path}`; + + const options: http.RequestOptions = { + method, + headers: { + 'Content-Type': 'application/json', + }, + }; + + const req = http.request(url, options, (res) => { + let data = ''; + res.on('data', (chunk) => { + data += chunk; + }); + res.on('end', () => { + resolve({ + statusCode: res.statusCode || 0, + data, + }); + }); + }); + + req.on('error', reject); + + if (body) { + req.write(JSON.stringify(body)); + } + + req.end(); + }); +}; + +const PutHello = httpRoute({ + path: '/hello', + method: 'PUT', + request: httpRequest({ + body: { + secretCode: t.number, + }, + }), + response: { + 200: t.type({ + message: t.string, + }), + 400: t.type({ + errors: t.string, + }), + 404: t.unknown, + 500: t.unknown, + }, +}); +type PutHello = typeof PutHello; + +const GetHello = httpRoute({ + path: '/hello/{id}', + method: 'GET', + request: httpRequest({ + params: { + id: t.string, + }, + }), + response: { + 200: t.type({ + id: t.string, + }), + }, +}); + +const GetHelloBad = httpRoute({ + path: '/hello/bad/{id}', + method: 'GET', + request: httpRequest({ + params: { + id: t.string, + }, + }), + response: { + 200: t.type({ + id: t.string, + }), + }, +}); + +const TestApiSpec = apiSpec({ + 'hello.world': { + put: PutHello, + get: GetHello, + }, + 'hello.world.bad': { + get: GetHelloBad, + }, +}); + +type TestApiSpec = typeof TestApiSpec; + +const CreateHelloWorld: TypedRequestHandler = ( + req, + res, +) => { + const { secretCode } = req.decoded; + if (secretCode === 0) { + res.sendEncoded(400, { + errors: 'Please do not tell me zero! I will now explode', + }); + } else { + res.sendEncoded(200, { + message: + secretCode === 42 ? 'Everything you see from here is yours' : "Who's there?", + }); + } +}; + +const GetHelloWorld: TypedRequestHandler = ( + { decoded: { id } }, + res, +) => res.sendEncoded(200, { id }); + +const GetHelloWorldBad: TypedRequestHandler = ( + { decoded: { id } }, + res, +) => res.sendEncoded(200, { bad: id } as any); + +const memoryExporter = new InMemorySpanExporter(); +const spanProcessor = new SimpleSpanProcessor(memoryExporter); +const provider = new NodeTracerProvider({ + spanProcessors: [spanProcessor], +}); +const tracer = provider.getTracer('typed-express-router'); +const contextManager = new AsyncLocalStorageContextManager().enable(); +let server: http.Server; +let rootSpan: Span; + +context.setGlobalContextManager(contextManager); +provider.register(); + +beforeEach(async () => { + rootSpan = tracer.startSpan('rootSpan'); + + const app = express(); + app.use(express.json()); + + app.use((_, __, next) => { + const rpcMetadata = { type: RPCType.HTTP, span: rootSpan }; + return context.with( + setRPCMetadata(trace.setSpan(context.active(), rootSpan), rpcMetadata), + next, + ); + }); + + const router = createRouter(TestApiSpec); + + router.put('hello.world', [CreateHelloWorld]); + router.get('hello.world', [GetHelloWorld]); + router.get('hello.world.bad', [GetHelloWorldBad]); + + app.use(router); + + server = http.createServer(app); + + await new Promise((resolve) => { + server.listen(0, () => { + resolve(); + }); + }); +}); + +afterEach(() => { + contextManager.disable(); + contextManager.enable(); + memoryExporter.reset(); + server?.close(); +}); + +const getSpans = () => memoryExporter.getFinishedSpans(); + +test('should capture spans for a request', async () => { + await context.with(trace.setSpan(context.active(), rootSpan), async () => { + const response = await makeRequest(server, 'PUT', '/hello', { secretCode: 42 }); + rootSpan.end(); + + assert.strictEqual(response.statusCode, 200); + const responseData = JSON.parse(response.data); + assert.strictEqual(responseData.message, 'Everything you see from here is yours'); + + // Check spans + const spans = getSpans(); + // rootSpan, encode, decode + assert.ok(spans.length >= 3, `Expected at least 3 spans but got ${spans.length}`); + + // Find decode span + const decodeSpan = spans.find( + (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(decodeSpan, 'Decode span not found'); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + 'hello.world', + ); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello', + ); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], + 'PUT', + ); + + // Find encode span + const encodeSpan = spans.find( + (span) => span.name.includes('encode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(encodeSpan, 'Encode span not found'); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + 'hello.world', + ); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello', + ); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], + 'PUT', + ); + }); +}); + +test('should handle route parameters correctly', async () => { + await context.with(trace.setSpan(context.active(), rootSpan), async () => { + // Make request with parameter + const response = await makeRequest(server, 'GET', '/hello/123', undefined); + rootSpan.end(); + + assert.strictEqual(response.statusCode, 200); + const responseData = JSON.parse(response.data); + assert.strictEqual(responseData.id, '123'); + + // Check spans + const spans = getSpans(); + + // Find decode span + const decodeSpan = spans.find( + (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(decodeSpan, 'Decode span not found'); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + 'hello.world', + ); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello/{id}', + ); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], + 'GET', + ); + + // Find encode span + const encodeSpan = spans.find( + (span) => span.name.includes('encode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(encodeSpan, 'Encode span not found'); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + 'hello.world', + ); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello/{id}', + ); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], + 'GET', + ); + }); +}); + +test('should capture bad request responses', async () => { + await context.with(trace.setSpan(context.active(), rootSpan), async () => { + // Make request that will trigger validation error + const response = await makeRequest(server, 'PUT', '/hello', { secretCode: 0 }); + rootSpan.end(); + + assert.strictEqual(response.statusCode, 400); + const responseData = JSON.parse(response.data); + assert.strictEqual( + responseData.errors, + 'Please do not tell me zero! I will now explode', + ); + + // Check spans + const spans = getSpans(); + + // Find encode span + const encodeSpan = spans.find( + (span) => span.name.includes('encode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(encodeSpan, 'Encode span not found'); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello', + ); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_STATUS_CODE], + 400, + ); + }); +}); + +test('should work with concurrent requests', async () => { + await context.with(trace.setSpan(context.active(), rootSpan), async () => { + // Make multiple concurrent requests + const requests = [ + makeRequest(server, 'GET', '/hello/1', undefined), + makeRequest(server, 'GET', '/hello/2', undefined), + makeRequest(server, 'GET', '/hello/3', undefined), + ]; + rootSpan.end(); + + const responses = await Promise.all(requests); + + // Verify all responses were successful + responses.forEach((response) => { + assert.ok( + [200, 201].includes(response.statusCode), + `Expected 200 or 201 status, got ${response.statusCode}`, + ); + }); + + // Check spans - we should have decode and encode spans for each request + const spans = getSpans(); + + const decodeSpans = spans.filter((span) => span.name.includes('decode')); + const encodeSpans = spans.filter((span) => span.name.includes('encode')); + + assert.ok( + decodeSpans.length >= 3, + `Expected at least 3 decode spans, got ${decodeSpans.length}`, + ); + assert.ok( + encodeSpans.length >= 3, + `Expected at least 3 encode spans, got ${encodeSpans.length}`, + ); + + // Verify we have spans for different route paths + const paths = spans + .filter((span) => span.name.includes('decode')) + .map((span) => span.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH]); + + assert.ok(paths.includes('/hello/{id}'), 'Missing spans for /hello/{id} path'); + }); +}); + +test('should capture encode errors', async () => { + await context.with(trace.setSpan(context.active(), rootSpan), async () => { + const response = await makeRequest(server, 'GET', '/hello/bad/1'); + rootSpan.end(); + + assert.strictEqual(response.statusCode, 500); + + // Check spans + const spans = getSpans(); + + // Find encode span + const encodeSpan = spans.find( + (span) => span.name.includes('encode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(encodeSpan, 'Encode span not found'); + assert.strictEqual( + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello/bad/{id}', + ); + const errorEvents = encodeSpan.events.filter((event) => { + const attributes = event.attributes; + if (!attributes) return false; + return attributes['exception.type'] === 'Error'; + }); + assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); + }); +}); + +test('should capture decode errors', async () => { + await context.with(trace.setSpan(context.active(), rootSpan), async () => { + const response = await makeRequest(server, 'PUT', '/hello', { + secretCode: 'not a number', + }); + rootSpan.end(); + + assert.strictEqual(response.statusCode, 400); + + // Check spans + const spans = getSpans(); + + // Find encode span + const decodeSpan = spans.find( + (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(decodeSpan, 'Encode span not found'); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + '/hello', + ); + const errorEvents = decodeSpan.events.filter((event) => { + const attributes = event.attributes; + if (!attributes) return false; + return attributes['exception.type'] === 'Error'; + }); + assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); + }); +}); + +test('should handle missing opentelemetry package', async () => { + const originalCache = { ...require.cache }; + const resolvedPath = require.resolve('@opentelemetry/api'); + + try { + require.cache[resolvedPath] = { + ...require.cache[resolvedPath]!!, + exports: undefined, + }; + delete require.cache[require.resolve('../src/telemetry')]; + + const tempModule = await import('../src/telemetry'); + + const testMetadata = { + apiName: 'test.missing.otel', + httpRoute: { + path: '/test-path', + method: 'GET', + } as HttpRoute, + }; + // Verify that span creation functions return undefined + const decodeSpan = tempModule.createDecodeSpan(testMetadata); + const encodeSpan = tempModule.createSendEncodedSpan(testMetadata); + + assert.strictEqual( + decodeSpan, + undefined, + 'Decode span should be undefined when OpenTelemetry is missing', + ); + assert.strictEqual( + encodeSpan, + undefined, + 'Encode span should be undefined when OpenTelemetry is missing', + ); + + // Verify that other functions don't throw when given undefined spans + assert.doesNotThrow(() => { + tempModule.recordSpanEncodeError(decodeSpan, 'Test error'); + tempModule.recordSpanDecodeError(encodeSpan, []); + tempModule.setSpanAttributes(decodeSpan, {}); + tempModule.endSpan(encodeSpan); + }, 'Telemetry functions should handle undefined spans gracefully'); + } finally { + require.cache = originalCache; + } +}); From c044072fc27be3e07b81fa1f99fb08a17f9c65f5 Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Thu, 10 Jul 2025 16:02:14 -0400 Subject: [PATCH 02/11] fix: widen the supported version for @opentelemetry/api --- packages/typed-express-router/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/typed-express-router/package.json b/packages/typed-express-router/package.json index 552799d4..cf8b59e1 100644 --- a/packages/typed-express-router/package.json +++ b/packages/typed-express-router/package.json @@ -24,7 +24,7 @@ "io-ts": "2.1.3" }, "peerDependencies": { - "@opentelemetry/api": "^1.9.0" + "@opentelemetry/api": "^1.0.0" }, "peerDependenciesMeta": { "@opentelemetry/api": { From a0275b134aca2507ee5492f9354d6ca066ce4e67 Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Thu, 10 Jul 2025 16:04:37 -0400 Subject: [PATCH 03/11] fix: update package-lock --- package-lock.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package-lock.json b/package-lock.json index 1f49ef7b..9a2dbabc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14667,7 +14667,7 @@ "typescript": "4.7.4" }, "peerDependencies": { - "@opentelemetry/api": "^1.9.0" + "@opentelemetry/api": "^1.0.0" }, "peerDependenciesMeta": { "@opentelemetry/api": { From c1af7da3c3b0e232d1ba6933fcab3df187edb105 Mon Sep 17 00:00:00 2001 From: Eric Crosson Date: Thu, 10 Jul 2025 16:09:47 -0500 Subject: [PATCH 04/11] wip: checkpoint Back to you, @starfy84! Co-authored-by: Dereck Tu --- packages/typed-express-router/src/errors.ts | 8 +- packages/typed-express-router/src/index.ts | 25 +-- .../typed-express-router/src/telemetry.ts | 53 +++--- packages/typed-express-router/src/types.ts | 8 +- .../typed-express-router/test/server.test.ts | 12 +- .../test/telemetry.test.ts | 180 +++++++----------- 6 files changed, 131 insertions(+), 155 deletions(-) diff --git a/packages/typed-express-router/src/errors.ts b/packages/typed-express-router/src/errors.ts index 226f84ac..45a0734c 100644 --- a/packages/typed-express-router/src/errors.ts +++ b/packages/typed-express-router/src/errors.ts @@ -2,14 +2,16 @@ import express from 'express'; import { Errors } from 'io-ts'; import * as PathReporter from 'io-ts/lib/PathReporter'; +import { OnDecodeErrorFn } from './types'; + export function defaultOnDecodeError( errs: Errors, _req: express.Request, - res: express.Response, -) { + _res: express.Response, +): ReturnType { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); - res.status(400).json({ error: validationErrorMessage }).end(); + return { response: validationErrorMessage, statusCode: 400 }; } export function defaultOnEncodeError( diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index 31f8e6cb..a827e4f0 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -116,7 +116,7 @@ export function wrapRouter( status: keyof (typeof route)['response'], payload: unknown, ) => { - const span = createSendEncodedSpan({ + const encodeSpan = createSendEncodedSpan({ apiName, httpRoute: route, }); @@ -129,7 +129,7 @@ export function wrapRouter( typeof status === 'number' ? status : KeyToHttpStatus[status as keyof KeyToHttpStatus]; - setSpanAttributes(span, { + setSpanAttributes(encodeSpan, { [ApiTsAttributes.API_TS_STATUS_CODE]: statusCode, }); if (statusCode === undefined) { @@ -146,28 +146,26 @@ export function wrapRouter( res as WrappedResponse, ); } catch (err) { - recordSpanEncodeError(span, err); + recordSpanEncodeError(encodeSpan, err); (options?.onEncodeError ?? onEncodeError)( err, req as WrappedRequest, res as WrappedResponse, ); } finally { - endSpan(span); + endSpan(encodeSpan); } }; next(); }; - const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, _, next) => { + const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, res, next) => { pipe( req.decoded, - E.matchW( - (errs) => { - recordSpanDecodeError(decodeSpan, errs); - }, - () => {}, // No need to do anything on success - ), + E.getOrElseW((errs) => { + const error = (onDecodeError ?? onDecodeError)(errs, req, res); + recordSpanDecodeError(decodeSpan, error.response, error.statusCode); + }), ); endSpan(decodeSpan); next(); @@ -202,7 +200,10 @@ export function wrapRouter( req.decoded, E.matchW( (errs) => { - (options?.onDecodeError ?? onDecodeError)(errs, req, res); + const { response, statusCode } = ( + options?.onDecodeError ?? onDecodeError + )(errs, req, res); + res.status(statusCode).json(response).end(); }, (value) => { req.decoded = value; diff --git a/packages/typed-express-router/src/telemetry.ts b/packages/typed-express-router/src/telemetry.ts index 0171fb65..a0c379e8 100644 --- a/packages/typed-express-router/src/telemetry.ts +++ b/packages/typed-express-router/src/telemetry.ts @@ -5,43 +5,42 @@ // This module handles the optional dependency on @opentelemetry/api // It provides functionality for creating spans for decode and sendEncoded operations -import { Errors } from 'io-ts'; -import type { SpanMetadata } from './types'; import type { Attributes, Span, Tracer } from '@opentelemetry/api'; -import * as PathReporter from 'io-ts/lib/PathReporter'; + +import type { Json, SpanMetadata } from './types'; let otelApi: any; let tracer: Tracer | undefined; -// Try to load @opentelemetry/api if available +// Load @opentelemetry/api, if available. try { otelApi = require('@opentelemetry/api'); if (otelApi) { tracer = otelApi.trace.getTracer('typed-express-router'); } } catch (e) { - // Optional dependency not available, tracing will be disabled + // Optional dependency not available, so tracing will be disabled. tracer = undefined; } export const ApiTsAttributes = { /** - * Route name in the API-TS spec + * The Operation ID of the HTTP request */ - API_TS_ROUTE_NAME: 'api_ts.route.name', + API_TS_OPERATION_ID: 'api_ts.operation_id', /** - * HTTP method for the route + * The method of the HTTP request */ - API_TS_ROUTE_METHOD: 'api_ts.route.method', + API_TS_METHOD: 'api_ts.method', /** - * Path for the route + * The path of the HTTP request */ - API_TS_ROUTE_PATH: 'api_ts.route.path', + API_TS_PATH: 'api_ts.path', /** - * Request status code + * Returned HTTP request status code */ API_TS_STATUS_CODE: 'api_ts.status_code', }; @@ -56,15 +55,15 @@ export function createDefaultDecodeAttributes(metadata: SpanMetadata): Attribute const attributes: Attributes = {}; if (metadata.apiName) { - attributes[ApiTsAttributes.API_TS_ROUTE_NAME] = metadata.apiName; + attributes[ApiTsAttributes.API_TS_OPERATION_ID] = metadata.apiName; } if (metadata.httpRoute) { if (metadata.httpRoute.method) { - attributes[ApiTsAttributes.API_TS_ROUTE_METHOD] = metadata.httpRoute.method; + attributes[ApiTsAttributes.API_TS_METHOD] = metadata.httpRoute.method; } if (metadata.httpRoute.path) { - attributes[ApiTsAttributes.API_TS_ROUTE_PATH] = metadata.httpRoute.path; + attributes[ApiTsAttributes.API_TS_PATH] = metadata.httpRoute.path; } } @@ -81,15 +80,15 @@ export function createDefaultEncodeAttributes(metadata: SpanMetadata): Attribute const attributes: Attributes = {}; if (metadata.apiName) { - attributes[ApiTsAttributes.API_TS_ROUTE_NAME] = metadata.apiName; + attributes[ApiTsAttributes.API_TS_OPERATION_ID] = metadata.apiName; } if (metadata.httpRoute) { if (metadata.httpRoute.method) { - attributes[ApiTsAttributes.API_TS_ROUTE_METHOD] = metadata.httpRoute.method; + attributes[ApiTsAttributes.API_TS_METHOD] = metadata.httpRoute.method; } if (metadata.httpRoute.path) { - attributes[ApiTsAttributes.API_TS_ROUTE_PATH] = metadata.httpRoute.path; + attributes[ApiTsAttributes.API_TS_PATH] = metadata.httpRoute.path; } } @@ -148,22 +147,28 @@ export function recordSpanEncodeError(span: Span | undefined, error: unknown): v /** * Records errors on a decode span * @param span The span to record the errors on - * @param errors The errors to record + * @param error The JSON error value to record + * @param statusCode The HTTP status code */ -export function recordSpanDecodeError(span: Span | undefined, errors: Errors): void { +export function recordSpanDecodeError( + span: Span | undefined, + error: Json, + statusCode: number, +): void { if (!span || !otelApi) { return; } - const validationErrors = PathReporter.failure(errors); - const validationErrorMessage = validationErrors.join('\n'); - span.recordException(new Error(validationErrorMessage)); + setSpanAttributes(span, { + [ApiTsAttributes.API_TS_STATUS_CODE]: statusCode, + }); + span.recordException(JSON.stringify(error, null, 2)); span.setStatus({ code: otelApi.SpanStatusCode.ERROR }); } /** * Sets a span's attributes if it exists * @param span The span to modify - * @param errors The attributes to modify the span with + * @param attributes The attributes to modify the span with */ export function setSpanAttributes( span: Span | undefined, diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index 798b79cd..86062a51 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -2,6 +2,12 @@ import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http'; import express from 'express'; import * as t from 'io-ts'; +export type Json = boolean | number | string | null | JsonArray | JsonRecord; +export interface JsonRecord { + readonly [key: string]: Json; +} +export interface JsonArray extends ReadonlyArray {} + export type Methods = Lowercase; export type WrappedRequest = express.Request & { @@ -22,7 +28,7 @@ export type OnDecodeErrorFn = ( errs: t.Errors, req: express.Request, res: express.Response, -) => void; +) => { response: Json; statusCode: number }; export type OnEncodeErrorFn = ( err: unknown, diff --git a/packages/typed-express-router/test/server.test.ts b/packages/typed-express-router/test/server.test.ts index aed47768..309c7d92 100644 --- a/packages/typed-express-router/test/server.test.ts +++ b/packages/typed-express-router/test/server.test.ts @@ -361,8 +361,8 @@ test('should return a 400 when request fails to decode', async () => { test('should invoke custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, res) => { - res.status(400).json('Custom decode error').end(); + onDecodeError: (_errs, _req, _res) => { + return { response: 'Custom decode error', statusCode: 400 }; }, }); @@ -390,8 +390,8 @@ test('should invoke custom decode error function', async () => { test('should invoke per-route custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, res) => { - res.status(400).json('Top-level decode error').end(); + onDecodeError: (_errs, _req, _res) => { + return { response: 'Top-level decode error', statusCode: 400 }; }, }); @@ -403,8 +403,8 @@ test('should invoke per-route custom decode error function', async () => { }, ], { - onDecodeError: (_errs, _req, res) => { - res.status(400).json('Route decode error').end(); + onDecodeError: (_errs, _req, _res) => { + return { response: 'Route decode error', statusCode: 400 }; }, routeAliases: ['/helloNoPathParams'], }, diff --git a/packages/typed-express-router/test/telemetry.test.ts b/packages/typed-express-router/test/telemetry.test.ts index 44e02dd4..451f3909 100644 --- a/packages/typed-express-router/test/telemetry.test.ts +++ b/packages/typed-express-router/test/telemetry.test.ts @@ -174,8 +174,8 @@ beforeEach(async () => { const router = createRouter(TestApiSpec); - router.put('hello.world', [CreateHelloWorld]); router.get('hello.world', [GetHelloWorld]); + router.put('hello.world', [CreateHelloWorld]); router.get('hello.world.bad', [GetHelloWorldBad]); app.use(router); @@ -198,17 +198,20 @@ afterEach(() => { const getSpans = () => memoryExporter.getFinishedSpans(); -test('should capture spans for a request', async () => { +test('should capture span attributes for GET requests', async () => { await context.with(trace.setSpan(context.active(), rootSpan), async () => { - const response = await makeRequest(server, 'PUT', '/hello', { secretCode: 42 }); + // Make request with path parameter + const response = await makeRequest(server, 'GET', '/hello/123', undefined); rootSpan.end(); assert.strictEqual(response.statusCode, 200); + const responseData = JSON.parse(response.data); - assert.strictEqual(responseData.message, 'Everything you see from here is yours'); + assert.strictEqual(responseData.id, '123'); // Check spans const spans = getSpans(); + // rootSpan, encode, decode assert.ok(spans.length >= 3, `Expected at least 3 spans but got ${spans.length}`); @@ -218,17 +221,14 @@ test('should capture spans for a request', async () => { ); assert.ok(decodeSpan, 'Decode span not found'); assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_OPERATION_ID], 'hello.world', ); assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], - '/hello', - ); - assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], - 'PUT', + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], + '/hello/{id}', ); + assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_METHOD], 'GET'); // Find encode span const encodeSpan = spans.find( @@ -236,50 +236,44 @@ test('should capture spans for a request', async () => { ); assert.ok(encodeSpan, 'Encode span not found'); assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_OPERATION_ID], 'hello.world', ); assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], - '/hello', - ); - assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], - 'PUT', + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], + '/hello/{id}', ); + assert.strictEqual(encodeSpan?.attributes?.[ApiTsAttributes.API_TS_METHOD], 'GET'); }); }); -test('should handle route parameters correctly', async () => { +test('should capture span attributes for PUT requests', async () => { await context.with(trace.setSpan(context.active(), rootSpan), async () => { - // Make request with parameter - const response = await makeRequest(server, 'GET', '/hello/123', undefined); + const response = await makeRequest(server, 'PUT', '/hello', { secretCode: 42 }); rootSpan.end(); assert.strictEqual(response.statusCode, 200); + const responseData = JSON.parse(response.data); - assert.strictEqual(responseData.id, '123'); + assert.strictEqual(responseData.message, 'Everything you see from here is yours'); // Check spans const spans = getSpans(); + // rootSpan, encode, decode + assert.ok(spans.length >= 3, `Expected at least 3 spans but got ${spans.length}`); + // Find decode span const decodeSpan = spans.find( (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, ); assert.ok(decodeSpan, 'Decode span not found'); assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_OPERATION_ID], 'hello.world', ); - assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], - '/hello/{id}', - ); - assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], - 'GET', - ); + assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); + assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_METHOD], 'PUT'); // Find encode span const encodeSpan = spans.find( @@ -287,21 +281,19 @@ test('should handle route parameters correctly', async () => { ); assert.ok(encodeSpan, 'Encode span not found'); assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_NAME], + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_OPERATION_ID], 'hello.world', ); - assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], - '/hello/{id}', - ); - assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_METHOD], - 'GET', - ); + assert.strictEqual(encodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); + assert.strictEqual(encodeSpan?.attributes?.[ApiTsAttributes.API_TS_METHOD], 'PUT'); }); }); -test('should capture bad request responses', async () => { +// TODO: POST +// TODO: DELETE +// TODO: PATCH + +test('should capture bad-request responses', async () => { await context.with(trace.setSpan(context.active(), rootSpan), async () => { // Make request that will trigger validation error const response = await makeRequest(server, 'PUT', '/hello', { secretCode: 0 }); @@ -317,15 +309,31 @@ test('should capture bad request responses', async () => { // Check spans const spans = getSpans(); + // rootSpan, encode, decode + assert.ok(spans.length >= 3, `Expected at least 3 spans but got ${spans.length}`); + + // Find decode span + const decodeSpan = spans.find( + (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, + ); + assert.ok(decodeSpan, 'Decode span not found'); + assert.strictEqual( + decodeSpan?.attributes?.[ApiTsAttributes.API_TS_OPERATION_ID], + 'hello.world', + ); + assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); + assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_METHOD], 'PUT'); + // Find encode span const encodeSpan = spans.find( (span) => span.name.includes('encode') && span.kind === SpanKind.INTERNAL, ); assert.ok(encodeSpan, 'Encode span not found'); assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], - '/hello', + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_OPERATION_ID], + 'hello.world', ); + assert.strictEqual(encodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); assert.strictEqual( encodeSpan?.attributes?.[ApiTsAttributes.API_TS_STATUS_CODE], 400, @@ -333,47 +341,28 @@ test('should capture bad request responses', async () => { }); }); -test('should work with concurrent requests', async () => { +test('should capture decode errors', async () => { await context.with(trace.setSpan(context.active(), rootSpan), async () => { - // Make multiple concurrent requests - const requests = [ - makeRequest(server, 'GET', '/hello/1', undefined), - makeRequest(server, 'GET', '/hello/2', undefined), - makeRequest(server, 'GET', '/hello/3', undefined), - ]; + const response = await makeRequest(server, 'PUT', '/hello', { + secretCode: 'not a number', + }); rootSpan.end(); - const responses = await Promise.all(requests); - - // Verify all responses were successful - responses.forEach((response) => { - assert.ok( - [200, 201].includes(response.statusCode), - `Expected 200 or 201 status, got ${response.statusCode}`, - ); - }); + assert.strictEqual(response.statusCode, 400); - // Check spans - we should have decode and encode spans for each request + // Check spans const spans = getSpans(); - const decodeSpans = spans.filter((span) => span.name.includes('decode')); - const encodeSpans = spans.filter((span) => span.name.includes('encode')); - - assert.ok( - decodeSpans.length >= 3, - `Expected at least 3 decode spans, got ${decodeSpans.length}`, - ); - assert.ok( - encodeSpans.length >= 3, - `Expected at least 3 encode spans, got ${encodeSpans.length}`, + // Find encode span + const decodeSpan = spans.find( + (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, ); - - // Verify we have spans for different route paths - const paths = spans - .filter((span) => span.name.includes('decode')) - .map((span) => span.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH]); - - assert.ok(paths.includes('/hello/{id}'), 'Missing spans for /hello/{id} path'); + assert.ok(decodeSpan, 'Encode span not found'); + assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); + const errorEvents = decodeSpan.events.filter((event) => { + return event['name'] === 'exception'; + }); + assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); }); }); @@ -387,13 +376,16 @@ test('should capture encode errors', async () => { // Check spans const spans = getSpans(); + // rootSpan, encode, decode + assert.ok(spans.length >= 3, `Expected at least 3 spans but got ${spans.length}`); + // Find encode span const encodeSpan = spans.find( (span) => span.name.includes('encode') && span.kind === SpanKind.INTERNAL, ); assert.ok(encodeSpan, 'Encode span not found'); assert.strictEqual( - encodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], + encodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello/bad/{id}', ); const errorEvents = encodeSpan.events.filter((event) => { @@ -405,36 +397,6 @@ test('should capture encode errors', async () => { }); }); -test('should capture decode errors', async () => { - await context.with(trace.setSpan(context.active(), rootSpan), async () => { - const response = await makeRequest(server, 'PUT', '/hello', { - secretCode: 'not a number', - }); - rootSpan.end(); - - assert.strictEqual(response.statusCode, 400); - - // Check spans - const spans = getSpans(); - - // Find encode span - const decodeSpan = spans.find( - (span) => span.name.includes('decode') && span.kind === SpanKind.INTERNAL, - ); - assert.ok(decodeSpan, 'Encode span not found'); - assert.strictEqual( - decodeSpan?.attributes?.[ApiTsAttributes.API_TS_ROUTE_PATH], - '/hello', - ); - const errorEvents = decodeSpan.events.filter((event) => { - const attributes = event.attributes; - if (!attributes) return false; - return attributes['exception.type'] === 'Error'; - }); - assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); - }); -}); - test('should handle missing opentelemetry package', async () => { const originalCache = { ...require.cache }; const resolvedPath = require.resolve('@opentelemetry/api'); @@ -473,7 +435,7 @@ test('should handle missing opentelemetry package', async () => { // Verify that other functions don't throw when given undefined spans assert.doesNotThrow(() => { tempModule.recordSpanEncodeError(decodeSpan, 'Test error'); - tempModule.recordSpanDecodeError(encodeSpan, []); + tempModule.recordSpanDecodeError(encodeSpan, [], 400); tempModule.setSpanAttributes(decodeSpan, {}); tempModule.endSpan(encodeSpan); }, 'Telemetry functions should handle undefined spans gracefully'); From ab8a1234c9b2a8c442bba8f1ef39e2e716e262b0 Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Tue, 15 Jul 2025 10:47:37 -0400 Subject: [PATCH 05/11] chore: cleanup, pass responseFn in decode error function --- packages/express-wrapper/src/request.ts | 12 ++++++-- packages/typed-express-router/src/errors.ts | 7 +++-- packages/typed-express-router/src/index.ts | 18 +++++++---- packages/typed-express-router/src/types.ts | 7 ++--- .../typed-express-router/test/server.test.ts | 30 +++++++++++++++---- .../test/telemetry.test.ts | 20 ++++++++++++- 6 files changed, 72 insertions(+), 22 deletions(-) diff --git a/packages/express-wrapper/src/request.ts b/packages/express-wrapper/src/request.ts index dfeae64b..cdbf31f0 100644 --- a/packages/express-wrapper/src/request.ts +++ b/packages/express-wrapper/src/request.ts @@ -97,9 +97,15 @@ const createNamedFunction = void>( export const onDecodeError: OnDecodeErrorFn = (errs, _req, res) => { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); - res.writeHead(400, { 'Content-Type': 'application/json' }); - res.write(JSON.stringify({ error: validationErrorMessage })); - res.end(); + return { + response: validationErrorMessage, + statusCode: 400, + responseFn: () => { + res.writeHead(400, { 'Content-Type': 'application/json' }); + res.write(JSON.stringify({ error: validationErrorMessage })); + res.end(); + }, + }; }; export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => { diff --git a/packages/typed-express-router/src/errors.ts b/packages/typed-express-router/src/errors.ts index 45a0734c..4101aa8b 100644 --- a/packages/typed-express-router/src/errors.ts +++ b/packages/typed-express-router/src/errors.ts @@ -7,11 +7,14 @@ import { OnDecodeErrorFn } from './types'; export function defaultOnDecodeError( errs: Errors, _req: express.Request, - _res: express.Response, + res: express.Response, ): ReturnType { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); - return { response: validationErrorMessage, statusCode: 400 }; + const responseFn = () => { + res.status(400).json({ error: validationErrorMessage }).end(); + }; + return { response: validationErrorMessage, statusCode: 400, responseFn }; } export function defaultOnEncodeError( diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index a827e4f0..490964c8 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -163,8 +163,12 @@ export function wrapRouter( pipe( req.decoded, E.getOrElseW((errs) => { - const error = (onDecodeError ?? onDecodeError)(errs, req, res); - recordSpanDecodeError(decodeSpan, error.response, error.statusCode); + const { response, statusCode } = (options?.onDecodeError ?? onDecodeError)( + errs, + req, + res, + ); + recordSpanDecodeError(decodeSpan, response, statusCode); }), ); endSpan(decodeSpan); @@ -200,10 +204,12 @@ export function wrapRouter( req.decoded, E.matchW( (errs) => { - const { response, statusCode } = ( - options?.onDecodeError ?? onDecodeError - )(errs, req, res); - res.status(statusCode).json(response).end(); + const { responseFn } = (options?.onDecodeError ?? onDecodeError)( + errs, + req, + res, + ); + responseFn(); }, (value) => { req.decoded = value; diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index 86062a51..dbbcc596 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -28,7 +28,7 @@ export type OnDecodeErrorFn = ( errs: t.Errors, req: express.Request, res: express.Response, -) => { response: Json; statusCode: number }; +) => { response: Json; statusCode: number; responseFn: () => void }; export type OnEncodeErrorFn = ( err: unknown, @@ -45,13 +45,12 @@ export type AfterEncodedResponseSentFn = ( export type UncheckedWrappedRouteOptions = { onEncodeError?: OnEncodeErrorFn; + onDecodeError?: OnDecodeErrorFn; afterEncodedResponseSent?: AfterEncodedResponseSentFn; routeAliases?: string[]; }; -export type WrappedRouteOptions = UncheckedWrappedRouteOptions & { - onDecodeError?: OnDecodeErrorFn; -}; +export type WrappedRouteOptions = UncheckedWrappedRouteOptions; export type WrappedRouterOptions = express.RouterOptions & WrappedRouteOptions; diff --git a/packages/typed-express-router/test/server.test.ts b/packages/typed-express-router/test/server.test.ts index 309c7d92..42fbed27 100644 --- a/packages/typed-express-router/test/server.test.ts +++ b/packages/typed-express-router/test/server.test.ts @@ -361,8 +361,14 @@ test('should return a 400 when request fails to decode', async () => { test('should invoke custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, _res) => { - return { response: 'Custom decode error', statusCode: 400 }; + onDecodeError: (_errs, _req, res) => { + return { + response: 'Custom decode error', + statusCode: 400, + responseFn: () => { + res.status(400).json('Custom decode error').end(); + }, + }; }, }); @@ -390,8 +396,14 @@ test('should invoke custom decode error function', async () => { test('should invoke per-route custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, _res) => { - return { response: 'Top-level decode error', statusCode: 400 }; + onDecodeError: (_errs, _req, res) => { + return { + response: 'Top-level decode error', + statusCode: 400, + responseFn: () => { + res.status(400).json('Top-level decode error').end(); + }, + }; }, }); @@ -403,8 +415,14 @@ test('should invoke per-route custom decode error function', async () => { }, ], { - onDecodeError: (_errs, _req, _res) => { - return { response: 'Route decode error', statusCode: 400 }; + onDecodeError: (_errs, _req, res) => { + return { + response: 'Route decode error', + statusCode: 400, + responseFn: () => { + res.status(400).json('Route decode error').end(); + }, + }; }, routeAliases: ['/helloNoPathParams'], }, diff --git a/packages/typed-express-router/test/telemetry.test.ts b/packages/typed-express-router/test/telemetry.test.ts index 451f3909..16b968f6 100644 --- a/packages/typed-express-router/test/telemetry.test.ts +++ b/packages/typed-express-router/test/telemetry.test.ts @@ -175,7 +175,17 @@ beforeEach(async () => { const router = createRouter(TestApiSpec); router.get('hello.world', [GetHelloWorld]); - router.put('hello.world', [CreateHelloWorld]); + router.put('hello.world', [CreateHelloWorld], { + onDecodeError: (_errs, _req, res) => { + return { + response: 'Custom Decode Error', + statusCode: 400, + responseFn: () => { + res.status(400).json({ error: 'Custom Decode Error' }); + }, + }; + }, + }); router.get('hello.world.bad', [GetHelloWorldBad]); app.use(router); @@ -359,10 +369,18 @@ test('should capture decode errors', async () => { ); assert.ok(decodeSpan, 'Encode span not found'); assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); + const errorEvents = decodeSpan.events.filter((event) => { return event['name'] === 'exception'; }); assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); + + assert.ok( + errorEvents.find( + (event) => event.attributes?.['exception.message'] === '"Custom Decode Error"', + ), + 'Expected custom decode reporter message', + ); }); }); From 46c776597cb586424bf2d60e0e41db5ac8a69f2f Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Wed, 16 Jul 2025 13:27:29 -0400 Subject: [PATCH 06/11] chore: simplify function definition --- packages/typed-express-router/src/errors.ts | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/packages/typed-express-router/src/errors.ts b/packages/typed-express-router/src/errors.ts index 4101aa8b..0fe32b6c 100644 --- a/packages/typed-express-router/src/errors.ts +++ b/packages/typed-express-router/src/errors.ts @@ -1,27 +1,17 @@ -import express from 'express'; -import { Errors } from 'io-ts'; import * as PathReporter from 'io-ts/lib/PathReporter'; -import { OnDecodeErrorFn } from './types'; +import type { OnDecodeErrorFn, OnEncodeErrorFn } from './types'; -export function defaultOnDecodeError( - errs: Errors, - _req: express.Request, - res: express.Response, -): ReturnType { +export const defaultOnDecodeError: OnDecodeErrorFn = (errs, _req, res) => { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); const responseFn = () => { res.status(400).json({ error: validationErrorMessage }).end(); }; return { response: validationErrorMessage, statusCode: 400, responseFn }; -} +}; -export function defaultOnEncodeError( - err: unknown, - _req: express.Request, - res: express.Response, -) { +export const defaultOnEncodeError: OnEncodeErrorFn = (err, _req, res) => { res.status(500).end(); console.warn(`Error in route handler: ${err}`); -} +}; From 920d088ff93a5832eaf15c6fe5cf73f9bbd315b1 Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Wed, 16 Jul 2025 14:38:10 -0400 Subject: [PATCH 07/11] Revert "chore: cleanup, pass responseFn in decode error function" This reverts commit ab8a1234c9b2a8c442bba8f1ef39e2e716e262b0. --- packages/express-wrapper/src/request.ts | 12 ++------ packages/typed-express-router/src/errors.ts | 7 ++--- packages/typed-express-router/src/index.ts | 18 ++++------- packages/typed-express-router/src/types.ts | 7 +++-- .../typed-express-router/test/server.test.ts | 30 ++++--------------- .../test/telemetry.test.ts | 20 +------------ 6 files changed, 22 insertions(+), 72 deletions(-) diff --git a/packages/express-wrapper/src/request.ts b/packages/express-wrapper/src/request.ts index cdbf31f0..dfeae64b 100644 --- a/packages/express-wrapper/src/request.ts +++ b/packages/express-wrapper/src/request.ts @@ -97,15 +97,9 @@ const createNamedFunction = void>( export const onDecodeError: OnDecodeErrorFn = (errs, _req, res) => { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); - return { - response: validationErrorMessage, - statusCode: 400, - responseFn: () => { - res.writeHead(400, { 'Content-Type': 'application/json' }); - res.write(JSON.stringify({ error: validationErrorMessage })); - res.end(); - }, - }; + res.writeHead(400, { 'Content-Type': 'application/json' }); + res.write(JSON.stringify({ error: validationErrorMessage })); + res.end(); }; export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => { diff --git a/packages/typed-express-router/src/errors.ts b/packages/typed-express-router/src/errors.ts index 0fe32b6c..113f1b21 100644 --- a/packages/typed-express-router/src/errors.ts +++ b/packages/typed-express-router/src/errors.ts @@ -2,13 +2,10 @@ import * as PathReporter from 'io-ts/lib/PathReporter'; import type { OnDecodeErrorFn, OnEncodeErrorFn } from './types'; -export const defaultOnDecodeError: OnDecodeErrorFn = (errs, _req, res) => { +export const defaultOnDecodeError: OnDecodeErrorFn = (errs, _req, _res) => { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); - const responseFn = () => { - res.status(400).json({ error: validationErrorMessage }).end(); - }; - return { response: validationErrorMessage, statusCode: 400, responseFn }; + return { response: validationErrorMessage, statusCode: 400 }; }; export const defaultOnEncodeError: OnEncodeErrorFn = (err, _req, res) => { diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index 490964c8..a827e4f0 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -163,12 +163,8 @@ export function wrapRouter( pipe( req.decoded, E.getOrElseW((errs) => { - const { response, statusCode } = (options?.onDecodeError ?? onDecodeError)( - errs, - req, - res, - ); - recordSpanDecodeError(decodeSpan, response, statusCode); + const error = (onDecodeError ?? onDecodeError)(errs, req, res); + recordSpanDecodeError(decodeSpan, error.response, error.statusCode); }), ); endSpan(decodeSpan); @@ -204,12 +200,10 @@ export function wrapRouter( req.decoded, E.matchW( (errs) => { - const { responseFn } = (options?.onDecodeError ?? onDecodeError)( - errs, - req, - res, - ); - responseFn(); + const { response, statusCode } = ( + options?.onDecodeError ?? onDecodeError + )(errs, req, res); + res.status(statusCode).json(response).end(); }, (value) => { req.decoded = value; diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index dbbcc596..86062a51 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -28,7 +28,7 @@ export type OnDecodeErrorFn = ( errs: t.Errors, req: express.Request, res: express.Response, -) => { response: Json; statusCode: number; responseFn: () => void }; +) => { response: Json; statusCode: number }; export type OnEncodeErrorFn = ( err: unknown, @@ -45,12 +45,13 @@ export type AfterEncodedResponseSentFn = ( export type UncheckedWrappedRouteOptions = { onEncodeError?: OnEncodeErrorFn; - onDecodeError?: OnDecodeErrorFn; afterEncodedResponseSent?: AfterEncodedResponseSentFn; routeAliases?: string[]; }; -export type WrappedRouteOptions = UncheckedWrappedRouteOptions; +export type WrappedRouteOptions = UncheckedWrappedRouteOptions & { + onDecodeError?: OnDecodeErrorFn; +}; export type WrappedRouterOptions = express.RouterOptions & WrappedRouteOptions; diff --git a/packages/typed-express-router/test/server.test.ts b/packages/typed-express-router/test/server.test.ts index 42fbed27..309c7d92 100644 --- a/packages/typed-express-router/test/server.test.ts +++ b/packages/typed-express-router/test/server.test.ts @@ -361,14 +361,8 @@ test('should return a 400 when request fails to decode', async () => { test('should invoke custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, res) => { - return { - response: 'Custom decode error', - statusCode: 400, - responseFn: () => { - res.status(400).json('Custom decode error').end(); - }, - }; + onDecodeError: (_errs, _req, _res) => { + return { response: 'Custom decode error', statusCode: 400 }; }, }); @@ -396,14 +390,8 @@ test('should invoke custom decode error function', async () => { test('should invoke per-route custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, res) => { - return { - response: 'Top-level decode error', - statusCode: 400, - responseFn: () => { - res.status(400).json('Top-level decode error').end(); - }, - }; + onDecodeError: (_errs, _req, _res) => { + return { response: 'Top-level decode error', statusCode: 400 }; }, }); @@ -415,14 +403,8 @@ test('should invoke per-route custom decode error function', async () => { }, ], { - onDecodeError: (_errs, _req, res) => { - return { - response: 'Route decode error', - statusCode: 400, - responseFn: () => { - res.status(400).json('Route decode error').end(); - }, - }; + onDecodeError: (_errs, _req, _res) => { + return { response: 'Route decode error', statusCode: 400 }; }, routeAliases: ['/helloNoPathParams'], }, diff --git a/packages/typed-express-router/test/telemetry.test.ts b/packages/typed-express-router/test/telemetry.test.ts index 16b968f6..451f3909 100644 --- a/packages/typed-express-router/test/telemetry.test.ts +++ b/packages/typed-express-router/test/telemetry.test.ts @@ -175,17 +175,7 @@ beforeEach(async () => { const router = createRouter(TestApiSpec); router.get('hello.world', [GetHelloWorld]); - router.put('hello.world', [CreateHelloWorld], { - onDecodeError: (_errs, _req, res) => { - return { - response: 'Custom Decode Error', - statusCode: 400, - responseFn: () => { - res.status(400).json({ error: 'Custom Decode Error' }); - }, - }; - }, - }); + router.put('hello.world', [CreateHelloWorld]); router.get('hello.world.bad', [GetHelloWorldBad]); app.use(router); @@ -369,18 +359,10 @@ test('should capture decode errors', async () => { ); assert.ok(decodeSpan, 'Encode span not found'); assert.strictEqual(decodeSpan?.attributes?.[ApiTsAttributes.API_TS_PATH], '/hello'); - const errorEvents = decodeSpan.events.filter((event) => { return event['name'] === 'exception'; }); assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); - - assert.ok( - errorEvents.find( - (event) => event.attributes?.['exception.message'] === '"Custom Decode Error"', - ), - 'Expected custom decode reporter message', - ); }); }); From 44aa35bbcee7e997aa7f7d8b9ccf9042dfaaf0cf Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Wed, 16 Jul 2025 14:40:37 -0400 Subject: [PATCH 08/11] chore: some cleanup --- packages/typed-express-router/src/index.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index a827e4f0..c942a64e 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -30,6 +30,7 @@ import { } from './types'; import type { Span } from '@opentelemetry/api'; +import * as PathReporter from 'io-ts/lib/PathReporter'; export type { AfterEncodedResponseSentFn, @@ -163,8 +164,12 @@ export function wrapRouter( pipe( req.decoded, E.getOrElseW((errs) => { - const error = (onDecodeError ?? onDecodeError)(errs, req, res); - recordSpanDecodeError(decodeSpan, error.response, error.statusCode); + const { response, statusCode } = (onDecodeError ?? onDecodeError)( + errs, + req, + res, + ); + recordSpanDecodeError(decodeSpan, response, statusCode); }), ); endSpan(decodeSpan); From 62f952bb552d5f997ed2c5c6181fb5ccc3f577e6 Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Wed, 16 Jul 2025 15:16:37 -0400 Subject: [PATCH 09/11] fix: fix express-wrapper package --- packages/express-wrapper/src/request.ts | 6 ++---- packages/typed-express-router/src/index.ts | 5 ++++- packages/typed-express-router/src/types.ts | 4 +++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/express-wrapper/src/request.ts b/packages/express-wrapper/src/request.ts index dfeae64b..316369da 100644 --- a/packages/express-wrapper/src/request.ts +++ b/packages/express-wrapper/src/request.ts @@ -94,12 +94,10 @@ const createNamedFunction = void>( fn: F, ): F => Object.defineProperty(fn, 'name', { value: name }); -export const onDecodeError: OnDecodeErrorFn = (errs, _req, res) => { +export const onDecodeError: OnDecodeErrorFn = (errs, _req, _res) => { const validationErrors = PathReporter.failure(errs); const validationErrorMessage = validationErrors.join('\n'); - res.writeHead(400, { 'Content-Type': 'application/json' }); - res.write(JSON.stringify({ error: validationErrorMessage })); - res.end(); + return { response: { error: validationErrorMessage }, statusCode: 400 }; }; export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => { diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index c942a64e..44c2552f 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -58,6 +58,7 @@ export function createRouter( onDecodeError, onEncodeError, afterEncodedResponseSent, + pathReporter, ...options }: WrappedRouterOptions = {}, ): WrappedRouter { @@ -66,6 +67,7 @@ export function createRouter( onDecodeError, onEncodeError, afterEncodedResponseSent, + pathReporter, }); } @@ -84,6 +86,7 @@ export function wrapRouter( onDecodeError = defaultOnDecodeError, onEncodeError = defaultOnEncodeError, afterEncodedResponseSent = () => {}, + pathReporter = PathReporter.failure, }: WrappedRouteOptions, ): WrappedRouter { const routerMiddleware: UncheckedRequestHandler[] = []; @@ -164,7 +167,7 @@ export function wrapRouter( pipe( req.decoded, E.getOrElseW((errs) => { - const { response, statusCode } = (onDecodeError ?? onDecodeError)( + const { response, statusCode } = (options?.onDecodeError ?? onDecodeError)( errs, req, res, diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index 86062a51..5e993b0b 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -1,6 +1,7 @@ import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http'; import express from 'express'; import * as t from 'io-ts'; +import { failure as prFailure } from 'io-ts/lib/PathReporter'; export type Json = boolean | number | string | null | JsonArray | JsonRecord; export interface JsonRecord { @@ -45,12 +46,13 @@ export type AfterEncodedResponseSentFn = ( export type UncheckedWrappedRouteOptions = { onEncodeError?: OnEncodeErrorFn; + onDecodeError?: OnDecodeErrorFn; afterEncodedResponseSent?: AfterEncodedResponseSentFn; routeAliases?: string[]; }; export type WrappedRouteOptions = UncheckedWrappedRouteOptions & { - onDecodeError?: OnDecodeErrorFn; + pathReporter?: typeof prFailure; }; export type WrappedRouterOptions = express.RouterOptions & WrappedRouteOptions; From 57b8b6435bc9584594f8f7a66fb93b76d1e7014e Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Thu, 17 Jul 2025 11:16:29 -0400 Subject: [PATCH 10/11] wip: first iteration of pathReporter --- packages/express-wrapper/src/index.ts | 11 +++++-- packages/express-wrapper/src/request.ts | 19 ++++++----- packages/typed-express-router/src/errors.ts | 10 +----- packages/typed-express-router/src/index.ts | 33 ++++++++++--------- packages/typed-express-router/src/types.ts | 18 +++++++--- .../typed-express-router/test/server.test.ts | 12 +++---- .../test/telemetry.test.ts | 22 ++++++++++++- 7 files changed, 79 insertions(+), 46 deletions(-) diff --git a/packages/express-wrapper/src/index.ts b/packages/express-wrapper/src/index.ts index 38dfd278..7cc22e46 100644 --- a/packages/express-wrapper/src/index.ts +++ b/packages/express-wrapper/src/index.ts @@ -8,7 +8,13 @@ import express from 'express'; import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http'; import { createRouter } from '@api-ts/typed-express-router'; -import { handleRequest, onDecodeError, onEncodeError, RouteHandler } from './request'; +import { + handleRequest, + pathReporter, + getDecodeErrorStatusCode, + onEncodeError, + RouteHandler, +} from './request'; import { defaultResponseEncoder, ResponseEncoder } from './response'; export { middlewareFn, MiddlewareChain, MiddlewareChainOutput } from './middleware'; @@ -33,7 +39,8 @@ export function routerForApiSpec({ encoder = defaultResponseEncoder, }: CreateRouterProps) { const router = createRouter(spec, { - onDecodeError, + pathReporter, + getDecodeErrorStatusCode, onEncodeError, }); for (const apiName of Object.keys(spec)) { diff --git a/packages/express-wrapper/src/request.ts b/packages/express-wrapper/src/request.ts index 316369da..8006269d 100644 --- a/packages/express-wrapper/src/request.ts +++ b/packages/express-wrapper/src/request.ts @@ -7,11 +7,7 @@ import express from 'express'; import * as PathReporter from 'io-ts/lib/PathReporter'; import { ApiSpec, HttpRoute, RequestType, ResponseType } from '@api-ts/io-ts-http'; -import { - OnDecodeErrorFn, - OnEncodeErrorFn, - TypedRequestHandler, -} from '@api-ts/typed-express-router'; +import { OnEncodeErrorFn, TypedRequestHandler } from '@api-ts/typed-express-router'; import { runMiddlewareChain, @@ -21,6 +17,10 @@ import { MiddlewareChainOutput, } from './middleware'; import type { KeyedResponseType, ResponseEncoder } from './response'; +import { + GetDecodeErrorStatusCodeFn, + PathReporterFailureFn, +} from '@api-ts/typed-express-router/src/types'; export type ServiceFunction> = | ((input: Input) => ResponseType | Promise>) @@ -94,10 +94,13 @@ const createNamedFunction = void>( fn: F, ): F => Object.defineProperty(fn, 'name', { value: name }); -export const onDecodeError: OnDecodeErrorFn = (errs, _req, _res) => { +export const pathReporter: PathReporterFailureFn = (errs, _req) => { const validationErrors = PathReporter.failure(errs); - const validationErrorMessage = validationErrors.join('\n'); - return { response: { error: validationErrorMessage }, statusCode: 400 }; + return { error: validationErrors.join('\n') }; +}; + +export const getDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = (_errs, _req) => { + return 400; }; export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => { diff --git a/packages/typed-express-router/src/errors.ts b/packages/typed-express-router/src/errors.ts index 113f1b21..4fd49e9c 100644 --- a/packages/typed-express-router/src/errors.ts +++ b/packages/typed-express-router/src/errors.ts @@ -1,12 +1,4 @@ -import * as PathReporter from 'io-ts/lib/PathReporter'; - -import type { OnDecodeErrorFn, OnEncodeErrorFn } from './types'; - -export const defaultOnDecodeError: OnDecodeErrorFn = (errs, _req, _res) => { - const validationErrors = PathReporter.failure(errs); - const validationErrorMessage = validationErrors.join('\n'); - return { response: validationErrorMessage, statusCode: 400 }; -}; +import type { OnEncodeErrorFn } from './types'; export const defaultOnEncodeError: OnEncodeErrorFn = (err, _req, res) => { res.status(500).end(); diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index 44c2552f..a6b75f44 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -6,7 +6,7 @@ import { ApiSpec, HttpRoute, KeyToHttpStatus } from '@api-ts/io-ts-http'; import express from 'express'; import * as E from 'fp-ts/Either'; import { pipe } from 'fp-ts/pipeable'; -import { defaultOnDecodeError, defaultOnEncodeError } from './errors'; +import { defaultOnEncodeError } from './errors'; import { apiTsPathToExpress } from './path'; import { ApiTsAttributes, @@ -55,19 +55,19 @@ export type { export function createRouter( spec: Spec, { - onDecodeError, onEncodeError, afterEncodedResponseSent, pathReporter, + getDecodeErrorStatusCode, ...options }: WrappedRouterOptions = {}, ): WrappedRouter { const router = express.Router(options); return wrapRouter(router, spec, { - onDecodeError, onEncodeError, afterEncodedResponseSent, pathReporter, + getDecodeErrorStatusCode, }); } @@ -83,10 +83,10 @@ export function wrapRouter( router: express.Router, spec: Spec, { - onDecodeError = defaultOnDecodeError, onEncodeError = defaultOnEncodeError, afterEncodedResponseSent = () => {}, pathReporter = PathReporter.failure, + getDecodeErrorStatusCode = () => 400, }: WrappedRouteOptions, ): WrappedRouter { const routerMiddleware: UncheckedRequestHandler[] = []; @@ -163,16 +163,15 @@ export function wrapRouter( next(); }; - const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, res, next) => { + const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, _res, next) => { pipe( req.decoded, E.getOrElseW((errs) => { - const { response, statusCode } = (options?.onDecodeError ?? onDecodeError)( - errs, - req, - res, - ); - recordSpanDecodeError(decodeSpan, response, statusCode); + const validationErrors = (options?.pathReporter ?? pathReporter)(errs, req); + const statusCode = ( + options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode + )(errs, req); + recordSpanDecodeError(decodeSpan, validationErrors, statusCode); }), ); endSpan(decodeSpan); @@ -208,10 +207,14 @@ export function wrapRouter( req.decoded, E.matchW( (errs) => { - const { response, statusCode } = ( - options?.onDecodeError ?? onDecodeError - )(errs, req, res); - res.status(statusCode).json(response).end(); + const statusCode = ( + options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode + )(errs, req); + const validationErrors = (options?.pathReporter ?? pathReporter)( + errs, + req, + ); + res.status(statusCode).json(validationErrors).end(); }, (value) => { req.decoded = value; diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index 5e993b0b..c50b215e 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -1,7 +1,6 @@ import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http'; import express from 'express'; import * as t from 'io-ts'; -import { failure as prFailure } from 'io-ts/lib/PathReporter'; export type Json = boolean | number | string | null | JsonArray | JsonRecord; export interface JsonRecord { @@ -44,16 +43,25 @@ export type AfterEncodedResponseSentFn = ( res: WrappedResponse, ) => void; +export type PathReporterFailureFn = ( + es: Array, + req: WrappedRequest, +) => Json; + +export type GetDecodeErrorStatusCodeFn = ( + es: Array, + req: WrappedRequest, +) => number; + export type UncheckedWrappedRouteOptions = { onEncodeError?: OnEncodeErrorFn; - onDecodeError?: OnDecodeErrorFn; + pathReporter?: PathReporterFailureFn; + getDecodeErrorStatusCode?: GetDecodeErrorStatusCodeFn; afterEncodedResponseSent?: AfterEncodedResponseSentFn; routeAliases?: string[]; }; -export type WrappedRouteOptions = UncheckedWrappedRouteOptions & { - pathReporter?: typeof prFailure; -}; +export type WrappedRouteOptions = UncheckedWrappedRouteOptions; export type WrappedRouterOptions = express.RouterOptions & WrappedRouteOptions; diff --git a/packages/typed-express-router/test/server.test.ts b/packages/typed-express-router/test/server.test.ts index 309c7d92..fa88b970 100644 --- a/packages/typed-express-router/test/server.test.ts +++ b/packages/typed-express-router/test/server.test.ts @@ -361,8 +361,8 @@ test('should return a 400 when request fails to decode', async () => { test('should invoke custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, _res) => { - return { response: 'Custom decode error', statusCode: 400 }; + pathReporter: (_errs, _req) => { + return 'Custom decode error'; }, }); @@ -390,8 +390,8 @@ test('should invoke custom decode error function', async () => { test('should invoke per-route custom decode error function', async () => { const router = createRouter(TestApiSpec, { - onDecodeError: (_errs, _req, _res) => { - return { response: 'Top-level decode error', statusCode: 400 }; + pathReporter: (_errs, _req) => { + return 'Top-level decode error'; }, }); @@ -403,8 +403,8 @@ test('should invoke per-route custom decode error function', async () => { }, ], { - onDecodeError: (_errs, _req, _res) => { - return { response: 'Route decode error', statusCode: 400 }; + pathReporter: (_errs, _req) => { + return 'Route decode error'; }, routeAliases: ['/helloNoPathParams'], }, diff --git a/packages/typed-express-router/test/telemetry.test.ts b/packages/typed-express-router/test/telemetry.test.ts index 451f3909..e8c8e3a9 100644 --- a/packages/typed-express-router/test/telemetry.test.ts +++ b/packages/typed-express-router/test/telemetry.test.ts @@ -175,7 +175,11 @@ beforeEach(async () => { const router = createRouter(TestApiSpec); router.get('hello.world', [GetHelloWorld]); - router.put('hello.world', [CreateHelloWorld]); + router.put('hello.world', [CreateHelloWorld], { + pathReporter: (_errs, _req) => { + return 'Custom Decode Error'; + }, + }); router.get('hello.world.bad', [GetHelloWorldBad]); app.use(router); @@ -363,6 +367,13 @@ test('should capture decode errors', async () => { return event['name'] === 'exception'; }); assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); + + assert.ok( + errorEvents.find( + (event) => event.attributes?.['exception.message'] === '"Custom Decode Error"', + ), + 'Expected custom decode reporter message', + ); }); }); @@ -394,6 +405,15 @@ test('should capture encode errors', async () => { return attributes['exception.type'] === 'Error'; }); assert.ok(errorEvents.length > 0, 'Expected at least 1 error event'); + + assert.ok( + errorEvents.find((event) => + event.attributes?.['exception.message'] + ?.toString() + .startsWith('response does not match expected type'), + ), + 'Expected encode error message', + ); }); }); From 183d5f43ab3d72edfb07489883f9cbce300b9d2b Mon Sep 17 00:00:00 2001 From: Dereck Tu Date: Thu, 17 Jul 2025 14:24:55 -0400 Subject: [PATCH 11/11] wip: second pass, align encode functionality with decode, fix up naming --- packages/express-wrapper/src/index.ts | 28 +++++++-- packages/express-wrapper/src/request.ts | 30 +++++++--- packages/typed-express-router/src/errors.ts | 25 ++++++-- packages/typed-express-router/src/index.ts | 59 +++++++++++-------- packages/typed-express-router/src/types.ts | 25 +++----- .../typed-express-router/test/server.test.ts | 26 ++++---- .../test/telemetry.test.ts | 2 +- 7 files changed, 122 insertions(+), 73 deletions(-) diff --git a/packages/express-wrapper/src/index.ts b/packages/express-wrapper/src/index.ts index 7cc22e46..0f9119b7 100644 --- a/packages/express-wrapper/src/index.ts +++ b/packages/express-wrapper/src/index.ts @@ -6,13 +6,20 @@ import express from 'express'; import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http'; -import { createRouter } from '@api-ts/typed-express-router'; +import { + createRouter, + DecodeErrorFormatterFn, + EncodeErrorFormatterFn, + GetDecodeErrorStatusCodeFn, + GetEncodeErrorStatusCodeFn, +} from '@api-ts/typed-express-router'; import { handleRequest, - pathReporter, - getDecodeErrorStatusCode, - onEncodeError, + defaultDecodeErrorFormatter, + defaultEncodeErrorFormatter, + defaultGetDecodeErrorStatusCode, + defaultGetEncodeErrorStatusCode, RouteHandler, } from './request'; import { defaultResponseEncoder, ResponseEncoder } from './response'; @@ -31,17 +38,26 @@ type CreateRouterProps = { }; }; encoder?: ResponseEncoder; + decodeErrorFormatter?: DecodeErrorFormatterFn; + encodeErrorFormatter?: EncodeErrorFormatterFn; + getDecodeErrorStatusCode?: GetDecodeErrorStatusCodeFn; + getEncodeErrorStatusCode?: GetEncodeErrorStatusCodeFn; }; export function routerForApiSpec({ spec, routeHandlers, encoder = defaultResponseEncoder, + decodeErrorFormatter = defaultDecodeErrorFormatter, + encodeErrorFormatter = defaultEncodeErrorFormatter, + getDecodeErrorStatusCode = defaultGetDecodeErrorStatusCode, + getEncodeErrorStatusCode = defaultGetEncodeErrorStatusCode, }: CreateRouterProps) { const router = createRouter(spec, { - pathReporter, + decodeErrorFormatter, + encodeErrorFormatter, getDecodeErrorStatusCode, - onEncodeError, + getEncodeErrorStatusCode, }); for (const apiName of Object.keys(spec)) { const resource = spec[apiName] as Spec[string]; diff --git a/packages/express-wrapper/src/request.ts b/packages/express-wrapper/src/request.ts index 8006269d..c9d61ff8 100644 --- a/packages/express-wrapper/src/request.ts +++ b/packages/express-wrapper/src/request.ts @@ -7,7 +7,13 @@ import express from 'express'; import * as PathReporter from 'io-ts/lib/PathReporter'; import { ApiSpec, HttpRoute, RequestType, ResponseType } from '@api-ts/io-ts-http'; -import { OnEncodeErrorFn, TypedRequestHandler } from '@api-ts/typed-express-router'; +import { + type DecodeErrorFormatterFn, + type EncodeErrorFormatterFn, + type GetDecodeErrorStatusCodeFn, + type GetEncodeErrorStatusCodeFn, + TypedRequestHandler, +} from '@api-ts/typed-express-router'; import { runMiddlewareChain, @@ -17,10 +23,6 @@ import { MiddlewareChainOutput, } from './middleware'; import type { KeyedResponseType, ResponseEncoder } from './response'; -import { - GetDecodeErrorStatusCodeFn, - PathReporterFailureFn, -} from '@api-ts/typed-express-router/src/types'; export type ServiceFunction> = | ((input: Input) => ResponseType | Promise>) @@ -94,18 +96,28 @@ const createNamedFunction = void>( fn: F, ): F => Object.defineProperty(fn, 'name', { value: name }); -export const pathReporter: PathReporterFailureFn = (errs, _req) => { +export const defaultDecodeErrorFormatter: DecodeErrorFormatterFn = (errs, _req) => { const validationErrors = PathReporter.failure(errs); return { error: validationErrors.join('\n') }; }; -export const getDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = (_errs, _req) => { +export const defaultEncodeErrorFormatter: EncodeErrorFormatterFn = (_err, _req) => { + return {}; +}; + +export const defaultGetDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = ( + _errs, + _req, +) => { return 400; }; -export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => { +export const defaultGetEncodeErrorStatusCode: GetEncodeErrorStatusCodeFn = ( + err, + _req, +) => { console.warn('Error in route handler:', err); - res.status(500).end(); + return 500; }; export const handleRequest = ( diff --git a/packages/typed-express-router/src/errors.ts b/packages/typed-express-router/src/errors.ts index 4fd49e9c..f106adc9 100644 --- a/packages/typed-express-router/src/errors.ts +++ b/packages/typed-express-router/src/errors.ts @@ -1,6 +1,21 @@ -import type { OnEncodeErrorFn } from './types'; +import * as PathReporter from 'io-ts/lib/PathReporter'; +import type { + DecodeErrorFormatterFn, + EncodeErrorFormatterFn, + GetDecodeErrorStatusCodeFn, + GetEncodeErrorStatusCodeFn, +} from './types'; -export const defaultOnEncodeError: OnEncodeErrorFn = (err, _req, res) => { - res.status(500).end(); - console.warn(`Error in route handler: ${err}`); -}; +export const defaultDecodeErrorFormatter: DecodeErrorFormatterFn = PathReporter.failure; + +export const defaultGetDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = ( + _err, + _req, +) => 400; + +export const defaultEncodeErrorFormatter: EncodeErrorFormatterFn = () => ({}); + +export const defaultGetEncodeErrorStatusCode: GetEncodeErrorStatusCodeFn = ( + _err, + _req, +) => 500; diff --git a/packages/typed-express-router/src/index.ts b/packages/typed-express-router/src/index.ts index a6b75f44..703d4685 100644 --- a/packages/typed-express-router/src/index.ts +++ b/packages/typed-express-router/src/index.ts @@ -6,7 +6,12 @@ import { ApiSpec, HttpRoute, KeyToHttpStatus } from '@api-ts/io-ts-http'; import express from 'express'; import * as E from 'fp-ts/Either'; import { pipe } from 'fp-ts/pipeable'; -import { defaultOnEncodeError } from './errors'; +import { + defaultDecodeErrorFormatter, + defaultEncodeErrorFormatter, + defaultGetDecodeErrorStatusCode, + defaultGetEncodeErrorStatusCode, +} from './errors'; import { apiTsPathToExpress } from './path'; import { ApiTsAttributes, @@ -30,12 +35,13 @@ import { } from './types'; import type { Span } from '@opentelemetry/api'; -import * as PathReporter from 'io-ts/lib/PathReporter'; export type { AfterEncodedResponseSentFn, - OnDecodeErrorFn, - OnEncodeErrorFn, + DecodeErrorFormatterFn, + EncodeErrorFormatterFn, + GetDecodeErrorStatusCodeFn, + GetEncodeErrorStatusCodeFn, TypedRequestHandler, UncheckedRequestHandler, WrappedRouter, @@ -55,18 +61,20 @@ export type { export function createRouter( spec: Spec, { - onEncodeError, + encodeErrorFormatter, + getEncodeErrorStatusCode, afterEncodedResponseSent, - pathReporter, + decodeErrorFormatter, getDecodeErrorStatusCode, ...options }: WrappedRouterOptions = {}, ): WrappedRouter { const router = express.Router(options); return wrapRouter(router, spec, { - onEncodeError, + encodeErrorFormatter, + getEncodeErrorStatusCode, afterEncodedResponseSent, - pathReporter, + decodeErrorFormatter, getDecodeErrorStatusCode, }); } @@ -83,10 +91,11 @@ export function wrapRouter( router: express.Router, spec: Spec, { - onEncodeError = defaultOnEncodeError, + encodeErrorFormatter = defaultEncodeErrorFormatter, + getEncodeErrorStatusCode = defaultGetEncodeErrorStatusCode, afterEncodedResponseSent = () => {}, - pathReporter = PathReporter.failure, - getDecodeErrorStatusCode = () => 400, + decodeErrorFormatter = defaultDecodeErrorFormatter, + getDecodeErrorStatusCode = defaultGetDecodeErrorStatusCode, }: WrappedRouteOptions, ): WrappedRouter { const routerMiddleware: UncheckedRequestHandler[] = []; @@ -151,11 +160,14 @@ export function wrapRouter( ); } catch (err) { recordSpanEncodeError(encodeSpan, err); - (options?.onEncodeError ?? onEncodeError)( - err, - req as WrappedRequest, - res as WrappedResponse, - ); + + const statusCode = ( + options?.getEncodeErrorStatusCode ?? getEncodeErrorStatusCode + )(err, req); + const encodeErrorMessage = ( + options?.encodeErrorFormatter ?? encodeErrorFormatter + )(err, req); + res.status(statusCode).json(encodeErrorMessage); } finally { endSpan(encodeSpan); } @@ -167,11 +179,13 @@ export function wrapRouter( pipe( req.decoded, E.getOrElseW((errs) => { - const validationErrors = (options?.pathReporter ?? pathReporter)(errs, req); + const decodeErrorMessage = ( + options?.decodeErrorFormatter ?? decodeErrorFormatter + )(errs, req); const statusCode = ( options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode )(errs, req); - recordSpanDecodeError(decodeSpan, validationErrors, statusCode); + recordSpanDecodeError(decodeSpan, decodeErrorMessage, statusCode); }), ); endSpan(decodeSpan); @@ -210,11 +224,10 @@ export function wrapRouter( const statusCode = ( options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode )(errs, req); - const validationErrors = (options?.pathReporter ?? pathReporter)( - errs, - req, - ); - res.status(statusCode).json(validationErrors).end(); + const decodeErrorMessage = ( + options?.decodeErrorFormatter ?? decodeErrorFormatter + )(errs, req); + res.status(statusCode).json(decodeErrorMessage); }, (value) => { req.decoded = value; diff --git a/packages/typed-express-router/src/types.ts b/packages/typed-express-router/src/types.ts index c50b215e..147a60a7 100644 --- a/packages/typed-express-router/src/types.ts +++ b/packages/typed-express-router/src/types.ts @@ -24,17 +24,9 @@ export type WrappedResponse void; }; -export type OnDecodeErrorFn = ( - errs: t.Errors, - req: express.Request, - res: express.Response, -) => { response: Json; statusCode: number }; - -export type OnEncodeErrorFn = ( - err: unknown, - req: WrappedRequest, - res: WrappedResponse, -) => void; +export type EncodeErrorFormatterFn = (err: unknown, req: WrappedRequest) => Json; + +export type GetEncodeErrorStatusCodeFn = (err: unknown, req: WrappedRequest) => number; export type AfterEncodedResponseSentFn = ( status: number, @@ -43,20 +35,21 @@ export type AfterEncodedResponseSentFn = ( res: WrappedResponse, ) => void; -export type PathReporterFailureFn = ( - es: Array, +export type DecodeErrorFormatterFn = ( + errs: Array, req: WrappedRequest, ) => Json; export type GetDecodeErrorStatusCodeFn = ( - es: Array, + errs: Array, req: WrappedRequest, ) => number; export type UncheckedWrappedRouteOptions = { - onEncodeError?: OnEncodeErrorFn; - pathReporter?: PathReporterFailureFn; + decodeErrorFormatter?: DecodeErrorFormatterFn; + encodeErrorFormatter?: EncodeErrorFormatterFn; getDecodeErrorStatusCode?: GetDecodeErrorStatusCodeFn; + getEncodeErrorStatusCode?: GetEncodeErrorStatusCodeFn; afterEncodedResponseSent?: AfterEncodedResponseSentFn; routeAliases?: string[]; }; diff --git a/packages/typed-express-router/test/server.test.ts b/packages/typed-express-router/test/server.test.ts index fa88b970..6a3376f1 100644 --- a/packages/typed-express-router/test/server.test.ts +++ b/packages/typed-express-router/test/server.test.ts @@ -361,7 +361,7 @@ test('should return a 400 when request fails to decode', async () => { test('should invoke custom decode error function', async () => { const router = createRouter(TestApiSpec, { - pathReporter: (_errs, _req) => { + decodeErrorFormatter: (_errs, _req) => { return 'Custom decode error'; }, }); @@ -390,7 +390,7 @@ test('should invoke custom decode error function', async () => { test('should invoke per-route custom decode error function', async () => { const router = createRouter(TestApiSpec, { - pathReporter: (_errs, _req) => { + decodeErrorFormatter: (_errs, _req) => { return 'Top-level decode error'; }, }); @@ -403,7 +403,7 @@ test('should invoke per-route custom decode error function', async () => { }, ], { - pathReporter: (_errs, _req) => { + decodeErrorFormatter: (_errs, _req) => { return 'Route decode error'; }, routeAliases: ['/helloNoPathParams'], @@ -442,8 +442,8 @@ test('should send a 500 when response type does not match', async () => { test('should invoke custom encode error function when response type does not match', async () => { const router = createRouter(TestApiSpec, { - onEncodeError: (_err, _req, res) => { - res.status(500).json('Custom encode error').end(); + encodeErrorFormatter: (_err, _req) => { + return 'Custom encode error'; }, }); @@ -467,8 +467,8 @@ test('should invoke custom encode error function when response type does not mat test('should invoke per-route custom encode error function when response type does not match', async () => { const router = createRouter(TestApiSpec, { - onEncodeError: (_err, _req, res) => { - res.status(500).json('Top-level encode error').end(); + encodeErrorFormatter: (_err, _req) => { + return 'Top-level encode error'; }, }); @@ -480,8 +480,8 @@ test('should invoke per-route custom encode error function when response type do }, ], { - onEncodeError: (_err, _req, res) => { - res.status(500).json('Route encode error').end(); + encodeErrorFormatter: (_err, _req) => { + return 'Route encode error'; }, }, ); @@ -500,8 +500,8 @@ test('should invoke per-route custom encode error function when response type do test('should invoke custom encode error function when an unknown HTTP status is passed to `sendEncoded`', async () => { const router = createRouter(TestApiSpec, { - onEncodeError: (_err, _req, res) => { - res.status(500).json('Custom encode error').end(); + encodeErrorFormatter: (_err, _req) => { + return 'Custom encode error'; }, }); @@ -538,8 +538,8 @@ test('should invoke custom encode error function when an unknown keyed status is }); const router = createRouter(WeirdApi, { - onEncodeError: (_err, _req, res) => { - res.status(500).json('Custom encode error').end(); + encodeErrorFormatter: (_err, _req) => { + return 'Custom encode error'; }, }); diff --git a/packages/typed-express-router/test/telemetry.test.ts b/packages/typed-express-router/test/telemetry.test.ts index e8c8e3a9..29dac818 100644 --- a/packages/typed-express-router/test/telemetry.test.ts +++ b/packages/typed-express-router/test/telemetry.test.ts @@ -176,7 +176,7 @@ beforeEach(async () => { router.get('hello.world', [GetHelloWorld]); router.put('hello.world', [CreateHelloWorld], { - pathReporter: (_errs, _req) => { + decodeErrorFormatter: (_errs, _req) => { return 'Custom Decode Error'; }, });