Integrating with Android and the Platform

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <uses-permission android:name="com.example.settings.permission.ACCESS_DEVICE_SETTINGS" />

    <!-- Android 11+: without this, the settings app is invisible to us and bindService fails. -->
    <queries>
        <package android:name="com.example.settings" />
    </queries>

    <application android:label="@string/app_name" android:allowBackup="false">

        <!-- The embedded HTTP server. Not exported: only this app starts it. -->
        <service android:name=".ApiServerService" android:exported="false" />

        <!-- Restarts the server after a reboot or an update of this app. Has an intent filter,
             so Android 12+ requires an explicit android:exported. -->
        <receiver android:name=".BootReceiver" android:exported="false">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />
                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
            </intent-filter>
        </receiver>
    </application>
</manifest>

class BootReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action != Intent.ACTION_BOOT_COMPLETED &&
            intent.action != Intent.ACTION_MY_PACKAGE_REPLACED
        ) return
        // Both are listed exemptions from the Android 12 ban on background foreground-service starts.
        Log.i("ApiServer", "BootReceiver: ${intent.action}")
        ApiServerService.start(context)
    }
}

private fun handle(client: Socket) {
    client.use { conn ->
        conn.soTimeout = 5_000
        val input = conn.getInputStream().bufferedReader()
        val parts = (input.readLine() ?: return).split(" ")
        var contentLength = 0
        while (true) {
            val header = input.readLine() ?: return
            if (header.isEmpty()) break
            if (header.startsWith("content-length:", ignoreCase = true)) {
                contentLength = header.substringAfter(':').trim().toIntOrNull() ?: 0
            }
        }
        // read() may return part of the body: loop until all of it has arrived.
        val buffer = CharArray(contentLength.coerceIn(0, 1024))
        var filled = 0
        while (filled < buffer.size) {
            val n = input.read(buffer, filled, buffer.size - filled)
            if (n < 0) break
            filled += n
        }
        val body = buffer.concatToString(0, filled)
        val (status, json) = route(parts.getOrElse(0) { "" }, parts.getOrElse(1) { "" }, body)
        val bytes = json.toString().toByteArray()
        conn.getOutputStream().apply {
            write(("HTTP/1.1 $status\r\nContent-Type: application/json\r\n" +
                "Content-Length: ${bytes.size}\r\nConnection: close\r\n\r\n").toByteArray())
            write(bytes)
            flush()
        }
    }
}

private fun route(method: String, path: String, body: String): Pair<String, JSONObject> {
    if (method == "GET" && path == "/api/v1/status") {
        return "200 OK" to JSONObject().put("state", "ready").put("settingsConnected", settings.service != null)
    }
    val key = path.removePrefix("/api/v1/settings/")
    if (key == path || key.isEmpty()) return "404 Not Found" to problem("Not Found")
    val service = settings.service ?: return "503 Service Unavailable" to problem("Settings service not connected")
    return try {
        when (method) {
            "GET" -> service.getSetting(key)
                ?.let { "200 OK" to JSONObject().put("key", key).put("value", it) }
                ?: ("404 Not Found" to problem("Unknown setting"))
            "PUT" -> if (service.setSetting(key, body.trim())) {
                "200 OK" to JSONObject().put("key", key).put("value", body.trim())
            } else {
                "422 Unprocessable Content" to problem("Rejected by the settings service")
            }
            else -> "405 Method Not Allowed" to problem("Method Not Allowed")
        }
    } catch (e: RemoteException) {
        "503 Service Unavailable" to problem("Settings service died")
    } catch (e: SecurityException) {
        "500 Internal Server Error" to problem("Not allowed to use the settings service")
    }
}

$ curl -s -i http://127.0.0.1:18609/api/v1/status
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 42
Connection: close

{"state":"ready","settingsConnected":true}

$ curl -s http://127.0.0.1:18609/api/v1/settings/display.brightness
{"key":"display.brightness","value":"70"}

$ curl -s -X PUT --data 65 http://127.0.0.1:18609/api/v1/settings/display.brightness
{"key":"display.brightness","value":"65"}

$ curl -s -i -X PUT --data 140 http://127.0.0.1:18609/api/v1/settings/display.brightness
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
Content-Length: 44
Connection: close

