Skip to content

chore: Implement openranking#46

Merged
dcadenas merged 13 commits into
mainfrom
feat/1037-implement-openranking
May 30, 2026
Merged

chore: Implement openranking#46
dcadenas merged 13 commits into
mainfrom
feat/1037-implement-openranking

Conversation

@dcadenas

Copy link
Copy Markdown
Contributor

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:

  • POST /rank ranks pubkeys by global PageRank, returning a rank for every requested pubkey (unknown pubkeys rank 0).
  • POST /reputation returns PageRank as the rank, follower and following counts, and our trust verdict in the provider x extension.
  • POST /followers returns the top followers of a pubkey by PageRank, plus the total follower count from the follow edges.
  • POST /recommend returns personalised for-you recommendations (a pov is required), up to 10.

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.

  • cargo test --all-features --features ci: 86 passed, 0 failed
  • cargo clippy --all-targets --all-features -- -D warnings: clean
  • cargo fmt --all -- --check: clean

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.

dcadenas added 13 commits May 29, 2026 14:54
…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
@dcadenas
dcadenas marked this pull request as ready for review May 30, 2026 07:06
@dcadenas
dcadenas merged commit edb34ef into main May 30, 2026
4 of 6 checks passed
@dcadenas
dcadenas deleted the feat/1037-implement-openranking branch May 30, 2026 07:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant