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
1 change: 1 addition & 0 deletions changelog.d/added-18884-customers-mention-search.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Customers: when an owner accepts a suggested GitHub login, the hive can now make one budgeted GitHub search for mentions and comments so the new profile starts with history (off by default; `customers.mention_search.enabled`, at most two requests per accept and a per-hour budget, shed when the API budget is low, never run by the discovery sweep, ids and counts only in the log) (#18884).
118 changes: 118 additions & 0 deletions src/cmd/hive/customers_mention.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
package main

import (
"context"
"errors"
"log/slog"
"time"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/customers"
"github.com/hivecommons/hive/pkg/github"
)

// Customers step E (hivecommons/hive#18884): the budgeted GitHub mention
// search that runs when a person accepts a suggested GitHub login. It is
// reached only from customersDashboard.Accept and AcceptInto. The discovery
// sweep (customers_sweep.go) is never handed this, nor a GitHub client.

// customersMentionTimeout bounds one accept's background search, including
// any wait for a pacing slot.
const customersMentionTimeout = 45 * time.Second

// customersMentionSearcher adapts the shared GitHub client to
// customers.MentionSearcher. The client is read at call time so a credential
// rebuild is followed.
type customersMentionSearcher struct {
client func() *github.Client
}

func (s customersMentionSearcher) SearchMentions(ctx context.Context, kind, login string, repos []string, limit int) ([]customers.MentionHit, error) {
c := s.client()
if c == nil {
return nil, github.ErrNoGitHubClient
}
ghKind := github.MentionSearchKindMentions
if kind == customers.MentionKindCommenter {
ghKind = github.MentionSearchKindCommenter
}
hits, err := c.SearchMentions(ctx, ghKind, login, repos, limit)
if err != nil {
if errors.Is(err, github.ErrMentionSearchRateLimited) {
return nil, customers.ErrMentionQuotaLow
}
return nil, err
}
out := make([]customers.MentionHit, 0, len(hits))
for _, h := range hits {
out = append(out, customers.MentionHit{Repo: h.Repo, Number: h.Number, IsPR: h.IsPR, At: h.UpdatedAt})
}
return out, nil
}

// newCustomersMentionSearch builds the accept-time search over the people
// store's index. cfg and client are read on every call.
func newCustomersMentionSearch(svc *customers.Service, cfg func() *config.Config, client func() *github.Client) *customers.MentionSearch {
m := customers.NewMentionSearch(customersMentionSearcher{client: client}, svc.Index())
m.Enabled = func() bool { return cfg().CustomersMentionSearchEnabled() }
m.HourlyLimit = func() int {
if c := cfg(); c != nil {
return c.Customers.MentionSearch.RequestsPerHour()
}
return config.DefaultCustomersMentionSearchMaxPerHour
}
m.Repos = func() []string {
if c := cfg(); c != nil {
return append([]string(nil), c.Project.Repos...)
}
return nil
}
m.QuotaLow = func() string { return client().OptionalSearchStandDown() }
return m
}

// suggestedIdentity returns the identity of a suggestion before an accept
// consumes it.
func (c *customersDashboard) suggestedIdentity(suggestionID string) (customers.Identity, bool) {
for _, sg := range c.svc.Store().Suggestions() {
if sg.ID == suggestionID {
return customers.Identity{Kind: sg.Kind, Value: sg.Value}, true
}
}
return customers.Identity{}, false
}

// searchOnAccept runs the budgeted search for the identity just accepted. It
// never delays or fails the accept: it runs in the background and logs the
// person id and counts only (never the login, a query or a token).
func (c *customersDashboard) searchOnAccept(person string, ident customers.Identity, found bool) {
if c.mentions == nil || !found || person == "" {
return
}
run := func() {
ctx, cancel := context.WithTimeout(context.Background(), customersMentionTimeout)
defer cancel()
res := c.mentions.Run(ctx, person, ident)
if c.logger == nil || res.Skipped == customers.SkipDisabled {
return
}
c.logger.Info("[customers] accept-time github search", slog.String("person", res.Person),
slog.Int("requests", res.Requests), slog.Int("found", res.Found), slog.Int("edges", res.Edges),
slog.Bool("truncated", res.Truncated), slog.String("skipped", res.Skipped))
}
if c.spawn != nil {
c.spawn(run)
return
}
go run()
}

// customersMentionConfig is the config the accept-time search reads on every
// call: the immutable snapshot the governor publishes after each reload,
// falling back to the boot config before the first one.
func (b *boot) customersMentionConfig() *config.Config {
if cfg := b.sweepConfig.Load(); cfg != nil {
return cfg
}
return b.cfg
}
202 changes: 202 additions & 0 deletions src/cmd/hive/customers_mention_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
package main

import (
"bytes"
"context"
"log/slog"
"os"
"strings"
"sync"
"testing"
"time"

"github.com/hivecommons/hive/pkg/customers"
"github.com/hivecommons/hive/pkg/dashboard"
)

type countingMentionSearcher struct {
mu sync.Mutex
calls int
login string
}

func (c *countingMentionSearcher) SearchMentions(_ context.Context, kind, login string, _ []string, _ int) ([]customers.MentionHit, error) {
c.mu.Lock()
defer c.mu.Unlock()
c.calls++
c.login = login
if kind == customers.MentionKindCommenter {
return nil, nil
}
return []customers.MentionHit{{Repo: "acme/widgets", Number: 5, IsPR: true, At: time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)}}, nil
}

