feat(container-loader): support offline loads in loadFrozenContainerFromPendingState

[anthony-murphy]

Description

Adds an "offline" form of loadFrozenContainerFromPendingState that loads a frozen container entirely from the URL captured in pendingLocalState — no IRequest, IUrlResolver, or IDocumentServiceFactory is supplied by the caller.

ILoadFrozenContainerFromPendingStateProps becomes a discriminated union of two shapes, selected by the presence of the driver-wiring fields:

• Online (existing behavior): caller supplies request, urlResolver, and documentServiceFactory. The supplied factory is wrapped in a frozen factory and the resolver re-resolves the request just as today.
• Offline (new): caller omits all three. The entry point synthesizes an IResolvedUrl from pendingLocalState.url, an IUrlResolver whose resolve() returns that synthesized URL, and a no-inner frozen IDocumentServiceFactory. The existing pipeline (loadExistingContainer -> Loader.resolve -> Container.load) is reused unchanged — the identity guard in Loader.resolveCore is trivially satisfied because the same URL string is on both sides of the compare.

Mixing the two forms (some fields supplied, others omitted) is rejected at runtime with UsageError.

IContainer.getAbsoluteUrl throws on an offline-loaded container, since the resolver's external (request-form) URL cannot be reconstructed from the captured resolved URL alone. Fabricating a string in the wrong format would mislead any caller that passed it back into a real resolver.

No changes to Container or Loader were required; all new behavior is composed at the entry-point layer in createAndLoadContainerUtils.ts.

Reviewer Guidance

The review process is outlined on this wiki page.

