feat: Convert APIs to Kotlin DSL (#298)

This commit converts various APIs to Kotlin DSL. BREAKING CHANGE: Various old APIs are removed, and DSL APIs are added instead.
ReVanced · Aug 6, 2024 · 11a911d · 11a911d
1 parent 6e3ba74
commit 11a911d
Show file tree

Hide file tree

Showing 64 changed files with 3,421 additions and 3,397 deletions.
diff --git a/api/revanced-patcher.api b/api/revanced-patcher.api
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -24,7 +24,6 @@ tasks {
 
 repositories {
     mavenCentral()
-    mavenLocal()
     google()
     maven {
         // A repository must be specified for some reason. "registry" is a dummy.
@@ -49,8 +48,8 @@ dependencies {
         // Exclude, otherwise the org.w3c.dom API breaks.
         exclude(group = "xerces", module = "xmlParserAPIs")
     }
-
     testImplementation(libs.kotlin.test)
+    testImplementation(libs.mockk)
 }
 
 kotlin {

diff --git a/docs/1_patcher_intro.md b/docs/1_patcher_intro.md
@@ -60,40 +60,43 @@
 
 # 💉 Introduction to ReVanced Patcher
 
-In order to create patches for Android applications, you first need to understand the fundamentals of ReVanced Patcher.
+To create patches for Android apps, it is recommended to know the basic concept of ReVanced Patcher.
 
 ## 📙 How it works
 
-ReVanced Patcher is a library that allows you to modify Android applications by applying patches to their APKs. It is built on top of [Smali](https://github.com/google/smali) for bytecode manipulation and [Androlib (Apktool)](https://github.com/iBotPeaches/Apktool) for resource decoding and encoding.
-ReVanced Patcher accepts a list of patches and integrations, and applies them to a given APK file. It then returns the modified components of the APK file, such as modified dex files and resources, that can be repackaged into a new APK file.
+ReVanced Patcher is a library that allows modifying Android apps by applying patches.
+It is built on top of [Smali](https://github.com/google/smali) for bytecode manipulation and [Androlib (Apktool)](https://github.com/iBotPeaches/Apktool)
+for resource decoding and encoding.
 
-ReVanced Patcher has a simple API that allows you to load patches and integrations from JAR files and apply them to an APK file.
-Later on, you will learn how to create patches.
+ReVanced Patcher receives a list of patches and applies them to a given APK file.
+It then returns the modified components of the APK file, such as modified dex files and resources,
+that can be repackaged into a new APK file.
+
+ReVanced Patcher has a simple API that allows you to load patches from RVP (JAR or DEX container) files
+and apply them to an APK file. Later on, you will learn how to create patches.
 
 ```kt
- // Executed patches do not necessarily reset their state.
- // For that reason it is important to create a new instance of the PatchBundleLoader
- // once the patches are executed instead of reusing the same instance of patches loaded by PatchBundleLoader.
-val patches: PatchSet /* = Set<Patch<*>> */ = PatchBundleLoader.Jar(File("revanced-patches.jar"))
-val integrations = setOf(File("integrations.apk"))
+val patches = loadPatchesFromJar(setOf(File("revanced-patches.rvp")))
+
+val patcherResult = Patcher(PatcherConfig(apkFile = File("some.apk"))).use { patcher ->
+    // Here you can access metadata about the APK file through patcher.context.packageMetadata
+    // such as package name, version code, version name, etc.
 
-// Instantiating the patcher will decode the manifest of the APK file to read the package and version name.
-val patcherConfig = PatcherConfig(apkFile = File("some.apk"))
-val patcherResult = Patcher(patcherConfig).use { patcher ->
-    patcher.apply {
-        acceptIntegrations(integrations)
-        acceptPatches(patches)
+    // Add patches.
+    patcher += patches
 
-        // Execute patches.
-        runBlocking {
-            patcher.apply(returnOnError = false).collect { patchResult ->
-                if (patchResult.exception != null)
-                    println("${patchResult.patchName} failed:\n${patchResult.exception}")
-                else
-                    println("${patchResult.patchName} succeeded")
-            }
+    // Execute the patches.
+    runBlocking {
+        patcher().collect { patchResult ->
+            if (patchResult.exception != null)
+                logger.info("\"${patchResult.patch}\" failed:\n${patchResult.exception}")
+            else
+                logger.info("\"${patchResult.patch}\" succeeded")
         }
-    }.get()
+    }
+
+    // Compile and save the patched APK file components.
+    patcher.get()
 }
 
 // The result of the patcher contains the modified components of the APK file that can be repackaged into a new APK file.

diff --git a/docs/2_1_setup.md b/docs/2_1_setup.md
@@ -98,7 +98,8 @@ Throughout the documentation, [ReVanced Patches](https://github.com/revanced/rev
 3. Open the project in your IDE
 
 > [!TIP]
-> It is a good idea to set up a complete development environment for ReVanced, so that you can also test your patches by following the [ReVanced documentation](https://github.com/ReVanced/revanced-documentation).
+> It is a good idea to set up a complete development environment for ReVanced, so that you can also test your patches
+> by following the [ReVanced documentation](https://github.com/ReVanced/revanced-documentation).
 
 ## ⏭️ What's next
 

diff --git a/docs/2_2_1_fingerprinting.md b/docs/2_2_1_fingerprinting.md
@@ -60,9 +60,10 @@
 
 # 🔎 Fingerprinting
 
-In the context of ReVanced, fingerprinting is primarily used to resolve methods with a limited amount of known information.
+In the context of ReVanced, fingerprinting is primarily used to match methods with a limited amount of known information.
 Methods with obfuscated names that change with each update are primary candidates for fingerprinting.
-The goal of fingerprinting is to uniquely identify a method by capturing various attributes, such as the return type, access flags, an opcode pattern, strings, and more.
+The goal of fingerprinting is to uniquely identify a method by capturing various attributes, such as the return type,
+access flags, an opcode pattern, strings, and more.
 
 ## ⛳️ Example fingerprint
 
@@ -72,14 +73,14 @@ Throughout the documentation, the following example will be used to demonstrate
 
 package app.revanced.patches.ads.fingerprints
 
-object ShowAdsFingerprint : MethodFingerprint(
-    returnType = "Z",
-    accessFlags = AccessFlags.PUBLIC or AccessFlags.FINAL,
-    parameters = listOf("Z"),
-    opcodes = listOf(Opcode.RETURN),
-    strings = listOf("pro"),
-    customFingerprint = { (methodDef, classDef) -> methodDef.definingClass == "Lcom/some/app/ads/AdsLoader;" }
-)
+fingerprint {
+    accessFlags(AccessFlags.PUBLIC, AccessFlags.FINAL)
+    returns("Z")
+    parameters("Z")
+    opcodes(Opcode.RETURN)
+    strings("pro")
+    custom { (method, classDef) -> method.definingClass == "Lcom/some/app/ads/AdsLoader;" }
+}
 ```
 
 ## 🔎 Reconstructing the original code from a fingerprint
@@ -91,22 +92,22 @@ The fingerprint contains the following information:
 - Method signature:
 
   ```kt
-  returnType = "Z",
-  access = AccessFlags.PUBLIC or AccessFlags.FINAL,
-  parameters = listOf("Z"),
+  accessFlags(AccessFlags.PUBLIC, AccessFlags.FINAL)
+  returns("Z")
+  parameters("Z")
   ```
 
 - Method implementation:
 
   ```kt
-  opcodes = listOf(Opcode.RETURN)
-  strings = listOf("pro"),
+  opcodes(Opcode.RETURN)
+  strings("pro")
   ```
 
 - Package and class name:
 
   ```kt
-  customFingerprint = { (methodDef, classDef) -> methodDef.definingClass == "Lcom/some/app/ads/AdsLoader;"}
+  custom = { (method, classDef) -> method.definingClass == "Lcom/some/app/ads/AdsLoader;"}
   ```
 
 With this information, the original code can be reconstructed:
@@ -129,144 +130,147 @@ With this information, the original code can be reconstructed:
 
 > [!TIP]
 > A fingerprint should contain information about a method likely to remain the same across updates.
-> A method's name is not included in the fingerprint because it is likely to change with each update in an obfuscated app. In contrast, the return type, access flags, parameters, patterns of opcodes, and strings are likely to remain the same.
+> A method's name is not included in the fingerprint because it will likely change with each update in an obfuscated app.
+> In contrast, the return type, access flags, parameters, patterns of opcodes, and strings are likely to remain the same.
 
 ## 🔨 How to use fingerprints
 
-After creating a fingerprint, add it to the constructor of a `BytecodePatch`:
+Fingerprints can be added to a patch by directly creating and adding them or by invoking them manually.
+Fingerprints added to a patch are matched by ReVanced Patcher before the patch is executed.
 
 ```kt
-object DisableAdsPatch : BytecodePatch(
-    setOf(ShowAdsFingerprint)
-) {
+val fingerprint = fingerprint {
     // ...
- }
-```
+}
 
-> [!NOTE]
-> Fingerprints passed to the constructor of `BytecodePatch` are resolved by ReVanced Patcher before the patch is executed.
+val patch = bytecodePatch {
+    // Directly create and add a fingerprint.
+    fingerprint {
+        // ...
+    }
 
-> [!TIP]
-> Multiple patches can share fingerprints. If a fingerprint is resolved once, it will not be resolved again.
+    // Add a fingerprint manually by invoking it.
+    fingerprint()
+}
+```
 
 > [!TIP]
-> If a fingerprint has an opcode pattern, you can use the `FuzzyPatternScanMethod` annotation to fuzzy match the pattern.
-> Opcode pattern arrays can contain `null` values to indicate that the opcode at the index is unknown.
-> Any opcode will match to a `null` value.
-
-> [!WARNING]
-> If the fingerprint can not be resolved because it does not match any method, the result of a fingerprint is `null`.
+> Multiple patches can share fingerprints. If a fingerprint is matched once, it will not be matched again.
 
-Once the fingerprint is resolved, the result can be used in the patch:
+> [!TIP]
+> If a fingerprint has an opcode pattern, you can use the `fuzzyPatternScanThreshhold` parameter of the `opcode`
+> function to fuzzy match the pattern.  
+> `null` can be used as a wildcard to match any opcode:
+>
+> ```kt
+> fingerprint(fuzzyPatternScanThreshhold = 2) {
+>    opcodes(
+>        Opcode.ICONST_0,
+>        null,
+>        Opcode.ICONST_1,
+>        Opcode.IRETURN,
+>    )
+>}
+> ```
+
+Once the fingerprint is matched, the match can be used in the patch:
 
 ```kt
-object DisableAdsPatch : BytecodePatch(
-  setOf(ShowAdsFingerprint)
-) {
-    override fun execute(context: BytecodeContext) {
-        val result = ShowAdsFingerprint.result
-            ?: throw PatchException("ShowAdsFingerprint not found")
-
+val patch = bytecodePatch {
+    // Add a fingerprint and delegate its match to a variable.
+    val match by showAdsFingerprint()
+    val match2 by fingerprint {
         // ...
     }
+  
+    execute {
+        val method = match.method
+        val method2 = match2.method
+    }
 }
 ```
 
-The result of a fingerprint that resolved successfully contains mutable and immutable references to the method and the class it is defined in.
+> [!WARNING]
+> If the fingerprint can not be matched to any method, the match of a fingerprint is `null`. If such a match is delegated
+> to a variable, accessing it will raise an exception.
+
+The match of a fingerprint contains mutable and immutable references to the method and the class it matches to.
 
 ```kt
-class MethodFingerprintResult(
+class Match(
     val method: Method,
     val classDef: ClassDef,
-    val scanResult: MethodFingerprintScanResult,
+    val patternMatch: Match.PatternMatch?,
+    val stringMatches: List<Match.StringMatch>?,
     // ...
 ) {
     val mutableClass by lazy { /* ... */ }
     val mutableMethod by lazy { /* ... */ }
 
     // ...
 }
-
-class MethodFingerprintScanResult(
-    val patternScanResult: PatternScanResult?,
-    val stringsScanResult: StringsScanResult?,
-) {
-    class StringsScanResult(val matches: List<StringMatch>) {
-        class StringMatch(val string: String, val index: Int)
-    }
-
-    class PatternScanResult(
-        val startIndex: Int,
-        val endIndex: Int,
-        // ...
-    ) {
-        // ...
-    }
-}
 ```
 
-## 🏹 Manual resolution of fingerprints
+## 🏹 Manual matching of fingerprints
 
-Unless a fingerprint is added to the constructor of `BytecodePatch`, the fingerprint will not be resolved automatically by ReVanced Patcher before the patch is executed.
-Instead, the fingerprint can be resolved manually using various overloads of the `resolve` function of a fingerprint.
+Unless a fingerprint is added to a patch, the fingerprint will not be matched automatically by ReVanced Patcher
+before the patch is executed.
+Instead, the fingerprint can be matched manually using various overloads of a fingerprint's `match` function.
 
-You can resolve a fingerprint in the following ways:
+You can match a fingerprint the following ways:
 
-- On a **list of classes**, if the fingerprint can resolve on a known subset of classes
+- In a **list of classes**, if the fingerprint can match in a known subset of classes
 
-  If you have a known list of classes you know the fingerprint can resolve on, you can resolve the fingerprint on the list of classes:
+  If you have a known list of classes you know the fingerprint can match in,
+you can match the fingerprint on the list of classes:
 
   ```kt
-  override fun execute(context: BytecodeContext) {
-      val result = ShowAdsFingerprint.also { it.resolve(context, context.classes) }.result
-          ?: throw PatchException("ShowAdsFingerprint not found")
-
-          // ...
-  }
+    execute { context ->
+        val match = showAdsFingerprint.apply { 
+            match(context, context.classes) 
+        }.match ?: throw PatchException("No match found")
+    }
   ```
 
-- On a **single class**, if the fingerprint can resolve on a single known class
+- In a **single class**, if the fingerprint can match in a single known class
 
-  If you know the fingerprint can resolve to a method in a specific class, you can resolve the fingerprint on the class:
+  If you know the fingerprint can match a method in a specific class, you can match the fingerprint in the class:
 
   ```kt
-  override fun execute(context: BytecodeContext) {
+  execute { context ->
       val adsLoaderClass = context.classes.single { it.name == "Lcom/some/app/ads/Loader;" }
 
-      val result = ShowAdsFingerprint.also { it.resolve(context, adsLoaderClass) }.result
-          ?: throw PatchException("ShowAdsFingerprint not found")
-
-      // ...
+      val match = showAdsFingerprint.apply { 
+        match(context, adsLoaderClass)
+      }.match ?: throw PatchException("No match found")
   }
   ```
 
-- On a **single method**, to extract certain information about a method
+- Match a **single method**, to extract certain information about it
 
-  The result of a fingerprint contains useful information about the method, such as the start and end index of an opcode pattern or the indices of the instructions with certain string references.
+  The match of a fingerprint contains useful information about the method, such as the start and end index of an opcode pattern
+or the indices of the instructions with certain string references.
   A fingerprint can be leveraged to extract such information from a method instead of manually figuring it out:
 
   ```kt
-  override fun execute(context: BytecodeContext) {
-      val adsFingerprintResult = ShowAdsFingerprint.result
-          ?: throw PatchException("ShowAdsFingerprint not found")
-
-      val proStringsFingerprint = object : MethodFingerprint(
-          strings = listOf("free", "trial")
-      ) {}
-
-      proStringsFingerprint.also {
-          it.resolve(context, adsFingerprintResult.method)
-      }.result?.let { result ->
-          result.scanResult.stringsScanResult!!.matches.forEach { match ->
+  execute { context ->
+      val proStringsFingerprint = fingerprint {
+          strings("free", "trial")
+      }
+
+      proStringsFingerprint.apply {
+          match(context, adsFingerprintMatch.method)
+      }.match?.let { match ->
+          match.stringMatches.forEach { match ->
               println("The index of the string '${match.string}' is ${match.index}")
           }
-
-      } ?: throw PatchException("pro strings fingerprint not found")
+      } ?: throw PatchException("No match found")
   }
   ```
 
 > [!TIP]
-> To see real-world examples of fingerprints, check out the [ReVanced Patches](https://github.com/revanced/revanced-patches) repository.
+> To see real-world examples of fingerprints,
+> check out the repository for [ReVanced Patches](https://github.com/revanced/revanced-patches).
 
 ## ⏭️ What's next