feat(registry): implement async RegistryClient using httpx #32

2026-06-05T20:18:25Z

CoreRasurae commented

2026-06-05 20:18:25 +00:00

Add async RegistryClient implementing the Package Registry Standard v1.0.0 HTTP API endpoints using httpx.AsyncClient.

GET /packages/{id} — retrieve package content by PackageId
GET /{type}/{ns}/{name}?version= — resolve references with version alias resolution
GET /browse — discover published packages with type/namespace filters
GET /.well-known/cleverthis-packages — registry metadata discovery
Maps all 8 standard error types to typed exceptions
Supports anonymous reads and optional API key auth
Async context manager support
32 Behave BDD scenarios, 7 Robot Framework integration tests, ASV benchmarks, 100% registry module coverage

Closes #24

Add async RegistryClient implementing the Package Registry Standard v1.0.0 HTTP API endpoints using httpx.AsyncClient. - GET /packages/{id} — retrieve package content by PackageId - GET /{type}/{ns}/{name}?version= — resolve references with version alias resolution - GET /browse — discover published packages with type/namespace filters - GET /.well-known/cleverthis-packages — registry metadata discovery - Maps all 8 standard error types to typed exceptions - Supports anonymous reads and optional API key auth - Async context manager support - 32 Behave BDD scenarios, 7 Robot Framework integration tests, ASV benchmarks, 100% registry module coverage Closes #24

CoreRasurae added this to the v2.1.0 milestone 2026-06-05 20:18:25 +00:00

CoreRasurae added a new dependency 2026-06-05 20:21:07 +00:00

#24 feat(registry): implement async HTTP client using httpx

CoreRasurae force-pushed feature/m1-registry-http-client from 3f8a2b1df2 to 1ae754cc01

2026-06-05 21:07:29 +00:00

Compare

brent.edwards requested changes 2026-06-05 21:44:13 +00:00

Dismissed

brent.edwards left a comment

A few things I found.

features/registry_http_client.feature Outdated

						
				@@ -0,0 +139,4 @@

				  Scenario: Unknown error status falls back to RegistryError

				    When I create a RegistryClient pointed at "https://registry.example.com"

				    When the mock server returns status 418 with non-JSON body "plain text error"

brent.edwards commented

2026-06-05 21:18:35 +00:00

The 418 return code means: "I'm a teapot". Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/418

Are you sure that's the return code that you want to use?

The 418 return code means: "I'm a teapot". Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/418 Are you sure that's the return code that you want to use?

robot/RegistryClientLib.py Outdated

						
				@@ -0,0 +131,4 @@

				                future = asyncio.run_coroutine_threadsafe(coro_fn(), loop)

				                future.result(timeout=10)

				            else:

				                loop.run_until_complete(coro_fn())

brent.edwards commented

2026-06-05 21:22:10 +00:00

Why does the execution allow 10 seconds if the event loop is already running, but as much time as desired if the event loop needs to be started?

CoreRasurae commented

2026-06-05 22:05:32 +00:00

Fixed. Both code paths now use asyncio.wait_for() with a consistent 30s timeout (future.result(timeout=30) for running loops, loop.run_until_complete(asyncio.wait_for(coro_fn(), timeout=30)) for non-running loops, and asyncio.run(asyncio.wait_for(coro_fn(), timeout=30)) for the fallback).

brent.edwards marked this conversation as resolved

robot/fake_registry_server.py Outdated

						
				@@ -0,0 +63,4 @@

				                    "packages": [],

				                    "count": 0,

				                },

				            )

brent.edwards commented

2026-06-05 21:33:31 +00:00

This is probably not a good response. There are packages returned in the earlier parts of this if statement. But nothing is listed here.

A generic testing framework would want examples of packages here. It would read the example packages, then try to read them.

This is probably not a good response. There are packages returned in the earlier parts of this `if` statement. But nothing is listed here. A generic testing framework would want examples of packages here. It would read the example packages, then try to read them.

CoreRasurae commented

2026-06-05 22:05:58 +00:00

Fixed. fake_registry_server.py now defines EXAMPLE_PACKAGES with 2 packages (an actor and a graph) that are returned by the /browse endpoint. The browse response also supports optional ?type= filtering.

