Configuration and network policy: bound the header block and the destination, and let a stage set both

[snkmcb]

The start of v0.7.0, ahead of v0.6.0 for the reason v0.5.0 was: this is
code, and the consumer integration is waiting on a gigabyte fixture and a host.
Three of phase 7's rows — the bounds §10 of the design policy names and the tree
did not enforce, and the per-stage configuration surface that lets a host state
them for one stage rather than for the whole process.

What it does

A bound on the response header block (660925b). 64 KiB per exchange,
summed across interim 1xx responses and counted in the transport before a line
is stored. With the caller's buffer already bounding the body, that is the whole
of §10.1's "bound the response header block and the total response size". A
response abandoned at the bound is refused whole, as InvalidResponse, whatever
its status — its status line arrived intact, and an open that took
Content-Length and Accept-Ranges from the prefix that fit would be acting on a
response nobody finished receiving. The corpus gains a nineteenth row,
OversizedHeaders, and the redirect-hop scheme allowlist gets the explicit case
implementation-status.md said it was owed.

A destination policy (856ff4e, e6e8768), USD_HTTP_RESOLVER_DESTINATIONS:
a set of address classes — public, private, loopback, link-local,
metadata — a connection may reach. The default is public,private,loopback:
loopback and intranet hosts are what http is registered for, and link-local
and the well-known instance-metadata endpoints are refused — the latter a class
of its own, by value, because AWS's IPv6 endpoint is unique-local and Alibaba's
is in the shared address space. It is judged three times — at connect time, in
CURLOPT_OPENSOCKETFUNCTION, against the address a name actually resolved to;
before each request, against the host as libcurl's own URL parser will send it,
which is what holds through a proxy; and at every redirect hop against a
canonical literal. IPv4-mapped, -compatible, and NAT64 addresses are the class
of the IPv4 address they carry. A refusal is AccessDenied naming the class,
unsent and unretried. libcurl is also told http,https and nothing else.

Per-stage configuration through ArResolverContext (9bf6459, e6e8768):

ctx = Ar.GetResolver().CreateContextFromString(
    "https", "USD_HTTP_RESOLVER_DESTINATIONS=public; USD_HTTP_RESOLVER_MAX_RETRIES=0")
stage = Usd.Stage.Open("https://example.org/scenes/main.usda", ctx)

The environment's own names and parser, so a value in a context is refused or
adjusted for exactly the reasons it would be in the environment, and kept as
the parser read it so that equivalent spellings are one context. The
environment is snapshot at the resolver's first use and a context resolves
against it: context, then environment, then default. No header of this
repository reaches a host that configures it this way.

What the review found (e6e8768)

A /code-review pass over the first three commits found the same shape of
defect four times: a guarantee that held in the case written for it and not the
one beside it. Each is closed, and each fix has a case that fails without it.

• Through a proxy, a non-canonical spelling walked past the policy. The
  connect is the proxy's, and libcurl normalizes 2852039166 to
  169.254.169.254 before the proxy reads it. The host is now judged as
  libcurl will send it; usdAssetHttp_destination_policy uses the fixture
  server as the proxy, and with the check removed four of five spellings reach
  it.
• Refusing link-local did not refuse the metadata endpoints outside it, so
  those became the metadata class.
• OpenUSD's scoped cache keyed Resolve by path, walking past a per-stage
  policy the way the layer registry had. The bundle declares
  implementsScopedCaches and keys the scope's cache by configuration. Asset
  info had the same gap and now answers from memory only for a caller whose
  policy could have reached the asset.
• Implementing contexts means being constructed in every process that opens
  any stage. The constructor had configured the persistent tier, creating its
  directory for local-only hosts. Construction now does nothing and
  configuration happens at first use; a local-only child process is asserted to
  leave no directory behind.

Smaller, in the same pass: no retry of an abandoned header block behind a
503; line breaks trimmed from a destination list instead of falling back to
the wider default; context adjustments judged over the environment; the Python
conversion under the GIL and no other lock; the context type out of OpenUSD's
namespace; close-on-exec sockets; dead getenv entry points removed.

Things worth reviewing

