@antelopejs/interface-api-util 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +78 -11
- package/dist/antelope.test.js +2 -1
- package/dist/antelope.test.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/rate-limit.js +1 -1
- package/dist/rate-limit.js.map +1 -1
- package/dist/tests/rate-limit.test.js +1 -1
- package/dist/tests/rate-limit.test.js.map +1 -1
- package/docs/1.introduction.md +198 -0
- package/docs/tsconfig.json +12 -0
- package/package.json +41 -22
- package/skills/api-util-interface/SKILL.md +102 -0
package/README.md
CHANGED
|
@@ -1,26 +1,93 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @antelopejs/interface-api-util
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="https://www.npmjs.com/package/@antelopejs/interface-api-util"><img src="https://img.shields.io/npm/v/@antelopejs/interface-api-util?style=for-the-badge&labelColor=000000&color=000000"
|
|
5
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/
|
|
6
|
-
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"
|
|
7
|
-
<a href="
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-api-util"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-api-util?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
+
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-api-util?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
+
<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
7
|
+
<a href="https://interfaces.antelopejs.com/docs/api-util"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
8
8
|
</div>
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Request validation and rate limiting helpers for handlers written against [`@antelopejs/interface-api`](https://github.com/AntelopeJS/interface-api). Every failure becomes an `HTTPResult` error response.
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## What it offers
|
|
13
|
+
|
|
14
|
+
- `assert(condition, code, message)` throws an `HTTPResult` when the condition is falsy and narrows its type when it holds.
|
|
15
|
+
- `assertValidation(body, validator)` runs a synchronous validator, such as a Zod `parse`, and turns a thrown error into a `400` response.
|
|
16
|
+
- `@RateLimit(limit, windowMs)` caps calls to a handler per client in a fixed window and answers `429` beyond it.
|
|
17
|
+
|
|
18
|
+
## Implementations
|
|
19
|
+
|
|
20
|
+
The helpers run in your module. They need the API interface served by a module:
|
|
21
|
+
|
|
22
|
+
| Module | Notes |
|
|
23
|
+
| ------------------------------------------------------ | --------------------------------------------------------------------------- |
|
|
24
|
+
| [`@antelopejs/api`](https://github.com/AntelopeJS/api) | Implements `@antelopejs/interface-api` and `@antelopejs/interface-api-util` |
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
Add the package to the module that declares routes:
|
|
13
29
|
|
|
14
30
|
```bash
|
|
15
|
-
|
|
31
|
+
pnpm add @antelopejs/interface-api-util
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Then add an implementation of the API interface to the project:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
ajs project modules add @antelopejs/api
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Quick start
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import {
|
|
44
|
+
Controller,
|
|
45
|
+
Get,
|
|
46
|
+
HTTPResult,
|
|
47
|
+
Parameter,
|
|
48
|
+
} from "@antelopejs/interface-api";
|
|
49
|
+
import { RateLimit, assert } from "@antelopejs/interface-api-util";
|
|
50
|
+
|
|
51
|
+
const BOOKS = new Map([["1", { title: "The Glass Meridian" }]]);
|
|
52
|
+
|
|
53
|
+
export class BookController extends Controller("/books") {
|
|
54
|
+
@Get(":id")
|
|
55
|
+
@RateLimit(100, 60_000)
|
|
56
|
+
async getBook(@Parameter("id") id: string) {
|
|
57
|
+
const book = BOOKS.get(id);
|
|
58
|
+
assert(book, 404, "Book not found");
|
|
59
|
+
return new HTTPResult(200, book);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
16
62
|
```
|
|
17
63
|
|
|
64
|
+
Place `@RateLimit` directly below the route decorator. Placed above it, `@RateLimit` throws when the class is defined.
|
|
65
|
+
|
|
18
66
|
## Documentation
|
|
19
67
|
|
|
20
|
-
|
|
68
|
+
- [Assertions, validation and rate limiting](./docs/1.introduction.md)
|
|
69
|
+
|
|
70
|
+
## Compatibility
|
|
71
|
+
|
|
72
|
+
Use with `@antelopejs/core` 1.x and the following peer dependencies:
|
|
21
73
|
|
|
22
|
-
-
|
|
74
|
+
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
75
|
+
|
|
76
|
+
| Package | Range |
|
|
77
|
+
| ---------------------------- | ----------------- |
|
|
78
|
+
| `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
|
|
79
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
80
|
+
|
|
81
|
+
## Contributing
|
|
82
|
+
|
|
83
|
+
Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pnpm install
|
|
87
|
+
pnpm lint
|
|
88
|
+
pnpm test
|
|
89
|
+
```
|
|
23
90
|
|
|
24
91
|
## License
|
|
25
92
|
|
|
26
|
-
|
|
93
|
+
[Apache-2.0](./LICENSE)
|
package/dist/antelope.test.js
CHANGED
|
@@ -9,10 +9,11 @@ exports.default = (0, config_1.defineConfig)({
|
|
|
9
9
|
source: {
|
|
10
10
|
type: "package",
|
|
11
11
|
package: "@antelopejs/api",
|
|
12
|
-
version: "1.
|
|
12
|
+
version: "1.3.0",
|
|
13
13
|
},
|
|
14
14
|
config: {
|
|
15
15
|
servers: [{ protocol: "http", host: "127.0.0.1", port: 5010 }],
|
|
16
|
+
publicBaseUrl: "http://127.0.0.1:5010",
|
|
16
17
|
},
|
|
17
18
|
},
|
|
18
19
|
},
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../src/antelope.test.ts"],"names":[],"mappings":";;AAAA,8DAAiE;AAEjE,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE;QACP,GAAG,EAAE;YACH,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,iBAAiB;gBAC1B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;
|
|
1
|
+
{"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../src/antelope.test.ts"],"names":[],"mappings":";;AAAA,8DAAiE;AAEjE,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE;QACP,GAAG,EAAE;YACH,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,iBAAiB;gBAC1B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBAC9D,aAAa,EAAE,uBAAuB;aACvC;SACF;KACF;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY;KACrB;CACF,CAAC,CAAC"}
|
package/dist/index.d.ts
CHANGED
|
@@ -23,8 +23,9 @@ export * from "./rate-limit";
|
|
|
23
23
|
*/
|
|
24
24
|
export declare function assert<T>(condition: T, code: number, message: string): asserts condition;
|
|
25
25
|
/**
|
|
26
|
-
* Executes
|
|
26
|
+
* Executes a synchronous validator on a body, converting thrown errors to HTTPResult.
|
|
27
27
|
* The validator should return a validated object on success and throw on failure.
|
|
28
|
+
* Promises are returned unchanged; asynchronous rejections are not converted.
|
|
28
29
|
*
|
|
29
30
|
* The error thrown by the validator may be altered by passing an error handler.
|
|
30
31
|
* The result of this error handler will be passed directly as the body of the HTTPResult.
|
package/dist/index.js
CHANGED
|
@@ -46,8 +46,9 @@ function assert(condition, code, message) {
|
|
|
46
46
|
}
|
|
47
47
|
}
|
|
48
48
|
/**
|
|
49
|
-
* Executes
|
|
49
|
+
* Executes a synchronous validator on a body, converting thrown errors to HTTPResult.
|
|
50
50
|
* The validator should return a validated object on success and throw on failure.
|
|
51
|
+
* Promises are returned unchanged; asynchronous rejections are not converted.
|
|
51
52
|
*
|
|
52
53
|
* The error thrown by the validator may be altered by passing an error handler.
|
|
53
54
|
* The result of this error handler will be passed directly as the body of the HTTPResult.
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AA0BA,wBAQC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AA0BA,wBAQC;AA2BD,4CAYC;AAzED,6DAAuD;AAEvD,+CAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,MAAM,CACpB,SAAY,EACZ,IAAY,EACZ,OAAe;IAEf,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,0BAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,gBAAgB,CAC9B,IAAa,EACb,SAA+B,EAC/B,SAAqC,EACrC,IAAI,GAAG,GAAG;IAEV,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpD,MAAM,IAAI,0BAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;AACH,CAAC"}
|
package/dist/rate-limit.js
CHANGED
|
@@ -4,9 +4,9 @@ exports.RateLimit = void 0;
|
|
|
4
4
|
exports.hitWindow = hitWindow;
|
|
5
5
|
exports.pruneExpired = pruneExpired;
|
|
6
6
|
exports.resolveKey = resolveKey;
|
|
7
|
-
const interface_api_1 = require("@antelopejs/interface-api");
|
|
8
7
|
const interface_core_1 = require("@antelopejs/interface-core");
|
|
9
8
|
const decorators_1 = require("@antelopejs/interface-core/decorators");
|
|
9
|
+
const interface_api_1 = require("@antelopejs/interface-api");
|
|
10
10
|
const TOO_MANY_REQUESTS = 429;
|
|
11
11
|
const DEFAULT_MESSAGE = "Too many requests";
|
|
12
12
|
const UNKNOWN_KEY = "unknown";
|
package/dist/rate-limit.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":";;;AA6DA,8BAkBC;AAQD,oCAUC;AAQD,gCASC;AAlHD
|
|
1
|
+
{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}
|
|
@@ -13,8 +13,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
13
13
|
};
|
|
14
14
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
15
15
|
const node_assert_1 = __importDefault(require("node:assert"));
|
|
16
|
-
const interface_api_1 = require("@antelopejs/interface-api");
|
|
17
16
|
const interface_core_1 = require("@antelopejs/interface-core");
|
|
17
|
+
const interface_api_1 = require("@antelopejs/interface-api");
|
|
18
18
|
const rate_limit_1 = require("../rate-limit");
|
|
19
19
|
const TOO_MANY_REQUESTS = 429;
|
|
20
20
|
const LIMIT = 2;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rate-limit.test.js","sourceRoot":"","sources":["../../src/tests/rate-limit.test.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAAA,8DAAqC;AACrC
|
|
1
|
+
{"version":3,"file":"rate-limit.test.js","sourceRoot":"","sources":["../../src/tests/rate-limit.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Interface API Util Documentation
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Interface API Util provides utilities for validating API requests, rate limiting handlers, and returning structured HTTP error responses. The package exports `assert` for checking conditions, `assertValidation` for running input validators, and the `@RateLimit` decorator for throttling handlers. All of them surface failures as `HTTPResult` errors from `@antelopejs/interface-api`.
|
|
6
|
+
|
|
7
|
+
## Getting Started
|
|
8
|
+
|
|
9
|
+
Install the package in your project:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @antelopejs/interface-api-util
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## `assert`
|
|
16
|
+
|
|
17
|
+
The `assert` function checks whether a condition is truthy. If the condition is falsy, it throws an `HTTPResult` with the specified HTTP status code and error message.
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
function assert<T>(
|
|
21
|
+
condition: T,
|
|
22
|
+
code: number,
|
|
23
|
+
message: string,
|
|
24
|
+
): asserts condition;
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
| Parameter | Type | Description |
|
|
28
|
+
| ----------- | -------- | --------------------------------------------------- |
|
|
29
|
+
| `condition` | `T` | The value to check (falsy values trigger the error) |
|
|
30
|
+
| `code` | `number` | HTTP status code for the error response |
|
|
31
|
+
| `message` | `string` | Error message included in the response body |
|
|
32
|
+
|
|
33
|
+
The function uses TypeScript's `asserts` keyword, so the compiler narrows the type of `condition` to truthy after the call.
|
|
34
|
+
|
|
35
|
+
### Check that a resource exists
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { assert } from "@antelopejs/interface-api-util";
|
|
39
|
+
import { HTTPResult } from "@antelopejs/interface-api";
|
|
40
|
+
|
|
41
|
+
async function getUser(id: string) {
|
|
42
|
+
const user = await findUser(id);
|
|
43
|
+
assert(user, 404, "User not found");
|
|
44
|
+
|
|
45
|
+
// TypeScript knows `user` is defined here
|
|
46
|
+
return new HTTPResult(200, user);
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Validate permissions
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import { assert } from "@antelopejs/interface-api-util";
|
|
54
|
+
import { HTTPResult } from "@antelopejs/interface-api";
|
|
55
|
+
|
|
56
|
+
async function deletePost(postId: string, currentUserId: string) {
|
|
57
|
+
const post = await findPost(postId);
|
|
58
|
+
assert(post, 404, "Post not found");
|
|
59
|
+
assert(
|
|
60
|
+
post.authorId === currentUserId,
|
|
61
|
+
403,
|
|
62
|
+
"Not authorized to delete this post",
|
|
63
|
+
);
|
|
64
|
+
|
|
65
|
+
await removePost(postId);
|
|
66
|
+
return new HTTPResult(200, { deleted: true });
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## `assertValidation`
|
|
71
|
+
|
|
72
|
+
The `assertValidation` function runs a synchronous validator on an input value. If the validator throws, `assertValidation` catches the error and throws an `HTTPResult` instead. It does not await promises or convert asynchronous rejections; use a synchronous validator such as Zod's `parse`, not `parseAsync`.
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
function assertValidation<T>(
|
|
76
|
+
body: unknown,
|
|
77
|
+
validator: (body: unknown) => T,
|
|
78
|
+
errorFunc?: (err: unknown) => unknown,
|
|
79
|
+
code?: number,
|
|
80
|
+
): T;
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
| Parameter | Type | Default | Description |
|
|
84
|
+
| ----------- | --------------------------- | ------- | ------------------------------------------------------- |
|
|
85
|
+
| `body` | `unknown` | | The input value to validate |
|
|
86
|
+
| `validator` | `(body: unknown) => T` | | A function that returns the validated value or throws |
|
|
87
|
+
| `errorFunc` | `(err: unknown) => unknown` | | Optional error transformer for customizing the response |
|
|
88
|
+
| `code` | `number` | `400` | HTTP status code for the error response |
|
|
89
|
+
|
|
90
|
+
The function returns the validated value on success. On failure, it throws an `HTTPResult` whose body is either the result of `errorFunc` or the stringified error.
|
|
91
|
+
|
|
92
|
+
### Validate with Zod
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
import { assertValidation } from "@antelopejs/interface-api-util";
|
|
96
|
+
import * as z from "zod";
|
|
97
|
+
|
|
98
|
+
const createUserSchema = z.object({
|
|
99
|
+
name: z.string().min(1),
|
|
100
|
+
email: z.string().email(),
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
function createUser(requestBody: unknown) {
|
|
104
|
+
const { name, email } = assertValidation(requestBody, createUserSchema.parse);
|
|
105
|
+
|
|
106
|
+
// `name` and `email` are typed strings here
|
|
107
|
+
return saveUser({ name, email });
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Custom error formatting
|
|
112
|
+
|
|
113
|
+
Pass an `errorFunc` to control the error response body.
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
import { assertValidation } from "@antelopejs/interface-api-util";
|
|
117
|
+
import * as z from "zod";
|
|
118
|
+
|
|
119
|
+
const schema = z.object({ age: z.number().min(18) });
|
|
120
|
+
|
|
121
|
+
function validateAge(requestBody: unknown) {
|
|
122
|
+
return assertValidation(
|
|
123
|
+
requestBody,
|
|
124
|
+
schema.parse,
|
|
125
|
+
(err) => {
|
|
126
|
+
if (err instanceof z.ZodError) {
|
|
127
|
+
return { errors: err.issues.map((e) => e.message) };
|
|
128
|
+
}
|
|
129
|
+
return { errors: [String(err)] };
|
|
130
|
+
},
|
|
131
|
+
422,
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## `RateLimit`
|
|
137
|
+
|
|
138
|
+
The `@RateLimit` decorator caps how often a route handler can be called. It counts requests per client in a fixed time window (in-memory, per process). Successful responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (a UNIX epoch-seconds timestamp) so clients can self-pace. Once the count exceeds `limit` within `windowMs`, the handler instead throws an `HTTPResult` with status `429` (adding a `Retry-After` header) without running.
|
|
139
|
+
|
|
140
|
+
```typescript
|
|
141
|
+
function RateLimit(
|
|
142
|
+
limit: number,
|
|
143
|
+
windowMs: number,
|
|
144
|
+
options?: RateLimitOptions,
|
|
145
|
+
): MethodDecorator;
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
| Parameter | Type | Description |
|
|
149
|
+
| ---------- | ------------------ | ---------------------------------------------------- |
|
|
150
|
+
| `limit` | `number` | Maximum number of requests allowed per window |
|
|
151
|
+
| `windowMs` | `number` | Window duration in milliseconds |
|
|
152
|
+
| `options` | `RateLimitOptions` | Optional custom key function and `429` response body |
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
interface RateLimitOptions {
|
|
156
|
+
key?: (context: RequestContext) => string | null | undefined;
|
|
157
|
+
message?: string;
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
By default, requests are counted per client IP (`context.rawRequest.socket.remoteAddress`). Provide `options.key` to count by user id, API key, or a forwarded header instead. If the custom key function returns a falsy value (for example a missing route parameter), the limiter falls back to the client IP rather than collapsing every such request into one shared bucket.
|
|
162
|
+
|
|
163
|
+
> **Ordering matters.** Place `@RateLimit` **directly beneath** the route decorator (`@Get`, `@Post`, …). The route decorator captures the handler's parameters when it is applied, so a `@RateLimit` above it would be ignored — this is detected at startup and throws, rather than silently leaving the route unprotected.
|
|
164
|
+
|
|
165
|
+
### Limit by client IP
|
|
166
|
+
|
|
167
|
+
```typescript
|
|
168
|
+
import { RateLimit } from "@antelopejs/interface-api-util";
|
|
169
|
+
import { Controller, Get, HTTPResult } from "@antelopejs/interface-api";
|
|
170
|
+
|
|
171
|
+
class UsersController extends Controller("users") {
|
|
172
|
+
@Get()
|
|
173
|
+
@RateLimit(100, 60_000)
|
|
174
|
+
list() {
|
|
175
|
+
return new HTTPResult(200, { users: [] });
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Limit by a custom key
|
|
181
|
+
|
|
182
|
+
```ts docs-check
|
|
183
|
+
import { RateLimit } from "@antelopejs/interface-api-util";
|
|
184
|
+
import { Controller, Post, HTTPResult } from "@antelopejs/interface-api";
|
|
185
|
+
|
|
186
|
+
class AuthController extends Controller("auth") {
|
|
187
|
+
@Post(":tenant/login")
|
|
188
|
+
@RateLimit(5, 60_000, {
|
|
189
|
+
key: (ctx) => ctx.routeParameters.tenant,
|
|
190
|
+
message: "Too many login attempts, slow down",
|
|
191
|
+
})
|
|
192
|
+
login() {
|
|
193
|
+
return new HTTPResult(200, { ok: true });
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Counts are kept in process memory, so they are not shared across instances and reset on restart. Elapsed windows are pruned periodically, so the store is bounded by the number of distinct keys seen within a single window rather than growing forever. For distributed limits, key by a stable identifier and enforce limits in a shared store at the edge. Behind a proxy, the socket address is the proxy's — supply `options.key` to read a forwarded header, but only trust the hop your proxy sets (a raw client-supplied `X-Forwarded-For` is spoofable and can be used to evade or to inflate the key cardinality).
|
package/package.json
CHANGED
|
@@ -1,24 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-api-util",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "AntelopeJS
|
|
3
|
+
"version": "0.1.3",
|
|
4
|
+
"description": "AntelopeJS helpers for API handlers: request assertions, input validation and rate limiting",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
7
|
-
"interface",
|
|
8
7
|
"api",
|
|
8
|
+
"interface",
|
|
9
|
+
"rate-limit",
|
|
9
10
|
"validation"
|
|
10
11
|
],
|
|
12
|
+
"homepage": "https://interfaces.antelopejs.com/docs/api-util",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/AntelopeJS/interface-api-util/issues"
|
|
15
|
+
},
|
|
16
|
+
"license": "Apache-2.0",
|
|
11
17
|
"repository": {
|
|
12
18
|
"type": "git",
|
|
13
19
|
"url": "git+https://github.com/AntelopeJS/interface-api-util.git"
|
|
14
20
|
},
|
|
15
|
-
"license": "Apache-2.0",
|
|
16
|
-
"packageManager": "pnpm@10.6.5",
|
|
17
|
-
"main": "dist/index.js",
|
|
18
|
-
"types": "dist/index.d.ts",
|
|
19
21
|
"files": [
|
|
20
|
-
"dist"
|
|
22
|
+
"dist",
|
|
23
|
+
"docs",
|
|
24
|
+
"skills"
|
|
21
25
|
],
|
|
26
|
+
"main": "dist/index.js",
|
|
27
|
+
"types": "dist/index.d.ts",
|
|
22
28
|
"exports": {
|
|
23
29
|
".": {
|
|
24
30
|
"types": "./dist/index.d.ts",
|
|
@@ -26,34 +32,47 @@
|
|
|
26
32
|
},
|
|
27
33
|
"./package.json": "./package.json"
|
|
28
34
|
},
|
|
35
|
+
"publishConfig": {
|
|
36
|
+
"access": "public",
|
|
37
|
+
"provenance": true
|
|
38
|
+
},
|
|
29
39
|
"scripts": {
|
|
30
40
|
"build": "rimraf dist && tsc",
|
|
31
|
-
"format": "
|
|
32
|
-
"lint:fix": "
|
|
33
|
-
"lint": "
|
|
41
|
+
"format": "oxfmt .",
|
|
42
|
+
"lint:fix": "oxlint --fix",
|
|
43
|
+
"lint": "oxlint",
|
|
34
44
|
"prepack": "pnpm run build",
|
|
35
45
|
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
36
|
-
"test": "pnpm run build && ajs module test ."
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
"test": "src/antelope.test.ts"
|
|
46
|
+
"test": "pnpm run build && ajs module test .",
|
|
47
|
+
"format:check": "oxfmt --check .",
|
|
48
|
+
"knip": "knip"
|
|
40
49
|
},
|
|
41
50
|
"devDependencies": {
|
|
42
|
-
"@antelopejs/
|
|
43
|
-
"@antelopejs/interface-
|
|
44
|
-
"@
|
|
51
|
+
"@antelopejs/core": "^1.16.0",
|
|
52
|
+
"@antelopejs/interface-api": "^0.0.15",
|
|
53
|
+
"@antelopejs/interface-core": "^0.2.4",
|
|
54
|
+
"@antelopejs/tooling-configs": "^0.0.9",
|
|
45
55
|
"@types/mocha": "^10.0.10",
|
|
46
56
|
"@types/node": "^22.19.15",
|
|
57
|
+
"eslint-plugin-perfectionist": "^5.11.0",
|
|
58
|
+
"knip": "^6.34.0",
|
|
59
|
+
"oxfmt": "^0.66.0",
|
|
60
|
+
"oxlint": "1.81.0",
|
|
61
|
+
"oxlint-tsgolint": "^7.0.2001",
|
|
47
62
|
"release-it": "^19.2.4",
|
|
48
63
|
"release-it-changelogen": "^0.1.0",
|
|
49
64
|
"rimraf": "^6.1.3",
|
|
50
65
|
"typescript": "^5.9.3"
|
|
51
66
|
},
|
|
52
67
|
"peerDependencies": {
|
|
53
|
-
"@antelopejs/interface-api": ">=0.0.
|
|
54
|
-
"@antelopejs/interface-core": ">=0.
|
|
68
|
+
"@antelopejs/interface-api": ">=0.0.15 <1.0.0",
|
|
69
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0"
|
|
55
70
|
},
|
|
56
|
-
"
|
|
57
|
-
|
|
71
|
+
"packageManager": "pnpm@10.6.5",
|
|
72
|
+
"antelopeJs": {
|
|
73
|
+
"test": "src/antelope.test.ts",
|
|
74
|
+
"skills": [
|
|
75
|
+
"./skills"
|
|
76
|
+
]
|
|
58
77
|
}
|
|
59
78
|
}
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-util-interface
|
|
3
|
+
description: Provides handler-side utilities for AntelopeJS APIs built on @antelopejs/interface-api - assert and assertValidation turn failed checks into HTTPResult error responses, and the @RateLimit method decorator adds fixed-window throttling with 429/Retry-After and X-RateLimit headers. Use when code imports from "@antelopejs/interface-api-util", when validating request bodies (e.g. with a Zod schema) inside @Get/@Post handlers, when returning 400/404/403-style errors from API controllers, or when asked to rate limit a route.
|
|
4
|
+
category: antelopejs-interface
|
|
5
|
+
tags: [antelopejs, api, validation, rate-limit, http]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# API Util Interface
|
|
9
|
+
|
|
10
|
+
Consumer-side helper library for AntelopeJS API modules. It is NOT an interface proxy itself:
|
|
11
|
+
nothing here crosses an interface boundary, so there is no `ImplementInterface` side. Everything
|
|
12
|
+
builds on its peer dependencies `@antelopejs/interface-api` (for `HTTPResult`, `RequestContext`,
|
|
13
|
+
controller metadata) and `@antelopejs/interface-core` (decorator machinery). All failures surface
|
|
14
|
+
as thrown `HTTPResult` values, which the API interface converts into HTTP responses.
|
|
15
|
+
|
|
16
|
+
## Imports
|
|
17
|
+
|
|
18
|
+
The package has a single export subpath (root only):
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import {
|
|
22
|
+
assert,
|
|
23
|
+
assertValidation,
|
|
24
|
+
RateLimit,
|
|
25
|
+
type RateLimitOptions,
|
|
26
|
+
} from "@antelopejs/interface-api-util";
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`hitWindow`, `pruneExpired`, and `resolveKey` are also exported but marked `@internal` (rate-limit
|
|
30
|
+
plumbing, exposed for tests) — do not reach for them in application code.
|
|
31
|
+
|
|
32
|
+
## Usage
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import {
|
|
36
|
+
Controller,
|
|
37
|
+
Get,
|
|
38
|
+
Post,
|
|
39
|
+
HTTPResult,
|
|
40
|
+
Parameter,
|
|
41
|
+
RawBody,
|
|
42
|
+
} from "@antelopejs/interface-api";
|
|
43
|
+
import {
|
|
44
|
+
assert,
|
|
45
|
+
assertValidation,
|
|
46
|
+
RateLimit,
|
|
47
|
+
} from "@antelopejs/interface-api-util";
|
|
48
|
+
import * as z from "zod";
|
|
49
|
+
|
|
50
|
+
const createMemberSchema = z.object({
|
|
51
|
+
fullName: z.string().min(1),
|
|
52
|
+
email: z.string().email(),
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
class MembersController extends Controller("members") {
|
|
56
|
+
@Get(":id")
|
|
57
|
+
@RateLimit(100, 60_000)
|
|
58
|
+
async get(@Parameter("id") id: string) {
|
|
59
|
+
const member = await findMember(id);
|
|
60
|
+
assert(member, 404, "Member not found"); // narrows `member` to non-falsy below
|
|
61
|
+
return new HTTPResult(200, member);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
@Post()
|
|
65
|
+
async create(@RawBody() body: Buffer) {
|
|
66
|
+
const { fullName, email } = assertValidation(body, (b) =>
|
|
67
|
+
createMemberSchema.parse(JSON.parse((b as Buffer).toString())),
|
|
68
|
+
);
|
|
69
|
+
return new HTTPResult(201, await saveMember({ fullName, email }));
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- `assert(condition, code, message)` — throws `new HTTPResult(code, message)` when falsy; uses
|
|
75
|
+
TypeScript `asserts condition`, so the compiler narrows after the call.
|
|
76
|
+
- `assertValidation(body, validator, errorFunc?, code = 400)` — returns the validator's result;
|
|
77
|
+
if the validator throws, rethrows an `HTTPResult` whose body is `errorFunc(err)` if provided,
|
|
78
|
+
otherwise `String(err)`.
|
|
79
|
+
- `RateLimit(limit, windowMs, options?)` — fixed-window counter per key; over-limit requests throw
|
|
80
|
+
a 429 `HTTPResult` (with `Retry-After`) before the handler runs. Successful responses get
|
|
81
|
+
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (epoch seconds) headers.
|
|
82
|
+
|
|
83
|
+
## Gotchas
|
|
84
|
+
|
|
85
|
+
- Decorator ordering: `@RateLimit` must sit directly BENEATH the route decorator
|
|
86
|
+
(`@Get`, `@Post`, ...). Placed above it, the guard would be ignored — this is detected at
|
|
87
|
+
decoration time and throws an `Error` at startup instead of silently unprotecting the route.
|
|
88
|
+
- Rate-limit keys default to the client IP (`context.rawRequest.socket.remoteAddress`). Behind a
|
|
89
|
+
proxy that is the proxy's address — supply `options.key` reading a trusted forwarded header. If
|
|
90
|
+
the custom `key` function returns a falsy value, the limiter falls back to the client IP rather
|
|
91
|
+
than merging those requests into one shared bucket.
|
|
92
|
+
- Counts live in process memory: not shared across instances, reset on restart, pruned once the
|
|
93
|
+
window elapses. For distributed limits, enforce them in a shared store at the edge.
|
|
94
|
+
- `options.message` customizes only the 429 body; the status code is fixed at 429.
|
|
95
|
+
- These helpers only throw `HTTPResult`; they do not send responses themselves — they rely on the
|
|
96
|
+
API interface's handling of thrown `HTTPResult` values.
|
|
97
|
+
|
|
98
|
+
## Deeper reference
|
|
99
|
+
|
|
100
|
+
See this package's `docs/1.introduction.md` (Interface API Util Documentation: `assert`,
|
|
101
|
+
`assertValidation`, `RateLimit` sections) and the shipped `dist/*.d.ts` typings. Do not duplicate
|
|
102
|
+
them here.
|