mob_wake

Status: scaffold. The public API contract is stable enough to code against but function bodies raise not yet implemented until the native trigger paths land. Follow MOB-257 for shipping order.

OS-triggered background execution for Mob apps. Cross-platform surface (Mob.Wake), per-platform NIFs, one dispatch mechanism regardless of trigger source: a compile-time identifier → MFA table, native wakes the BEAM, we run to completion, native marks the task done.

What this is (and isn't)

Is: handlers the OS wakes on our behalf.

All four dispatch through the same Mob.Wake.dispatch/1 entry point.

Isn't:

Read this before you commit to a background flow

The reliability story is not what most people assume.

If your feature genuinely requires guaranteed periodic execution — accounting reconciliation, medical dose reminders — a background wake plugin is the wrong shape and you should be talking to a server-side scheduler with a push relay.

Install (once shipped)

def deps do
  [
    {:mob,      "~> 0.9.1"},
    {:mob_wake, "~> 0.1"}
  ]
end

In mob.exs:

config :mob, :plugins, [:mob_wake]

# The task table drives both codegen (Info.plist, AndroidManifest.xml,
# WorkerFactory registration) and runtime dispatch.
config :mob_wake, tasks: [
  {:sync_notes,   MyApp.BackgroundJobs, :sync_notes,   :refresh},
  {:cleanup,      MyApp.BackgroundJobs, :cleanup,      :processing},
  {:on_new_peer,  MyApp.BackgroundJobs, :handle_peer,  :push}
]

Then write the handlers as normal functions:

defmodule MyApp.BackgroundJobs do
  def sync_notes do
    # Runs when iOS BGAppRefreshTask fires or Android OneTimeWorkRequest fires.
    # Return :ok on success, {:error, term} on failure. The native side reads
    # the return value to call setTaskCompleted(success:) correctly, so iOS's
    # opportunistic scheduler learns to trust (or distrust) us for future fires.
    :ok
  end

  def cleanup, do: :ok

  def handle_peer(%{payload: payload}) do
    # :push-triggered handlers can accept a %{payload: _} map — that's the
    # APNs/FCM message body. Otherwise called with no args, same as
    # :refresh / :processing handlers.
    IO.inspect(payload)
    :ok
  end
end

AppDelegate wiring (iOS, until MOB-265 codegen lands)

Until mob_new's codegen (MOB-265) writes this automatically from your config :mob_wake, :tasks table, add the following to your generated ios/AppDelegate.m:

// Near the top of the file:
#import <BackgroundTasks/BackgroundTasks.h>
@interface MobWakeDispatcher : NSObject
+ (void)registerTaskWithIdentifier:(NSString *)identifier trigger:(NSString *)trigger;
@end

// Inside `application:didFinishLaunchingWithOptions:`, BEFORE `return YES;`:
if (@available(iOS 13.0, *)) {
  // One line per identifier in your `config :mob_wake, :tasks`. iOS
  // rejects registration attempted after `didFinishLaunching` returns.
  [MobWakeDispatcher registerTaskWithIdentifier:@"com.myapp.sync_notes" trigger:@"refresh"];
  [MobWakeDispatcher registerTaskWithIdentifier:@"com.myapp.cleanup"    trigger:@"processing"];
}

// For silent APNs (:push-triggered identifiers), also add:
- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
        fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  // mob_wake routes on the top-level "mob_wake_id" key in userInfo.
  // Your server's silent-push payload MUST include it (mob_push, when
  // shipped, will enforce this convention on the send side).
  [MobWakeDispatcher onPushFired:userInfo completionHandler:completionHandler];
}

And in your Info.plist, add each identifier to BGTaskSchedulerPermittedIdentifiers:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.myapp.sync_notes</string>
  <string>com.myapp.cleanup</string>
</array>
<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>                 <!-- for :refresh triggers -->
  <string>processing</string>            <!-- for :processing triggers -->
  <string>remote-notification</string>   <!-- for :push triggers -->
</array>

For silent APNs, the server-side payload must include a top-level mob_wake_id key naming the identifier, plus aps.content-available: 1:

{
  "aps": { "content-available": 1 },
  "mob_wake_id": "com.myapp.sync_from_peer",
  "peer": "abc"
}

Mob.Wake.dispatch/1 will invoke the registered handler with the whole payload as a JSON binary — decode with Jason.decode!/1 or :json.decode/1 (Elixir 1.18+) in your handler if you want a map.

Public API

Under the Mob.Wake namespace. Full contract in the module's @moduledoc.

Related plugins

Cross-references

License

MIT.