@morojs/engine 1.1.5 → 1.1.7

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,20 @@ 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, `probe().transportReason` why, and
82
+ `probe().transportMode` which io_uring ring mode is running: `defer-taskrun`
83
+ (completions run as one batch inside the engine's own `io_uring_enter`, woken
84
+ through a registered eventfd) or `coop-taskrun` (the 1.1.6 mode, also
85
+ selectable with `MORO_ENGINE_URING_TASKRUN=coop`).
86
+
73
87
  ## License
74
88
 
75
89
  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,50 @@ 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
+ /** Every callback into JS (onRequest, onRequestBatch, onAborted, onWritable,
34
+ * the WebSocket callbacks) runs inside a Node callback scope, so
35
+ * process.nextTick callbacks and microtasks queued during dispatch run
36
+ * when the callback returns, as they do after Node's own I/O callbacks. */
37
+ callbackScope: boolean;
38
+ /** onAborted / onWritable are delivered on a later loop turn - never
39
+ * re-entrantly from inside respond()/writeHead()/write()/end(). close()
40
+ * still delivers pending onAborted calls before it returns. False only
41
+ * under the MORO_ENGINE_NOTIFY=sync diagnostics switch. */
42
+ asyncNotify: boolean;
43
+ /** A server left open when its environment is torn down
44
+ * (worker.terminate(), process.exit() inside a worker thread) is closed by
45
+ * an environment cleanup hook, so the engine is safe inside worker_threads. */
46
+ workerThreads: boolean;
47
+ /** V8 fast API calls are installed on the hot entry points (respondPrepared,
48
+ * respondPreparedEmpty, writeHeadPrepared, write, end, endWith, isAborted):
49
+ * optimised callers invoke the engine directly, skipping the V8 callback
50
+ * machinery. Informational - behaviour is identical either way. See
51
+ * EngineProbeResult.fastApi for why it is off. */
52
+ fastCalls: boolean;
53
+ /** Batched pipelined dispatch: the onRequestBatch callback, getBatchBuffers()
54
+ * and getPath(). Off under MORO_ENGINE_BATCH=0. */
55
+ batchDispatch: boolean;
56
+ }
57
+
58
+ export interface FastApiInfo {
59
+ /** Built with the V8 fast-call targets (tools/build.mjs fetched the
60
+ * per-tag v8-fast-api-calls.h; `--no-fast-api` turns this off). */
61
+ compiled: boolean;
62
+ /** Fast targets registered on this load. */
63
+ installed: boolean;
64
+ /** 'ok' | 'not-compiled' | 'env-disabled' (MORO_ENGINE_FASTCALL=0) |
65
+ * 'sync-notify' (MORO_ENGINE_NOTIFY=sync forbids it) |
66
+ * 'v8-mismatch' (host V8 major.minor != the compiled one). */
67
+ reason: string;
68
+ /** V8 major.minor this binary was compiled against, e.g. '13.6'. */
69
+ compiledV8: string;
70
+ /** V8 major.minor of the running Node. */
71
+ runtimeV8: string;
28
72
  }
29
73
 
