Use the reviewed background execution contract
Driver App background execution coordinates AppState changes, local permission state, authenticated account state, language readiness, background-location setup, direct location refresh, account refresh, event logging, and provider callbacks.
Mounting the app or moving it between foreground and background can start work without a task button press. This contract describes source responsibilities only; it does not prove runtime isolation, location delivery, provider success, or a deployed backend.
Availability
Background-location setup is source-defined only after the Root-local permission gate reports granted, a token is available, and language loading has settled. The reviewed start branch checks ready/disabled state and the local user-enabled flag but does not explicitly require current authentication before it can issue start intent. A later stop branch checks unauthenticated state. Treat explicit authentication-before-start as a required responsibility, not proven behavior.
Requested/declared/effective OS permission, local grant state, provider authorization, location trust, user availability and server acceptance remain separate.
Prerequisites
- Reviewed native permission declarations and effective merged build state.
- Explicit foreground/background product and privacy requirements.
- Authenticated Driver identity and per-request authorization.
- Zero sensitive logging and clear provider/network egress ownership.
- Deterministic listener/subscription cleanup and account-generation isolation.
- A serial, independently reviewed runtime harness before any execution.
Responsibility boundaries
| Boundary | Responsibility | Limit |
|---|---|---|
| Root AppState listener | Observe active/inactive/background and request configured developer-mode, location, user refresh, permission recheck or event-log work. | Registered once with initial closure state; captured auth/user/loaded values can be stale. |
| Permission provider | Supply current local location-permission state and app-state rechecks. | Permission-completeness finding and listener cleanup remain blocked. |
| Background setup | Configure provider, HTTP/location callbacks, headers, templates, notification and accuracy/lifecycle behavior. | Setup is not start, delivery, trust or cleanup success. |
| Start/stop effect | Reviewed ordering can request start for ready-disabled plus locally enabled user before the later unauthenticated stop branch. | Require explicit current auth/account generation before start; source conditions do not prove provider state. |
| Location callback | Observe provider location events. | A callback value is not fresh/mock-safe/server-stored proof. |
| HTTP callback | Observe provider response, request direct location refresh, and locally logout on unauthorized response. | Response/logging/follow-ons can be partial. |
| Direct location refresh | Read current device location and request Driver-location publication. | C07/C08 trust/storage/broadcast/trail boundaries apply. |
| API/AppState refresh | Refresh current user and record background/connectivity events conditionally. | Captured initial state and failures can suppress or misroute work. |
Inputs and result
| Input/state | Source transition | Observable/client result | Limit |
|---|---|---|---|
| Local permission not granted | Setup returns after clearing local loading. | Provider not configured by that call. | Effective OS state/currentness separate. |
| Missing token | Existing provider listeners are requested for removal. | No configured authenticated setup. | Removal completion/provider state unproven. |
| Permission + token + language ready | Follow location and await provider ready. | Ready/enabled state stored locally. | Provider/server success unproven. |
| Ready, disabled, user enabled | Start can be requested without an explicit current-auth check in that branch. | Provider state may change later. | Authentication/account generation and location delivery remain unproven. |
| Not ready/auth absent/user disabled | Later branch can request stop. | Provider stop intent. | Stop ordering cannot erase a prior stale-user start intent; cleanup unproven. |
| AppState active/background/inactive | Handler can request location/user work; background can request event log. | Async work may begin. | Initial closure can hold null user/token/loaded false. |
| Provider HTTP unauthorized | Local logout requested. | Local auth/navigation can change. | Server/provider/local cleanup separate. |
Security and privacy
- Never persist or expose precise coordinates, raw HTTP/provider responses, tokens, user/order data, provider identifiers or verbose location logs.
- Treat location collection, current/last storage, availability broadcast, customer sharing, order trail/effects and retention as separate approvals.
- Do not assume simulator, background mode or provider debug settings are hermetic.
- Bind callbacks and late results to the current account/session generation.
- Require cleanup to remove every location/HTTP/AppState/permission/provider listener and prove no egress remains.
Limits and failure states
| State | Meaning | Maintainer response |
|---|---|---|
| AppState callback has stale closure | Listener registered with initial Root values. | Do not infer current auth/user/loaded behavior. |
| Async setup returns cleanup function | Cleanup is returned by an async function. | Calling effect does not return/consume it; listeners can remain across dependency changes. |
| Permission listener lacks cleanup | Provider context can retain lifecycle listener. | Fix/test before completeness claim. |
| Provider ready but not started | Configuration settled, start condition separate. | Keep state explicit. |
| Start/stop requested | Provider command intent. | Verify actual state only in isolated harness. |
| Location/HTTP callback | Provider supplied data/response. | No trust/storage/completion inference. |
| Unauthorized callback | Local logout requested. | Cleanup/session/provider effects separate. |
Troubleshooting
| Symptom | Inspect | Safe diagnostic |
|---|---|---|
| Expected AppState refresh does not occur | Initial closure values, listener mount and current account generation | Use static trace; do not background a real authenticated app. |
| Duplicate location/HTTP callbacks appear | Async setup cleanup consumption and permission-provider listener cleanup | Count synthetic listener registrations in an isolated harness. |
| Provider shows ready but no location result | Ready, start, permission, auth, user-enabled and egress states separately | Do not use real coordinates to diagnose. |
| Logout occurs after provider response | HTTP response handling and session cleanup ownership | Treat session/provider state as partial until reconciled. |
| Location appears stored/broadcast unexpectedly | C07/C08 publication, availability and order-trail boundaries | Stop runtime and use privacy/security review. |
Re-review this contract whenever AppState dependencies, permission provider, background setup/start/stop, listener cleanup, location publication, provider callbacks, unauthorized handling or account-generation isolation changes.
Related guides: Device permissions · Location permissions · Location validation · Authenticated bootstrap