The header bound was not optional. With it removed, libcurl 8.7.1 opens an
asset behind a megabyte of ordinary header fields; the library's ceilings are on
a single line, and a block of kilobyte lines never reaches them. With libcurl's
own CURLE_TOO_LARGE reclassified as something else, the row still passes, so
the refusal is this code's.

Only the connect-time check stops a name. Removing it leaves every literal
case passing and lets localhost through a policy that refuses loopback.
usdAssetHttp_destination_policy's name case is the one test that fails, which
is what it is there for.

Every identifier this resolver owns is now context-dependent. Not because it
resolves to a different path under two contexts, but because whether it resolves
at all can — and OpenUSD's layer registry acts on the answer. For a path that is
not context-dependent, SdfLayer::FindOrOpen finds an already-loaded layer by
identifier whatever Resolve has just said, so a stage whose context refuses a
destination would be handed the layer by any stage that opened the URL first.
Answering false fails exactly the stillRefused case in httpResolver_stage.
The only other reader of that answer in OpenUSD is usdUtils packaging, which
sends URI paths down its remap path either way.

The retained opens are keyed by transport options as well as identifier.
Correct keyed by identifier while one process had one configuration; a reader
keeps the options it was opened with, and keyed by identifier alone the refusing
context in TestRetainedOpenIsNotHandedAcrossContexts got a reader a permissive
resolve had left behind.

The metadata list is a list. Eight addresses, by value, documented in
CONFIGURATION.md §2.1. It is the one piece of provider-specific knowledge in
the policy, and the alternative — calling link-local "the metadata endpoint" —
was true of one address out of eight.

Four variables are not settable per stage. The block size, the two budgets,
and the persistent directory stay the environment's, although the roadmap's
v0.7.0 scope lists block size and budgets among what a context resolves. Every
stage shares the store they configure, and the store's stripes are sized for one
block size — eight blocks to a stripe, 2 MiB at the defaults — so a stage asking
for larger blocks would fetch each one and watch it evicted on arrival. A context
naming one is told so when it is created. This is a judgement call and the place
to disagree with it.

A Python conversion in the bundle. Without one, ctx.Get() raised
TypeError: No to_python (by-value) converter found, and Usd.Stage.__repr__
printed pathResolverContext=<invalid repr>. The context converts to its
canonical string, registered once Python is running. It uses the vendored
pxr_boost::python that tf already links, under PXR_PYTHON_SUPPORT_ENABLED.

Tests

• usdAssetHttp_destination — address classification as a table: every class
  boundary from both sides, the metadata endpoints and their neighbours, the
  mapped/compatible/NAT64 spellings, and the non-canonical forms left to the
  transport.
• usdAssetHttp_destination_policy — the client-side and connect-time halves
  over a real socket, through localhost, 127.1, and a proxy.
• usdAssetHttp_protocol — the abandoned header block at open, at a redirect,
  mid-read, and behind a 503; seven refused redirect schemes; the policy's
  pre-flight at every hop and its presence on every request the transport sees.
• usdAssetFixture_corpus, usdAssetHttp_corpus_projection — OversizedHeaders
  from the wire, and projected.
• httpResolver_configuration — the variable, the context string grammar,
  canonical values, line breaks, judgement over the environment, precedence,
  and the fingerprint.
• httpResolver_stage — a context configuring one stage, including through a
  layer another stage loaded, a retained reader, a scoped cache, and asset
  info; a context bounding the transport; and a local-only child process left
  untouched.

Verified locally on macOS arm64 (Apple clang 17, libcurl 8.7.1, OpenUSD 26.08):
core 31/31, ASan + UBSan 31/31, TSan 31/31, plugin 36/36, and the plugin's
configuration code under ASan + UBSan by hand. The first three commits passed
all twelve CI lanes, Windows included; e6e8768 adds SetHandleInformation on
Windows and curl_url on every platform, which CI is the first to build.

Not in this PR

• The rest of phase 7: the request interception point for authentication, which
  needs an ADR on how a host supplies a provider before it needs code; formation
  composition; and the /Brepro link flag for reproducible Windows binaries.
• The release commit. VERSION, openstrata.toml, the plugin manifest, and the
  CMake fallback are untouched, and the changelog section is Unreleased.

🤖 Generated with Claude Code