@antelopejs/interface-api-util 0.1.3 → 0.2.0
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/dist/index.d.ts +8 -1
- package/dist/index.js +7 -0
- 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/capture-http-result.d.ts +2 -0
- package/dist/tests/capture-http-result.js +17 -0
- package/dist/tests/capture-http-result.js.map +1 -0
- package/dist/tests/index.test.js +28 -49
- package/dist/tests/index.test.js.map +1 -1
- package/dist/tests/rate-limit.test.js +28 -20
- package/dist/tests/rate-limit.test.js.map +1 -1
- package/docs/1.introduction.md +94 -15
- package/package.json +14 -3
- package/skills/api-util-interface/SKILL.md +6 -4
- package/skills/api-util-interface/cases.json +60 -0
package/dist/index.d.ts
CHANGED
|
@@ -31,6 +31,13 @@ export declare function assert<T>(condition: T, code: number, message: string):
|
|
|
31
31
|
* The result of this error handler will be passed directly as the body of the HTTPResult.
|
|
32
32
|
* If no error handler is given, assertValidation will resort to calling the error's toString() method if possible.
|
|
33
33
|
*
|
|
34
|
+
* The validator receives the body at the type of the argument you pass (`Input`, inferred from `body`;
|
|
35
|
+
* `unknown` when you give an explicit `T` only). A validator that accepts a wider type, such as
|
|
36
|
+
* `schema.parse`, always fits; one that accepts a narrower type than the body is rejected at compile time,
|
|
37
|
+
* except when the body is typed `any`, which fits every validator.
|
|
38
|
+
*
|
|
39
|
+
* @typeParam T Type of the validated result
|
|
40
|
+
* @typeParam Input Type of the body; the validator receives it at this type
|
|
34
41
|
* @param body Input to validate
|
|
35
42
|
* @param validator Validator function
|
|
36
43
|
* @param errorFunc Error handler
|
|
@@ -47,4 +54,4 @@ export declare function assert<T>(condition: T, code: number, message: string):
|
|
|
47
54
|
* const { name } = assertValidation(requestBody, schema.parse);
|
|
48
55
|
* ```
|
|
49
56
|
*/
|
|
50
|
-
export declare function assertValidation<T>(body:
|
|
57
|
+
export declare function assertValidation<T, Input = unknown>(body: Input, validator: (body: Input) => T, errorFunc?: (err: unknown) => unknown, code?: number): T;
|
package/dist/index.js
CHANGED
|
@@ -54,6 +54,13 @@ function assert(condition, code, message) {
|
|
|
54
54
|
* The result of this error handler will be passed directly as the body of the HTTPResult.
|
|
55
55
|
* If no error handler is given, assertValidation will resort to calling the error's toString() method if possible.
|
|
56
56
|
*
|
|
57
|
+
* The validator receives the body at the type of the argument you pass (`Input`, inferred from `body`;
|
|
58
|
+
* `unknown` when you give an explicit `T` only). A validator that accepts a wider type, such as
|
|
59
|
+
* `schema.parse`, always fits; one that accepts a narrower type than the body is rejected at compile time,
|
|
60
|
+
* except when the body is typed `any`, which fits every validator.
|
|
61
|
+
*
|
|
62
|
+
* @typeParam T Type of the validated result
|
|
63
|
+
* @typeParam Input Type of the body; the validator receives it at this type
|
|
57
64
|
* @param body Input to validate
|
|
58
65
|
* @param validator Validator function
|
|
59
66
|
* @param errorFunc Error handler
|
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;AAkCD,4CAYC;AAhFD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,gBAAgB,CAC9B,IAAW,EACX,SAA6B,EAC7B,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
|
@@ -132,7 +132,7 @@ function nextFreeIndex(meta, key) {
|
|
|
132
132
|
* }
|
|
133
133
|
* ```
|
|
134
134
|
*/
|
|
135
|
-
exports.RateLimit = (0, decorators_1.MakeMethodDecorator)((target, key, _descriptor, limit, windowMs, options) => {
|
|
135
|
+
exports.RateLimit = (0, decorators_1.MakeMethodDecorator)((target, key, _descriptor, ...[limit, windowMs, options]) => {
|
|
136
136
|
const resolvedOptions = options ?? {};
|
|
137
137
|
const meta = getControllerMeta(target);
|
|
138
138
|
assertGuardWiringOrder(meta, key);
|
package/dist/rate-limit.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.captureHTTPResult = captureHTTPResult;
|
|
4
|
+
const interface_api_1 = require("@antelopejs/interface-api");
|
|
5
|
+
function captureHTTPResult(action) {
|
|
6
|
+
try {
|
|
7
|
+
action();
|
|
8
|
+
}
|
|
9
|
+
catch (error) {
|
|
10
|
+
if (error instanceof interface_api_1.HTTPResult) {
|
|
11
|
+
return error;
|
|
12
|
+
}
|
|
13
|
+
throw error;
|
|
14
|
+
}
|
|
15
|
+
throw new Error("Expected the action to throw");
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=capture-http-result.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"capture-http-result.js","sourceRoot":"","sources":["../../src/tests/capture-http-result.ts"],"names":[],"mappings":";;AAEA,8CAUC;AAZD,6DAAuD;AAEvD,SAAgB,iBAAiB,CAAC,MAAkB;IAClD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC;IACX,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,YAAY,0BAAU,EAAE,CAAC;YAChC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;AAClD,CAAC"}
|
package/dist/tests/index.test.js
CHANGED
|
@@ -4,36 +4,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
4
4
|
};
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
6
|
const node_assert_1 = __importDefault(require("node:assert"));
|
|
7
|
-
const
|
|
8
|
-
const
|
|
7
|
+
const __1 = require("..");
|
|
8
|
+
const capture_http_result_1 = require("./capture-http-result");
|
|
9
|
+
class RawPayload {
|
|
10
|
+
name;
|
|
11
|
+
active;
|
|
12
|
+
constructor(name, active) {
|
|
13
|
+
this.name = name;
|
|
14
|
+
this.active = active;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
9
17
|
const BAD_REQUEST_CODE = 400;
|
|
10
18
|
const UNPROCESSABLE_ENTITY_CODE = 422;
|
|
11
19
|
const ASSERTION_ERROR_MESSAGE = "Missing payload";
|
|
12
20
|
const VALIDATION_ERROR_MESSAGE = "Invalid payload";
|
|
13
21
|
const VALIDATION_ERROR_CODE = "VALIDATION_ERROR";
|
|
14
|
-
function
|
|
15
|
-
if (!(
|
|
16
|
-
throw new Error("Expected an HTTPResult error");
|
|
17
|
-
}
|
|
18
|
-
return error;
|
|
19
|
-
}
|
|
20
|
-
function isObjectRecord(value) {
|
|
21
|
-
return typeof value === "object" && value !== null;
|
|
22
|
-
}
|
|
23
|
-
function parsePayload(value) {
|
|
24
|
-
if (!isObjectRecord(value)) {
|
|
25
|
-
throw new Error(VALIDATION_ERROR_MESSAGE);
|
|
26
|
-
}
|
|
27
|
-
const nameValue = value.name;
|
|
28
|
-
const activeValue = value.active;
|
|
29
|
-
if (typeof nameValue !== "string" || typeof activeValue !== "boolean") {
|
|
22
|
+
function parsePayload(body) {
|
|
23
|
+
if (!(body instanceof RawPayload)) {
|
|
30
24
|
throw new Error(VALIDATION_ERROR_MESSAGE);
|
|
31
25
|
}
|
|
32
26
|
return {
|
|
33
|
-
name:
|
|
34
|
-
active:
|
|
27
|
+
name: body.name,
|
|
28
|
+
active: body.active,
|
|
35
29
|
};
|
|
36
30
|
}
|
|
31
|
+
function countBytes(body) {
|
|
32
|
+
return body.length;
|
|
33
|
+
}
|
|
37
34
|
function mapValidationError() {
|
|
38
35
|
return {
|
|
39
36
|
code: VALIDATION_ERROR_CODE,
|
|
@@ -43,51 +40,33 @@ function mapValidationError() {
|
|
|
43
40
|
describe("API Util Interface", () => {
|
|
44
41
|
describe("assert", () => {
|
|
45
42
|
it("returns when the condition is truthy", () => {
|
|
46
|
-
node_assert_1.default.doesNotThrow(() => (0,
|
|
43
|
+
node_assert_1.default.doesNotThrow(() => (0, __1.assert)(true, BAD_REQUEST_CODE, ASSERTION_ERROR_MESSAGE));
|
|
47
44
|
});
|
|
48
45
|
it("throws HTTPResult when the condition is falsy", () => {
|
|
49
|
-
|
|
50
|
-
try {
|
|
51
|
-
(0, interface_api_util_1.assert)(false, BAD_REQUEST_CODE, ASSERTION_ERROR_MESSAGE);
|
|
52
|
-
}
|
|
53
|
-
catch (error) {
|
|
54
|
-
thrownError = error;
|
|
55
|
-
}
|
|
56
|
-
const httpError = toHTTPResult(thrownError);
|
|
46
|
+
const httpError = (0, capture_http_result_1.captureHTTPResult)(() => (0, __1.assert)(false, BAD_REQUEST_CODE, ASSERTION_ERROR_MESSAGE));
|
|
57
47
|
node_assert_1.default.equal(httpError.getStatus(), BAD_REQUEST_CODE);
|
|
58
48
|
node_assert_1.default.equal(httpError.getBody(), ASSERTION_ERROR_MESSAGE);
|
|
59
49
|
});
|
|
60
50
|
});
|
|
61
51
|
describe("assertValidation", () => {
|
|
62
52
|
it("returns parsed payload when validation succeeds", () => {
|
|
63
|
-
const
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
}, parsePayload);
|
|
53
|
+
const input = new RawPayload("antelope", true);
|
|
54
|
+
const payload = (0, __1.assertValidation)(input, parsePayload);
|
|
55
|
+
node_assert_1.default.notEqual(payload, input);
|
|
67
56
|
node_assert_1.default.equal(payload.name, "antelope");
|
|
68
57
|
node_assert_1.default.equal(payload.active, true);
|
|
69
58
|
});
|
|
59
|
+
it("hands the validator a body of the caller's own type", () => {
|
|
60
|
+
const byteCount = (0, __1.assertValidation)(Buffer.from("antelope"), countBytes);
|
|
61
|
+
node_assert_1.default.equal(byteCount, "antelope".length);
|
|
62
|
+
});
|
|
70
63
|
it("throws HTTPResult with default code and serialized error message", () => {
|
|
71
|
-
|
|
72
|
-
try {
|
|
73
|
-
(0, interface_api_util_1.assertValidation)({}, parsePayload);
|
|
74
|
-
}
|
|
75
|
-
catch (error) {
|
|
76
|
-
thrownError = error;
|
|
77
|
-
}
|
|
78
|
-
const httpError = toHTTPResult(thrownError);
|
|
64
|
+
const httpError = (0, capture_http_result_1.captureHTTPResult)(() => (0, __1.assertValidation)({}, parsePayload));
|
|
79
65
|
node_assert_1.default.equal(httpError.getStatus(), BAD_REQUEST_CODE);
|
|
80
66
|
node_assert_1.default.equal(httpError.getBody(), `Error: ${VALIDATION_ERROR_MESSAGE}`);
|
|
81
67
|
});
|
|
82
68
|
it("applies custom error mapper and status code", () => {
|
|
83
|
-
|
|
84
|
-
try {
|
|
85
|
-
(0, interface_api_util_1.assertValidation)({}, parsePayload, mapValidationError, UNPROCESSABLE_ENTITY_CODE);
|
|
86
|
-
}
|
|
87
|
-
catch (error) {
|
|
88
|
-
thrownError = error;
|
|
89
|
-
}
|
|
90
|
-
const httpError = toHTTPResult(thrownError);
|
|
69
|
+
const httpError = (0, capture_http_result_1.captureHTTPResult)(() => (0, __1.assertValidation)({}, parsePayload, mapValidationError, UNPROCESSABLE_ENTITY_CODE));
|
|
91
70
|
node_assert_1.default.equal(httpError.getStatus(), UNPROCESSABLE_ENTITY_CODE);
|
|
92
71
|
node_assert_1.default.equal(httpError.getBody(), JSON.stringify(mapValidationError()));
|
|
93
72
|
});
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":";;;;;AAAA,
|
|
1
|
+
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -13,9 +13,12 @@ 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 node_http_1 = require("node:http");
|
|
17
|
+
const node_net_1 = require("node:net");
|
|
16
18
|
const interface_core_1 = require("@antelopejs/interface-core");
|
|
17
19
|
const interface_api_1 = require("@antelopejs/interface-api");
|
|
18
20
|
const rate_limit_1 = require("../rate-limit");
|
|
21
|
+
const capture_http_result_1 = require("./capture-http-result");
|
|
19
22
|
const TOO_MANY_REQUESTS = 429;
|
|
20
23
|
const LIMIT = 2;
|
|
21
24
|
const WINDOW_MS = 60_000;
|
|
@@ -23,26 +26,24 @@ const RETRY_AFTER_HEADER = "Retry-After";
|
|
|
23
26
|
const RATELIMIT_LIMIT_HEADER = "X-RateLimit-Limit";
|
|
24
27
|
const RATELIMIT_REMAINING_HEADER = "X-RateLimit-Remaining";
|
|
25
28
|
const RATELIMIT_RESET_HEADER = "X-RateLimit-Reset";
|
|
26
|
-
function toHTTPResult(error) {
|
|
27
|
-
if (!(error instanceof interface_api_1.HTTPResult)) {
|
|
28
|
-
throw new Error("Expected an HTTPResult error");
|
|
29
|
-
}
|
|
30
|
-
return error;
|
|
31
|
-
}
|
|
32
29
|
function makeContext(remoteAddress) {
|
|
30
|
+
const socket = new node_net_1.Socket();
|
|
31
|
+
Object.defineProperty(socket, "remoteAddress", { value: remoteAddress });
|
|
32
|
+
const rawRequest = new node_http_1.IncomingMessage(socket);
|
|
33
33
|
return {
|
|
34
|
-
rawRequest
|
|
34
|
+
rawRequest,
|
|
35
|
+
rawResponse: new node_http_1.ServerResponse(rawRequest),
|
|
36
|
+
url: new URL("http://localhost/"),
|
|
37
|
+
routeParameters: {},
|
|
35
38
|
response: new interface_api_1.HTTPResult(),
|
|
36
39
|
};
|
|
37
40
|
}
|
|
38
|
-
function
|
|
39
|
-
|
|
40
|
-
|
|
41
|
+
function handlerDescriptor(controller) {
|
|
42
|
+
const descriptor = Object.getOwnPropertyDescriptor(controller.prototype, "handler");
|
|
43
|
+
if (!descriptor) {
|
|
44
|
+
throw new Error("Expected handler to be a declared method");
|
|
41
45
|
}
|
|
42
|
-
|
|
43
|
-
return error;
|
|
44
|
-
}
|
|
45
|
-
throw new Error("Expected the action to throw");
|
|
46
|
+
return descriptor;
|
|
46
47
|
}
|
|
47
48
|
function guardProvider(controller) {
|
|
48
49
|
const meta = (0, interface_core_1.GetMetadata)(controller, interface_api_1.ControllerMeta);
|
|
@@ -52,7 +53,7 @@ function guardProvider(controller) {
|
|
|
52
53
|
}
|
|
53
54
|
return provider;
|
|
54
55
|
}
|
|
55
|
-
|
|
56
|
+
function describeWindows() {
|
|
56
57
|
describe("hitWindow", () => {
|
|
57
58
|
it("allows up to the limit then denies within the window", () => {
|
|
58
59
|
const store = new Map();
|
|
@@ -101,6 +102,8 @@ describe("RateLimit", () => {
|
|
|
101
102
|
node_assert_1.default.equal(store.has("fresh"), true);
|
|
102
103
|
});
|
|
103
104
|
});
|
|
105
|
+
}
|
|
106
|
+
function describeKeyResolution() {
|
|
104
107
|
describe("resolveKey", () => {
|
|
105
108
|
it("uses the custom key function when provided", () => {
|
|
106
109
|
const options = { key: () => "custom" };
|
|
@@ -117,6 +120,8 @@ describe("RateLimit", () => {
|
|
|
117
120
|
node_assert_1.default.equal((0, rate_limit_1.resolveKey)(makeContext("1.2.3.4"), options), "1.2.3.4");
|
|
118
121
|
});
|
|
119
122
|
});
|
|
123
|
+
}
|
|
124
|
+
function describeDecorator() {
|
|
120
125
|
describe("decorator", () => {
|
|
121
126
|
it("registers a guard provider at the trailing parameter index", () => {
|
|
122
127
|
class Indexed extends (0, interface_api_1.Controller)("rate-limit-index") {
|
|
@@ -124,9 +129,7 @@ describe("RateLimit", () => {
|
|
|
124
129
|
}
|
|
125
130
|
const proto = Indexed.prototype;
|
|
126
131
|
(0, interface_api_1.SetParameterProvider)(proto, "handler", 0, () => "existing");
|
|
127
|
-
(0, rate_limit_1.RateLimit)(LIMIT, WINDOW_MS)(proto, "handler",
|
|
128
|
-
value: proto.handler,
|
|
129
|
-
});
|
|
132
|
+
(0, rate_limit_1.RateLimit)(LIMIT, WINDOW_MS)(proto, "handler", handlerDescriptor(Indexed));
|
|
130
133
|
const meta = (0, interface_core_1.GetMetadata)(Indexed, interface_api_1.ControllerMeta);
|
|
131
134
|
node_assert_1.default.ok(meta.computed_params.handler[1]?.provider);
|
|
132
135
|
});
|
|
@@ -146,7 +149,7 @@ describe("RateLimit", () => {
|
|
|
146
149
|
const context = makeContext("9.9.9.9");
|
|
147
150
|
node_assert_1.default.equal(provider(context), undefined);
|
|
148
151
|
node_assert_1.default.equal(provider(context), undefined);
|
|
149
|
-
const error =
|
|
152
|
+
const error = (0, capture_http_result_1.captureHTTPResult)(() => provider(context));
|
|
150
153
|
const headers = error.getHeaders();
|
|
151
154
|
const retryAfter = Number(headers[RETRY_AFTER_HEADER]);
|
|
152
155
|
node_assert_1.default.equal(error.getStatus(), TOO_MANY_REQUESTS);
|
|
@@ -193,10 +196,15 @@ describe("RateLimit", () => {
|
|
|
193
196
|
handler() { }
|
|
194
197
|
}
|
|
195
198
|
const proto = Misordered.prototype;
|
|
196
|
-
const descriptor =
|
|
199
|
+
const descriptor = handlerDescriptor(Misordered);
|
|
197
200
|
(0, interface_api_1.Get)()(proto, "handler", descriptor);
|
|
198
201
|
node_assert_1.default.throws(() => (0, rate_limit_1.RateLimit)(LIMIT, WINDOW_MS)(proto, "handler", descriptor), /directly beneath/);
|
|
199
202
|
});
|
|
200
203
|
});
|
|
204
|
+
}
|
|
205
|
+
describe("RateLimit", () => {
|
|
206
|
+
describeWindows();
|
|
207
|
+
describeKeyResolution();
|
|
208
|
+
describeDecorator();
|
|
201
209
|
});
|
|
202
210
|
//# sourceMappingURL=rate-limit.test.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"rate-limit.test.js","sourceRoot":"","sources":["../../src/tests/rate-limit.test.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAAA,
|
|
1
|
+
{"version":3,"file":"rate-limit.test.js","sourceRoot":"","sources":["../../src/tests/rate-limit.test.ts"],"names":[],"mappings":"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"}
|
package/docs/1.introduction.md
CHANGED
|
@@ -1,17 +1,52 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Validate and throttle API requests
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
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
6
|
|
|
7
|
+
## Choose a guard
|
|
8
|
+
|
|
9
|
+
| Task | Use | Failure behavior |
|
|
10
|
+
| -------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
|
|
11
|
+
| Require a resource or permission | [`assert`](#assert) | A falsy condition throws the status and message you supply. |
|
|
12
|
+
| Parse an untrusted request body | [`assertValidation`](#assertvalidation) | A synchronous validation error becomes an HTTP error; the default status is 400. |
|
|
13
|
+
| Limit repeated calls | [`RateLimit`](#ratelimit) | Requests above the fixed-window limit receive 429 before the handler runs. |
|
|
14
|
+
|
|
15
|
+
These guards complement one another. Throttling does not authenticate a caller, and a TypeScript body annotation does not validate incoming JSON.
|
|
16
|
+
|
|
7
17
|
## Getting Started
|
|
8
18
|
|
|
9
19
|
Install the package in your project:
|
|
10
20
|
|
|
11
21
|
```bash
|
|
12
|
-
|
|
22
|
+
pnpm add @antelopejs/interface-api-util
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Use the utilities in an existing AntelopeJS API controller. The `findUser`, `findPost`, `removePost`, and `saveUser` functions below stand for your application's persistence functions; they are not exports of this package. The Zod examples also require `zod` in your project.
|
|
26
|
+
|
|
27
|
+
## Reject a bad request
|
|
28
|
+
|
|
29
|
+
This endpoint accepts a non-empty `name` query parameter. With the API provider listening, `GET /greet?name=Ada` returns a greeting; `GET /greet` or `GET /greet?name=` returns HTTP 400. No database or validation library is needed for this example.
|
|
30
|
+
|
|
31
|
+
```ts docs-check
|
|
32
|
+
import { Controller, Get, Parameter } from "@antelopejs/interface-api";
|
|
33
|
+
import { assert } from "@antelopejs/interface-api-util";
|
|
34
|
+
|
|
35
|
+
class GreetingController extends Controller("/greet") {
|
|
36
|
+
@Get("")
|
|
37
|
+
greet(@Parameter("name", "query") name: string | true | undefined) {
|
|
38
|
+
assert(
|
|
39
|
+
typeof name === "string" && name.trim().length > 0,
|
|
40
|
+
400,
|
|
41
|
+
"Name is required",
|
|
42
|
+
);
|
|
43
|
+
return { message: `Hello, ${name}!` };
|
|
44
|
+
}
|
|
45
|
+
}
|
|
13
46
|
```
|
|
14
47
|
|
|
48
|
+
Use `assert` for a condition you can state directly, `assertValidation` for a schema parser, and `RateLimit` to bound repeated requests. The reference below covers each independently.
|
|
49
|
+
|
|
15
50
|
## `assert`
|
|
16
51
|
|
|
17
52
|
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.
|
|
@@ -72,9 +107,9 @@ async function deletePost(postId: string, currentUserId: string) {
|
|
|
72
107
|
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
108
|
|
|
74
109
|
```typescript
|
|
75
|
-
function assertValidation<T>(
|
|
76
|
-
body:
|
|
77
|
-
validator: (body:
|
|
110
|
+
function assertValidation<T, Input = unknown>(
|
|
111
|
+
body: Input,
|
|
112
|
+
validator: (body: Input) => T,
|
|
78
113
|
errorFunc?: (err: unknown) => unknown,
|
|
79
114
|
code?: number,
|
|
80
115
|
): T;
|
|
@@ -82,11 +117,35 @@ function assertValidation<T>(
|
|
|
82
117
|
|
|
83
118
|
| Parameter | Type | Default | Description |
|
|
84
119
|
| ----------- | --------------------------- | ------- | ------------------------------------------------------- |
|
|
85
|
-
| `body` | `
|
|
86
|
-
| `validator` | `(body:
|
|
120
|
+
| `body` | `Input` | | The input value to validate |
|
|
121
|
+
| `validator` | `(body: Input) => T` | | A function that returns the validated value or throws |
|
|
87
122
|
| `errorFunc` | `(err: unknown) => unknown` | | Optional error transformer for customizing the response |
|
|
88
123
|
| `code` | `number` | `400` | HTTP status code for the error response |
|
|
89
124
|
|
|
125
|
+
`Input` is inferred from `body` and has no constraint; it defaults to `unknown` when you write only `assertValidation<T>(...)`. The validator receives the body at that type, so a body typed `Buffer` reaches a `(body: Buffer) => T` validator without a cast. A validator that accepts a wider type, such as Zod's `parse(data: unknown)`, always fits. A validator that accepts a narrower type than the body does not compile: a `string | Buffer` body is rejected by a `(body: string) => T` validator. The exception is a body typed `any`, which fits every validator, so the validator's declared type is then unchecked. When the validator's parameter is unannotated, a literal body such as `"lit"` gives it the widened type `string`.
|
|
126
|
+
|
|
127
|
+
```ts docs-check
|
|
128
|
+
import { Controller, Post, RawBody } from "@antelopejs/interface-api";
|
|
129
|
+
import { assertValidation } from "@antelopejs/interface-api-util";
|
|
130
|
+
|
|
131
|
+
function parseJsonObject(body: Buffer): Record<string, string> {
|
|
132
|
+
const parsed: unknown = JSON.parse(body.toString());
|
|
133
|
+
if (typeof parsed !== "object" || parsed === null) {
|
|
134
|
+
throw new Error("Expected a JSON object");
|
|
135
|
+
}
|
|
136
|
+
return Object.fromEntries(
|
|
137
|
+
Object.entries(parsed).map(([key, value]) => [key, String(value)]),
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
class ImportController extends Controller("import") {
|
|
142
|
+
@Post("")
|
|
143
|
+
create(@RawBody() body: Buffer) {
|
|
144
|
+
return assertValidation(body, parseJsonObject);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
90
149
|
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
150
|
|
|
92
151
|
### Validate with Zod
|
|
@@ -135,7 +194,9 @@ function validateAge(requestBody: unknown) {
|
|
|
135
194
|
|
|
136
195
|
## `RateLimit`
|
|
137
196
|
|
|
138
|
-
|
|
197
|
+
`@RateLimit` counts requests per key, per decorated handler, in a fixed time window held in process memory. A key's window starts with its first request; it is not aligned to the clock minute. Once the count exceeds `limit` within `windowMs`, the guard throws an `HTTPResult` with status `429` and a `Retry-After` header before the handler runs.
|
|
198
|
+
|
|
199
|
+
Allowed requests add `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` to `context.response`; rejected requests carry them on the thrown response. `Reset` is a UNIX timestamp in seconds, while `Retry-After` is a delay in seconds. If a handler replaces the response with a new `HTTPResult`, header preservation depends on the API provider; retain the context response when you need those headers.
|
|
139
200
|
|
|
140
201
|
```typescript
|
|
141
202
|
function RateLimit(
|
|
@@ -166,17 +227,25 @@ By default, requests are counted per client IP (`context.rawRequest.socket.remot
|
|
|
166
227
|
|
|
167
228
|
```typescript
|
|
168
229
|
import { RateLimit } from "@antelopejs/interface-api-util";
|
|
169
|
-
import {
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
230
|
+
import {
|
|
231
|
+
Controller,
|
|
232
|
+
Get,
|
|
233
|
+
Context,
|
|
234
|
+
RequestContext,
|
|
235
|
+
} from "@antelopejs/interface-api";
|
|
236
|
+
|
|
237
|
+
class UsersController extends Controller("/users") {
|
|
238
|
+
@Get("")
|
|
173
239
|
@RateLimit(100, 60_000)
|
|
174
|
-
list() {
|
|
175
|
-
|
|
240
|
+
list(@Context() context: RequestContext) {
|
|
241
|
+
context.response.setBody({ users: [] });
|
|
242
|
+
return context.response;
|
|
176
243
|
}
|
|
177
244
|
}
|
|
178
245
|
```
|
|
179
246
|
|
|
247
|
+
Requests 1–100 from one IP are allowed within its 60-second window; request 101 receives 429. Another decorated handler has a separate counter, even for the same IP.
|
|
248
|
+
|
|
180
249
|
### Limit by a custom key
|
|
181
250
|
|
|
182
251
|
```ts docs-check
|
|
@@ -195,4 +264,14 @@ class AuthController extends Controller("auth") {
|
|
|
195
264
|
}
|
|
196
265
|
```
|
|
197
266
|
|
|
198
|
-
|
|
267
|
+
### Choose a deployment strategy
|
|
268
|
+
|
|
269
|
+
| Deployment | What the limiter counts | What to do |
|
|
270
|
+
| --------------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
|
|
271
|
+
| One process, direct clients | Requests per socket IP by default | Use the default key when an IP is the intended identity. |
|
|
272
|
+
| Behind a reverse proxy | The proxy's socket IP by default | Supply a key derived from a trusted proxy hop or an authenticated identity. |
|
|
273
|
+
| Multiple instances | Independent counters in each process | Enforce a shared limit at the edge or in a shared store. |
|
|
274
|
+
|
|
275
|
+
Counters reset on process restart. Elapsed windows are pruned periodically, bounding the store by distinct keys seen within an active window rather than retaining keys forever.
|
|
276
|
+
|
|
277
|
+
Never trust a raw client-supplied `X-Forwarded-For` as identity: clients can spoof it to evade limits or create many keys. A stable custom key does not make the in-memory counter distributed.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-api-util",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "AntelopeJS helpers for API handlers: request assertions, input validation and rate limiting",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -45,17 +45,28 @@
|
|
|
45
45
|
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
46
46
|
"test": "pnpm run build && ajs module test .",
|
|
47
47
|
"format:check": "oxfmt --check .",
|
|
48
|
-
"knip": "knip"
|
|
48
|
+
"knip": "knip",
|
|
49
|
+
"prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
|
|
50
|
+
"checks": "antelopejs-checks",
|
|
51
|
+
"size": "antelopejs-check-size",
|
|
52
|
+
"ratchet": "antelopejs-ratchet",
|
|
53
|
+
"sync": "antelopejs-sync",
|
|
54
|
+
"ratchet:update": "antelopejs-ratchet --update",
|
|
55
|
+
"sync:check": "antelopejs-sync --check",
|
|
56
|
+
"typecheck": "tsc --noEmit",
|
|
57
|
+
"suppressions": "antelopejs-suppressions",
|
|
58
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
49
59
|
},
|
|
50
60
|
"devDependencies": {
|
|
51
61
|
"@antelopejs/core": "^1.16.0",
|
|
52
62
|
"@antelopejs/interface-api": "^0.0.15",
|
|
53
63
|
"@antelopejs/interface-core": "^0.2.4",
|
|
54
|
-
"@antelopejs/tooling-configs": "^0.
|
|
64
|
+
"@antelopejs/tooling-configs": "^0.2.11",
|
|
55
65
|
"@types/mocha": "^10.0.10",
|
|
56
66
|
"@types/node": "^22.19.15",
|
|
57
67
|
"eslint-plugin-perfectionist": "^5.11.0",
|
|
58
68
|
"knip": "^6.34.0",
|
|
69
|
+
"lefthook": "^2.2.2",
|
|
59
70
|
"oxfmt": "^0.66.0",
|
|
60
71
|
"oxlint": "1.81.0",
|
|
61
72
|
"oxlint-tsgolint": "^7.0.2001",
|
|
@@ -64,7 +64,7 @@ class MembersController extends Controller("members") {
|
|
|
64
64
|
@Post()
|
|
65
65
|
async create(@RawBody() body: Buffer) {
|
|
66
66
|
const { fullName, email } = assertValidation(body, (b) =>
|
|
67
|
-
createMemberSchema.parse(JSON.parse(
|
|
67
|
+
createMemberSchema.parse(JSON.parse(b.toString())),
|
|
68
68
|
);
|
|
69
69
|
return new HTTPResult(201, await saveMember({ fullName, email }));
|
|
70
70
|
}
|
|
@@ -73,9 +73,11 @@ class MembersController extends Controller("members") {
|
|
|
73
73
|
|
|
74
74
|
- `assert(condition, code, message)` — throws `new HTTPResult(code, message)` when falsy; uses
|
|
75
75
|
TypeScript `asserts condition`, so the compiler narrows after the call.
|
|
76
|
-
- `assertValidation(body, validator, errorFunc?, code = 400)` — returns the
|
|
77
|
-
if the validator throws, rethrows an `HTTPResult` whose body is
|
|
78
|
-
otherwise `String(err)`.
|
|
76
|
+
- `assertValidation<T, Input = unknown>(body, validator, errorFunc?, code = 400)` — returns the
|
|
77
|
+
validator's result; if the validator throws, rethrows an `HTTPResult` whose body is
|
|
78
|
+
`errorFunc(err)` if provided, otherwise `String(err)`. `Input` is the type of `body`, and the
|
|
79
|
+
validator receives it at that type (a `Buffer` body needs no cast). A validator taking a wider
|
|
80
|
+
type (`schema.parse`) fits; one taking a narrower type than the body is a compile error, unless the body is typed `any`.
|
|
79
81
|
- `RateLimit(limit, windowMs, options?)` — fixed-window counter per key; over-limit requests throw
|
|
80
82
|
a 429 `HTTPResult` (with `Retry-After`) before the handler runs. Successful responses get
|
|
81
83
|
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (epoch seconds) headers.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"cases": [
|
|
4
|
+
{
|
|
5
|
+
"id": "api-util-interface-validate-body",
|
|
6
|
+
"area": "framework",
|
|
7
|
+
"style": "clean",
|
|
8
|
+
"prompt": "In a POST handler I receive the raw request body as a Buffer. How do I validate it with a Zod schema and return a 400 when it is invalid?",
|
|
9
|
+
"expect": {
|
|
10
|
+
"skills": ["api-util-interface"],
|
|
11
|
+
"acceptable": ["api-interface", "ajs-consume-interface", "antelopejs"],
|
|
12
|
+
"mustMention": ["assertValidation"]
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"id": "api-util-interface-not-found-casual",
|
|
17
|
+
"area": "framework",
|
|
18
|
+
"style": "casual",
|
|
19
|
+
"prompt": "how do i send a 404 from my controller when the record does not exist",
|
|
20
|
+
"expect": {
|
|
21
|
+
"skills": ["api-util-interface"],
|
|
22
|
+
"acceptable": ["api-interface", "ajs-consume-interface", "antelopejs"],
|
|
23
|
+
"mustMention": ["assert"]
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"id": "api-util-interface-rate-limit",
|
|
28
|
+
"area": "framework",
|
|
29
|
+
"style": "clean",
|
|
30
|
+
"prompt": "Limit my login route to 5 attempts per minute per client and answer 429 beyond that.",
|
|
31
|
+
"expect": {
|
|
32
|
+
"skills": ["api-util-interface"],
|
|
33
|
+
"acceptable": ["api-interface", "ajs-consume-interface", "antelopejs"],
|
|
34
|
+
"mustMention": ["RateLimit"]
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"id": "api-util-interface-rate-limit-ignored-casual",
|
|
39
|
+
"area": "framework",
|
|
40
|
+
"style": "casual",
|
|
41
|
+
"prompt": "my rate limit decorator does nothing and startup throws an error about ordering",
|
|
42
|
+
"expect": {
|
|
43
|
+
"skills": ["api-util-interface"],
|
|
44
|
+
"acceptable": ["api-interface", "antelopejs"],
|
|
45
|
+
"mustMention": ["RateLimit", "beneath"]
|
|
46
|
+
}
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
"id": "api-util-interface-controller-neighbour",
|
|
50
|
+
"area": "framework",
|
|
51
|
+
"style": "clean",
|
|
52
|
+
"prompt": "Add a GET endpoint with a prefix handler that runs before every route in my controller.",
|
|
53
|
+
"expect": {
|
|
54
|
+
"skills": ["api-interface"],
|
|
55
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
56
|
+
"avoid": ["api-util-interface"]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
]
|
|
60
|
+
}
|