fix: E2E validation — handle permission errors gracefully in examples

flashlight_torch: pass non-null client binder token (camera service
rejects nil with NullPointerException), make GetNumberOfCameras
non-fatal, document android.permission.CAMERA requirement.

server_service: handle SELinux denial on AddService gracefully by
falling back to in-process self-test when running from shell context.

Validated on Pixel device (41041JEKB08092):
- list_packages: 325 packages listed successfully
- error_handling: all 4 sections pass (availability, permissions, typed errors, degradation)
- server_service: SELinux fallback works, in-process ping/echo pass
- flashlight_torch: permission error reported clearly (requires CAMERA permission)

Author: xaionaro@dx.center

README.md

@@ -289,9 +289,13 @@ import (
 
 ### Toggle Flashlight
 
+Requires `android.permission.CAMERA`; see [`examples/flashlight_torch/`](examples/flashlight_torch/) for the full runnable example with permission handling.
+
 ```go
 import (
     "github.com/AndroidGoLab/binder/android/hardware"
+    "github.com/AndroidGoLab/binder/binder"
+    "github.com/AndroidGoLab/binder/parcel"
     "github.com/AndroidGoLab/binder/servicemanager"
 )
 
@@ -301,14 +305,23 @@ import (
     }
     camera := hardware.NewCameraServiceProxy(svc)
 
+    // The camera service requires a non-null client binder token.
+    type token struct{}
+    func (t *token) Descriptor() string { return "torch.client" }
+    func (t *token) OnTransaction(_ context.Context, _ binder.TransactionCode, _ *parcel.Parcel) (*parcel.Parcel, error) {
+        return parcel.New(), nil
+    }
+    clientToken := binder.NewStubBinder(&token{})
+    clientToken.RegisterWithTransport(ctx, transport)
+
     // Turn torch on for camera "0"
-    if err := camera.SetTorchMode(ctx, "0", true, nil); err != nil {
+    if err := camera.SetTorchMode(ctx, "0", true, clientToken); err != nil {
         log.Fatal(err)
     }
     fmt.Println("Torch ON")
 
     // Turn torch off
-    _ = camera.SetTorchMode(ctx, "0", false, nil)
+    _ = camera.SetTorchMode(ctx, "0", false, clientToken)
 ```
 
 ### List All Installed Packages

examples/flashlight_torch/main.go

@@ -4,6 +4,11 @@
 // By default, turns the torch ON for 3 seconds, then turns it OFF.
 // Pass "on" or "off" as a command-line argument to set a specific state.
 //
+// Note: the framework camera service (media.camera) requires the caller
+// to hold android.permission.CAMERA. From the adb shell context this
+// typically fails with a permission error. Run from an app context or
+// with elevated privileges for full functionality.
+//
 // Build:
 //
 //	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o build/flashlight_torch ./examples/flashlight_torch/
@@ -20,9 +25,25 @@ import (
 	"github.com/AndroidGoLab/binder/binder"
 	"github.com/AndroidGoLab/binder/binder/versionaware"
 	"github.com/AndroidGoLab/binder/kernelbinder"
+	"github.com/AndroidGoLab/binder/parcel"
 	"github.com/AndroidGoLab/binder/servicemanager"
 )
 
+// torchClientToken is a minimal TransactionReceiver used as the client
+// binder token for SetTorchMode. The camera service requires a non-null
+// binder to track torch ownership.
+type torchClientToken struct{}
+
+func (t *torchClientToken) Descriptor() string { return "torch.client" }
+
+func (t *torchClientToken) OnTransaction(
+	_ context.Context,
+	_ binder.TransactionCode,
+	_ *parcel.Parcel,
+) (*parcel.Parcel, error) {
+	return parcel.New(), nil
+}
+
 func main() {
 	ctx := context.Background()
 
@@ -49,13 +70,14 @@ func main() {
 
 	cam := hardware.NewCameraServiceProxy(svc)
 
-	// Report the number of available cameras.
+	// Report the number of available cameras (informational; may fail
+	// if the caller lacks android.permission.CAMERA).
 	numCameras, err := cam.GetNumberOfCameras(ctx, hardware.ICameraServiceCameraTypeBackwardCompatible)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "GetNumberOfCameras: %v\n", err)
-		os.Exit(1)
+		fmt.Fprintf(os.Stderr, "GetNumberOfCameras: %v (continuing anyway)\n", err)
+	} else {
+		fmt.Printf("Number of cameras: %d\n", numCameras)
 	}
-	fmt.Printf("Number of cameras: %d\n", numCameras)
 
 	// Determine the desired action from command-line arguments.
 	action := "toggle" // default: on, wait, off
@@ -71,40 +93,46 @@ func main() {
 		}
 	}
 
