Skip to content
Embabel Worlds

App limits and profiles

A captured browser app is held to size limits (see apps). The defaults are 10 MiB for the page, 10 MiB for any one resource, 10 MiB for all of one app’s resources together, and 16 resources. They match what the reference host runs with out of the box. The host operator sets the host’s own limits, and a host with larger ones takes larger apps, so each limit synth applies can be raised or lowered:

Terminal window
bun packages/realm-synth/src/cli.ts realm.ts --out dist --app-limit 32MiB
Flag Sets
--app-limit <size> The page, per-resource and total byte limits together.
--app-page-limit <size> The page.
--app-resource-limit <size> Any one resource.
--app-total-limit <size> All of one app’s resources together.
--app-resource-count <n> How many resources one app may list.
  • A size is a whole number of bytes, or a whole number with a unit: K, KB or KiB, M, MB or MiB, G, GB or GiB, in any letter case. Every unit is binary, so 32MB and 32MiB are both 33,554,432 bytes. A size or count comes to at least 1, and there is no upper cap.
  • A per-limit flag wins over --app-limit.
  • A refusal names the limit it hit and the flag that raises it.
  • Raising a limit in synth does not raise the host’s. An app over the host’s limits is still refused when the owner opens it.

A realm can run in more than one execution environment, and they do not all load the same things. --profile checks the realm against one of them:

Terminal window
bun packages/realm-synth/src/cli.ts realm.ts --out dist --profile reference-wasm
bun packages/realm-synth/src/cli.ts realm.ts --out dist --profile ./my-host.json

A profile only adds warnings and refusals, and may carry its own app limits. Synth writes every file the realm declares whether a profile is given or not. A feature the profile marks warn prints one warning, starting PROFILE <name>: and naming each place the realm uses it, and the build carries on. A feature marked refuse stops the build with every place it is used. A feature left out of the profile is supported.

The two built-in profiles describe the reference host running handlers under Wasm and under Docker. They have the same rules and no app limits of their own:

Feature id What it finds reference-wasm, reference-docker
layers A non-empty layers list refuse
captured-actions actions on a captured realm warn
captured-events events on a captured realm warn
captured-webhooks webhooks on a captured realm warn
captured-focuses focuses on a captured realm supported

Any other environment is described in a JSON file whose path ends in .json:

{
  "name": "my-host",
  "features": { "layers": "supported", "captured-actions": "refuse" },
  "appLimits": { "pageBytes": 67108864 }
}
Field Rule
name Required, not blank. Messages name the profile by it.
description Optional text.
features Optional. Maps a feature id from the table above to "supported", "warn" or "refuse".
appLimits Optional. Any of pageBytes, resourceBytes, resourcesTotalBytes and resourcesPerApp, each a whole number of at least 1.

An unknown field, feature id or limit is refused, so a typo cannot turn a check off. The app limits a build uses come from the defaults, then the profile’s appLimits, then the flags, and each later one wins.