{"title":"Rejected by the settings service"}

$ curl -s -i http://127.0.0.1:18609/api/v1/settings/nope
HTTP/1.1 404 Not Found
...
{"title":"Unknown setting"}

$ cat /proc/sys/net/ipv4/ip_unprivileged_port_start
1024
$ run-as com.example.webapi toybox nc -l -p 80
nc: bind: Permission denied
$ run-as com.example.webapi toybox nc -l -p 8081 &
$ netstat -ltn | grep 8081
tcp6       0      0 [::]:8081               [::]:*                  LISTEN

// The on-device web API is a bridge: HTTP in, a platform-service call out.
// Every way the platform call can fail needs its own HTTP answer. Binder calls have no timeout
// of their own, so the bridge adds one.
import express from "express";
import request from "supertest";

class RemoteException extends Error {}
let neverSettles; // a call that hangs, like a platform service stuck on a lock
const platform = {
  connected: true,
  async getSetting(key) {
    if (key === "audio.volume") throw new RemoteException("DeadObjectException");
    if (key === "camera.ptz") return new Promise((resolve) => (neverSettles = resolve));
    if (key === "secure.pin") throw Object.assign(new Error("Caller lacks permission"), { name: "SecurityException" });
    return { "display.brightness": "70" }[key] ?? null;
  },
};

const withTimeout = (promise, ms) =>
  Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), ms).unref())]);

const app = express();
app.get("/api/v1/settings/:key", async (req, res) => {
  if (!platform.connected) return res.status(503).set("Retry-After", "2").json({ title: "Settings service not connected" });
  try {
    const value = await withTimeout(platform.getSetting(req.params.key), 50);
    if (value === null) return res.status(404).json({ title: "Unknown setting" });
    res.json({ key: req.params.key, value });
  } catch (e) {
    if (e instanceof RemoteException) return res.status(503).set("Retry-After", "2").json({ title: "Settings service died" });
    if (e.message === "timeout") return res.status(504).json({ title: "Settings service did not answer" });
    res.status(500).json({ title: "Internal error" }); // SecurityException: our bug, not the caller's
  }
});

for (const key of ["display.brightness", "nope", "audio.volume", "camera.ptz", "secure.pin"]) {
  const r = await request(app).get(`/api/v1/settings/${key}`);
  console.log(`${key.padEnd(19)} ${r.status} ${JSON.stringify(r.body)}${r.headers["retry-after"] ? " Retry-After: 2" : ""}`);
}
platform.connected = false;
const r = await request(app).get("/api/v1/settings/display.brightness");
console.log(`(disconnected)      ${r.status} ${JSON.stringify(r.body)}`);
neverSettles?.(null);

display.brightness  200 {"key":"display.brightness","value":"70"}
nope                404 {"title":"Unknown setting"}
audio.volume        503 {"title":"Settings service died"} Retry-After: 2
camera.ptz          504 {"title":"Settings service did not answer"}
secure.pin          500 {"title":"Internal error"}
(disconnected)      503 {"title":"Settings service not connected"}

// Can the app call startForegroundService() right now? A model of the Android 12 rule
// (developer.android.com, "Restrictions on starting a foreground service from the background",
// read October 2026). Only a few of the listed exemptions are modelled here.
const EXEMPT_TRIGGERS = new Set([
  "BOOT_COMPLETED", "LOCKED_BOOT_COMPLETED", "MY_PACKAGE_REPLACED", // after reboot or update
  "user tapped notification or widget", "exact alarm for a user action", "high-priority FCM",
]);

function canStartForegroundService({ targetSdk, appVisible, trigger, deviceOwner = false }) {
  if (targetSdk < 31) return "allowed (rule applies from targetSdk 31)";
  if (appVisible) return "allowed (app is in the foreground)";
  if (EXEMPT_TRIGGERS.has(trigger)) return `allowed (exemption: ${trigger})`;
  if (deviceOwner) return "allowed (exemption: device owner)";
  return "ForegroundServiceStartNotAllowedException";
}

