Search by

pushinbr / pam-native-background-transfer

DavidWilliamBalbino

Durable background uploads, downloads and request chains for PAM Native.

Package info

github.com/push-in/pam-native-background-transfer

Language:Swift

Type:pam-native-plugin

pkg:composer/pushinbr/pam-native-background-transfer

Statistics

Installs: 391

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 1

v0.5.0 2026-11-19 00:22 UTC

README

pam-native-background-transfer: Durable background uploads, downloads and request chains for PAM Native.

Uploads and downloads that survive backgrounding and process death.
Schedule durable, observable transfers and HTTP request chains through WorkManager and background URLSession while your PHP application stays responsive.

Packagist Latest release PHP 8.5 CI License

Install · Quick example · Platforms · Permissions · Docs · Issues

Install

Inside a PAM Native project, add only this capability:

pam composer require pushinbr/pam-native-background-transfer
pam doctor --fix

The package is a PAM Native plugin (module background-transfer); nothing is added to pam-native.json. Use pam packages to list direct requirements and pam composer remove pushinbr/pam-native-background-transfer to uninstall. New to PAM? Create a project with pam init my-app --template native (see the PAM Native overview), then come back here.

Quick example

<?php

use Pam\Native\BackgroundTransfer\{Backoff, BackgroundTransfer, HttpStep, Multipart, NetworkRequirement, Secret, TransferHandle, TransferNotification, TransferSnapshot};

Secret::put('session', $accessToken); // refresh it any time; queued transfers 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('Sending video')->progress()->failed('Upload failed'))
    ->network(NetworkRequirement::Unmetered)
    ->retry(3, Backoff::Exponential)
    ->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 $transfer) => $transfer->watch(
        fn (TransferSnapshot $s) => $this->progress = $s->progress(),
    ));

The video uploads and the message is posted even if the app is closed. Signed URL uploads, transcoding before upload, downloads, templates and the Zé Chat outbox are in the guide; every class and error is in the API reference. A runnable minimal app is in example/.

Platform support

Platform Support Notes
Android API 24+ WorkManager 2.11.2 (expedited + dataSync foreground service when a notification is set), OkHttp 4.12.0
iOS 15.0+ Background URLSession for every step; Security, UserNotifications; not validated on a device yet
PAM Native 1.0.35 to < 2.0.0 From pam-native.plugin.json; PHP 8.5+

Permissions and requirements

Platform Declared by the plugin
Android android.permission.ACCESS_NETWORK_STATE, INTERNET, FOREGROUND_SERVICE, FOREGROUND_SERVICE_DATA_SYNC, POST_NOTIFICATIONS
iOS No Info.plist keys or capabilities (background URLSessions do not need a background mode)

Request PermissionKind::Notifications on Android 13+ if you want the progress notification to be visible; transfers run either way. transcode() needs pushinbr/pam-native-media 0.4+ on Android and 0.5+ on iOS. Full notes: docs/platform-notes.md.

What you can build

  • Resumable media uploads that post the message when the file lands
  • Signed URL uploads and request chains of up to 64 steps
  • Offline download queues for video, documents or maps
  • Reliable sync of large files under constrained networks
Native path WorkManager + OkHttp · background URLSession
Application model Composer package + generated native integration
Design rule Independent module; no feed, vertical or application template bundled

Retries and security

Retries cover network errors and HTTP 408/425/429/5xx; other 4xx responses fail immediately with statusCode and response on the snapshot. Completed steps are checkpointed, so neither automatic nor manual retries repeat them. Mark a non-idempotent step with ->retryable(false) to fail instead of repeating it automatically.

URLs must be HTTPS (plain HTTP is accepted only for loopback test servers). Paths are PAM sandbox paths (FileReference::$path) and traversal is rejected natively. Transfer specs, step checkpoints and the secret vault are encrypted with AES-256-GCM (a non-exportable Android Keystore key; a device-only Keychain key on iOS) and are excluded from backups; snapshots never contain secrets.

Compatibility

pushinbr/pam-native-background-transfer pushinbr/pam-native Android iOS
0.4.x >=1.0.35 <2.0.0 (tested with 1.14.x) API 26+ 15+, full pipelines (transcode() with pam-native-media 0.5+)
0.3.x >=1.0.35 <2.0.0 API 26+ Single requests only

Platform SDKs, credentials, entitlements, physical hardware and store configuration remain application responsibilities.

Tests

composer test runs the PHP contract suite. Android JVM tests live in android/src/test and instrumented tests (MockWebServer, WorkManager, cross-plugin transcode) in android/src/androidTest; run them from a PAM Android host that includes this plugin (and pam-native-media for the transcode test) with connectedDebugAndroidTest.

Production checklist

  • Persist transfer identifiers before leaving the initiating screen.
  • Reconcile transfer state after launch and resume.
  • Treat destination files as untrusted until size, type and checksum validation pass.
  • Run pam doctor, pam test and a signed release build on every supported platform.
  • Exercise denial, cancellation, backgrounding, process restart and offline behavior before release.

Security vulnerabilities should be reported through the repository security policy or GitHub private vulnerability reporting, not a public issue.

Troubleshooting

  • Work never starts: verify HTTPS, network constraints and OS background policy.
  • Path rejected: use an application-sandbox-relative path without traversal.
  • Progress stops in development: query the persisted identifier after runtime reload.
  • A watch goes silent: a watch ends when the native module restarts; re-read the durable state with BackgroundTransfer::find() (Zé Chat re-checks after 30 s without a snapshot).
  • A 4xx response is not retried: only network errors and HTTP 408/425/429/5xx are retried; inspect TransferSnapshot::$response.
  • A template path is missing: the transfer fails without retrying; check {{response.…}}/{{steps.<name>.…}} against the real JSON.
  • Native integration is stale: run pam doctor --fix, rebuild the native host, and inspect the first reported diagnostic.

Docs

Part of the PAM ecosystem

PAM

PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.

PAM PAM Desktop PAM Native Ecosystem
the runtime and CLI native desktop apps in PHP native Android and iOS apps in PHP every official package and plugin

Docs: push-in.github.io/pam-docs · Issues

Apache License 2.0 · Made in Brazil by Pushin