{"id":15451130,"url":"https://github.com/gr2m/node-http-recorder","last_synced_at":"2025-04-19T23:34:02.713Z","repository":{"id":37030713,"uuid":"440349792","full_name":"gr2m/node-http-recorder","owner":"gr2m","description":"Library agnostic in-process recording of http(s) requests and responses","archived":false,"fork":false,"pushed_at":"2025-04-09T22:30:38.000Z","size":269,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T23:28:21.880Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gr2m.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"gr2m"}},"created_at":"2021-12-21T01:01:28.000Z","updated_at":"2025-04-09T22:30:18.000Z","dependencies_parsed_at":"2023-12-22T14:05:00.212Z","dependency_job_id":"b9aa0bd1-725e-4c68-a11e-4544735dd5be","html_url":"https://github.com/gr2m/node-http-recorder","commit_stats":{"total_commits":68,"total_committers":2,"mean_commits":34.0,"dds":0.3529411764705882,"last_synced_commit":"dc0f5a91fc5d517342130f8590507393fd9acaef"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fnode-http-recorder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fnode-http-recorder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fnode-http-recorder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fnode-http-recorder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gr2m","download_url":"https://codeload.github.com/gr2m/node-http-recorder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248683011,"owners_count":21144862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T21:21:33.012Z","updated_at":"2025-04-19T23:34:02.681Z","avatar_url":"https://github.com/gr2m.png","language":"JavaScript","funding_links":["https://github.com/sponsors/gr2m"],"categories":[],"sub_categories":[],"readme":"# `@gr2m/http-recorder`\n\n\u003e Library agnostic in-process recording of http(s) requests and responses\n\n[![Test](https://github.com/gr2m/node-http-recorder/actions/workflows/test.yml/badge.svg)](https://github.com/gr2m/node-http-recorder/actions/workflows/test.yml)\n\n## Features\n\n- unopiniated, minimal library, as low-level as possible\n- to record http(s) requests and responses within the same process, without starting a server or proxying\n\n## Goals \u0026 trade-offs\n\nI created `@gr2m/http-recorder` as a utility library that can be used as a building stone for more opiniated libraries. I'm one of the maintainers of [nock](https://github.com/nock/nock/) and hope to use this library to replace what `nock` is currently doing with much more code.\n\n`@gr2m/http-recorder` plays well with [Mitm.js](https://github.com/moll/node-mitm) (or its [esm version](https://github.com/gr2m/mitm-esm)), which is another lowe-level library but focused on mocking http(s) and net requests.\n\nNote that the requests \u0026 responses you receive from the `\"record\"` event is as-is. If the request or response was encoded then it's up to you to decode it if you need to.\n\n## Install\n\n```\nnpm install @gr2m/http-recorder\n```\n\n## Usage\n\n```js\nimport http from \"node:http\";\nimport httpRecorder from \"@gr2m/http-recorder\";\n\nhttpRecorder.start();\nhttpRecorder.addListener(\n  \"record\",\n  ({ request, response, requestBody, responseBody }) =\u003e {\n    const { method, protocol, host, path } = request;\n    const requestHeaders = request.getHeaders();\n\n    console.log(`\u003e %s %s//%s%s`, method, protocol, host, path);\n    console.log(`\u003e %j`, requestHeaders);\n    console.log(Buffer.concat(requestBody).toString());\n\n    const { statusCode, statusMessage, headers: responseHeaders } = response;\n    console.log(`\\n\u003c %s %s`, statusCode, statusMessage);\n    console.log(`\u003c %j`, responseHeaders);\n    console.log(Buffer.concat(responseBody).toString());\n  },\n);\n\nconst request = http.request(\"http://httpbin.org/post\", { method: \"post\" });\nrequest.write(\"data\");\nrequest.end();\n\n// \u003e POST http://httpbin.org/post\n// \u003e {\"host\":\"httpbin.org\"}\n// data\n//\n// \u003c 200 OK\n// \u003c {\"content-type\":\"application/json\",...}\n// {\n//   \"args\": {},\n//   \"data\": \"data\",\n//   ...\n// }\n```\n\nSee more [examples](examples)\n\n## API\n\n`httpRecorder` is a singleton API.\n\n### `httpRecorder.start()`\n\nHooks into the request life cycle and emits `record` events for each request sent through the `http` or `https` modules.\n\n### `httpRecorder.stop()`\n\nRemoves the hooks. No `record` events will be emitted.\n\n### `httpRecorder.addListener(\"record\", listener)`\n\nSubscribe to a `record` event. The `listener` callback is called with an options object\n\n- `options.request`: an [`http.ClientRequest` instance](https://nodejs.org/api/http.html#class-httpclientrequest)\n- `options.response`: an [`http.IncomingMessage` instance](https://nodejs.org/api/http.html#class-httpincomingmessage)\n- `options.requestBody`: An array of Buffer chunks representing the request body\n- `options.responseBody`: An array of Buffer chunks representing the response body\n\n### `httpRecorder.removeListener(\"record\", listener)`\n\nRemove a `record` event listener.\n\n### `httpRecorder.removeAllListeners()`\n\nRemoves all `record` event listeners.\n\n## How it works\n\nOnce started, `httpRecorder` hooks itself into [the `http.ClientRequest.prototype.onSocket` method](https://github.com/nodejs/node/blob/cf6996458b82ec0bdf97209bce380e1483c349fb/lib/_http_client.js#L778-L782) which is conveniently called synchronously in [the `http.ClientRequest` constructor](https://nodejs.org/api/http.html#class-httpclientrequest).\n\nWhen a request is intercepted, we\n\n1. hook into [the `request.write` method](https://github.com/nodejs/node/blob/cf6996458b82ec0bdf97209bce380e1483c349fb/lib/_http_outgoing.js#L701-L711) and [the `request.end` method](https://github.com/nodejs/node/blob/cf6996458b82ec0bdf97209bce380e1483c349fb/lib/_http_outgoing.js#L833-L906) in order to clone the request body\n2. subscribe to [the `response` event](https://nodejs.org/api/http.html#event-response)\n3. hook into the `response.emit` method in order to clone the response body without consuming it\n\nand then emit a `record` event with the `request`, `response`, `requestBody` and `responseBody` options.\n\n## See also\n\n- [`@gr2m/net-interceptor`](https://github.com/gr2m/node-net-interceptor) - Intercept outgoing network TCP/TLS connections\n- [`@gr2m/http-interceptor`](https://github.com/gr2m/node-http-interceptor) - Intercept and mock outgoing http/https requests\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Credit\n\nThe inspiration for hooking into `http.ClientRequest.prototype.onSocket` method comes from [Mitm.js](https://github.com/moll/node-mitm/#readme) - an http mocking library for TCP connections and http(s) requests.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgr2m%2Fnode-http-recorder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgr2m%2Fnode-http-recorder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgr2m%2Fnode-http-recorder/lists"}