const cases = [
  { label: "launcher activity on screen", targetSdk: 33, appVisible: true, trigger: "activity" },
  { label: "BootReceiver after reboot", targetSdk: 33, appVisible: false, trigger: "BOOT_COMPLETED" },
  { label: "BootReceiver after app update", targetSdk: 33, appVisible: false, trigger: "MY_PACKAGE_REPLACED" },
  { label: "custom broadcast in background", targetSdk: 33, appVisible: false, trigger: "custom broadcast" },
  { label: "same, app still targeting 30", targetSdk: 30, appVisible: false, trigger: "custom broadcast" },
  { label: "same, app is device owner", targetSdk: 33, appVisible: false, trigger: "custom broadcast", deviceOwner: true },
];

for (const c of cases) console.log(`${c.label.padEnd(32)} → ${canStartForegroundService(c)}`);

launcher activity on screen      → allowed (app is in the foreground)
BootReceiver after reboot        → allowed (exemption: BOOT_COMPLETED)
BootReceiver after app update    → allowed (exemption: MY_PACKAGE_REPLACED)
custom broadcast in background   → ForegroundServiceStartNotAllowedException
same, app still targeting 30     → allowed (rule applies from targetSdk 31)
same, app is device owner        → allowed (exemption: device owner)

# android:exported removed from a <receiver> that has an <intent-filter>:
Manifest merger failed : android:exported needs to be explicitly specified for element
<receiver#com.example.webapi.BootReceiver>. Apps targeting Android 12 and higher are required to
specify an explicit value for `android:exported` when the corresponding component has an intent
filter defined.

# PendingIntent.FLAG_IMMUTABLE replaced by 0 (lint):
UnspecifiedImmutableFlag | Missing PendingIntent mutability flag

# webapi still declares <uses-permission> for the settings app's custom permission:
I SettingsClient: bindService returned true (provider visible: true)
# webapi without <queries> and without that <uses-permission>:
I SettingsClient: bindService returned false (provider visible: false)

// IDeviceSettings.aidl: the contract between the settings service and its clients.
package com.example.settings;

import com.example.settings.ISettingsListener;

interface IDeviceSettings {
    /** Bumped when methods are added, so a client can check before calling a newer one. */
    int apiVersion();

    /** Returns null if the key is unknown. */
    String getSetting(String key);

    /** Returns false if the key is unknown or the value is invalid. */
    boolean setSetting(String key, String value);

    void registerListener(ISettingsListener listener);
    void unregisterListener(ISettingsListener listener);
}

// ISettingsListener.aidl: a callback the client implements and the service calls.
package com.example.settings;

oneway interface ISettingsListener {
    void onSettingChanged(String key, String value);
}

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Only apps signed with the same certificate as this app are granted it. -->
    <permission
        android:name="com.example.settings.permission.ACCESS_DEVICE_SETTINGS"
        android:label="Access device settings"
        android:protectionLevel="signature" />

    <application android:label="@string/app_name" android:allowBackup="false">
        <service
            android:name=".DeviceSettingsService"
            android:exported="true"
            android:permission="com.example.settings.permission.ACCESS_DEVICE_SETTINGS">
            <intent-filter>
                <action android:name="com.example.settings.BIND_DEVICE_SETTINGS" />
            </intent-filter>
        </service>
    </application>
</manifest>

class SettingsClient(private val context: Context) : ServiceConnection {

    @Volatile var service: IDeviceSettings? = null
        private set

    fun bind(): Boolean {
        val intent = Intent("com.example.settings.BIND_DEVICE_SETTINGS")
            .setPackage(PROVIDER) // bindService needs an explicit intent
        val ok = try {
            context.bindService(intent, this, Context.BIND_AUTO_CREATE)
        } catch (e: SecurityException) {
            Log.e(TAG, "not allowed to bind: ${e.message}") // e.g. lacking the signature permission
            false
        }
        Log.i(TAG, "bindService returned $ok (provider visible: ${isVisible()})")
        return ok
    }

    private fun isVisible() = try {
        context.packageManager.getPackageInfo(PROVIDER, 0)
        true
    } catch (e: PackageManager.NameNotFoundException) {
        false // filtered by package visibility (Android 11+), or not installed
    }

    fun unbind() {
        // Context's contract: call unbindService() whatever bindService() returned or threw.
        try {
            context.unbindService(this)
        } catch (e: IllegalArgumentException) {
            // The connection was never registered.
        }
        service = null
    }

