Skip to content

feat(runtime): guard native methods against instance shadowing in debug builds (rooted/canary) - #593

Draft
edusperoni wants to merge 2 commits into
fix/canary-weak-collectionsfrom
feat/native-member-guard
Draft

edusperoni wants to merge 2 commits into
fix/canary-weak-collectionsfrom
feat/native-member-guard

Conversation

@edusperoni

@edusperoni edusperoni commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #592.

In the rooted and canary wrapper lifetime modes, a JS wrapper can die while its native object lives. In canary mode, a wrapper is rebuilt when native code hands the object back. Assigning a native method's name on an instance (obj.isEqual = fn) was always JS-only: native code calls the class's implementation, never a JS own property of a native object. In these modes the shadow can also be lost silently when the wrapper is rebuilt. This PR makes that assignment throw in debug builds, so the mistake shows up during development.

Behavior

Debug builds (RuntimeConfig.IsDebug) with wrapperLifetime.mode "rooted" or "canary", any scope, unless "allowShadowingNativeMembers": true:

  • Native instance methods on native class prototypes become accessor pairs. That covers protocol members and protocol-binding prototypes, toString, and NSArray's Symbol.iterator.
    • The getter returns the same function every time, so obj.m === obj.m, typeof, .call/.bind, in, super.m() and _super.prototype.m.call(this) are unchanged.
    • The setter throws a TypeError when the receiver is a native object wrapper, a released one, or a Proxy around one. The message names the method, the class, the mode and the escape hatch. Any other receiver gets the own data property a plain assignment would create. That keeps __extends / @NativeClass child prototypes, Object.create(wrapper) and extend() overrides working.
  • Klass.prototype.m = fn still swizzles once. That name then becomes a plain data property and is no longer guarded.
  • Not covered:
    • constructor;
    • static methods (constructor functions are never rebuilt);
    • native properties (already accessors);
    • JS-defined methods of extended classes;
    • define-semantics writes: class fields and Object.defineProperty, which is the documented escape route.
  • Visible change in guarded builds: Object.getOwnPropertyDescriptor(UIView.prototype, "setNeedsLayout") is { get, set, enumerable, configurable }.
  • Release builds and "resurrecting" keep plain data properties. On an iPhone 11 Pro (jitless), a guard accessor costs +11 to +15 ns per method load. An API (C++) getter was also measured and rejected: V8 sends super.m loads through an API getter to the slow path (about +100 ns), while the JS closure getter adds about +8 ns there.
  • getConfig("wrapperLifetimeAllowShadowingNativeMembers") reads the new key; it is read-only at runtime, like the other wrapper lifetime keys.

JS-extended classes (second commit)

On iOS, native code calls a JS-extended class's method through the function captured when the class is defined, never through an instance property. So an instance assignment over such a method is just as invisible to native code. In the same debug condition, these methods become accessor pairs on the prototype level that defines them:

  • exposed methods (exposedMethods / ObjCExposedMethods);
  • overrides of native methods;
  • protocol implementations;
  • a JS Symbol.iterator the class uses for native fast enumeration.

They're installed when extend() returns, or in +initialize for __extends / @NativeClass classes. Assigning one on a native instance throws, with the same kind of message and escape hatch as native members.

JS-only methods stay plain data properties. This needs no forwarding canary: extended instances keep the masking mirror. Native dispatch, super, _super.prototype.m.call(this), prototype-level replacement and Object.create(instance) receivers keep working. The #593 spec that expected these overrides to stay writable now expects the guard.

Suite on the tip: 2194 specs, 0 failures in resurrecting/extended, rooted/all, canary/all, canary/extended and canary/all + allowShadowingNativeMembers.

Implementation

  • MetadataBuilder collects the method names it registers. After the prototype is instantiated, before PublishNativeSetters, it swaps each own data function for the accessor pair. The getter comes from a JS factory compiled once per isolate. The setter is one C++ function whose data is the property name.
  • A thread-local flag makes the prototype's swizzle handlers stand down while the guard installs accessors and while its setter defines the replacement property. So a prototype write swizzles exactly once, and an accessor pair the guard installs is never read as a native property's.
  • WrapperLifetime::ReadConfig computes one process-wide flag: debug, guarded mode and no escape hatch.

Specs

  • NativeMemberGuardTests.js (new, with TNSNativeMemberGuard fixtures). It checks:
    • throws in strict and sloppy code;
    • Proxy and released receivers;
    • toString and Symbol.iterator;
    • identity, call/bind/in;
    • prototype swizzles, __extends, extend() overrides with native dispatch, super and _super;
    • Object.create and defineProperty;
    • the descriptor shape;
    • no guard in "resurrecting" or with the escape hatch.
  • WrapperLifetimeModesTests.js: the spec that shadowed isEqual on an instance now expects the TypeError in guarded modes.

Testing

2173 specs in each run:

Run Failures
canary/all 0
canary/extended 0
resurrecting/extended 0
canary/all + allowShadowingNativeMembers 0
ASan canary/all 0
rooted/all 1 intermittent

The rooted/all failure was in the leak-probe "planted shapes" specs, in 2 of 5 runs. Four later runs were clean, with the guard on and off. It looks timing-dependent and unrelated to the guard; #591 reworks that area.

@coderabbitai

coderabbitai Bot commented Nov 21, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

…ng in debug builds

In debug builds under the "rooted" and "canary" wrapper lifetime modes,
assigning a native instance method's name on a native object throws a
TypeError: native code never calls a JS own property of a native object,
so the assignment only changes what JS callers see.

Native instance methods (protocol members included, and those of protocol
bindings), toString and NSArray's Symbol.iterator become accessor pairs on
their prototype once it is instantiated. The getter is a JS closure that
returns the original function, so reads, identity and super loads stay on
V8's fast paths. The setter throws for a native, released or proxied
native receiver and otherwise creates the own data property an assignment
would, so prototype-level writes still swizzle (once) and subclass
prototypes and objects inheriting from native ones are unaffected.
Object.defineProperty remains the route to a JS-only own member.

"wrapperLifetime": { "allowShadowingNativeMembers": true } turns the guard
off; ns:runtime exposes it read-only as
wrapperLifetimeAllowShadowingNativeMembers. Release builds and the
resurrecting mode keep data properties.
@edusperoni
edusperoni force-pushed the feat/native-member-guard branch from e688a0f to 58ab800 Compare November 21, 2026 20:53
@edusperoni
edusperoni changed the base branch from main to fix/canary-weak-collections November 21, 2026 20:53
…uilds

Native code calls a JS-extended class's exposed methods, its overrides of
native methods and its protocol implementations through the function the
class captured when it was built, never through an instance's own property.
Assigning one of those names on an instance therefore changes the method for
JS callers only, as with native members.

In debug builds under the "rooted" and "canary" modes, unless
"allowShadowingNativeMembers" is set, those methods become accessor pairs on
the prototype level that defines them (an extend() implementation object
once extend() returns, an __extends or @nativeclass prototype in the class's
+initialize), using the native member guard's getter closures. Assigning one
on a native object throws a TypeError naming the method, class, mode and
escape hatch; other receivers (subclass prototypes, objects inheriting from
an instance) get the own data property. JS-only methods stay data
properties. A second +initialize pass over a prototype reads a guarded
method back through its marked getter.

Release builds and the "resurrecting" mode are unchanged.

This branch has not been deployed

No deployments
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.

1 participant