feat(#1277): the CloudFront origin access control family, and a tagged create

[scttfrdmn]

An origin access control is what lets a CloudFront distribution serve a private S3 bucket: CloudFront signs the origin request with SigV4 and the bucket policy trusts the distribution rather than the world. Substrate routed none of it — /2020-05-31/origin-access-control was not a path parseCloudFrontOperation knew, so the create reached HandleRequest's unknown-route refusal and a consumer keeping its bucket private could not run against the emulator at all. That is the first of the ten missing operations #1274's adopter found by replacing ~1,100 lines of hand-written AWS fakes, and the one it named as blocking.

Closes #1277. Refs #1274.

What lands

The four OAC operations, in a new emulator/cloudfront_oac.go:

• CreateOriginAccessControl — 201 with the ETag and Location headers. Neither is in the API Reference's Response Syntax block, which shows the XML body alone; both are top-level output members in the CLI and the SDKs, and the ETag is the value a caller has to hold to delete the control later. Emitting them as headers is how a REST/XML output member that is not in the body reaches a caller.
• All four Required: Yes config members are validated, three of them against their published enums (s3|mediastore|mediapackagev2|lambda, never|always|no-override, sigv4), case-sensitively: accepting S3 would pass a request through substrate that AWS refuses, which is the direction a consumer pays for with a failed live deploy.
• GetOriginAccessControl — the same document and the same version, through one renderer so the two cannot drift.
• ListOriginAccessControls — the account's controls whole. An account using none answers no Items element at all, which is what the page states and what a decoder cannot tell from an empty one, so the test asserts on the raw XML. Marker/MaxItems/NextMarker are not rendered, for the reason ListDistributions omits them.
• DeleteOriginAccessControl — 204, with the version contract separated into the codes the reference publishes for it: absent control → NoSuchOriginAccessControl/404, missing or malformed If-Match → InvalidIfMatchVersion/400 (the code's own description is "missing or not valid", two cases in one sentence), well-formed but stale → PreconditionFailed/412.

CreateDistributionWithTags — the same path and verb as CreateDistribution with ?WithTags. The key is published bare, so a bare query key arrives as the sentinel "1" and the routing tests for the key's presence; testing for a value would have sent a tagged create to the untagged handler and dropped the tags while answering 201. Its body is decoded strictly, unlike CreateDistribution's: a caller that asked for tags must not be handed an untagged distribution and a success, which is #883's argument applied to the create path. Both halves happen in one write, so the distribution is never observable untagged.

CloudFront crosses off #856. generateCloudFrontID was one of the remaining crypto/rand draw sites, and adding a fourth caller to it would have widened a list #856 is actively shortening, so it converts here instead: it takes the request's IDMint, loses its error return, and the alphabet it maps onto is a named constant its three callers share. The mapping is byte-for-byte the one it performed before, so an ID recorded by an earlier substrate is still the shape this one mints. 29 → 28 draw sites.

Two published behaviours deliberately absent

Both are recorded in the code and in docs/services.md rather than left to be discovered:

• OriginAccessControlInUse/409 needs to know which distributions reference the control, and substrate records no Origins — the same gap "A configuration is not a distribution" describes, and why GetDistributionConfig answers two of five required members. CloudFront: UpdateDistribution should reject an incomplete DistributionConfig (IllegalUpdate / missing-field errors) #1271 is where a distribution starts recording its configuration and the check becomes answerable; the deferral is noted on both issues and in both directions in the docs.
• OriginAccessControlAlreadyExists/409 is published for a control "with the specified parameters" without publishing which parameters, and an OAC carries no CallerReference to key a duplicate on the way a distribution does. A repeated create mints a second control; a consumer converging by name should list first.

UpdateOriginAccessControl is not implemented — #1274 lists four OAC operations, and a create-if-absent converge loop does not reach the fifth.

One reading is substrate's rather than AWS's, and is worth a reviewer's attention: the ETag shape. AWS publishes only that the value identifies the current version, so substrate mints the same E-prefixed form it mints IDs in. That is also what makes "malformed" decidable — a value outside that shape was never handed out here, so it cannot be a stale one — which is a statement about substrate's own minting, not a claim about what CloudFront accepts. Either way the request is refused; only the code a caller reads differs.

Verification

• make lint — 0 issues. make test (race, -count=1) — all green.
• make docs-reference-check docs-versions version-check discarded-unmarshal-check wire-bookkeeping-check — the ratchet still reports 330 wire-visible bookkeeping fields: the new state type carries none of the five names, since the record is read back under the account that created it and no ARN path addresses one.
• grep -c 'rand\.Read(' over non-test emulator/ — 28, down one, with no new draw site.
• Patch coverage: every changed statement is covered except three two-line marshal-failure guards (xml.Marshal/json.Marshal over a struct of strings), which cannot be reached and must not discard their error.
• TestReplay_ACloudFrontCreateReplaysWithTheIdentifiersItMinted is load-bearing, not decorative: pointed at a nil mint it reports five major differences and a critical state-hash mismatch, including the recorded CreateInvalidation answering NoSuchDistribution and the recorded delete answering NoSuchOriginAccessControl.

[codecov]

Codecov Report

❌ Patch coverage is 98.63014% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
emulator/cloudfront_oac.go	97.93%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!