30
74
  export interface EngineProbeResult {
@@ -39,6 +83,27 @@ export interface EngineProbeResult {
39
83
  /** Feature flags for consumers to gate option passing on (feature-detect;
40
84
  * treat absent as all-false). */
41
85
  capabilities?: EngineCapabilities;
86
+ /** How onAborted / onWritable reach JS: 'deferred' (a later loop turn, the
87
+ * default) or 'sync' (MORO_ENGINE_NOTIFY=sync, re-entrant, diagnostics). */
88
+ notify?: 'deferred' | 'sync';
89
+ /** Fast-call build/install diagnostics. */
90
+ fastApi?: FastApiInfo;
91
+ /** I/O transport in use: 'uring' (Linux 6.1+ with io_uring permitted by the
92
+ * sandbox) or 'uv' (libuv streams - macOS, Windows, older kernels,
93
+ * seccomp-blocked containers, MORO_ENGINE_TRANSPORT=uv). Behaviour and wire
94
+ * bytes are identical; only the syscall layer differs. */
95
+ transport?: 'uv' | 'uring';
96
+ /** Why the transport is not io_uring ('ok' when it is). */
97
+ transportReason?: string;
98
+ /** 'uv', or the io_uring ring mode in use: 'defer-taskrun' (completions run
99
+ * as one batch inside the engine's own io_uring_enter, woken through a
100
+ * registered eventfd) or 'coop-taskrun' (the 1.1.6 mode). The probe tries
101
+ * defer first; MORO_ENGINE_URING_TASKRUN=coop|defer pins one. */
102
+ transportMode?: 'uv' | 'defer-taskrun' | 'coop-taskrun';
103
+ /** Per-thread fast/slow hit counters per hot entry point - present only when
104
+ * MORO_ENGINE_FASTCALL_STATS=1 was set when the addon loaded (test/CI proof
105
+ * that the fast path is taken). */
106
+ fastCallStats?: Record<string, { fast: number; slow: number }>;
42
107
  /** Load failure detail when ok is false */
43
108
  error?: string;
44
109
  }
@@ -47,9 +112,27 @@ export interface ServeCallbacks {
47
112
  /** A complete request (head + body) arrived. methodIdx indexes
48
113
  * ['GET','POST','PUT','DELETE','PATCH','HEAD','OPTIONS','OTHER']. */
49
114
  onRequest(reqId: number, methodIdx: number, path: string): void;
50
- /** The client disconnected before the response completed. */
115
+ /** Batched pipelined dispatch (capabilities.batchDispatch). When registered,
116
+ * complete pipelined requests are parsed ahead and delivered as ONE call:
117
+ * `count` slots described in getBatchBuffers().descriptors (three
118
+ * Uint32 per slot: reqId, methodIdx, pathIdx into `paths`, or 0xFFFFFFFF
119
+ * meaning "call getPath(reqId)"). Answer slot 0, then read `control[0]`:
120
+ * it is the index of the slot the engine has activated (only a
121
+ * synchronously completed response activates the next one) - continue at
122
+ * that index, or return when it still equals the slot you just dispatched
123
+ * (that handler is async; the remaining slots are delivered later). A
124
+ * request that stands alone still arrives here with count 1; onRequest is
125
+ * used only when this callback is absent. Return the slots consumed. */
126
+ onRequestBatch?(count: number): number;
127
+ /** The client disconnected, or the engine tore the request down (write
128
+ * error, responseBackpressureLimit, timeout, close()), before the response
129
+ * completed. Delivered on a LATER loop turn, never re-entrantly from
130
+ * inside a respond()/write()/end() call; isAborted(reqId) is already true
131
+ * when it runs. Exception: close() delivers the onAborted of every
132
+ * in-flight request synchronously, before close() returns. */
51
133
  onAborted(reqId: number): void;
52
- /** A backpressured write() drained; safe to write more. */
134
+ /** A backpressured write() drained; safe to write more. Delivered on a
135
+ * later loop turn (never from inside the write() that reported false). */
53
136
  onWritable(reqId: number): void;
54
137
  /** WebSocket opened after a successful Upgrade.
55
138
  * DELIVERY GUARANTEE: onWsOpen is invoked SYNCHRONOUSLY, re-entrantly, during
@@ -203,6 +286,18 @@ export function stopListening(serverId: number): void;
203
286
 
204
287
  // ---- per-request accessors (valid until the response ends / aborts) ----
205
288
  export function getMethod(reqId: number): string | undefined;
289
+ /** The batch-dispatch buffers of a server (the same objects every call):
290
+ * descriptors (3 x 16 Uint32), control (1 Uint32), paths (string[]). See
291
+ * ServeCallbacks.onRequestBatch. Feature-detect via
292
+ * probe().capabilities.batchDispatch. */
293
+ export function getBatchBuffers(serverId: number): {
294
+ descriptors: Uint32Array;
295
+ control: Uint32Array;
296
+ paths: string[];
297
+ };
298
+ /** The active request's path, for a batch descriptor whose pathIdx is
299
+ * 0xFFFFFFFF (the path was too long or the table full). */
300
+ export function getPath(reqId: number): string;
206
301
  export function getQuery(reqId: number): string;
207
302
  /** Flat [k0,v0,k1,v1,...] with lowercased keys. */
208
303
  export function getHeaders(reqId: number): string[];
@@ -224,6 +319,59 @@ export function writeHead(reqId: number, status: number, headersFlat: string[] |
224
319
  export function write(reqId: number, chunk: BodyInit): boolean;
225
320
  export function end(reqId: number, chunk?: BodyInit): void;
226
321
 
322
+ // ---- Static routes ----
323
+ /** Register a fixed response for one (method, path), answered entirely inside
324
+ * the engine: no JS call, no routing, no header building per request. The
325
+ * header block and body are materialised once, here, so the response is
326
+ * byte-identical to the same reply sent via respond().
327
+ *
328
+ * Only an exact method match short-circuits - anything else (a HEAD against a
329
+ * registered GET included) still reaches onRequest, so method policy stays in
330
+ * JS. Re-registering the same (method, path) replaces it.
331
+ *
332
+ * `method` is the engine's method index: GET 0, POST 1, PUT 2, DELETE 3,
333
+ * PATCH 4, HEAD 5, OPTIONS 6.
334
+ *
335
+ * Feature-detect via probe().capabilities.staticRoutes. */
336
+ export function setStaticRoute(
337
+ serverId: number,
338
+ method: number,
339
+ path: string,
340
+ status?: number,
341
+ headersFlat?: string[] | null,
342
+ body?: BodyInit | null
343
+ ): void;
344
+ /** Drop every static route registered on this server. */
345
+ export function clearStaticRoutes(serverId: number): void;
346
+
347
+ // ---- Prepared response templates ----
348
+ /** Materialise status + headers ONCE (the same header builder respond() uses,
349
+ * so the wire bytes are identical) and get back a template id to replay per
350
+ * request with respondPrepared()/respondPreparedEmpty()/writeHeadPrepared().
351
+ * Ids are per server, dense from 1, and stay valid until releaseTemplates()
352
+ * (or close()). Throws a RangeError when the per-server store is full (4096).
353
+ * A Content-Length in `headersFlat` is honoured on HEAD/bodyless replies only,
354
+ * exactly as with respond(). Feature-detect via
355
+ * probe().capabilities.responseTemplates. */
356
+ export function prepareResponse(
357
+ serverId: number,
358
+ status: number,
359
+ headersFlat: string[] | null
360
+ ): number;
361
+ /** Invalidate every template id issued by prepareResponse() on this server. */
362
+ export function releaseTemplates(serverId: number): void;
363
+ /** respond() with a prepared template instead of a header array. An invalid
364
+ * tplId (0, released, another server's) answers 500 with an empty body and
365
+ * leaves keep-alive intact - it never throws and never hangs the request. */
366
+ export function respondPrepared(reqId: number, tplId: number, body: BodyInit | null): void;
367
+ /** respondPrepared() with no body (Content-Length: 0). */
368
+ export function respondPreparedEmpty(reqId: number, tplId: number): void;
369
+ /** writeHead() with a prepared template (streaming follows with write()/end()). */
370
+ export function writeHeadPrepared(reqId: number, tplId: number): void;
371
+ /** Exactly end(reqId, chunk): a fixed-arity twin for call sites that always
372
+ * pass a chunk. */
373
+ export function endWith(reqId: number, chunk: BodyInit): void;
374
+
227
375
  // ---- WebSocket (RFC 6455) ----
228
376
  /** Upgrade the request's connection; returns wsId, or -1 if not a valid upgrade.
229
377
  * onWsOpen (and any early frames pipelined in the handshake's TCP segment, via
@@ -248,6 +396,8 @@ declare const engine: {
248
396
  close: typeof close;
249
397
  stopListening: typeof stopListening;
250
398
  getMethod: typeof getMethod;
399
+ getBatchBuffers: typeof getBatchBuffers;
400
+ getPath: typeof getPath;
251
401
  getQuery: typeof getQuery;
252
402
  getHeaders: typeof getHeaders;
253
403
  getHeader: typeof getHeader;
@@ -258,6 +408,14 @@ declare const engine: {
258
408
  writeHead: typeof writeHead;
259
409
  write: typeof write;
260
410
  end: typeof end;
411
+ setStaticRoute: typeof setStaticRoute;
412
+ clearStaticRoutes: typeof clearStaticRoutes;
413
+ prepareResponse: typeof prepareResponse;
414
+ releaseTemplates: typeof releaseTemplates;
415
+ respondPrepared: typeof respondPrepared;
416
+ respondPreparedEmpty: typeof respondPreparedEmpty;
417
+ writeHeadPrepared: typeof writeHeadPrepared;
418
+ endWith: typeof endWith;
261
419
  upgradeToWebSocket: typeof upgradeToWebSocket;
262
420
  wsSend: typeof wsSend;
263
421
  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.5",
3
+ "version": "1.1.7",
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.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"
41
+ "@morojs/engine-darwin-arm64": "1.1.7",
42
+ "@morojs/engine-darwin-x64": "1.1.7",
43
+ "@morojs/engine-linux-x64-gnu": "1.1.7",
44
+ "@morojs/engine-linux-arm64-gnu": "1.1.7",
45
+ "@morojs/engine-linux-x64-musl": "1.1.7",
46
+ "@morojs/engine-linux-arm64-musl": "1.1.7",
47
+ "@morojs/engine-win32-x64": "1.1.7"
48
48
  },
49
49
  "keywords": [
50
50
  "morojs",