@reekon-tools/react-native-pdf-canvas 0.1.0 → 0.2.0

package/android/src/main/cpp/pdfcanvas-jni.cpp

@@ -0,0 +1,262 @@
+/*
+ * The JNI surface of `tools.reekon.pdfcanvas.PdfCanvasNative`.
+ *
+ * MARSHALLING ONLY, in the most literal sense: every function below converts
+ * Java values to the C++ core's types, calls one method on
+ * `pdfcanvas::Service` (or the slot store), and converts the answer back.
+ * Nothing here decides anything about rasterizing — that is `native/core`,
+ * proven on a laptop by `native/tests` against the same PDFium build.
+ *
+ * A C++ EXCEPTION MUST NOT UNWIND OUT OF A JNI METHOD: the ART frame below is
+ * not exception-aware, so the unwind reaches `std::terminate` and aborts the
+ * process. Every entry point is therefore wrapped by `guarded()`, which turns a
+ * `PdfError` into a `PdfRasterException` carrying the same wire code, and
+ * anything else into `backend-failure`.
+ *
+ * PLAIN JNI, NO FBJNI. The whole surface is a dozen static methods on one
+ * class; fbjni would add a dependency and a registration dance to express
+ * `SetByteArrayRegion`.
+ */
+
+#include <jni.h>
+
+#include <cstdint>
+#include <exception>
+#include <string>
+#include <vector>
+
+#include "pdfcanvas/error.h"
+#include "pdfcanvas/jsi.h"
+#include "pdfcanvas/service.h"
+#include "pdfcanvas/slots.h"
+
+namespace {
+
+using pdfcanvas::ErrorCode;
+using pdfcanvas::PdfError;
+using pdfcanvas::Service;
+
+/// Raises a `PdfRasterException` through its `fromWire` factory. Leaves the
+/// exception pending; the caller must return immediately afterwards.
+void throwPdfError(JNIEnv* env, ErrorCode code, const std::string& message) {
+  if (env->ExceptionCheck()) return;
+  jclass clazz = env->FindClass("tools/reekon/pdfcanvas/PdfRasterException");
+  if (clazz == nullptr) return;  // NoClassDefFoundError is already pending.
+  jmethodID factory = env->GetStaticMethodID(
+      clazz, "fromWire",
+      "(Ljava/lang/String;Ljava/lang/String;)Ltools/reekon/pdfcanvas/PdfRasterException;");
+  if (factory == nullptr) return;
+  jstring wire = env->NewStringUTF(pdfcanvas::wireName(code));
+  jstring text = env->NewStringUTF(message.c_str());
+  if (wire == nullptr || text == nullptr) return;
+  jobject exception = env->CallStaticObjectMethod(clazz, factory, wire, text);
+  if (exception != nullptr && !env->ExceptionCheck()) {
+    env->Throw(static_cast<jthrowable>(exception));
+  }
+}
+
+/// Runs `body`, converting every C++ failure into a pending Java exception.
+/// `fallback` is what the JNI method returns while the exception is pending.
+template <typename T, typename Body>
+T guarded(JNIEnv* env, T fallback, Body&& body) {
+  try {
+    return body();
+  } catch (const PdfError& error) {
+    throwPdfError(env, error.code(), error.message());
+  } catch (const std::exception& error) {
+    throwPdfError(env, ErrorCode::BackendFailure, std::string("Native failure: ") + error.what());
+  } catch (...) {
+    throwPdfError(env, ErrorCode::BackendFailure, "Native failure of an unknown kind.");
+  }
+  return fallback;
+}
+
+Service* serviceOf(jlong pointer) { return reinterpret_cast<Service*>(pointer); }
+
+std::string toString(JNIEnv* env, jstring value) {
+  if (value == nullptr) return {};
+  const char* chars = env->GetStringUTFChars(value, nullptr);
+  if (chars == nullptr) return {};
+  std::string out(chars);
+  env->ReleaseStringUTFChars(value, chars);
+  return out;
+}
+
+std::vector<uint8_t> toBytes(JNIEnv* env, jbyteArray value) {
+  if (value == nullptr) return {};
+  const jsize length = env->GetArrayLength(value);
+  std::vector<uint8_t> out(static_cast<size_t>(length));
+  if (length > 0) {
+    // GetByteArrayRegion, not GetPrimitiveArrayCritical: the critical variants
+    // suspend GC for their duration, and a document can be tens of megabytes.
+    env->GetByteArrayRegion(value, 0, length, reinterpret_cast<jbyte*>(out.data()));
+  }
+  return out;
+}
+
+jbyteArray toJavaBytes(JNIEnv* env, const std::vector<uint8_t>& bytes) {
+  const jsize length = static_cast<jsize>(bytes.size());
+  jbyteArray out = env->NewByteArray(length);
+  if (out == nullptr) return nullptr;
+  if (length > 0) {
+    env->SetByteArrayRegion(out, 0, length, reinterpret_cast<const jbyte*>(bytes.data()));
+  }
+  return out;
+}
+
+}  // namespace
+
+extern "C" {
+
+/* ------------------------------------------------------------------ *
+ * Service lifecycle
+ * ------------------------------------------------------------------ */
+
+JNIEXPORT jlong JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_createService(JNIEnv* env, jclass) {
+  return guarded<jlong>(env, 0, [] { return reinterpret_cast<jlong>(new Service()); });
+}
+
+JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_invalidateService(JNIEnv* env, jclass,
+                                                                                    jlong service) {
+  guarded<int>(env, 0, [&] {
+    if (Service* s = serviceOf(service)) s->invalidate();
+    return 0;
+  });
+}
+
+/* ------------------------------------------------------------------ *
+ * Documents
+ * ------------------------------------------------------------------ */
+
+JNIEXPORT jdoubleArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_open(
+    JNIEnv* env, jclass, jlong service, jstring path, jbyteArray bytes, jstring password) {
+  return guarded<jdoubleArray>(env, nullptr, [&]() -> jdoubleArray {
+    Service* s = serviceOf(service);
+    if (s == nullptr) throw PdfError(ErrorCode::BackendFailure, "The native service is gone.");
+
+    pdfcanvas::Source source;
+    source.path = toString(env, path);
+    if (source.path.empty()) source.bytes = toBytes(env, bytes);
+    if (password != nullptr) {
+      source.hasPassword = true;
+      source.password = toString(env, password);
+    }
+
+    const Service::Opened opened = s->open(source);
+    std::vector<jdouble> flat;
+    flat.reserve(2 + opened.pages.size() * 3);
+    flat.push_back(static_cast<jdouble>(opened.handle));
+    flat.push_back(static_cast<jdouble>(opened.pages.size()));
+    for (const auto& page : opened.pages) {
+      flat.push_back(page.width);
+      flat.push_back(page.height);
+      flat.push_back(static_cast<jdouble>(page.rotation));
+    }
+    jdoubleArray out = env->NewDoubleArray(static_cast<jsize>(flat.size()));
+    if (out == nullptr) {
+      s->close(opened.handle);
+      return nullptr;
+    }
+    env->SetDoubleArrayRegion(out, 0, static_cast<jsize>(flat.size()), flat.data());
+    return out;
+  });
+}
+
+JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_registerCancellation(
+    JNIEnv* env, jclass, jlong service, jint handle, jlong token) {
+  guarded<int>(env, 0, [&] {
+    if (Service* s = serviceOf(service)) s->registerCancellation(handle, token);
+    return 0;
+  });
+}
+
+JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_render(
+    JNIEnv* env, jclass, jlong service, jint handle, jint page, jdouble x, jdouble y, jdouble width,
+    jdouble height, jdouble scale, jboolean annotations, jboolean transparent, jlong token,
+    jboolean useSlot, jlongArray out) {
+  return guarded<jbyteArray>(env, nullptr, [&]() -> jbyteArray {
+    Service* s = serviceOf(service);
+    if (s == nullptr) throw PdfError(ErrorCode::BackendFailure, "The native service is gone.");
+    if (out == nullptr || env->GetArrayLength(out) < 4) {
+      throw PdfError(ErrorCode::BackendFailure, "render() needs a long[4] to report the raster's shape.");
+    }
+
+    pdfcanvas::RasterRequest request;
+    request.page = page;
+    request.x = x;
+    request.y = y;
+    request.width = width;
+    request.height = height;
+    request.scale = scale;
+    request.annotations = annotations == JNI_TRUE;
+    request.background = transparent == JNI_TRUE ? pdfcanvas::Background::Transparent
+                                                 : pdfcanvas::Background::White;
+
+    pdfcanvas::RasterPixels pixels = s->render(handle, request, token, useSlot == JNI_TRUE);
+
+    const jlong shape[4] = {static_cast<jlong>(pixels.slot), pixels.width, pixels.height, pixels.rowBytes};
+    env->SetLongArrayRegion(out, 0, 4, shape);
+    if (pixels.inSlot()) return nullptr;
+
+    jbyteArray bytes = toJavaBytes(env, pixels.bytes);
+    if (bytes == nullptr) {
+      throw PdfError(ErrorCode::OutOfMemory, "Could not allocate a Java array for " +
+                                                 std::to_string(pixels.bytes.size()) + " raster bytes.");
+    }
+    return bytes;
+  });
+}
+
+JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_cancel(JNIEnv* env, jclass, jlong service,
+                                                                         jint handle, jlong token) {
+  guarded<int>(env, 0, [&] {
+    if (Service* s = serviceOf(service)) s->cancel(handle, token);
+    return 0;
+  });
+}
+
+JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_close(JNIEnv* env, jclass, jlong service,
+                                                                        jint handle) {
+  guarded<int>(env, 0, [&] {
+    if (Service* s = serviceOf(service)) s->close(handle);
+    return 0;
+  });
+}
+
+/* ------------------------------------------------------------------ *
+ * Transport
+ * ------------------------------------------------------------------ */
+
+JNIEXPORT jboolean JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_installJsi(JNIEnv* env, jclass,
+                                                                                 jlong runtimePointer) {
+  return guarded<jboolean>(env, JNI_FALSE, [&] {
+    return pdfcanvas::installTakePixels(reinterpret_cast<void*>(runtimePointer)) ? JNI_TRUE : JNI_FALSE;
+  });
+}
+
+JNIEXPORT jlong JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_storeProbe(JNIEnv* env, jclass) {
+  return guarded<jlong>(env, -1, [] { return static_cast<jlong>(pdfcanvas::slots::storeProbe()); });
+}
+
+JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_releaseSlot(JNIEnv*, jclass, jlong slot) {
+  pdfcanvas::slots::release(slot);
+}
+
+JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_releaseAllSlots(JNIEnv*, jclass) {
+  pdfcanvas::slots::releaseAll();
+}
+
+JNIEXPORT jint JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_slotCount(JNIEnv*, jclass) {
+  return static_cast<jint>(pdfcanvas::slots::count());
+}
+
+JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_takeSlotForTest(JNIEnv* env, jclass,
+                                                                                        jlong slot) {
+  return guarded<jbyteArray>(env, nullptr, [&]() -> jbyteArray {
+    std::shared_ptr<pdfcanvas::SlotBuffer> buffer = pdfcanvas::slots::take(slot);
+    if (buffer == nullptr) return nullptr;
+    return toJavaBytes(env, std::vector<uint8_t>(buffer->data(), buffer->data() + buffer->size()));
+  });
+}
+
+}  // extern "C"

