feat: Move fingerprint match members to fingerprint for ease of access by using context receivers

2026-01-30 22:51:02 +00:00 · 2024-11-04 02:24:16 +01:00
parent 7f55868e6f
commit 0746c22743
9 changed files with 324 additions and 217 deletions
--- a/src/main/kotlin/app/revanced/patcher/Fingerprint.kt
+++ b/src/main/kotlin/app/revanced/patcher/Fingerprint.kt
@@ -3,8 +3,8 @@
 package app.revanced.patcher

 import app.revanced.patcher.extensions.InstructionExtensions.instructionsOrNull
-import app.revanced.patcher.patch.*
-import app.revanced.patcher.patch.MethodClassPairs
+import app.revanced.patcher.patch.BytecodePatchContext
+import app.revanced.patcher.patch.PatchException
 import app.revanced.patcher.util.proxy.ClassProxy
 import com.android.tools.smali.dexlib2.AccessFlags
 import com.android.tools.smali.dexlib2.Opcode
@@ -44,17 +44,21 @@ class Fingerprint internal constructor(
    internal val custom: ((method: Method, classDef: ClassDef) -> Boolean)?,
    private val fuzzyPatternScanThreshold: Int,
 ) {
+    @Suppress("ktlint:standard:backing-property-naming")
+    // Backing field needed for lazy initialization.
+    private var _matchOrNull: Match? = null
+
    /**
     * The match for this [Fingerprint]. Null if unmatched.
     */
-    // Backing property for "match" extension in BytecodePatchContext.
-    @Suppress("ktlint:standard:backing-property-naming", "PropertyName")
-    internal var _match: Match? = null
+    context(BytecodePatchContext)
+    private val matchOrNull: Match?
+        get() = matchOrNull()

    /**
-     * Match using [BytecodePatchContext.LookupMaps].
+     * Match using [BytecodePatchContext.lookupMaps].
     *
-     * Generally faster than the other [_match] overloads when there are many methods to check for a match.
+     * Generally faster than the other [matchOrNull] overloads when there are many methods to check for a match.
     *
     * Fingerprints can be optimized for performance:
     * - Slowest: Specify [custom] or [opcodes] and nothing else.
@@ -62,29 +66,28 @@ class Fingerprint internal constructor(
     * - Faster: Specify [accessFlags], [returnType] and [parameters].
     * - Fastest: Specify [strings], with at least one string being an exact (non-partial) match.
     *
-     * @param context The [BytecodePatchContext] to match against [BytecodePatchContext.classes].
     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
     */
-    internal fun match(context: BytecodePatchContext): Match? {
-        if (_match != null) return _match
+    context(BytecodePatchContext)
+    internal fun matchOrNull(): Match? {
+        if (_matchOrNull != null) return _matchOrNull

-        val lookupMaps = context.lookupMaps
+        val lookupMaps = lookupMaps

-        fun Fingerprint.match(methodClasses: MethodClassPairs): Match? {
+        // Find the first
+        var match = strings?.firstNotNullOfOrNull { lookupMaps.methodsByStrings[it] }?.let { methodClasses ->
            methodClasses.forEach { (classDef, method) ->
-                val match = match(context, classDef, method)
-                if (match != null) return match
+                val match = matchOrNull(classDef, method)
+                if (match != null) return@let match
            }

-            return null
+            null
        }

-        // TODO: If only one string is necessary, why not use a single string for every fingerprint?
-        val match = strings?.firstNotNullOfOrNull { lookupMaps.methodsByStrings[it] }?.let(::match)
        if (match != null) return match

-        context.classes.forEach { classDef ->
-            val match = match(context, classDef)
+        classes.forEach { classDef ->
+            match = matchOrNull(classDef)
            if (match != null) return match
        }

@@ -95,18 +98,17 @@ class Fingerprint internal constructor(
     * Match using a [ClassDef].
     *
     * @param classDef The class to match against.
-     * @param context The [BytecodePatchContext] to match against [BytecodePatchContext.classes].
     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
     */
-    internal fun match(
-        context: BytecodePatchContext,
+    context(BytecodePatchContext)
+    fun matchOrNull(
        classDef: ClassDef,
    ): Match? {
-        if (_match != null) return _match
+        if (_matchOrNull != null) return _matchOrNull

        for (method in classDef.methods) {
-            val match = match(context, method, classDef)
-            if (match != null)return match
+            val match = matchOrNull(method, classDef)
+            if (match != null) return match
        }

        return null
@@ -117,28 +119,26 @@ class Fingerprint internal constructor(
     * The class is retrieved from the method.
     *
     * @param method The method to match against.
-     * @param context The [BytecodePatchContext] to match against [BytecodePatchContext.classes].
     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
     */
-    internal fun match(
-        context: BytecodePatchContext,
+    context(BytecodePatchContext)
+    fun matchOrNull(
        method: Method,
-    ) = match(context, method, context.classBy { method.definingClass == it.type }!!.immutableClass)
+    ) = matchOrNull(method, classBy { method.definingClass == it.type }!!.immutableClass)

    /**
     * Match using a [Method].
     *
     * @param method The method to match against.
     * @param classDef The class the method is a member of.
-     * @param context The [BytecodePatchContext] to match against [BytecodePatchContext.classes].
     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
     */
-    internal fun match(
-        context: BytecodePatchContext,
+    context(BytecodePatchContext)
+    fun matchOrNull(
        method: Method,
        classDef: ClassDef,
    ): Match? {
-        if (_match != null) return _match
+        if (_matchOrNull != null) return _matchOrNull

        if (returnType != null && !method.returnType.startsWith(returnType)) {
            return null
@@ -243,33 +243,189 @@ class Fingerprint internal constructor(
            null
        }

-        _match = Match(
-            classDef,
+        _matchOrNull = Match(
            method,
            patternMatch,
            stringMatches,
-            context,
+            classDef,
        )

-        return _match
+        return _matchOrNull
    }
+
+    private val exception get() = PatchException("Failed to match the fingerprint: $this")
+
+    /**
+     * The match for this [Fingerprint].
+     *
+     * @throws PatchException If the [Fingerprint] has not been matched.
+     */
+    context(BytecodePatchContext)
+    private val match
+        get() = matchOrNull ?: throw exception
+
+    /**
+     * Match using a [ClassDef].
+     *
+     * @param classDef The class to match against.
+     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    fun match(
+        classDef: ClassDef,
+    ) = matchOrNull(classDef) ?: throw exception
+
+    /**
+     * Match using a [Method].
+     * The class is retrieved from the method.
+     *
+     * @param method The method to match against.
+     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    fun match(
+        method: Method,
+    ) = matchOrNull(method) ?: throw exception
+
+    /**
+     * Match using a [Method].
+     *
+     * @param method The method to match against.
+     * @param classDef The class the method is a member of.
+     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    fun match(
+        method: Method,
+        classDef: ClassDef,
+    ) = matchOrNull(method, classDef) ?: throw exception
+
+    /**
+     * The class the matching method is a member of.
+     */
+    context(BytecodePatchContext)
+    val originalClassDefOrNull
+        get() = matchOrNull?.originalClassDef
+
+    /**
+     * The matching method.
+     */
+    context(BytecodePatchContext)
+    val originalMethodOrNull
+        get() = matchOrNull?.originalMethod
+
+    /**
+     * The mutable version of [originalClassDefOrNull].
+     *
+     * Accessing this property allocates a [ClassProxy].
+     * Use [originalClassDefOrNull] if mutable access is not required.
+     */
+    context(BytecodePatchContext)
+    val classDefOrNull
+        get() = matchOrNull?.classDef
+
+    /**
+     * The mutable version of [originalMethodOrNull].
+     *
+     * Accessing this property allocates a [ClassProxy].
+     * Use [originalMethodOrNull] if mutable access is not required.
+     */
+    context(BytecodePatchContext)
+    val methodOrNull
+        get() = matchOrNull?.method
+
+    /**
+     * The match for the opcode pattern.
+     */
+    context(BytecodePatchContext)
+    val patternMatchOrNull
+        get() = matchOrNull?.patternMatch
+
+    /**
+     * The matches for the strings.
+     */
+    context(BytecodePatchContext)
+    val stringMatchesOrNull
+        get() = matchOrNull?.stringMatches
+
+    /**
+     * The class the matching method is a member of.
+     *
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    val originalClassDef
+        get() = match.originalClassDef
+
+    /**
+     * The matching method.
+     *
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    val originalMethod
+        get() = match.originalMethod
+
+    /**
+     * The mutable version of [originalClassDef].
+     *
+     * Accessing this property allocates a [ClassProxy].
+     * Use [originalClassDef] if mutable access is not required.
+     *
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    val classDef
+        get() = match.classDef
+
+    /**
+     * The mutable version of [originalMethod].
+     *
+     * Accessing this property allocates a [ClassProxy].
+     * Use [originalMethod] if mutable access is not required.
+     *
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    val method
+        get() = match.method
+
+    /**
+     * The match for the opcode pattern.
+     *
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    val patternMatch
+        get() = match.patternMatch
+
+    /**
+     * The matches for the strings.
+     *
+     * @throws PatchException If the fingerprint has not been matched.
+     */
+    context(BytecodePatchContext)
+    val stringMatches
+        get() = match.stringMatches
 }

 /**
- * A match for a [Fingerprint].
+ * A match of a [Fingerprint].
 *
 * @param originalClassDef The class the matching method is a member of.
 * @param originalMethod The matching method.
 * @param patternMatch The match for the opcode pattern.
 * @param stringMatches The matches for the strings.
- * @param context The context to create mutable proxies in.
 */
+context(BytecodePatchContext)
 class Match internal constructor(
-    val originalClassDef: ClassDef,
    val originalMethod: Method,
    val patternMatch: PatternMatch?,
    val stringMatches: List<StringMatch>?,
-    internal val context: BytecodePatchContext,
+    val originalClassDef: ClassDef,
 ) {
    /**
     * The mutable version of [originalClassDef].
@@ -277,7 +433,7 @@ class Match internal constructor(
     * Accessing this property allocates a [ClassProxy].
     * Use [originalClassDef] if mutable access is not required.
     */
-    val classDef by lazy { context.proxy(originalClassDef).mutableClass }
+    val classDef by lazy { proxy(originalClassDef).mutableClass }

    /**
     * The mutable version of [originalMethod].
@@ -292,7 +448,7 @@ class Match internal constructor(
     * @param startIndex The index of the first opcode of the pattern in the method.
     * @param endIndex The index of the last opcode of the pattern in the method.
     */
-    class PatternMatch(
+    class PatternMatch internal constructor(
        val startIndex: Int,
        val endIndex: Int,
    )
@@ -303,7 +459,7 @@ class Match internal constructor(
     * @param string The string that matched.
     * @param index The index of the instruction in the method.
     */
-    class StringMatch(val string: String, val index: Int)
+    class StringMatch internal constructor(val string: String, val index: Int)
 }

 /**
--- a/src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt
+++ b/src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt
@@ -1,6 +1,8 @@
 package app.revanced.patcher.patch

-import app.revanced.patcher.*
+import app.revanced.patcher.InternalApi
+import app.revanced.patcher.PatcherConfig
+import app.revanced.patcher.PatcherResult
 import app.revanced.patcher.extensions.InstructionExtensions.instructionsOrNull
 import app.revanced.patcher.util.ClassMerger.merge
 import app.revanced.patcher.util.MethodNavigator
@@ -22,7 +24,6 @@ import java.io.Closeable
 import java.io.FileFilter
 import java.util.*
 import java.util.logging.Logger
-import kotlin.reflect.KProperty

 /**
 * A context for patches containing the current state of the bytecode.
@@ -33,7 +34,7 @@ import kotlin.reflect.KProperty
 class BytecodePatchContext internal constructor(private val config: PatcherConfig) :
    PatchContext<Set<PatcherResult.PatchedDexFile>>,
    Closeable {
-    private val logger = Logger.getLogger(BytecodePatchContext::class.java.name)
+    private val logger = Logger.getLogger(this::javaClass.name)

    /**
     * [Opcodes] of the supplied [PatcherConfig.apkFile].
@@ -53,36 +54,6 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
        ).also { opcodes = it.opcodes }.classes.toMutableList(),
    )

-    /**
-     * The match for this [Fingerprint]. Null if unmatched.
-     */
-    val Fingerprint.match get() = match(this@BytecodePatchContext)
-
-    /**
-     * Match using a [ClassDef].
-     *
-     * @param classDef The class to match against.
-     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
-     */
-    fun Fingerprint.match(classDef: ClassDef) = match(this@BytecodePatchContext, classDef)
-
-    /**
-     * Match using a [Method].
-     * The class is retrieved from the method.
-     *
-     * @param method The method to match against.
-     * @return The [Match] if a match was found or if the fingerprint is already matched to a method, null otherwise.
-     */
-    fun Fingerprint.match(method: Method) = match(this@BytecodePatchContext, method)
-
-    /**
-     * Get the match for this [Fingerprint].
-     *
-     * @throws IllegalStateException If the [Fingerprint] has not been matched.
-     */
-    operator fun Fingerprint.getValue(nothing: Nothing?, property: KProperty<*>): Match = match
-        ?: throw PatchException("No fingerprint match to delegate to \"${property.name}\".")
-
    /**
     * The lookup maps for methods and the class they are a member of from the [classes].
     */
@@ -137,9 +108,9 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
     *
     * @return A proxy for the class.
     */
-    fun proxy(classDef: ClassDef) = this@BytecodePatchContext.classes.proxyPool.find {
+    fun proxy(classDef: ClassDef) = classes.proxyPool.find {
        it.immutableClass.type == classDef.type
-    } ?: ClassProxy(classDef).also { this@BytecodePatchContext.classes.proxyPool.add(it) }
+    } ?: ClassProxy(classDef).also { classes.proxyPool.add(it) }

    /**
     * Navigate a method.
@@ -148,7 +119,7 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
     *
     * @return A [MethodNavigator] for the method.
     */
-    fun navigate(method: MethodReference) = MethodNavigator(this@BytecodePatchContext, method)
+    fun navigate(method: MethodReference) = MethodNavigator(method)

    /**
     * Compile bytecode from the [BytecodePatchContext].
@@ -227,28 +198,6 @@ class BytecodePatchContext internal constructor(private val config: PatcherConfi
            }
        }

-        internal companion object {
-            /**
-             * Appends a string based on the parameter reference types of this method.
-             */
-            internal fun StringBuilder.appendParameters(parameters: Iterable<CharSequence>) {
-                // Maximum parameters to use in the signature key.
-                // Some apps have methods with an incredible number of parameters (over 100 parameters have been seen).
-                // To keep the signature map from becoming needlessly bloated,
-                // group together in the same map entry all methods with the same access/return and 5 or more parameters.
-                // The value of 5 was chosen based on local performance testing and is not set in stone.
-                val maxSignatureParameters = 5
-                // Must append a unique value before the parameters to distinguish this key includes the parameters.
-                // If this is not appended, then methods with no parameters
-                // will collide with different keys that specify access/return but omit the parameters.
-                append("p:")
-                parameters.forEachIndexed { index, parameter ->
-                    if (index >= maxSignatureParameters) return
-                    append(parameter.first())
-                }
-            }
-        }
-
        override fun close() {
            methodsByStrings.clear()
            classesByType.clear()
--- a/src/main/kotlin/app/revanced/patcher/util/MethodNavigator.kt
+++ b/src/main/kotlin/app/revanced/patcher/util/MethodNavigator.kt
@@ -17,7 +17,6 @@ import kotlin.reflect.KProperty
 /**
 * A navigator for methods.
 *
- * @param context The [BytecodePatchContext] to use.
 * @param startMethod The [Method] to start navigating from.
 *
 * @constructor Creates a new [MethodNavigator].
@@ -25,12 +24,16 @@ import kotlin.reflect.KProperty
 * @throws NavigateException If the method does not have an implementation.
 * @throws NavigateException If the instruction at the specified index is not a method reference.
 */
-class MethodNavigator internal constructor(private val context: BytecodePatchContext, private var startMethod: MethodReference) {
+context(BytecodePatchContext)
+class MethodNavigator internal constructor(
+    private var startMethod: MethodReference,
+) {
    private var lastNavigatedMethodReference = startMethod

-    private val lastNavigatedMethodInstructions get() = with(original()) {
-        instructionsOrNull ?: throw NavigateException("Method $definingClass.$name does not have an implementation.")
-    }
+    private val lastNavigatedMethodInstructions
+        get() = with(original()) {
+            instructionsOrNull ?: throw NavigateException("Method $this does not have an implementation.")
+        }

    /**
     * Navigate to the method at the specified index.
@@ -39,7 +42,7 @@ class MethodNavigator internal constructor(private val context: BytecodePatchCon
     *
     * @return This [MethodNavigator].
     */
-    fun at(vararg index: Int): MethodNavigator {
+    fun to(vararg index: Int): MethodNavigator {
        index.forEach {
            lastNavigatedMethodReference = lastNavigatedMethodInstructions.getMethodReferenceAt(it)
        }
@@ -53,7 +56,7 @@ class MethodNavigator internal constructor(private val context: BytecodePatchCon
     * @param index The index of the method to navigate to.
     * @param predicate The predicate to match.
     */
-    fun at(index: Int = 0, predicate: (Instruction) -> Boolean): MethodNavigator {
+    fun to(index: Int = 0, predicate: (Instruction) -> Boolean): MethodNavigator {
        lastNavigatedMethodReference = lastNavigatedMethodInstructions.asSequence()
            .filter(predicate).asIterable().getMethodReferenceAt(index)

@@ -77,7 +80,7 @@ class MethodNavigator internal constructor(private val context: BytecodePatchCon
     *
     * @return The last navigated method mutably.
     */
-    fun stop() = context.classBy(matchesCurrentMethodReferenceDefiningClass)!!.mutableClass.firstMethodBySignature
+    fun stop() = classBy(matchesCurrentMethodReferenceDefiningClass)!!.mutableClass.firstMethodBySignature
        as MutableMethod

    /**
@@ -92,7 +95,7 @@ class MethodNavigator internal constructor(private val context: BytecodePatchCon
     *
     * @return The last navigated method immutably.
     */
-    fun original() = context.classes.first(matchesCurrentMethodReferenceDefiningClass).firstMethodBySignature
+    fun original(): Method = classes.first(matchesCurrentMethodReferenceDefiningClass).firstMethodBySignature

    /**
     * Predicate to match the class defining the current method reference.
@@ -104,9 +107,10 @@ class MethodNavigator internal constructor(private val context: BytecodePatchCon
    /**
     * Find the first [lastNavigatedMethodReference] in the class.
     */
-    private val ClassDef.firstMethodBySignature get() = methods.first {
-        MethodUtil.methodSignaturesMatch(it, lastNavigatedMethodReference)
-    }
+    private val ClassDef.firstMethodBySignature
+        get() = methods.first {
+            MethodUtil.methodSignaturesMatch(it, lastNavigatedMethodReference)
+        }

    /**
     * An exception thrown when navigating fails.
--- a/src/test/kotlin/app/revanced/patcher/PatcherTest.kt
+++ b/src/test/kotlin/app/revanced/patcher/PatcherTest.kt
@@ -3,21 +3,18 @@ package app.revanced.patcher
 import app.revanced.patcher.patch.*
 import app.revanced.patcher.patch.BytecodePatchContext.LookupMaps
 import app.revanced.patcher.util.ProxyClassList
-import com.android.tools.smali.dexlib2.iface.ClassDef
-import com.android.tools.smali.dexlib2.iface.Method
 import com.android.tools.smali.dexlib2.immutable.ImmutableClassDef
 import com.android.tools.smali.dexlib2.immutable.ImmutableMethod
-import io.mockk.every
-import io.mockk.just
-import io.mockk.mockk
-import io.mockk.runs
-import jdk.internal.module.ModuleBootstrap.patcher
+import io.mockk.*
 import kotlinx.coroutines.flow.toList
 import kotlinx.coroutines.runBlocking
 import org.junit.jupiter.api.BeforeEach
 import org.junit.jupiter.api.assertAll
 import java.util.logging.Logger
-import kotlin.test.*
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue

 internal object PatcherTest {
    private lateinit var patcher: Patcher
@@ -153,10 +150,10 @@ internal object PatcherTest {
        val patch = bytecodePatch {
            execute {
                // Fingerprint can never match.
-                val match by fingerprint { }
+                val fingerprint = fingerprint { }

                // Throws, because the fingerprint can't be matched.
-                match.patternMatch
+                fingerprint.patternMatch
            }
        }

@@ -193,11 +190,6 @@ internal object PatcherTest {
                ),
            ),
        )
-        every { with(patcher.context.bytecodeContext) { any<Fingerprint>().match } } answers { callOriginal() }
-        every { with(patcher.context.bytecodeContext) { any<Fingerprint>().match(any<ClassDef>()) } } answers { callOriginal() }
-        every { with(patcher.context.bytecodeContext) { any<Fingerprint>().match(any<Method>()) } } answers { callOriginal() }
-        every { patcher.context.bytecodeContext.classBy(any()) } answers { callOriginal() }
-        every { patcher.context.bytecodeContext.proxy(any()) } answers { callOriginal() }

        val fingerprint = fingerprint { returns("V") }
        val fingerprint2 = fingerprint { returns("V") }
@@ -208,19 +200,21 @@ internal object PatcherTest {
                execute {
                    fingerprint.match(classes.first().methods.first())
                    fingerprint2.match(classes.first())
-                    fingerprint3.match
+                    fingerprint3.originalClassDef
                }
            },
        )

        patches()

-        assertAll(
-            "Expected fingerprints to match.",
-            { assertNotNull(fingerprint._match) },
-            { assertNotNull(fingerprint2._match) },
-            { assertNotNull(fingerprint3._match) },
-        )
+        with(patcher.context.bytecodeContext) {
+            assertAll(
+                "Expected fingerprints to match.",
+                { assertNotNull(fingerprint.originalClassDefOrNull) },
+                { assertNotNull(fingerprint2.originalClassDefOrNull) },
+                { assertNotNull(fingerprint3.originalClassDefOrNull) },
+            )
+        }
    }

    private operator fun Set<Patch<*>>.invoke(): List<PatchResult> {