@morojs/engine 1.1.3 → 1.1.5

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 CHANGED
@@ -65,10 +65,10 @@ optional-dependency lockfile bug ([npm/cli#4828](https://github.com/npm/cli/issu
65
65
  | `@morojs/engine-linux-arm64-gnu` | linux | arm64 | glibc |
66
66
  | `@morojs/engine-linux-x64-musl` | linux | x64 | musl |
67
67
  | `@morojs/engine-linux-arm64-musl` | linux | arm64 | musl |
68
+ | `@morojs/engine-win32-x64` | win32 | x64 | - |
68
69
 
69
70
  Node ABIs: 115/127/131/137/141/147 (Node 20/22/23/24/25/26). Any other
70
- platform/ABI (including Windows, until an MSVC build lands) falls back to
71
- Node's `http` server via MoroJS.
71
+ platform/ABI falls back to Node's `http` server via MoroJS.
72
72
 
73
73
  ## License
74
74
 
package/index.d.ts CHANGED
@@ -1,5 +1,12 @@
1
1
  // Type definitions for @morojs/engine.
2
2
  // The Moro-shaped native HTTP/1.1 + WebSocket binding (see docs/API.md).
3
+ //
4
+ // DRIFT CHECK (maintainers): this surface must stay in lockstep with what the
5
+ // native binding actually parses (src/binding.cpp) and with docs/API.md. When a
6
+ // serve() option or capability flag is added there, add it here in the same
7
+ // change. TODO: wire a release-time gate (tools/) that diffs the getNum/getStr
8
+ // option names + setCap flags in src/binding.cpp against ServeOptions /
9
+ // EngineCapabilities here and fails the release on drift.
3
10
 
4
11
  export interface EngineCapabilities {
5
12
  /** The full serve() limit surface (maxHeadSize/maxHeaders/wsMaxMessageSize/
@@ -12,6 +19,12 @@ export interface EngineCapabilities {
12
19
  http2: boolean;
13
20
  /** WebSocket permessage-deflate (RFC 7692) via ServeOptions.wsDeflate. */
14
21
  wsDeflate: boolean;
22
+ /** The response-side / target-size hardening options are parsed:
23
+ * ServeOptions.responseTimeoutMs, responseBackpressureLimit, and maxUriSize. */
24
+ responseLimits: boolean;
25
+ /** Explicit TLS cipher/group policy is parsed:
26
+ * ServeOptions.ssl.ciphers, ciphersuites, and ecdhCurve. */
27
+ tlsPolicy: boolean;
15
28
  }
16
29
 
17
30
  export interface EngineProbeResult {
@@ -38,9 +51,17 @@ export interface ServeCallbacks {
38
51
  onAborted(reqId: number): void;
39
52
  /** A backpressured write() drained; safe to write more. */
40
53
  onWritable(reqId: number): void;
41
- /** WebSocket opened after a successful Upgrade. */
54
+ /** WebSocket opened after a successful Upgrade.
55
+ * DELIVERY GUARANTEE: onWsOpen is invoked SYNCHRONOUSLY, re-entrantly, during
56
+ * the upgradeToWebSocket() call that returns the wsId — it has already fired
57
+ * by the time upgradeToWebSocket() returns. Register per-socket state here
58
+ * before that return, since inbound frames may arrive immediately after. */
42
59
  onWsOpen?(wsId: number, path: string): void;
43
- /** WebSocket message (text -> string, binary -> ArrayBuffer). */
60
+ /** WebSocket message (text -> string, binary -> ArrayBuffer).
61
+ * Frames the client sent in the SAME TCP segment as the handshake are
62
+ * delivered here immediately after onWsOpen — also synchronously within the
63
+ * upgradeToWebSocket() call — so a client that pipelines its first frame with
64
+ * the Upgrade is never dropped. */
44
65
  onWsMessage?(wsId: number, data: string | ArrayBuffer, isBinary: boolean): void;
45
66
  /** WebSocket closed (code per RFC 6455 §7.4). */
46
67
  onWsClose?(wsId: number, code: number): void;
@@ -64,6 +85,15 @@ export interface ServeOptions {
64
85
  * so slow-drip (slowloris) clients are bounded. Expiry answers 408 and
65
86
  * closes. 0 disables. Default 300000 (Node's server.requestTimeout). */
66
87
  requestTimeoutMs?: number;
88
+ /** Budget in ms for DELIVERING queued outbound bytes (the response-side twin
89
+ * of requestTimeoutMs; feature-detect via probe().capabilities.responseLimits).
90
+ * Resets on drain progress — the write queue shrinking since the last sweep,
91
+ * or a write completing — so only a drain making NO progress for the whole
92
+ * budget is closed; a genuinely slow-but-steady reader of a large download or
93
+ * SSE stream is never shed, only a stalled / zero-window peer (slow-read /
94
+ * zero-window DoS defense). Also bounds a stalled WebSocket consumer and a
95
+ * stalled close-frame flush. 0 disables. Default 300000. */
96
+ responseTimeoutMs?: number;
67
97
  /** Bind with SO_REUSEPORT so several engine instances (worker threads or
68
98
  * processes) can share one port with kernel-load-balanced accepts —
69
99
  * required for clustering. POSIX only; ignored on Windows. Default false. */
@@ -73,6 +103,19 @@ export interface ServeOptions {
73
103
  maxHeadSize?: number;
74
104
  /** Max header count; more is rejected (431). Must be > 0. Default 100. */
75
105
  maxHeaders?: number;
106
+ /** Dedicated cap on the request target (URI) length; over it answers 414.
107
+ * Default 0 = no dedicated cap (maxHeadSize still bounds the whole head with
108
+ * 431). Feature-detect via probe().capabilities.responseLimits. */
109
+ maxUriSize?: number;
110
+ /** Opt-in hard cap in bytes on the not-yet-flushed HTTP outbound queue (the
111
+ * HTTP mirror of wsBackpressureLimit); over it the connection is closed
112
+ * immediately. Default 0 = unlimited. Leave 0 unless response sizes are
113
+ * bounded — one large respond() legitimately queues its whole body; a queued
114
+ * response holds an engine-side copy (~2x body peak for one slow drain,
115
+ * bounded in time by responseTimeoutMs). Apps serving large payloads to
116
+ * untrusted clients should set this cap or stream via writeHead()/write().
117
+ * Feature-detect via probe().capabilities.responseLimits. */
118
+ responseBackpressureLimit?: number;
76
119
  /** Cap on a complete (reassembled) WebSocket message; larger messages fail
77
120
  * the connection with close code 1009. Must be > 0. Default 16 MiB. */
78
121
  wsMaxMessageSize?: number;
@@ -110,6 +153,13 @@ export interface ServeOptions {
110
153
  requestCert?: boolean;
111
154
  /** Fail the handshake when the client cert doesn't verify (default true) */
112
155
  rejectUnauthorized?: boolean;
156
+ /** Explicit cipher/group policy for compliance baselines (PCI/FIPS/hardened
157
+ * profiles; feature-detect via probe().capabilities.tlsPolicy). Same
158
+ * semantics as Node's tls.createSecureContext; unset = the host Node's
159
+ * OpenSSL defaults; invalid values THROW from serve(). */
160
+ ciphers?: string; // TLS <= 1.2 cipher list
161
+ ciphersuites?: string; // TLS 1.3 suites (colon-separated)
162
+ ecdhCurve?: string; // key-share groups, e.g. 'X25519:P-256'; 'auto' = default
113
163
  };
114
164
  /** WebSocket permessage-deflate (RFC 7692). Off by default.
115
165
  * boolean to enable with defaults, or an options object. */
@@ -175,7 +225,9 @@ export function write(reqId: number, chunk: BodyInit): boolean;
175
225
  export function end(reqId: number, chunk?: BodyInit): void;
176
226
 
177
227
  // ---- WebSocket (RFC 6455) ----
178
- /** Upgrade the request's connection; returns wsId, or -1 if not a valid upgrade. */
228
+ /** Upgrade the request's connection; returns wsId, or -1 if not a valid upgrade.
229
+ * onWsOpen (and any early frames pipelined in the handshake's TCP segment, via
230
+ * onWsMessage) fire SYNCHRONOUSLY during this call, before it returns. */
179
231
  export function upgradeToWebSocket(reqId: number): number;
180
232
  /** Send a frame; returns false on backpressure. */
181
233
  export function wsSend(wsId: number, data: string | ArrayBuffer | Uint8Array | Buffer, isBinary: boolean): boolean;
package/index.js CHANGED
@@ -124,30 +124,55 @@ function probe() {
124
124
  return { ...loaded.module.probe(), version: ENGINE_VERSION };
125
125
  }
126
126
 
127
+ // The native binding's function exports (src/binding.cpp Initialize; mirrored by
128
+ // the ESM named exports in index.mjs). ONLY these names force a native load —
129
+ // anything else reads as undefined without loading, so `require`/`import` of
130
+ // this package never throws on a platform with no prebuilt binary, even when a
131
+ // module-interop probe (TypeScript `__importDefault` reads `__esModule`, Babel
132
+ // `interopRequireDefault` reads `default`, `JSON.stringify` reads `toJSON`,
133
+ // `util.inspect` reads assorted keys) walks the exports object. `probe` and
134
+ // `version` are served from the target below and likewise never load.
135
+ const NATIVE_API = new Set([
136
+ 'serve',
137
+ 'listen',
138
+ 'close',
139
+ 'stopListening',
140
+ 'getMethod',
141
+ 'getQuery',
142
+ 'getHeaders',
143
+ 'getHeader',
144
+ 'getBody',
145
+ 'getRemoteAddress',
146
+ 'isAborted',
147
+ 'respond',
148
+ 'writeHead',
149
+ 'write',
150
+ 'end',
151
+ 'upgradeToWebSocket',
152
+ 'wsSend',
153
+ 'wsClose',
154
+ ]);
155
+
127
156
  module.exports = new Proxy(
128
157
  { probe, version: ENGINE_VERSION },
129
158
  {
130
159
  get(target, prop) {
131
160
  if (prop in target) return target[prop];
132
- // Structural probes must never force (and possibly fail) the native
133
- // load: `then` is touched by `await`/Promise.resolve() on the module,
134
- // and symbols by console.log/util.inspect. Real engine API props are
135
- // string-named and never `then`.
136
- if (typeof prop === 'symbol' || prop === 'then') return undefined;
137
- // Everything else (serve, listen, ... as the engine grows) comes from the
138
- // native binding, loaded on first touch. `probe` and `version` are served
139
- // from the target above so neither forces a native load.
140
- const binding = loadBinding();
141
- return binding[prop];
161
+ // Only a known native API name forces the load. Everything else —
162
+ // symbols, `then` (awaiting the module), and interop probes like
163
+ // `__esModule`/`default`/`toJSON` — resolves to undefined WITHOUT loading,
164
+ // so importing this package can never throw on an unsupported platform.
165
+ if (typeof prop === 'string' && NATIVE_API.has(prop)) {
166
+ return loadBinding()[prop];
167
+ }
168
+ return undefined;
142
169
  },
143
170
  has(target, prop) {
144
- // Keep `in` consistent with the get trap (so `'serve' in engine` works
145
- // for feature detection) without forcing a native load: `then` and
146
- // symbols read as undefined there, so report them absent here; every
147
- // other string key is served from the binding on first touch.
171
+ // Keep `in` consistent with the get trap (so `'serve' in engine` works for
172
+ // feature detection) without forcing a native load: a key is present iff
173
+ // it is served from the target or is a known native API name.
148
174
  if (prop in target) return true;
149
- if (typeof prop === 'symbol' || prop === 'then') return false;
150
- return typeof prop === 'string';
175
+ return typeof prop === 'string' && NATIVE_API.has(prop);
151
176
  },
152
177
  }
153
178
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@morojs/engine",
3
- "version": "1.1.3",
3
+ "version": "1.1.5",
4
4
  "description": "MoroJS native HTTP engine - Moro-authored C++ core with per-platform prebuilt binaries and automatic Node.js fallback in MoroJS",
5
5
  "license": "MIT",
6
6
  "author": "CM Ventures Inc.",
@@ -38,13 +38,13 @@
38
38
  "provenance": true
39
39
  },
40
40
  "optionalDependencies": {
41
- "@morojs/engine-darwin-arm64": "1.1.3",
42
- "@morojs/engine-darwin-x64": "1.1.3",
43
- "@morojs/engine-linux-x64-gnu": "1.1.3",
44
- "@morojs/engine-linux-arm64-gnu": "1.1.3",
45
- "@morojs/engine-linux-x64-musl": "1.1.3",
46
- "@morojs/engine-linux-arm64-musl": "1.1.3",
47
- "@morojs/engine-win32-x64": "1.1.3"
41
+ "@morojs/engine-darwin-arm64": "1.1.5",
42
+ "@morojs/engine-darwin-x64": "1.1.5",
43
+ "@morojs/engine-linux-x64-gnu": "1.1.5",
44
+ "@morojs/engine-linux-arm64-gnu": "1.1.5",
45
+ "@morojs/engine-linux-x64-musl": "1.1.5",
46
+ "@morojs/engine-linux-arm64-musl": "1.1.5",
47
+ "@morojs/engine-win32-x64": "1.1.5"
48
48
  },
49
49
  "keywords": [
50
50
  "morojs",