chore: Implement openranking#46
Merged
Merged
Conversation
…covery route (ORE-01) with algorithm registry; 3 unit tests
…ery, OpenRankingError (400/413/422/500 + X-Reason header) and algorithm resolution; 12 unit tests
…ower/following stats, is_trusted in x extension; 6 unit tests
…uery (top followers by pagerank + total follower_count) and shared limit validation; 7 unit tests
…ommendations requiring pov, similarity mapped to rank; 6 unit tests
…th /api/v1) and document the endpoints in the README
…e instead of blocking on the heavy query
…d of wedging /recommend on a 500
dcadenas
marked this pull request as ready for review
May 30, 2026 07:06
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
nos-followers already computes PageRank, follow-graph counts, a trust verdict, and similarity recommendations, but only exposed them through its own /api/v1.
This change adds the part of the Open Ranking protocol that fits our graph, so any Open Ranking client can read that data without a custom integration.
The new endpoints are additive, so /api/v1 is unchanged.
What Changed
New top-level JSON-over-HTTP endpoints, discoverable from a capability document at GET /.well-known/open-ranking:
Input is validated per the spec (400 malformed, 413 too large, 422 semantic) with an X-Reason header, and the routes share the existing CORS, timeout, and rate-limit layers.
Two batched Neo4j reads were added (get_pageranks and get_top_followers); the rest reuses existing repo methods.
/recommend never blocks on the heavy similarity query.
A cache miss starts a background compute through the shared recommendation queue and returns an empty list with a short ttl, and the client retries once it is warm.
A transient compute failure now self-heals: the queue treats a cached failure as a miss and re-enqueues on the next request, instead of wedging the endpoint on a 500 until the status cache expired.
New Prometheus metrics track the cold-miss rate and the warm-up compute time, and CI now gates rustfmt and clippy.
Testing
I rebased onto main and ran the suite on the pinned 1.84.0 toolchain.
The two new repo queries also have Neo4j integration tests, gated out of CI and run locally against the compose db service.
Risks
The change is additive, so existing /api/v1 consumers are unaffected.
For a cold account, /recommend returns an empty list first and the real list once the background compute finishes, so clients retry after the ttl.
The warm-up histogram measures the compute time, which is the dominant cost, not the time a request waits in the queue.