diff --git a/python/client-contract/CHANGELOG.md b/python/client-contract/CHANGELOG.md index dadb4ef..708bea7 100644 --- a/python/client-contract/CHANGELOG.md +++ b/python/client-contract/CHANGELOG.md @@ -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. diff --git a/python/client-contract/src/dfo_client_contract/proxy-codes.json b/python/client-contract/src/dfo_client_contract/proxy-codes.json index 3bdf54e..d8dbc55 100644 --- a/python/client-contract/src/dfo_client_contract/proxy-codes.json +++ b/python/client-contract/src/dfo_client_contract/proxy-codes.json @@ -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, diff --git a/tools/tests/test_validate_client_contract.py b/tools/tests/test_validate_client_contract.py index 353c2e5..62aaa0f 100644 --- a/tools/tests/test_validate_client_contract.py +++ b/tools/tests/test_validate_client_contract.py @@ -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 diff --git a/tools/validate_client_contract.py b/tools/validate_client_contract.py index 60ffb65..dbb5fd6 100644 --- a/tools/validate_client_contract.py +++ b/tools/validate_client_contract.py @@ -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. @@ -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", "") @@ -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