README.md

Fleet Worker for Android

Separate package local.hwak.fleetworker; no Activity, launcher replacement, media commands or Quiet TV modifications. It runs an owner-enabled foreground service (specialUse) and restarts through BOOT_COMPLETED/MY_PACKAGE_REPLACED. The APK contains no native libraries and runs on the verified ARM32 TV.

Build

Use a full JDK 21 (the system JRE alone lacks javac), Android SDK 36 and the included Gradle wrapper:

JAVA_HOME=/path/to/jdk21 ./gradlew :app:assembleRelease :app:testReleaseUnitTest :app:lintRelease \
  -PworkerVersionCode=12 -PworkerVersionName=0.5.0

Builds require no production configuration or secrets. preparePublicAssets creates the packaged assets from the tracked safe template and the public RSA key. The legacy ignored app/src/main/assets/release-sources.json is explicitly excluded, and environment configuration is not a build input. Run :app:verifyPublicApk to check that the APK contains exactly the public template.

Provision private release endpoints after installation with the DUMP-protected CONFIGURE_RELEASES action. An operator may keep its JSON locally in ignored .local/release-sources.json; that directory is never packaged. Runtime override values stay in the application’s private preferences and are not returned by status. Per-device worker credentials are provisioned separately.

The output app/build/outputs/apk/release/app-release-unsigned.apk must be signed with the same application certificate for every release. The pinned RSA release public key in assets/release-public.der signs the release manifest separately. Private signing material and per-device credentials stay outside this repository. dist/ is an ignored local handoff directory for local unsigned APK handoff builds.

Bootstrap and control

The owner approves the first installation manually. Deployment is handled by the main operator; this project does not silently initiate a first install.

ControlReceiver is exported under android.permission.DUMP, available to an authorized ADB shell. It accepts explicit broadcasts with these actions:

  • local.hwak.fleetworker.CONFIGURE: extras base_url (HTTPS including optional prefix) and token; worker_id is optional for legacy configuration. A device or enrollment token is accepted. Credentials are written to private preferences; neither status nor logs returns the token.
  • local.hwak.fleetworker.CONFIGURE_RELEASES: extra release_sources containing the public source array below. The entire chain is validated and saved locally; credentials, request headers, HTTP URLs and a fourth source are refused. This control is protected by the same DUMP permission.
  • local.hwak.fleetworker.STATUS: ordered-broadcast result data and status_json extras contain sanitized state/version/current job/outbox/update status.
  • local.hwak.fleetworker.RELOAD: reloads the saved identity and wakes polling.
  • local.hwak.fleetworker.UPDATE_CHECK: requests a release check at the next safe idle point, after durable results have been delivered.
  • local.hwak.fleetworker.CANCEL: explicitly cancels the current script.

WorkerService is also DUMP-protected for an explicit shell foreground-service start if Android restricts a start from the configuration receiver. No Activity or permission prompt is launched. POST_NOTIFICATIONS denial does not stop the worker; the mandatory foreground notification is still supplied to Android.

Server identity and resource profile

Before heartbeats, claims or resuming local work, the service authenticates with POST /v1/workers/connect and persists the returned stable worker_id using a synchronous preferences commit. A token-only initial configuration contains no client-generated identifier. Existing device tokens keep their legacy IDs. A changed server ID cannot replace an identity with pending work; results and checkpoints stay intact. A failed durable write blocks queue use and the next connection reconciles the same credential. Credentials changed during an in-flight connection cannot be overwritten by its old response.

Connect, worker heartbeat and claim include X-Worker-Profile: unpadded base64url of compact UTF-8 JSON schema1. Body capabilities and header capabilities match. Binary chunks, job heartbeats, effects and completions do not repeatedly send the profile. It reports CPU counts from Runtime/process affinity, OS RAM with available memory bounded by the application’s actual heap budget, and total/available bytes on the private state filesystem via StatFs. Filesystem paths, hostname, model, serial and other device identifiers are not sent. Unknown values remain null. Android does not reliably expose GPU compute units or VRAM through these APIs: gpu_status is unknown, gpus is empty, and unified memory is not guessed. These measurements describe current capacity; they introduce no job deadline.

Jobs and durability

API paths follow the separately versioned protocol repository. Each accepted claim is committed to SQLite (synchronous=FULL, WAL) before execution. The result and removal of the current job are committed together. Results remain in an outbox until a matching job_id/attempt_id receipt confirms committed or candidate_saved. The next claim is not taken while an outbox result is unacknowledged. Replacing worker ID or API base is refused while work remains; token rotation is allowed.

