Cloud Storage

The rule: one private bucket, private things only

The bucket is private, and only private things move to it. Everything else stays on this server. This is enforced, not advised:

• At Save. The check fetches a probe object anonymously; a bucket that answers is refused and nothing is stored (§ The Save check).
• At the registry. Every profile keeps visibility(), and StorageProfileRegistry::all() refuses any profile that does not answer private — logged and left out — so a future consumer cannot opt a public set into the bucket by declaring one.
• At eligibility. BlobStorageProfile::eligibilityWhere() is fbb_is_private = TRUE; a public blob is never a candidate.
• At a visibility flip. A private cloud blob that is made public is pulled back to this server by FileBlob::flipVisibility() before its record flips (§ Permission changes). A local public blob made private moves on the next tick.

CloudStorageDriverFactory resolves the drivers. current() is where a new offload goes: the store file_store_target_id names, while cloud_storage_enabled is on — the single signal "there is a usable, proven-private store to write to". forTarget($id) is the driver for the store a row names, latch on or off, so a paused or draining store still serves and still gives its files back. currentUnlatched() is the named store whatever the latch says, for the page's health line and a move's destination. The driver (CloudStorageS3Driver) is S3Signer's, the platform's one S3 client; it takes full keys and adds nothing to them.

The Save check

Save runs the check, in this order, and stores nothing on a fail (CloudStorageLifecycle::testConnection()):

A store's location is fixed once a file is in it

An offloaded file is in backup storage before its local copy goes

Offloaded mail is backed up the same way: RawMessageStore declares its backup objects as BlobStorageProfile does, each message the object mailbox/{message id}.eml (a namespaced name no stored file name can be), and a restore puts it back by the row its profile names for it (StorageProfile::backupRow()).

The archives a backup takes carry no cloud blob (the runner hands the files engine an exclude list naming every one, original and variants). Each is copied to the backup storage once instead, encrypted, under objects/{epoch}/{name}.enc — see docs/backups.md § Offloaded files in backup storage. The tick is where the two meet. CloudOffloadEngine::_sync_row(), after the flip to cloud, calls BackupObjects::after_offload() in place of an unconditional unlink:

1. Store. When the site profile is enabled, the original is encrypted with the site epoch key and uploaded to the site's own backup storage, one object's ciphertext on disk for the length of the upload. A failed store leaves the row cloud with its bytes; the next site run's backup storage listing shows the object missing and stores it. Nothing is retried in the tick.
2. Release. The local bytes — original and variants — are unlinked only when every enabled profile holds the object: the site profile by the store that just succeeded (or its held.json), the manager profile by its held.json, written by the management node's runs. With no profile enabled the release is unconditional, and the file is served from the bucket alone.

So a file can sit on this server, offloaded but not yet released, for as long as a backup that stores offloaded files has not run. That figure is on the cloud-storage page's Status block and the Backups page's Offloaded files box — "M files (X GB) waiting for the management node's backup before their local copy is released" (BackupObjectsStatus: every cloud row whose original is still on disk, one stat per row on page load, no column and no cache) — and, because a count on a page is read by nobody, on every admin page as a notice when it matters: BackupObjectsNotice stands when the waiting bytes exceed 2 GB, or when anything waits for a backup whose newest success is older than 7 days (or that has never succeeded) — "N files (X GB) are waiting for the management node's backup, which last succeeded D days ago. They stay on this server until it does." — and clears itself when nothing waits. The thresholds are constants on the class.

When the file store and this site's backup target share an access key (the current store's key equals the target's), both pages also say so: "Backup storage and the file store share one account; losing it loses both. A management node's copy would survive it." The same-key test is the whole rule — accounts are not detectable, keys are.

The file store is checked daily

