Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions python/client-contract/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ All notable changes to the `dfo-spec-kit-client-contract` Python package will be
- `scenario.schema.json`, the scenario record, and 126 scenarios: 34 recorded against the deployed dfo-apis dev app at `ccb661792`, and 92 synthetic, each derived from a recorded one by a one-line edit, with 21 binary bodies totalling 1,142,020 bytes and records and bodies together 14,160,817 bytes. `search-place-ambiguous-twice` pins two entity_ambiguous groups of one text, each option and slot token naming its group by `entity_choice`, and `choose-refused-label-in-two-groups` pins that a label both groups offer matches two options, so a choice there names its option by index. The scenarios cover the several-part choice entries and the assumptions each identity entry echoes, a picked reading whose assumption Search states in its answer, the place choice through a no_data part's options, the choice refusals, a part without variable_text, an unknown status without a restatement, a shared label, a one-part option whose data_query holds two parts, the separate and operations echo, an unsupported part's placeholder, the timed_out, unsupported and unknown gaps, an unknown answer kind, the `SearchWarning` rule, the stacked dataset's `part` column, the frame layout, a strict fetch's `DataWarning`, a spec fetch that rebinds one of two entity roles and keeps the other, one that drops a role bound to null, a spec whose destination is a named group fetched with a window or with its origin rebound, whose sentence lookup posts the groups of the roles the build left bound, a twice cut-off build, a cut-off build retried after its Retry-After, a retryable refusal whose Retry-After passes the 60-second cap, a build refused 504 then 503 and one refused 503 then 504, a refused build, a build refused 501 `capability_unavailable`, a digest mismatch, a signed URL refused on both rounds, a relative files-route Location, an artifact url on a foreign origin, on the storage host and absolute on the API's origin, a manifest definition without identity or schema_version, a Search spec without identity or resolved, nested specs no rule reads, an empty parts list, a Search body that is not an object, a codeless 503 problem document that is not retryable, a 401, an identity resubmit answering another spec, a part whose status is not a string, a Search spec whose definition names another spec_id, a Search response with no JSON body, an option with no data_query, empty entities and facets, a Sunset header issued once, `x-dfo-warning` messages and a Deprecation and Sunset pair, an unreadable versions page, a mint and a spec fetch whose build answers 202 and is polled to done, a resumed operation, a rate-limited poll, 503 polls retried within the budget an answered poll restores, a 202 that reads running, polls whose `retry_after_ms` changes from one to the next, a 404 poll that raises, a failed operation posted again, a failed operation with no error, and a ref whose stored file expired, read through the file selector, rebuilt at the same version, at a newer one, or refused with the newest version read from the versions route: the first version it lists with no `base_content_version`, the newest plain build, so a derived version listed before it is skipped.
- `client-codes.json` and its schema: the 35 codes a client sets on the errors it raises itself, each with its error class, retryable flag and condition, disjoint from `actions.json` and `registries/codes.json`, and the `client_codes()` and `client_codes_schema()` accessors. Every scenario error the client raises itself carries its code, and `refusal_without_code` names a refusal whose body carries no code.
- `proxy-codes.json` and its schema, the website proxy's `rate_limited` and `transient_unavailable` codes with their statuses, which the proxy sends in problem documents of the shape every refusal has, both retryable, with `Retry-After` on the 429, so a client reads one refusal shape, and `warning-codes.json` and its schema, the 7 codes a client sets on the warnings it issues itself, with the `proxy_codes()` and `warning_codes()` accessors.
- `invalid_api_key` in `proxy-codes.json`, the 401 the website proxy answers a call whose API key, sent as `Authorization: Bearer dfo_...` or `X-API-Key`, is unknown, revoked or malformed. The call is refused, not served as an anonymous one, and the problem document is not retryable, so a client raises `AuthenticationError` with this code. `tools/validate_client_contract.py` expects `retryable: false` in a proxy problem document with this code and `retryable: true` in any other.
- `ref_digest_changed` in `warning-codes.json`, a `DfoWarning` for a ref member whose `content_version` serves a file with another digest than the ref's, because the server rendered the same data again. The client returns the data, with no error under strict.
- `timed_out` in `actions.json` and `registries/codes.json`, the no_data reason Search gives a part it left unresolved at the request's time limit, with action `ask_data_question` and gap kind `timed_out`, which `actions.schema.json` now admits. The client-side `timeout` code, a transport timeout, is unchanged.
- A no_data part's gap kind comes from its own reason, whatever the answer's `diagnostics.timed_out` says. `answer-timed-out` gives its part the reason `timed_out`, and `answer-timed-out-keeps-reasons` pins a part that keeps `variable_not_resolved` as a `not_understood` gap in a timed-out answer.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
{
"format_version": 1,
"codes": [
{
"code": "invalid_api_key",
"status": 401,
"condition": "The API key the caller sent in Authorization: Bearer dfo_... or X-API-Key is unknown, revoked or malformed; the call is not treated as anonymous, so it is refused rather than served without a key, and the document is not retryable."
},
{
"code": "rate_limited",
"status": 429,
Expand Down
27 changes: 27 additions & 0 deletions tools/tests/test_validate_client_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,33 @@ def _digest_vector(document: Any, name: str) -> Any:
return next(vector for vector in document["vectors"] if vector["name"] == name)


def _proxy_problem(code: str, retryable: bool) -> dict[str, Any]:
return {
"headers": {"content-type": "application/problem+json"},
"status": 401,
"json": {
"type": f"/codes/{code}",
"title": "x",
"status": 401,
"detail": "x",
"code": code,
"trace_id": "t",
"retryable": retryable,
},
}


def test_an_invalid_api_key_problem_is_not_retryable() -> None:
check = validator._check_proxy_problem
assert check("l", _proxy_problem("invalid_api_key", False)) == []
assert check("l", _proxy_problem("invalid_api_key", True)) == [
"l: a proxy problem document is not retryable: false"
]
assert check("l", _proxy_problem("rate_limited", False)) == [
"l: a proxy problem document is not retryable: true"
]


def test_the_real_contract_is_valid(package_dir: Path) -> None:
assert validator.validate() == []
assert validator.main() == 0
Expand Down
17 changes: 13 additions & 4 deletions tools/validate_client_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@
included, is an active code registered with its status or a code
`proxy-codes.json` lists with its status. A document with a proxy code is
`application/problem+json` and carries PROXY_PROBLEM_MEMBERS, its own
status and `retryable` true, and no 202's operation reads `done`.
status and `retryable` true, or false for `invalid_api_key`, and no 202's
operation reads `done`.
- Each error a scenario expects, other than a `SearchWarning` or
`DataWarning`, carries a refusal's code from its exchanges, a failed
operation's included, or a client code of its class.
Expand Down Expand Up @@ -762,11 +763,15 @@ def _check_accepted(label: str, response: Mapping[str, Any]) -> list[str]:
# The members every problem document the website proxy answers itself carries.
PROXY_PROBLEM_MEMBERS = ("type", "title", "status", "detail", "code", "trace_id")
PROXY_PROBLEM_MEDIA = "application/problem+json"
# A proxy code whose problem document is `retryable: false`, because the same
# call refused again gets the same answer. Every other proxy code is retryable.
PROXY_NOT_RETRYABLE = frozenset({"invalid_api_key"})


def _check_proxy_problem(label: str, response: Mapping[str, Any]) -> list[str]:
"""A proxy problem document is `application/problem+json`, has the common
members, carries the response's status, and has `retryable` true."""
members, carries the response's status, and has `retryable` true, or false
for a code in `PROXY_NOT_RETRYABLE`."""
body = response["json"]
problems = []
content_type = response.get("headers", {}).get("content-type", "")
Expand All @@ -779,8 +784,12 @@ def _check_proxy_problem(label: str, response: Mapping[str, Any]) -> list[str]:
problems.append(f"{label}: a proxy problem document lacks {missing}")
if "status" in body and body["status"] != response["status"]:
problems.append(f"{label}: a proxy problem document's status is not its own")
if body.get("retryable") is not True:
problems.append(f"{label}: a proxy problem document is not retryable: true")
retryable = body.get("code") not in PROXY_NOT_RETRYABLE
if body.get("retryable") is not retryable:
problems.append(
f"{label}: a proxy problem document is not "
f"retryable: {str(retryable).lower()}"
)
return problems


Expand Down
Loading