    override fun onServiceConnected(name: ComponentName, binder: IBinder) {
        service = IDeviceSettings.Stub.asInterface(binder)
        Log.i(TAG, "connected to $name, apiVersion ${service?.apiVersion()}")
    }

    override fun onServiceDisconnected(name: ComponentName) {
        // The provider's process died. The binding stays; Android reconnects when it restarts.
        service = null
        Log.w(TAG, "disconnected from $name")
    }

    override fun onBindingDied(name: ComponentName) {
        // The binding itself is dead (for example, the provider app was updated): bind again.
        Log.w(TAG, "binding died for $name; binding again")
        unbind()
        bind()
    }

    private companion object {
        const val TAG = "SettingsClient"
        const val PROVIDER = "com.example.settings"
    }
}

// How AIDL calls travel: the generated proxy sends a transaction *number*, not a method name.
// Numbers are FIRST_CALL_TRANSACTION (1) + the method's position in the .aidl file.
const FIRST_CALL_TRANSACTION = 1;
const codesFor = (methods) => Object.fromEntries(methods.map((m, i) => [m, FIRST_CALL_TRANSACTION + i]));

// A tiny Parcel of typed values. Reading past the end, or reading a String where a boolean was
// written, gives null: what the real proxies returned on an Android 16 emulator.
const parcel = (values = []) => ({ values, pos: 0,
  readString() { const x = this.values[this.pos++]; return typeof x === "string" ? x : null; } });

function makeService(methods, impl) {
  const byCode = Object.fromEntries(methods.map((m, i) => [FIRST_CALL_TRANSACTION + i, m]));
  return (code, data) => {
    const method = byCode[code];
    if (!method) return { handled: false, reply: parcel() }; // unknown code: onTransact returns false
    return { handled: true, reply: parcel([impl[method](data)]) };
  };
}

function makeProxy(methods, transact) {
  const codes = codesFor(methods);
  // Like the generated Proxy: the boolean result of transact() is ignored.
  return (method, ...args) => transact(codes[method], parcel(args)).reply.readString();
}

const v2Methods = ["apiVersion", "getSetting", "setSetting", "registerListener", "unregisterListener"];
const settings = { "display.brightness": "70" };
const v2Service = makeService(v2Methods, {
  apiVersion: () => "2",
  getSetting: (d) => settings[d.readString()] ?? null,
  setSetting: (d) => { const k = d.readString(), v = d.readString();
    console.log(`     (service ran setSetting(${k}, ${v}))`); return v !== null; },
  registerListener: () => null, unregisterListener: () => null,
});

const appended = [...v2Methods, "exportAll"];
const inserted = ["apiVersion", "exportAll", ...v2Methods.slice(1)];

for (const [label, methods] of [["v2 client", v2Methods], ["v3 client, method appended", appended],
                                ["v3 client, method inserted", inserted]]) {
  const call = makeProxy(methods, v2Service);
  console.log(`${label}: codes ${JSON.stringify(codesFor(methods))}`);
  console.log(`  getSetting("display.brightness") -> ${call("getSetting", "display.brightness")}`);
  if (methods.includes("exportAll")) console.log(`  exportAll() -> ${call("exportAll")}`);
}

v2 client: codes {"apiVersion":1,"getSetting":2,"setSetting":3,"registerListener":4,"unregisterListener":5}
  getSetting("display.brightness") -> 70
v3 client, method appended: codes {"apiVersion":1,"getSetting":2,"setSetting":3,"registerListener":4,"unregisterListener":5,"exportAll":6}
  getSetting("display.brightness") -> 70
  exportAll() -> null
v3 client, method inserted: codes {"apiVersion":1,"exportAll":2,"getSetting":3,"setSetting":4,"registerListener":5,"unregisterListener":6}
     (service ran setSetting(display.brightness, null))
  getSetting("display.brightness") -> null
  exportAll() -> null

<permissions>
    <privapp-permissions package="com.example.webapi">
        <permission name="android.permission.WRITE_SECURE_SETTINGS"/>
        <deny-permission name="android.permission.READ_PRIVILEGED_PHONE_STATE"/>
    </privapp-permissions>
</permissions>