• The interface -> type change on ILoadFrozenContainerFromPendingStateProps is required because TS does not allow widening an inherited required field (request/urlResolver/documentServiceFactory) to optional via extends. The API is @legacy @alpha and was introduced one PR ago, so consumer impact is essentially zero.
• The synthesized request.url carries a resolved-form URL where an external-form URL is normally expected. Nothing downstream inspects it before the synthesized resolver swallows it. Worth a sanity check that no future load-pipeline change starts depending on request.url having external-form structure.
• Three new tests in loadFrozenContainerFromPendingState.spec.ts cover: offline happy path, getAbsoluteUrl throws, mixed-driver-wiring is rejected.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (831 lines, 16 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  288859 links
    1925 destination URLs
    2175 URLs ignored
       0 warnings
       0 errors

[anthony-murphy]

Deep Review

Reviewed commit 463f9aa on 2026-05-21.

Readiness: 8/10 — ALMOST READY

The prior cross-package changeset gap for AllOrNone / validateAllOrNone is resolved in 463f9aa by sweet-spiders-grow.md (versions @fluidframework/core-interfaces and @fluidframework/core-utils) and harden-try-parse-resolved-url.md (documents the tryParseCompatibleResolvedUrl non-throwing-contract restoration). All six prior inline threads are resolved. Three Tier 3 polish items remain — flagged inline.

Path to Ready

• Resolve inline threads

Context for Reviewers

• Load-side bookend of the multi-PR frozen-container series (ContainerLoader: Load pending state as a frozen container #25538, FrozenContainer: Support read blob #25590, Testing frozen container #25603, Expose creation of a frozen document service factory. #25653, feat(container-loader): add readOnly option to loadFrozenContainerFromPendingState #27211, feat(container-loader): add captureFullContainerState free function #27220). feat(container-loader): add captureFullContainerState free function #27220 (markfields) introduced captureFullContainerState as the inlined-blob counterpart; this PR is its consuming end, and the offline blob round-trip test in loadFrozenContainerFromPendingState.spec.ts is the integration point that proves the series hangs together.
• tryParseCompatibleResolvedUrl's non-throwing contract — originally established by markfields in Expose the parseUrl utility api for loop #17850 (2023-10-19), silently regressed in Remove url-parse usage throughout repo #19854 (2024-03-01) when the body was rewritten to use new URL(url) unguarded — is restored by harden-try-parse-resolved-url.md. The offline path is the first caller for which the gap mattered in practice; treat the harden change as a real bug fix, not cosmetic.
• ILoadFrozenContainerFromPendingStateProps now turns markfields' previously-soft URL-shape compatibility warning (Expose the parseUrl utility api for loop #17850) into a hard runtime precondition on the offline form: a host wiring a custom IUrlResolver whose resolved-URL shape differs (no two-segment path) will work online but fail offline with UsageError. JSDoc documents this; thread 3271021816 confirmed the wording in faa6a1f. Driver-compatibility scrutiny should focus here.
• IResolvedUrl.id single-segment convention is encoded as a contract for the first time. Every in-tree production resolver (localResolver, insecureUrlResolver, routerlicious-urlResolver, odspDriverUrlResolver) populates IResolvedUrl.id with only the trailing doc-id segment; the offline path now takes that trailing segment and a regression assertion frozenContainer.resolvedUrl?.id === "test" pins it. Empty-trailing-segment edge case is the inline finding on createAndLoadContainerUtils.ts:627.
• interface → type widening on ILoadFrozenContainerFromPendingStateProps has minimal blast radius: the API is @legacy @alpha, introduced one PR ago; PR Add legacy tags to the added apis for creating and loading container #23301 (jatgarg) established the @legacy @alpha evolution norm that @alpha-only consumers do not exist in production.
• IContainerHostProps / IContainerDriverServices / IContainerLoadDriverProps decomposition of ICreateAndLoadContainerProps is the natural follow-on to the original props-pattern move (anthony-murphy, Move Loader Constructor to Props Pattern #3945, 2020-10-15). Deprecation is opt-in; the alias is preserved.
• Offline implementation preserves the Container/Loader layering boundary established in Minimize involvement of Container in request headers #5175 (ChumpChief): offline behavior is composed entirely at the entry-point layer (synthesizes IUrlResolver, IResolvedUrl, IRequest, frozen IDocumentServiceFactory, then delegates to loadExistingContainer) — no changes to Container or Loader.
• Suggested reviewers: markfields (tryParseCompatibleResolvedUrl naming and URL-shape caveat in Expose the parseUrl utility api for loop #17850; authored captureFullContainerState in feat(container-loader): add captureFullContainerState free function #27220; persistent reviewer in the feat(container-loader): add readOnly option to loadFrozenContainerFromPendingState #27211 readOnly debate; right voice on the AllOrNone shape), ChumpChief (last touched tryParseCompatibleResolvedUrl in Remove url-parse usage throughout repo #19854 and established Container/Loader layering in Minimize involvement of Container in request headers #5175; right sign-off for the utils.ts contract shift and the resolved-form-URL shim), jatgarg (added the @legacy tags in Add legacy tags to the added apis for creating and loading container #23301 with the explicit rationale that Loop consumes these loader APIs; relevant for the @legacy @beta ICreateAndLoadContainerProps @deprecated tag and the @legacy @alpha AllOrNone export), dannimad (authored createFrozenDocumentServiceFactory in Expose creation of a frozen document service factory. #25653 and the test scaffold in Testing frozen container #25603; natural fit for frozenServices.spec.ts).

For human reviewer

• Needs human judgment (markfields) — Whether AllOrNone<T> belongs as a publicly-exported @legacy @alpha primitive in core-interfaces or should be inlined at the single current call site. Author's own previously unresolved comment 3276855511 ("can we restructure the interfaces to be more composable") suggested the shape may move again; reconciling that with the published export is a taste/owner call.
• Needs human judgment (markfields) — Offline + readOnly: false semantics: local DDS submissions accrue without being published. The "capture → restart offline → keep editing → re-capture and replay online later" workflow is the supporting case. Owner sign-off on this contract is appropriate.
• Needs human judgment (markfields / ChumpChief) — Offline getAbsoluteUrl deliberately throws UsageError rather than fabricating a string. Well-reasoned (a captured resolved-form URL would mislead any consumer that passes it back into a real resolver), but a contract call worth confirming.
• Needs human judgment (jatgarg) — Reshape of @legacy @beta ICreateAndLoadContainerProps into IContainerHostProps / IContainerDriverServices bases plus the @deprecated tag. Structurally identical so existing Loop call sites should still compile, but TS will emit deprecation diagnostics. PR Add legacy tags to the added apis for creating and loading container #23301 explicitly carved this surface out for Loop; a Loop-prod usage check and migration-window confirmation are human-scope.
• Cannot be assessed by the pipeline — Whether the end-to-end offline blob round-trip test catches realistic consumer workloads beyond a single primitive-DDS + single attachment-blob scenario; runtime determinism across resolver implementations; whether Loader.resolveCore / Container.load evolution will preserve the "request.url is opaque-until-resolver in offline mode" invariant.

Review history (6 prior reviews)

• 5efb38e 2026-05-21 · 5/10 — quiet-shrews-marry.md cross-package changeset gap for AllOrNone / validateAllOrNone
• ce2ede7 2026-05-20 · 5/10 — resolvedUrl.id two-segment shape divergence still unaddressed at this commit
• faa6a1f 2026-05-20 · 5/10 — resolvedUrl.id two-segment tenantId/docId shape divergence flagged inline on the offline path
• 9213320 2026-05-20 · 8/10 — both prior correctness concerns resolved; AllOrNothing API-surface item flagged inline
• 66f1d3d 2026-05-19 · 9/10 — AllOrNothing API-surface concern resolved (moved to core-interfaces, renamed AllOrNone); JSDoc shape-constraint Tier 3 flagged inline
• 2a9813f 2026-05-19 · 5/10 — two correctness concerns flagged inline (offline blob-read footgun; unreachable UsageError jacket in tryParseCompatibleResolvedUrl)

[anthony-murphy]

Deep Review: This is an observable change to the @legacy @alpha surface that isn't called out in any changeset.

Pre-PR, frozenDocumentStorageServiceHandler threw new Error("Operations are not supported on the FrozenDocumentStorageService."). Post-PR the generic handler throws new UsageError(...) (different class), and readBlob is rebound to a new frozenReadBlobOfflineHandler that throws a dedicated UsageError whose message names captureFullContainerState explicitly.

The three changesets in this PR cover URL parsing (harden-try-parse-resolved-url.md), the ICreateAndLoadContainerProps deprecation (quiet-shrews-marry.md), and the AllOrNone / validateAllOrNone primitive (sweet-spiders-grow.md) — none mention this Error → UsageError class change or the new readBlob-specific message.

Suggested fix: append a sentence to quiet-shrews-marry.md (or land a fourth changeset) noting that FrozenDocumentStorageService operations now throw UsageError instead of Error, and that readBlob on a no-inner-storage frozen container throws a dedicated UsageError whose message names captureFullContainerState.