TotisWorkers Architecture ​

TotisWorkers runs Cloudflare-Workers-shaped TypeScript/JavaScript handlers on an embedded QuickJS-ng engine inside a per-request sandbox. It is a standalone application that owns its storage directly through the file-system module — there is no S3 server underneath. Each app lives under apps/<appId>/ on the file-system: its source, compiled worker, SQL database, static site and bindings all live there, and its secrets live in the instance vault.

Layers ​

  • Front door (:workers-app) — WorkersApp + PrefixRouter route by origin: the platform host (hosts.platform, required) serves the bundled system app (the platform console and its /v1 API), while each app is reached at <label>.<base> on every configured hosts.apps base (or /apps/<label>/ when no apps base is set) and at its custom domains. hosts.apps may be one wildcard base or a list (the first is primary); <label> is <app>-<project>-<org> plus -<env> outside production. hosts.consoleUrl (optional) is the public console origin used for links in system email, defaulting to https://<hosts.platform>. cloudflared exposes the server publicly.
  • Control plane (:tiny-s3-sandbox · platform) — the system app drives orgs, projects, apps, deploys, secrets, databases, storage and domains through env.PLATFORM (PlatformOps). The HostRegistry records every app (storage root apps/<appId>), the Vault encrypts secrets under the instance KEK, and AppDeployer bundles, stores and migrates a deployed Worker.
  • Bundler (WorkerBundler, SWC→wasm) — server-side bundles raw worker.ts: strips types, inlines the SDK, wires export default. Source stays at _code_/worker.ts; compiled output at _code_/worker.js.
  • Execution sandbox (:tiny-s3-runtime) — a JS worker runs on a JsRuntime, which keeps warm per-app state so a cold start becomes a small per-call cost. Two implementations run the same QuickJS-ng engine behind one contract: QuickJsJsRuntime in-process (side-loaded native QuickJS-ng via FFM; the default, runs on any OS with no KVM) and HyperlightJsRuntime (the same engine in a KVM micro-VM for stronger isolation, Linux/KVM only). The host uses hyperlight where KVM is available, else quickjs. Each request runs the worker's fetch on a warm context.
  • Host capabilities (HostBridge → HostBridgeImpl) — the only authority a guest gets, executed host-side under the caller's identity. Each hostExt op is looked up in a registry of HostOps contributed by the owning subsystem (DB, S3 and bucket bindings, fetch, KV, queues, caches, analytics, images, email, logging, and env.PLATFORM for the system app only), then checked against the capabilities the run was granted.
  • Outbound email (:tiny-s3-workers-email, connections in :tiny-s3-workers-connections) — org email connections (SMTP with STARTTLS/implicit TLS, or a provider API: Mailjet, Resend, Postmark, SendGrid, Mailgun, Amazon SES) with write-only credentials in the vault, host-built MIME, per-org/per-app send quotas, a 30-day send log, and SSRF-guarded egress (private SMTP relays need an email entry in the instance's private address allow-list). The system app sends invitations and password reset through an instance connection.
  • Data, cache & egress — env.DB binds the app's own SQL engine (:tiny-s3-sql, row store + MergeTree) living at apps/<appId>/_data_/db; env.CACHE is an in-process TTL cache (WorkerCache, per-node, non-durable); env.S3 signs host-side via the AWS SDK to an external bucket; fetch is SSRF-guarded by EgressGuard/HttpEgress.
  • Observability (:tiny-s3-sandbox-telemetry) — TelemetryRegistry collects logs, DB metrics, and a per-app worker-error ring; ResourceGovernor enforces CPU/memory/disk/rate limits and quota.
  • Platform modules — the host is split by layer, each its own Gradle module under workers/: workers-registry (HostRegistry, value types) → the host subsystems (workers-egress, workers-email, workers-vault, workers-storage, workers-connections, workers-kv, workers-queues, workers-analytics, workers-images, workers-cron, workers-cache, workers-sockets), each with its own HostOps → sandbox (WorkersServer, HostBridgeImpl, app code and sites, and the SystemApi hook) → workers-platform (PlatformOps and its op groups, bootstrap, and the bundled management app and console), wired to the sandbox by the app. Each module depends only on the layers below it. Each module owns one package root, dev.totis.workers.<module>; BoundaryTest in workers/arch enforces the layering.
  • Storage (file-system module) — the underlying FileSystem holds every app's root (apps/<appId>/): code, SQL data, and static site. Secrets live in the instance vault, encrypted under the KEK.

See also: TypeScript Workers · Worker SDK reference · Deploy API.

TinyS3 is AGPLv3 licensed. Cloudflare and Cloudflare Workers are trademarks of Cloudflare, Inc. Amazon S3 and AWS are trademarks of Amazon.com, Inc. or its affiliates. MinIO is a trademark of MinIO, Inc. They are named only to describe compatibility; totis.ai is not affiliated with, endorsed by, or sponsored by any of them.

totis.ai