feat(orbit): Add Orbit named query templates endpoint

Aaron Algutifanrequested to merge
aalgutifan/orbit-template-grpc-endpoint into master

What does this MR do and why?

Adds GET /api/v4/orbit/query/templates, which proxies the Knowledge Graph ListNamedQueries RPC and returns the server-defined named queries with name, description, and the query DSL rendered for the current user (identity bindings resolved from the caller, parameters filled with their declared examples).

The Orbit graph explorer currently hardcodes named-query identifiers and, before that, whole DSL strings that drifted from the server's grammar and ontology. With this endpoint the frontend can populate its preset dropdown and query editor from the server-owned catalog, so query text never lives on the client. The returned raw_query is executable as-is via POST /api/v4/orbit/query.

Also bumps gitlab-gkg-proto to 0.87.0, which ships the new RPC stubs.

References

Screenshots or screen recordings

API-only change, no UI. Example response:

[
  {
    "name": "my_neighbors",
    "description": "Immediate graph neighborhood of the current user.",
    "raw_query": { "query_type": "neighbors", "node": { "id": "me", "entity": "User", "node_ids": [1] }, "neighbors": { "node": "me", "direction": "both" }, "limit": 100 }
  }
]

How to set up and validate locally

  1. Run a local GKG server (mise run dev in the knowledge-graph repo) alongside GDK.

  2. Enable the feature flag in the rails console:

    Feature.enable(:knowledge_graph, User.find_by_username('root'))

  3. Fetch the catalog with an api-scoped PAT:

    curl -H "PRIVATE-TOKEN: $TOKEN" http://127.0.0.1:3000/api/v4/orbit/query/templates

  4. Round-trip a returned template to confirm it executes unchanged:

    curl -X POST -H "PRIVATE-TOKEN: $TOKEN" -H "Content-Type: application/json" \
  -d '{"query": <raw_query from step 3>}' http://127.0.0.1:3000/api/v4/orbit/query

Validated locally end-to-end: catalog returns all 6 embedded named queries with bindings rendered to the caller's user id, and the my_neighbors template executed via POST /orbit/query (Workhorse + redaction path) returning 99 nodes / 99 edges.

Security and caching notes

  • The rendered raw_query only substitutes the caller's own user ID into the query text. It grants no query capability: authorization happens at execution time in the GKG query pipeline (compiler security pass and redaction), under the executing user's permissions, regardless of which IDs appear in the DSL.
  • Responses are per-user, but the API default Cache-Control: max-age=0, private, must-revalidate (verified against GDK) already prevents shared or proxy caching, and the endpoint performs no fragment caching.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Aaron Algutifan

Merge request reports