Skip to content

fix: require quickbeam >= 0.11.1 for a release-optimized SSR NIF - #155

Open
dannote wants to merge 1 commit into
Valian:mainfrom
dannote:chore/quickbeam-0.11
Open

dannote wants to merge 1 commit into
Valian:mainfrom
dannote:chore/quickbeam-0.11

Conversation

@dannote

@dannote dannote commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Bumps the required QuickBEAM version to >= 0.11.1 (from ~> 0.8).

Why

QuickBEAM's precompiled NIFs were built in Zig debug mode up to and including 0.11.0 (elixir-volt/quickbeam#23). optimize: :env resolves from Mix.env(), and the release workflow set no ZIGLER_RELEASE_MODE, so every published artifact was compiled .Debug.

This matters for SSR because max_stack_size — 8 MB by default, and LiveVue configures no limits — is not a JS frame counter. It caps the native C stack, and every JS call spends real stack. Unoptimized frames are ~140x fatter, so for the same budget you get vastly fewer calls. Measured on aarch64-macos, same script, 0.11.0 vs 0.11.1:

max_stack_size 0.11.0 (debug) 0.11.1 (release)
1 MB 6 1,006
2 MB 13 2,015
8 MB (default) 57 8,064

So on 0.11.0 and earlier, SSR had a ceiling of ~57 nested JS calls. Deeply nested component trees could overflow the JS stack mid-render, and it isn't tunable away: matching 8,064 frames in debug would need ~1.1 GB of stack.

0.11.1 fixed the build. It also requires mint >= 1.10 (CVE-2026-82728, CVE-2026-82729), so that comes along too.

Changes

  • mix.exs: ~> 0.8 → >= 0.11.1 and < 1.0.0
  • Installer, moduledoc, missing-dependency message, guides: ~> 0.11.1
  • CHANGELOG entry

mix.exs uses a range rather than ~> 0.11.1 so the ceiling is unchanged — the old ~> 0.8 already meant < 1.0.0. The installer and docs keep ~> 0.11.1, since that's advice for an app's own dependencies.

No code changes: start/2, call/4, and load_module/3 are unchanged in 0.11.1.

Upgrade note

Apps on loose constraints (~> 0.8, ~> 0.10) resolve to 0.11.1 with no action. Apps pinned to a specific minor need to bump, and the resolver says so clearly:

Because "your app" depends on "live_vue" which depends on
"quickbeam >= 0.11.1 and < 1.0.0", "quickbeam >= 0.11.1 and < 1.0.0" is required.
So, because "your app" depends on "quickbeam ~> 0.10.20", version solving failed.

Verification

  • mix test — 228/230; the 2 failures are the phx_new archive missing locally, unrelated
  • QuickBEAM/SSR tests — 17/17
  • Installed NIF is identical to the published v0.11.1 artifact: __TEXT vmsize 0x1f8fd8 and 24,008 symbols, both exact (debug was 0xbfb8b4 / 100,924)

Precompiled QuickBEAM NIFs were built in Zig debug mode up to and
including 0.11.0 (elixir-volt/quickbeam#23). quickbeam declares
`optimize: :env`, and Zigler resolves that from ZIGLER_RELEASE_MODE,
falling back to Mix.env() -- :debug for dev/test. The release workflow
set neither, so published artifacts were compiled with `.Debug`.

This matters because max_stack_size is not a JS-level frame counter:
JS_SetMaxStackSize/2 caps the native C stack, and each JS call frame
spends real native stack. Debug frames are uninlined and keep separate
stack slots per temporary, inflating every frame by ~2 orders of
magnitude. LiveVue configures no limits, so it inherited the debug
ceiling silently.

Measured on aarch64-macos, quickbeam 0.11.0 vs 0.11.1:

  max_stack_size    0.11.0     0.11.1
  1 MB                   6       1006
  2 MB                  13       2015
  8 MB (default)        57       8064

That is ~141x more nested JS calls for the same 8 MB, i.e. ~147 KB per
frame in debug vs ~1 KB in release. The floor is 0.11.1 rather than
0.11 because 0.11.0 still ships the debug build.

mix.exs uses ">= 0.11.1 and < 1.0.0" rather than "~> 0.11.1" to preserve
the existing ceiling: the previous "~> 0.8" already meant "< 1.0.0", and
a "~> 0.11.1" requirement would have started rejecting 0.12+. The
installer, moduledoc, and guides keep "~> 0.11.1" as app-level advice,
where tight pinning is appropriate.

No code changes needed: start/2, call/4, and load_module/3 are
unchanged in 0.11.1.
@dannote
dannote force-pushed the chore/quickbeam-0.11 branch from 464c241 to e37c3cd Compare September 12, 2026 17:34
@dannote

dannote commented Sep 12, 2026

Copy link
Copy Markdown
Contributor Author

Hm, the 1.15 / OTP 25 and E2E failures aren't from this change — it's a QuickBEAM bug:

lib/quickbeam/vm/abi/source.ex:54 — ^prefix <> rest

That needs Elixir 1.16+, but QuickBEAM declares ~> 1.15 and its CI only runs 1.20, so nobody noticed.

Will fix it in QuickBEAM and update this PR.

@Valian

Valian commented Sep 14, 2026

Copy link
Copy Markdown
Owner

Ok thank you for that PR, will merge and release as soon as you'll finish this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants