docs: fix stale "static resolution" fallback comments · Entire

docs: fix stale "static resolution" fallback comments

fa23d62→main·

Soph·1mo ago·3 files·+15 added/-14 removed

ResolveDataAPIToken is discovery-only since 10aa97eec: a host that doesn't advertise /.well-known/entire-api.json is a surfaced error, not a fall-through to static resolution. Three comments still described the removed fallback — recap.go and dispatch/mode_local.go on the call side, and api_discovery.go's ErrDiscoveryUnavailable doc on the source side (which invited a future caller to reintroduce the fallback). The no-fallback docs-alignment pass (087f5a498) missed these.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

Sessions

d5fa60431596View transcript

Changes

3

26 unmodified lines

27
28
29
30
31
30
31
32
33
34

26 unmodified lines

// lookupResourceToken returns a bearer for the given data-API base URL.
    // Production wiring goes through auth.ResolveDataAPIToken so the dispatch
    // host's /.well-known/entire-api.json picks the matching login context
    // (falling back to static resolution when unadvertised). Tests swap to a
    // fixed-token closure.
    // (a host that doesn't advertise discovery is a surfaced error). Tests
    // swap to a fixed-token closure.
    lookupResourceToken = auth.ResolveDataAPIToken

nowUTC = func() time.Time { return time.Now().UTC() }

Mcmd/entire/cli/dispatch/mode_local.go+2/-2

169 unmodified lines

170
171
172
173
174
173
174
175
176
177

169 unmodified lines

//
// Goes through auth.ResolveDataAPIToken (the same context-aware path as
// activity/search/dispatch) so the data host's /.well-known/entire-api.json
// picks the matching login context and exchanges for the advertised audience,
// falling back to static resolution when discovery is unavailable.
// picks the matching login context and exchanges for the advertised audience;
// a host that doesn't advertise discovery is a surfaced error, not a fallback.
// ErrNotLoggedIn is collapsed back into an empty token so the caller's "render
// with no bearer, let the server respond 401" path still fires. Every other
// resolution failure (no eligible/ambiguous context, STS exchange rejected,

Mcmd/entire/cli/recap.go+2/-2

31 unmodified lines

32
33
34
35
36
37
38
39
35
36
37
38
39
40
41
42
43
44
45
45
46
47
48
17 unmodified lines

66
67
68
69
69
70
71
72
20 unmodified lines

93
94
95
96
97
98
96
97
98
99
100
101
102

31 unmodified lines

// ErrDiscoveryUnavailable wraps every "the API didn't give us a usable
// trust-root document" outcome: it doesn't serve /.well-known/entire-api.json
// (404 — old deployment), is unreachable, answers 503 (unconfigured), or
// returns a malformed/empty body. Callers match on it to fall back to
// static token resolution so behaviour is never worse than before
// discovery existed. Selection failures (no eligible / ambiguous
// context) are NOT wrapped — those are real "log in / pick one" errors
the user must see.
// returns a malformed/empty body. Callers match on it to surface a clear
// "host does not advertise its trusted login servers" error — discovery is
// the only path, so there is no static fallback. Selection failures (no
// eligible / ambiguous context) are NOT wrapped — those are real "log in /
// pick one" errors the user must see.
var ErrDiscoveryUnavailable = errors.New("api discovery unavailable")

// DiscoverAPI fetches and parses an API host's /.well-known/entire-api.json,
// returning its trusted issuers. Every failure mode (transport, non-200,
// decode, empty trusted_issuers) is folded under ErrDiscoveryUnavailable so the
// caller has a single sentinel to fall back on.
// caller has a single sentinel to match on.

func DiscoverAPI(ctx context.Context, apiHost string, c *http.Client, debugf DebugFunc) (*APIResponse, error) {
17 unmodified lines

// Shares the cache-then-discover logic with resolveClusterCores via
// resolveCachedCores — the data-API trusted issuers ARE core URLs, so they
// reuse the cores cache (different file). Cold failures stay folded under
// ErrDiscoveryUnavailable (from DiscoverAPI) for the caller's static fallback.
// ErrDiscoveryUnavailable (from DiscoverAPI) for the caller to surface.
func resolveAPICores(ctx context.Context, cacheDir, apiHost string, httpClient *http.Client, debugf DebugFunc) ([]string, error) {
    return resolveCachedCores(cacheDir, apiHost, "api host",
        discovery.LoadAPICores, discovery.ModifyAPICores,
20 unmodified lines

//
// When the API doesn't advertise discovery (404 / unreachable / 503 /
// malformed) and no cache entry exists, the returned error wraps
// ErrDiscoveryUnavailable so the caller falls back to static resolution. A
// successful fetch whose context selection fails returns that selection error
// unwrapped — the user must act on it.
// ErrDiscoveryUnavailable; data-API callers surface it as a fatal "host does not
// advertise its trusted login servers" error rather than guessing which
// login servers to trust. A successful fetch whose context selection fails
// returns that selection error unwrapped — the user must act on it.
//
// debugf is optional; nil suppresses debug output.
func ResolveContextForAPI(ctx context.Context, configDir, cacheDir, apiHost string, httpClient *http.Client, debugf DebugFunc) (*contexts.Context, error) {