brent.edwards marked this conversation as resolved

src/cleveractors/registry/client.py Outdated

						
				@@ -0,0 +33,4 @@

				    "skill": "pkg_skl_",

				    "mcp": "pkg_mcp_",

				    "lsp": "pkg_lsp_",

				}

brent.edwards commented

2026-06-05 21:38:40 +00:00

When I look at https://git.cleverthis.com/cleveragents/cleveractors-core/pulls/31/files , file src/cleveractors/registry/types.py , lines 14-21 and I see this file, I get nervous. This is close to the same information in two different files.

What happens when a new package type appears in one but not the other?

I strongly recommend that the prefixes be in the same file, next to each other, so that it will be harder for them to get out of sync.

When I look at https://git.cleverthis.com/cleveragents/cleveractors-core/pulls/31/files , file src/cleveractors/registry/types.py , lines 14-21 and I see this file, I get nervous. This is close to the same information in two different files. What happens when a new package type appears in one but not the other? I strongly recommend that the prefixes be in the same file, next to each other, so that it will be harder for them to get out of sync.

CoreRasurae commented

2026-06-05 21:46:52 +00:00

That will be consolidated better after merging this PR and with other PR merged too. For now these are independent works.

brent.edwards marked this conversation as resolved

src/cleveractors/registry/exceptions.py

CoreRasurae commented

2026-06-05 22:17:10 +00:00

How do you know this isn't a ValidationError?

How do you know this isn't a `ValidationError`?

CoreRasurae commented

2026-06-05 22:19:11 +00:00

(Replying to your inline comment on src/cleveractors/registry/exceptions.py in the exception_for_status function)

The exception_for_status() function is the fallback — it only activates when the server does not include an explicit error type in the response body.

Per Package Registry Standard §13.1, compliant servers return errors as:

{"error": {"type": "ValidationError", "message": "..."}}
The _request() method now parses this structure first:

Extract body["error"]["type"] from the JSON response
Look it up in _ERROR_TYPE_MAP to get the correct exception class
Raise that specific exception (e.g. ValidationError, VersionNotFoundError, ...)
Only when the body lacks a recognizable error.type field does exception_for_status() act as the status-code-only fallback
This means a standards-compliant server can signal either ValidationError or InvalidPackageIdError at 400 by including the appropriate type value, and the client will raise the correct exception.

Test added:

Scenario: 400 with ValidationError error type in body raises ValidationError
  When the mock server returns status 400 with body '{"error": {"type": "ValidationError", "message": "..."}}'
  Then a ValidationError should be raised

(Replying to your inline comment on `src/cleveractors/registry/exceptions.py` in the `exception_for_status` function) The exception_for_status() function is the fallback — it only activates when the server does not include an explicit error type in the response body. Per Package Registry Standard §13.1, compliant servers return errors as: ``` {"error": {"type": "ValidationError", "message": "..."}} The _request() method now parses this structure first: ``` Extract `body["error"]["type"]` from the JSON response Look it up in `_ERROR_TYPE_MAP` to get the correct exception class Raise that specific exception (e.g.` ValidationError, VersionNotFoundError, ...`) Only when the body lacks a recognizable error.type field does `exception_for_status()` act as the status-code-only fallback This means a standards-compliant server can signal either ValidationError or InvalidPackageIdError at 400 by including the appropriate type value, and the client will raise the correct exception. Test added: ``` Scenario: 400 with ValidationError error type in body raises ValidationError When the mock server returns status 400 with body '{"error": {"type": "ValidationError", "message": "..."}}' Then a ValidationError should be raised ```

brent.edwards marked this conversation as resolved

src/cleveractors/registry/exceptions.py Outdated

						
				@@ -0,0 +68,4 @@

				    if status_code == 403:

				        return AccessDeniedError(message)

				    if status_code == 404:

				        return PackageNotFoundError(message)

brent.edwards commented

2026-06-05 21:42:33 +00:00

The above list of errors maps from PackageNotFoundError and VersionNotFoundError to 404. How do you know that this is a PackageNotFoundError instead of a VersionNotFoundError?

