Skip to content
Open
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
33 changes: 22 additions & 11 deletions internal/connector/admission/boost_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -240,17 +240,28 @@ func TestNoAgentWakesAnAgentByBoosting(t *testing.T) {
}

func TestABoostSettledFromItsPointerCostsNoRead(t *testing.T) {
t.Run("in a project connect.json does not serve", func(t *testing.T) {
f := newFakeReads()
boostOn(f, "Comment", agentID, operatorID)
ev := boostEvent(operatorID)
ev.BucketID = unservedProj

v := decide(t, newAdmitter(t, basePolicy(), f), ev)
assert.Equal(t, StateDiscarded, v.State, "never blocked: a holding reply to a boost answers nobody")
assert.Equal(t, ReasonNoRoute, v.Reason)
assert.Zero(t, f.totalReads())
})
// A connector that hears Pings asks whether the bucket is one, since a
// boost in a Ping is heard (ping_boosts_test.go); nothing past that read.
for name, hears := range map[string]bool{"in a project connect.json does not serve": false, "in a project connect.json does not serve, by a connector that hears Pings": true} {
t.Run(name, func(t *testing.T) {
f := newFakeReads()
boostOn(f, "Comment", agentID, operatorID)
ev := boostEvent(operatorID)
ev.BucketID = unservedProj
p := basePolicy()
p.HearsPings = hears

v := decide(t, newAdmitter(t, p, f), ev)
assert.Equal(t, StateDiscarded, v.State, "never blocked: a holding reply to a boost answers nobody")
assert.Equal(t, ReasonNoRoute, v.Reason)
if hears {
assert.Equal(t, 1, f.pingCalls)
assert.Equal(t, 1, f.totalReads(), "the Ping read alone")
} else {
assert.Zero(t, f.totalReads())
}
})
}

t.Run("on one of the recording's events", func(t *testing.T) {
f := newFakeReads()
Expand Down
7 changes: 5 additions & 2 deletions internal/connector/admission/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@
// 2. A chat line in a bucket connect.json does not serve is read as a Ping
// (Reads.Pings), because where the line was said decides whose word
// counts, and that comes before anyone's trust is read. A bucket that
// is no Ping goes on as an unserved project's; its answer is cached.
// is no Ping goes on as an unserved project's; its answer is cached. A
// boost there is read the same way by the connector that hears Pings,
// and is heard only in a Ping.
// 3. In project trust mode a performer the policy does not name is confirmed
// as a non-client member of the project. That is a read, cached per
// project, and it is the one trust decision the pointer alone cannot make.
Expand All @@ -29,7 +31,8 @@
// completed (trusted completer and a stake: the served project's
// watch_completions flag, an assignment, or a subscription), or boosted
// (a boost on the recording itself, which the agent wrote, given by the
// trusted performer; a boost on one of a recording's events is not), or,
// trusted performer, in a served project or on the agent's line in a
// Ping; a boost on one of a recording's events is not), or,
// in a Ping, pinged (an operator's line in a direct Ping, the agent and
// its writer alone; in a group Ping, and from a participant anywhere,
// only a mention counts), or campfire (a trusted human's new line in a
Expand Down
8 changes: 5 additions & 3 deletions internal/connector/admission/gate.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ type GateResult struct {
Agent bool
// InPing says the performer is trusted only as a participant of the Ping
// the event's bucket is keyed as (Policy.Pings): only once the Ping read
// confirms the bucket is a Ping, and only by mention.
// confirms the bucket is a Ping, and only by mention or by boosting the
// agent's own line there.
InPing bool
}

Expand Down Expand Up @@ -99,7 +100,8 @@ func Gate(ev Event, p Policy, m Matrix) GateResult {
case role == RoleOperator:
// Named in the allowlist; Validate keeps one out of operator mode.
case !served && p.pingParticipant(ev.BucketID, performer):
// Let into this one Ping, by mention (matchPing). Before project
// Let into this one Ping, by mention or a boost on the agent's
// line there (matchPing, matchPingBoost). Before project
// trust, which would ask a Ping for members it does not have; a
// served bucket is a project, whatever a Ping entry is keyed on.
inPing = true
Expand All @@ -109,7 +111,7 @@ func Gate(ev Event, p Policy, m Matrix) GateResult {
drop(ReasonUntrustedPerformer)
continue
}
if rule.RequiresServed && !served {
if rule.RequiresServed && !served && (!rule.HeardInPings || !p.HearsPings) {
drop(ReasonNoRoute)
continue
}
Expand Down
11 changes: 9 additions & 2 deletions internal/connector/admission/matrix.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,11 @@ type Rule struct {
// trigger is discarded there, so it is cheaper to discard it before any
// read.
RequiresServed bool
// HeardInPings keeps a RequiresServed rule open outside a served project
// for a connector that hears the agent's Pings (Policy.HearsPings), so
// that the Ping read can say whether the bucket is a Ping. Decide admits
// it there only in a Ping, and discards it as no_route anywhere else.
HeardInPings bool
// Acknowledge says a person asked for something, so the worker's
// acknowledgement and the thirty-second guard apply. A completion, a
// subscription comment or a boost is not a request.
Expand All @@ -58,8 +63,10 @@ var (
// is not acknowledged. It requires a served project because nothing in an
// unserved one waits on it: blocked(no_route) would post a holding reply
// to a thumbs-up. Who may boost is whoever may mention the agent, in
// every trust mode, so it is not OperatorOnly.
ruleBoosted = Rule{Trigger: TriggerBoosted, RequiresServed: true}
// every trust mode, so it is not OperatorOnly. A Ping is never served,
// and the agent's lines there are answered as its comments are in a
// project, so a boost is heard in a Ping too.
ruleBoosted = Rule{Trigger: TriggerBoosted, RequiresServed: true, HeardInPings: true}
// Only a line in a Ping admits under pinged, and a Ping is never a served
// project, so the rule is not in the matrix: matchPing returns it.
rulePinged = Rule{Trigger: TriggerPinged, Acknowledge: true}
Expand Down
195 changes: 195 additions & 0 deletions internal/connector/admission/ping_boosts_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
package admission

import (
"testing"

"github.com/basecamp/basecamp-sdk/go/pkg/basecamp"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

// A boost in a Ping: someone boosts a line in a Ping the agent is in. It is
// heard as a boost on the agent's comment is in a project — a reply, from
// whoever may mention the agent there — and only by the connector that hears
// the agent's Pings.

// boostInPing puts a line author wrote in the Ping whose others are people,
// boosted by booster, and returns the boost's event.
func boostInPing(t *testing.T, f *fakeReads, people []int64, author, booster int64) Event {
t.Helper()
inPing(f, people, author, "<div>Shall I ship the fix?</div>")
f.boosts[boostID] = &basecamp.Boost{
ID: boostID,
Content: "yes, go",
CreatedAt: boostedAt,
Booster: &basecamp.Person{ID: booster, Name: "Booster"},
Recording: &basecamp.Parent{ID: recordingID, Type: "Chat::Lines::RichText"},
}
return Event{
ID: eventID, EventType: "boost.created", BucketID: pingID, RecordingID: recordingID,
CreatorID: booster, Details: boostDetailsJSON(boostID, nil),
}
}

func TestTheOperatorsBoostOnTheAgentsPingLineIsAdmittedAsAReply(t *testing.T) {
for name, people := range map[string][]int64{
"a direct Ping": {operatorID},
"a group Ping": {operatorID, memberID},
} {
t.Run(name, func(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, people, agentID, operatorID)

v := decide(t, newAdmitter(t, basePolicy(), f), ev)

require.Equal(t, StateAdmitted, v.State, "reason %q", v.Reason)
assert.Equal(t, TriggerBoosted, v.Trigger)
assert.False(t, v.Acknowledge, "a boost is a reply, not a request")
assert.Equal(t, RoleOperator, v.Role)
assert.Equal(t, operatorID, v.RequesterID)
assert.Equal(t, &ReplyDestination{Kind: ReplyChatLine, RecordingID: pingCampfire}, v.Reply)
assert.Equal(t, PingConversationKey(pingID), v.ConversationKey)
assert.True(t, IsPingConversation(v.ConversationKey, pingID), "handed off as a Ping's")
assert.False(t, v.Served)
require.NotNil(t, v.Snapshot)
assert.Equal(t, "yes, go", v.Snapshot.Content, "the boost is the content")
assert.False(t, v.Snapshot.Owner, "a boost is never the owner's word on the connector")
assert.Empty(t, v.Snapshot.ProjectName)
// As in a project: the operator's boost names the line as the ask
// it would answer, and the ledger decides whether one was declared.
assert.Equal(t, recordingID, v.AskRecordingID)
assert.Equal(t, "Chat::Lines::RichText", f.summaryRefs[0].RecordingType)
})
}
}

func TestAPersonAllowedInOnePingMayBoostTheAgentsLineThere(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, []int64{operatorID, pingGuest}, agentID, pingGuest)

v := decide(t, newAdmitter(t, guestPolicy(basePolicy()), f), ev)

require.Equal(t, StateAdmitted, v.State, "reason %q", v.Reason)
assert.Equal(t, TriggerBoosted, v.Trigger)
assert.Equal(t, RoleParticipant, v.Role)
assert.Equal(t, pingGuest, v.RequesterID)
assert.Zero(t, v.AskRecordingID, "only the operator's boost may be a go")
assert.False(t, v.Snapshot.Owner)
}

func TestABoostInAPingIsTrustedLikeAMentionThere(t *testing.T) {
t.Run("someone the policy does not name is discarded unread", func(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, []int64{operatorID, strangerID}, agentID, strangerID)

v := decide(t, newAdmitter(t, basePolicy(), f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, ReasonUntrustedPerformer, v.Reason)
assert.Zero(t, f.totalReads())
})

t.Run("a person let into another Ping is nobody in this one", func(t *testing.T) {
f := newFakeReads()
p := basePolicy()
p.Pings = map[int64]PingTrust{otherPing: {Participants: []int64{pingGuest}}}
ev := boostInPing(t, f, []int64{operatorID, pingGuest}, agentID, pingGuest)

v := decide(t, newAdmitter(t, p, f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, ReasonUntrustedPerformer, v.Reason)
assert.Zero(t, f.boostCalls)
assert.Zero(t, f.summaryCalls)
})

t.Run("in project trust a member is nobody in a Ping", func(t *testing.T) {
f := newFakeReads()
f.members[pingID] = map[int64]bool{memberID: true}
ev := boostInPing(t, f, []int64{operatorID, memberID}, agentID, memberID)

v := decide(t, newAdmitter(t, projectPolicy(), f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, ReasonUntrustedPerformer, v.Reason)
assert.Zero(t, f.memberCalls, "a Ping has no members to ask about")
assert.Zero(t, f.boostCalls)
})

t.Run("a boost whose booster is not the performer", func(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, []int64{operatorID, strangerID}, agentID, strangerID)
ev.CreatorID = operatorID

v := decide(t, newAdmitter(t, basePolicy(), f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, ReasonUntrustedAuthor, v.Reason)
})

t.Run("no agent wakes the agent by boosting in a Ping", func(t *testing.T) {
for name, c := range map[string]struct {
policy Policy
ev func(Event) Event
want Reason
}{
"the agent itself": {basePolicy(), func(ev Event) Event { ev.CreatorID = agentID; return ev }, ReasonAgentAuthored},
"an allowed agent": {agentPolicy(), func(ev Event) Event { ev.CreatorID = peerAgent; return ev }, ReasonNoRoute},
"a person's boost an agent performed": {basePolicy(), func(ev Event) Event {
ev.PerformedByID = ptr(otherAgent)
return ev
}, ReasonDelegated},
} {
t.Run(name, func(t *testing.T) {
f := newFakeReads()
ev := c.ev(boostInPing(t, f, []int64{operatorID}, agentID, operatorID))

v := decide(t, newAdmitter(t, c.policy, f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, c.want, v.Reason)
assert.Zero(t, f.totalReads())
})
}
})
}

func TestABoostOnSomeoneElsesPingLineIsNotTheAgents(t *testing.T) {
for name, author := range map[string]int64{
"the operator's own line": operatorID,
"someone else's line": memberID,
"another agent's line": otherAgent,
} {
t.Run(name, func(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, []int64{operatorID, memberID}, author, operatorID)

v := decide(t, newAdmitter(t, basePolicy(), f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, ReasonNotAddressed, v.Reason)
assert.Nil(t, v.Snapshot)
assert.Zero(t, v.AskRecordingID)
})
}
}

// Only the connector that hears the agent's Pings hears a boost in one, so
// one boost is answered once. Any other discards it at the gate, unread.
func TestAConnectorThatDoesNotHearPingsDiscardsABoostInOne(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, []int64{operatorID}, agentID, operatorID)
p := basePolicy()
p.HearsPings = false

v := decide(t, newAdmitter(t, p, f), ev)
assert.Equal(t, StateDiscarded, v.State)
assert.Equal(t, ReasonNoRoute, v.Reason)
assert.Zero(t, f.totalReads())
}

func TestABoostInAPingWithConnectJSONUnreadableIsHeld(t *testing.T) {
f := newFakeReads()
ev := boostInPing(t, f, []int64{operatorID}, agentID, operatorID)
p := basePolicy()
p.ProjectsUnknown = true

v := decide(t, newAdmitter(t, p, f), ev)
assert.Equal(t, StateBlocked, v.State)
assert.Equal(t, ReasonConfigUnreadable, v.Reason)
assert.Zero(t, f.totalReads())
}
33 changes: 29 additions & 4 deletions internal/connector/admission/verdict.go
Original file line number Diff line number Diff line change
Expand Up @@ -368,8 +368,11 @@ func (a *Admitter) Decide(ctx context.Context, ev Event) (out Verdict, err error

// Where the line was said decides whose word counts, so it is settled
// before anyone's trust is read: a Ping has no members to ask about.
// A boost outside a served project passed the gate only to be asked
// about here (Rule.HeardInPings): it is heard in a Ping alone.
_, served := policy.served(ev.BucketID)
var ping *basecamp.Ping
if _, served := policy.served(ev.BucketID); !served && ev.EventType == eventChatLineCreated {
if !served && (ev.EventType == eventChatLineCreated || boostID > 0) {
var reason Reason
if ping, reason, err = d.pingOf(ctx, ev.BucketID); err != nil {
return Verdict{}, err
Expand All @@ -390,6 +393,11 @@ func (a *Admitter) Decide(ctx context.Context, ev Event) (out Verdict, err error
return v.end(StateDiscarded, ReasonUntrustedPerformer), nil
}
}
if boostID > 0 && !served && ping == nil {
// A project connect.json does not serve. Never blocked: a holding
// reply to a boost answers nobody.
return v.end(StateDiscarded, ReasonNoRoute), nil
}
if gate.InPing && ping == nil {
// Trusted only in a Ping, and the bucket is none the agent is in.
return v.end(StateDiscarded, ReasonUntrustedPerformer), nil
Expand Down Expand Up @@ -470,10 +478,15 @@ func (a *Admitter) Decide(ctx context.Context, ev Event) (out Verdict, err error
state State
reason Reason
)
if ping != nil {
switch {
case ping != nil && boost != nil:
rule, state, reason = a.matchPingBoost(summary, shape)
case ping != nil:
rule, author, state, reason = a.matchPing(summary, ping, gate.Role)
} else if rule, author, state, reason, err = d.match(ctx, ev, policy, gate, summary); err != nil {
return Verdict{}, err
default:
if rule, author, state, reason, err = d.match(ctx, ev, policy, gate, summary); err != nil {
return Verdict{}, err
}
}
if state != "" {
return v.end(state, reason), nil
Expand Down Expand Up @@ -706,6 +719,18 @@ func (a *Admitter) matchPing(summary *basecamp.RecordingSummary, ping *basecamp.
return Rule{}, "", StateDiscarded, ReasonNotAddressed
}

// matchPingBoost decides what a boost in a Ping is to the agent. The booster
// was an operator at the gate, or a participant connect.json lets into this
// Ping, and wrote the boost (readBoost): it is a reply when the boosted line
// is the agent's own, as a boost on the agent's comment is in a project.
// A boost on anyone else's line in a Ping says nothing to the agent.
func (a *Admitter) matchPingBoost(summary *basecamp.RecordingSummary, shape shape) (Rule, State, Reason) {
if shape == shapeChatLine && summary.Creator.ID == a.policy.AgentID {
return ruleBoosted, "", ""
}
return Rule{}, StateDiscarded, ReasonNotAddressed
}

// direct reports whether the Ping is the agent and the writer alone. People
// are the others in it as the agent sees it. Basecamp carries no group flag,
// so a group that has shrunk to the two of them reads as direct, which it now
Expand Down
4 changes: 1 addition & 3 deletions skills/basecamp-connect/subagent.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,7 @@ A Ping has no project and no AGENTS.md: skip the AGENTS.md paragraph below, and
the repo the handoff names, or none. A group Ping's other people read the
reply too. Its `role` is `operator`, or `participant` for a person the
operator let into this one Ping: *A participant asks, an operator authorizes*
applies, with two differences. The operator's go there is only their
@mention of the agent saying go: a boost in a Ping never reaches the agent,
so don't say a boost is a go. And when the operator isn't among the Ping's
applies, with one difference: when the operator isn't among the Ping's
people (`basecamp pings show <bucket_id> --json -P '<profile>'`), they can't
see the ask: say in the Ping that this needs the operator's word, and stop
there.
Expand Down
Loading