@rapidrest/service-core 2.4.0 → 2.5.1

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.
@@ -67,6 +67,12 @@ export declare class UWSResponse implements HttpResponse {
67
67
  private _abortHandlers;
68
68
  private _finished;
69
69
  private _finishHandlers;
70
+ /** True while uWS reports backpressure from a `write()` that has not yet drained. */
71
+ private _needDrain;
72
+ /** Whether the single uWS `onWritable` slot has been claimed by this response yet. */
73
+ private _writableHooked;
74
+ private _drainHandlers;
75
+ private _drainWaiters;
70
76
  /** Set to true for HEAD requests — body bytes must not be sent. */
71
77
  isHead: boolean;
72
78
  /** Intermediate result passed between middleware. */
@@ -91,6 +97,13 @@ export declare class UWSResponse implements HttpResponse {
91
97
  get statusCode(): number;
92
98
  get headersSent(): boolean;
93
99
  get writableEnded(): boolean;
100
+ /** `true` once the client has aborted the connection. A producer should stop writing and release its resources. */
101
+ get aborted(): boolean;
102
+ /**
103
+ * `true` while a previous `write()` returned `false` and the buffered data has not drained yet (the equivalent
104
+ * of Node's `Writable.writableNeedDrain`). Wait with `waitForDrain()` or `onDrain()` before writing more.
105
+ */
106
+ get writableNeedDrain(): boolean;
94
107
  status(code: number): this;
95
108
  setHeader(key: string, value: string | number | string[]): this;
96
109
  appendHeader(key: string, value: string | number): this;
@@ -104,6 +117,8 @@ export declare class UWSResponse implements HttpResponse {
104
117
  * acts on the first call.
105
118
  */
106
119
  flushHeaders(): void;
120
+ /** Writes the status line and buffered headers. Must be called from within a cork. */
121
+ private _writeHead;
107
122
  /**
108
123
  * Writes all buffered headers to the wire, skipping content-length (uWS sets it
109
124
  * automatically via end(data)/endWithoutBody(n)). Headers with multiple values (e.g. one
@@ -112,10 +127,39 @@ export declare class UWSResponse implements HttpResponse {
112
127
  */
113
128
  private _writeHeaders;
114
129
  /**
115
- * Writes a chunk to the response without ending it (streaming / SSE).
116
- * Flushes headers on the first call if they haven't been sent yet.
130
+ * Writes a chunk to the response without ending it (streaming / SSE), corked so it is safe from any async
131
+ * context. Flushes headers on the first call if they haven't been sent yet.
132
+ *
133
+ * Mirrors Node's `Writable.write()`: returns `true` when the data was sent (or buffered below the limit) and
134
+ * `false` when uWS's buffer is now full. The chunk is still accepted in that case, but the caller should stop
135
+ * writing until `waitForDrain()` resolves (or an `onDrain()` callback fires). Also returns `false`, and writes
136
+ * nothing, once the response has ended or the client aborted (see `aborted`).
137
+ */
138
+ write(data: string | Buffer): boolean;
139
+ /**
140
+ * Registers a callback fired every time the buffered data of a backpressured `write()` has drained and it is safe
141
+ * to write again (the equivalent of Node's `'drain'` event). It is never called after the response has ended or
142
+ * aborted.
143
+ */
144
+ onDrain(callback: () => void): void;
145
+ /**
146
+ * Resolves once it is safe to write again, so a producer can honour backpressure:
147
+ *
148
+ * ```ts
149
+ * for (const chunk of chunks) {
150
+ * if (!res.write(chunk) && !(await res.waitForDrain())) return; // client went away
151
+ * }
152
+ * res.end();
153
+ * ```
154
+ *
155
+ * Resolves `true` immediately when there is no pending backpressure, `true` when the data drains, and `false` when
156
+ * the client aborts or the response ends while waiting, meaning the producer must stop. It never stays pending
157
+ * for a connection that can no longer drain.
117
158
  */
118
- write(data: string | Buffer): void;
159
+ waitForDrain(): Promise<boolean>;
160
+ /** Claims uWS's single `onWritable` slot (once) to learn when a backpressured `write()` has drained. */
161
+ private _hookWritable;
162
+ private _settleDrainWaiters;
119
163
  /**
120
164
  * Registers a callback to run when the client aborts the connection.
121
165
  * Safe to call multiple times — all registered callbacks are invoked on abort.
@@ -2,6 +2,7 @@ import { type JWTUser } from "@rapidrest/core";
2
2
  import type { RedisClientType } from "redis";
3
3
  import Transport from "winston-transport";
4
4
  import { type IWebSocketShim } from "../http/IWebSocketShim.js";
5
+ import type { HttpResponse } from "../http/types.js";
5
6
  /**
6
7
  * Implements a Winston transport that pipes incoming log messages to a configured redis pubsub channel.
7
8
  */
@@ -20,10 +21,15 @@ export declare class RedisTransport extends Transport {
20
21
  *
21
22
  * | Name | HTTP Method | What it does |
22
23
  * | --- | --- | --- |
23
- * | `clearCache` | `GET /<base_path>/clear-cache` | Clears the Redis-based cache system. |
24
+ * | `clearCache` | `POST /<base_path>/clear-cache` | Clears the Redis-based cache system. |
24
25
  * | `logs` | `UPGRADE /<base_path>/logs` | Live tail the service logs |
25
26
  * | `getReleaseNotes` | `GET /<base_path>/release-notes` | Retrieve the server release notes. |
26
- * | `restart` | `GET /<base_path>/restart` | ` Restart the server |
27
+ * | `restart` | `POST /<base_path>/restart` | Restart the server |
28
+ *
29
+ * `clear-cache` and `restart` change server state, so they are `POST` only (and therefore CSRF-checked) and require a
30
+ * recent elevation: the user's most recent elevation must be no older than the `admin:elevation_max_age` config value
31
+ * in seconds (default `600`). The former `GET` variants of both paths are no longer served and answer `405 Method Not
32
+ * Allowed` (with an `Allow: POST` header) without performing any action.
27
33
  *
28
34
  * !!Note!! that the `BaseAdminRoute` is not automatically registered with a server by default. You must create
29
35
  * your own class that extends `AdminRoute` and apply the desired base path with `@Route()`.
@@ -59,7 +65,14 @@ export declare class BaseAdminRoute {
59
65
  protected trustedRoles: string[];
60
66
  protected init(): Promise<void>;
61
67
  clearCache(user?: JWTUser): Promise<void>;
68
+ clearCacheMovedToPost(res: HttpResponse): void;
62
69
  logs(socket: IWebSocketShim, user: JWTUser): Promise<void>;
63
70
  getReleaseNotes(user?: JWTUser): string | undefined;
71
+ restartMovedToPost(res: HttpResponse): void;
64
72
  restart(user?: JWTUser): void;
73
+ /**
74
+ * Throws the `405 Method Not Allowed` returned by the retired `GET` variants of state-changing admin endpoints,
75
+ * naming the replacement so a stale caller fails loudly instead of silently doing nothing.
76
+ */
77
+ private static rejectGet;
65
78
  }
@@ -1,6 +1,6 @@
1
1
  import type { HttpRequest, RequestHandler } from "../http/types.js";
2
2
  import { RateLimiter } from "../RateLimiter.js";
3
- import { RateLimitOptions, WebSocketRouteOptions } from "../decorators/RouteDecorators.js";
3
+ import { ElevationWindow, RateLimitOptions, WebSocketRouteOptions } from "../decorators/RouteDecorators.js";
4
4
  /**
5
5
  * Provides a set of utilities for converting Route classes to HTTP middleware.
6
6
  *
@@ -12,15 +12,37 @@ export declare class RouteUtils {
12
12
  private authMiddleware?;
13
13
  private logger?;
14
14
  protected rateLimiter?: RateLimiter;
15
+ protected config?: any;
15
16
  protected trustedRoles: string[];
16
17
  protected trustedProxies: string[];
17
18
  protected csrfConfig: any;
18
19
  protected corsConfig: any;
20
+ protected wsConfig: any;
19
21
  /**
20
22
  * Creates a middleware function that checks if the user has elevated privileges and if not
21
23
  * throws the `AUTH_REQUIRES_ELEVATION` error.
22
24
  */
23
- checkElevation(lastStart?: number): RequestHandler;
25
+ checkElevation(window?: number | ElevationWindow): RequestHandler;
26
+ /**
27
+ * Decides whether a WebSocket upgrade request may proceed, based on its `Origin` header. Browsers attach the
28
+ * visitor's cookies to a WebSocket handshake for ANY page, and a sibling subdomain (or the apex) is same-site, so
29
+ * `SameSite` cookies do not stop it: without this check a page on any such host could open an authenticated
30
+ * socket in the victim's browser (cross-site WebSocket hijacking). Browsers always send `Origin` on a handshake and
31
+ * a page cannot forge it, so it is the one reliable signal.
32
+ *
33
+ * The upgrade is allowed when:
34
+ * - the check is disabled with `websocket:checkOrigin: false`; or
35
+ * - there is no `Origin` header (a non-browser client, which has no ambient cookies to abuse); or
36
+ * - the origin's host is the host the request was addressed to (same origin); or
37
+ * - the origin exactly matches an entry of `websocket:allowedOrigins`, or, when that is not set, of `cors:origins`.
38
+ *
39
+ * A `"*"` entry from `cors:origins` is NOT honoured (that setting means "any origin, without credentials", the
40
+ * opposite of what is safe here); `"*"` in `websocket:allowedOrigins` explicitly allows any.
41
+ *
42
+ * Same-origin compares host and port only, not scheme, because TLS is commonly terminated by a proxy in front
43
+ * of the service. If a proxy rewrites `Host`, list the public origin in `websocket:allowedOrigins`.
44
+ */
45
+ checkWebSocketOrigin(req: HttpRequest): boolean;
24
46
  /**
25
47
  * Creates a middleware function that enforces CSRF protection for a state-changing request whose only
26
48
  * credential came from the `jwt` cookie (`req.auth?.source === "cookie"`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rapidrest/service-core",
3
- "version": "2.4.0",
3
+ "version": "2.5.1",
4
4
  "description": "Provides all core functionality for RapidREST based backend services.",
5
5
  "repository": "https://github.com/rapidrest/service-core.git",
6
6
  "author": "RapidREST <rapidrests@gmail.com>",
@@ -24,18 +24,18 @@
24
24
  "release": "rapidrest release"
25
25
  },
26
26
  "dependencies": {
27
- "axios": "^1.20.0",
27
+ "axios": "^1.21.0",
28
28
  "dayjs": "^1.11.23",
29
29
  "deepmerge": "^4.3.1",
30
- "node-schedule": "^2.1.1",
30
+ "node-schedule": "^2.1.2",
31
31
  "winston-transport": "^4.9.0",
32
- "ws": "^8.21.3"
32
+ "ws": "^8.22.1"
33
33
  },
34
34
  "optionalDependencies": {
35
35
  "uWebSockets.js": "uNetworking/uWebSockets.js#v20.69.0"
36
36
  },
37
37
  "peerDependencies": {
38
- "@rapidrest/core": "5.x",
38
+ "@rapidrest/core": "6.x",
39
39
  "lodash-es": "4.x",
40
40
  "mongodb": "^7.0.0",
41
41
  "openapi3-ts": "4.x",
@@ -58,53 +58,53 @@
58
58
  }
59
59
  },
60
60
  "devDependencies": {
61
- "@rapidrest/cli": "^1.0.1",
62
- "@rapidrest/core": "^6.0.0",
63
- "@simplewebauthn/server": "^14.0.1",
64
- "@swc/core": "^1.16.2",
61
+ "@rapidrest/cli": "^2.1.0",
62
+ "@rapidrest/core": "^6.1.0",
63
+ "@simplewebauthn/server": "^14.0.3",
64
+ "@swc/core": "^1.16.21",
65
65
  "@types/better-sqlite3": "^9.6.0",
66
- "@types/bun": "^1.4.2",
67
- "@types/node": "^26.5.0",
66
+ "@types/bun": "^1.4.4",
67
+ "@types/node": "^26.6.6",
68
68
  "@types/node-schedule": "^2.1.8",
69
69
  "@types/rimraf": "^4.0.5",
70
70
  "@types/semver": "^7.8.0",
71
71
  "@types/speakeasy": "^2.0.10",
72
72
  "@types/uuid": "^11.0.0",
73
- "@types/ws": "^8.18.1",
74
- "@typescript-eslint/eslint-plugin": "^8.70.0",
75
- "@typescript-eslint/parser": "^8.70.0",
76
- "@vitest/coverage-v8": "^5.0.0",
73
+ "@types/ws": "^8.18.2",
74
+ "@typescript-eslint/eslint-plugin": "^8.72.1",
75
+ "@typescript-eslint/parser": "^8.72.1",
76
+ "@vitest/coverage-v8": "^5.1.0",
77
77
  "autocannon": "^8.0.0",
78
78
  "better-sqlite3": "^13.0.3",
79
- "eslint": "^10.10.0",
79
+ "eslint": "^10.14.0",
80
80
  "eslint-config-prettier": "^10.1.8",
81
81
  "eslint-plugin-import": "^2.32.0",
82
- "eslint-plugin-jsdoc": "^64.3.6",
83
- "globals": "^17.12.0",
82
+ "eslint-plugin-jsdoc": "^65.4.3",
83
+ "globals": "^17.14.0",
84
84
  "lodash-es": "^4.18.1",
85
- "mongodb": "^7.6.0",
86
- "mongodb-memory-server": "^11.2.0",
85
+ "mongodb": "^7.8.0",
86
+ "mongodb-memory-server": "^11.3.0",
87
87
  "nconf": "^0.13.0",
88
- "nock": "^14.0.17",
89
- "openapi3-ts": "^4.6.1",
90
- "pg": "^8.23.0",
88
+ "nock": "^15.0.5",
89
+ "openapi3-ts": "^4.6.2",
90
+ "pg": "^8.23.1",
91
91
  "prom-client": "^15.1.3",
92
- "redis": "^6.2.1",
92
+ "redis": "^6.3.1",
93
93
  "reflect-metadata": "^0.2.2",
94
- "rimraf": "^6.1.3",
95
- "semver": "^7.8.5",
94
+ "rimraf": "^6.1.4",
95
+ "semver": "^7.8.6",
96
96
  "ts-node": "^10.9.2",
97
- "tsx": "^4.23.13",
97
+ "tsx": "^4.23.15",
98
98
  "typedoc": "^0.28.20",
99
- "typedoc-plugin-markdown": "^4.13.0",
100
- "typeorm": "^1.1.1",
99
+ "typedoc-plugin-markdown": "^4.14.1",
100
+ "typeorm": "^1.1.2",
101
101
  "typescript": "^6.0.3",
102
- "unplugin-swc": "^1.6.0",
103
- "uuid": "^14.0.2",
104
- "vite": "^8.2.2",
105
- "vitest": "^5.0.0",
102
+ "unplugin-swc": "^2.0.0",
103
+ "uuid": "^14.0.3",
104
+ "vite": "^8.3.5",
105
+ "vitest": "^5.1.0",
106
106
  "winston": "^3.19.0",
107
- "ws": "^8.21.3"
107
+ "ws": "^8.22.1"
108
108
  },
109
109
  "resolutions": {
110
110
  "cross-spawn": "^7.0.5",