Operations:

  • sha256: UTF-8 input.text → { "sha256": "hex" }.
  • text.normalize: Unicode NFC, collapse Unicode whitespace, trim → { "text": "..." }.
  • javascript: Rhino 1.9.1, interpreter-only, portable run(input, resume, ctx) -> JSON. The optional second argument run(input, resume) receives the last local checkpoint. checkpoint(value) synchronously persists JSON; progress(value) updates heartbeat progress. Checkpoints are also sent in heartbeat progress. The third argument offers the same ctx.checkpoint, ctx.progress and synchronous ctx.http.request interface as the portable Node.js adapter. It advertises javascript.portable.v1 for this versioned interface.
  • http.request: declarative HTTP on the native client, with optional per-job network policy, explicit replay semantics, durable effect journal and raw binary streaming. Binary responses use one 1 MiB buffer and server-side artifacts; no intermediate worker-local binary file or base64 is created. artifact.stream is advertised separately. Inline text/JSON requires an explicit byte budget; overflow or invalid encoding preserves the complete original response as an artifact. A response whose encoded control envelope exceeds the gateway’s documented 16 MiB JSON transport capacity also remains a complete artifact (control_budget_exceeded), including original JSON whitespace. This does not limit binary artifact size. There is no overall HTTP/job deadline. Explicit cancellation closes a stalled source connection.

Use stable effect_id values for every ctx.http.request call. GET/HEAD may retry after a transport failure; writes default to never and an uncertain write is not automatically repeated. Vendor-supported idempotent writes require its key. The effect journal reuses a completed response across worker attempts. Before acknowledging an HTTP result, Android persists its small response metadata in a SQLite effect outbox. Restart recovery delivers the same finish request before claiming more work or updating. Permanent delivery conflicts retain the response in a separate diagnostic record so other work can proceed. Job artifact ownership is persisted separately from script checkpoints and cleared only after the completion receipt. A computed result exceeding the JSON control budget is streamed as result.json with result_format: json; its content is the complete original JSON result. Recovery never needs to repeat the vendor request to recover a lost gateway acknowledgement. The gateway stores and verifies streamed bytes before acknowledging them; queue events carry the resulting reference, hash and length. Android retries safe transfers from the source; the portable Node/PHP adapters additionally resume sources offering authenticated Range validators.

Rhino safe standard objects, a deny-all ClassShutter and a rejecting Java object wrapper prevent Java reflection/packages/worker credential access. Inputs and results cross the boundary through JSON, not Java wrappers. The script receives JSON response metadata through the host HTTP interface. No Java object, raw HTTP client, filesystem or worker credential is exposed to scripts. Instruction observation checks explicit cancellation; it does not impose a total execution deadline. Stack/heap exhaustion produces a failed completion when the runtime can recover. Leases are renewed separately from execution; lost lease cancels further work, and a completed stale result is still delivered for server-side candidate storage.

New claims pause on Android’s actual low-memory/thermal-pressure signals. The worker has one execution slot and background thread priority. A physical TV’s sleep/process-kill policy still controls availability; durable work is resumed rather than claiming uninterrupted platform uptime.

The worker heartbeat may set update_poll_seconds live (30 for pilot, 900 for normal polling). Job heartbeat may return lease_until and cancel_requested. No APK restart is necessary to apply the polling policy.

Task proxy configuration

Task HTTP requests (including ctx.http.request) support operator-configured HTTP proxies with HTTPS CONNECT and SOCKS5/SOCKS5h with per-connection username and password authentication. SOCKS names are resolved by the proxy. The worker does not change the process-wide Java authenticator. TLS certificates and origin hostnames are checked normally. A https:// TLS-to-proxy endpoint and SOCKS4 are rejected; an http:// endpoint can tunnel an HTTPS origin using CONNECT. No protocol label is silently converted to another protocol.

The DUMP-protected CONFIGURE_PROXY action accepts the private proxy_json configuration and optional proxy_sources text / proxy_cache JSON extras. These are stored in the app’s private storage and never added to public assets or status output. A configuration has this shape (example addresses only):

{
  "mode": "required",
  "servers": [{"url": "http://proxy.example.invalid:8080", "username": "operator", "password": "private"}],
  "sources_file": "/private/operator/proxy-sources.txt",
  "cache_file": "/private/operator/proxy-cache.json",
  "required_country": "RU"
}

off uses a direct task connection. required never falls back to a direct connection; temporary route failures remain recoverable for safe/idempotent effects. prefer uses an available proxy and permits direct access when no healthy route remains. Uncertain non-replayable effects are not repeated through another route. Explicit servers are trusted operator choices. Source URLs may be one HTTPS URL per line or a JSON array of strings / {url,scheme} objects; the scheme hint is needed for lists containing only host:port.

Sources are fetched anonymously over verified HTTPS, directly, in a background refresh. Plain lists and Proxifly JSON are parsed into private candidates. These candidates are never active solely because a feed calls them Russian or alive. The operator’s cache must contain verified entries with url, optional username/password, verified_at (UTC ISO8601), exit_ip and exit_country; required_country, when present, filters these verified entries. Source failure does not disable already verified routes or ordinary computation. Advisory route health is stored separately, using endpoint hashes, absolute UTC millisecond retry_after_ms / last_ok values and failure counts.