+	// The camera service requires a non-null client binder token to
+	// track torch ownership. Create a stub and register it with the
+	// transport so it gets a valid cookie.
+	clientToken := binder.NewStubBinder(&torchClientToken{})
+	clientToken.RegisterWithTransport(ctx, transport)
+
 	const cameraID = "0"
 
 	switch action {
 	case "on":
-		fmt.Printf("Turning torch ON for camera %s\n", cameraID)
-		if err := cam.SetTorchMode(ctx, cameraID, true, nil); err != nil {
-			fmt.Fprintf(os.Stderr, "SetTorchMode(on): %v\n", err)
-			os.Exit(1)
-		}
-		fmt.Println("Torch is ON.")
+		setTorch(ctx, cam, cameraID, true, clientToken)
 
 	case "off":
-		fmt.Printf("Turning torch OFF for camera %s\n", cameraID)
-		if err := cam.SetTorchMode(ctx, cameraID, false, nil); err != nil {
-			fmt.Fprintf(os.Stderr, "SetTorchMode(off): %v\n", err)
-			os.Exit(1)
-		}
-		fmt.Println("Torch is OFF.")
+		setTorch(ctx, cam, cameraID, false, clientToken)
 
 	default: // toggle
-		fmt.Printf("Turning torch ON for camera %s\n", cameraID)
-		if err := cam.SetTorchMode(ctx, cameraID, true, nil); err != nil {
-			fmt.Fprintf(os.Stderr, "SetTorchMode(on): %v\n", err)
-			os.Exit(1)
-		}
-		fmt.Println("Torch is ON. Waiting 3 seconds...")
-
+		setTorch(ctx, cam, cameraID, true, clientToken)
+		fmt.Println("Waiting 3 seconds...")
 		time.Sleep(3 * time.Second)
+		setTorch(ctx, cam, cameraID, false, clientToken)
+	}
+}
 
-		fmt.Printf("Turning torch OFF for camera %s\n", cameraID)
-		if err := cam.SetTorchMode(ctx, cameraID, false, nil); err != nil {
-			fmt.Fprintf(os.Stderr, "SetTorchMode(off): %v\n", err)
-			os.Exit(1)
-		}
-		fmt.Println("Torch is OFF.")
+func setTorch(
+	ctx context.Context,
+	cam *hardware.CameraServiceProxy,
+	cameraID string,
+	enabled bool,
+	clientToken binder.IBinder,
+) {
+	state := "OFF"
+	if enabled {
+		state = "ON"
+	}
+
+	fmt.Printf("Turning torch %s for camera %s\n", state, cameraID)
+	if err := cam.SetTorchMode(ctx, cameraID, enabled, clientToken); err != nil {
+		fmt.Fprintf(os.Stderr, "SetTorchMode(%s): %v\n", state, err)
+		fmt.Fprintf(os.Stderr, "Hint: this requires android.permission.CAMERA; from adb shell, try running as root.\n")
+		os.Exit(1)
 	}
+	fmt.Printf("Torch is %s.\n", state)
 }

examples/server_service/main.go

@@ -1,18 +1,26 @@
 // Register a Go service with the ServiceManager and call it back.
 //
+// Demonstrates implementing binder.TransactionReceiver — the server-side
+// binder interface — and registering it via AddService. When running in
+// a restricted SELinux context (e.g. shell), AddService will be denied;
+// in that case the example falls back to an in-process self-test that
+// exercises the same OnTransaction code path.
+//
 // Build:
 //
-//	GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o build/server_service ./examples/server_service/
-//	adb push server_service /data/local/tmp/ && adb shell /data/local/tmp/server_service
+//	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o build/server_service ./examples/server_service/
+//	adb push build/server_service /data/local/tmp/ && adb shell /data/local/tmp/server_service
 package main
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 
 	"github.com/AndroidGoLab/binder/binder"
 	"github.com/AndroidGoLab/binder/binder/versionaware"
+	aidlerrors "github.com/AndroidGoLab/binder/errors"
 	"github.com/AndroidGoLab/binder/kernelbinder"
 	"github.com/AndroidGoLab/binder/parcel"
 	"github.com/AndroidGoLab/binder/servicemanager"
