RFC for API 102

.github/workflows/deploy.yml

@@ -2,18 +2,12 @@ name: Deploy to Maven Central
 
 on:
  workflow_dispatch:
- inputs:
- confirm:
- description: 'Type "yes" to confirm deployment to Maven Central'
- required: true
- default: ''
 
 permissions:
  contents: read
 
 jobs:
  deploy:
- if: github.event.inputs.confirm == 'yes'
  runs-on: ubuntu-latest
 
  steps:

.github/workflows/snapshot.yml

@@ -0,0 +1,45 @@
+name: Publish Sonatype Snapshot
+
+on:
+ workflow_dispatch:
+ inputs:
+ dependency_snapshot:
+ description: 'Use snapshot annotation and lint dependencies'
+ type: boolean
+ default: false
+
+permissions:
+ contents: read
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: 'recursive'
+ fetch-depth: 0
+
+ - name: set up JDK
+ uses: actions/setup-java@v4
+ with:
+ java-version: '21'
+ distribution: 'temurin'
+ cache: gradle
+
+ - name: Publish snapshot to Sonatype
+ run: |
+ echo 'org.gradle.caching=true' >> gradle.properties
+ echo 'org.gradle.parallel=true' >> gradle.properties
+ echo 'org.gradle.vfs.watch=true' >> gradle.properties
+ echo 'org.gradle.jvmargs=-Xmx2048m' >> gradle.properties
+ echo 'publishSnapshot=true' >> gradle.properties
+ echo 'dependencySnapshot=${{ github.event.inputs.dependency_snapshot }}' >> gradle.properties
+ ./gradlew publishApiPublicationToSnapshotsRepository
+ ./gradlew --stop
+ env:
+ ORG_GRADLE_PROJECT_signingKey: ${{ secrets.maven_pgp_signingKey }}
+ ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.maven_pgp_signingPassword }}
+ ORG_GRADLE_PROJECT_snapshotsUsername: ${{ secrets.OSSRHUSERNAME }}
+ ORG_GRADLE_PROJECT_snapshotsPassword: ${{ secrets.OSSRHPASSWORD }}

README.md

@@ -1,6 +1,6 @@
 # libxposed API
 
-[![API](https://img.shields.io/badge/API-101-brightgreen)](https://github.com/libxposed/api)
+[![API](https://img.shields.io/badge/API-102-brightgreen)](https://github.com/libxposed/api)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.libxposed/api?color=blue)](https://central.sonatype.com/artifact/io.github.libxposed/api)
 [![Android Min SDK](https://img.shields.io/badge/minSdk-26-orange)](https://developer.android.com/about/versions/oreo)
 [![License](https://img.shields.io/github/license/libxposed/api)](LICENSE)
@@ -13,15 +13,15 @@ Modern Xposed Module API — a type-safe, redesigned replacement for the legacy
 
 ```kotlin
 dependencies {
- compileOnly("io.github.libxposed:api:101.0.1")
+ compileOnly("io.github.libxposed:api:102.0.0")
 }
 ```
 
 ### For Framework Developers
 
 ```kotlin
 dependencies {
- implementation("io.github.libxposed:api:101.0.1")
+ implementation("io.github.libxposed:api:102.0.0")
 }
 ```
 

api/build.gradle.kts

@@ -6,8 +6,8 @@ plugins {
 
 android {
  namespace = "io.github.libxposed.api"
- compileSdk = 36
- buildToolsVersion = "36.1.0"
+ compileSdk = 37
+ buildToolsVersion = "37.0.0"
  androidResources.enable = false
  enableKotlin = false
 
@@ -32,13 +32,22 @@ android {
  }
 }
 
+val libVersion = "102.0.0"
+val publishSnapshot = providers.gradleProperty("publishSnapshot").orNull == "true"
+val dependencySnapshot = providers.gradleProperty("dependencySnapshot").orNull == "true"
+fun String.real(snapshot: Boolean) = if (snapshot) "$this-SNAPSHOT" else this
+val libxposedAnnotation = "io.github.libxposed:annotation:" + libs.versions.libxposed.annotation.get()
+val libxposedLint = "io.github.libxposed:lint:" + libs.versions.libxposed.lint.get()
+
 dependencies {
- compileOnly(libs.annotation)
+ compileOnly(libs.androidx.annotation)
+ compileOnly(libxposedAnnotation.real(dependencySnapshot))
+ lintPublish(libxposedLint.real(dependencySnapshot))
 }
 
 val androidJavadoc by tasks.registering(Javadoc::class) {
- title = "libxposed API $version"
- source(android.sourceSets["main"].java.srcDirs)
+ title = "libxposed API $libVersion"
+ source(layout.projectDirectory.dir("src/main/java"))
  destinationDir = layout.buildDirectory.dir("javadoc").get().asFile
 
  (options as StandardJavadocDocletOptions).apply {
@@ -71,7 +80,7 @@ publishing {
  register<MavenPublication>("api") {
  artifactId = "api"
  group = "io.github.libxposed"
- version = "101.0.1"
+ version = libVersion.real(publishSnapshot)
  artifact(javadocJar)
  pom {
  name.set("api")
@@ -105,6 +114,11 @@ publishing {
  url = uri("https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/")
  credentials(PasswordCredentials::class)
  }
+ maven {
+ name = "snapshots"
+ url = uri("https://central.sonatype.com/repository/maven-snapshots/")
+ credentials(PasswordCredentials::class)
+ }
  maven {
  name = "GitHubPackages"
  url = uri("https://maven.pkg.github.com/libxposed/api")

api/proguard-rules.pro

@@ -1,3 +1,4 @@
+-dontwarn io.github.libxposed.annotation.**
 -adaptresourcefilecontents META-INF/xposed/java_init.list
 -keep,allowoptimization,allowobfuscation public class * extends io.github.libxposed.api.XposedModule {
  public <init>();

api/src/main/java/io/github/libxposed/api/XposedInterface.java

@@ -15,30 +15,47 @@
 import java.util.List;
 
 import io.github.libxposed.api.error.HookFailedError;
+import io.github.libxposed.annotation.SinceApi;
 
 /**
  * Xposed interface for modules to operate on application processes.
  */
 @SuppressWarnings("unused")
 public interface XposedInterface {
  /**
- * Behavior changes: all modules
+ * API version 101.
+ * <p>Behavior changes: all modules</p>
  * <ul>
- * <li>Modules cannot be injected into zygote;
+ * <li>Modules cannot be injected into zygote;
  * they are only loaded within the process of the scope.</li>
  * </ul>
- * Behavior changes: Modules targeting 101 or higher
+ * <p>Behavior changes: Modules targeting 101 or higher</p>
  * <ul>
  * <li>This is the first API version.</li>
  * </ul>
  */
  int API_101 = 101;
 
+ /**
+ * API version 102.
+ * <p>New features</p>
+ * <ul>
+ * <li>Hot reload allows modules to be updated without restarting the process.</li>
+ * <li>Module entries can stop receiving subsequent lifecycle callbacks.</li>
+ * <li>Hooks can be atomically replaced by api or same id.</li>
+ * </ul>
+ * <p>Behavior changes: Modules targeting 102 or higher</p>
+ * <ul>
+ * <li>Libxposed modules can not call legacy {@code de.robv.android.xposed} APIs.</li>
+ * </ul>
+ */
+ int API_102 = 102;
+
  /**
  * The API version of this <b>library</b>. This is a static value for the framework.
  * Modules should use {@link #getApiVersion()} to check the API version at runtime.
  */
- int LIB_API = API_101;
+ int LIB_API = API_102;
 
  /**
  * The framework has the capability to hook system_server and other system processes.
@@ -279,6 +296,36 @@ interface HookHandle {
  * Cancels the hook. This method is idempotent. It is safe to call this method multiple times.
  */
  void unhook();
+
+ /**
+ * Gets the unique id of the hook, or null if the hook is not assigned with an id.
+ */
+ @SinceApi(API_102)
+ @Nullable
+ String getId();
+
+ /**
+ * Atomically replaces this hook with a new hooker and returns the new hook handle.
+ * <p>
+ * The replacement keeps the executable, priority, exception handling mode, and id of this hook.
+ * For a hook with an id, this targets the same hook as creating a new hook on the same executable
+ * with the same id. This method is the handle-based form of replacement and can also replace a
+ * hook without an id. It is useful during hot reloading when new code receives old hook handles
+ * from {@link XposedModuleInterface.HotReloadedParam#getOldHookHandles()}. After a successful
+ * replacement, this handle is no longer valid.
+ * </p>
+ * <p>The hook chain is snapshot based. Replacing a hook while a call is running does not affect
+ * that in-flight call.</p>
+ *
+ * @param hooker The new hooker object
+ * @return The new handle for the replaced hook
+ * @throws IllegalArgumentException if hooker is invalid
+ * @throws IllegalStateException if this hook handle is no longer valid
+ * @throws HookFailedError if replacement fails due to framework internal error
+ */
+ @SinceApi(API_102)
+ @NonNull
+ HookHandle replaceHook(@NonNull Hooker hooker);
  }
 
  /**
@@ -344,10 +391,25 @@ interface HookBuilder {
  */
  @NonNull
  HookHandle intercept(@NonNull Hooker hooker);
+
+ /**
+ * Sets a unique id for the hook, default to {@code null}. An id is used for exclusively identifying
+ * a hook in the same module on the executable. A new hook with the same id in the same module on
+ * the executable will replace the old one atomically, and the old hook handle will be invalid.
+ * Hook ids are isolated between modules.
+ *
+ * <p>The hook chain is snapshot based. Replacing or adding a hook while a call is running does not
+ * affect that in-flight call.</p>
+ *
+ * @param id The id for the hook. It can be null if you don't care about replacing the hook later.
+ * @return The builder itself for chaining
+ */
+ @SinceApi(API_102)
+ HookBuilder setId(@Nullable String id);
  }
 
  /**
- * Gets the runtime Xposed API version. Framework implementations must <b>not</b> override this method.
+ * Gets the runtime Xposed API version. Framework implementations <b>must not</b> override this method.
  */
  default int getApiVersion() {
  return LIB_API;

api/src/main/java/io/github/libxposed/api/XposedInterfaceWrapper.java

@@ -12,24 +12,32 @@
 import java.lang.reflect.Executable;
 import java.lang.reflect.Method;
 
+import io.github.libxposed.annotation.InternalApi;
+import io.github.libxposed.annotation.SinceApi;
+
 /**
  * Wrapper of {@link XposedInterface} used by modules to shield framework implementation details.
  */
 public class XposedInterfaceWrapper implements XposedInterface {
 
- private volatile XposedInterface mBase;
+ private XposedInterface mBase;
+ private Runnable mDetachImpl;
 
  /**
- * Attaches the framework interface to the module. Modules should never call this method.
+ * Attaches the framework interface to the module. Modules <b>must not</b> call this method.
+ * It is reserved for framework implementations and may change without compatibility guarantees.
  *
- * @param base The framework interface
+ * @param base The framework interface
+ * @param detachImpl The implementation of {@link #detach()}
  */
+ @InternalApi
  @SuppressWarnings("unused")
- public final void attachFramework(@NonNull XposedInterface base) {
+ public final void attachFramework(@NonNull XposedInterface base, @NonNull Runnable detachImpl) {
  if (mBase != null) {
  throw new IllegalStateException("Framework already attached");
  }
  mBase = base;
+ mDetachImpl = detachImpl;
  }
 
  private void ensureAttached() {
@@ -38,6 +46,44 @@ private void ensureAttached() {
  }
  }
 
+ /**
+ * Stops all subsequent lifecycle callbacks for the <b>current module entry</b> in the current
+ * process. After this method is called, the framework removes its reference to the entry
+ * instance and will no longer invoke any lifecycle callbacks (such as
+ * {@link XposedModuleInterface#onPackageLoaded},
+ * {@link XposedModuleInterface#onHotReloading}, etc.) on the entry instance that
+ * called this method. Only lifecycle callbacks are affected; all {@link XposedInterface} APIs
+ * remain fully functional.
+ *
+ * <p>If the module declares multiple entry classes, only the entry that calls this method is
+ * affected. Other entries continue to receive their lifecycle callbacks as normal.</p>
+ *
+ * <p>This method is idempotent. Calling it multiple times has the same effect as calling it once.</p>
+ *
+ * <p>If the module expects its classloader to become collectible after detaching, it must also
+ * remove module-owned references and execution contexts that keep module objects reachable, such
+ * as installed hooks, Java threads, and callbacks held by system or app objects. If native code
+ * is still running after all Java references to the module classloader are cleared, later runtime
+ * unloading of native libraries may crash the process; this is a module lifecycle bug.</p>
+ *
+ * <p>Typical use cases include:</p>
+ * <ul>
+ * <li>The module entry has finished all its initialization work and no longer needs to
+ * respond to further package loading events.</li>
+ * <li>For modules that target multiple apps with a dedicated entry class per app: if the
+ * entry detects it is not loaded in its target app, it can call this method immediately to
+ * avoid receiving any further callbacks.</li>
+ * <li>Calling this method together with unhooking all registered hooks, so that the module
+ * classloader can be garbage collected when no longer needed.</li>
+ * </ul>
+ */
+ @SinceApi(API_102)
+ @SuppressWarnings("unused")
+ public final void detach() {
+ ensureAttached();
+ mDetachImpl.run();
+ }
+
  @Override
  public final int getApiVersion() {
  ensureAttached();

api/src/main/java/io/github/libxposed/api/XposedModule.java

@@ -2,8 +2,7 @@
 
 /**
  * Super class which all Xposed module entry classes should extend.<br/>
- * Entry classes will be instantiated exactly once for each process. Modules should not do initialization
- * work before {@link #onModuleLoaded(ModuleLoadedParam)} is called.
+ * Entry classes will be instantiated once for each loaded module generation in a process.
  */
 @SuppressWarnings("unused")
 public abstract class XposedModule extends XposedInterfaceWrapper implements XposedModuleInterface {