PAM Native Background Transfer
Start here
Section titled “Start here”Every PAM Native product runs on the PAM runtime. Install and verify PAM first, create a Native application, and add this package through PAM Composer:
curl -fsSL https://github.com/push-in/pam/releases/latest/download/install.sh | shpam doctorpam init my-app --template nativecd my-apppam composer require pushinbr/pam-native-background-transferpam doctorpam native devpushinbr/pam-native-background-transfer 0.4 runs a whole pipeline natively:
optional steps before the main request, the upload or download itself, then
follow-up requests that read earlier responses. Android uses WorkManager 2.11.2
(expedited dataSync foreground work when a notification is set) and OkHttp
4.12.0; iOS uses background URLSessions and relaunches the app to chain the
next step. Requires PAM Native >=1.0.35 <2.0.0.
use Pam\Native\BackgroundTransfer\{Backoff, BackgroundTransfer, HttpStep, Multipart, Secret, TransferHandle, TransferNotification, TransferSnapshot};
Secret::put('session', $accessToken); // queued transfers always read the latest value
BackgroundTransfer::upload('https://api.example.com/media') ->multipart(fn (Multipart $m) => $m->file('file', $video->path, 'video/mp4')->field('caption', $caption, template: false)) ->header('Idempotency-Key', $clientMessageId) ->bearer(Secret::vault('session')) ->notification(TransferNotification::make('Enviando vídeo')->progress()->failed('Falha ao enviar')) ->retry(3, Backoff::Exponential) ->unique("chat-media:{$clientMessageId}") ->then(HttpStep::post('https://api.example.com/chats/42/messages') ->bearer(Secret::vault('session')) ->json(['media_id' => '{{response.id}}', 'client_id' => $clientMessageId])) ->tag('chat:42') ->dispatch(fn (TransferHandle $t) => $t->watch(fn (TransferSnapshot $s) => $this->progress = $s->progress()));- Templates:
{{response.a.b}}reads the previous JSON response,{{steps.<name>.…}}a step named withas(),{{transfer.id}}/{{transfer.tag}}the transfer. Usetemplate: falsefor user text. - Retries: network errors and HTTP 408/425/429/5xx; completed steps are
checkpointed and never repeated;
retryable(false)protects non-idempotent steps.BackgroundTransfer::retry($id)resumes after the last completed step. - Transcoding:
->transcode(VideoPreset::Adaptive, fallbackToOriginal: true)re-encodes videos first throughpam-native-media(0.4+ on Android, 0.5+ on iOS). - Recovery: persist
TransferHandle::$id; after relaunch useBackgroundTransfer::find(),all(tag:)andwatch();prune(olderThanDays: 7)cleans finished records. - Security: HTTPS only (HTTP for loopback tests), sandbox-relative paths, specs, checkpoints and the secret vault encrypted with AES-256-GCM (Android Keystore / iOS Keychain); snapshots never contain secrets.
Android merges INTERNET, ACCESS_NETWORK_STATE, FOREGROUND_SERVICE,
FOREGROUND_SERVICE_DATA_SYNC and POST_NOTIFICATIONS; iOS needs no
capability. On iOS there is no progress notification (completed/failed texts
are posted as local notifications) and transcode() runs while the app runs.