NOJIRA-peer-events-read-api - #1136
Merged
Merged
Conversation
Add a new read path over bin-timeline-manager's existing peer_events ClickHouse table (ingestion-only until now), letting square-admin/square-talk query raw peer/local activity for a contact's registered addresses or a single peer address. Returns rows as-is, including internal-resource noise (agent/AI/conference/SIP legs) that contact_interactions deliberately excludes; the client is responsible for any presentation-layer filtering. contact_interactions and its algorithm are left completely untouched -- this is purely additive. - bin-timeline-manager: models/peerevent (new package: PeerEvent, PeerPair, PeerEventListRequest/Response) - bin-timeline-manager: dbhandler.PeerEventList (ClickHouse OR-expansion query over peer_type+peer_target pairs, added to the DBHandler interface) - bin-timeline-manager: pkg/peereventhandler (new package, business logic + pagination, primitives-only interface matching eventhandler's pattern) - bin-timeline-manager: listenhandler GET /v1/peer-events route + DTOs (regex correctly matches both bare and query-string URIs) - bin-common-handler: requesthandler.TimelineV1PeerEventList (GET, mirrors TimelineV1AnalysisList's query-authority + body-filter shape) - bin-openapi-manager: new TimelineManagerPeerEvent / TimelineManagerPeerEventListResponse schemas, contact_peer_events and service_agents/contact_peer_events path specs - bin-api-manager: servicehandler.PeerEventList / ServiceAgentPeerEventList (resolvePeerPairs: contact_id resolves via existing contactGet + Contact.Addresses, or a single peer_type+peer_target passthrough; anti-enumeration ErrNotFound on cross-tenant contact_id) - bin-api-manager: GET /contact_peer_events and GET /service_agents/contact_peer_events server handlers - bin-api-manager: RST docs (contact_peer_event_overview, contact_peer_event_struct) + rebuilt docsdev/build HTML
- bin-timeline-manager: Store peer/local as full commonaddress.Address JSON columns in peer_events (migration 000006), replacing flat peer_type/ peer_target response fields; keep the flat columns internal-only for ORDER BY/WHERE search - bin-timeline-manager: Simplify PeerEventListRequest.PeerAddresses to []commonaddress.Address end-to-end, removing the PeerPair/PeerPairFilter primitive-type conversion layers - bin-common-handler: Update TimelineV1PeerEventList to the commonaddress.Address-based request/response shape - bin-api-manager: Rename resolvePeerPairs to resolvePeerAddresses, return []commonaddress.Address directly from Contact.Addresses or the single-address filter; rename API filter param to peer_address - bin-api-manager: Rebuild RST docs (contact_peer_event_overview.rst, contact_peer_event_struct.rst) and Sphinx HTML for the new commonaddress.Address-shaped PeerEvent struct - bin-openapi-manager: Update OpenAPI spec and generated types for the new PeerEvent/PeerEventListRequest shapes - docs: Record the post-approval redesign rationale in docs/plans/2026-07-24-peer-events-read-api-design.md (Round 4/5 review disposition + Section 16 explaining the peer/local JSON change)
- docs: Correct design doc section 16 point 4, which falsely claimed the external peer_type/peer_target query params were renamed to a single peer_address param -- they were not; only the servicehandler layer (one hop past the HTTP boundary) unifies them into commonaddress.Address - docs: Add section 17 recording the Round 1 PR review disposition (2 MAJOR, 2 MINOR, 0 BLOCKER) for commit 44501b2 - bin-api-manager: Add a Request vs. Response Shape note to contact_peer_event_overview.rst explaining why the peer_type/peer_target filter params stay flat while the response peer/local fields are full Address objects; rebuild Sphinx HTML - bin-timeline-manager: gofmt models/peerevent/peerevent.go (struct tag alignment) and pkg/dbhandler/main.go (import grouping)
…ction struct shape - bin-api-manager: Reword contact_peer_event_struct.rst and contact_peer_event_overview.rst -- both previously claimed peer/local match Contact Interactions' or Contact's Address shape, but no Interaction struct page exists in docsdev/source/ and Contact.Address is a genuinely different shape (id/type/target/is_primary/tm_create vs commonaddress.Address's type/target/target_name/name/detail). Now states plainly that peer/local are commonaddress.Address, the platform's standard cross-service address type, distinct from Contact's Address; rebuild Sphinx HTML - docs: Record Round 2 PR review disposition in design doc section 18
…er_events tests - bin-api-manager: contact_peer_events_test.go and its ServiceAgents counterpart now assert the exact contactID/commonaddress.Address the handler constructs from contact_id or peer_type+peer_target, instead of gomock.Any() -- closes a coverage gap Round 3 flagged (the two-param to Address construction in contact_peer_events.go was previously unverified by the test suite) - docs: Record Round 3 PR review disposition in design doc section 19 (APPROVE #1 of the required 2 consecutive APPROVEs)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a new read-only API path over bin-timeline-manager's existing
peer_events ClickHouse table (ingestion was added and merged in a prior
session, PR #1135; the read path was explicitly scoped out at the time).
Lets square-admin/square-talk query raw peer/local address activity for a
contact's registered addresses (contact_id) or a single peer address
(peer_type + peer_target). Returns rows as-is, including internal-resource
noise (agent/AI/conference/SIP legs) that contact_interactions deliberately
excludes -- by explicit product decision, no server-side eligibility filter
is applied; clients are responsible for any presentation-layer filtering.
contact_interactions and its algorithm are left completely untouched; this
is purely additive.
Post-approval, peer/local were redesigned from flat peer_type/peer_target
strings to full commonaddress.Address objects (matching contact_interactions'
own Peer/Local shape), stored as new JSON columns in peer_events
(migration 000006) alongside the existing internal-only flat search
columns. The external peer_type/peer_target query params are unchanged;
only the response shape and internal request/filter plumbing were
unified onto commonaddress.Address end to end. Went through a 5-round
adversarial PR review loop (2 consecutive clean APPROVEs) that caught and
fixed 3 documentation-accuracy defects and 1 test-coverage gap; no
BLOCKER-level code defects were found. Full history recorded in
docs/plans/2026-07-24-peer-events-read-api-design.md sections 14-21.
Peer/Local as commonaddress.Address, PeerEventListRequest/Response)
query over peer_type+peer_target pairs derived from commonaddress.Address,
added to the DBHandler interface); migration 000006 adds peer/local JSON
columns alongside the existing internal-only flat search columns
pagination, commonaddress.Address-based interface matching
eventhandler's pattern)
TimelineV1AnalysisList's query-authority + body-filter shape)
TimelineManagerPeerEventListResponse schemas, contact_peer_events and
service_agents/contact_peer_events path specs
(resolvePeerAddresses: contact_id resolves via existing contactGet +
Contact.Addresses, or a single peer_type+peer_target passthrough
constructed into commonaddress.Address; anti-enumeration ErrNotFound on
cross-tenant contact_id)
GET /service_agents/contact_peer_events server handlers
contact_peer_event_struct) + rebuilt docsdev/build HTML
the full 5-round PR review loop disposition