Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions changelog.d/added-18742-customers-graphql.md
Original file line number Diff line number Diff line change
@@ -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.
69 changes: 69 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
23 changes: 22 additions & 1 deletion src/cmd/hive/customerswire.go
Original file line number Diff line number Diff line change
@@ -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"
)

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
}
46 changes: 46 additions & 0 deletions src/cmd/hive/customerswire_test.go
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
package main

import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"testing"

"github.com/hivecommons/hive/pkg/config"
Expand Down Expand Up @@ -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)
}
}
4 changes: 2 additions & 2 deletions src/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand Down
Loading
Loading