Check every Android Java API call against the SDK's API level metadata

[ruccho]

Closes #168

Problem

unienc_android_mc reaches the Android Java API through jni::JNIEnv::call_method, which names the method and its signature as plain strings:

env.call_method(format, "getKeys", "()Ljava/util/Set;", &[])?

Nothing in that call records that MediaFormat.getKeys() was introduced in API 29. The crate is built with cargo ndk --platform 26, so on a device running API 26-28 the call compiles, links, ships, and then throws NoSuchMethodError. jni returns Error::JavaException while leaving the exception pending, so the process aborts as soon as control returns to the JVM.

Four such calls had accumulated — MediaCodecInfo.getCanonicalName(), MediaCodecInfo.isHardwareAccelerated(), MediaFormat.getKeys() and MediaFormat.getValueTypeForKey(), all API 29. The first commit repairs them. The remaining two commits make the class of bug impossible to reintroduce.

Fix

Every Java member the crate calls is now declared in src/bindings.rs, and the java_api! macro generates the wrappers:

class MediaFormat = "android/media/MediaFormat" {
    fn contains_key(key) = "containsKey(Ljava/lang/String;)Z";
    #[api(29)]
    fn get_keys() = "getKeys()Ljava/util/Set;";
}

Each declaration is checked at compile time against the metadata Android Lint's NewApi check uses ($ANDROID_HOME/platforms/android-*/data/api-versions.xml), which records the API level of every class, method and field on the platform. The build fails when

• the member does not exist on the platform,
• it was introduced after min_api (26) and carries no #[api(N)],
• #[api(N)] disagrees with the level it was introduced in,
• it has since been removed from the platform, or
• the declared parameter names do not match the descriptor's arity.

Removing the annotation from getKeys produces exactly the bug this PR started from, now at compile time:

error: `android.media.MediaFormat.getKeys()Ljava/util/Set;` was introduced in API level 29,
       above the minimum supported level 26.
       Annotate the declaration with `#[api(29)]` and guard every call site with
       `ApiLevel::<29>::check()`.
  --> crates/unienc_android_mc/src/bindings.rs:90:25

A member annotated #[api(N)] takes an extra ApiLevel<N> parameter, obtainable only from ApiLevel::<N>::check(). The run-time version check therefore cannot be forgotten:

match ApiLevel::<29>::check()? {
    Some(api) => {
        let name = bindings::MediaCodecInfo::get_canonical_name(env, api, &codec_info)?;
        let accelerated = bindings::MediaCodecInfo::is_hardware_accelerated(env, api, &codec_info)?;
        // ...
    }
    None => {
        let name = bindings::MediaCodecInfo::get_name(env, &codec_info)?;
        // ...
    }
}

No call site outside bindings.rs names a Java method, field or class any more; JNIEnv::call_method, find_class, get_field and friends appear nowhere else in the crate.

How it works

$ANDROID_HOME/.../api-versions.xml  (5.7 MB, all 13470 platform classes)
        |  android_api_metadata: extract the classes in classes.txt + their supertypes
        v
java-api/android-api-versions.txt   (21 KB, committed)
        |  java_api! reads it at macro expansion and checks each declaration
        v
src/bindings.rs  ->  typed wrappers

Vendoring the subset keeps the build hermetic: compiling needs no Android SDK, no JDK and no nightly toolchain. The subset holds every member of the classes it covers, so adding a call to a member of an already-listed class needs no regeneration; only a new class does. Supertypes are pulled in transitively, so a call that resolves to an inherited member (ByteBuffer.position(int) on java.nio.Buffer, HardwareBuffer.close() on AutoCloseable) is found and levelled correctly.

The generated wrappers derive their argument and return types from the JNI descriptor, and clear any pending JNI exception before propagating the error — so a failed call can no longer abort the process. Members that throw as part of normal operation (the MediaFormat getters used to probe an unknown value type below API 29) are declared #[may_throw], which discards the exception without writing it to the log.

Alternatives considered and rejected: java-spaghetti requires a nightly toolchain (#![feature(arbitrary_self_types)]); jni-bindgen has been unmaintained since 2022 and stops at API 28; duchess needs a JDK and android.jar on CLASSPATH at build time. None of them model API levels, which is the property this crate actually needs.

What changed at the call sites

The three members that need a level above the minimum now carry a witness to their call site:

Member	Level	Fallback below it
MediaCodecInfo.getCanonicalName() / isHardwareAccelerated()	29	getName(), acceleration flag omitted
MediaFormat.getKeys() / getValueTypeForKey()	29	probe of well-known keys
ImageWriter.Builder	33	ImageWriter.newInstance(Surface,int,int) (29)

Two guards were missing before and are now enforced by the type system:

• Image.getHardwareBuffer() requires API 28 and was called unconditionally.
• ImageWriter::new raised no error of its own below API 29, even though every path it takes needs it. It relied entirely on EncodingSystem.is_blit_supported() checking the level for it.

The untyped helpers in java.rs (call_void_method, call_int_method, call_object_method, get_int_field, get_long_field, check_jni_exception) and the four error variants only they produced are removed. java.rs now holds JNI-level helpers only. common.rs loses roughly 500 lines.

Verification

• cargo build for aarch64-linux-android and x86_64-linux-android, and cargo ndk --platform 26 build --profile release -F unity,mimalloc through to a linked libunienc_c.so: no errors, no warnings.

• 13 unit tests in java_api_macros cover descriptor parsing, metadata lookup through supertypes, the emitted JNI descriptor, and each of the four rejection cases.

  Two recordings were exported (10.1 s and 54.8 s). Both are H.264 High 1280x1280 with AAC-LC 24 kHz stereo, and ffmpeg -f null - decodes both end to end without errors — which also confirms the getKeys() path feeding MediaMuxer.addTrack() still produces correct track formats, codec-specific data included. An extracted frame shows the scene rendered correctly, so the ImageWriter / HardwareBuffer / Vulkan path is intact. No NoSuchMethodError, pending JNI exception or Unity-side error appeared in logcat.

Limitations

• The API 26-28 fallbacks are unchanged in behaviour but were not exercised on hardware; no device of that vintage was available. They are, however, the paths the type system now forces every call site to provide.