Merge feature/plan-5-ffi-jni: C FFI, JNI bindings, and Java samples

Completes libroqr: a C++20 RoQR (RTMP over QUIC) implementation with a
sans-I/O core, picoquic transport, RTMP/AMF/E-RTMP gateway module, test
relay, ffmpeg-validated gateways, and C/JNI/Java bindings.

Author: mondain

CMakeLists.txt

@@ -21,6 +21,17 @@ option(ROQR_BUILD_QUIC "Build the picoquic transport (needs picoquic)" OFF)
 option(ROQR_BUILD_TOOLS "Build tools (roqr-relayd; needs ROQR_BUILD_QUIC)" OFF)
 option(ROQR_BUILD_RTMP "Build the RTMP/AMF gateway module" ON)
 option(ROQR_BUILD_EXAMPLES "Build gateway library and example apps" ON)
+option(ROQR_BUILD_FFI "Build the C FFI shared library" ON)
+option(ROQR_BUILD_JNI "Build JNI bindings (needs a JDK)" OFF)
+
+# The SHARED roqr-ffi library links the static libraries (and picoquic), so
+# they must be position-independent — but only when FFI is actually built.
+# Setting this directory-scoped variable before add_subdirectory propagates
+# it to every subproject (including the picoquic add_subdirectory), so the
+# core-only build (no FFI) is unaffected.
+if(ROQR_BUILD_FFI AND ROQR_BUILD_QUIC AND ROQR_BUILD_RTMP)
+  set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+endif()
 
 add_subdirectory(core)
 
@@ -57,6 +68,26 @@ if(ROQR_BUILD_TOOLS)
   add_subdirectory(tools/relayd)
 endif()
 
+if(ROQR_BUILD_FFI)
+  if(ROQR_BUILD_QUIC AND ROQR_BUILD_RTMP)
+    add_subdirectory(ffi)
+  else()
+    message(STATUS "ROQR_BUILD_FFI needs QUIC and RTMP; skipping FFI in this config")
+  endif()
+endif()
+
+if(ROQR_BUILD_JNI)
+  if(NOT TARGET roqr-ffi)
+    message(FATAL_ERROR "ROQR_BUILD_JNI requires the FFI library (ROQR_BUILD_FFI plus QUIC+RTMP)")
+  endif()
+  find_package(JNI)
+  if(JNI_FOUND OR ANDROID)
+    add_subdirectory(jni)
+  else()
+    message(WARNING "JNI not found; skipping roqr-jni")
+  endif()
+endif()
+
 if(ROQR_BUILD_TESTS)
   enable_testing()
   add_subdirectory(tests)

CMakePresets.json

@@ -9,7 +9,8 @@
         "ROQR_BUILD_TESTS": "ON",
         "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
         "ROQR_BUILD_QUIC": "ON",
