https://github.com/gr2m/node-http-interceptor
Intercept and mock outgoing http/https requests
https://github.com/gr2m/node-http-interceptor
Last synced: 5 months ago
JSON representation
Intercept and mock outgoing http/https requests
- Host: GitHub
- URL: https://github.com/gr2m/node-http-interceptor
- Owner: gr2m
- License: other
- Created: 2021-12-27T12:07:23.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-09-23T19:40:33.000Z (almost 4 years ago)
- Last Synced: 2025-10-20T01:21:10.927Z (9 months ago)
- Language: JavaScript
- Size: 61.5 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# `@gr2m/http-interceptor`
[](https://github.com/gr2m/node-http-interceptor/actions/workflows/test.yml)
> Intercept and mock outgoing http/https requests
## Install
```
npm install @gr2m/http-interceptor
```
## Usage
```js
import httpInterceptor from "@gr2m/http-interceptor";
httpInterceptor.start();
httpInterceptor.on("connect", (socket, options, bypass) => {
// call bypass() to continue the unintercepted request
if (options.host === "db.example.com") return bypass();
});
httpInterceptor.on("request", (request, response) => {
response.end("Hello World!");
});
```
## API
`httpInterceptor` is a singleton API.
### `httpInterceptor.start()`
Hooks into the request life cycle and emits `connect` events for each request that connects to a server as well as `request` events for all intercepted requests.
### `httpInterceptor.stop()`
Stops intercepting. No `connect` or `request` events will be emitted.
### `httpInterceptor.addListener(event, listener)`
#### `connect` event
The `listener` callback is called with 3 arguments
- `socket`: the intercepted net or TLS socket
- `options`: socket options: `{port, /* host, localAddress, localPort, family, allowHalfOpen */}`
- `bypass`: a function to call to continue the unintercepted connection
#### `request` event
The `listener` callback is called with 2 arguments
- `request`: `Http.IncomingMessage`
- `response`: `Http.ServerResponse`
It's the same arguments as e.g. `http.createServer(listener)` receives.
### `httpInterceptor.removeListener(event, listener)`
Remove an event listener.
### `httpInterceptor.removeAllListeners(event)`
Removes all event listeners for the given event. Or when called without the `event` argument, remove all listeners for all events.
## See also
- [`@gr2m/net-interceptor`](https://github.com/gr2m/node-net-interceptor) - Intercept outgoing network TCP/TLS connections
- [`@gr2m/http-recorder`](https://github.com/gr2m/node-http-recorder) - Library agnostic in-process recording of http(s) requests and responses
## How it works
`@gr2m/http-interceptor` is using [`@gr2m/net-interceptor`](https://github.com/gr2m/node-net-interceptor/#readme) to intercept TCP/TLS connections, and to permit to bypass the interception.
`@gr2m/http-interceptor` also hooks into `http.ClientRequest.prototype.onSocket` which is called in the `http.ClientRequest` constructor. Each time `http.ClientRequest` is instantiated with a socket, we check if the socket is intercepted and if so, emit the `request` event with a `request`/`response` pair for mocking.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## Credits
`@gr2m/http-interceptor` is built upon code and concepts from [moll/node-mitm](https://github.com/moll/node-mitm) by [Andri Möll](http://themoll.com). [Monday Calendar](https://mondayapp.com) supported that engineering work.
**[Gregor Martynus](https://github.com/gr2m)** removed all `http(s)`-related code and made its focus on intercepting connections that use the lower-level `net` and `tls` modules.
## License
[LGPL](LICENSE.md)