package/android/src/main/java/tools/reekon/pdfcanvas/PdfCanvasNative.java

@@ -0,0 +1,167 @@
+package tools.reekon.pdfcanvas;
+
+/**
+ * The Java face of the C++ core in {@code native/core}. EVERY method here is a
+ * one-line JNI hop; nothing in this package decides anything about rendering
+ * any more.
+ *
+ * <h3>Why the rasterizer is no longer Java</h3>
+ *
+ * It used to be {@code android.graphics.pdf.PdfRenderer}: PDFium behind a
+ * platform wrapper that exposed no annotation switch (embedded annotations were
+ * invisible on every API level below 35 and only two kinds on 35+), no
+ * password ({@code LoadParams} landed at API 35), no cancel, a poisoning bug on
+ * API 24, and a process-wide lock that convoyed. The core now links PDFium
+ * itself — the same release iOS and the web backend use — so a tile is
+ * byte-identical across all three platforms, annotations and form fields draw
+ * when asked, encrypted documents open, and a superseded render stops
+ * mid-draw.
+ *
+ * <h3>The contract</h3>
+ *
+ * A {@code service} is an opaque native pointer from {@link #createService()},
+ * owned by one {@code PdfCanvasModule}. Handles, cancellation tokens and the
+ * transport flag all live behind it in C++ (see {@code service.h}); this class
+ * only carries values across. It is never freed: {@link #invalidateService}
+ * closes everything it holds, and a worker still inside a render when a reload
+ * lands keeps a pointer that must stay valid. One small struct per reload is the
+ * price, dev-only.
+ *
+ * <h3>Degrading</h3>
+ *
+ * {@link #isLoaded()} is false when {@code libpdfcanvas.so} — or the
+ * {@code libpdfium.so} it links — is absent from the APK: a build that skipped
+ * the native build, an ABI with no artifact. There is no Java fallback engine
+ * any more, so the binding reports {@code backend-failure} and says why rather
+ * than pretending.
+ */
+public final class PdfCanvasNative {
+
+  /**
+   * The transport self-test payload, mirroring {@code TRANSPORT_PROBE_BYTES} in
+   * {@code src/rasterizer/native-bridge.ts} and {@code slots::probeBytes()} in
+   * C++. Restated rather than derived on purpose: a mismatch has to make the
+   * probe FAIL and the platform fall back to base64.
+   */
+  public static final byte[] PROBE_BYTES = {
+    0x00, 0x01, 0x02, (byte) 0xFD, (byte) 0xFE, (byte) 0xFF, 0x2A, 0x07
+  };
+
+  private static final boolean LOADED = load();
+
+  private PdfCanvasNative() {}
+
+  private static boolean load() {
+    try {
+      // Pulls libpdfium.so in through DT_NEEDED; both sit in the APK's lib dir.
+      System.loadLibrary("pdfcanvas");
+      return true;
+    } catch (Throwable t) {
+      return false;
+    }
+  }
+
+  /** Whether the native library loaded. False means nothing here may be called. */
+  public static boolean isLoaded() {
+    return LOADED;
+  }
+
+  /* ---------------------------------------------------------------- *
+   * Service lifecycle
+   * ---------------------------------------------------------------- */
+
+  /** A fresh {@code pdfcanvas::Service}. Never freed — see the class note. */
+  public static native long createService();
+
+  /**
+   * Closes every document the service holds (waiting for an in-flight render
+   * to reach its next cancellation checkpoint), drains every parked slot, and
+   * makes every further call fail with {@code backend-failure}.
+   */
+  public static native void invalidateService(long service);
+
+  /* ---------------------------------------------------------------- *
+   * Documents
+   * ---------------------------------------------------------------- */
+
+  /**
+   * Opens a document from a path or from bytes (exactly one non-null).
+   *
+   * @param password null when none was supplied. An EMPTY string counts as
+   *     supplied: PDFium reports the same error for "no password" and "wrong
+   *     password", and only the caller knows which it was.
+   * @return {@code [handle, pageCount, w0, h0, rot0, w1, h1, rot1, ...]} —
+   *     flat doubles rather than a Java object, so the JNI side constructs
+   *     nothing it would have to look up by signature.
+   * @throws PdfRasterException with the failure's {@link PdfErrorCode}.
+   */
+  public static native double[] open(long service, String path, byte[] bytes, String password)
+      throws PdfRasterException;
+
+  /**
+   * Registers the cancellation signal for {@code (handle, token)} BEFORE the
+   * render is dispatched, so a cancel arriving during the dispatch hop lands.
+   */
+  public static native void registerCancellation(long service, int handle, long token);
+
+  /**
+   * Renders one raster on the calling thread.
+   *
+   * @param useSlot ask for the zero-copy transport. The store may still refuse,
+   *     so the result says where the pixels ARE: a non-null return is heap
+   *     bytes, a null return means {@code out[0]} names a slot.
+   * @param out receives {@code [slot, width, height, rowBytes]}.
+   * @return the RGBA bytes when heap-backed, null when slot-backed.
+   */
+  public static native byte[] render(
+      long service,
+      int handle,
+      int page,
+      double x,
+      double y,
+      double width,
+      double height,
+      double scale,
+      boolean annotations,
+      boolean transparent,
+      long token,
+      boolean useSlot,
+      long[] out)
+      throws PdfRasterException;
+
+  /** Sets the signal a render polls, including mid-draw. A pure lookup. */
+  public static native void cancel(long service, int handle, long token);
+
+  /** Closes one document. Idempotent. */
+  public static native void close(long service, int handle);
+
+  /* ---------------------------------------------------------------- *
+   * Transport
+   * ---------------------------------------------------------------- */
+
+  /**
+   * Installs {@code globalThis.__pdfCanvasTakePixels}. MUST be called on the JS
+   * thread with a live runtime pointer; returns false rather than throwing when
+   * the pointer is null, this build has no JSI, or the runtime refuses.
+   */
+  public static native boolean installJsi(long runtimePointer);
+
+  /** Parks {@link #PROBE_BYTES} in a fresh slot and returns its id. */
+  public static native long storeProbe();
+
+  /** Drops one slot if it is still there. */
+  public static native void releaseSlot(long slot);
+
+  /** Drops every slot. */
+  public static native void releaseAllSlots();
+
+  /** Slots waiting to be taken. Diagnostics only. */
+  public static native int slotCount();
+
+  /**
+   * Takes a slot back out as a Java array through the identical storage the
+   * ArrayBuffer would have wrapped. Null when empty. The instrumented suite's
+   * only way to check the transport without a JS runtime.
+   */
+  public static native byte[] takeSlotForTest(long slot);
+}