@@ -88,71 +96,148 @@ func main() {
 
 	// Register our ping service with the service manager.
 	svc := &pingService{}
-	if err := sm.AddService(ctx, servicemanager.ServiceName(pingServiceName), svc, false, 0); err != nil {
-		fmt.Fprintf(os.Stderr, "add service: %v\n", err)
-		os.Exit(1)
+	err = sm.AddService(ctx, servicemanager.ServiceName(pingServiceName), svc, false, 0)
+
+	switch {
+	case err == nil:
+		fmt.Printf("Registered service %q\n", pingServiceName)
+		remoteTest(ctx, sm)
+
+	default:
+		// AddService typically fails from the shell SELinux context.
+		// Show the error and fall back to an in-process self-test.
+		var se *aidlerrors.StatusError
+		if errors.As(err, &se) && se.Exception == aidlerrors.ExceptionSecurity {
+			fmt.Printf("AddService denied by SELinux (expected from shell context).\n")
+			fmt.Printf("Falling back to in-process self-test.\n\n")
+		} else {
+			fmt.Fprintf(os.Stderr, "add service: %v\n", err)
+			fmt.Fprintf(os.Stderr, "Falling back to in-process self-test.\n\n")
+		}
+		inProcessTest(ctx, svc)
 	}
-	fmt.Printf("Registered service %q\n", pingServiceName)
+}
 
-	// Self-test: look up the service we just registered and call it.
+// remoteTest looks up the service via the ServiceManager and calls it
+// through the binder driver, exercising the full IPC path.
+func remoteTest(ctx context.Context, sm *servicemanager.ServiceManager) {
 	remote, err := sm.GetService(ctx, servicemanager.ServiceName(pingServiceName))
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "get service: %v\n", err)
 		os.Exit(1)
 	}
 
-	// Call Ping (codePing).
+	callPing(ctx, remote)
+	callEcho(ctx, remote, "hello from Go")
+	fmt.Println("All remote self-tests passed.")
+}
+
+// inProcessTest calls OnTransaction directly, verifying the handler
+// logic without requiring ServiceManager registration.
+func inProcessTest(ctx context.Context, svc *pingService) {
+	// Ping
 	{
 		data := parcel.New()
 		defer data.Recycle()
 		data.WriteInterfaceToken(pingServiceDescriptor)
 
-		reply, err := remote.Transact(ctx, codePing, 0, data)
+		reply, err := svc.OnTransaction(ctx, codePing, data)
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "ping transact: %v\n", err)
+			fmt.Fprintf(os.Stderr, "in-process ping: %v\n", err)
 			os.Exit(1)
 		}
 		defer reply.Recycle()
 
 		if err := binder.ReadStatus(reply); err != nil {
-			fmt.Fprintf(os.Stderr, "ping status: %v\n", err)
+			fmt.Fprintf(os.Stderr, "in-process ping status: %v\n", err)
 			os.Exit(1)
 		}
 
 		result, err := reply.ReadString16()
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "ping read result: %v\n", err)
+			fmt.Fprintf(os.Stderr, "in-process ping read: %v\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("Ping -> %q\n", result)
 	}
 
-	// Call Echo (codeEcho).
+	// Echo
 	{
 		data := parcel.New()
 		defer data.Recycle()
 		data.WriteInterfaceToken(pingServiceDescriptor)
 		data.WriteString16("hello from Go")
 
-		reply, err := remote.Transact(ctx, codeEcho, 0, data)
+		reply, err := svc.OnTransaction(ctx, codeEcho, data)
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "echo transact: %v\n", err)
+			fmt.Fprintf(os.Stderr, "in-process echo: %v\n", err)
 			os.Exit(1)
 		}
 		defer reply.Recycle()
 
 		if err := binder.ReadStatus(reply); err != nil {
-			fmt.Fprintf(os.Stderr, "echo status: %v\n", err)
+			fmt.Fprintf(os.Stderr, "in-process echo status: %v\n", err)
 			os.Exit(1)
 		}
 
 		result, err := reply.ReadString16()
 		if err != nil {
-			fmt.Fprintf(os.Stderr, "echo read result: %v\n", err)
+			fmt.Fprintf(os.Stderr, "in-process echo read: %v\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("Echo -> %q\n", result)
 	}
 
-	fmt.Println("All self-tests passed.")
+	fmt.Println("All in-process self-tests passed.")
+}
+
+func callPing(ctx context.Context, remote binder.IBinder) {
+	data := parcel.New()
+	defer data.Recycle()
+	data.WriteInterfaceToken(pingServiceDescriptor)
+
+	reply, err := remote.Transact(ctx, codePing, 0, data)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "ping transact: %v\n", err)
+		os.Exit(1)
+	}
+	defer reply.Recycle()
+
+	if err := binder.ReadStatus(reply); err != nil {
+		fmt.Fprintf(os.Stderr, "ping status: %v\n", err)
+		os.Exit(1)
+	}
+
+	result, err := reply.ReadString16()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "ping read result: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("Ping -> %q\n", result)
+}
+
+func callEcho(ctx context.Context, remote binder.IBinder, msg string) {
+	data := parcel.New()
+	defer data.Recycle()
+	data.WriteInterfaceToken(pingServiceDescriptor)
+	data.WriteString16(msg)
+
+	reply, err := remote.Transact(ctx, codeEcho, 0, data)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "echo transact: %v\n", err)
+		os.Exit(1)
+	}
+	defer reply.Recycle()
+
+	if err := binder.ReadStatus(reply); err != nil {
+		fmt.Fprintf(os.Stderr, "echo status: %v\n", err)
+		os.Exit(1)
+	}
+
+	result, err := reply.ReadString16()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "echo read result: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("Echo -> %q\n", result)
 }