func (c *countingMentionSearcher) count() int {
c.mu.Lock()
defer c.mu.Unlock()
return c.calls
}

// wireMentionTest returns an adapter whose accept-time search is on, runs
// inline, and logs into buf.
func wireMentionTest(t *testing.T, enabled bool) (*customersDashboard, *countingMentionSearcher, *bytes.Buffer) {
t.Helper()
c := wireTestCustomers(t)
fake := &countingMentionSearcher{}
m := customers.NewMentionSearch(fake, c.svc.Index())
m.Enabled = func() bool { return enabled }
m.HourlyLimit = func() int { return 10 }
m.Repos = func() []string { return []string{"acme/widgets"} }
c.mentions = m
c.spawn = func(f func()) { f() }
var buf bytes.Buffer
c.logger = slog.New(slog.NewTextHandler(&buf, nil))
return c, fake, &buf
}

// suggest makes the sweep see a login and an address nobody owns, which
// leaves one suggestion for each, and returns their ids.
func suggest(t *testing.T, c *customersDashboard) (loginID, emailID string) {
t.Helper()
at := time.Date(2026, 11, 2, 10, 0, 0, 0, time.UTC)
_, err := c.svc.Sweep(customers.SweepInput{Sightings: []customers.Sighting{
{Source: customersSourcePoll, Observation: customers.Observation{Kind: customers.KindGitHub, Value: "zed", Predicate: customers.PredReported, Artefact: "gh:issue:acme/widgets#7", At: at}},
{Source: customersSourceMail, Observation: customers.Observation{Kind: customers.KindEmail, Value: "yara@example.org", Predicate: customers.PredSent, Artefact: "inbox:mail:1", At: at}},
}})
if err != nil {
t.Fatal(err)
}
for _, sg := range c.svc.Store().Suggestions() {
switch sg.Kind {
case customers.KindGitHub:
loginID = sg.ID
case customers.KindEmail:
emailID = sg.ID
}
}
if loginID == "" || emailID == "" {
t.Fatalf("suggestions = %+v", c.svc.Store().Suggestions())
}
return loginID, emailID
}

// The search is reached from the accept path only: a sweep that sees a new
// login, with the search wired and on, makes no call.
func TestCustomersMentionSearchNeverRunsInTheSweep(t *testing.T) {
c, fake, _ := wireMentionTest(t, true)
suggest(t, c)
if _, err := c.svc.Sweep(customers.SweepInput{}); err != nil {
t.Fatal(err)
}
if n := fake.count(); n != 0 {
t.Fatalf("the sweep made %d GitHub searches", n)
}
// And the sweep's source cannot reach it: it is handed no client and
// names neither the search nor its adapter.
src, err := os.ReadFile("customers_sweep.go")
if err != nil {
t.Fatal(err)
}
for _, banned := range []string{"MentionSearch", "SearchMentions", "mentions"} {
if strings.Contains(string(src), "."+banned) || strings.Contains(string(src), banned+"(") {
t.Errorf("customers_sweep.go references %q; the search belongs on the accept path only", banned)
}
}
if !strings.Contains(string(src), "never handed a GitHub client") {
t.Error("the sweep's no-network comment is gone")
}
}

