diff --git a/NOTICE b/NOTICE index 49a8bdfea2..1fe523a90b 100644 --- a/NOTICE +++ b/NOTICE @@ -1830,6 +1830,38 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ----------------------------------------------------------------------------- +Package: github.com/graph-gophers/graphql-go +Version: v1.11.1 +License: BSD-2-Clause +Source: https://github.com/graph-gophers/graphql-go/blob/v1.11.1/LICENSE + +Copyright (c) 2016 Richard Musiol. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +----------------------------------------------------------------------------- + Package: github.com/grpc-ecosystem/grpc-gateway/v2 Version: v2.30.0 License: BSD-3-Clause diff --git a/changelog.d/added-18742-customers-graphql.md b/changelog.d/added-18742-customers-graphql.md new file mode 100644 index 0000000000..bef3c2f56f --- /dev/null +++ b/changelog.d/added-18742-customers-graphql.md @@ -0,0 +1 @@ +- **Customers: a read-only GraphQL endpoint over the customer graph (#18742).** `POST /api/graph` answers GraphQL queries over people, the artefacts they touched and the edges between them: `me`, `person(id)`, `people(tag, first, after)` and `artefact(ref)`, with `Person.edges` paged newest first and `Artefact.people` for the walk back. There are no mutations and no subscriptions, so any signed-in, named user may call it, and every field that returns a person checks the viewer: the owner and read-write users reach every customer, a read-only user reaches only their own profile by any path (by id, through the list, through a shared artefact, through aliases or fragments; tested), suggested people are never returned, and an edge is shown only to a viewer who could open its artefact where it lives. Limits per query: depth 8, 8 KB of query text, pages of at most 100, 5,000 nodes and 5 seconds; introspection is off and the schema is in `src/docs/api-reference/customers.md`. Each query is audited as `customer_graph_query` with the operation name, node count and error count, never the query text. A profile's **Activity** in the Customers section is now a timeline read from this endpoint, grouped by what each entry points at, with **Show more** for the next page. New dependency: `github.com/graph-gophers/graphql-go` v1.11.1 (BSD-2-Clause), imported only by `pkg/customers/gql`; it brought no other new module into the build. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 14373a6618..38476cfe84 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -2147,6 +2147,75 @@ } } }, + "/api/graph": { + "post": { + "tags": [ + "Customers" + ], + "summary": "Query the customer graph (GraphQL, read-only)", + "description": "Runs one GraphQL query against the customer graph: people, the artefacts they touched and the edges between them. The schema has no mutations and no subscriptions, so this POST changes nothing, and any signed-in, named user may call it, the read role included. Access is decided on the viewer: the verified owner and read-write users can reach every customer; a read-only user reaches only their own profile by any path (person by id answers null, people lists only them, and an artefact's people lists only them). Suggested people are never returned. An edge to an artefact the viewer may not open where it lives is left out. Limits: depth 8, 8 KB of query text, pages of at most 100, 5,000 nodes and 5 seconds per query; introspection is off (the schema is in src/docs/api-reference/customers.md). A query that fails still answers 200 with a GraphQL errors array. Audited as customer_graph_query with the operation name, node count and error count, never the query text.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "GraphQL query text, at most 8 KB" + }, + "operationName": { + "type": "string" + }, + "variables": { + "type": "object", + "description": "Query variables" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "GraphQL response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "description": "The selected fields" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "GraphQL error: message, locations, path" + } + } + } + } + } + } + }, + "400": { + "description": "Malformed body or no query" + }, + "403": { + "description": "Not signed in as a named user, or the owner role was not verified" + }, + "503": { + "description": "Customers are turned off on this hive, or the graph engine is not running" + } + } + } + }, "/api/meetings/schedule": { "get": { "tags": [ diff --git a/src/cmd/hive/customerswire.go b/src/cmd/hive/customerswire.go index f29a86be74..b2eb1bf86c 100644 --- a/src/cmd/hive/customerswire.go +++ b/src/cmd/hive/customerswire.go @@ -1,12 +1,14 @@ package main import ( + "context" "errors" "fmt" "log/slog" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/customers" + "github.com/hivecommons/hive/pkg/customers/gql" "github.com/hivecommons/hive/pkg/dashboard" ) @@ -24,6 +26,8 @@ const ( // pkg/customers; this adapter is the only place the two meet. type customersDashboard struct { svc *customers.Service + // graph is the read-only GraphQL engine; nil if it failed to start. + graph *gql.Engine } // wireCustomers opens the people store and the edge index when @@ -61,7 +65,15 @@ func wireCustomersAt(dataDir, graphDir string, resolvers customers.Resolvers, lo _ = index.Close() } } - return &customersDashboard{svc: customers.NewService(store, index, resolvers)}, stop + svc := customers.NewService(store, index, resolvers) + graph, err := gql.New(svc, gql.Limits{}) + if err != nil { + graph = nil + if logger != nil { + logger.Error("[customers] graph endpoint unavailable", "error", err) + } + } + return &customersDashboard{svc: svc, graph: graph}, stop } // customersError maps a store error onto the dashboard's sentinels, which @@ -139,3 +151,12 @@ func (c *customersDashboard) Accept(v dashboard.CustomersViewer, suggestionID st func (c *customersDashboard) Dismiss(v dashboard.CustomersViewer, suggestionID string) error { return customersError(c.svc.Dismiss(customersViewer(v), suggestionID)) } + +// Graph is POST /api/graph: one read-only GraphQL query as the viewer. +func (c *customersDashboard) Graph(ctx context.Context, v dashboard.CustomersViewer, req dashboard.CustomerGraphRequest) (dashboard.CustomerGraphResult, error) { + if c.graph == nil { + return dashboard.CustomerGraphResult{}, dashboard.ErrCustomerUnavailable + } + res := c.graph.Exec(ctx, customersViewer(v), req.Query, req.OperationName, req.Variables) + return dashboard.CustomerGraphResult{Body: res.Body, Nodes: res.Nodes, Errors: res.Errors}, nil +} diff --git a/src/cmd/hive/customerswire_test.go b/src/cmd/hive/customerswire_test.go index cb2e4d3a5f..3662461fb4 100644 --- a/src/cmd/hive/customerswire_test.go +++ b/src/cmd/hive/customerswire_test.go @@ -1,11 +1,13 @@ package main import ( + "context" "encoding/json" "errors" "fmt" "os" "path/filepath" + "strings" "testing" "github.com/hivecommons/hive/pkg/config" @@ -171,3 +173,47 @@ func TestCustomersAdapterRoleMatrix(t *testing.T) { t.Fatalf("Accept missing = %v", err) } } + +// TestCustomersAdapterGraph runs GraphQL through the adapter the dashboard +// calls: the viewer the handler built is the viewer the engine enforces. +func TestCustomersAdapterGraph(t *testing.T) { + c := wireTestCustomers(t) + owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true} + read := dashboard.CustomersViewer{User: "reed"} + ada, err := c.Add(owner, dashboard.CustomerAddRequest{Name: "Ada", Identities: []dashboard.CustomerIdentityInput{{Kind: "github", Value: "ada"}}}) + if err != nil { + t.Fatal(err) + } + query := dashboard.CustomerGraphRequest{ + Query: `query Who($id: ID!) { me { name me } person(id: $id) { name } people { nodes { name } } }`, + Variables: map[string]any{"id": ada.ID}, OperationName: "Who", + } + asOwner, err := c.Graph(context.Background(), owner, query) + if err != nil || asOwner.Errors != 0 || !strings.Contains(string(asOwner.Body), `"person":{"name":"Ada"}`) { + t.Fatalf("owner graph = %s, %+v, %v", asOwner.Body, asOwner, err) + } + asRead, err := c.Graph(context.Background(), read, query) + if err != nil || asRead.Errors != 0 { + t.Fatalf("read graph = %s, %v", asRead.Body, err) + } + body := string(asRead.Body) + if !strings.Contains(body, `"me":{"name":"reed","me":true}`) || !strings.Contains(body, `"person":null`) || strings.Contains(body, "Ada") || strings.Contains(body, "olivia") { + t.Fatalf("read graph leaks or lacks the viewer: %s", body) + } + if asRead.Nodes == 0 || asOwner.Nodes <= asRead.Nodes { + t.Fatalf("node counts: owner %d, read %d", asOwner.Nodes, asRead.Nodes) + } + // A mutation is refused by the schema. + bad, err := c.Graph(context.Background(), owner, dashboard.CustomerGraphRequest{Query: `mutation { forget(id: "` + ada.ID + `") }`}) + if err != nil || bad.Errors == 0 { + t.Fatalf("mutation = %s, %v", bad.Body, err) + } + if _, err := c.Get(owner, ada.ID); err != nil { + t.Fatalf("a refused mutation changed the store: %v", err) + } + // No engine: 503 to the caller, not a panic. + c.graph = nil + if _, err := c.Graph(context.Background(), owner, query); !errors.Is(err, dashboard.ErrCustomerUnavailable) { + t.Fatalf("Graph without an engine = %v", err) + } +} diff --git a/src/docs/api-reference.md b/src/docs/api-reference.md index 7fb6fe5a8f..abc38a4b06 100644 --- a/src/docs/api-reference.md +++ b/src/docs/api-reference.md @@ -23,7 +23,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | Inception | [`api-reference/inception.md`](api-reference/inception.md) | 14 | | Beads | [`api-reference/beads.md`](api-reference/beads.md) | 5 | | Sessions | [`api-reference/sessions.md`](api-reference/sessions.md) | 8 | -| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 7 | +| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 8 | | Dashboard miscellaneous | [`api-reference/dashboard-misc.md`](api-reference/dashboard-misc.md) | 56 | | Hub SaaS | [`api-reference/hub-saas.md`](api-reference/hub-saas.md) | 102 | | Hub server | [`api-reference/hub-server.md`](api-reference/hub-server.md) | 46 | @@ -82,7 +82,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh ## Customers -7 routes — see [api-reference/customers.md](api-reference/customers.md). +8 routes — see [api-reference/customers.md](api-reference/customers.md). ## Dashboard miscellaneous diff --git a/src/docs/api-reference/customers.md b/src/docs/api-reference/customers.md index d369847c4e..f1e85e0c7a 100644 --- a/src/docs/api-reference/customers.md +++ b/src/docs/api-reference/customers.md @@ -12,10 +12,86 @@ The rules are enforced twice: by the handlers and again by the store's service o | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:128` | -| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:129` | -| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:130` | -| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:131` | -| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:132` | -| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:133` | -| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:134` | +| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:132` | +| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:133` | +| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:134` | +| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:135` | +| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:136` | +| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:137` | +| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:138` | +| `POST` | `/api/graph` | Signed-in user | The customer graph over GraphQL, read-only (no mutations, so a read-only user may call it): `{query, operationName?, variables?}`, answered with a GraphQL `{data, errors}` document. Access follows the viewer exactly as above; see [the customer graph](#the-customer-graph). Audited as `customer_graph_query` with the operation name, node count and error count, never the query text | `pkg/dashboard/api_graph.go:47` | + +## The customer graph + +`POST /api/graph` answers GraphQL queries over people, the artefacts they touched and the edges between them. An artefact is a reference (`gh:issue:org/repo#12`, `meeting:`, `inbox:email:`, `event:`), never content. + +Rules that hold for every query: + +- It is **read-only**. There is no `Mutation` and no `Subscription` type. Changes go through the REST routes above, which carry the role checks and the audit lines. +- **Every field that returns a person checks the viewer.** With the full view you can reach every customer. Without it you reach only yourself: `person(id)` answers `null` for anyone else (the same answer as an id that does not exist), `people` lists only you, and an artefact's `people` lists only you. +- **Suggested people are never returned** as a person. +- **An edge is shown only if you could open its artefact where it lives.** A meeting is the owner's to see; Calendar events and Inbox items are for the owner and read-write users. +- `satisfaction` and `notes` are `null` without the full view. + +Limits per query: depth 8, 8 KB of query text, pages of at most 100 (25 when `first` is not given), 5,000 people, edges and artefacts in total, and 5 seconds. Introspection is off; this is the schema: + +```graphql +type Query { + me: Person! + person(id: ID!): Person + people(tag: String, first: Int, after: String): PersonConnection! + artefact(ref: String!): Artefact +} + +type Person { + id: ID! + name: String! + origin: String! # hive_user, manual or accepted + me: Boolean! + tags: [Tag!]! + identities: [Identity!]! + goals: [Goal!]! + satisfaction: Satisfaction # null without the full view + notes: String # null without the full view + counts: [Count!]! + edges(predicate: String, first: Int, after: String): EdgeConnection! +} + +type PersonConnection { nodes: [Person!]! next: String } +type Tag { name: String! on: Boolean! source: String! rule: String } +type Identity { kind: String! value: String! source: String manual: Boolean! claimed: Boolean! } +type Goal { id: ID! text: String! state: String! source: String! evidence: [String!]! } +type Satisfaction { level: String! source: String evidence: [String!]! suggestedLevel: String suggestedEvidence: [String!]! } +type Count { predicate: String! count: Int! } +type Edge { predicate: String! at: String! source: String artefact: Artefact! } +type EdgeConnection { nodes: [Edge!]! next: String } +type Artefact { ref: String! kind: String! people(first: Int): [ArtefactPerson!]! } +type ArtefactPerson { predicate: String! person: Person! } +``` + +Your own profile: + +```sh +curl -s -X POST "$HIVE/api/graph" -H 'Content-Type: application/json' \ + -d '{"query":"{ me { name tags { name on source } goals { text state } } }"}' +``` + +Two hops, from a person to the artefacts they touched to everyone else on them: + +```graphql +query Around($id: ID!) { + person(id: $id) { + name + edges(first: 20) { + nodes { + predicate + at + artefact { ref people { predicate person { name } } } + } + next + } + } +} +``` + +Page with `after`: pass the `next` value of the previous page; `next` is `null` on the last page. diff --git a/src/docs/design/customers.md b/src/docs/design/customers.md index 2ff5018f76..6d70a632b5 100644 --- a/src/docs/design/customers.md +++ b/src/docs/design/customers.md @@ -340,11 +340,28 @@ forget, the role checks and retention pruning are merged and tested. - Suggested people are never returned as a person. - Each query is audited (viewer, operation name, node count), not its text. -Library: `github.com/graph-gophers/graphql-go`, schema-first, chosen for its -small dependency list and built-in depth limit. The fallback, if it cannot -pass the vulnerability, NOTICE or licence checks, is -`github.com/graphql-go/graphql` with a hand-written depth and size check. The -PR that adds the endpoint records which was used and the evidence. +Library: `github.com/graph-gophers/graphql-go` v1.11.1 (BSD-2-Clause), +schema-first, imported only by `src/pkg/customers/gql`. The decision and the +evidence: + +- `go mod graph` shows it requires `opentracing-go`, `go.opentelemetry.io/otel` + and `otel/trace`, plus their indirect modules. Hive already requires the + OpenTelemetry modules at the same version (v1.47.0), and `opentracing-go` is + imported only by the library's optional `trace/opentracing` package, which + Hive does not import. Adding the library added one line to `go.mod` and its + own two lines to `go.sum`; no other module entered the build. +- It has the limits this endpoint needs built in: `MaxDepth`, + `MaxQueryLength`, `MaxSelections` and an introspection switch. +- The fallback, `github.com/graphql-go/graphql` with a hand-written depth and + size check, was not needed. + +Introspection is off: the standard introspection query is deeper than the +depth limit anyway, and the schema is published in +[the API reference](../api-reference/customers.md#the-customer-graph). The +node limit is enforced by the resolvers, which charge every person, edge and +artefact they materialise to a per-query budget. Access is not decided in the +GraphQL layer at all: every resolver calls the customers service with the +viewer of the request, the same service the REST routes use. ## 12. Agents and privacy guard rails diff --git a/src/go.mod b/src/go.mod index 9702ab1ff1..369c499bda 100644 --- a/src/go.mod +++ b/src/go.mod @@ -19,6 +19,7 @@ require ( github.com/google/go-github/v72 v72.0.0 github.com/google/uuid v1.6.0 github.com/gorilla/websocket v1.5.3 + github.com/graph-gophers/graphql-go v1.11.1 github.com/ledongthuc/pdf v0.0.0-20250511090121-5959a4027728 github.com/muesli/termenv v0.16.0 github.com/robfig/cron/v3 v3.0.1 diff --git a/src/go.sum b/src/go.sum index baef1bec0b..d403e692b3 100644 --- a/src/go.sum +++ b/src/go.sum @@ -75,6 +75,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg= github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE= +github.com/graph-gophers/graphql-go v1.11.1 h1:PgW3mnUYcdZV0tw9Z/tvoffTpD+8wQ88PtMoAgbWPLs= +github.com/graph-gophers/graphql-go v1.11.1/go.mod h1:j14c6XnomYqrHWyBbDNoqWnl4NZ4deiZ9TGZ3fuvJx8= github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 h1:/Tnpcb2E0Pz/tN9s3bfEY2Q8ePCEX9iuS+cneUwncnw= github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0/go.mod h1:zOBXOsUaBSjKgmH4OGzV1esUpR3oUSCPYVd2cUBjKYY= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= diff --git a/src/pkg/customers/gql/engine.go b/src/pkg/customers/gql/engine.go new file mode 100644 index 0000000000..67ea3c74b2 --- /dev/null +++ b/src/pkg/customers/gql/engine.go @@ -0,0 +1,137 @@ +// Package gql serves the customer graph over GraphQL, read-only. It is the +// only package that imports the GraphQL library. Every access decision is +// made by customers.Service on the viewer of the request; the resolvers +// here only shape what the service returns. +package gql + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "sync/atomic" + "time" + + graphql "github.com/graph-gophers/graphql-go" + + "github.com/hivecommons/hive/pkg/customers" +) + +// Limits bound one query. +type Limits struct { + // MaxDepth is the deepest field nesting a query may use. + MaxDepth int + // MaxQueryBytes is the longest query text accepted. + MaxQueryBytes int + // MaxPage is the largest page a list field returns. + MaxPage int + // MaxNodes is how many people, edges and artefacts one query may + // materialise in total. + MaxNodes int + // Timeout bounds the execution of one query. + Timeout time.Duration +} + +// DefaultLimits are the limits of POST /api/graph. +var DefaultLimits = Limits{ + MaxDepth: 8, + MaxQueryBytes: 8 << 10, + MaxPage: 100, + MaxNodes: 5000, + Timeout: 5 * time.Second, +} + +// defaultPage is the page size when a query does not ask for one. +const defaultPage = 25 + +// maxSelections bounds how far fragment spreads may expand one operation. +const maxSelections = 2000 + +// ErrNodeLimit is the resolver error once a query has materialised more +// nodes than Limits.MaxNodes. +var ErrNodeLimit = errors.New("the query touches too many nodes; narrow it or page through it") + +// Engine executes queries against the customer graph. +type Engine struct { + schema *graphql.Schema + svc *customers.Service + limits Limits +} + +// New builds the engine. The zero Limits selects DefaultLimits. +func New(svc *customers.Service, limits Limits) (*Engine, error) { + if svc == nil { + return nil, errors.New("gql: a customers service is required") + } + if limits == (Limits{}) { + limits = DefaultLimits + } + e := &Engine{svc: svc, limits: limits} + schema, err := graphql.ParseSchema(Schema, &query{e: e}, + graphql.MaxDepth(limits.MaxDepth), + graphql.MaxQueryLength(limits.MaxQueryBytes), + graphql.MaxSelections(maxSelections), + // The schema is published in the docs. Introspection is off so the + // endpoint answers only what the limits above were sized for. + graphql.RestrictIntrospection(func(context.Context) bool { return false }), + ) + if err != nil { + return nil, fmt.Errorf("gql: parsing schema: %w", err) + } + e.schema = schema + return e, nil +} + +// Limits reports the engine's limits. +func (e *Engine) Limits() Limits { return e.limits } + +// Result is the outcome of one query. +type Result struct { + // Body is the GraphQL response, JSON-encoded: {"data": ..., "errors": ...}. + Body []byte + // Nodes is how many people, edges and artefacts the query materialised. + Nodes int + // Errors is the number of errors in the response. + Errors int +} + +// request is the per-query state the resolvers share. +type request struct { + viewer customers.Viewer + nodes atomic.Int64 + limit int64 +} + +type requestKey struct{} + +// take charges n nodes to the query and fails once the budget is spent. +func (r *request) take(n int) error { + if r.nodes.Add(int64(n)) > r.limit { + return ErrNodeLimit + } + return nil +} + +func requestFrom(ctx context.Context) *request { + r, _ := ctx.Value(requestKey{}).(*request) + if r == nil { + // No viewer: nothing is visible and nothing may be materialised. + return &request{} + } + return r +} + +// Exec runs one query as the viewer. It never returns an error: a failure +// is a GraphQL error in the response body. +func (e *Engine) Exec(ctx context.Context, viewer customers.Viewer, queryText, operation string, variables map[string]any) Result { + req := &request{viewer: viewer, limit: int64(e.limits.MaxNodes)} + ctx, cancel := context.WithTimeout(context.WithValue(ctx, requestKey{}, req), e.limits.Timeout) + defer cancel() + resp := e.schema.Exec(ctx, queryText, operation, variables) + body, err := json.Marshal(resp) + if err != nil { + body = []byte(`{"errors":[{"message":"the response could not be encoded"}]}`) + return Result{Body: body, Nodes: int(req.nodes.Load()), Errors: 1} + } + return Result{Body: body, Nodes: int(req.nodes.Load()), Errors: len(resp.Errors)} +} diff --git a/src/pkg/customers/gql/gql_test.go b/src/pkg/customers/gql/gql_test.go new file mode 100644 index 0000000000..62ef591895 --- /dev/null +++ b/src/pkg/customers/gql/gql_test.go @@ -0,0 +1,435 @@ +package gql + +import ( + "context" + "encoding/json" + "path/filepath" + "strings" + "testing" + "time" + + graphql "github.com/graph-gophers/graphql-go" + + "github.com/hivecommons/hive/pkg/customers" +) + +var ( + ownerV = customers.Viewer{User: "olivia", Full: true, Owner: true} + rwV = customers.Viewer{User: "rita", Full: true} + readV = customers.Viewer{User: "reed"} +) + +// ownersOnly lets only the owner see the artefacts in it. +type ownersOnly map[string]bool + +func (o ownersOnly) Exists(string) bool { return true } + +func (o ownersOnly) Visible(ref string, v customers.Viewer) bool { return !o[ref] || v.Owner } + +type fixture struct { + svc *customers.Service + engine *Engine + reed customers.PersonView + ada customers.PersonView + private string + shared string +} + +func newFixture(t *testing.T, limits Limits) fixture { + t.Helper() + dir := t.TempDir() + store, err := customers.Open(filepath.Join(dir, "customers"), nil) + if err != nil { + t.Fatal(err) + } + index, err := customers.OpenIndex(filepath.Join(dir, "graph")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = index.Close() }) + f := fixture{private: customers.MeetingRef("board"), shared: customers.IssueRef("o/r", 1)} + f.svc = customers.NewService(store, index, customers.Resolvers{customers.RefMeeting: ownersOnly{f.private: true}}) + if f.reed, err = f.svc.Get(readV, customers.MeID); err != nil { + t.Fatal(err) + } + if f.ada, err = f.svc.Add(ownerV, "Ada", []customers.Identity{{Kind: customers.KindGitHub, Value: "ada"}, {Kind: customers.KindEmail, Value: "ada@example.com"}}); err != nil { + t.Fatal(err) + } + for _, e := range []customers.Edit{ + {Op: customers.OpTag, Tag: customers.TagStakeholder, State: customers.TagOn}, + {Op: customers.OpGoalAdd, Text: "Get exports working"}, + {Op: customers.OpSatisfactionSet, Level: string(customers.LevelAtRisk)}, + {Op: customers.OpNotes, Notes: "private note about Ada"}, + } { + if _, err := f.svc.Edit(ownerV, f.ada.ID, e); err != nil { + t.Fatalf("edit %s: %v", e.Op, err) + } + } + at := time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC) + if _, err := index.Put([]customers.Edge{ + {Person: f.reed.ID, Predicate: customers.PredReported, Artefact: f.shared, Via: "hive_user:reed", Source: "github_poll", At: at}, + {Person: f.reed.ID, Predicate: customers.PredAttended, Artefact: f.private, Via: "hive_user:reed", Source: "meetings", At: at.Add(time.Hour)}, + {Person: f.ada.ID, Predicate: customers.PredAssigned, Artefact: f.shared, Via: "github:ada", Source: "github_poll", At: at.Add(2 * time.Hour)}, + {Person: f.ada.ID, Predicate: customers.PredAttended, Artefact: f.private, Via: "github:ada", Source: "meetings", At: at.Add(3 * time.Hour)}, + }); err != nil { + t.Fatal(err) + } + if f.engine, err = New(f.svc, limits); err != nil { + t.Fatalf("New: %v", err) + } + return f +} + +type response struct { + Data map[string]json.RawMessage `json:"data"` + Errors []struct { + Message string `json:"message"` + } `json:"errors"` +} + +func exec(t *testing.T, f fixture, v customers.Viewer, query string, vars map[string]any) (response, Result) { + t.Helper() + res := f.engine.Exec(context.Background(), v, query, "", vars) + var out response + if err := json.Unmarshal(res.Body, &out); err != nil { + t.Fatalf("response is not JSON: %v\n%s", err, res.Body) + } + return out, res +} + +func mustOK(t *testing.T, f fixture, v customers.Viewer, query string, vars map[string]any) string { + t.Helper() + out, res := exec(t, f, v, query, vars) + if len(out.Errors) != 0 { + t.Fatalf("query failed: %+v\n%s", out.Errors, query) + } + return string(res.Body) +} + +func TestSchemaParsesAndIsReadOnly(t *testing.T) { + f := newFixture(t, Limits{}) + if f.engine.Limits() != DefaultLimits { + t.Fatalf("zero limits must select the defaults: %+v", f.engine.Limits()) + } + if strings.Contains(Schema, "type Mutation") || strings.Contains(Schema, "mutation:") || strings.Contains(Schema, "subscription:") { + t.Fatal("the customer graph must have no mutations and no subscriptions") + } + out, _ := exec(t, f, ownerV, `mutation { forget(id: "x") }`, nil) + if len(out.Errors) == 0 { + t.Fatal("a mutation was accepted") + } + out, _ = exec(t, f, ownerV, `{ __schema { types { name } } }`, nil) + if len(out.Errors) == 0 && strings.Contains(string(out.Data["__schema"]), "Person") { + t.Fatal("introspection is on") + } + if _, err := New(nil, Limits{}); err == nil { + t.Fatal("New without a service must fail") + } +} + +func TestMeForEveryRole(t *testing.T) { + f := newFixture(t, Limits{}) + for _, v := range []customers.Viewer{ownerV, rwV, readV} { + body := mustOK(t, f, v, `{ me { id name origin me identities { kind value claimed } tags { name on source } goals { id text state source evidence } counts { predicate count } } }`, nil) + if !strings.Contains(body, `"me":true`) || !strings.Contains(body, `"value":"`+v.User+`"`) || !strings.Contains(body, `"origin":"hive_user"`) { + t.Fatalf("%s: me = %s", v.User, body) + } + } + out, _ := exec(t, f, customers.Viewer{}, `{ me { id } }`, nil) + if len(out.Errors) == 0 { + t.Fatal("a viewer with no name got a profile") + } +} + +func TestFullViewReadsAPersonAndWalksTwoHops(t *testing.T) { + f := newFixture(t, Limits{}) + vars := map[string]any{"id": f.ada.ID} + body := mustOK(t, f, ownerV, `query($id: ID!) { person(id: $id) { name me notes satisfaction { level source evidence suggestedLevel suggestedEvidence } + tags { name on source rule } identities { kind value source manual claimed } goals { text state source } + counts { predicate count } edges(first: 10) { nodes { predicate at source artefact { ref kind } } next } } }`, vars) + for _, want := range []string{ + `"name":"Ada"`, `"me":false`, `"notes":"private note about Ada"`, `"level":"at_risk"`, + `"name":"stakeholder","on":true,"source":"manual"`, `"value":"ada@example.com"`, `"text":"Get exports working","state":"confirmed","source":"manual"`, + `"predicate":"assigned","count":1`, `"ref":"gh:issue:o/r#1","kind":"gh"`, `"ref":"meeting:board","kind":"meeting"`, `"at":"2026-11-01T03:00:00Z"`, `"next":null`, + } { + if !strings.Contains(body, want) { + t.Errorf("owner person query missing %s in %s", want, body) + } + } + // Two hops: Ada -> the issue -> everyone on it. + body = mustOK(t, f, ownerV, `query($id: ID!) { person(id: $id) { edges(predicate: "assigned") { nodes { artefact { ref people { predicate person { name me } } } } } } }`, vars) + if !strings.Contains(body, `"predicate":"reported","person":{"name":"reed","me":false}`) || !strings.Contains(body, `"predicate":"assigned","person":{"name":"Ada","me":false}`) { + t.Fatalf("two-hop walk = %s", body) + } + // Read-write sees Ada but not the artefact only the owner may open. + body = mustOK(t, f, rwV, `query($id: ID!) { person(id: $id) { name notes edges { nodes { artefact { ref } } } } }`, vars) + if !strings.Contains(body, `"name":"Ada"`) || strings.Contains(body, "meeting:board") { + t.Fatalf("read-write person query = %s", body) + } + if got := mustOK(t, f, rwV, `{ artefact(ref: "meeting:board") { ref } }`, nil); !strings.Contains(got, `"artefact":null`) { + t.Fatalf("an artefact the viewer may not see = %s", got) + } + // people: every customer, filtered by tag, paged. + body = mustOK(t, f, ownerV, `{ people(first: 1) { nodes { name } next } }`, nil) + if !strings.Contains(body, `"next":"1"`) { + t.Fatalf("first page = %s", body) + } + body = mustOK(t, f, ownerV, `{ people(tag: "Stakeholder") { nodes { name } next } }`, nil) + if !strings.Contains(body, `"nodes":[{"name":"Ada"}]`) || !strings.Contains(body, `"next":null`) { + t.Fatalf("tag filter = %s", body) + } + if out, _ := exec(t, f, ownerV, `{ people(after: "x") { nodes { name } } }`, nil); len(out.Errors) == 0 { + t.Fatal("a garbage cursor was accepted") + } + if got := mustOK(t, f, ownerV, `{ person(id: "p_doesnotexist") { name } }`, nil); !strings.Contains(got, `"person":null`) { + t.Fatalf("missing person = %s", got) + } +} + +// TestReadOnlyCannotReachAnotherPersonByAnyPath walks every field that can +// return a person as a read-only user. The only person that ever comes back +// is the viewer, and nothing about Ada appears anywhere in any response. +func TestReadOnlyCannotReachAnotherPersonByAnyPath(t *testing.T) { + f := newFixture(t, Limits{}) + vars := map[string]any{"id": f.ada.ID} + person := `id name origin me notes satisfaction { level } tags { name } identities { kind value } goals { text } counts { predicate count }` + short := `id name origin me notes` + queries := []string{ + // Directly, by id. + `query($id: ID!) { person(id: $id) { ` + person + ` edges { nodes { artefact { ref people { person { ` + short + ` } } } } } } }`, + // Through the list, with and without a filter and a cursor. + `{ people { nodes { ` + person + ` } next } }`, + `{ people(tag: "stakeholder") { nodes { ` + person + ` } next } }`, + `{ people(first: 100, after: "0") { nodes { ` + person + ` } next } }`, + // Through an artefact they share with Ada. + `{ artefact(ref: "gh:issue:o/r#1") { ref people { predicate person { ` + person + ` edges { nodes { artefact { ref } } } } } } }`, + // Through their own edges, two hops out. + `{ me { ` + person + ` edges { nodes { predicate artefact { ref people { predicate person { ` + short + ` } } } } } } }`, + // Aliases and fragments do not change who is asking. + `query($id: ID!) { a: person(id: $id) { ...P } b: me { ...P } } fragment P on Person { ` + person + ` }`, + } + for _, q := range queries { + out, res := exec(t, f, readV, q, vars) + if len(out.Errors) != 0 { + t.Fatalf("query errored (it should answer with nulls and the viewer only): %+v\n%s", out.Errors, q) + } + body := string(res.Body) + for _, leak := range []string{f.ada.ID, "Ada", "ada@example.com", `"ada"`, "private note", "at_risk", "Get exports working", "stakeholder", "meeting:board", "olivia", "rita"} { + if strings.Contains(body, leak) { + t.Fatalf("read-only response leaks %q:\n%s\n%s", leak, q, body) + } + } + } + // What a read-only user does get: themselves, and their own visible edge. + body := mustOK(t, f, readV, `{ me { name me notes satisfaction { level } edges { nodes { predicate artefact { ref people { person { name me } } } } } } }`, nil) + for _, want := range []string{`"name":"reed"`, `"me":true`, `"notes":null`, `"satisfaction":null`, `"ref":"gh:issue:o/r#1"`, `"people":[{"person":{"name":"reed","me":true}}]`} { + if !strings.Contains(body, want) { + t.Errorf("read-only me query missing %s in %s", want, body) + } + } + if got := mustOK(t, f, readV, `query($id: ID!) { person(id: $id) { name } }`, vars); !strings.Contains(got, `"person":null`) { + t.Fatalf("read-only person(ada) = %s", got) + } + // Their own id works as well as "me". + if got := mustOK(t, f, readV, `query($id: ID!) { person(id: $id) { name me } }`, map[string]any{"id": f.reed.ID}); !strings.Contains(got, `"me":true`) { + t.Fatalf("read-only person(self) = %s", got) + } +} + +func TestSuggestedPeopleAreNeverReturned(t *testing.T) { + f := newFixture(t, Limits{}) + if _, err := f.svc.Store().Observe([]customers.Observation{{Kind: customers.KindGitHub, Value: "stranger", Predicate: customers.PredReported, Artefact: f.shared}}); err != nil { + t.Fatal(err) + } + sid := f.svc.Store().Suggestions()[0].ID + for _, q := range []string{ + `{ people(first: 100) { nodes { id name identities { value } } } }`, + `{ artefact(ref: "gh:issue:o/r#1") { people { person { id name identities { value } } } } }`, + `{ person(id: "` + sid + `") { id name } }`, + } { + body := mustOK(t, f, ownerV, q, nil) + if strings.Contains(body, "stranger") || strings.Contains(body, sid+`","name"`) { + t.Fatalf("a suggested person was returned:\n%s\n%s", q, body) + } + } +} + +func TestLimits(t *testing.T) { + f := newFixture(t, Limits{MaxDepth: 4, MaxQueryBytes: 200, MaxPage: 2, MaxNodes: 3, Timeout: time.Second}) + + // Depth. + out, _ := exec(t, f, ownerV, `{ me { edges { nodes { artefact { people { person { name } } } } } } }`, nil) + if len(out.Errors) == 0 { + t.Fatal("an over-deep query was accepted") + } + // Size. + out, _ = exec(t, f, ownerV, `{ me { name } } #`+strings.Repeat("x", 300), nil) + if len(out.Errors) == 0 { + t.Fatal("an over-long query was accepted") + } + // Page size is clamped, not refused. + body := mustOK(t, f, ownerV, `{ people(first: 100) { nodes { name } next } }`, nil) + if strings.Count(body, `"name"`) != 2 || !strings.Contains(body, `"next":"2"`) { + t.Fatalf("page clamp = %s", body) + } + // Node budget: three people fit, their edges do not. + tight := newFixture(t, Limits{MaxDepth: 8, MaxQueryBytes: 1000, MaxPage: 10, MaxNodes: 3, Timeout: time.Second}) + out, res := exec(t, tight, ownerV, `{ people { nodes { name edges { nodes { predicate } } } } }`, nil) + if len(out.Errors) == 0 || !strings.Contains(out.Errors[0].Message, "too many nodes") { + t.Fatalf("node budget not enforced: %+v (%d nodes)", out.Errors, res.Nodes) + } + if res.Errors == 0 { + t.Fatal("Result.Errors must count the errors") + } + // A small query stays within it and reports what it touched. + if _, res := exec(t, f, ownerV, `{ me { name } }`, nil); res.Nodes != 1 || res.Errors != 0 { + t.Fatalf("Result = %+v", res) + } + + // Timeout: a query that cannot finish in time is cut off. + slow := newFixture(t, Limits{MaxDepth: 8, MaxQueryBytes: 1000, MaxPage: 10, MaxNodes: 100, Timeout: time.Nanosecond}) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + res = slow.engine.Exec(ctx, ownerV, `{ me { name } }`, "", nil) + if len(res.Body) == 0 { + t.Fatal("a cancelled query must still answer") + } +} + +func withViewer(v customers.Viewer, budget int64) context.Context { + return context.WithValue(context.Background(), requestKey{}, &request{viewer: v, limit: budget}) +} + +func TestPageAndHelpers(t *testing.T) { + f := newFixture(t, Limits{MaxDepth: 8, MaxQueryBytes: 1000, MaxPage: 10, MaxNodes: 100, Timeout: time.Second}) + n := func(v int32) *int32 { return &v } + for _, tc := range []struct { + first *int32 + want int + }{{nil, 10}, {n(0), 10}, {n(-4), 10}, {n(3), 3}, {n(500), 10}} { + if got := f.engine.page(tc.first); got != tc.want { + t.Errorf("page(%v) = %d, want %d", tc.first, got, tc.want) + } + } + wide := newFixture(t, Limits{}) + if got := wide.engine.page(nil); got != defaultPage { + t.Fatalf("default page = %d", got) + } + if optional("") != nil || *optional("x") != "x" { + t.Fatal("optional") + } + if got := list(nil); got == nil || len(got) != 0 { + t.Fatal("list(nil) must be an empty, non-nil list") + } + if got := (&personConnection{}).Nodes(); got == nil || len(got) != 0 { + t.Fatal("an empty person page must be an empty list") + } + if got := (&edgeConnection{}).Nodes(); got == nil || len(got) != 0 { + t.Fatal("an empty edge page must be an empty list") + } +} + +// A resolver reached without a request (no viewer) sees nothing. +func TestResolversWithoutAViewer(t *testing.T) { + f := newFixture(t, Limits{}) + q := &query{e: f.engine} + if _, err := q.Me(context.Background()); err == nil { + t.Fatal("Me without a viewer must fail") + } + if p, err := q.Person(context.Background(), struct{ ID graphql.ID }{ID: graphql.ID(f.ada.ID)}); err != nil || p != nil { + t.Fatalf("Person without a viewer = %v, %v; want null", p, err) + } + if a, err := q.Artefact(context.Background(), struct{ Ref string }{Ref: f.shared}); err != nil || a != nil { + t.Fatalf("Artefact without a viewer = %v, %v; want null", a, err) + } + if _, err := q.People(context.Background(), struct { + Tag *string + First *int32 + After *string + }{}); err == nil { + t.Fatal("People without a viewer must fail") + } +} + +// Even handed a person the viewer may not see, the edge and artefact +// resolvers ask the service again and come back empty. +func TestResolversRecheckTheViewer(t *testing.T) { + f := newFixture(t, Limits{}) + ada := &personResolver{e: f.engine, p: f.ada} + conn, err := ada.Edges(withViewer(readV, 100), struct { + Predicate *string + First *int32 + After *string + }{}) + if err != nil || len(conn.Nodes()) != 0 || conn.Next() != nil { + t.Fatalf("read-only Edges on another person = %+v, %v; want empty", conn, err) + } + hidden := &artefactResolver{e: f.engine, ref: f.private} + people, err := hidden.People(withViewer(rwV, 100), struct{ First *int32 }{}) + if err != nil || len(people) != 0 { + t.Fatalf("People on an artefact the viewer may not see = %v, %v; want empty", people, err) + } + if hidden.Kind() != customers.RefMeeting || hidden.Ref() != f.private { + t.Fatal("artefact fields") + } +} + +func TestSuggestedSatisfactionAndCursors(t *testing.T) { + f := newFixture(t, Limits{}) + if _, err := f.svc.Store().SuggestSatisfaction(f.ada.ID, customers.LevelNeutral, []string{f.shared}); err != nil { + t.Fatal(err) + } + body := mustOK(t, f, ownerV, `query($id: ID!) { person(id: $id) { satisfaction { level suggestedLevel suggestedEvidence } } }`, map[string]any{"id": f.ada.ID}) + if !strings.Contains(body, `"suggestedLevel":"neutral","suggestedEvidence":["gh:issue:o/r#1"]`) { + t.Fatalf("suggestion = %s", body) + } + // The owner's own profile has no suggestion: an empty list, not null. + body = mustOK(t, f, ownerV, `{ me { satisfaction { level suggestedLevel suggestedEvidence } } }`, nil) + if !strings.Contains(body, `"level":"unknown","suggestedLevel":null,"suggestedEvidence":[]`) { + t.Fatalf("no suggestion = %s", body) + } + // A cursor past the end is an empty last page; a blank tag is no filter. + body = mustOK(t, f, ownerV, `{ people(after: "999", tag: " ") { nodes { name } next } }`, nil) + if !strings.Contains(body, `"nodes":[],"next":null`) { + t.Fatalf("cursor past the end = %s", body) + } + if out, _ := exec(t, f, ownerV, `{ people(after: "-1") { nodes { name } } }`, nil); len(out.Errors) == 0 { + t.Fatal("a negative cursor was accepted") + } + // A malformed edge cursor is an error, not a silent first page. + if out, _ := exec(t, f, ownerV, `{ me { edges(after: "zz") { nodes { predicate } } } }`, nil); len(out.Errors) == 0 { + t.Fatal("a malformed edge cursor was accepted") + } + // Edge pages carry a cursor while there is more. + body = mustOK(t, f, ownerV, `query($id: ID!) { person(id: $id) { edges(first: 1) { nodes { predicate } next } } }`, map[string]any{"id": f.ada.ID}) + if strings.Contains(body, `"next":null`) || !strings.Contains(body, `"predicate":"attended"`) { + t.Fatalf("first edge page = %s", body) + } +} + +// TestNodeBudgetAtEveryResolver: each resolver that materialises a node +// charges the budget and stops when it is spent. +func TestNodeBudgetAtEveryResolver(t *testing.T) { + none := newFixture(t, Limits{MaxDepth: 8, MaxQueryBytes: 1000, MaxPage: 10, MaxNodes: 0, Timeout: time.Second}) + for _, q := range []string{ + `{ me { name } }`, + `query($id: ID!) { person(id: $id) { name } }`, + `{ people { nodes { name } } }`, + `{ artefact(ref: "gh:issue:o/r#1") { ref } }`, + } { + out, res := exec(t, none, ownerV, q, map[string]any{"id": none.ada.ID}) + if len(out.Errors) == 0 || !strings.Contains(out.Errors[0].Message, "too many nodes") || res.Errors == 0 { + t.Errorf("no budget, %s: %+v", q, out.Errors) + } + } + one := newFixture(t, Limits{MaxDepth: 8, MaxQueryBytes: 1000, MaxPage: 10, MaxNodes: 1, Timeout: time.Second}) + for _, q := range []string{ + `query($id: ID!) { person(id: $id) { edges { nodes { predicate } } } }`, + `{ artefact(ref: "gh:issue:o/r#1") { people { predicate } } }`, + } { + out, _ := exec(t, one, ownerV, q, map[string]any{"id": one.ada.ID}) + if len(out.Errors) == 0 || !strings.Contains(out.Errors[0].Message, "too many nodes") { + t.Errorf("budget of one, %s: %+v", q, out.Errors) + } + } +} diff --git a/src/pkg/customers/gql/resolvers.go b/src/pkg/customers/gql/resolvers.go new file mode 100644 index 0000000000..cfc238d44d --- /dev/null +++ b/src/pkg/customers/gql/resolvers.go @@ -0,0 +1,378 @@ +package gql + +import ( + "context" + "errors" + "sort" + "strconv" + "strings" + "time" + + graphql "github.com/graph-gophers/graphql-go" + + "github.com/hivecommons/hive/pkg/customers" +) + +// query is the root resolver. +type query struct { + e *Engine +} + +// page clamps a requested page size to the engine's limits. +func (e *Engine) page(first *int32) int { + n := defaultPage + if first != nil { + n = int(*first) + } + if n <= 0 { + n = defaultPage + } + if n > e.limits.MaxPage { + n = e.limits.MaxPage + } + return n +} + +// hidden reports whether err means "not there for this viewer", which a +// nullable field answers with null rather than an error. +func hidden(err error) bool { + return errors.Is(err, customers.ErrNotFound) || errors.Is(err, customers.ErrForbidden) +} + +// Me is the viewer's own profile. +func (q *query) Me(ctx context.Context) (*personResolver, error) { + req := requestFrom(ctx) + p, err := q.e.svc.Get(req.viewer, customers.MeID) + if err != nil { + return nil, err + } + if err := req.take(1); err != nil { + return nil, err + } + return &personResolver{e: q.e, p: p}, nil +} + +// Person is one profile, or null. +func (q *query) Person(ctx context.Context, args struct{ ID graphql.ID }) (*personResolver, error) { + req := requestFrom(ctx) + p, err := q.e.svc.Get(req.viewer, string(args.ID)) + if err != nil { + if hidden(err) { + return nil, nil + } + return nil, err + } + if err := req.take(1); err != nil { + return nil, err + } + return &personResolver{e: q.e, p: p}, nil +} + +// People pages through the customers the viewer may see. +func (q *query) People(ctx context.Context, args struct { + Tag *string + First *int32 + After *string +}) (*personConnection, error) { + req := requestFrom(ctx) + list, err := q.e.svc.List(req.viewer) + if err != nil { + return nil, err + } + all := append([]customers.PersonView{list.Me}, list.People...) + if args.Tag != nil && strings.TrimSpace(*args.Tag) != "" { + tag := strings.ToLower(strings.TrimSpace(*args.Tag)) + kept := all[:0:0] + for _, p := range all { + if p.HasTag(tag) { + kept = append(kept, p) + } + } + all = kept + } + start := 0 + if args.After != nil && *args.After != "" { + n, err := strconv.Atoi(*args.After) + if err != nil || n < 0 { + return nil, errors.New("bad cursor") + } + start = n + } + if start > len(all) { + start = len(all) + } + end := start + q.e.page(args.First) + if end > len(all) { + end = len(all) + } + if err := req.take(end - start); err != nil { + return nil, err + } + conn := &personConnection{} + for _, p := range all[start:end] { + conn.nodes = append(conn.nodes, &personResolver{e: q.e, p: p}) + } + if end < len(all) { + next := strconv.Itoa(end) + conn.next = &next + } + return conn, nil +} + +// Artefact is an artefact by reference, or null. +func (q *query) Artefact(ctx context.Context, args struct{ Ref string }) (*artefactResolver, error) { + req := requestFrom(ctx) + if !q.e.svc.ArtefactVisible(req.viewer, args.Ref) { + return nil, nil + } + if err := req.take(1); err != nil { + return nil, err + } + return &artefactResolver{e: q.e, ref: args.Ref}, nil +} + +type personConnection struct { + nodes []*personResolver + next *string +} + +func (c *personConnection) Nodes() []*personResolver { + if c.nodes == nil { + return []*personResolver{} + } + return c.nodes +} + +func (c *personConnection) Next() *string { return c.next } + +// personResolver is a profile as the service already cut it for the viewer. +type personResolver struct { + e *Engine + p customers.PersonView +} + +func (r *personResolver) ID() graphql.ID { return graphql.ID(r.p.ID) } +func (r *personResolver) Name() string { return r.p.Name } +func (r *personResolver) Origin() string { return string(r.p.Origin) } +func (r *personResolver) Me() bool { return r.p.Me } + +func (r *personResolver) Tags() []*tagResolver { + out := make([]*tagResolver, 0, len(r.p.Tags)) + for _, t := range r.p.Tags { + out = append(out, &tagResolver{t: t}) + } + return out +} + +func (r *personResolver) Identities() []*identityResolver { + out := make([]*identityResolver, 0, len(r.p.Identities)) + for _, i := range r.p.Identities { + out = append(out, &identityResolver{i: i}) + } + return out +} + +func (r *personResolver) Goals() []*goalResolver { + out := make([]*goalResolver, 0, len(r.p.Goals)) + for _, g := range r.p.Goals { + out = append(out, &goalResolver{g: g}) + } + return out +} + +// Satisfaction is null when the service withheld it (no full view). +func (r *personResolver) Satisfaction() *satisfactionResolver { + if r.p.Satisfaction.Level == "" { + return nil + } + return &satisfactionResolver{s: r.p.Satisfaction} +} + +// Notes is null when the service withheld them or there are none. +func (r *personResolver) Notes() *string { + if r.p.Notes == "" { + return nil + } + notes := r.p.Notes + return ¬es +} + +func (r *personResolver) Counts() []*countResolver { + keys := make([]string, 0, len(r.p.Counts)) + for k := range r.p.Counts { + keys = append(keys, k) + } + sort.Strings(keys) + out := make([]*countResolver, 0, len(keys)) + for _, k := range keys { + out = append(out, &countResolver{predicate: k, count: int32(r.p.Counts[k])}) + } + return out +} + +// Edges pages through the person's edges the viewer may see, newest first. +func (r *personResolver) Edges(ctx context.Context, args struct { + Predicate *string + First *int32 + After *string +}) (*edgeConnection, error) { + req := requestFrom(ctx) + predicate, after := "", "" + if args.Predicate != nil { + predicate = *args.Predicate + } + if args.After != nil { + after = *args.After + } + edges, next, err := r.e.svc.Edges(req.viewer, r.p.ID, predicate, after, r.e.page(args.First)) + if err != nil { + if hidden(err) { + return &edgeConnection{}, nil + } + return nil, err + } + if err := req.take(len(edges)); err != nil { + return nil, err + } + conn := &edgeConnection{} + for _, e := range edges { + conn.nodes = append(conn.nodes, &edgeResolver{e: r.e, edge: e}) + } + if next != "" { + conn.next = &next + } + return conn, nil +} + +type tagResolver struct{ t customers.Tag } + +func (r *tagResolver) Name() string { return r.t.Name } +func (r *tagResolver) On() bool { return r.t.State == customers.TagOn } +func (r *tagResolver) Source() string { return string(r.t.Source) } +func (r *tagResolver) Rule() *string { return optional(r.t.Rule) } + +type identityResolver struct{ i customers.Identity } + +func (r *identityResolver) Kind() string { return string(r.i.Kind) } +func (r *identityResolver) Value() string { return r.i.Value } +func (r *identityResolver) Source() *string { return optional(r.i.Source) } +func (r *identityResolver) Manual() bool { return r.i.Manual } +func (r *identityResolver) Claimed() bool { return r.i.Claimed } + +type goalResolver struct{ g customers.Goal } + +func (r *goalResolver) ID() graphql.ID { return graphql.ID(r.g.ID) } +func (r *goalResolver) Text() string { return r.g.Text } +func (r *goalResolver) State() string { return r.g.State } +func (r *goalResolver) Source() string { return string(r.g.Source) } +func (r *goalResolver) Evidence() []string { return list(r.g.Evidence) } + +type satisfactionResolver struct{ s customers.Satisfaction } + +func (r *satisfactionResolver) Level() string { return string(r.s.Level) } +func (r *satisfactionResolver) Source() *string { return optional(string(r.s.Source)) } +func (r *satisfactionResolver) Evidence() []string { return list(r.s.Evidence) } + +func (r *satisfactionResolver) SuggestedLevel() *string { + if r.s.Suggestion == nil { + return nil + } + return optional(string(r.s.Suggestion.Level)) +} + +func (r *satisfactionResolver) SuggestedEvidence() []string { + if r.s.Suggestion == nil { + return []string{} + } + return list(r.s.Suggestion.Evidence) +} + +type countResolver struct { + predicate string + count int32 +} + +func (r *countResolver) Predicate() string { return r.predicate } +func (r *countResolver) Count() int32 { return r.count } + +type edgeConnection struct { + nodes []*edgeResolver + next *string +} + +func (c *edgeConnection) Nodes() []*edgeResolver { + if c.nodes == nil { + return []*edgeResolver{} + } + return c.nodes +} + +func (c *edgeConnection) Next() *string { return c.next } + +type edgeResolver struct { + e *Engine + edge customers.Edge +} + +func (r *edgeResolver) Predicate() string { return r.edge.Predicate } +func (r *edgeResolver) At() string { return r.edge.At.UTC().Format(time.RFC3339) } +func (r *edgeResolver) Source() *string { return optional(r.edge.Source) } + +func (r *edgeResolver) Artefact() *artefactResolver { + return &artefactResolver{e: r.e, ref: r.edge.Artefact} +} + +// artefactResolver is a reference. It never carries content. +type artefactResolver struct { + e *Engine + ref string +} + +func (r *artefactResolver) Ref() string { return r.ref } +func (r *artefactResolver) Kind() string { return customers.RefKind(r.ref) } + +// People walks back from the artefact to the people on it that the viewer +// may see. For a viewer without the full view that is at most themselves. +func (r *artefactResolver) People(ctx context.Context, args struct{ First *int32 }) ([]*artefactPersonResolver, error) { + req := requestFrom(ctx) + people, err := r.e.svc.ArtefactPeople(req.viewer, r.ref, r.e.page(args.First)) + if err != nil { + if hidden(err) { + return []*artefactPersonResolver{}, nil + } + return nil, err + } + if err := req.take(len(people)); err != nil { + return nil, err + } + out := make([]*artefactPersonResolver, 0, len(people)) + for _, p := range people { + out = append(out, &artefactPersonResolver{predicate: p.Predicate, person: &personResolver{e: r.e, p: p.Person}}) + } + return out, nil +} + +type artefactPersonResolver struct { + predicate string + person *personResolver +} + +func (r *artefactPersonResolver) Predicate() string { return r.predicate } +func (r *artefactPersonResolver) Person() *personResolver { return r.person } + +// optional turns an empty string into null. +func optional(s string) *string { + if s == "" { + return nil + } + return &s +} + +// list turns a nil slice into an empty list, which a non-null list field +// needs. +func list(s []string) []string { + if s == nil { + return []string{} + } + return s +} diff --git a/src/pkg/customers/gql/schema.go b/src/pkg/customers/gql/schema.go new file mode 100644 index 0000000000..37bdeedb93 --- /dev/null +++ b/src/pkg/customers/gql/schema.go @@ -0,0 +1,115 @@ +package gql + +// Schema is the customer graph, read-only: there is no Mutation and no +// Subscription type, so nothing can be written through this endpoint. +const Schema = ` +schema { + query: Query +} + +# The customer graph: people, the artefacts they touched, and the edges +# between them. Read-only. Every field that returns a person checks who is +# asking; a read-only user reaches only their own profile. +type Query { + # The viewer's own profile. + me: Person! + # One profile. null when there is no such person or the viewer may not + # see them; the two cases are not distinguishable. + person(id: ID!): Person + # Customers the viewer may see, by name. Suggested people are never + # returned. + people(tag: String, first: Int, after: String): PersonConnection! + # An artefact by reference, for walking back to the people on it. null + # when the reference is malformed or the viewer may not see it. + artefact(ref: String!): Artefact +} + +type Person { + id: ID! + name: String! + origin: String! + me: Boolean! + tags: [Tag!]! + identities: [Identity!]! + goals: [Goal!]! + # null for a viewer without the full view. + satisfaction: Satisfaction + # null for a viewer without the full view. + notes: String + counts: [Count!]! + edges(predicate: String, first: Int, after: String): EdgeConnection! +} + +type PersonConnection { + nodes: [Person!]! + # Cursor for the next page; null on the last page. + next: String +} + +type Tag { + name: String! + on: Boolean! + # "auto" or "manual". + source: String! + rule: String +} + +type Identity { + kind: String! + value: String! + source: String + manual: Boolean! + # true while a read-only user's own addition waits to be confirmed. + claimed: Boolean! +} + +type Goal { + id: ID! + text: String! + # "suggested" or "confirmed". + state: String! + # "auto" (inferred) or "manual". + source: String! + evidence: [String!]! +} + +type Satisfaction { + # unknown, at_risk, neutral or satisfied. There is no score. + level: String! + source: String + evidence: [String!]! + suggestedLevel: String + suggestedEvidence: [String!]! +} + +type Count { + predicate: String! + count: Int! +} + +type Edge { + predicate: String! + at: String! + source: String + artefact: Artefact! +} + +type EdgeConnection { + nodes: [Edge!]! + # Cursor for the next page; null on the last page. + next: String +} + +# An artefact is a reference, never content. +type Artefact { + ref: String! + kind: String! + # The people on this artefact that the viewer may see. + people(first: Int): [ArtefactPerson!]! +} + +type ArtefactPerson { + predicate: String! + person: Person! +} +` diff --git a/src/pkg/customers/service.go b/src/pkg/customers/service.go index 22a82517c0..4856229884 100644 --- a/src/pkg/customers/service.go +++ b/src/pkg/customers/service.go @@ -323,3 +323,76 @@ func (s *Service) Dismiss(v Viewer, suggestionID string) error { } return s.store.Dismiss(suggestionID) } + +// ArtefactPerson is one person on an artefact, as the viewer sees them. +type ArtefactPerson struct { + Predicate string + Person PersonView +} + +// Edges returns a page of a person's edges, newest first, leaving out the +// ones whose artefact the viewer may not see where it lives. Without the +// full view only the viewer's own edges can be read. A page can come back +// shorter than limit when edges were left out; next is still the cursor for +// the following page. +func (s *Service) Edges(v Viewer, id, predicate, after string, limit int) ([]Edge, string, error) { + p, _, err := s.resolve(v, id) + if err != nil { + return nil, "", err + } + if s.index == nil { + return nil, "", nil + } + edges, next, err := s.index.ByPerson(p.ID, predicate, after, limit) + if err != nil { + return nil, "", err + } + visible := edges[:0:0] + for _, e := range edges { + if s.resolvers.Visible(e.Artefact, v) { + visible = append(visible, e) + } + } + return visible, next, nil +} + +// ArtefactVisible reports whether the viewer may be told about an artefact +// reference at all: the reference is well formed, the viewer is a named +// user, and the artefact's own source lets them see it. It says nothing +// about whether the artefact exists. +func (s *Service) ArtefactVisible(v Viewer, ref string) bool { + if !validRef(ref) || strings.TrimSpace(v.User) == "" { + return false + } + return s.resolvers.Visible(ref, v) +} + +// ArtefactPeople walks back from an artefact to the people on it that the +// viewer may see. Without the full view that is at most the viewer. +func (s *Service) ArtefactPeople(v Viewer, ref string, limit int) ([]ArtefactPerson, error) { + if !s.ArtefactVisible(v, ref) { + return nil, ErrNotFound + } + if s.index == nil { + return nil, nil + } + edges, err := s.index.ByArtefact(ref) + if err != nil { + return nil, err + } + if limit <= 0 || limit > MaxEdgePage { + limit = MaxEdgePage + } + var out []ArtefactPerson + for _, e := range edges { + if len(out) == limit { + break + } + p, isMe, err := s.resolve(v, e.Person) + if err != nil { + continue // not visible to this viewer, or gone + } + out = append(out, ArtefactPerson{Predicate: e.Predicate, Person: s.view(v, p, isMe, false)}) + } + return out, nil +} diff --git a/src/pkg/customers/service_test.go b/src/pkg/customers/service_test.go index 2bfc30f45b..c663014c5d 100644 --- a/src/pkg/customers/service_test.go +++ b/src/pkg/customers/service_test.go @@ -444,3 +444,100 @@ func TestServiceWithoutIndex(t *testing.T) { t.Fatalf("Forget without an index = %d, %v", n, err) } } + +// privateTo is a resolver that lets only one user see each listed artefact. +type privateTo map[string]string + +func (p privateTo) Exists(string) bool { return true } + +func (p privateTo) Visible(ref string, v Viewer) bool { + owner, restricted := p[ref] + return !restricted || owner == v.User +} + +func TestEdgesAndArtefactPeopleFollowTheViewer(t *testing.T) { + dir := t.TempDir() + store, err := Open(filepath.Join(dir, "customers"), newClock().now) + if err != nil { + t.Fatal(err) + } + index, err := OpenIndex(filepath.Join(dir, "graph")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = index.Close() }) + private := MeetingRef("owners-only") + s := NewService(store, index, Resolvers{RefMeeting: privateTo{private: "olivia"}}) + + reed, _ := s.Get(readV, MeID) + ada, _ := s.Add(ownerV, "Ada", []Identity{{Kind: KindGitHub, Value: "ada"}}) + shared := IssueRef("o/r", 1) + if _, err := index.Put([]Edge{ + edge(reed.ID, PredReported, shared, "hive_user:reed", 1), + edge(reed.ID, PredAttended, private, "hive_user:reed", 2), + edge(ada.ID, PredAssigned, shared, "github:ada", 3), + edge(ada.ID, PredAttended, private, "github:ada", 4), + }); err != nil { + t.Fatal(err) + } + + // The owner sees every edge of anyone. + edges, next, err := s.Edges(ownerV, ada.ID, "", "", 10) + if err != nil || next != "" || len(edges) != 2 { + t.Fatalf("owner Edges(ada) = %d, %q, %v", len(edges), next, err) + } + // Read-write sees Ada, but not the artefact only the owner may open. + edges, _, err = s.Edges(rwV, ada.ID, "", "", 10) + if err != nil || len(edges) != 1 || edges[0].Artefact != shared { + t.Fatalf("read-write Edges(ada) = %+v, %v", edges, err) + } + // Read-only: own edges only, and still not the private artefact. + edges, _, err = s.Edges(readV, MeID, "", "", 10) + if err != nil || len(edges) != 1 || edges[0].Artefact != shared { + t.Fatalf("read-only Edges(me) = %+v, %v", edges, err) + } + if _, _, err := s.Edges(readV, ada.ID, "", "", 10); !errors.Is(err, ErrNotFound) { + t.Fatalf("read-only Edges(ada) = %v, want ErrNotFound", err) + } + if _, _, err := s.Edges(Viewer{}, MeID, "", "", 10); !errors.Is(err, ErrForbidden) { + t.Fatalf("nameless Edges = %v", err) + } + + // Walking back from an artefact never reaches a person the viewer may + // not see: the read-only user finds only themselves on a shared issue. + people, err := s.ArtefactPeople(ownerV, shared, 10) + if err != nil || len(people) != 2 { + t.Fatalf("owner ArtefactPeople = %+v, %v", people, err) + } + people, err = s.ArtefactPeople(readV, shared, 10) + if err != nil || len(people) != 1 || people[0].Person.ID != reed.ID || !people[0].Person.Me || people[0].Predicate != PredReported { + t.Fatalf("read-only ArtefactPeople = %+v, %v", people, err) + } + if people, err := s.ArtefactPeople(ownerV, shared, 1); err != nil || len(people) != 1 { + t.Fatalf("limit = %+v, %v", people, err) + } + // An artefact the viewer may not see is not there for them. + if _, err := s.ArtefactPeople(rwV, private, 10); !errors.Is(err, ErrNotFound) { + t.Fatalf("ArtefactPeople on a private artefact = %v", err) + } + if s.ArtefactVisible(rwV, private) || !s.ArtefactVisible(ownerV, private) { + t.Fatal("ArtefactVisible must follow the artefact's own source") + } + for _, bad := range []string{"", "no-kind", "gh:bad\nref"} { + if s.ArtefactVisible(ownerV, bad) { + t.Errorf("ArtefactVisible(%q) = true", bad) + } + } + if s.ArtefactVisible(Viewer{Full: true}, shared) { + t.Fatal("a nameless viewer sees no artefact") + } + + // No index: nothing to read, and no error. + bare := NewService(store, nil, nil) + if e, n, err := bare.Edges(ownerV, ada.ID, "", "", 10); err != nil || e != nil || n != "" { + t.Fatalf("Edges without an index = %v, %q, %v", e, n, err) + } + if p, err := bare.ArtefactPeople(ownerV, shared, 10); err != nil || p != nil { + t.Fatalf("ArtefactPeople without an index = %v, %v", p, err) + } +} diff --git a/src/pkg/dashboard/api_customers.go b/src/pkg/dashboard/api_customers.go index 9b269af5c7..28553eeb25 100644 --- a/src/pkg/dashboard/api_customers.go +++ b/src/pkg/dashboard/api_customers.go @@ -21,7 +21,8 @@ import ( // - only the verified owner may forget a person; // - anyone else who is signed in sees only their own profile ("me") and // may edit its name, identities, tags and goals, through -// POST /api/customers/me/edit and no other route. +// POST /api/customers/me/edit and no other route. They may also query +// the read-only graph (POST /api/graph), where the same rule holds. // // The service enforces the same rules again on the viewer it is handed, so // a mistake here cannot widen what a read-only user reaches. @@ -33,6 +34,9 @@ var ( ErrCustomerInvalid = errors.New("invalid customer request") ErrCustomerConflict = errors.New("customer request conflicts with the current state") ErrCustomerForbidden = errors.New("you do not have access to this customer") + // ErrCustomerUnavailable is a part of the feature that is not running + // (the graph engine failed to start). + ErrCustomerUnavailable = errors.New("this part of customers is not available on this hive") ) const ( @@ -132,13 +136,19 @@ func (s *Server) registerCustomersRoutes() { s.mux.HandleFunc("DELETE /api/customers/{id}", s.handleCustomersForget) s.mux.HandleFunc("POST /api/customers/suggestions/{sid}/accept", s.handleCustomersAccept) s.mux.HandleFunc("POST /api/customers/suggestions/{sid}/dismiss", s.handleCustomersDismiss) + s.registerCustomersGraphRoutes() } // readOnlySelfService reports whether a write from a read-only user is one // of the few a read-only user may make to their own data. It is consulted // by roleEnforcement, which refuses every other write from the read role. func readOnlySelfService(r *http.Request) bool { - return r.Method == http.MethodPost && r.URL.Path == customersSelfEditPath + if r.Method != http.MethodPost { + return false + } + // The graph endpoint is a POST that only reads: its schema has no + // mutations. + return r.URL.Path == customersSelfEditPath || r.URL.Path == customersGraphPath } // customersViewer works out who is asking. The owner role counts only when @@ -188,6 +198,8 @@ func customersErrorStatus(err error) int { return http.StatusConflict case errors.Is(err, ErrCustomerForbidden): return http.StatusForbidden + case errors.Is(err, ErrCustomerUnavailable): + return http.StatusServiceUnavailable default: return http.StatusInternalServerError } diff --git a/src/pkg/dashboard/api_graph.go b/src/pkg/dashboard/api_graph.go new file mode 100644 index 0000000000..8820523061 --- /dev/null +++ b/src/pkg/dashboard/api_graph.go @@ -0,0 +1,102 @@ +package dashboard + +import ( + "context" + "net/http" + "strconv" +) + +// POST /api/graph: the customer graph over GraphQL (hivecommons/hive#18742). +// It is read-only: the schema has no mutations, so although the route is a +// POST it changes nothing, which is why a read-only user may call it. Who +// may see what is decided by the customers service on the viewer of the +// request: a read-only user reaches only their own profile by any path. + +const ( + // customersGraphPath is the endpoint. roleEnforcement lets a read-only + // user post to exactly this path. + customersGraphPath = "/api/graph" + // customersGraphOperationMax bounds the operation name kept for the + // audit line. + customersGraphOperationMax = 64 +) + +// CustomerGraphRequest is a GraphQL request body. +type CustomerGraphRequest struct { + Query string `json:"query"` + OperationName string `json:"operationName,omitempty"` + Variables map[string]any `json:"variables,omitempty"` +} + +// CustomerGraphResult is a GraphQL response. Body is the encoded +// {"data": ..., "errors": ...} document, written as is. +type CustomerGraphResult struct { + Body []byte + Nodes int + Errors int +} + +// CustomersGraphService executes read-only queries against the customer +// graph as the viewer. An error wraps the ErrCustomer* sentinels; a query +// that fails is not an error but a GraphQL error inside Body. +type CustomersGraphService interface { + Graph(ctx context.Context, v CustomersViewer, req CustomerGraphRequest) (CustomerGraphResult, error) +} + +func (s *Server) registerCustomersGraphRoutes() { + s.mux.HandleFunc("POST /api/graph", s.handleCustomersGraph) +} + +// customersGraphOperation is the operation name as the audit log keeps it: +// letters, digits and underscores only, and bounded. The query text itself +// is never logged. +func customersGraphOperation(name string) string { + out := make([]byte, 0, len(name)) + for i := 0; i < len(name) && len(out) < customersGraphOperationMax; i++ { + c := name[i] + if c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9' || c == '_' { + out = append(out, c) + } + } + if len(out) == 0 { + return "anonymous" + } + return string(out) +} + +func (s *Server) handleCustomersGraph(w http.ResponseWriter, r *http.Request) { + v, ok := customersViewer(w, r) + if !ok { + return + } + svc, ok := s.customersService(w) + if !ok { + return + } + graph, ok := svc.(CustomersGraphService) + if !ok { + jsonError(w, "the customer graph is not available on this hive", http.StatusServiceUnavailable) + return + } + // The body cap covers the query text (the engine caps it at 8 KB) and + // its variables. + var req CustomerGraphRequest + if !decodeCustomersBody(w, r, &req) { + return + } + if req.Query == "" { + jsonError(w, "a query is required", http.StatusBadRequest) + return + } + res, err := graph.Graph(r.Context(), v, req) + if err != nil { + s.customersError(w, r, err) + return + } + s.auditFromRequest(r, "customer_graph_query", auditDetail( + "operation", customersGraphOperation(req.OperationName), + "nodes", strconv.Itoa(res.Nodes), "errors", strconv.Itoa(res.Errors), "full", boolString(v.Full)), "") + w.Header().Set("Content-Type", "application/json") + w.Header().Set("Cache-Control", "no-store") + _, _ = w.Write(res.Body) +} diff --git a/src/pkg/dashboard/api_graph_test.go b/src/pkg/dashboard/api_graph_test.go new file mode 100644 index 0000000000..eeb794a6fe --- /dev/null +++ b/src/pkg/dashboard/api_graph_test.go @@ -0,0 +1,138 @@ +package dashboard + +import ( + "context" + "fmt" + "net/http" + "strings" + "testing" +) + +// fakeGraphService is the customers fake plus the graph. +type fakeGraphService struct { + fakeCustomersService + queries []string +} + +func (f *fakeGraphService) Graph(_ context.Context, v CustomersViewer, req CustomerGraphRequest) (CustomerGraphResult, error) { + f.note("Graph", v, req.OperationName) + f.queries = append(f.queries, req.Query) + if f.err != nil { + return CustomerGraphResult{}, f.err + } + return CustomerGraphResult{Body: []byte(`{"data":{"me":{"name":"` + v.User + `"}}}`), Nodes: 4, Errors: 1}, nil +} + +const graphBody = `{"query":"query Timeline { me { name } }","operationName":"Timeline","variables":{"id":"p_x"}}` + +// TestCustomersGraphRoleMatrix: every signed-in, named user may query the +// graph, the read role included, because the endpoint only reads. The +// service is handed the viewer, and decides what that viewer reaches. +func TestCustomersGraphRoleMatrix(t *testing.T) { + s, _ := apiServer(t) + want := map[string]int{ + "owner": http.StatusOK, "read-write": http.StatusOK, "merger": http.StatusOK, "read": http.StatusOK, + "unverified owner": http.StatusForbidden, "read with no name": http.StatusForbidden, + } + for _, who := range []customersWho{custOwner, custReadWrite, custMerger, custRead, custFakeOwner, custNamelessRO} { + fake := &fakeGraphService{} + s.SetCustomersService(fake) + rec := customersDo(s, who, http.MethodPost, "/api/graph", graphBody) + if rec.Code != want[who.name] { + t.Fatalf("POST /api/graph as %s = %d, want %d: %s", who.name, rec.Code, want[who.name], rec.Body.String()) + } + if rec.Code != http.StatusOK { + if len(fake.calls) != 0 { + t.Fatalf("a refused query reached the service: %v", fake.calls) + } + continue + } + full := who.name != "read" + wantCall := fmt.Sprintf("Graph user=%s full=%v owner=%v arg=Timeline", who.user, full, who.name == "owner") + if len(fake.calls) != 1 || fake.calls[0] != wantCall { + t.Fatalf("service saw %v, want %q", fake.calls, wantCall) + } + if rec.Body.String() != `{"data":{"me":{"name":"`+who.user+`"}}}` || rec.Header().Get("Content-Type") != "application/json" || rec.Header().Get("Cache-Control") != "no-store" { + t.Fatalf("response = %q %v", rec.Body.String(), rec.Header()) + } + } + // The read role's exemption is this exact path and method. + fake := &fakeGraphService{} + s.SetCustomersService(fake) + for _, r := range []customersRoute{ + {http.MethodPost, "/api/graph/", graphBody}, + {http.MethodPost, "/api/graph/x", graphBody}, + {http.MethodPut, "/api/graph", graphBody}, + {http.MethodDelete, "/api/graph", ""}, + {http.MethodPost, "/api/graphql", graphBody}, + } { + if rec := customersDo(s, custRead, r.method, r.path, r.body); rec.Code == http.StatusOK { + t.Errorf("%s %s as read = 200", r.method, r.path) + } + } + if len(fake.calls) != 0 { + t.Fatalf("a near-miss reached the service: %v", fake.calls) + } +} + +func TestCustomersGraphErrorsAndAudit(t *testing.T) { + s, _ := apiServer(t) + // Off. + if rec := customersDo(s, custOwner, http.MethodPost, "/api/graph", graphBody); rec.Code != http.StatusServiceUnavailable { + t.Fatalf("graph while customers are off = %d", rec.Code) + } + // A service without the graph. + s.SetCustomersService(&fakeCustomersService{}) + if rec := customersDo(s, custOwner, http.MethodPost, "/api/graph", graphBody); rec.Code != http.StatusServiceUnavailable { + t.Fatalf("graph without an engine = %d", rec.Code) + } + fake := &fakeGraphService{} + s.SetCustomersService(fake) + for body, want := range map[string]int{ + `{not json`: http.StatusBadRequest, + `{"query":""}`: http.StatusBadRequest, + `{"variables":{"a":1}}`: http.StatusBadRequest, + `{"query":"` + strings.Repeat("x", customersMaxBody) + `"}`: http.StatusBadRequest, + } { + if rec := customersDo(s, custOwner, http.MethodPost, "/api/graph", body); rec.Code != want { + t.Errorf("body %.30q = %d, want %d", body, rec.Code, want) + } + } + if len(fake.calls) != 0 { + t.Fatalf("a malformed request reached the service: %v", fake.calls) + } + fake.err = ErrCustomerUnavailable + if rec := customersDo(s, custOwner, http.MethodPost, "/api/graph", graphBody); rec.Code != http.StatusServiceUnavailable { + t.Fatalf("engine unavailable = %d", rec.Code) + } + fake.err = nil + + // The audit line carries the operation name (cleaned), the node and + // error counts and whether the viewer had the full view. Never the query. + secret := `{"query":"query { person(id: \"p_secret\") { notes } }","operationName":"Peek at