Gateway control, artifact uploads, release discovery and update downloads always use direct connections, independently of task proxies or system proxy settings. Proxy credentials are supplied only to the proxy transport. Caller-provided Proxy-Authorization headers are rejected. The capability proxy.egress.v1 means the worker implements this private routing configuration.

Release discovery and failover

The public template defines this ordered chain:

  1. Unconfigured Gitea placeholder; skipped without a network request. After private provisioning this slot uses the operator’s Gitea latest-release API.
  2. GitFlic public stable.json channel on the release-channel branch.
  3. GitHub public releases/latest/download asset links (no REST API polling).

Gitea selects the exact release assets android-manifest.json and fleet-worker-android.apk; drafts, prereleases, missing or duplicate assets are refused. GitHub uses its latest-release asset redirects directly, avoiding the anonymous REST API rate limit shared by devices behind one public IP. GitFlic’s public channel contains manifest_url and apk_url, pointing to anonymous release downloads; the REST API’s authentication token is never needed on a device. All requests, including redirects, remain HTTPS. Public release transport is separate from the authenticated worker API and never adds its Bearer token. No repository PAT, device token or private signing key is included in the APK.

A source fails over on discovery/network/HTTP errors, invalid metadata or RSA signature, missing assets, transfer/hash failure, or APK identity/certificate failure. The worker tries the next source in the same check; if all fail, it records sources_unavailable and tries again on the next scheduled check. Status exposes only source ID and failure stage/class, without response bodies, credentials or URL query strings. A mirror publishing the installed version does not end the check: later mirrors are checked for a newer release. If a newer signed release is found but its artifact is unavailable, the check reports unavailable rather than current, even if another mirror still publishes the installed version.

Every mirror publishes the same signed manifest bytes and APK. The manifest’s signed canonical URL remains unchanged; a mirror’s APK locator is only a transport address. Its downloaded bytes must match the signed hash and installed certificate. The highest RSA-authenticated version and manifest identity are persisted before transfer. An older version or a different signed artifact with the same version cannot be substituted by fallback, including after a restart. A broken signed release therefore requires a corrected release with a new version code.

The old gateway endpoint is only used once by the installed 0.1.2 bootstrap to deliver a release-chain-enabled worker. It is not a fourth source in the new worker.

GitFlic channel example (locator metadata itself is untrusted):

{
  "manifest_url": "https://gitflic.ru/project/OWNER/REPO/release/RELEASE/FILE/download",
  "apk_url": "https://gitflic.ru/project/OWNER/REPO/release/RELEASE/FILE/download"
}

Source array entries have id, type, url and optional manifest_asset / apk_asset. A manifest source may supply an HTTPS apk_url transport locator without changing the signed canonical URL; IDs must be exactly gitea, gitflic, github in that order. Supported public adapters are gitea, github, channel, manifest and gitflic-api (only for an endpoint actually offering anonymous metadata). The template GitFlic adapter is channel. Reserved .invalid sources are reported as not_configured and skipped without making an HTTP request. A private runtime override restores the configured Gitea primary while preserving the same GitFlic/GitHub fallback and signature checks.

Release API references: Gitea latest release, GitHub latest-release links, GitFlic API authentication.

Silent self-update

Only a valid SHA256withRSA manifest under the pinned release key is accepted. The APK SHA-256, package, versionCode, versionName and same installed signing certificate are checked before the session is committed. Version downgrades and foreign update owners are refused. The current pure-Java APK has no native ABI payload; arbitrary future native-ABI compatibility is not asserted here.

Unattended installation requires Android 12/API31+ and a one-time owner-approved canRequestPackageInstalls() permission/app-op. On older APIs or missing permission the worker reports blocked_*, without opening Settings or an installer screen. The API34 TV is the deployment target for the real proof.

The HTTP client uses OkHttp 4.12.1, including the current certificate trust fix without requiring a newer compile SDK. Network requests keep platform TLS validation enabled; worker API authentication is never forwarded to sources.

PackageInstaller is explicitly set to USER_ACTION_NOT_REQUIRED. Session ID, expected version and hash are persisted before commit. No new job starts during an update session. Result callbacks must match the saved session and version. STATUS_PENDING_USER_ACTION is recorded as blocked and the owned session is abandoned; EXTRA_INTENT is never launched. Retry respects Android’s documented silent-install throttle. Boot/package replacement reconciles installed versions, and successful updates remove only their own obsolete cached APKs.

Tests cover real SHA/Unicode processing, JavaScript JSON/checkpoint semantics, blocked Java access, explicit cancellation of an otherwise unbounded script and RSA signature tampering, ordered mirror failover at every transfer stage, manifest/version conflicts and durable rollback refusal. Full PackageInstaller/SQLite acceptance is verified on the owner’s device after their initial-install approval, not inferred from JVM unit tests.

Upstream runtime: https://github.com/mozilla/rhino (MPL-2.0).

Описание
Portable distributed workers worker-android
Релизы
2026-11-17
последний
Конвейеры
5 успешных
1 с ошибкой
Разработчики