func TestCustomersMentionSearchRunsOnAccept(t *testing.T) {
c, fake, buf := wireMentionTest(t, true)
loginID, _ := suggest(t, c)
owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}
res, err := c.Accept(owner, loginID)
if err != nil {
t.Fatal(err)
}
if fake.count() != customers.MentionSearchMaxRequests {
t.Fatalf("accept made %d searches, want %d", fake.count(), customers.MentionSearchMaxRequests)
}
edges, _, err := c.svc.Index().ByPerson(res.ID, customers.PredMentionedIn, "", 10)
if err != nil || len(edges) == 0 {
t.Fatalf("edges = %+v, %v", edges, err)
}
var found bool
for _, e := range edges {
if e.Artefact == "gh:pr:acme/widgets#5" && e.Source == customers.MentionSearchSource {
found = true
}
}
if !found {
t.Fatalf("the search result did not land as an edge: %+v", edges)
}
// Ids and counts only in the log.
out := buf.String()
if !strings.Contains(out, "requests=2") || !strings.Contains(out, "person="+res.ID) {
t.Fatalf("log line missing ids and counts: %q", out)
}
for _, bad := range []string{"zed", "acme", "widgets", "mentions:", "token"} {
if strings.Contains(out, bad) {
t.Errorf("log line leaks %q: %q", bad, out)
}
}
}

func TestCustomersMentionSearchAcceptIntoAlsoSearches(t *testing.T) {
c, fake, _ := wireMentionTest(t, true)
loginID, _ := suggest(t, c)
owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}
if _, err := c.AcceptInto(owner, loginID, "me"); err != nil {
t.Fatal(err)
}
if fake.count() != customers.MentionSearchMaxRequests || fake.login != "zed" {
t.Fatalf("calls = %d, login %q", fake.count(), fake.login)
}
}

func TestCustomersMentionSearchSkippedWhenOffOrNotALogin(t *testing.T) {
owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}
c, fake, _ := wireMentionTest(t, false)
loginID, _ := suggest(t, c)
if _, err := c.Accept(owner, loginID); err != nil || fake.count() != 0 {
t.Fatalf("off: err %v, calls %d", err, fake.count())
}
c, fake, _ = wireMentionTest(t, true)
_, emailID := suggest(t, c)
if _, err := c.Accept(owner, emailID); err != nil || fake.count() != 0 {
t.Fatalf("an email suggestion must never be searched: err %v, calls %d", err, fake.count())
}
}

// A refused accept (read-only viewer, unknown suggestion) searches nothing.
func TestCustomersMentionSearchNotRunOnRefusedAccept(t *testing.T) {
c, fake, _ := wireMentionTest(t, true)
loginID, _ := suggest(t, c)
if _, err := c.Accept(dashboard.CustomersViewer{User: "reed"}, loginID); err == nil {
t.Fatal("a read-only accept must be refused")
}
if _, err := c.Accept(dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}, "s_missing"); err == nil {
t.Fatal("an unknown suggestion must be refused")
}
if fake.count() != 0 {
t.Fatalf("%d searches after refused accepts", fake.count())
}
}

// The accept does not wait for GitHub: by default the search is a goroutine.
func TestCustomersMentionSearchDefaultsToBackground(t *testing.T) {
c, fake, _ := wireMentionTest(t, true)
c.spawn = nil
loginID, _ := suggest(t, c)
if _, err := c.Accept(dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}, loginID); err != nil {
t.Fatal(err)
}
deadline := time.Now().Add(5 * time.Second)
for fake.count() < customers.MentionSearchMaxRequests && time.Now().Before(deadline) {
time.Sleep(10 * time.Millisecond)
}
if fake.count() != customers.MentionSearchMaxRequests {
t.Fatalf("background search made %d calls", fake.count())
}
}
22 changes: 19 additions & 3 deletions src/cmd/hive/customerswire.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ type customersDashboard struct {
svc *customers.Service
// graph is the read-only GraphQL engine; nil if it failed to start.
graph *gql.Engine
// mentions is the accept-time GitHub search (step E, #18884); nil when
// it is not wired. Only Accept and AcceptInto reach it.
mentions *customers.MentionSearch
logger *slog.Logger
// spawn runs the search; nil means a goroutine. Tests run it inline.
spawn func(func())
}