package/android/src/main/java/tools/reekon/pdfcanvas/PdfErrorCode.java

@@ -1,14 +1,14 @@
 package tools.reekon.pdfcanvas;
 
 /**
- * The eight failure kinds, mirroring {@code PdfErrorCode} in {@code src/types.ts}.
+ * The eight failure kinds, mirroring {@code PdfErrorCode} in {@code src/types.ts}
+ * and {@code pdfcanvas::ErrorCode} in the C++ core.
  *
  * The wire strings are the TypeScript union members verbatim. They are the
  * contract across the bridge: the binding rejects a promise with {@link #wire()}
  * and the TS side constructs a {@code PdfError} from it with no translation
- * table in between. Adding a member here without adding it there produces a
- * {@code PdfError} with a code no consumer can switch on, so the two lists have
- * to move together.
+ * table in between. The C++ core throws with the same strings, and
+ * {@link #fromWire} is how a JNI-raised exception gets its typed code back.
  */
 public enum PdfErrorCode {
   NOT_FOUND("not-found"),
@@ -30,4 +30,14 @@ public enum PdfErrorCode {
   public String wire() {
     return wire;
   }
+
+  /** The code for a wire string; {@link #BACKEND_FAILURE} for one nobody knows. */
+  public static PdfErrorCode fromWire(String wire) {
+    for (PdfErrorCode code : values()) {
+      if (code.wire.equals(wire)) {
+        return code;
+      }
+    }
+    return BACKEND_FAILURE;
+  }
 }

package/android/src/main/java/tools/reekon/pdfcanvas/PdfRasterException.java

@@ -1,15 +1,12 @@
 package tools.reekon.pdfcanvas;
 
 /**
- * Every way this backend can fail, carrying a {@link PdfErrorCode}.
+ * Every way the native core can fail, carrying a {@link PdfErrorCode}.
  *
  * CHECKED on purpose. The whole point of the code is that a caller distinguishes
  * "wrong password" from "not a PDF" from "cancelled", and an unchecked exception
  * lets the binding forget to map it — at which point every failure reaches JS as
  * a generic {@code Error} and the {@code PdfErrorCode} union is decorative.
- *
- * The {@code cause} is always kept. A {@code corrupt} verdict that turns out to
- * be a truncated download is only diagnosable from the underlying IOException.
  */
 public class PdfRasterException extends Exception {
 
@@ -24,6 +21,15 @@ public class PdfRasterException extends Exception {
     this.code = code;
   }
 
+  /**
+   * How the JNI layer raises one: it has a wire string from
+   * {@code pdfcanvas::wireName} and a message, and constructing an enum from C++
+   * is a signature lookup nobody should have to get right twice.
+   */
+  public static PdfRasterException fromWire(String wire, String message) {
+    return new PdfRasterException(PdfErrorCode.fromWire(wire), message);
+  }
+
   public PdfErrorCode code() {
     return code;
   }