@morojs/engine 1.1.4 → 1.1.6

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
@@ -70,6 +70,16 @@ optional-dependency lockfile bug ([npm/cli#4828](https://github.com/npm/cli/issu
70
70
  Node ABIs: 115/127/131/137/141/147 (Node 20/22/23/24/25/26). Any other
71
71
  platform/ABI falls back to Node's `http` server via MoroJS.
72
72
 
73
+ ## I/O transport
74
+
75
+ The engine runs on libuv streams by default. On Linux 6.1+ an io_uring
76
+ transport is available opt-in (`MORO_ENGINE_TRANSPORT=uring`): it is probed
77
+ once per process by a feature check and a self-test, and anywhere it is
78
+ unavailable (kernels before 6.1, gVisor, containers under Docker's default
79
+ seccomp profile, which blocks `io_uring_setup`) the engine silently stays on
80
+ libuv. Neither transport changes a byte on the wire. `probe().transport`
81
+ reports which one is live and `probe().transportReason` why.
82
+
73
83
  ## License
74
84
 
75
85
  MIT licensed.
package/index.d.ts CHANGED
@@ -3,10 +3,10 @@
3
3
  //
4
4
  // DRIFT CHECK (maintainers): this surface must stay in lockstep with what the
5
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.
6
+ // serve() option, capability flag, or native export is added there, add it
7
+ // here in the same change. `npm run check:exports` (tools/check-exports.mjs,
8
+ // run by CI and by tools/release.mjs) diffs the binding against this file,
9
+ // index.js NATIVE_API and index.mjs, and fails on drift.
10
10
 
11
11
  export interface EngineCapabilities {
12
12
  /** The full serve() limit surface (maxHeadSize/maxHeaders/wsMaxMessageSize/
@@ -25,6 +25,45 @@ export interface EngineCapabilities {
25
25
  /** Explicit TLS cipher/group policy is parsed:
26
26
  * ServeOptions.ssl.ciphers, ciphersuites, and ecdhCurve. */
27
27
  tlsPolicy: boolean;
28
+ /** setStaticRoute() / clearStaticRoutes() are available. */
29
+ staticRoutes: boolean;
30
+ /** prepareResponse() / releaseTemplates() / respondPrepared() /
31
+ * respondPreparedEmpty() / writeHeadPrepared() / endWith() are available. */
32
+ responseTemplates: boolean;
33
+ /** onAborted / onWritable are delivered on a later loop turn - never
34
+ * re-entrantly from inside respond()/writeHead()/write()/end(). close()
35
+ * still delivers pending onAborted calls before it returns. False only
36
+ * under the MORO_ENGINE_NOTIFY=sync diagnostics switch. */
37
+ asyncNotify: boolean;
38
+ /** A server left open when its environment is torn down
39
+ * (worker.terminate(), process.exit() inside a worker thread) is closed by
40
+ * an environment cleanup hook, so the engine is safe inside worker_threads. */
41
+ workerThreads: boolean;
42
+ /** V8 fast API calls are installed on the hot entry points (respondPrepared,
43
+ * respondPreparedEmpty, writeHeadPrepared, write, end, endWith, isAborted):
44
+ * optimised callers invoke the engine directly, skipping the V8 callback
45
+ * machinery. Informational - behaviour is identical either way. See
46
+ * EngineProbeResult.fastApi for why it is off. */
47
+ fastCalls: boolean;
48
+ /** Batched pipelined dispatch: the onRequestBatch callback, getBatchBuffers()
49
+ * and getPath(). Off under MORO_ENGINE_BATCH=0. */
50
+ batchDispatch: boolean;
51
+ }
52
+
53
+ export interface FastApiInfo {
54
+ /** Built with the V8 fast-call targets (tools/build.mjs fetched the
55
+ * per-tag v8-fast-api-calls.h; `--no-fast-api` turns this off). */
56
+ compiled: boolean;
57
+ /** Fast targets registered on this load. */
58
+ installed: boolean;
59
+ /** 'ok' | 'not-compiled' | 'env-disabled' (MORO_ENGINE_FASTCALL=0) |
60
+ * 'sync-notify' (MORO_ENGINE_NOTIFY=sync forbids it) |
61
+ * 'v8-mismatch' (host V8 major.minor != the compiled one). */
62
+ reason: string;
63
+ /** V8 major.minor this binary was compiled against, e.g. '13.6'. */
64
+ compiledV8: string;
65
+ /** V8 major.minor of the running Node. */
66
+ runtimeV8: string;
28
67
  }
29
68
 
30
69
  export interface EngineProbeResult {
@@ -39,6 +78,22 @@ export interface EngineProbeResult {
39
78
  /** Feature flags for consumers to gate option passing on (feature-detect;
40
79
  * treat absent as all-false). */
41
80
  capabilities?: EngineCapabilities;
81
+ /** How onAborted / onWritable reach JS: 'deferred' (a later loop turn, the
82
+ * default) or 'sync' (MORO_ENGINE_NOTIFY=sync, re-entrant, diagnostics). */
83
+ notify?: 'deferred' | 'sync';
84
+ /** Fast-call build/install diagnostics. */
85
+ fastApi?: FastApiInfo;
86
+ /** I/O transport in use: 'uring' (Linux 6.1+ with io_uring permitted by the
87
+ * sandbox) or 'uv' (libuv streams - macOS, Windows, older kernels,
88
+ * seccomp-blocked containers, MORO_ENGINE_TRANSPORT=uv). Behaviour and wire
89
+ * bytes are identical; only the syscall layer differs. */
90
+ transport?: 'uv' | 'uring';
91
+ /** Why the transport is not io_uring ('ok' when it is). */
92
+ transportReason?: string;
93
+ /** Per-thread fast/slow hit counters per hot entry point - present only when
94
+ * MORO_ENGINE_FASTCALL_STATS=1 was set when the addon loaded (test/CI proof
95
+ * that the fast path is taken). */
96
+ fastCallStats?: Record<string, { fast: number; slow: number }>;
42
97
  /** Load failure detail when ok is false */
43
98
  error?: string;
44
99
  }
@@ -47,9 +102,27 @@ export interface ServeCallbacks {
47
102
  /** A complete request (head + body) arrived. methodIdx indexes
48
103
  * ['GET','POST','PUT','DELETE','PATCH','HEAD','OPTIONS','OTHER']. */
49
104
  onRequest(reqId: number, methodIdx: number, path: string): void;
50
- /** The client disconnected before the response completed. */
105
+ /** Batched pipelined dispatch (capabilities.batchDispatch). When registered,
106
+ * complete pipelined requests are parsed ahead and delivered as ONE call:
107
+ * `count` slots described in getBatchBuffers().descriptors (three
108
+ * Uint32 per slot: reqId, methodIdx, pathIdx into `paths`, or 0xFFFFFFFF
109
+ * meaning "call getPath(reqId)"). Answer slot 0, then read `control[0]`:
110
+ * it is the index of the slot the engine has activated (only a
111
+ * synchronously completed response activates the next one) - continue at
112
+ * that index, or return when it still equals the slot you just dispatched
113
+ * (that handler is async; the remaining slots are delivered later). A
114
+ * request that stands alone still arrives here with count 1; onRequest is
115
+ * used only when this callback is absent. Return the slots consumed. */
116
+ onRequestBatch?(count: number): number;
117
+ /** The client disconnected, or the engine tore the request down (write
118
+ * error, responseBackpressureLimit, timeout, close()), before the response
119
+ * completed. Delivered on a LATER loop turn, never re-entrantly from
120
+ * inside a respond()/write()/end() call; isAborted(reqId) is already true
121
+ * when it runs. Exception: close() delivers the onAborted of every
122
+ * in-flight request synchronously, before close() returns. */
51
123
  onAborted(reqId: number): void;
52
- /** A backpressured write() drained; safe to write more. */
124
+ /** A backpressured write() drained; safe to write more. Delivered on a
125
+ * later loop turn (never from inside the write() that reported false). */
53
126
  onWritable(reqId: number): void;
54
127
  /** WebSocket opened after a successful Upgrade.
55
128
  * DELIVERY GUARANTEE: onWsOpen is invoked SYNCHRONOUSLY, re-entrantly, during
@@ -203,6 +276,18 @@ export function stopListening(serverId: number): void;
203
276
 
204
277
  // ---- per-request accessors (valid until the response ends / aborts) ----
205
278
  export function getMethod(reqId: number): string | undefined;
279
+ /** The batch-dispatch buffers of a server (the same objects every call):
280
+ * descriptors (3 x 16 Uint32), control (1 Uint32), paths (string[]). See
281
+ * ServeCallbacks.onRequestBatch. Feature-detect via
282
+ * probe().capabilities.batchDispatch. */
283
+ export function getBatchBuffers(serverId: number): {
284
+ descriptors: Uint32Array;
285
+ control: Uint32Array;
286
+ paths: string[];
287
+ };
288
+ /** The active request's path, for a batch descriptor whose pathIdx is
289
+ * 0xFFFFFFFF (the path was too long or the table full). */
290
+ export function getPath(reqId: number): string;
206
291
  export function getQuery(reqId: number): string;
207
292
  /** Flat [k0,v0,k1,v1,...] with lowercased keys. */
208
293
  export function getHeaders(reqId: number): string[];
@@ -224,6 +309,59 @@ export function writeHead(reqId: number, status: number, headersFlat: string[] |
224
309
  export function write(reqId: number, chunk: BodyInit): boolean;
225
310
  export function end(reqId: number, chunk?: BodyInit): void;
226
311
 
312
+ // ---- Static routes ----
313
+ /** Register a fixed response for one (method, path), answered entirely inside
314
+ * the engine: no JS call, no routing, no header building per request. The
315
+ * header block and body are materialised once, here, so the response is
316
+ * byte-identical to the same reply sent via respond().
317
+ *
318
+ * Only an exact method match short-circuits - anything else (a HEAD against a
319
+ * registered GET included) still reaches onRequest, so method policy stays in
320
+ * JS. Re-registering the same (method, path) replaces it.
321
+ *
322
+ * `method` is the engine's method index: GET 0, POST 1, PUT 2, DELETE 3,
323
+ * PATCH 4, HEAD 5, OPTIONS 6.
324
+ *
325
+ * Feature-detect via probe().capabilities.staticRoutes. */
326
+ export function setStaticRoute(
327
+ serverId: number,
328
+ method: number,
329
+ path: string,
330
+ status?: number,
331
+ headersFlat?: string[] | null,
332
+ body?: BodyInit | null
333
+ ): void;
334
+ /** Drop every static route registered on this server. */
335
+ export function clearStaticRoutes(serverId: number): void;
336
+
337
+ // ---- Prepared response templates ----
338
+ /** Materialise status + headers ONCE (the same header builder respond() uses,
339
+ * so the wire bytes are identical) and get back a template id to replay per
340
+ * request with respondPrepared()/respondPreparedEmpty()/writeHeadPrepared().
341
+ * Ids are per server, dense from 1, and stay valid until releaseTemplates()
342
+ * (or close()). Throws a RangeError when the per-server store is full (4096).
343
+ * A Content-Length in `headersFlat` is honoured on HEAD/bodyless replies only,
344
+ * exactly as with respond(). Feature-detect via
345
+ * probe().capabilities.responseTemplates. */
346
+ export function prepareResponse(
347
+ serverId: number,
348
+ status: number,
349
+ headersFlat: string[] | null
350
+ ): number;
351
+ /** Invalidate every template id issued by prepareResponse() on this server. */
352
+ export function releaseTemplates(serverId: number): void;
353
+ /** respond() with a prepared template instead of a header array. An invalid
354
+ * tplId (0, released, another server's) answers 500 with an empty body and
355
+ * leaves keep-alive intact - it never throws and never hangs the request. */
356
+ export function respondPrepared(reqId: number, tplId: number, body: BodyInit | null): void;
357
+ /** respondPrepared() with no body (Content-Length: 0). */
358
+ export function respondPreparedEmpty(reqId: number, tplId: number): void;
359
+ /** writeHead() with a prepared template (streaming follows with write()/end()). */
360
+ export function writeHeadPrepared(reqId: number, tplId: number): void;
361
+ /** Exactly end(reqId, chunk): a fixed-arity twin for call sites that always
362
+ * pass a chunk. */
363
+ export function endWith(reqId: number, chunk: BodyInit): void;
364
+
227
365
  // ---- WebSocket (RFC 6455) ----
228
366
  /** Upgrade the request's connection; returns wsId, or -1 if not a valid upgrade.
229
367
  * onWsOpen (and any early frames pipelined in the handshake's TCP segment, via
@@ -248,6 +386,8 @@ declare const engine: {
248
386
  close: typeof close;
249
387
  stopListening: typeof stopListening;
250
388
  getMethod: typeof getMethod;
389
+ getBatchBuffers: typeof getBatchBuffers;
390
+ getPath: typeof getPath;
251
391
  getQuery: typeof getQuery;
252
392
  getHeaders: typeof getHeaders;
253
393
  getHeader: typeof getHeader;
@@ -258,6 +398,14 @@ declare const engine: {
258
398
  writeHead: typeof writeHead;
259
399
  write: typeof write;
260
400
  end: typeof end;
401
+ setStaticRoute: typeof setStaticRoute;
402
+ clearStaticRoutes: typeof clearStaticRoutes;
403
+ prepareResponse: typeof prepareResponse;
404
+ releaseTemplates: typeof releaseTemplates;
405
+ respondPrepared: typeof respondPrepared;
406
+ respondPreparedEmpty: typeof respondPreparedEmpty;
407
+ writeHeadPrepared: typeof writeHeadPrepared;
408
+ endWith: typeof endWith;
261
409
  upgradeToWebSocket: typeof upgradeToWebSocket;
262
410
  wsSend: typeof wsSend;
263
411
  wsClose: typeof wsClose;
package/index.js CHANGED
@@ -61,6 +61,22 @@ function tryLoad() {
61
61
  const name = binaryName();
62
62
  const attempts = [];
63
63
 
64
+ // 0. Explicit binary (build/diagnostics only, never needed by users): the
65
+ // PGO training run loads an instrumented build from a side directory,
66
+ // and A/B runs can pin a specific .node. A path that fails to load is a
67
+ // hard error - falling through to a different binary would defeat the
68
+ // point of asking for this one.
69
+ const explicit = process.env.MORO_ENGINE_BINARY;
70
+ if (explicit) {
71
+ try {
72
+ return { module: require(explicit), from: explicit };
73
+ } catch (err) {
74
+ const error = new Error(`@morojs/engine: MORO_ENGINE_BINARY=${explicit} failed to load: ${err.message}`);
75
+ error.code = 'MORO_ENGINE_BINARY_MISSING';
76
+ return { error };
77
+ }
78
+ }
79
+
64
80
  // 1. Per-platform npm package
65
81
  const pkg = platformPackageName();
66
82
  try {
@@ -138,6 +154,8 @@ const NATIVE_API = new Set([
138
154
  'close',
139
155
  'stopListening',
140
156
  'getMethod',
157
+ 'getBatchBuffers',
158
+ 'getPath',
141
159
  'getQuery',
142
160
  'getHeaders',
143
161
  'getHeader',
@@ -148,6 +166,14 @@ const NATIVE_API = new Set([
148
166
  'writeHead',
149
167
  'write',
150
168
  'end',
169
+ 'setStaticRoute',
170
+ 'clearStaticRoutes',
171
+ 'prepareResponse',
172
+ 'releaseTemplates',
173
+ 'respondPrepared',
174
+ 'respondPreparedEmpty',
175
+ 'writeHeadPrepared',
176
+ 'endWith',
151
177
  'upgradeToWebSocket',
152
178
  'wsSend',
153
179
  'wsClose',
@@ -163,7 +189,13 @@ module.exports = new Proxy(
163
189
  // `__esModule`/`default`/`toJSON` — resolves to undefined WITHOUT loading,
164
190
  // so importing this package can never throw on an unsupported platform.
165
191
  if (typeof prop === 'string' && NATIVE_API.has(prop)) {
166
- return loadBinding()[prop];
192
+ // Cache the native function on the target so every later read
193
+ // short-circuits on `prop in target` above: the call site then sees
194
+ // one constant function (inline-cacheable, fast-call eligible)
195
+ // instead of a fresh trap invocation per call.
196
+ const fn = loadBinding()[prop];
197
+ target[prop] = fn;
198
+ return fn;
167
199
  }
168
200
  return undefined;
169
201
  },
package/index.mjs CHANGED
@@ -6,11 +6,19 @@
6
6
  // cannot enumerate dynamic props), so this wrapper restates the named surface
7
7
  // declared in index.d.ts for ESM consumers.
8
8
  //
9
- // Every function is a thin lazy pass-through: it touches the native binding
10
- // only when CALLED, so a bare `import` never loads the addon and never throws
11
- // on a platform without a prebuilt binary. probe() stays non-throwing.
9
+ // Every function is a lazy pass-through that touches the native binding only
10
+ // when CALLED, so a bare `import` never loads the addon and never throws on a
11
+ // platform without a prebuilt binary. probe() stays non-throwing.
12
12
  //
13
- // Maintenance: keep this list in sync with the function exports in index.d.ts.
13
+ // The first successful call REBINDS the export to the native function itself
14
+ // (`export let` bindings are live for importers): every later call from a
15
+ // `import { respond } from '@morojs/engine'` site goes straight to the addon
16
+ // with no wrapper frame and a constant call target, which is what lets V8
17
+ // inline-cache the site and take the engine's fast-call path. If the addon
18
+ // fails to load, the assignment never happens and the wrapper keeps throwing
19
+ // the loader's error on every call.
20
+ //
21
+ // Maintenance: `npm run check:exports` diffs this list against the binding.
14
22
  import engine from './index.js';
15
23
 
16
24
  export default engine;
@@ -18,21 +26,31 @@ export default engine;
18
26
  // probe() lives on the loader itself (never loads the binding) - safe to alias.
19
27
  export const probe = engine.probe;
20
28
 
21
- export const serve = (...a) => engine.serve(...a);
22
- export const listen = (...a) => engine.listen(...a);
23
- export const close = (...a) => engine.close(...a);
24
- export const stopListening = (...a) => engine.stopListening(...a);
25
- export const getMethod = (...a) => engine.getMethod(...a);
26
- export const getQuery = (...a) => engine.getQuery(...a);
27
- export const getHeaders = (...a) => engine.getHeaders(...a);
28
- export const getHeader = (...a) => engine.getHeader(...a);
29
- export const getBody = (...a) => engine.getBody(...a);
30
- export const getRemoteAddress = (...a) => engine.getRemoteAddress(...a);
31
- export const isAborted = (...a) => engine.isAborted(...a);
32
- export const respond = (...a) => engine.respond(...a);
33
- export const writeHead = (...a) => engine.writeHead(...a);
34
- export const write = (...a) => engine.write(...a);
35
- export const end = (...a) => engine.end(...a);
36
- export const upgradeToWebSocket = (...a) => engine.upgradeToWebSocket(...a);
37
- export const wsSend = (...a) => engine.wsSend(...a);
38
- export const wsClose = (...a) => engine.wsClose(...a);
29
+ export let serve = (...a) => (serve = engine.serve)(...a);
30
+ export let listen = (...a) => (listen = engine.listen)(...a);
31
+ export let close = (...a) => (close = engine.close)(...a);
32
+ export let stopListening = (...a) => (stopListening = engine.stopListening)(...a);
33
+ export let getMethod = (...a) => (getMethod = engine.getMethod)(...a);
34
+ export let getBatchBuffers = (...a) => (getBatchBuffers = engine.getBatchBuffers)(...a);
35
+ export let getPath = (...a) => (getPath = engine.getPath)(...a);
36
+ export let getQuery = (...a) => (getQuery = engine.getQuery)(...a);
37
+ export let getHeaders = (...a) => (getHeaders = engine.getHeaders)(...a);
38
+ export let getHeader = (...a) => (getHeader = engine.getHeader)(...a);
39
+ export let getBody = (...a) => (getBody = engine.getBody)(...a);
40
+ export let getRemoteAddress = (...a) => (getRemoteAddress = engine.getRemoteAddress)(...a);
41
+ export let isAborted = (...a) => (isAborted = engine.isAborted)(...a);
42
+ export let respond = (...a) => (respond = engine.respond)(...a);
43
+ export let writeHead = (...a) => (writeHead = engine.writeHead)(...a);
44
+ export let write = (...a) => (write = engine.write)(...a);
45
+ export let end = (...a) => (end = engine.end)(...a);
46
+ export let setStaticRoute = (...a) => (setStaticRoute = engine.setStaticRoute)(...a);
47
+ export let clearStaticRoutes = (...a) => (clearStaticRoutes = engine.clearStaticRoutes)(...a);
48
+ export let prepareResponse = (...a) => (prepareResponse = engine.prepareResponse)(...a);
49
+ export let releaseTemplates = (...a) => (releaseTemplates = engine.releaseTemplates)(...a);
50
+ export let respondPrepared = (...a) => (respondPrepared = engine.respondPrepared)(...a);
51
+ export let respondPreparedEmpty = (...a) => (respondPreparedEmpty = engine.respondPreparedEmpty)(...a);
52
+ export let writeHeadPrepared = (...a) => (writeHeadPrepared = engine.writeHeadPrepared)(...a);
53
+ export let endWith = (...a) => (endWith = engine.endWith)(...a);
54
+ export let upgradeToWebSocket = (...a) => (upgradeToWebSocket = engine.upgradeToWebSocket)(...a);
55
+ export let wsSend = (...a) => (wsSend = engine.wsSend)(...a);
56
+ export let wsClose = (...a) => (wsClose = engine.wsClose)(...a);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@morojs/engine",
3
- "version": "1.1.4",
3
+ "version": "1.1.6",
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.4",
42
- "@morojs/engine-darwin-x64": "1.1.4",
43
- "@morojs/engine-linux-x64-gnu": "1.1.4",
44
- "@morojs/engine-linux-arm64-gnu": "1.1.4",
45
- "@morojs/engine-linux-x64-musl": "1.1.4",
46
- "@morojs/engine-linux-arm64-musl": "1.1.4",
47
- "@morojs/engine-win32-x64": "1.1.4"
41
+ "@morojs/engine-darwin-arm64": "1.1.6",
42
+ "@morojs/engine-darwin-x64": "1.1.6",
43
+ "@morojs/engine-linux-x64-gnu": "1.1.6",
44
+ "@morojs/engine-linux-arm64-gnu": "1.1.6",
45
+ "@morojs/engine-linux-x64-musl": "1.1.6",
46
+ "@morojs/engine-linux-arm64-musl": "1.1.6",
47
+ "@morojs/engine-win32-x64": "1.1.6"
48
48
  },
49
49
  "keywords": [
50
50
  "morojs",