Skip to content

✨ Customers: a read-only GraphQL endpoint over the customer graph - #18771

Merged
kubestellar-prow[bot] merged 2 commits into
v5from
feat/customers-graphql
Nov 17, 2026
Merged

kubestellar-prow[bot] merged 2 commits into
v5from
feat/customers-graphql

Conversation

@clubanderson

Copy link
Copy Markdown
Member

PR 5 of the Customers series (RFC #18742, design in src/docs/design/customers.md). With this the first usable slice (PRs 0 to 5) is complete.

What is here

  • POST /api/graph: GraphQL over people, the artefacts they touched and the edges between them. me, person(id), people(tag, first, after), artefact(ref); Person.edges paged newest first; Artefact.people for the walk back. No mutations, no subscriptions.
  • pkg/customers/gql: the schema and thin resolvers. It is the only package that imports the GraphQL library.
  • pkg/customers: Service.Edges, ArtefactPeople, ArtefactVisible.
  • The profile's Activity is now a timeline read from the endpoint, grouped by what each entry points at, with Show more.
  • openapi, API reference (with the schema and two example queries), changelog, design doc.

Access

The GraphQL layer decides nothing. Every resolver calls customers.Service with the viewer of the request, the same service the REST routes use.

  • Owner and read-write: every customer.
  • Read-only: only their own profile, by any path. TestReadOnlyCannotReachAnotherPersonByAnyPath goes at another person by id, through the list (plain, filtered, with a cursor), through an artefact the two share, two hops out from the viewer's own edges, and through aliases and a fragment, and checks that nothing about the other person appears anywhere in any response.
  • Suggested people are never returned as a person.
  • An edge is shown only to a viewer who could open its artefact where it lives (a meeting is the owner's; Calendar and Inbox are owner and read-write).
  • satisfaction and notes are null without the full view.

The route is a POST that only reads, so the read role's write gate lets exactly POST /api/graph through (near-miss paths and methods are tested).

Limits

Depth 8, 8 KB of query text, pages of at most 100, 5,000 nodes and 5 seconds per query. Depth, length and selection count are the library's; the node budget is charged by the resolvers. Introspection is off: the standard introspection query is deeper than the depth limit anyway, and the schema is in the API reference.

Audit: customer_graph_query with the operation name (letters, digits and underscores only, bounded), node count and error count. Never the query text.

The library

github.com/graph-gophers/graphql-go v1.11.1, BSD-2-Clause, as planned. No fallback was needed.

go mod graph for it:

github.com/graph-gophers/graphql-go@v1.11.1 github.com/opentracing/opentracing-go@v1.2.0
github.com/graph-gophers/graphql-go@v1.11.1 go.opentelemetry.io/otel@v1.47.0
github.com/graph-gophers/graphql-go@v1.11.1 go.opentelemetry.io/otel/trace@v1.47.0
github.com/graph-gophers/graphql-go@v1.11.1 github.com/cespare/xxhash/v2@v2.3.0
github.com/graph-gophers/graphql-go@v1.11.1 github.com/go-logr/logr@v1.4.4
github.com/graph-gophers/graphql-go@v1.11.1 github.com/go-logr/stdr@v1.2.2
github.com/graph-gophers/graphql-go@v1.11.1 go.opentelemetry.io/auto/sdk@v1.2.1
github.com/graph-gophers/graphql-go@v1.11.1 go.opentelemetry.io/otel/log@v1.47.0
github.com/graph-gophers/graphql-go@v1.11.1 go.opentelemetry.io/otel/metric@v1.47.0

Hive already requires every OpenTelemetry module at exactly these versions. opentracing-go is imported only by the library's optional trace/opentracing package, which Hive does not import, so it does not enter the build. The whole change to the module files is one line in go.mod and the library's own two lines in go.sum.

NOTICE: I generated it with src/scripts/generate-notice.sh on macOS and committed only the new graphql-go entry, because a macOS run also renames the golang.org/x/sys entry to its darwin package path. If notice-drift disagrees with the placement I will take its artifact.

Refs #18742

🤖 Generated with Claude Code

…e profile timeline reads it

PR 5 of RFC #18742.

- pkg/customers/gql: the schema (no mutations, no subscriptions) and thin
  resolvers. Every access decision is made by customers.Service on the
  viewer of the request.
- pkg/customers: Service.Edges, ArtefactPeople and ArtefactVisible. Without
  the full view only the viewer's own profile is reachable, by any path;
  an edge is shown only to a viewer who could open its artefact.
- POST /api/graph behind the injected service; the read role may call it
  because it only reads. Limits: depth 8, 8 KB, page 100, 5,000 nodes, 5 s.
  Audited without the query text.
- The profile's Activity is a timeline read from the endpoint.
- New dependency github.com/graph-gophers/graphql-go v1.11.1 (BSD-2-Clause),
  imported only by pkg/customers/gql; NOTICE regenerated.

Refs #18742

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#18772 🐛 Activity monitor: one rule for the human-gate pill and its verbs; name the real blocker same files src/pkg/dashboard/static/index.html

@hivecommons-hive

hivecommons-hive Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

ℹ️ Sentinel: informational, author is trusted (owner), merge is not blocked. Head b5d2e7142500 matched:

  • sensitive_path: changes 1 sensitive path(s) (src/go.mod)

No sentinel-alert label was added. The finding is recorded in the dashboard Security tab and /api/sentinel; set sentinel.trusted_authors_block: true to block trusted authors too.

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • coverage

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

…budget at every resolver

The coverage gate holds pkg/customers/gql to 90%.

Refs #18742

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@github-actions

Copy link
Copy Markdown
Contributor

Mutation testing

gremlins found 8 surviving mutant(s) in changed files: the code ran under tests, but changing it did not fail any test.

File Line Mutation
src/pkg/customers/gql/engine.go 109 CONDITIONALS_BOUNDARY
src/pkg/customers/gql/resolvers.go 30 CONDITIONALS_BOUNDARY
src/pkg/customers/gql/resolvers.go 101 CONDITIONALS_BOUNDARY
src/pkg/customers/gql/resolvers.go 105 CONDITIONALS_BOUNDARY
src/pkg/customers/gql/resolvers.go 108 ARITHMETIC_BASE
src/pkg/customers/gql/resolvers.go 108 INVERT_NEGATIVES
src/pkg/customers/service.go 383 CONDITIONALS_BOUNDARY
src/pkg/customers/service.go 383 CONDITIONALS_BOUNDARY

2 mutant(s) in changed files are not reached by any test (NOT COVERED). A maintainer may apply the mutation/acknowledged label to accept this.

File Line Mutation
src/cmd/hive/customerswire.go 72 CONDITIONALS_NEGATION
src/pkg/customers/gql/engine.go 41 ARITHMETIC_BASE

ℹ️ 3 mutant(s) on added lines were SKIPPED because gremlins v0.6.0 only honours the first lines added lines of each default-context hunk, so non-contiguous edits in one hunk are partly missed. This does not affect the verdict.

File Line Mutation
src/pkg/dashboard/api_customers.go 146 CONDITIONALS_NEGATION
src/pkg/dashboard/api_customers.go 151 CONDITIONALS_NEGATION
src/pkg/dashboard/api_customers.go 151 CONDITIONALS_NEGATION

Verdict: lived (#17349).

@clubanderson clubanderson added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Nov 17, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow
kubestellar-prow Bot merged commit b6693c9 into v5 Nov 17, 2026
97 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/customers-graphql branch November 17, 2026 17:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant