hello-pear-worker

The shared Pear worker used by all hello-pear boilerplates

Cross-platform Bare worker that embeds pear-runtime (desktop) / pear-mobile (mobile) to provide peer-to-peer Over-the-Air updates as a local backend for the boilerplate view layers.

Used by:

• hello-pear-electron — Electron desktop apps
• hello-pear-bare — standalone Bare CLI processes
• hello-pear-react-native — React Native mobile apps

Table of Contents

• How It Works
  • Runtime Selection
  • Arguments
  • IPC Protocol
  • Updates
  • Storage
• Usage
• Scripts
• License

How It Works

The worker is started by the parent application (Electron main process, Bare CLI or React Native view layer) and communicates with it over a framed IPC stream (framed-stream wrapping Bare.IPC).

It instantiates a PearRuntime with a Hyperswarm and Corestore, joins the swarm on the application drive's discovery key and replicates updates peer-to-peer.

Runtime Selection

The imports field in package.json maps pear-runtime per platform, so the same worker code runs everywhere:

"imports": {
  "pear-runtime": {
    "ios": "pear-mobile",
    "android": "pear-mobile",
    "simulator": "pear-mobile",
    "default": "pear-runtime"
  }
}

Arguments

The worker reads its configuration from positional arguments passed by the parent via PearRuntime.run(entry, args).

On desktop, Bare.argv starts with the executable path (argv[0]) and the worker entry path (argv[1]), so the passed arguments land at Bare.argv[2..7]; on mobile (BareKit) they land at Bare.argv[0..3]. The worker offsets the indices via which-runtime so the same argument order works on all platforms:

| args | Bare.argv desktop | Bare.argv mobile | Field | Description | | ------ | ------------------- | ------------------ | --------- | -------------------------------------------------------------------------------------- | | 0 | 2 | 0 | updates | 'false' disables updates (e.g. in development) | | 1 | 3 | 1 | version | current application version (from package.json) | | 2 | 4 | 2 | upgrade | pear:// upgrade link (from package.json) | | 3 | 5 | 3 | name | application name | | 4 | 6 | — | dir | storage directory (not passed on mobile — resolved via bare-storage) | | 5 | 7 | — | app | application path (not passed on mobile) |

IPC Protocol

Messages the worker writes to its parent:

• Hello from worker — sent on startup
• updating — an update is downloading
• updated — an update has been fully downloaded
• pear:updateApplied — reply after an update has been applied

Messages the worker handles from its parent:

• pear:applyUpdate — apply the downloaded update (swaps in the new build for the next launch)

Any other incoming message is logged.

Updates

An update occurs when the seeded application drive behind the upgrade link is written to. Unless updates are disabled, the worker joins the swarm as a client on the drive's discovery key and replicates the corestore over each connection. Update lifecycle events are forwarded to the parent over IPC so the view layer can prompt for a restart.

Storage

Peer-to-peer data is persisted in a Corestore at <dir>/pear-runtime/corestore. The dir argument is passed by the parent on desktop; on mobile it defaults to the persistent app directory via bare-storage.

Usage

Add hello-pear-worker as a dependency in the boilerplate, then the worker entry (workers/main.js) is just:

require('hello-pear-worker')

The parent starts the worker entry with PearRuntime.run(...), passing the arguments, and frames the returned IPC stream:

const FramedStream = require('framed-stream')

const IPC = PearRuntime.run(require.resolve('./workers/main.js'), [
  String(updates),
  version,
  upgrade,
  name,
  storageDir, // desktop only — mobile resolves it itself
  appPath // desktop only
])
const pipe = new FramedStream(IPC)

pipe.on('data', (data) => {
  const message = data.toString()
  if (message === 'updated') pipe.write('pear:applyUpdate')
})

On mobile the worker entry is packaged into a worklet bundle with bare-pack and started via PearRuntime.run('/worker.bundle', bundle, args).

See each boilerplate's README for the platform-specific wiring and full peer-to-peer deployment flow.

Scripts

• npm test - run brittle tests with brittle-bare
• npm run lint - run prettier check and lunte
• npm run format - format repository with prettier

License

Apache-2.0