[316] Set tiered Cache-Control on published dashboard objects

[CarsonDavis]

Category	Lines added	%
Tests	242	76.6%
Production code	67	21.2%
Docs	7	2.2%

Every object a publish writes now carries a Cache-Control header, so a republished dashboard reaches visitors instead of sitting stale on a cache we cannot reach.

Closes #316. PR 3 of 3 for the issue, stacked on #348 (which stacks on #330), retargeted to development as the stack merges.

A republish now reaches a customer's own cache

Previously, an operator republished a dashboard, saw the new content on our CloudFront (the publish invalidates /*), and a customer fronting that same dashboard on their own domain kept serving the old index.html.

Every object we wrote went up with no Cache-Control at all: the PUTs carried only Bucket, Key, Body, ContentLength and ContentType, and the shared-asset copies used CopyObject's default COPY directive, which carries over the source object's headers, and the upload router never set a Cache-Control on those either. With no instruction from the origin, a CloudFront cache policy falls back to its Default TTL, 86400 seconds in the managed policies and in most hand-rolled ones. The old entry page could stay pinned for a day in a distribution we have no ability to invalidate.

The fix: cacheControlForKey(key) assigns one of three tiers to every object, applied on all four write paths (uploadDirectory, uploadFile, copyPrefix, copyObjectIfExists):

• no-cache, revalidate on every request, for index.html, build/index.html and Missions/<mission>/config.json: the entry page and the baked mission config.
• public, max-age=31536000, immutable for build/static/{js,css,media}/… and assets/<mission>/<subdir>/uploads/…: the two classes whose filenames are content-addressed, webpack content hashes on one side and crypto.randomUUID() names that are never overwritten on the other.
• public, max-age=300 for everything else, the keys that genuinely change in place on republish: build/static/cesium/…, public/workers/…, Missions/…/Data/mosaic_parameters.csv, and non-upload assets/….

A republish now reaches a header-honoring cache in stages: entry page and config at once, the rest within about five minutes. The two copy paths switched to MetadataDirective: REPLACE, because COPY cannot add a header the source never had; REPLACE drops the source's whole metadata set, so those copies restate ContentType as well, re-derived from the file extension.

One test guards the premise of the immutable tier: a new spec reads configuration/webpack.config.js as text and asserts a content hash in all six output-name settings, so dropping one breaks the suite instead of quietly putting a stable filename into the year-long tier.

Two un-rendered templates are no longer published

Previously, anyone hitting <dashboard>/build/index.pug or <dashboard>/public/index.html got a raw template with #{LINK_PREVIEW_TITLE}, #{AUTH} and #{user} still in it.

The publish uploads build/ and public/ wholesale, and it interpolates those placeholders into build/index.html only. The two siblings shipped exactly as they sit on disk, and uploadDirectory had no way to leave a key out.

The fix: uploadDirectory takes an optional filter(key) and publish-static.js skips those two exact keys. They are left out of the upload and out of the reported file count.

The customer doc sets a Maximum TTL and covers password rotation

Previously, docs/infrastructure/serving-a-dashboard-from-your-domain.md asked the path owner for a custom cache policy with Authorization in the cache key, all query strings, and Minimum TTL 0. It said nothing about a maximum, so a customer who set a one-day Maximum TTL would silently cap our year-long tier down to a day. Nothing told an operator what happens to a fronting cache after a dashboard's password is rotated.

The doc was written when we sent no Cache-Control at all, so there were no TTL ceilings and no revalidating tier to describe.

The fix: the setup list adds "Maximum TTL 31536000 (one year) or more", and the rationale section explains the three tiers as behavior, including what a staged republish looks like from the customer's side. It also notes that AWS's managed UseOriginCacheControlHeaders policies get the TTLs right but omit Authorization from the cache key, so a custom policy is still required. A closing paragraph tells operators to invalidate their distribution after rotating a password: the cache is keyed on Authorization, so responses fetched under the old password keep being served to anyone still presenting it, never reaching us to be rejected, for up to a year on the immutable tier.

Decisions to review

• One-year immutable on password-gated files. public is the directive that lets a shared cache store a response to a request carrying Authorization, so cross-visitor safety rests entirely on the customer keeping Authorization in their cache key, which the doc requires and we cannot enforce. The alternative is a ceiling of hours or days, which still fixes the day-long pin and bounds the exposure after a rotation without a customer-side step.
• The immutable tier is decided by key prefix, not by evidence of a hash in the filename. The webpack half of that claim is guarded by the new spec and the uploads half is only a code comment; the alternative is to require a hash segment in the key itself, which needs no cross-file guard. Being wrong is asymmetric, because we cannot purge a stale immutable object from a customer's edge for a year.
• MetadataDirective: REPLACE restates only ContentType and CacheControl. Content-Encoding, Content-Disposition and x-amz-meta-* are dropped, which is exact for every type the upload router writes today; the alternatives are to HeadObject the source and carry its headers forward, or to set Cache-Control at upload time so a plain COPY suffices.
• Our own per-dashboard distribution stays on the managed CachingOptimized policy. Its 1-second minimum TTL overrides no-cache at our edge, which does not matter because the publish already invalidates /*; the alternative is an owned cache policy in the template with minimum 0.
• The two raw templates are kept out by an exact-key skip on a publish that only writes. A dashboard published before this keeps its copies until its bucket is emptied; the alternative is to delete those two keys on republish, which needs s3:ListBucket and s3:DeleteObject added in three IAM layers.