Skip to content

Commit 68ff6de

Browse files
xaionaro@dx.centerxaionaro@dx.center
authored andcommitted
docs: move gRPC/deploy/E2E sections to jni-proxy README
The jni README now focuses on core JNI bindings, Android API packages, and code generation. gRPC remote access, deployment instructions, and E2E verification details moved to the jni-proxy repository.
1 parent acd4d76 commit 68ff6de

1 file changed

Lines changed: 7 additions & 125 deletions

File tree

README.md

Lines changed: 7 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](LICENSE)
66
[![Go Version](https://img.shields.io/github/go-mod/go-version/AndroidGoLab/jni)](go.mod)
77

8-
Idiomatic Go bindings for the Java Native Interface and 53 Android Java API packages, auto-generated from YAML specs to ensure full coverage and easy maintenance. Includes a gRPC layer for remote Android API access.
8+
Idiomatic Go bindings for the Java Native Interface and 53 Android Java API packages, auto-generated from YAML specs to ensure full coverage and easy maintenance.
9+
10+
For remote Android API access over gRPC, see [jni-proxy](https://github.com/AndroidGoLab/jni-proxy).
911

1012
## Android Interfaces for Go
1113

@@ -276,60 +278,7 @@ flowchart TD
276278

277279
3. **Android API Layer** (53 packages) — High-level wrappers for Android system services. Each package provides a `Manager` type obtained via `NewManager(ctx)`, with methods that call through JNI. Generated by `javagen`.
278280

279-
4. **gRPC Layer** (`grpc/`) — Remote proxy for Android APIs over gRPC. A companion app runs the gRPC server on-device; clients call Android APIs from any machine. Generated by `grpcgen`.
280-
281-
### gRPC Remote Access
282-
283-
The gRPC layer turns any Android phone into a remotely accessible API server. A companion service (`jniservice`) runs on the device — either as an APK (non-rooted) or a Magisk module (rooted, auto-starts on boot). Clients on any machine connect over the network using `jnicli`.
284-
285-
```mermaid
286-
sequenceDiagram
287-
participant Client as jnicli (host)
288-
participant Server as jniservice (phone)
289-
participant Android as Android APIs
290-
291-
Client->>Server: auth register (CSR)
292-
Server-->>Client: signed client cert + CA cert
293-
294-
Client->>Server: auth request-permission
295-
Server->>Android: launch approval dialog
296-
Note over Android: User taps "Approve"
297-
Server-->>Client: status: approved
298-
299-
Client->>Server: location get (mTLS)
300-
Server->>Android: LocationManager.getLastKnownLocation()
301-
Android-->>Server: Location object
302-
Server-->>Client: {lat, lon, alt, accuracy}
303-
```
304-
305-
Each client registers with a unique certificate (mTLS). Method access is controlled by per-service ACLs — the device owner approves which services each client can use through an on-screen dialog:
306-
307-
```mermaid
308-
flowchart LR
309-
subgraph Client
310-
CLI["jnicli"]
311-
end
312-
313-
subgraph "jniservice (on device)"
314-
TLS["mTLS gateway"]
315-
ACL["Per-service ACL"]
316-
SVC["31 Android API\nservices"]
317-
RAW["Raw JNI surface"]
318-
PROXY["Callback proxy\n(Camera2, etc.)"]
319-
end
320-
321-
CLI -->|client cert| TLS
322-
TLS --> ACL
323-
ACL -->|"camera.*"| SVC
324-
ACL -->|"admin only"| RAW
325-
SVC --> Android["Android\nFramework"]
326-
RAW --> Android
327-
PROXY --> Android
328-
```
329-
330-
**Available services** include camera, location, bluetooth, WiFi, telephony, battery, power, alarm, vibrator, audio, NFC, notifications, and more (31 services total, ~2000 RPCs). Callback-based APIs (like Camera2) work through a bidirectional streaming proxy with build-time generated adapter classes.
331-
332-
> **Security disclaimer:** This is a hobby/research project. The mTLS + ACL system provides basic access control, but it has not been audited and should not be relied upon for security-critical deployments. The self-signed CA, handle-based object references, and raw JNI surface all have inherent attack surface. Use it on trusted networks for development, testing, and experimentation.
281+
4. **gRPC Layer** — See [jni-proxy](https://github.com/AndroidGoLab/jni-proxy) for the gRPC remote access layer.
333282

334283
## Project Layout
335284

@@ -338,7 +287,6 @@ flowchart LR
338287
├── *.go # Core JNI types (VM, Env, Class, Object, ...)
339288
├── capi/ # Raw CGo bindings to JNI C API
340289
├── internal/ # Internal: exception handling, test JVM
341-
├── handlestore/ # Object handle mapping for gRPC
342290
343291
├── app/ # Android API wrappers (Java SDK hierarchy)
344292
│ ├── alarm/, download/, ...
@@ -353,11 +301,6 @@ flowchart LR
353301
│ ├── power/, battery/, ...
354302
├── ... # (53 packages total)
355303
356-
├── grpc/ # gRPC client/server for remote access
357-
│ ├── client/
358-
│ └── server/
359-
├── proto/ # Protocol buffer definitions
360-
361304
├── tools/ # Code generators
362305
│ ├── jnigen/ # Core JNI + capi generation
363306
│ ├── javagen/ # Android API package generation
@@ -372,8 +315,7 @@ flowchart LR
372315
│ └── java/
373316
374317
├── ref/android/ # Reference .class files
375-
├── examples/ # Per-package usage examples
376-
└── e2e/ # End-to-end tests (Android device)
318+
└── examples/ # Per-package usage examples
377319
```
378320

379321
## Make Targets
@@ -386,77 +328,17 @@ flowchart LR
386328
| `make proto` | Generate .proto files | -- |
387329
| `make protoc` | Compile .proto to Go stubs | protoc + protoc-gen-go |
388330
| `make grpc` | Generate gRPC server/client | protoc |
331+
| `make cli` | Generate jnicli cobra commands | protoc |
389332
| `make test` | Run all tests | JDK |
390333
| `make test-tools` | Run generator tests only | -- |
391334
| `make build` | Cross-compile for android/arm64 | Android NDK |
392335
| `make lint` | Run golangci-lint | golangci-lint |
393336
| `make clean` | Remove all generated files | -- |
394337

395-
## Running jniservice on Android
396-
397-
jniservice is a gRPC server that exposes the JNI surface and Android APIs over the network.
398-
399-
### Development (via adb)
400-
401-
```bash
402-
make deploy # build, push, start, forward port
403-
make deploy HOST_PORT=50052 # use different host port
404-
make stop-server # stop the server
405-
```
406-
407-
### Rooted devices (Magisk module)
408-
409-
Auto-starts on boot. Self-contained — no `make deploy` needed after install.
410-
411-
```bash
412-
make magisk DIST_GOARCH=arm64 # build module
413-
adb push build/jniservice-magisk-arm64-v8a.zip /sdcard/
414-
adb shell su -c "magisk --install-module /sdcard/jniservice-magisk-arm64-v8a.zip"
415-
adb reboot # starts on next boot
416-
```
417-
418-
Configuration: create `/data/local/tmp/jniservice.env` on the device:
419-
```bash
420-
JNISERVICE_PORT=50051
421-
JNISERVICE_TOKEN=my-secret-token
422-
```
423-
424-
### Non-rooted devices (APK)
425-
426-
Auto-starts on boot via foreground service.
427-
428-
```bash
429-
make apk DIST_GOARCH=arm64 # build APK
430-
adb install build/jniservice-arm64-v8a.apk
431-
```
432-
433-
Open "jniservice" from the launcher once to start the service and register the boot receiver.
434-
435-
### Connecting
436-
437-
```bash
438-
adb forward tcp:50051 tcp:50051
439-
jnicli --addr localhost:50051 --insecure jni get-version
440-
```
441-
442-
## E2E Test Verification
443-
444-
Run `make test-emulator` to test against a connected device or emulator. Tests skip when `JNICTL_E2E_ADDR` is not set.
445-
446-
<details>
447-
<summary>Verified platforms (click to expand)</summary>
448-
449-
| Type | Device | Android | API | ABI | Build | Date | Passed | Total |
450-
|------|--------|---------|-----|-----|-------|------|--------|-------|
451-
| Phone | Pixel 8a | 16 | 36 | arm64-v8a | BP4A.260205.001 | 2026-03-14 | 21 | 21 |
452-
| Emulator | sdk_gphone64_x86_64 | 15 | 35 | x86_64 | | 2026-03-14 | 21 | 21 |
453-
454-
</details>
455-
456338
## Adding a New Android API Package
457339

458340
1. Create `spec/java/{package}.yaml` with the Java class, methods, and `go_import` path.
459341
2. Optionally create `spec/overlays/java/{package}.yaml` for customizations (extra methods, type overrides, name overrides).
460342
3. Run `make java` to generate the Go package.
461-
4. Run `make proto protoc grpc` if gRPC support is needed.
343+
4. For gRPC support, see [jni-proxy](https://github.com/AndroidGoLab/jni-proxy).
462344

0 commit comments

Comments
 (0)