@mikrojs/firmware 0.18.0 → 0.18.1

package/components/mikrojs/mik_ota_env.cpp

@@ -0,0 +1,370 @@
+/**
+ * MIKOtaEnv for ESP-IDF: the platform side of the native OTA client.
+ *
+ * Every seam here is deliberately thin. The parts that are easy to get subtly
+ * wrong — how a mik.sys value is encoded, how the device-name pair is spelled —
+ * live in the portable library behind host tests (mikrojs/sys_codec.h), because
+ * getting them wrong means the C and JS implementations disagree about live
+ * device state in a way no compile catches.
+ */
+
+#include <esp_app_desc.h>
+#include <esp_random.h>
+#include <esp_system.h>
+#include <esp_timer.h>
+#include <nvs.h>
+
+#include <cstdio>
+#include <cstring>
+
+#include "esp_log.h"
+#include "mik_http_internal.h"
+#include "mik_ota_native.h"
+#include "mikrojs/mikrojs.h"
+#include "mikrojs/private.h"
+#include "mikrojs/platform.h"
+#include "mikrojs/sys_codec.h"
+
+#define MIK_OTA_ENV_TAG "native:mikro/ota_client"
+#define MIK_OTA_SYS_NS "mik.sys"
+
+namespace {
+
+/* One env per runtime. The OTA client is a singleton within a runtime (one
+ * check-in loop per device), so a file-scope record is the whole lifetime story. */
+struct EnvState {
+    MIKOtaEnv env;
+    MIKRuntime* rt;
+    int bytecode_version;
+    /* The device id string the platform owns; copied so identity() can hand back
+     * a fixed-size field without worrying about the platform's lifetime. */
+    char device_id[64];
+};
+
+EnvState g_state = {};
+
+// ── kv (mik.sys) ─────────────────────────────────────────────────────────────
+// Values are the CBOR encoding of the value itself, exactly as
+// native:mikro/nvs_kv writes them, so `ota.tries` means the same thing whether
+// the C policy or the JS one reads it.
+
+/* Absence is the only silent outcome: a missing namespace (nothing ever stored)
+ * or a missing key reads as absent. Every other failure is an error, so a read
+ * starved by heap pressure — nvs_open allocates its handle — is never mistaken
+ * for "not stored". Same rule as native:mikro/nvs_kv's get. */
+MIKOtaKvStatus kv_read_blob(const char* key, uint8_t* out, size_t* inout_len) {
+    nvs_handle_t h;
+    esp_err_t err = nvs_open(MIK_OTA_SYS_NS, NVS_READONLY, &h);
+    if (err == ESP_ERR_NVS_NOT_FOUND) return MIK_OTA_KV_ABSENT;
+    if (err != ESP_OK) return MIK_OTA_KV_ERROR;
+
+    size_t len = 0;
+    err = nvs_get_blob(h, key, nullptr, &len);
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
+        nvs_close(h);
+        return MIK_OTA_KV_ABSENT;
+    }
+    if (err != ESP_OK) {
+        nvs_close(h);
+        return MIK_OTA_KV_ERROR;
+    }
+    if (len == 0) {
+        nvs_close(h);
+        return MIK_OTA_KV_ABSENT;
+    }
+    if (!out) {
+        *inout_len = len;
+        nvs_close(h);
+        return MIK_OTA_KV_OK;
+    }
+    if (*inout_len < len) {
+        nvs_close(h);
+        return MIK_OTA_KV_ERROR;
+    }
+    err = nvs_get_blob(h, key, out, &len);
+    nvs_close(h);
+    if (err != ESP_OK) return MIK_OTA_KV_ERROR;
+    *inout_len = len;
+    return MIK_OTA_KV_OK;
+}
+
+bool kv_write_blob(const char* key, const uint8_t* data, size_t len) {
+    nvs_handle_t h;
+    if (nvs_open(MIK_OTA_SYS_NS, NVS_READWRITE, &h) != ESP_OK) return false;
+    esp_err_t err = nvs_set_blob(h, key, data, len);
+    if (err == ESP_OK) err = nvs_commit(h);
+    nvs_close(h);
+    return err == ESP_OK;
+}
+
+MIKOtaKvStatus env_kv_get_blob(void*, const char* key, uint8_t* out, size_t* inout_len) {
+    return kv_read_blob(key, out, inout_len);
+}
+
+bool env_kv_set_blob(void*, const char* key, const uint8_t* data, size_t len) {
+    return kv_write_blob(key, data, len);
+}
+
+bool env_kv_get_str(void*, const char* key, char* out, size_t max_len) {
+    uint8_t buf[320];
+    size_t len = sizeof(buf);
+    if (kv_read_blob(key, buf, &len) != MIK_OTA_KV_OK) return false;
+    return mik__kv_decode_str(buf, len, out, max_len);
+}
+
+bool env_kv_set_str(void*, const char* key, const char* value) {
+    uint8_t buf[320];
+    size_t needed = mik__kv_encode_str(value, buf, sizeof(buf));
+    if (needed > sizeof(buf)) return false;
+    return kv_write_blob(key, buf, needed);
+}
+
+bool env_kv_get_i32(void*, const char* key, int32_t* out) {
+    uint8_t buf[16];
+    size_t len = sizeof(buf);
+    if (kv_read_blob(key, buf, &len) != MIK_OTA_KV_OK) return false;
+    return mik__kv_decode_i32(buf, len, out);
+}
+
+bool env_kv_set_i32(void*, const char* key, int32_t value) {
+    uint8_t buf[16];
+    size_t needed = mik__kv_encode_i32(value, buf, sizeof(buf));
+    if (needed > sizeof(buf)) return false;
+    return kv_write_blob(key, buf, needed);
+}
+
+bool env_kv_remove(void*, const char* key) {
+    nvs_handle_t h;
+    if (nvs_open(MIK_OTA_SYS_NS, NVS_READWRITE, &h) != ESP_OK) return false;
+    esp_err_t err = nvs_erase_key(h, key);
+    if (err == ESP_OK) err = nvs_commit(h);
+    nvs_close(h);
+    /* A key that was never there is not a failure: the client removes slots
+     * unconditionally. */
+    return err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND;
+}
+
+// ── HTTP ─────────────────────────────────────────────────────────────────────
+// Borrowed from native:mikro/http: its task, TLS setup, inflight ceiling and
+// chunk budget. A second esp_http_client path would double the handshake heap
+// spike this device has the least of.
+
+void* env_http_request(void* opaque, const MIKOtaHttpRequest* req,
+                       const MIKOtaHttpCallbacks* cbs) {
+    auto* state = static_cast<EnvState*>(opaque);
+    MIKHttpNativeRequest spec = {};
+    spec.url = req->url;
+    spec.method = req->method;
+    spec.header_keys = req->header_keys;
+    spec.header_values = req->header_values;
+    spec.header_count = req->header_count;
+    spec.body = req->body;
+    spec.body_len = req->body_len;
+    spec.timeout_ms = req->timeout_ms;
+
+    MIKHttpNativeSink sink = {};
+    sink.headers = cbs->headers;
+    sink.data = cbs->data;
+    sink.done = cbs->done;
+    sink.user_data = cbs->user_data;
+
+    uint32_t id = mik__http_start_native(state->rt, &spec, &sink);
+    if (id == 0) return nullptr;
+    /* The handle is the id, offset so it is never NULL for id 0's sake. */
+    return reinterpret_cast<void*>(static_cast<uintptr_t>(id));
+}
+
+void env_http_cancel(void* opaque, void* handle) {
+    auto* state = static_cast<EnvState*>(opaque);
+    mik__http_cancel_native(state->rt, static_cast<uint32_t>(reinterpret_cast<uintptr_t>(handle)));
+}
+
+// ── identity and system ──────────────────────────────────────────────────────
+
+bool env_identity(void* opaque, MIKDeviceIdentity* out) {
+    auto* state = static_cast<EnvState*>(opaque);
+    if (!out) return false;
+    *out = {};
+    snprintf(out->device_id, sizeof(out->device_id), "%s", state->device_id);
+#ifdef MIK_FW_VERSION
+    snprintf(out->firmware_version, sizeof(out->firmware_version), "%s", MIK_FW_VERSION);
+#else
+    snprintf(out->firmware_version, sizeof(out->firmware_version), "0.0.0-dev");
+#endif
+    const esp_app_desc_t* desc = esp_app_get_description();
+    for (int i = 0; i < 32; i++) {
+        snprintf(out->firmware_hash + i * 2, 3, "%02x", desc->app_elf_sha256[i]);
+    }
+    out->bytecode_version = state->bytecode_version;
+    return true;
+}
+
+bool env_storage_free(void*, size_t* out) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    size_t total = 0;
+    size_t used = 0;
+    if (!platform->get_fs_info || !platform->get_fs_info("user", &total, &used)) return false;
+    if (out) *out = total > used ? total - used : 0;
+    return true;
+}
+
+bool env_get_device_name(void*, int* out_rev, char* out_name, size_t name_len) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    const char* stored = platform->get_device_name ? platform->get_device_name() : nullptr;
+    if (!stored) return false;
+    /* A pair that will not parse reads as never named, matching the JS reader. */
+    return mik__device_name_parse(stored, out_rev, out_name, name_len);
+}
+
+void env_set_device_name(void*, int rev, const char* name) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    if (!platform->set_device_name) return;
+    char text[160];
+    size_t needed = mik__device_name_format(rev, name, text, sizeof(text));
+    if (needed >= sizeof(text)) return;  /* an absurd name: leave the pair alone */
+    platform->set_device_name(text);
+}
+
+void env_restart(void*) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    if (platform->restart) platform->restart();
+}
+
+int64_t env_monotonic_ms(void*) { return esp_timer_get_time() / 1000; }
+
+double env_random_fraction(void*) {
+    /* esp_random is uniform over the full 32-bit range; scale to [0, 1). */
+    return static_cast<double>(esp_random()) / 4294967296.0;
+}
+
+void env_log(void*, int level, const char* fmt, ...) {
+    va_list args;
+    va_start(args, fmt);
+    char buf[320];
+    vsnprintf(buf, sizeof(buf), fmt, args);
+    va_end(args);
+    switch (level) {
+        case MIK_LOG_ERROR:
+            ESP_LOGE(MIK_OTA_ENV_TAG, "%s", buf);
+            break;
+        case MIK_LOG_WARN:
+            ESP_LOGW(MIK_OTA_ENV_TAG, "%s", buf);
+            break;
+        case MIK_LOG_DEBUG:
+            ESP_LOGD(MIK_OTA_ENV_TAG, "%s", buf);
+            break;
+        default:
+            ESP_LOGI(MIK_OTA_ENV_TAG, "%s", buf);
+            break;
+    }
+}
+
+/* Join a JS-level app path onto the runtime's fs base, the way the fs layer
+ * does for `readFile('/app/...')`. */
+void resolve_app_path(EnvState* state, const char* leaf, char* out, size_t out_len) {
+    const char* root = state && state->rt
+                           ? (state->rt->fs_root ? state->rt->fs_root : state->rt->fs_base_path)
+                           : nullptr;
+    snprintf(out, out_len, "%s%s", root ? root : "", leaf);
+}
+
+char* env_read_manifest(void* opaque) {
+    auto* state = static_cast<EnvState*>(opaque);
+    char path[128];
+    resolve_app_path(state, "/app/mikro.app.json", path, sizeof(path));
+    FILE* f = fopen(path, "r");
+    if (!f) return nullptr;
+    fseek(f, 0, SEEK_END);
+    long size = ftell(f);
+    /* A manifest is a few hundred bytes of metadata plus whatever configDefaults
+     * carries. The bound is generous but present: this is read into RAM. */
+    if (size <= 0 || size > 8192) {
+        fclose(f);
+        return nullptr;
+    }
+    rewind(f);
+    char* text = static_cast<char*>(malloc(static_cast<size_t>(size) + 1));
+    if (!text) {
+        fclose(f);
+        return nullptr;
+    }
+    size_t read = fread(text, 1, static_cast<size_t>(size), f);
+    fclose(f);
+    text[read] = '\0';
+    return text;
+}
+
+bool env_read_app_version(void* opaque, char* out, size_t out_len) {
+    auto* state = static_cast<EnvState*>(opaque);
+    /* The live app version, the same file `ota.ts` reads as /app/package.json.
+     * That is a JS-level path: the fs layer joins it onto the runtime's base
+     * path, so reaching it from C means joining it here too. Read with stdio
+     * rather than through the JS fs layer, because the client runs from C and
+     * must not need a JSContext for a report field. */
+    char path[128];
+    resolve_app_path(state, "/app/package.json", path, sizeof(path));
+    FILE* f = fopen(path, "r");
+    if (!f) return false;
+    /* First 511 bytes only: enough for the small package.json a packed app
+     * carries. A "version" key past that, or a nested one before the top-level
+     * key, misreports; keep version near the top of package.json. */
+    char buf[512];
+    size_t read = fread(buf, 1, sizeof(buf) - 1, f);
+    fclose(f);
+    buf[read] = '\0';
+
+    /* Minimal scan for the top-level "version" string. A full JSON parse would
+     * mean pulling one in for a single field. */
+    const char* key = strstr(buf, "\"version\"");
+    if (!key) return false;
+    const char* colon = strchr(key, ':');
+    if (!colon) return false;
+    const char* quote = strchr(colon, '"');
+    if (!quote) return false;
+    const char* end = strchr(quote + 1, '"');
+    if (!end) return false;
+    size_t len = static_cast<size_t>(end - quote - 1);
+    if (len == 0 || len + 1 > out_len) return false;
+    memcpy(out, quote + 1, len);
+    out[len] = '\0';
+    return true;
+}
+
+}  // namespace
+
+const MIKOtaEnv* mik__ota_env_for(MIKRuntime* rt, int bytecode_version) {
+    g_state.rt = rt;
+    g_state.bytecode_version = bytecode_version;
+    const MIKPlatform* platform = MIK_GetPlatform();
+    const char* id = platform->get_device_id ? platform->get_device_id() : nullptr;
+    snprintf(g_state.device_id, sizeof(g_state.device_id), "%s", id ? id : "");
+
+    MIKOtaEnv& env = g_state.env;
+    env = {};
+    env.opaque = &g_state;
+
+    env.http_request = env_http_request;
+    env.http_cancel = env_http_cancel;
+
+    env.kv_get_blob = env_kv_get_blob;
+    env.kv_set_blob = env_kv_set_blob;
+    env.kv_get_str = env_kv_get_str;
+    env.kv_set_str = env_kv_set_str;
+    env.kv_get_i32 = env_kv_get_i32;
+    env.kv_set_i32 = env_kv_set_i32;
+    env.kv_remove = env_kv_remove;
+
+    mik__ota_fill_install_ops(&env);
+
+    env.identity = env_identity;
+    env.storage_free = env_storage_free;
+    env.get_device_name = env_get_device_name;
+    env.set_device_name = env_set_device_name;
+    env.restart = env_restart;
+    env.monotonic_ms = env_monotonic_ms;
+    env.random_fraction = env_random_fraction;
+    env.log = env_log;
+    env.read_app_version = env_read_app_version;
+    env.read_manifest = env_read_manifest;
+    return &env;
+}