The above list of errors maps from `PackageNotFoundError` and `VersionNotFoundError` to 404. How do you know that this is a `PackageNotFoundError` instead of a `VersionNotFoundError`?

CoreRasurae commented

2026-06-05 22:08:12 +00:00

Fixed. The _request() method now parses the standard error format {"error": {"type": "...", "message": "..."}} from the JSON response body per Package Registry Standard §13.1. When the error type is present, it is matched against the defined types in _ERROR_TYPE_MAP to raise the correct specific exception. The status-code fallback via exception_for_status() is preserved for servers that do not include the type field or return non-standard error formats.

brent.edwards marked this conversation as resolved

brent.edwards commented

2026-06-05 21:46:20 +00:00

FOR ANYONE ELSE READING THIS -- We need to work quickly.

If, in your judgement, all of the problems have been either solved (i.e. new code) or there is an explanation, then feel free to accept this code and merge it with master.

FOR ANYONE ELSE READING THIS -- We need to work quickly. If, in your judgement, all of the problems have been either solved (i.e. new code) or there is an explanation, then feel free to accept this code and merge it with `master`.

CoreRasurae force-pushed feature/m1-registry-http-client from 1ae754cc01 to 92d5305a20

2026-06-05 22:01:36 +00:00

Compare

CoreRasurae reviewed 2026-06-05 22:03:51 +00:00

CoreRasurae left a comment

Thanks for the thorough review, Brent. Here is what was addressed and the rationale for each point:

Applied

#2 — Timeout asymmetry in RegistryClientLib._run()
Fixed. Both code paths now use asyncio.wait_for() with a consistent 30s timeout (future.result(timeout=30) for running loops, loop.run_until_complete(asyncio.wait_for(coro_fn(), timeout=30)) for non-running loops, and asyncio.run(asyncio.wait_for(coro_fn(), timeout=30)) for the fallback).

#3 — Fake server browse returns empty list
Fixed. fake_registry_server.py now defines EXAMPLE_PACKAGES with 2 packages (an actor and a graph) that are returned by the /browse endpoint. The browse response also supports optional ?type= filtering.

#6 — 404 maps to PackageNotFoundError but could be VersionNotFoundError
Fixed. The _request() method now parses the standard error format {"error": {"type": "...", "message": "..."}} from the JSON response body per Package Registry Standard §13.1. When the error type is present, it is matched against the defined types in _ERROR_TYPE_MAP to raise the correct specific exception. The status-code fallback via exception_for_status() is preserved for servers that do not include the type field or return non-standard error formats.

#7 — 400 maps to InvalidPackageIdError but could be ValidationError
Same fix as #6. Added Behave scenarios verifying both VersionNotFoundError (404 + type in body) and ValidationError (400 + type in body) are correctly raised when the server includes the explicit error type.

Not Applied

#1 — HTTP 418 status code in test
Not changed. The 418 response status is used in a single test scenario whose purpose is to verify that unmapped HTTP status codes fall through to the generic RegistryError. Any unregistered 4xx code serves this purpose equally well; 418 is as arbitrary as 417 or 422. The scenario description explicitly states "Unknown error status falls back to RegistryError", making the intent clear.

#4/#5 — Duplicate _PACKAGE_TYPE_PREFIXES dict vs PR #31 types.py
Not changed. As noted in your follow-up comment #5, these are independent works developed on separate branches. Consolidation will happen after both PRs are merged. Duplicating a small mapping on separate branches avoids a merge-order dependency between the two PRs.

