Files
buzz/crates/buzz-relay/src/api/profiles.rs
Kalvin C 3d26ed7dfd feat(relay): match verified names in profile search (#9019)
## Summary

`POST /profiles/search` only matches kind:0 `name` and `display_name`.
In communities that publish NIP-FI verified profiles, a person's surname
or directory username often appears only in their relay-signed
kind:30382, so typeahead cannot find them by it.

- Where the community advertises verified profiles, the search also
matches the `display_name`, `username` and `full_name` tags of each
current kind:30382 head signed by the relay key.
- Verified names need a trailing prefix of at least three characters, as
in NIP-50, so a short prefix doesn't make the relay rank every verified
head. kind:0 keeps one-character typeahead. Lookups from heads to
`events` also match `created_at`, so Postgres prunes to one partition.
- Results are paged by person. Each person returns their current kind:0,
when they have one, then their current kind:30382, when they have one,
whichever matched. A person is ranked by their best match across both
sources, using the existing tiers.
- NIP-11 `federated_identity.public_profile` gains `searchable: true`,
so clients can rely on the response instead of a separate kind:30382
read.
- Migration `0081` adds a GIN expression index over the head's name tags
on `nip_fi_profile_heads` (built-in `jsonb_path_query_first` and
`to_tsvector`, no new functions). The table holds one row per verified
person. Like `0078`, the migration builds the index only while the table
is empty; populated databases prebuild it with `CREATE INDEX
CONCURRENTLY` (`docs/profile-search.md`), and the migration then checks
it is valid and has the expected definition.

Compatibility: the request schema is unchanged. Existing clients that
keep only kind:0 events work as before and also find people who match
only by verified name. Trust stays pinned to the relay `self` key; the
event shape follows NIP-85 user assertions, but discovery is
relay-advertised rather than kind:10040.

## Testing

- `buzz-search` Postgres integration: new
`profile_names_match_verified_names` covers forged-key heads, replaced
heads, other communities, people without kind:0, per-person grouping,
paging, and words split across sources; the existing profile-name tests
pass unchanged. The test fails when the author filter is inverted.
- `buzz-relay` end to end in enforce mode:
`profile_search_matches_verified_names_where_advertised` publishes
through the real writer and finds the person by surname only where
verified profiles are advertised.
- Desired-state and migration index definitions match.
- `profile_names_use_verified_name_index` asserts the search scans the
new index. Migration `0081` checked against an empty table, a rerun, a
populated table without the index (raises), the documented concurrent
prebuild, and an index with a different definition (raises).
- Latency, 50k people each with a kind:0 and a verified head, release
build, local Postgres, best of 5, 30 people per page: 11–22 ms with
verified names versus 1–8 ms kind:0 only. `EXPLAIN` shows a bitmap scan
on the new index.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: Kalvin Chau <kalvin@block.xyz>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 21:25:15 -05:00

176 lines
6.3 KiB
Rust

//! Relay-owned profile name search.
//!
//! NIP-50 search over kind:0 matches the full profile JSON, so text inside
//! avatar data URLs, `about` and `nip05` competes with real names. This
//! endpoint keeps NIP-50 prefix matching and paging but applies them only to
//! the `name` and `display_name` fields of each current profile and, where
//! the community advertises verified profiles, to the names in each current
//! relay-signed kind:30382. Pages count people; each person returns their
//! signed kind:0 and, when they have one, their kind:30382.
use std::{collections::HashMap, sync::Arc};
use axum::{
extract::State,
http::{HeaderMap, StatusCode},
response::{IntoResponse, Json, Response},
};
use buzz_search::PROFILE_NAMES_PER_PAGE_MAX;
use serde::Deserialize;
use serde_json::Value;
use crate::state::AppState;
use super::{api_error, bridge, db_read_error, search_read_error};
/// Route path for profile name search.
pub(crate) const SEARCH_PATH: &str = "/profiles/search";
/// Longest accepted search text, in characters.
const QUERY_MAX_CHARS: usize = 100;
/// Page size when the request omits `limit`.
const DEFAULT_LIMIT: u32 = 20;
/// Highest accepted page, matching the NIP-50 search page ceiling.
const PAGE_MAX: u32 = 1000;
/// `POST /profiles/search` body.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct SearchRequest {
/// Text to find in `name` or `display_name`.
query: String,
/// Results per page, 1 through [`PROFILE_NAMES_PER_PAGE_MAX`].
limit: Option<u32>,
/// 1-based page of `limit` results, 1 through [`PAGE_MAX`].
page: Option<u32>,
}
/// A validated search: text, page size and page.
type Search = (String, u32, u32);
fn parse_request(body: &[u8]) -> Result<Search, (StatusCode, Json<Value>)> {
let request: SearchRequest = serde_json::from_slice(body)
.map_err(|_| api_error(StatusCode::BAD_REQUEST, "invalid profile search JSON"))?;
let query = request.query.trim();
if query.is_empty() || query.chars().count() > QUERY_MAX_CHARS {
return Err(api_error(
StatusCode::BAD_REQUEST,
&format!("query must be 1 through {QUERY_MAX_CHARS} characters"),
));
}
let limit = request.limit.unwrap_or(DEFAULT_LIMIT);
if !(1..=PROFILE_NAMES_PER_PAGE_MAX).contains(&limit) {
return Err(api_error(
StatusCode::BAD_REQUEST,
&format!("limit must be 1 through {PROFILE_NAMES_PER_PAGE_MAX}"),
));
}
let page = request.page.unwrap_or(1);
if !(1..=PAGE_MAX).contains(&page) {
return Err(api_error(
StatusCode::BAD_REQUEST,
&format!("page must be 1 through {PAGE_MAX}"),
));
}
Ok((query.to_owned(), limit, page))
}
/// Search people by profile and verified names for an authenticated member.
/// Responds with one page of signed kind:0 and kind:30382 events, best match
/// first.
pub async fn search(
State(state): State<Arc<AppState>>,
slot: crate::access::AccessSlot,
headers: HeaderMap,
body: axum::body::Bytes,
) -> Response {
search_inner(state, slot, headers, body)
.await
.into_response()
}
#[allow(clippy::result_large_err)] // Response is the natural error type for axum handlers
async fn search_inner(
state: Arc<AppState>,
slot: crate::access::AccessSlot,
headers: HeaderMap,
body: axum::body::Bytes,
) -> Result<Json<Value>, Response> {
// Admission first so the denial contract wins over request validation.
// [FI-TRACE-HTTP-INGRESS]
let (tenant, pubkey) =
bridge::authenticate_member_post(&state, &slot, &headers, SEARCH_PATH, &body).await?;
let (query, limit, page) = parse_request(&body).map_err(IntoResponse::into_response)?;
// Verified profiles count only where this community advertises them.
let verified_by = crate::verified_profiles::discovery(&state, &tenant)
.await
.map(|_| state.relay_keypair.public_key().to_bytes());
let hits = state
.search
.search_profile_names(tenant.community(), &query, verified_by, page, limit)
.await
.map_err(|e| search_read_error("profile search error", &e).into_response())?
.hits;
if hits.is_empty() {
return Ok(Json(Value::Array(Vec::new())));
}
let ids: Vec<&[u8]> = hits.iter().map(|hit| hit.event_id.as_slice()).collect();
let stored = state
.db
.get_events_by_ids_routed("profile_search_hydrate", tenant.community(), &ids)
.await
.map_err(|e| db_read_error("profile search fetch error", &e).into_response())?;
let mut by_id: HashMap<[u8; 32], &buzz_core::StoredEvent> = stored
.iter()
.map(|stored| (stored.event.id.to_bytes(), stored))
.collect();
// Keep search order. Search never widens visibility: apply the shared
// per-event read gate.
let reader = pubkey.to_bytes();
let events = hits
.iter()
.filter_map(|hit| by_id.remove(&hit.event_id))
.filter(|stored| crate::handlers::req::event_visible_to_reader(&stored.event, &reader))
.filter_map(|stored| serde_json::to_value(&stored.event).ok())
.collect();
Ok(Json(Value::Array(events)))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn request_validation_bounds_query_and_limit() {
assert_eq!(
parse_request(br#"{"query":" Wes "}"#).unwrap(),
("Wes".to_owned(), DEFAULT_LIMIT, 1)
);
assert_eq!(
parse_request(br#"{"query":"w","limit":100,"page":1000}"#).unwrap(),
("w".to_owned(), 100, 1000)
);
let long = "x".repeat(QUERY_MAX_CHARS + 1);
for body in [
br#"{"query":" "}"#.to_vec(),
format!(r#"{{"query":"{long}"}}"#).into_bytes(),
br#"{"query":"w","limit":0}"#.to_vec(),
br#"{"query":"w","limit":101}"#.to_vec(),
br#"{"query":"w","page":0}"#.to_vec(),
br#"{"query":"w","page":1001}"#.to_vec(),
br#"{"query":"w","search_mode":"prefix"}"#.to_vec(),
br#"{"q":"w"}"#.to_vec(),
b"not json".to_vec(),
] {
let (status, _) = parse_request(&body).unwrap_err();
assert_eq!(
status,
StatusCode::BAD_REQUEST,
"{}",
String::from_utf8_lossy(&body)
);
}
}
}