Skip to content

The app bundle

The app reads no file while it answers: what the company’s files say reaches it as a snapshot (AppSnapshot): the description, the people and Cedar policies, the files’ texts the Code view shows, the scenarios, content/’s fields and published content, the repository’s remote (without credentials), infra.ts, the lockfile’s bindings, a deriving host’s facts, and the applicationVersion its runs are enqueued with. startApp makes it with appSnapshot(config, { source }) and again once a file it was read from changes (liveSnapshot).

buildAppBundle(repo, { config, domains }) from sanoma/app/bundle builds the same app, every route and site, for Cloudflare’s workerd (nodejs_compat), with the snapshot baked in, into an AppBundle: its main module and modules (base64), its assets with Cloudflare’s hash and size, the compatibility date and flags, and the pages of each public site on one of domains that show everyone the same content, prerendered into the assets: every page but one whose file, a layout above it, or a site file either imports (directly or through others, statically or by import()) calls api or renders a RunForm, or imports code the build does not read (outside the site’s folder, an import() not written out, import.meta.glob, a package’s #import, a path from the root): the rule is SitePage.calls. A login on the site does not matter: on its domain, the server’s render never reads the visitor, whom useActor() asks for once the page is in the browser, so a prerendered page shows no visitor’s own header. The main module’s default export is fetch(request, env, ctx, host?) (AppBundleModule), over env.DATABASE (a Hyperdrive binding, or anything with a connectionString), SANOMA_HOSTNAME (the app’s own host, and so its agent address; any other host that is no site’s domain answers 404; without it every host that is no site’s is the app’s, and its agent address is the Worker’s own URL’s, SANOMA_HOST_URL, which the Cloudflare host binds; with neither no agent signs in), SANOMA_DOMAINS, SANOMA_SIGNING_KEY, SANOMA_SECRETS_KEY and ASSETS; a run it queues has host.startNow() start the worker. A page prerendered for a domain it answers from ASSETS without loading the app; anything else loads the app, on the first request that needs it, with a client of each request’s own, and Cedar on its first decision, over the policies sanoma checked at build, which it never checks again. The bundle carries only the modules its main module reaches. The bundle’s config is the one sanoma loads: the config file’s, with each workflow file’s workflow and resources/data.ts’s collections joined to it. Each module’s import.meta.url is its file’s URL, as on Node (workerd has none), and what a connector’s vendorInfo(import.meta.url) reads of its package is read at build.

  • Not on the Worker: what reads the checkout or runs a child process. Adopt, a form’s Save, going live, connecting a repository and a chat’s turn are runs of the built-ins adopt, patch, go-live, go-live-host, go-live-cloud, connect-existing and chat, which a worker given the app’s steps runs (sanoma serve and sanoma worker give them theirs); on a worker without them, the run fails saying so. The staff’s sign-in and each site’s login run on the Worker as on Node, each request on its own pool; the Worker’s bindings give SANOMA_SIGNING_KEY for their keys and, for GitHub sign-in, SANOMA_GITHUB_CLIENT_ID and SANOMA_GITHUB_CLIENT_SECRET (both or neither). A login that cannot start (the key unset) is logged, and its pages answer 503.
  • Refused: a site’s file, or the app’s own, that imports what workerd does not have (node:fs, node:child_process, …): the build throws NodeOnlyImport, naming the file and what it imports, which sanoma check reports. And a bundle that cannot answer: the build runs it on workerd and asks its /healthz, which loads the app as a first request does, so a module that throws as it is evaluated (one reading a file, say) fails the build with <file>:<line> throws as the Cloudflare Worker evaluates it, the file from the repo, or from node_modules for a package’s, by the bundle’s source map.

These pages describe sanoma 0.11.24.