stacklok / stacklok/toolhive

Align embedded v0.1 registry list endpoints with client contract (search/pagination mismatch)

Open
#6,138 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement needs-triage registry
Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Found while implementing #5529 (see PR #6135 reviewer notes).

The registry extension client and thv's embedded v0.1 handlers disagree on the list-endpoint wire contract, for both skills and plugins:

Client (pkg/registry/api/skills_client.go, plugins_client.go) Embedded handler (pkg/api/v1/registry_v01_skills.go, registry_v01_plugins.go)
Search param ?search= ?q=
Pagination params ?cursor= + ?limit= ?page= + ?limit=
Response metadata metadata.count + metadata.nextCursor metadata.total + page + limit

Concretely: pointing SkillsClient/PluginsClient at a ToolHive embedded registry API (rather than toolhive-registry-server) means server-side search silently returns the unfiltered first page, and auto-pagination terminates after page 1 (client looks for nextCursor, handler never emits it) — silently truncating catalogs >100 entries.

The client contract matches toolhive-registry-server's API (which uses search/cursor/limit + count/nextCursor — see internal/api/x/skills/routes.go there), so the embedded handlers are the odd ones out. The plugins client/handler copied the skills pair verbatim, so both pairs need fixing together.

Proposed direction: align the embedded v0.1 handlers with the registry-server contract (search/cursor + count/nextCursor), or make the clients tolerate both shapes. Needs a compatibility pass first — check whether anything external already consumes the embedded routes' q/page shape (UI, docs, thv itself).

Refs: #5525 (epic), #5529, PR #6135.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare pkg/registry/api/skills_client.go and plugins_client.go with pkg/api/v1/registry_v01_skills.go and registry_v01_plugins.go, then inspect internal/api/x/skills/routes.go and references in the UI, docs, and thv. Confirm whether q/page is externally consumed before choosing a compatibility approach; done means both embedded list endpoints match the client contract without breaking existing consumers or pagination.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.