v0.8.1

[vfsfitvnm]

This is another important release!

JS vs C

Internally, frida-il2cpp-bridge used a CModule to implement missing or additional IL2CPP internals (let's refer to these ones as internal fallbacks).
This solution allowed the codebase to not be aware whether a specific IL2CPP internal was present or not, and had a positive impact on code consistency.

However, this solution had a practical drawback and mental one.

The former was the impossibility to use any of the internal fallbacks before, well, the creation of the CModule itself! This is obvious (you can't enter a room without opening its door, can you?), but the nasty thing was some internal fallbacks had a dependency on another internal fallbacks, but the creation of the CModule is atomic, so I couldn't use some internal fallbacks before having other internal fallbacks compiled.
Long story short: I couldn't implement 20f6923 and 7c766ec.

The latter is, whenever it came to add a new property to a IL2CPP struct (e.g. Il2Cpp.Domain::object), I didn't know if it would have made sense to implement it in C (e.g. 43d3659).
This resulted in a cognitive load spike!
The only advantage of using C is speed. Like, 20x/50x improvement over JS. I'll admit: having Il2Cpp::dump complete in one fifth of the time and Il2Cpp::backtracer initialize in one twentieth of the time was very tempting.
However, after writing a proof of concept, I realized it wasn't worth it.

Eventually, my final decision was to implement the internal fallbacks in JS (exception made for Il2Cpp::MemorySnapshot internals): 20645bb.

New threading model

Il2Cpp::perform does four things jobs: wait for IL2CPP to be loaded and initialized, ensure the caller thread to IL2CPP, execute the given block and then detach the caller thread it has been previously attached by frida-il2cpp-bridge.

In case you were wondering, I don't exactly know what "attaching to IL2CPP" really does, but it is necessary to do some IL2CPP related stuff. Moreover, when a thread is attached, the garbage collector tracks the resources the thread allocates, so that they can be freed when the thread detaches.

However, the implementation of Il2Cpp::perform has a major drawback.

Let's consider this snippet:

Il2Cpp.perform(() => {
    const Timer = Il2Cpp.corlib.class("System.Threading.Timer").initialize();
    const TimerCallback = Il2Cpp.corlib.class("System.Threading.TimerCallback");

    let i = 0;
    const callback = Il2Cpp.delegate(TimerCallback, () => console.log(">", i++));

    console.log("callback @", callback.handle);

    const timer = Timer.alloc();
    timer.method(".ctor").invoke(callback, NULL, 0, 1000);

    Script.bindWeak(globalThis, () => timer.method("Dispose").invoke());
});

If you are lazy, this is equivalent to the following:

let i = 0;
setInterval(() => console.log(">", i++), 1000);

Can you spot the issue?
The snippet is indeed correct, but it possibly makes the process crash.
How so? The problem here is Il2pp::perform itself. In fact, the following line

() => timer.method("Dispose").invoke();

is invoked when the Frida thread isn't attached to IL2CPP anymore. Sure, you could wrap it inside another Il2Cpp::perform:

Script.bindWeak(globalThis, () => Il2Cpp.perform(() => timer.method("Dispose").invoke()));

But it still doesn't prevent the garbage collector from eagerly freeing timer (well, in this specific scenario, it's unlikely to happen).

The same applies to the callbacks passed to setImmediate, setTimeout and setIntveral: they are always executed off IL2CPP.

Il2Cpp.perform(() => {
    console.log(">", Il2Cpp.currentThread != null);
    setTimeout(() => console.log(">>", Il2Cpp.currentThread != null));
});

// output:
// > true
// >> false

Another important drawback of this approach is it wasn't quite nice to interact with IL2CPP from the Frida's REPL.

Now, Il2Cpp::perform takes a second (optional) parameter, a string that identifies the detach strategy:

• "always" immediately detaches the caller thread after executing the given block (this the classic behaviour);
• "lazy" detaches the caller thread only when the script is going to be reloaded or destroyed (this is now the default behaviour);
• "never" never detaches the caller thread explicitly.

"never" causes the native Il2Cpp::Thread struct to be freed only when the underlying native thread is freed as well. For instance, in the context where you are prototyping a Frida script (so that you save and reload the script frequently to apply changes), it means Il2Cpp.Thread::managedId doesn't change across script realods.

Now, the previous snippet has the following outcome:

// > true
// >> true

Tracing

Some major refactorings were made to Il2Cpp::Tracer.

Firstly, tracers are now thread-specific - the default intercepted thread is the main one.

Secondly, tracers are now not verbose by default: it means that they won't print the exact same call stack twice!

Il2Cpp.perform(() => {
    Il2Cpp.trace()
        .thread(Il2Cpp::Thread) // optional, defaults to Il2Cpp.mainThread
        .verbose(true | false) // optional, defaults to false
        .assemblies(Il2Cpp.domain.assembly("Assembly-CSharp"))
        .and()
        .attach();
});

Thirdly, tracers now have appliers. An applier is just an jerkish OOP concept - you can read the commit 00865d3 to learn more - but the essential impact is the tracer-specific customization happens outside Il2Cpp::Tracer, so it is more flexible.

For instance:

Il2Cpp.perform(() => {
    // before
    Il2Cpp.trace()
        .parameters(true | false)
        .assemblies(Il2Cpp.domain.assembly("Assembly-CSharp"))
        .and()
        .attach();

    // now
    Il2Cpp.trace(true | false) // defaults to false
        .assemblies(Il2Cpp.domain.assembly("Assembly-CSharp"))
        .and()
        .attach();
});

Il2Cpp.perform(() => {
    // before
    Il2Cpp.backtrace()
        .strategy("fuzzy" | "accurate")
        .verbose(false)
        .assemblies(Il2Cpp.domain.assembly("Assembly-CSharp"))
        .and()
        .attach();

    // now
    Il2Cpp.backtrace(Backtracer.FUZZY | Backtracer.ACCURATE) // defaults to undefined
        .assemblies(Il2Cpp.domain.assembly("Assembly-CSharp"))
        .and()
        .attach();
});

I strongly suggest you to use TypeScript with a language server, so you can easily inspect what you can or cannot call now.

Relevant changes

• Make Il2Cpp.Class::initialize return this:

  Il2Cpp.perform(() => {
      // old
      const SystemReflectionModule = Il2Cpp.corlib.class("System.Reflection.Module");
      SystemReflectionModule.initialize();
  
      // new, better
      const SystemReflectionModule = Il2Cpp.corlib.class("System.Reflection.Module").initialize();
  });

• Fix Il2Cpp.Thread::id on Windows (Il2Cpp.Thread::id doesn't work on Windows #195).

• Rename Il2Cpp::Api to Il2Cpp::api:
  It is now an object literal.

• Rename Il2Cpp.Class::valueSize to Il2Cpp.Class::valueTypeSize:

  Il2Cpp.perform(() => {
      const SystemString = Il2Cpp.corlib.class("System.String");
  
      // old
      SystemString.valueSize;
  
      // new
      SystemString.valueTypeSize;
  });

• Drop Il2Cpp::Runtime:
  It had no practical use cases.

Other changes

v0.8.0...v0.8.1

[qingpengchen2011]

Great Job!