package/components/mikrojs/test/ota_host/run.sh

@@ -93,9 +93,14 @@ echo "== corrupt/truncated rejection =="
 head -c "$(( $(wc -c < "$BUILD/small.tgz") - 16 ))" "$BUILD/small.tgz" > "$BUILD/trunc.tgz"
 "$TEST" expect-fail "$BUILD/trunc.tgz" "$BUILD/out_trunc" >/dev/null && echo "  truncated rejected ✓" \
     || { echo "FAIL: truncated build was accepted"; exit 1; }
-# Corrupt: flip a byte in the deflate body.
+# Corrupt: flip a byte in the deflate body. XOR rather than overwrite: the
+# fixture's compressed bytes shift with the host's gzip, and overwriting with a
+# constant is a no-op whenever the byte already holds that value, which turns
+# this case into "valid build rejected as accepted" on some runner images.
 cp "$BUILD/large.tgz" "$BUILD/corrupt.tgz"
-printf '\xff' | dd of="$BUILD/corrupt.tgz" bs=1 seek=64 count=1 conv=notrunc 2>/dev/null
+orig=$(dd if="$BUILD/corrupt.tgz" bs=1 skip=64 count=1 2>/dev/null | od -An -tu1 | tr -d ' ')
+printf "\\$(printf '%03o' $((orig ^ 0x5a)))" \
+    | dd of="$BUILD/corrupt.tgz" bs=1 seek=64 count=1 conv=notrunc 2>/dev/null
 "$TEST" expect-fail "$BUILD/corrupt.tgz" "$BUILD/out_corrupt" >/dev/null && echo "  corrupt rejected ✓" \
     || { echo "FAIL: corrupt build was accepted"; exit 1; }
 # Not gzip at all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/firmware",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Mikro.js ESP32 firmware: ESP-IDF component, build tools, and project template",
   "keywords": [
     "esp-idf",
@@ -47,8 +47,8 @@
   },
   "dependencies": {
     "esbuild": "^0.28.0",
-    "@mikrojs/native": "0.18.0",
-    "@mikrojs/quickjs": "0.18.0"
+    "@mikrojs/native": "0.18.1",
+    "@mikrojs/quickjs": "0.18.1"
   },
   "engines": {
     "node": ">=24.0.0"

package/sdkconfig.defaults

@@ -32,6 +32,22 @@ CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH=y
 CONFIG_ESP_WIFI_IRAM_OPT=n
 CONFIG_ESP_WIFI_RX_IRAM_OPT=n
 
+# Trim WiFi driver buffers toward Espressif's low-RAM rank. The IDF defaults
+# left too little heap for a TLS handshake next to a JS runtime on no-PSRAM
+# chips. STATIC_RX is a real ~1.6 KB/buffer allocation made at wifi init; the
+# DYNAMIC_* counts are ceilings, so they raise the guaranteed-free floor
+# rather than idle heap. Paired with the lwIP window below, which the WiFi
+# performance guide says must track the DYNAMIC_* counts.
+CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=6
+CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=10
+CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM=10
+# IDF default, and within the guide's min(2 x STATIC_RX, DYNAMIC_RX) bound.
+# Lower values throttle downlink aggregation for a few pointers of RAM; to
+# actually reclaim the reorder path, disable AMPDU RX instead.
+CONFIG_ESP_WIFI_RX_BA_WIN=6
+# Management short buffers. 6 is the Kconfig minimum and enough for a station.
+CONFIG_ESP_WIFI_MGMT_SBUF_NUM=6
+
 # SPI master ISR doesn't need to run during flash writes
 CONFIG_SPI_MASTER_ISR_IN_IRAM=n
 
@@ -106,6 +122,31 @@ CONFIG_HAL_DEFAULT_ASSERTION_LEVEL=0
 # native module won't even compile. Cost is roughly 5–10 KB flash.
 CONFIG_LWIP_IPV6=y
 
+# TIME_WAIT is 2xMSL. At the lwIP default (60s MSL) every closed TLS
+# connection leaves heap residue for two minutes; on a client checking in
+# on an interval, that residue fragments the heap until TLS handshakes
+# fail (measured on esp32c6: largest free block ratchets down each round).
+# 6s is safe for an outbound-only client: stale-segment reuse needs the
+# same ephemeral port against the same server inside the window, and a
+# stale segment that did land fails the TLS record MAC anyway. Note this is
+# a global lwIP setting: in SoftAP mode the device is the side that lands in
+# TIME_WAIT, where a short MSL is a weaker guarantee.
+CONFIG_LWIP_TCP_MSL=6000
+# FIN_WAIT_2 is the same lingering-socket story when the peer half-closes;
+# the IDF lwIP guide names both timers for minimum-RAM builds.
+CONFIG_LWIP_TCP_FIN_WAIT_TIMEOUT=6000
+
+# Per-connection TCP buffering, and the paired half of the WiFi DYNAMIC_*
+# counts above. 2880 is 2xMSS: it halves lwIP's per-connection peak, at the
+# cost of roughly doubling OTA image download time on a high-latency path.
+CONFIG_LWIP_TCP_SND_BUF_DEFAULT=2880
+CONFIG_LWIP_TCP_WND_DEFAULT=2880
+# Out-of-order segments are held as heap pbufs per pcb until the gap fills,
+# which is exactly when a handshake wants a large contiguous block.
+CONFIG_LWIP_TCP_OOSEQ_MAX_PBUFS=2
+# Bounds how many pbufs can queue up waiting on the tcpip task.
+CONFIG_LWIP_TCPIP_RECVMBOX_SIZE=12
+
 # --- MbedTLS: TLS 1.2 only, AES-GCM/CCM, ECDHE ---
 # 1.3's handshake working state plus its Kconfig-forced
 # KEEP_PEER_CERTIFICATE add several KB of peak heap per connection, so disable for now
@@ -125,6 +166,10 @@ CONFIG_MBEDTLS_FS_IO=n
 # Allocate TLS record buffers on demand (vs. a fixed 16 KB IN +
 # 4 KB OUT block alive per connection). Incompatible with DTLS.
 CONFIG_MBEDTLS_DYNAMIC_BUFFER=y
+# Every handshake TX step allocates OUT_CONTENT_LEN + record overhead, and it
+# does so while the RX certificate buffer is still live. Caps the outbound
+# record size, so large request bodies split across more records.
+CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN=2048
 
 # Drop the peer cert chain after handshake validates it (~4 KB per
 # connection). Note: TLS 1.3 force-selects this back on via Kconfig.
@@ -140,5 +185,18 @@ CONFIG_MBEDTLS_ECP_DP_BP512R1_ENABLED=n
 
 # Use smaller cert bundle (common CAs only)
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN=y
+# Deliberate deviation from IDF 6.0.2, which defaults this to n to save ~700 B
+# of heap. We need it: with n, esp_crt_bundle looks up only the top served
+# cert's issuer, so any chain that serves a cross-signed root fails outright.
+# That is ~2 in 5 real hosts, mostly Google Trust Services roots cross-signed
+# by GlobalSign: openai, anthropic, cloudflare, npm, pypi, discord, googleapis.
+# Device-confirmed against registry.npmjs.org (MBEDTLS_ERR_X509_FATAL_ERROR,
+# -0x3000). Neither cross-signing root ships in the CMN or the full bundle, so
+# bundle selection is not an escape either.
+#
+# The cost on 6.0.2 is a leak: ~215 B of issuer-name copies per successful
+# handshake, ~10 KB/day at a 30-minute check-in cadence. Fixed upstream by
+# 0d8ff68f8a47 and a1f1d9072900, landing in an upcoming release. Until our
+# IDF floor gets there, patch IDF rather than turning this off.
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY=y