Once a file is offloaded, the bucket is the only place its bytes are served from, and a file the bucket has lost is otherwise invisible until a visitor gets a 404. So the tick asks: while any offloaded file exists — paused store or not — CloudStoreInventory::tick() runs inside runOffloadTick() and, once a day, HEADs every cloud blob in the store its record names (CloudStorageDriver::head()), a slice per tick (TICK_BUDGET_SECONDS of HEADs, then a cursor) so ten thousand files never hold the scheduler. A file the bucket does not have, or holds at a size other than its row records, goes on the missing list by name.

The check never calls a file missing on a bucket's silence: a tick pings each store before its first file and waits when it does not answer, and a HEAD that says absent is asked once more before it counts. A file whose store this site has no driver for cannot be checked, and is counted as such.

The result is one settings row, cloud_storage_inventory (JSON: the pass in progress, the last completed pass with its missing names, and what the last Bring them back did). No schema. Both the cloud-storage page and the Backups page read it (CloudStoreInventoryPanel) and say: "N offloaded files are missing from the file store; the backup holds M of them" — M counted against what the enabled backup profiles' shelves hold (BackupObjects::held_sets()), or "known after its next run" when no profile has a run since the object store shipped. The action beside it, Bring them back, is the object restore in missing mode against the newest backup (see docs/backups.md § Restore):

• a site with a backup target of its own runs it here, in the background (BackupObjectRestoreLauncher::start_newest() → utils/bring_back_objects.php), with links it signs for itself and its own key;
• a site backed up only by its management node is told so, with the node's URL: the job is started from that node's Backups tab (FleetObjectRestore::start() through the restore_objects backup action);
• a site with neither is told nothing holds them.

Declarative profile registry

Profiles are declared, not self-registered at runtime, so the registry and the immutability guard see them whether or not the owning plugin is active — matching how the platform declares plugin settings and menus:

• Core profiles are listed in storage_profiles.json at the public_html/ root; the class file lives at includes/cloud_storage/<ClassName>.php.
• Plugin profiles are listed under a storage_profiles key in the plugin's plugin.json; the class file lives at plugins/<plugin>/includes/<ClassName>.php.

A deactivated plugin leaves its files — and so its declaration and class — on disk, so the guard still sees its cloud rows. Uninstall is the one gap, closed by policy: uninstalling a plugin that owns a profile requires the store drained back to local first (the same disable-and-pull flow the guard points admins at).

Add a new offload consumer

1. Implement StorageProfile (including reverseItemsForRow for pull-back and move, and the store and key columns its table carries), answering 'private' from visibility() — the registry refuses anything else. Its rows must be things people must be signed in to see. To be in backups, also implement backupObjects(), backupObject() and backupRow() (BlobStorageProfile is the pattern).
2. Declare the class name in storage_profiles.json (core) or a plugin's plugin.json storage_profiles array.

A table with rows that are not the profile's. A profile may also implement an optional reverseEligibilityWhere(): string — a SQL fragment naming which cloud rows of its table are its own. It is needed when the table also holds rows that never move (fbb_file_blobs holds public blobs, which stay local); the engine and the cloud-row counts probe it via method_exists(), so a profile that owns its table outright simply omits it. The forward offload is already partitioned by eligibilityWhere(); this gate partitions the reverse/drain and the cloud-row count.

Private files

Any file that carries a restriction — fil_min_permission, fil_grp_group_id, fil_access_provider, fil_tier_min_level, or fil_private — is private (the inverse of File::is_public()). A file's visibility is recorded on its blob as fbb_is_private (kept in step with the referencing files by the dedup scoping and copy-on-write split — see File Signed URLs and the blob layer). BlobStorageProfile drains restricted blobs to the bucket. So a group doc, event handout, tier-gated download, Drive file or email attachment offloads instead of pinning to local disk — draining a small VPS that would otherwise fill with private uploads. A public blob is never eligible.

Serving stays gated: a private file's get_url() returns the local /uploads/... path (never a bucket URL), and serve.php runs File::is_viewable() before streaming the bytes from the bucket through PHP. No File column drives placement — whether a blob may be cloud at all is fbb_is_private.