-        "ROQR_BUILD_TOOLS": "ON"
+        "ROQR_BUILD_TOOLS": "ON",
+        "ROQR_BUILD_JNI": "ON"
       }
     },
     {

README.md

@@ -34,4 +34,16 @@ The core protocol library builds without picoquic:
 - `tools/relayd/` the RoQR test relay
 - `examples/` roqr-ingest, roqr-egress, roqr-duplex
 
+## Language bindings
+
+- `ffi/` a C ABI (`roqr.h` for the client, `roqr_rtmp.h` for the ingest/egress
+  gateways) in `libroqr-ffi.so`.
+- `jni/` JNI bindings (`org.red5.roqr`) in `libroqr-jni.so` + `roqr.jar`,
+  built when `-DROQR_BUILD_JNI=ON` and a JDK is present.
+- `examples/java/` Java publish/play samples (see `examples/java/README.md`).
+- Android: see `cmake/android-jni.md` for the NDK cross-compile.
+
+Native callbacks (`MessageListener`) fire on a native thread the binding
+attaches to the JVM for the call; do not block in them.
+
 License: Apache-2.0.

cmake/android-jni.md

@@ -0,0 +1,66 @@
+# Building the RoQR JNI library for Android (NDK)
+
+The `roqr-jni` shared library and its dependencies (roqr-core, roqr-quic,
+roqr-rtmp, roqr-gateway, roqr-ffi, picoquic, picotls, OpenSSL) are all
+C/C++ and cross-compile for Android with the NDK toolchain. The Java
+classes in `jni/java/org/red5/roqr` are platform-independent and go into
+your Android app or an AAR unchanged.
+
+## Prerequisites
+
+- Android NDK r25+ (`ANDROID_NDK_HOME` set).
+- OpenSSL built for the target ABI. This repo's sibling `openssl-android`
+  tree provides prebuilt static libs; point `OPENSSL_ROOT_DIR` at the ABI
+  you are building.
+- picoquic/picotls source (fetched by `scripts/setup_picoquic_deps.sh`);
+  they build under the NDK toolchain via the same source-tree mechanism
+  `FindPicoquic.cmake` uses.
+
+## Configure
+
+```
+export ANDROID_ABI=arm64-v8a          # or armeabi-v7a, x86_64
+export ANDROID_PLATFORM=android-24
+
+eval "$(scripts/setup_picoquic_deps.sh)"
+
+cmake -S . -B build/android-$ANDROID_ABI \
+  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
+  -DANDROID_ABI=$ANDROID_ABI \
+  -DANDROID_PLATFORM=$ANDROID_PLATFORM \
+  -DOPENSSL_ROOT_DIR=/path/to/openssl-android/$ANDROID_ABI \
+  -DROQR_BUILD_QUIC=ON -DROQR_BUILD_RTMP=ON \
+  -DROQR_BUILD_EXAMPLES=ON -DROQR_BUILD_FFI=ON \
+  -DROQR_BUILD_JNI=ON -DROQR_BUILD_TESTS=OFF -DROQR_BUILD_TOOLS=OFF
+
+cmake --build build/android-$ANDROID_ABI --target roqr-jni
+```
+
+The root `CMakeLists.txt` still calls `find_package(JNI)` whenever
+`ROQR_BUILD_JNI=ON`, including on Android, but the `jni` subdirectory is
+gated with `if(JNI_FOUND OR ANDROID)` so it is added regardless of whether
+`find_package(JNI)` succeeds under the NDK toolchain (`FindJNI` can be
+unreliable there). Inside `jni/CMakeLists.txt`, the
+`target_include_directories(... ${JNI_INCLUDE_DIRS})` and
+`target_link_libraries(... ${JNI_LIBRARIES})` lines are further guarded with
+`if(NOT ANDROID)`, since the NDK sysroot already provides `jni.h` on the
+default include path and needs no separate JNI libraries to link against.
+
+Note that a HOST JDK is still required even for the NDK configure: the NDK
+only supplies `jni.h`, not a `javac`. `jni/CMakeLists.txt` calls
+`find_package(Java REQUIRED COMPONENTS Development)` and `add_jar` to build
+`roqr.jar` from the platform-independent Java sources, and both need a host
+JDK's `javac` on `PATH` (or discoverable via `JAVA_HOME`) regardless of the
+Android target ABI.
+
+## Package
+
+Copy `build/android-<abi>/jni/libroqr-jni.so` into
+`app/src/main/jniLibs/<abi>/`, add the `org.red5.roqr` Java sources (or the
+`roqr.jar`) to your app, and call `System.loadLibrary("roqr-jni")` (already
+done in the static initializers).
+
+## ABI note
+
+Build one `libroqr-jni.so` per ABI you ship. The Java API is identical
+across ABIs.

examples/java/PlaySample.java

@@ -0,0 +1,32 @@
+import org.red5.roqr.EgressGateway;
+
+/** Serves a RoQR stream to an RTMP player.
+ *  Usage: PlaySample <rtmpPort> <roqrHost> <roqrPort> <stream> */
+public final class PlaySample {
+    public static void main(String[] args) throws Exception {
+        if (args.length < 4) {
+            System.err.println(
+                "usage: PlaySample <rtmpPort> <roqrHost> <roqrPort> <stream>");
+            System.exit(2);
+        }
+        int rtmpPort = Integer.parseInt(args[0]);
+        String host = args[1];
+        int roqrPort = Integer.parseInt(args[2]);
+        String stream = args[3];
+
+        try (EgressGateway egress = new EgressGateway()) {
+            if (!egress.start(rtmpPort, host, roqrPort, stream, true)) {
+                System.err.println("failed to start egress");
+                System.exit(1);
+            }
+            if (!egress.waitPlaying(5000)) {
+                System.err.println("warning: RoQR play not confirmed");
+            }
+            System.out.printf(
+                "PlaySample: play with ffplay rtmp://127.0.0.1:%d/live/%s%n",
+                rtmpPort, stream);
+            System.out.println("Ctrl-C to stop.");
+            Thread.currentThread().join();
+        }
+    }
+}

examples/java/PublishSample.java

@@ -0,0 +1,28 @@
+import org.red5.roqr.IngestGateway;
+
+/** Bridges an RTMP publisher into a RoQR server.
+ *  Usage: PublishSample <rtmpPort> <roqrHost> <roqrPort> */
+public final class PublishSample {
+    public static void main(String[] args) throws Exception {
+        if (args.length < 3) {
+            System.err.println(
+                "usage: PublishSample <rtmpPort> <roqrHost> <roqrPort>");
+            System.exit(2);
+        }
+        int rtmpPort = Integer.parseInt(args[0]);
+        String host = args[1];
+        int roqrPort = Integer.parseInt(args[2]);
+
+        try (IngestGateway ingest = new IngestGateway()) {
+            if (!ingest.start(rtmpPort, host, roqrPort, true)) {
+                System.err.println("failed to start ingest");
+                System.exit(1);
+            }
+            System.out.printf(
+                "PublishSample: publish RTMP to rtmp://127.0.0.1:%d/live/<name>%n",
+                rtmpPort);
+            System.out.println("Ctrl-C to stop.");
+            Thread.currentThread().join();
+        }
+    }
+}

examples/java/README.md

@@ -0,0 +1,30 @@
+# libroqr Java samples
+
+Build the JNI bindings and the samples:
+
+```
+eval "$(scripts/setup_picoquic_deps.sh)"
+cmake --preset dev            # ROQR_BUILD_JNI=ON in the dev preset
+cmake --build --preset dev
+```
+
+Run (point java at the built native lib and jars):
+
+```
+JNI_DIR=build/dev/jni
+JAR=$(find build/dev -name roqr.jar)
+SAMPLES=$(find build/dev -name roqr-samples.jar)
+
+# Publisher gateway on :1935 -> RoQR server 127.0.0.1:4443
+java -Djava.library.path=$JNI_DIR -cp "$JAR:$SAMPLES" \
+    PublishSample 1935 127.0.0.1 4443
+# then: ffmpeg ... -f flv rtmp://127.0.0.1:1935/live/cam
+
+# Player gateway on :1936 <- RoQR server, stream "cam"
+java -Djava.library.path=$JNI_DIR -cp "$JAR:$SAMPLES" \
+    PlaySample 1936 127.0.0.1 4443 cam
+# then: ffplay rtmp://127.0.0.1:1936/live/cam
+```
+
+A `roqr-relayd --mode media` (or any RoQR server) must be running at the
+RoQR host/port.

ffi/CMakeLists.txt

@@ -0,0 +1,21 @@
+add_library(roqr-ffi SHARED
+  src/roqr_ffi.cpp
+  src/roqr_rtmp_ffi.cpp
+)
+
+target_include_directories(roqr-ffi PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+)
+
+target_link_libraries(roqr-ffi PRIVATE roqr-core roqr-quic roqr-gateway)
+
+target_compile_features(roqr-ffi PRIVATE cxx_std_20)
+target_compile_options(roqr-ffi PRIVATE
+  $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra>)
+
+set_target_properties(roqr-ffi PROPERTIES
+  VERSION ${PROJECT_VERSION}
+  SOVERSION 0)
+
+install(TARGETS roqr-ffi LIBRARY DESTINATION lib)
+install(DIRECTORY include/roqr DESTINATION include)

ffi/include/roqr/roqr.h

@@ -0,0 +1,91 @@
+#ifndef ROQR_H
+#define ROQR_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Error codes. 0x00-0x07 mirror the RoQR draft Table 2 application error
+ * codes; values >= 100 are FFI-local. */
+typedef enum roqr_error {
+    ROQR_OK = 0,
+    ROQR_ERR_GENERAL = 1,
+    ROQR_ERR_INTERNAL = 2,
+    ROQR_ERR_FRAME_ENCODING = 3,
+    ROQR_ERR_STREAM_CREATION = 4,
+    ROQR_ERR_FRAME_CANCELLED = 5,
+    ROQR_ERR_UNKNOWN_FLOW = 6,
+    ROQR_ERR_EXPECTATION_UNMET = 7,
+    ROQR_ERR_INVALID_ARG = 100,
+    ROQR_ERR_CONNECT_FAILED = 101,
+    ROQR_ERR_TIMEOUT = 102
+} roqr_error;
+
+typedef enum roqr_delivery_mode {
+    ROQR_DELIVERY_STREAM = 0,
+    ROQR_DELIVERY_DATAGRAM = 1,
+    ROQR_DELIVERY_AUTO = 2
+} roqr_delivery_mode;
+
+/* One RoQR frame crossing the ABI. On the receive callback, `payload`
+ * points into memory owned by the library and valid only for the duration
+ * of the callback; copy it if you need it later. */
+typedef struct roqr_frame {
+    uint64_t flow_id;
+    uint64_t timestamp;
+    uint8_t message_type;
+    uint64_t message_stream_id;
+    uint64_t chunk_stream_id;
+    const uint8_t* payload;
+    size_t payload_len;
+} roqr_frame;
+
+typedef struct roqr_client roqr_client;
+
+/* Library version, "major.minor.patch". */
+const char* roqr_version(void);
+
+roqr_client* roqr_client_create(void);
+void roqr_client_destroy(roqr_client* client);
+
+/* Receive callback: fires on the QUIC network thread. Do NOT block and do
+ * NOT call roqr_client_destroy or roqr_client_wait_* from inside it;
+ * roqr_client_send/close/bind_flow/retire_flow are safe to call. `frame`
+ * and its payload are valid only for the duration of the call. */
+typedef void (*roqr_message_cb)(const roqr_frame* frame, void* user_data);
+
+/* Close callback: fires on the network thread with the peer's application
+ * error code (0 for a clean close). Same non-blocking rules apply. */
+typedef void (*roqr_closed_cb)(uint64_t app_error_code, void* user_data);
+
+/* Set handlers before roqr_client_connect. */
+void roqr_client_set_on_message(roqr_client* client, roqr_message_cb cb,
+                                void* user_data);
+void roqr_client_set_on_closed(roqr_client* client, roqr_closed_cb cb,
+                               void* user_data);
+
+roqr_error roqr_client_connect(roqr_client* client, const char* host,
+                               uint16_t port, int insecure_skip_verify);
+/* Returns 1 if connected within timeout_ms, 0 on timeout. */
+int roqr_client_wait_connected(roqr_client* client, int timeout_ms);
+int roqr_client_datagrams_negotiated(roqr_client* client);
+
+/* Thread-safe. Returns ROQR_ERR_INVALID_ARG for a null client/frame or an
+ * empty payload (RoQR requires payload length > 0). */
+roqr_error roqr_client_send(roqr_client* client, const roqr_frame* frame,
+                            roqr_delivery_mode mode);
+
+void roqr_client_bind_flow(roqr_client* client, uint64_t flow_id);
+void roqr_client_retire_flow(roqr_client* client, uint64_t flow_id);
+
+void roqr_client_close(roqr_client* client, uint64_t app_error_code);
+int roqr_client_wait_closed(roqr_client* client, int timeout_ms);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ROQR_H */

ffi/include/roqr/roqr_rtmp.h

@@ -0,0 +1,43 @@
+#ifndef ROQR_RTMP_H
+#define ROQR_RTMP_H
+
+#include <stdint.h>
+
+#include "roqr/roqr.h" /* roqr_error */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct roqr_ingest roqr_ingest;
+typedef struct roqr_egress roqr_egress;
+
+roqr_ingest* roqr_ingest_create(void);
+void roqr_ingest_destroy(roqr_ingest* ingest);
+/* Starts the RTMP listener on rtmp_port and connects to the RoQR server on
+ * publish. ROQR_OK means the RTMP listener is up; it does NOT mean the RoQR
+ * server leg is live. Wait for roqr_ingest_wait_publishing to confirm the
+ * end-to-end path. */
+roqr_error roqr_ingest_start(roqr_ingest* ingest, uint16_t rtmp_port,
+                              const char* roqr_host, uint16_t roqr_port,
+                              int insecure_skip_verify);
+int roqr_ingest_wait_publishing(roqr_ingest* ingest, int timeout_ms);
+void roqr_ingest_stop(roqr_ingest* ingest);
+
+roqr_egress* roqr_egress_create(void);
+void roqr_egress_destroy(roqr_egress* egress);
+/* Starts the RTMP listener on rtmp_port and plays stream_name from the RoQR
+ * server. Same readiness caveat as ingest: wait for
+ * roqr_egress_wait_playing. */
+roqr_error roqr_egress_start(roqr_egress* egress, uint16_t rtmp_port,
+                              const char* roqr_host, uint16_t roqr_port,
+                              const char* stream_name,
+                              int insecure_skip_verify);
+int roqr_egress_wait_playing(roqr_egress* egress, int timeout_ms);
+void roqr_egress_stop(roqr_egress* egress);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ROQR_RTMP_H */