CycloneDX / CycloneDX/transparency-exchange-api

Complete discovery failover: missing priority, invalid JSON, well-known vs /discovery

Open
#282 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.