CycloneDX / CycloneDX/transparency-exchange-api
Complete discovery failover: missing priority, invalid JSON, well-known vs /discovery
- Dominant language
- Shell
- Stars
- 113
- Forks
- 22
- Avg merge
- 8d 12h
- Merged PRs (30d)
- 5
Description
## Summary
Discovery failover and failure reporting were tightened in #276 (compatible endpoints, bounded attempts, TLS on failover, and auth failures as “update status could not be determined”). A few related client rules are still unspecified: omitted `priority`, invalid discovery JSON, and the split between `.well-known` failure and `/discovery` failure.
This issue tracks only those leftovers, as a follow-up to #276 / #275.
## What #276 already covers
- Fail over only to an untried endpoint with a compatible API version
- Bound total discovery attempts; backoff; report when discovery could not be completed
- Do not fail over solely on `401` / `403`
- Auth/authorization failures MUST NOT be reported as “no updates available”
## Remaining gaps
1. Missing `priority`
- `discovery/tea-well-known.schema.json` gives `priority` a JSON Schema `default: 1`, but defaults do not populate omitted fields in responses.
- OpenAPI `tea-server-info.priority` has no equivalent effective-default rule.
- Proposed: if `priority` is absent, clients MUST treat it as `1` for both `.well-known` endpoints and discovery `servers[]`.
2. Invalid discovery JSON
- No rule for malformed or non-conforming `.well-known/tea` documents, or invalid `/discovery` response bodies.
- Proposed: treat as a failed attempt for that candidate (count toward the bound; failover if another compatible endpoint remains).
3. Well-known vs `/discovery` failure
- Current prose mixes DNS / TLS / 5xx handling without clearly separating:
- failure to retrieve or use `.well-known/tea`, vs
- failure of `/discovery` on an already selected API base.
- Proposed: same retry/bound machinery for both stages, but state the stages explicitly so clients know what failed.
## Relation to other work
- Builds on #276 / #275; does not replace them.
- Related to #274 (discovery `404` semantics) and the cardinality / non-empty discovery response work — keep those separate; this issue is only failover/failure reporting leftovers.
Does this follow-up scope look right to address after #276 merges?
Contributor guide
Assessment
This issue has not been assessed yet.