// wireCustomers opens the people store and the edge index when
Expand Down Expand Up @@ -76,7 +82,7 @@ func wireCustomersAt(dataDir, graphDir string, resolvers customers.Resolvers, lo
logger.Error("[customers] graph endpoint unavailable", "error", err)
}
}
return &customersDashboard{svc: svc, graph: graph}, stop
return &customersDashboard{svc: svc, graph: graph, logger: logger}, stop
}

// customersError maps a store error onto the dashboard's sentinels, which
Expand Down Expand Up @@ -148,7 +154,12 @@ func (c *customersDashboard) Forget(v dashboard.CustomersViewer, id string) (int
}

func (c *customersDashboard) Accept(v dashboard.CustomersViewer, suggestionID string) (dashboard.CustomerResult, error) {
return customerResult(c.svc.Accept(customersViewer(v), suggestionID))
ident, found := c.suggestedIdentity(suggestionID)
res, err := customerResult(c.svc.Accept(customersViewer(v), suggestionID))
if err == nil {
c.searchOnAccept(res.ID, ident, found)
}
return res, err
}

func (c *customersDashboard) Dismiss(v dashboard.CustomersViewer, suggestionID string) error {
Expand Down Expand Up @@ -212,7 +223,12 @@ func installCustomersAgentContext(c *customersDashboard, setKickLookup func(sche
}

func (c *customersDashboard) AcceptInto(v dashboard.CustomersViewer, suggestionID, into string) (dashboard.CustomerResult, error) {
return customerResult(c.svc.AcceptInto(customersViewer(v), suggestionID, into))
ident, found := c.suggestedIdentity(suggestionID)
res, err := customerResult(c.svc.AcceptInto(customersViewer(v), suggestionID, into))
if err == nil {
c.searchOnAccept(res.ID, ident, found)
}
return res, err
}

func (c *customersDashboard) Merge(v dashboard.CustomersViewer, id, from string) (dashboard.CustomerResult, error) {
Expand Down
3 changes: 3 additions & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -3633,6 +3633,9 @@ func (b *boot) bootDashboardAPIWith(deps bootDashboardAPIDeps) {
if svc, stop := wireCustomers(b.cfg, b.customersResolvers(), b.logger); svc != nil {
b.cleanup.push(stop)
b.customers = svc
// Step E (#18884): the budgeted GitHub search on accept. Off unless
// customers.mention_search.enabled; never reached by the sweep.
svc.mentions = newCustomersMentionSearch(svc.svc, b.customersMentionConfig, b.currentGitHubClient)
b.dashSrv.SetCustomersService(svc)
if b.sched != nil {
installCustomersAgentContext(svc, b.sched.SetCustomerContextLookup)
Expand Down
2 changes: 1 addition & 1 deletion src/docs/api-reference/customers.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The rules are enforced twice: by the handlers and again by the store's service o
| `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:176` |
| `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:177` |
| `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:178` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. With the optional body `{into}` (an existing customer id, or `me`) it attaches the suggestion to that customer instead: the identity becomes one of theirs, pinned as a manual decision, no new person is created, the activity moves onto them on the next sweep, and `unmerge` undoes it with the id in the target's merge history. Audited as `customer_accept`, or `customer_attach` with the target's id and never a name | `pkg/dashboard/api_customers.go:179` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. With the optional body `{into}` (an existing customer id, or `me`) it attaches the suggestion to that customer instead: the identity becomes one of theirs, pinned as a manual decision, no new person is created, the activity moves onto them on the next sweep, and `unmerge` undoes it with the id in the target's merge history. Audited as `customer_accept`, or `customer_attach` with the target's id and never a name. When `customers.mention_search.enabled` is on and the suggestion is a GitHub login, a budgeted background GitHub search adds `mentioned_in` and `commented_on` edges after the accept (see the design doc, step E) | `pkg/dashboard/api_customers.go:179` |
| `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:180` |
| `POST` | `/api/customers/hints/{hid}/answer` | Full view | Answer a "Same person?" question: `{same}`. `true` makes the suggested identity the customer's own and deletes the suggestion; `false` closes the question for good. A question between two customers is answered by merging them, so `true` on one is 400. Audited as `customer_hint_answer` | `pkg/dashboard/api_customers.go:181` |
| `POST` | `/api/customers/{id}/merge` | Full view | Fold the customer `{from}` into this one: identities, tags, goals and activity move across and the merge is recorded. 409 for two dashboard users. Audited as `customer_merge` | `pkg/dashboard/api_customers.go:182` |
Expand Down
Loading
Loading