Thanks for the thorough review, Brent. Here is what was addressed and the rationale for each point: ### Applied **#2 — Timeout asymmetry in `RegistryClientLib._run()`** Fixed. Both code paths now use `asyncio.wait_for()` with a consistent 30s timeout (`future.result(timeout=30)` for running loops, `loop.run_until_complete(asyncio.wait_for(coro_fn(), timeout=30))` for non-running loops, and `asyncio.run(asyncio.wait_for(coro_fn(), timeout=30))` for the fallback). **#3 — Fake server browse returns empty list** Fixed. `fake_registry_server.py` now defines `EXAMPLE_PACKAGES` with 2 packages (an actor and a graph) that are returned by the `/browse` endpoint. The browse response also supports optional `?type=` filtering. **#6 — 404 maps to `PackageNotFoundError` but could be `VersionNotFoundError`** Fixed. The `_request()` method now parses the standard error format `{"error": {"type": "...", "message": "..."}}` from the JSON response body per Package Registry Standard §13.1. When the error type is present, it is matched against the defined types in `_ERROR_TYPE_MAP` to raise the correct specific exception. The status-code fallback via `exception_for_status()` is preserved for servers that do not include the type field or return non-standard error formats. **#7 — 400 maps to `InvalidPackageIdError` but could be `ValidationError`** Same fix as #6. Added Behave scenarios verifying both `VersionNotFoundError` (404 + type in body) and `ValidationError` (400 + type in body) are correctly raised when the server includes the explicit error type. ### Not Applied **#1 — HTTP 418 status code in test** Not changed. The 418 response status is used in a single test scenario whose purpose is to verify that *unmapped* HTTP status codes fall through to the generic `RegistryError`. Any unregistered 4xx code serves this purpose equally well; 418 is as arbitrary as 417 or 422. The scenario description explicitly states "Unknown error status falls back to RegistryError", making the intent clear. **#4/#5 — Duplicate `_PACKAGE_TYPE_PREFIXES` dict vs PR #31 `types.py`** Not changed. As noted in your follow-up comment #5, these are independent works developed on separate branches. Consolidation will happen after both PRs are merged. Duplicating a small mapping on separate branches avoids a merge-order dependency between the two PRs.

CoreRasurae commented

2026-06-05 22:15:03 +00:00

Re: How do you know this isn't a ValidationError?

(Replying to your inline comment on src/cleveractors/registry/exceptions.py in the exception_for_status function)

The exception_for_status() function is the fallback — it only activates when the server does not include an explicit error type in the response body.

Per Package Registry Standard §13.1, compliant servers return errors as:

{"error": {"type": "ValidationError", "message": "..."}}

The _request() method now parses this structure first:

Extract body["error"]["type"] from the JSON response
Look it up in _ERROR_TYPE_MAP to get the correct exception class
Raise that specific exception (e.g. ValidationError, VersionNotFoundError, ...)
Only when the body lacks a recognizable error.type field does exception_for_status() act as the status-code-only fallback

This means a standards-compliant server can signal either ValidationError or InvalidPackageIdError at 400 by including the appropriate type value, and the client will raise the correct exception.

Test added:

Scenario: 400 with ValidationError error type in body raises ValidationError
  When the mock server returns status 400 with body '{"error": {"type": "ValidationError", "message": "..."}}'
  Then a ValidationError should be raised

### Re: How do you know this isn't a ValidationError? *(Replying to your inline comment on `src/cleveractors/registry/exceptions.py` in the `exception_for_status` function)* The `exception_for_status()` function is the **fallback** — it only activates when the server does not include an explicit error type in the response body. Per Package Registry Standard §13.1, compliant servers return errors as: ```json {"error": {"type": "ValidationError", "message": "..."}} ``` The `_request()` method now parses this structure first: 1. Extract `body["error"]["type"]` from the JSON response 2. Look it up in `_ERROR_TYPE_MAP` to get the correct exception class 3. Raise that specific exception (e.g. `ValidationError`, `VersionNotFoundError`, ...) 4. Only when the body lacks a recognizable `error.type` field does `exception_for_status()` act as the status-code-only fallback This means a standards-compliant server can signal either `ValidationError` or `InvalidPackageIdError` at 400 by including the appropriate type value, and the client will raise the correct exception. Test added: ```gherkin Scenario: 400 with ValidationError error type in body raises ValidationError When the mock server returns status 400 with body '{"error": {"type": "ValidationError", "message": "..."}}' Then a ValidationError should be raised ```

brent.edwards approved these changes 2026-06-05 22:21:31 +00:00

brent.edwards left a comment

Looks good to me!

CoreRasurae merged commit 92d5305a20 into master

2026-06-05 22:27:54 +00:00

CoreRasurae deleted branch feature/m1-registry-http-client

2026-06-05 22:27:54 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Blocks

#24 feat(registry): implement async HTTP client using httpx

cleveragents/cleveractors-core

Reference: cleveragents/cleveractors-core#32