fil_private is a distinct restriction mode from the other four: it isn't a threshold or membership check, it's an owner-or-admin rule — only the file's owner (fil_usr_user_id) or an admin (permission ≥ 5) can view it. File::is_viewable() and SystemBase::authenticate_read()/ authenticate_write() (the record-access gate) share one is_owner_or_admin() helper, so the rule for opening a record and the rule for streaming its file bytes can never drift apart. This is the only restriction mode that can express "visible to a specific permission-0 user and nobody else" — a plain fil_min_permission threshold can't, since any value that admits the owner also admits every other user at that level. The trade-off: it's coarse for admins (any admin can view any owner-or-admin private file) and it can't express sharing among several non-admin users — a consumer needing that would require a heavier per-set membership mechanism this platform doesn't build.

BlobStorageProfile declares a reverseEligibilityWhere() ownership gate (fbb_is_private = TRUE) so the reverse/drain path and the cloud-row counts touch only the cloud rows, never the public blobs that share the table. Enabling or draining the store acts on every profile, so the blob profile and the inbound-mail raw store light up together. No per-profile task is involved — the single CloudOffloadRun tick drives every profile by the store's mode.

Bucket Layout

<folder>/<stored_name>            ← original
<folder>/<size>/<stored_name>     ← variants (thumb, avatar, ...)
<folder>/mailbox/<yyyy>/<mm>/<message id>.eml   ← offloaded mail

<stored_name> is the blob's fbb_stored_name — the physical identity shared by every file that references the blob (files reference it by fil_name, which is the URL identity and equals the stored name for a fresh, non-deduped upload).

<folder> is the store's folder (bkt_path_prefix). A new store's folder defaults to this site's name (site_template, e.g. joinerytest), so several Joinery sites can share one bucket. It is part of the store's location, fixed once a file is in it, and each row records the full key it was written under (fbb_remote_key, iem_raw_remote_key), so nothing a setting says later can re-point an existing object. A variant's key sits beside its original's (FileBlob::remote_key_for()).

The bucket must be private. The customer applies that policy at bucket creation; the platform never tries to set it, and Save refuses a bucket that is not.

A file deleted from the store is deleted from the bucket, every version of it: on a versioned bucket (every Backblaze bucket) a plain delete would only hide it, so the driver's delete goes through S3Signer::delete(), which removes each version and delete marker by id. The offload tick also sweeps each store's folder daily for anything a delete left hidden (Backups § Uploads), and stays active while a sweep has work left.

A file store never takes object lock, as a backup target can (Backups § Object lock): a member's deleted file has to go. Save refuses a bucket that locks every new object by default (object lock with a default retention): the Delete step's probe cannot be deleted, and says why.

Settings

The store itself is a target row (bkt_backup_targets, bkt_purpose = 'files'): name, provider, bucket, folder, and a sealed credential (access key, secret, region, endpoint). Set up and changed on the admin page at /admin/admin_cloud_storage. Beside it, in stg_settings:

Providers

The form is the shared target form (BackupTargetForm, in its files mode), headed by a provider picker (includes/StorageProvider.php, the one catalogue of what each provider asks for and names). Only the fields the provider needs are shown; the rest are settled at Save, before the check runs (BackupTarget::complete_credentials()):

This page is the only place a file store is set up or changed: a backup target's form refuses to save one (BackupTargetForm::save()), and a list of targets is the backup targets unless it asks for file stores (MultiBackupTarget, purpose).

Auto-Derivations

• Path-style vs virtual-hosted addressing. A property of the provider in the catalogue: Amazon addresses a bucket as a host label; everything else is path-style. S3Signer applies it to every request.
• The bucket's own address, which url() builds on and only the privacy gate's anonymous probe fetches (S3Signer::object_url()): - Amazon: https://{bucket}.s3.{region}.amazonaws.com/{key} - Path-style: https://{endpoint_host}[:port]/{bucket}/{key}

