@mikrojs/native 0.6.0-pr-70.g7bdc6dd → 0.6.0-pr-70.gd2fdc0d

package/include/mikrojs/mem.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <stdbool.h>
 #include <stddef.h>
 #include <stdlib.h>
 
@@ -9,3 +10,19 @@ void* mik__mallocz(size_t size);
 void* mik__calloc(size_t count, size_t size);
 void mik__free(void* ptr);
 void* mik__realloc(void* ptr, size_t size);
+
+/* QuickJS-heap allocators. Backed by libc malloc by default; routed to
+ * PSRAM via the platform's malloc_psram/calloc_psram/realloc_psram hooks
+ * when mik__set_quickjs_heap_psram(true) has been called and the platform
+ * supports PSRAM. Free is unchanged: PSRAM pointers from heap_caps_malloc
+ * free cleanly via standard free() on ESP-IDF. */
+void* mik__js_malloc(size_t size);
+void* mik__js_calloc(size_t count, size_t size);
+void* mik__js_realloc(void* ptr, size_t size);
+
+/* Toggle QuickJS heap allocations to PSRAM (no-op on platforms without
+ * PSRAM). Set once before JS_NewRuntime2; do not change mid-run since
+ * mik__js_realloc relies on the flag staying consistent with the heap
+ * the original pointer came from. */
+void mik__set_quickjs_heap_psram(bool enable);
+bool mik__is_quickjs_heap_psram(void);

package/include/mikrojs/mikrojs.h

