# @imqueue/http-protect 3.0.1 · API reference

Source: https://imqueue.org/api/http-protect/latest/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/http-protect 3.0.1 — generated reference, not hand-written

Rate limiting and IP banning for express-like HTTP servers, backed by Redis.

[HttpProtect](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect/) counts requests per client IP and, past two configurable thresholds, first answers 429 and then adds the address to a persistent block list answered with 418. Mount it as [HttpProtect.jsonMiddleware()](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.jsonmiddleware/), [HttpProtect.textMiddleware()](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.textmiddleware/) or [HttpProtect.middleware()](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.middleware/), or call [HttpProtect.verify()](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.verify/) yourself and act on the [VerificationStatus](https://imqueue.org/api/http-protect/latest/http-protect.verificationstatus/) it returns.

## Remarks

Three things about this package are load-bearing and none of them is visible in a signature.

A ban is permanent. Addresses go into a Redis set that is never given an expiry and never written to again, and there is no method here that removes one — so an address stays banned until something outside this package deletes it from Redis. Read [HttpProtect.banLimit](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.banlimit/) before choosing a value for it.

The request counter measures a continuous stream, not a fixed window. Its TTL is pushed back to [HttpProtect.ttl](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.ttl/) on every request, so the count only resets after a full `ttl` of silence from that address. A client that keeps making requests accumulates indefinitely, which is why the default [HttpProtect.maxRequests](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.maxrequests/) of 200 stops a steady 1-per-second client after about 200 seconds and not just a 200-request burst.

Everything is keyed by the client IP, and by default that comes from proxy headers a client can set. See [HttpProtectOptions.getClientIp](https://imqueue.org/api/http-protect/latest/http-protect.httpprotectoptions.getclientip/) before exposing this to the internet behind a proxy you do not control.

## Example 1


```typescript
import HttpProtect from '@imqueue/http-protect';

// 429 then 418, as JSON, using default thresholds and a local Redis
app.use(new HttpProtect().jsonMiddleware());
```

## Example 2


```typescript
import HttpProtect, { VerificationStatus } from '@imqueue/http-protect';

const protect = new HttpProtect({ ttl: 60, maxRequests: 600, banLimit: 5000 });
const { status, httpCode } = await protect.verify(req);

if (status !== VerificationStatus.SAFE) {
    res.status(httpCode).end();
}
```

## Classes


| Class | Description |
| --- | --- |
| [HttpProtect](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect/) | Per-IP request counting, rate limiting and banning for an express-like server. |


## Enumerations


| Enumeration | Description |
| --- | --- |
| [VerificationStatus](https://imqueue.org/api/http-protect/latest/http-protect.verificationstatus/) | What [HttpProtect.verify()](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.verify/) concluded about a request. |


## Interfaces


| Interface | Description |
| --- | --- |
| [HttpProtectOptions](https://imqueue.org/api/http-protect/latest/http-protect.httpprotectoptions/) | Configuration for the [HttpProtect](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect/) constructor. |
| [NextFunction](https://imqueue.org/api/http-protect/latest/http-protect.nextfunction/) | The `next()` callback an express-like framework passes to a middleware. |
| [Response](https://imqueue.org/api/http-protect/latest/http-protect.response/) | The minimum a response object must provide for the middlewares to answer with. |
| [VerificationResponse](https://imqueue.org/api/http-protect/latest/http-protect.verificationresponse/) | The verdict [HttpProtect.verify()](https://imqueue.org/api/http-protect/latest/http-protect.httpprotect.verify/) returns. |