Admin UI

/admin/admin_cloud_storage (System → Cloud Storage) opens with a note on what moves — only files people must be signed in to see: private uploads, Drive files and inbound mail; public images and downloads stay on this server, so nothing on a page is served from the bucket — then a status block, then the file store:

The steps a failed Save shows are those of § The Save check.

Migration

Forward (local → bucket)

The CloudOffloadRun tick in offload mode is the forward migration. When cloud storage is first enabled, the batch query naturally selects every private local file and the tick drains them across cron ticks until the queue is empty. There is no separate migration task.

Migration starts on the next regular cron tick (within 15 minutes). To start sooner, click "Run Now" on the Scheduled Tasks admin page.

The task is bounded per run (50 rows or 60 seconds, whichever first). Failures increment fbb_sync_failed_count; after 5 consecutive failures a blob is excluded from the batch query and surfaces in the admin UI as "stuck." The "Retry" button resets the counter and re-queues the blob.

Reverse (bucket → local)

Drain mode is entered only by the "Disable and Pull Files Back to Local" button (which sets the draining flag). CloudOffloadRun then pulls every cloud row back, each from the store its record names. Per-row, three phases:

1. Pull bytes to a temp dir.
2. Place files into the correct local dir (per the blob's fbb_is_private), commit fbb_storage_driver = 'local' and forget the store and key.
3. Best-effort bucket delete. Failures here are logged with CLOUD_STORAGE_ORPHAN: table=<table> keys=<...>; the row is correctly served locally regardless. Manual cleanup with aws s3 rm or equivalent.

Moving to another bucket

Files never age out, so switching buckets carries them across rather than waiting: Move files on an older store's row (CloudStorageLifecycle::startMove()) records the move in cloud_storage_move, and each tick runs a batch (CloudOffloadEngine::moveBatch(), 25 rows or 60 seconds) for every profile. Per row, under the row lock:

1. Read each object from the old store and write it to the current one under its folder (<new folder>/<name>).
2. Check each copy: its size, and the ETag when it is the MD5 of the bytes; when it is not (a multipart upload, a bucket encrypted with its own keys, whatever the ETag's shape), the copy is read back and its SHA-256 compared. A copy that does not check is deleted from the new store and the row stays where it was.
3. Re-point the row to the new store and key — only if it still names the old one.
4. Delete the old copies. A refused delete is logged as CLOUD_STORAGE_ORPHAN; a process killed between steps 3 and 4 leaves the old copy in the old bucket with no record naming it (deleting the old store later touches nothing in its bucket, so the copy stays until removed at the provider).

It runs online: a row is served from the old store until the moment it names the new one. It resumes on its own: what is left is whatever still names the old store, and a row that failed is tried again on a later tick. It ends itself once the old store holds nothing (or when the current store is no longer the one it moves to), and the old store can then be deleted. Nothing needs the whole store to fit on this server: one row's objects are on disk at a time. A pull-back ends any move.

Permission Changes

When a file's is_public() flips, its bytes must end up where the new visibility allows — public bytes on this server, in the fast-serve directory; private bytes in the restricted directory, and from there to the bucket on the next tick — so nothing public is ever served from the bucket, and a restricted file is never reachable by a world-readable URL.

A cloud-stored file made public

A local file whose visibility flips

The directory move (static_files/uploads/ ⇄ restricted uploads/) happens in the save path; the row stays 'local'. A file made private is eligible, and the next tick offloads it; a file made public stays where it is. No request blocks on bucket I/O.

URL Generation

File::get_url($size_key, $format) always mints a local /uploads/... URL, whatever the blob's driver. A public file is a local file, served by the fast path; a private file's URL routes through serve.php's gate, which streams the bytes — from the bucket when the blob is cloud. A bucket URL is never emitted: the "never url()" rule, enforced at the model.