@@ -10,6 +10,17 @@ typedef struct MIKRuntime MIKRuntime;
 typedef struct MIKRunOptions {
     int mem_limit;
     size_t stack_size;
+    /* Allocate the QuickJS heap from PSRAM instead of internal SRAM on
+     * chips with both. Frees ~150-250 KB of contiguous internal SRAM for
+     * mbedTLS, WiFi/BLE, and DMA buffers, the dominant root cause of
+     * HTTPS handshake failures (error 0x7002) on apps with significant
+     * retained JS state. JS execution is somewhat slower (PSRAM has
+     * higher access latency than internal SRAM); for typical embedded
+     * IO-bound workloads this is invisible against networking and IO
+     * costs. No effect on hosts and chips without PSRAM. Defaults false
+     * for backward compatibility; the firmware bootstrap flips it on
+     * when CONFIG_MIKROJS_QUICKJS_HEAP_PSRAM is set. */
+    bool use_psram_heap;
 } MIKRunOptions;
 
 typedef struct MIKConfig {

package/include/mikrojs/platform.h

@@ -18,11 +18,37 @@ typedef struct MIKPlatform {
     size_t (*get_free_system_mem)(void);
     size_t (*get_min_free_system_mem)(void); /* All-time low watermark */
     size_t (*get_total_system_mem)(void);
-    /** Largest contiguous free block (for diagnosing heap fragmentation —
+    /** Largest contiguous free block (for diagnosing heap fragmentation:
      *  an allocation larger than this fails even if total free is bigger).
      *  On platforms without a native largest-block API, implementations
      *  may return the same value as get_free_system_mem. */
     size_t (*get_largest_free_system_mem)(void);
+    /** Free internal-SRAM bytes. On chips with PSRAM this is the subset of
+     *  free heap that lives in fast on-chip RAM, which is also what mbedTLS
+     *  handshake buffers, WiFi/BLE drivers, and DMA-capable buffers compete
+     *  for. Distinct from get_free_system_mem on PSRAM-equipped chips, where
+     *  combined heap is dominated by PSRAM and hides internal-SRAM pressure.
+     *  On hosts and chips without PSRAM, may return the same value as
+     *  get_free_system_mem (or 0 if unavailable). */
+    size_t (*get_free_internal_mem)(void);
+    /** Largest contiguous free block in internal SRAM. Allocations that
+     *  must land in internal RAM (such as mbedTLS record buffers) fail when
+     *  this drops below their size, even when get_largest_free_system_mem
+     *  reports plenty of contiguous PSRAM. Same fallback rules as
+     *  get_free_internal_mem. */
+    size_t (*get_largest_free_internal_mem)(void);
+    /** Allocate `size` bytes from PSRAM/external RAM. Returns NULL if
+     *  PSRAM is unavailable (host platforms, chips without PSRAM, or
+     *  PSRAM exhaustion); the caller falls back to the regular allocator.
+     *  On ESP32 with CONFIG_SPIRAM=y, implemented via heap_caps_malloc
+     *  with MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT. The returned pointer is
+     *  freed via standard free(). */
+    void* (*malloc_psram)(size_t size);
+    /** PSRAM-targeted calloc. Same fallback rules as malloc_psram. */
+    void* (*calloc_psram)(size_t count, size_t size);
+    /** PSRAM-targeted realloc. Grows or moves the allocation while keeping
+     *  it in PSRAM. Same fallback rules as malloc_psram. */
+    void* (*realloc_psram)(void* ptr, size_t size);
     bool (*get_fs_info)(const char* label, size_t* total, size_t* used);
     void (*log)(int level, const char* tag, const char* fmt, ...);
     int (*stdout_write)(const void* buf, size_t len);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.6.0-pr-70.g7bdc6dd",
+  "version": "0.6.0-pr-70.gd2fdc0d",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -78,7 +78,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.6.0-pr-70.g7bdc6dd"
+    "@mikrojs/quickjs": "0.6.0-pr-70.gd2fdc0d"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/ble/ble.ts

@@ -2,6 +2,7 @@ import {Observable} from 'mikrojs/observable'
 import {err, ok} from 'mikrojs/result'
 import {Ble as NativeBle} from 'native:ble'
 
+import type {Subscriber} from '../observable/types.js'
 import type {Result} from '../result/types.js'
 import type {
   AdvertiseHandle,
@@ -142,15 +143,31 @@ function normalizeServices(services: Service[]) {
 
 const native = new NativeBle()
 
-/* Per-event multicast sources backed by a single native.on registration each.
- * See observable.md → Module integration. */
-const _onConnect = Observable.withEmitters<ConnectionInfo>()
-const _onDisconnect = Observable.withEmitters<ConnectionInfo>()
-const _onMtu = Observable.withEmitters<MtuInfo>()
-
-native.on('connect', (info) => _onConnect.next(info as ConnectionInfo))
-native.on('disconnect', (info) => _onDisconnect.next(info as ConnectionInfo))
-native.on('mtu', (info) => _onMtu.next(info as MtuInfo))
+/* Lazy-attach: native.on runs only after the first JS subscriber and is
+ * removed when the last one leaves. Same pattern as wifi.ts; see the note
+ * there for the mbedTLS internal-RAM rationale. */
+function lazyEvent<T>(eventName: string): Observable<T> {
+  const subscribers: Subscriber<T>[] = []
+  function handler(value: unknown): void {
+    const snapshot = subscribers.slice()
+    for (const s of snapshot) {
+      if (!s.closed) s.next(value as T)
+    }
+  }
+  return new Observable<T>((sub) => {
+    subscribers.push(sub)
+    if (subscribers.length === 1) {
+      native.on(eventName, handler)
+    }
+    sub.addTeardown(() => {
+      const i = subscribers.indexOf(sub)
+      if (i >= 0) subscribers.splice(i, 1)
+      if (subscribers.length === 0) {
+        native.off(eventName, handler)
+      }
+    })
+  })
+}
 
 const ble: Ble = {
   get name(): string {
@@ -231,9 +248,9 @@ const peripheral: Peripheral = {
     return ok(handle)
   },
 
-  onConnect: _onConnect.observable,
-  onDisconnect: _onDisconnect.observable,
-  onMtu: _onMtu.observable,
+  onConnect: lazyEvent<ConnectionInfo>('connect'),
+  onDisconnect: lazyEvent<ConnectionInfo>('disconnect'),
+  onMtu: lazyEvent<MtuInfo>('mtu'),
 }
 
 export {ble, peripheral}

package/runtime/sys/types.ts

@@ -10,10 +10,23 @@ export interface MemoryUsage {
   /** Total system heap in bytes (0 on host) */
   systemTotal: number
   /** Largest contiguous free block in bytes (0 on host). Allocations
-   *  larger than this fail even when `systemFree` is bigger — the gap
+   *  larger than this fail even when `systemFree` is bigger; the gap
    *  between `systemLargestFree` and `systemFree` measures heap
    *  fragmentation. */
   systemLargestFree: number
+  /** Free internal-SRAM bytes (0 on host). On chips with PSRAM this is
+   *  the subset of free heap that lives in fast on-chip RAM, which
+   *  also holds mbedTLS handshake buffers, WiFi/BLE driver state, and
+   *  DMA-capable buffers. On PSRAM-equipped chips `systemFree` is
+   *  dominated by PSRAM and can hide internal-SRAM pressure: watch
+   *  `internalFree` instead when diagnosing TLS handshake or driver
+   *  allocation failures. On chips without PSRAM, equals `systemFree`. */
+  internalFree: number
+  /** Largest contiguous free block in internal SRAM (0 on host).
+   *  Allocations that must land in internal RAM (such as mbedTLS record
+   *  buffers, ~16 KB each) fail when this drops below their size, even
+   *  when `systemLargestFree` reports plenty of contiguous PSRAM. */
+  internalLargestFree: number
 }
 
 export interface Uptime {

package/runtime/wifi/wifi.ts

@@ -2,6 +2,7 @@ import {Observable} from 'mikrojs/observable'
 import {err, ok} from 'mikrojs/result'
 import {Wifi as NativeWifi} from 'native:wifi'
 
+import type {Subscriber} from '../observable/types.js'
 import type {Result} from '../result/types.js'
 import type {
   ApStartOptions,
@@ -37,22 +38,35 @@ const StatusFromCode = new Map<number, WifiStatus>(
 
 const native = new NativeWifi()
 
-/* One Observable per event type, each backed by a single native.on
- * registration. Subscribers share that registration via the multicast
- * source from Observable.withEmitters() — registering the listener once
- * keeps the C-level callback list at minimum size regardless of how many
- * JS subscribers are attached. */
-const _onConnect = Observable.withEmitters<WifiConnectionInfo>()
-const _onDisconnect = Observable.withEmitters<WifiDisconnectReason>()
-const _onRssiLow = Observable.withEmitters<number>()
-const _onStationConnect = Observable.withEmitters<ApStationInfo>()
-const _onStationDisconnect = Observable.withEmitters<ApStationInfo>()
-
-native.on('connect', (info) => _onConnect.next(info as WifiConnectionInfo))
-native.on('disconnect', (reason) => _onDisconnect.next(reason as WifiDisconnectReason))
-native.on('rssi-low', (rssi) => _onRssiLow.next(rssi as number))
-native.on('station-connect', (info) => _onStationConnect.next(info as ApStationInfo))
-native.on('station-disconnect', (info) => _onStationDisconnect.next(info as ApStationInfo))
+/* Lazy-attach Observable: native.on is only called once a JS subscriber
+ * appears, and native.off runs when the last one unsubscribes. Code paths
+ * that import wifi but don't subscribe (e.g. a fetch-only flow) take the
+ * exact same internal-RAM path as before observables existed — important
+ * because mbedTLS handshake needs ~16 KB contiguous internal SRAM and
+ * each eager closure pinned at module load chips into that headroom. */
+function lazyEvent<T>(eventName: string): Observable<T> {
+  const subscribers: Subscriber<T>[] = []
+  function handler(value: unknown): void {
+    /* Snapshot so unsubscribes during dispatch don't shift indices. */
+    const snapshot = subscribers.slice()
+    for (const s of snapshot) {
+      if (!s.closed) s.next(value as T)
+    }
+  }
+  return new Observable<T>((sub) => {
+    subscribers.push(sub)
+    if (subscribers.length === 1) {
+      native.on(eventName, handler)
+    }
+    sub.addTeardown(() => {
+      const i = subscribers.indexOf(sub)
+      if (i >= 0) subscribers.splice(i, 1)
+      if (subscribers.length === 0) {
+        native.off(eventName, handler)
+      }
+    })
+  })
+}
 
 const ap: WifiAp = {
   start(options: ApStartOptions): Result<void, WifiError> {
@@ -88,8 +102,8 @@ const ap: WifiAp = {
     native.apSetInactiveTimeout(seconds)
   },
 
-  onStationConnect: _onStationConnect.observable,
-  onStationDisconnect: _onStationDisconnect.observable,
+  onStationConnect: lazyEvent<ApStationInfo>('station-connect'),
+  onStationDisconnect: lazyEvent<ApStationInfo>('station-disconnect'),
 }
 
 const MAX_CONNECT_RETRIES = 5
@@ -147,9 +161,9 @@ const wifi: Wifi = {
     return ok(asyncResult.value as ScanResult[])
   },
 
-  onConnect: _onConnect.observable,
-  onDisconnect: _onDisconnect.observable,
-  onRssiLow: _onRssiLow.observable,
+  onConnect: lazyEvent<WifiConnectionInfo>('connect'),
+  onDisconnect: lazyEvent<WifiDisconnectReason>('disconnect'),
+  onRssiLow: lazyEvent<number>('rssi-low'),
 
   get mac(): string {
     const result = native.mac()

package/src/mem.cpp

@@ -5,6 +5,8 @@
 #include <stdlib.h>
 #include <string.h>
 
+#include "mikrojs/platform.h"
+
 /*
  * QuickJS uses malloc_usable_size to track memory consumption against its
  * memory limit. ESP-IDF lacks a standard malloc_usable_size, and the
@@ -61,3 +63,65 @@ void* mik__realloc(void* ptr, size_t size) {
     hdr_write(raw, size);
     return static_cast<char*>(raw) + HDR_SIZE;
 }
+
+/* QuickJS-heap allocator. When the PSRAM flag is set, route through the
+ * platform's malloc_psram first; if the platform can't satisfy the request
+ * (no PSRAM, or PSRAM exhausted), fall back to libc malloc so the runtime
+ * keeps working. The fallback only matters on host builds and in PSRAM-OOM
+ * edge cases. Under normal ESP32 operation with CONFIG_SPIRAM=y, every
+ * allocation lands in PSRAM. */
+
+static bool g_quickjs_heap_psram = false;
+
+void mik__set_quickjs_heap_psram(bool enable) {
+    g_quickjs_heap_psram = enable;
+}
+
+bool mik__is_quickjs_heap_psram(void) {
+    return g_quickjs_heap_psram;
+}
+
+void* mik__js_malloc(size_t size) {
+    void* raw = nullptr;
+    if (g_quickjs_heap_psram) {
+        const MIKPlatform* p = MIK_GetPlatform();
+        if (p && p->malloc_psram) {
+            raw = p->malloc_psram(size + HDR_SIZE);
+        }
+    }
+    if (!raw) raw = malloc(size + HDR_SIZE);
+    if (!raw) return nullptr;
+    hdr_write(raw, size);
+    return static_cast<char*>(raw) + HDR_SIZE;
+}
+
+void* mik__js_calloc(size_t count, size_t size) {
+    if (size && count > SIZE_MAX / size) return nullptr;
+    size_t total = count * size;
+    void* raw = nullptr;
+    if (g_quickjs_heap_psram) {
+        const MIKPlatform* p = MIK_GetPlatform();
+        if (p && p->calloc_psram) {
+            raw = p->calloc_psram(1, total + HDR_SIZE);
+        }
+    }
+    if (!raw) raw = calloc(1, total + HDR_SIZE);
+    if (!raw) return nullptr;
+    hdr_write(raw, total);
+    return static_cast<char*>(raw) + HDR_SIZE;
+}
+
+void* mik__js_realloc(void* ptr, size_t size) {
+    void* raw = ptr ? static_cast<char*>(ptr) - HDR_SIZE : nullptr;
+    void* new_raw = nullptr;
+    if (g_quickjs_heap_psram) {
+        const MIKPlatform* p = MIK_GetPlatform();
+        if (p && p->realloc_psram) {
+            new_raw = p->realloc_psram(raw, size + HDR_SIZE);
+        }
+    }
+    if (!new_raw) new_raw = realloc(raw, size + HDR_SIZE);
+    if (!new_raw) return nullptr;
+    hdr_write(new_raw, size);
+    return static_cast<char*>(new_raw) + HDR_SIZE;
+}

package/src/mik_sys.cpp

@@ -47,6 +47,10 @@ static JSValue mik__sys_memory_usage(JSContext* ctx, JSValue this_val, int argc,
                       JS_NewInt64(ctx, (int64_t)platform->get_total_system_mem()));
     JS_SetPropertyStr(ctx, obj, "systemLargestFree",
                       JS_NewInt64(ctx, (int64_t)platform->get_largest_free_system_mem()));
+    JS_SetPropertyStr(ctx, obj, "internalFree",
+                      JS_NewInt64(ctx, (int64_t)platform->get_free_internal_mem()));
+    JS_SetPropertyStr(ctx, obj, "internalLargestFree",
+                      JS_NewInt64(ctx, (int64_t)platform->get_largest_free_internal_mem()));
     return obj;
 }
 

package/src/mikrojs.cpp

@@ -17,16 +17,18 @@
 
 #define MIK__DEFAULT_STACK_SIZE 1024 * 1024  // 1 MB
 
-/* JS malloc functions */
+/* JS malloc functions. Routed through the mik__js_* family so the QuickJS
+ * heap can be relocated to PSRAM on chips with both internal SRAM and PSRAM,
+ * leaving internal SRAM free for mbedTLS, WiFi/BLE, and DMA buffers. */
 
 static void* mik__mf_calloc(void* opaque, size_t count, size_t size) {
     (void)opaque;
-    return mik__calloc(count, size);
+    return mik__js_calloc(count, size);
 }
 
 static void* mik__mf_malloc(void* opaque, size_t size) {
     (void)opaque;
-    return mik__malloc(size);
+    return mik__js_malloc(size);
 }
 
 static void mik__mf_free(void* opaque, void* ptr) {
@@ -36,7 +38,7 @@ static void mik__mf_free(void* opaque, void* ptr) {
 
 static void* mik__mf_realloc(void* opaque, void* ptr, size_t size) {
     (void)opaque;
-    return mik__realloc(ptr, size);
+    return mik__js_realloc(ptr, size);
 }
 
 static const JSMallocFunctions mik_mf = {
@@ -199,7 +201,11 @@ static void mik__promise_rejection_tracker(JSContext* ctx, JSValue promise, JSVa
 }
 
 void MIK_DefaultOptions(MIKRunOptions* options) {
-    static MIKRunOptions default_options = {.mem_limit = 0, .stack_size = MIK__DEFAULT_STACK_SIZE};
+    static MIKRunOptions default_options = {
+        .mem_limit = 0,
+        .stack_size = MIK__DEFAULT_STACK_SIZE,
+        .use_psram_heap = false,
+    };
 
     memcpy(options, &default_options, sizeof(*options));
 }
@@ -228,6 +234,12 @@ MIKRuntime* MIK_NewRuntimeInternal(MIKRunOptions* options) {
     memcpy(&mik_rt->options, options, sizeof(*options));
     MIK_DefaultConfig(&mik_rt->config);
 
+    /* Switch the QuickJS heap to PSRAM before constructing the runtime,
+     * so JS_NewRuntime2 and every subsequent QuickJS allocation lands
+     * in PSRAM. The MIKRuntime struct itself stays in internal SRAM:
+     * it was allocated before this point. */
+    mik__set_quickjs_heap_psram(options->use_psram_heap);
+
     rt = JS_NewRuntime2(&mik_mf, NULL);
     CHECK_NOT_NULL(rt);
     mik_rt->rt = rt;

package/src/platform_posix.cpp

@@ -45,6 +45,31 @@ static size_t posix_get_largest_free_system_mem(void) {
     return 0;  /* Not available on desktop */
 }
 
+static size_t posix_get_free_internal_mem(void) {
+    return 0;  /* No internal/PSRAM distinction on desktop */
+}
+
+static size_t posix_get_largest_free_internal_mem(void) {
+    return 0;  /* No internal/PSRAM distinction on desktop */
+}
+
+static void* posix_malloc_psram(size_t size) {
+    (void)size;
+    return NULL;  /* No PSRAM on desktop; caller falls back to libc */
+}
+
+static void* posix_calloc_psram(size_t count, size_t size) {
+    (void)count;
+    (void)size;
+    return NULL;
+}
+
+static void* posix_realloc_psram(void* ptr, size_t size) {
+    (void)ptr;
+    (void)size;
+    return NULL;
+}
+
 static bool posix_get_fs_info(const char* label, size_t* total, size_t* used) {
     (void)label;
     (void)total;
@@ -111,6 +136,11 @@ static const MIKPlatform posix_platform = {
     .get_min_free_system_mem = posix_get_min_free_system_mem,
     .get_total_system_mem = posix_get_total_system_mem,
     .get_largest_free_system_mem = posix_get_largest_free_system_mem,
+    .get_free_internal_mem = posix_get_free_internal_mem,
+    .get_largest_free_internal_mem = posix_get_largest_free_internal_mem,
+    .malloc_psram = posix_malloc_psram,
+    .calloc_psram = posix_calloc_psram,
+    .realloc_psram = posix_realloc_psram,
     .get_fs_info = posix_get_fs_info,
     .log = posix_log,
     .stdout_write = posix_stdout_write,