Skip to content

PAM Native Background Transfer

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:

Terminal window
curl -fsSL https://github.com/push-in/pam/releases/latest/download/install.sh | sh
pam doctor
pam init my-app --template native
cd my-app
pam composer require pushinbr/pam-native-background-transfer
pam doctor
pam native dev

pushinbr/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 with as(), {{transfer.id}}/{{transfer.tag}} the transfer. Use template: false for 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 through pam-native-media (0.4+ on Android, 0.5+ on iOS).
  • Recovery: persist TransferHandle::$id; after relaunch use BackgroundTransfer::find(), all(tag:) and watch(); 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.