From 74149e223cdfbf8b39778e09f0c0808bb5c370c6 Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 09:16:31 +0530 Subject: [PATCH 01/23] Put embedding and rerank calls behind a model gateway (R22 part 1) CircuitBreaker and Bulkhead were empty classes, and provider calls only had their own timeouts: no shared budget, concurrency limit, retry policy, fallback or usage accounting. - CircuitBreaker (opens after 5 failures, one trial call after 30s) and Bulkhead (bounded concurrency and queue per provider) - model-gateway.ts wraps both ports: per-operation time budgets that cover retries, abort signals so a timed-out request really stops, one or two jittered retries for 429/5xx/timeouts/network errors only - Fallbacks: a failed query embedding returns null (search matches by words); a failed profile embedding throws (the job's own backoff retries later); a failed rerank keeps the scored order - Search has a 6-second total budget split between query embedding and rerank; a rerank is skipped when under 750 ms remain - Migration 0013: model_usage records every call (provider, operation, outcome, latency, characters), kept 90 days by the sweep --- .../application/ports/embedding-provider.ts | 10 +- .../web/src/application/ports/llm-provider.ts | 3 +- apps/web/src/application/ports/model-usage.ts | 10 ++ apps/web/src/composition/container.ts | 8 +- apps/web/src/domain/matching/pipeline.ts | 13 +- .../matching/stages/llm-rerank.stage.ts | 11 +- .../postgres/model-usage.repo.ts | 9 ++ .../providers/gemini-embedding.provider.ts | 6 +- .../providers/gemini-llm.provider.ts | 5 +- .../providers/local-bge.provider.ts | 6 +- .../infrastructure/providers/model-gateway.ts | 147 ++++++++++++++++++ .../src/infrastructure/resilience/bulkhead.ts | 50 +++++- .../resilience/circuit-breaker.ts | 49 +++++- packages/db/migrations/0013_model_gateway.sql | 22 +++ packages/db/src/index.ts | 1 + packages/db/src/repositories/housekeeping.ts | 2 + packages/db/src/repositories/model-usage.ts | 42 +++++ 17 files changed, 374 insertions(+), 20 deletions(-) create mode 100644 apps/web/src/application/ports/model-usage.ts create mode 100644 apps/web/src/infrastructure/postgres/model-usage.repo.ts create mode 100644 apps/web/src/infrastructure/providers/model-gateway.ts create mode 100644 packages/db/migrations/0013_model_gateway.sql create mode 100644 packages/db/src/repositories/model-usage.ts diff --git a/apps/web/src/application/ports/embedding-provider.ts b/apps/web/src/application/ports/embedding-provider.ts index 4ee3b2a..4c5def3 100644 --- a/apps/web/src/application/ports/embedding-provider.ts +++ b/apps/web/src/application/ports/embedding-provider.ts @@ -1,5 +1,13 @@ +/** Limits a caller can put on one provider call. */ +export interface ProviderCallOptions { + /** The most time this call may take, including retries. */ + timeoutMs?: number; + /** Aborts the underlying request when the caller gives up. */ + signal?: AbortSignal; +} + export interface EmbeddingProvider { /** Provider and model; vectors from different ids are different spaces and never mixed. */ readonly id: string; - embed(text: string, task: "profile" | "query"): Promise; + embed(text: string, task: "profile" | "query", options?: ProviderCallOptions): Promise; } diff --git a/apps/web/src/application/ports/llm-provider.ts b/apps/web/src/application/ports/llm-provider.ts index 8e38241..12fef3f 100644 --- a/apps/web/src/application/ports/llm-provider.ts +++ b/apps/web/src/application/ports/llm-provider.ts @@ -1,10 +1,11 @@ import type { MatchCandidate } from "../../domain/matching/match-strategy"; import type { ParticipantProfile } from "../../domain/participant/participant.entity"; +import type { ProviderCallOptions } from "./embedding-provider"; export interface LlmProvider { /** Identifies the provider and model, recorded with every reranked result. */ readonly id: string; /** Bump when the prompt changes, so cached explanations are not reused across prompts. */ readonly promptVersion: string; - rerank(viewer: ParticipantProfile, candidates: MatchCandidate[]): Promise; + rerank(viewer: ParticipantProfile, candidates: MatchCandidate[], options?: ProviderCallOptions): Promise; } diff --git a/apps/web/src/application/ports/model-usage.ts b/apps/web/src/application/ports/model-usage.ts new file mode 100644 index 0000000..cf123a8 --- /dev/null +++ b/apps/web/src/application/ports/model-usage.ts @@ -0,0 +1,10 @@ +/** Records each model provider call for usage, cost and reliability reports. Never blocks the call. */ +export interface ModelUsageLog { + record(entry: { + provider: string; + operation: string; + outcome: "ok" | "error" | "timeout" | "rejected"; + latencyMs: number; + inputChars: number; + }): void; +} diff --git a/apps/web/src/composition/container.ts b/apps/web/src/composition/container.ts index 05b44b7..b8b986a 100644 --- a/apps/web/src/composition/container.ts +++ b/apps/web/src/composition/container.ts @@ -11,6 +11,8 @@ import { PostgresExplanationCache } from "../infrastructure/cache/postgres-expla import { UpstashCandidateCache } from "../infrastructure/cache/upstash-candidate-cache"; import { RealtimeNotifier } from "../infrastructure/notifications/realtime.notifier"; import { ProviderRegistry } from "../infrastructure/providers/provider-registry"; +import { GatewayEmbeddingProvider, GatewayLlmProvider } from "../infrastructure/providers/model-gateway"; +import { PostgresModelUsageLog } from "../infrastructure/postgres/model-usage.repo"; import { MatchingPipeline } from "../domain/matching/pipeline"; const globalContainer = globalThis as typeof globalThis & { __matchMakerContainer?: ReturnType }; @@ -20,8 +22,10 @@ function buildContainer() { const matches = new PostgresMatchRepository(); const intros = new PostgresIntroRepository(); const events = new PostgresEventRepository(); - const embeddings = ProviderRegistry.embedding(); - const llm = ProviderRegistry.llm(); + const usage = new PostgresModelUsageLog(); + const embeddings = new GatewayEmbeddingProvider(ProviderRegistry.embedding(), usage); + const rawLlm = ProviderRegistry.llm(); + const llm = rawLlm ? new GatewayLlmProvider(rawLlm, usage) : null; const candidateCache = new UpstashCandidateCache(new PostgresCandidateCache()); return { participants, diff --git a/apps/web/src/domain/matching/pipeline.ts b/apps/web/src/domain/matching/pipeline.ts index 2ae079c..d5d661e 100644 --- a/apps/web/src/domain/matching/pipeline.ts +++ b/apps/web/src/domain/matching/pipeline.ts @@ -40,6 +40,10 @@ export interface MatchingInput { */ export const MATCHING_PIPELINE_VERSION = `v2.${SCORING_CONFIG.version}`; +/** Total time a search may spend on model calls; rerank is skipped if too little is left. */ +export const SEARCH_BUDGET_MS = 6_000; +const QUERY_EMBED_BUDGET_MS = 2_500; + /** The profile changed while matching ran; the newer job will publish instead. */ export class StaleRevisionError extends Error { constructor() { @@ -118,7 +122,7 @@ export class MatchingPipeline { * Both feed the score, so the same query ranks differently per person. */ /** Query embeddings are shared across replicas and searches for a day. */ - private embedQuery(query: string): Promise { + private embedQuery(query: string, timeoutMs: number): Promise { const normalized = query.trim().toLowerCase().replace(/\s+/g, " "); const key = createHash("sha256").update(JSON.stringify(["query-embedding", this.embeddings.id, normalized])).digest("hex"); return computeOnce({ @@ -126,15 +130,16 @@ export class MatchingPipeline { key, read: () => this.cache.getVector(key), write: (vector) => vector ? this.cache.setVector(key, vector, 24 * 60 * 60) : Promise.resolve(), - compute: () => this.embeddings.embed(normalized, "query"), + compute: () => this.embeddings.embed(normalized, "query", { timeoutMs }), shouldStore: (vector) => vector !== null, }); } private async search(input: MatchingInput, viewer: ParticipantProfile) { const query = input.query!.trim(); + const deadline = Date.now() + SEARCH_BUDGET_MS; const terms = queryTerms(query); - const queryEmbedding = await this.embedQuery(query); + const queryEmbedding = await this.embedQuery(query, Math.min(QUERY_EMBED_BUDGET_MS, deadline - Date.now())); const retrieved = await this.retrieve.execute({ eventId: input.eventId, viewerId: input.participantId, @@ -155,7 +160,7 @@ export class MatchingPipeline { }; }).sort((a, b) => b.score - a.score); const top = this.topK.execute(scored, input.limit ?? 12); - const { candidates: ranked } = await this.rerank.execute(viewer, top, queryContext(query)); + const { candidates: ranked } = await this.rerank.execute(viewer, top, queryContext(query), { timeoutMs: deadline - Date.now() }); return ranked; } } diff --git a/apps/web/src/domain/matching/stages/llm-rerank.stage.ts b/apps/web/src/domain/matching/stages/llm-rerank.stage.ts index df0e8c2..74cfaef 100644 --- a/apps/web/src/domain/matching/stages/llm-rerank.stage.ts +++ b/apps/web/src/domain/matching/stages/llm-rerank.stage.ts @@ -16,13 +16,16 @@ export interface RerankResult { * the model is not called and the scored order stands. A cached reason never * decides the order of a shortlist. */ +/** Below this much remaining time a rerank call is not worth starting. */ +const MIN_RERANK_MS = 750; + export class LlmRerankStage { constructor( private readonly provider: LlmProvider | null, private readonly cache: ExplanationCache | null = null ) {} - async execute(viewer: ParticipantProfile, candidates: MatchCandidate[], context = "profile"): Promise { + async execute(viewer: ParticipantProfile, candidates: MatchCandidate[], context = "profile", options: { timeoutMs?: number } = {}): Promise { const scored = { candidates: candidates.map(addFallbackReason), rankedBy: "score" }; if (!this.provider || candidates.length === 0) return scored; const provider = this.provider; @@ -34,9 +37,13 @@ export class LlmRerankStage { const cached = await this.readCache(keys); const withCached = candidates.map((candidate, index) => ({ ...candidate, reason: cached.get(keys[index]) ?? candidate.reason })); if (cached.size === candidates.length) return { candidates: withCached, rankedBy: "score" }; + // Too little of the request's budget left for a model call: keep the scored order. + if (options.timeoutMs !== undefined && options.timeoutMs < MIN_RERANK_MS) { + return { candidates: withCached.map(addFallbackReason), rankedBy: "score" }; + } try { - const reranked = await provider.rerank(viewer, candidates); + const reranked = await provider.rerank(viewer, candidates, { timeoutMs: options.timeoutMs }); await this.writeCache(viewer, reranked.filter((candidate) => candidate.reason).map((candidate) => ({ key: keyFor(candidate), candidateId: candidate.participant.attendeeId, reason: candidate.reason!, }))); diff --git a/apps/web/src/infrastructure/postgres/model-usage.repo.ts b/apps/web/src/infrastructure/postgres/model-usage.repo.ts new file mode 100644 index 0000000..a3dc7eb --- /dev/null +++ b/apps/web/src/infrastructure/postgres/model-usage.repo.ts @@ -0,0 +1,9 @@ +import { modelUsage } from "@match-maker/db"; +import type { ModelUsageLog } from "../../application/ports/model-usage"; + +export class PostgresModelUsageLog implements ModelUsageLog { + record(entry: Parameters[0]): void { + // Fire and forget: accounting must never slow down or fail a model call. + modelUsage.record(entry).catch((error) => console.warn("[usage] could not record", error)); + } +} diff --git a/apps/web/src/infrastructure/providers/gemini-embedding.provider.ts b/apps/web/src/infrastructure/providers/gemini-embedding.provider.ts index 940e965..0fc6024 100644 --- a/apps/web/src/infrastructure/providers/gemini-embedding.provider.ts +++ b/apps/web/src/infrastructure/providers/gemini-embedding.provider.ts @@ -1,11 +1,11 @@ -import type { EmbeddingProvider } from "../../application/ports/embedding-provider"; +import type { EmbeddingProvider, ProviderCallOptions } from "../../application/ports/embedding-provider"; const DIMENSIONS = 768; export class GeminiEmbeddingProvider implements EmbeddingProvider { readonly id = `gemini:gemini-embedding-001:${DIMENSIONS}`; - async embed(text: string, task: "profile" | "query"): Promise { + async embed(text: string, task: "profile" | "query", options: ProviderCallOptions = {}): Promise { const apiKey = process.env.GEMINI_API_KEY; if (!apiKey || !text.trim()) return null; const response = await fetch("https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent", { @@ -16,7 +16,7 @@ export class GeminiEmbeddingProvider implements EmbeddingProvider { taskType: task === "profile" ? "RETRIEVAL_DOCUMENT" : "RETRIEVAL_QUERY", outputDimensionality: DIMENSIONS, }), - signal: AbortSignal.timeout(15_000), + signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000), }); if (!response.ok) throw new Error(`Gemini embedding failed (${response.status}): ${(await response.text()).slice(0, 300)}`); const payload = await response.json() as { embedding?: { values?: number[] } }; diff --git a/apps/web/src/infrastructure/providers/gemini-llm.provider.ts b/apps/web/src/infrastructure/providers/gemini-llm.provider.ts index d0c9d5d..9a9ae80 100644 --- a/apps/web/src/infrastructure/providers/gemini-llm.provider.ts +++ b/apps/web/src/infrastructure/providers/gemini-llm.provider.ts @@ -1,4 +1,5 @@ import type { LlmProvider } from "../../application/ports/llm-provider"; +import type { ProviderCallOptions } from "../../application/ports/embedding-provider"; import type { MatchCandidate } from "../../domain/matching/match-strategy"; import type { ParticipantProfile } from "../../domain/participant/participant.entity"; @@ -11,7 +12,7 @@ export class GeminiLlmProvider implements LlmProvider { return `gemini:${process.env.GEMINI_LLM_MODEL || DEFAULT_MODEL}`; } - async rerank(viewer: ParticipantProfile, candidates: MatchCandidate[]): Promise { + async rerank(viewer: ParticipantProfile, candidates: MatchCandidate[], options: ProviderCallOptions = {}): Promise { const apiKey = process.env.GEMINI_API_KEY; if (!apiKey) return candidates; const model = process.env.GEMINI_LLM_MODEL || DEFAULT_MODEL; @@ -41,7 +42,7 @@ export class GeminiLlmProvider implements LlmProvider { contents: [{ parts: [{ text: prompt }] }], generationConfig: { temperature: 0.2, maxOutputTokens: 2048, responseMimeType: "application/json" }, }), - signal: AbortSignal.timeout(20_000), + signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000), }); if (!response.ok) throw new Error(`Gemini rerank failed (${response.status}): ${(await response.text()).slice(0, 300)}`); const payload = await response.json() as { candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }> }; diff --git a/apps/web/src/infrastructure/providers/local-bge.provider.ts b/apps/web/src/infrastructure/providers/local-bge.provider.ts index ea7fa99..e1d16c8 100644 --- a/apps/web/src/infrastructure/providers/local-bge.provider.ts +++ b/apps/web/src/infrastructure/providers/local-bge.provider.ts @@ -1,17 +1,17 @@ -import type { EmbeddingProvider } from "../../application/ports/embedding-provider"; +import type { EmbeddingProvider, ProviderCallOptions } from "../../application/ports/embedding-provider"; /** Adapter for an internal sentence-transformers inference endpoint. */ export class LocalBgeProvider implements EmbeddingProvider { readonly id = "local-bge:768"; - async embed(text: string): Promise { + async embed(text: string, _task: "profile" | "query" = "profile", options: ProviderCallOptions = {}): Promise { const endpoint = process.env.LOCAL_BGE_URL; if (!endpoint) return null; const response = await fetch(`${endpoint.replace(/\/$/, "")}/embed`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text, normalize: true }), - signal: AbortSignal.timeout(20_000), + signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000), }); if (!response.ok) throw new Error(`Local embedding service failed (${response.status})`); const result = await response.json() as { embedding?: number[] } | number[]; diff --git a/apps/web/src/infrastructure/providers/model-gateway.ts b/apps/web/src/infrastructure/providers/model-gateway.ts new file mode 100644 index 0000000..dec68dc --- /dev/null +++ b/apps/web/src/infrastructure/providers/model-gateway.ts @@ -0,0 +1,147 @@ +import type { EmbeddingProvider, ProviderCallOptions } from "../../application/ports/embedding-provider"; +import type { LlmProvider } from "../../application/ports/llm-provider"; +import type { ModelUsageLog } from "../../application/ports/model-usage"; +import type { MatchCandidate } from "../../domain/matching/match-strategy"; +import type { ParticipantProfile } from "../../domain/participant/participant.entity"; +import { Bulkhead, BulkheadFullError } from "../resilience/bulkhead"; +import { CircuitBreaker, CircuitOpenError } from "../resilience/circuit-breaker"; + +/** Per-operation limits: a time budget for the whole call and how many quick retries fit in it. */ +export interface GatewayPolicy { + timeoutMs: number; + retries: number; +} + +export const POLICIES = { + embedQuery: { timeoutMs: 2_500, retries: 1 }, + embedProfile: { timeoutMs: 15_000, retries: 2 }, + rerank: { timeoutMs: 20_000, retries: 1 }, +} satisfies Record; + +/** Rate limits, server errors, timeouts and network failures are worth one more try. */ +export function isTransient(error: unknown): boolean { + const message = error instanceof Error ? `${error.name} ${error.message}` : String(error); + return /\((429|5\d\d)\)|timeout|aborted|fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN/i.test(message); +} + +interface Guards { + breaker: CircuitBreaker; + bulkhead: Bulkhead; + usage: ModelUsageLog | null; +} + +/** + * Runs one provider call under the gateway's rules: a concurrency limit, a + * circuit breaker, a time budget for the whole call (including retries), and + * a couple of jittered retries for transient errors. Every attempt is + * recorded for usage and cost reports. Provider retries stay separate from + * background job retries, which take over when this gives up. + */ +export async function guardedCall(input: { + provider: string; + operation: string; + inputChars: number; + policy: GatewayPolicy; + budgetMs?: number; + guards: Guards; + call: (signal: AbortSignal) => Promise; +}): Promise { + const deadline = Date.now() + Math.min(input.policy.timeoutMs, input.budgetMs ?? Infinity); + for (let attempt = 0; ; attempt++) { + const remaining = deadline - Date.now(); + if (remaining <= 50) throw new Error(`${input.provider} ${input.operation} timeout: no time left in the budget`); + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(new Error(`${input.provider} ${input.operation} timeout`)), remaining); + const started = Date.now(); + try { + const result = await input.guards.bulkhead.run(() => input.guards.breaker.execute(() => input.call(controller.signal))); + input.guards.usage?.record({ provider: input.provider, operation: input.operation, outcome: "ok", latencyMs: Date.now() - started, inputChars: input.inputChars }); + return result; + } catch (error) { + const rejected = error instanceof CircuitOpenError || error instanceof BulkheadFullError; + const outcome = rejected ? "rejected" : controller.signal.aborted ? "timeout" : "error"; + input.guards.usage?.record({ provider: input.provider, operation: input.operation, outcome, latencyMs: Date.now() - started, inputChars: input.inputChars }); + const retryable = !rejected && (controller.signal.aborted ? false : isTransient(error)); + if (!retryable || attempt >= input.policy.retries) throw error; + const backoff = Math.min(100 * 2 ** attempt + Math.random() * 100, deadline - Date.now() - 100); + if (backoff <= 0) throw error; + await new Promise((resolve) => setTimeout(resolve, backoff)); + } finally { + clearTimeout(timer); + } + } +} + +/** + * Embedding calls through the gateway. A failed query embedding returns null, + * so search falls back to its word-matching path; a failed profile embedding + * throws, so the background job retries later. + */ +export class GatewayEmbeddingProvider implements EmbeddingProvider { + private readonly guards: Guards; + + constructor(private readonly inner: EmbeddingProvider, usage: ModelUsageLog | null) { + this.guards = { + breaker: new CircuitBreaker(`embeddings:${inner.id}`), + bulkhead: new Bulkhead(`embeddings:${inner.id}`, { maxConcurrent: 8, maxQueue: 32, queueTimeoutMs: 2_000 }), + usage, + }; + } + + get id(): string { + return this.inner.id; + } + + async embed(text: string, task: "profile" | "query", options: ProviderCallOptions = {}): Promise { + try { + return await guardedCall({ + provider: this.inner.id, + operation: `embed:${task}`, + inputChars: text.length, + policy: task === "query" ? POLICIES.embedQuery : POLICIES.embedProfile, + budgetMs: options.timeoutMs, + guards: this.guards, + call: (signal) => this.inner.embed(text, task, { ...options, signal }), + }); + } catch (error) { + if (task === "query") { + console.warn("[gateway] query embedding unavailable; searching by words", (error as Error).message); + return null; + } + throw error; + } + } +} + +/** Rerank calls through the gateway; failures surface so the stage keeps the scored order. */ +export class GatewayLlmProvider implements LlmProvider { + private readonly guards: Guards; + + constructor(private readonly inner: LlmProvider, usage: ModelUsageLog | null) { + this.guards = { + breaker: new CircuitBreaker(`llm:${inner.id}`), + bulkhead: new Bulkhead(`llm:${inner.id}`, { maxConcurrent: 4, maxQueue: 16, queueTimeoutMs: 2_000 }), + usage, + }; + } + + get id(): string { + return this.inner.id; + } + + get promptVersion(): string { + return this.inner.promptVersion; + } + + rerank(viewer: ParticipantProfile, candidates: MatchCandidate[], options: ProviderCallOptions = {}): Promise { + return guardedCall({ + provider: this.inner.id, + operation: "rerank", + inputChars: JSON.stringify(candidates.map((candidate) => candidate.participant.aboutMe ?? "")).length, + policy: POLICIES.rerank, + budgetMs: options.timeoutMs, + guards: this.guards, + call: (signal) => this.inner.rerank(viewer, candidates, { ...options, signal }), + }); + } +} diff --git a/apps/web/src/infrastructure/resilience/bulkhead.ts b/apps/web/src/infrastructure/resilience/bulkhead.ts index 579f032..126bd5a 100644 --- a/apps/web/src/infrastructure/resilience/bulkhead.ts +++ b/apps/web/src/infrastructure/resilience/bulkhead.ts @@ -1 +1,49 @@ -export class Bulkhead {} +/** Thrown when a provider already has as many calls running and waiting as allowed. */ +export class BulkheadFullError extends Error { + constructor(name: string) { + super(`${name} is busy`); + this.name = "BulkheadFullError"; + } +} + +/** + * Limits concurrent calls to one provider in this process. Extra calls wait + * in a bounded queue for at most `queueTimeoutMs`, so a slow provider cannot + * tie up every request or exceed its rate limits. + */ +export class Bulkhead { + private running = 0; + private readonly waiting: Array<() => void> = []; + + constructor( + private readonly name: string, + private readonly options: { maxConcurrent: number; maxQueue: number; queueTimeoutMs: number } = { maxConcurrent: 8, maxQueue: 32, queueTimeoutMs: 2_000 } + ) {} + + async run(call: () => Promise): Promise { + if (this.running >= this.options.maxConcurrent) await this.wait(); + this.running += 1; + try { + return await call(); + } finally { + this.running -= 1; + this.waiting.shift()?.(); + } + } + + private wait(): Promise { + if (this.waiting.length >= this.options.maxQueue) return Promise.reject(new BulkheadFullError(this.name)); + return new Promise((resolve, reject) => { + const turn = () => { + clearTimeout(timer); + resolve(); + }; + const timer = setTimeout(() => { + const index = this.waiting.indexOf(turn); + if (index >= 0) this.waiting.splice(index, 1); + reject(new BulkheadFullError(this.name)); + }, this.options.queueTimeoutMs); + this.waiting.push(turn); + }); + } +} diff --git a/apps/web/src/infrastructure/resilience/circuit-breaker.ts b/apps/web/src/infrastructure/resilience/circuit-breaker.ts index 4068672..8b1a2ae 100644 --- a/apps/web/src/infrastructure/resilience/circuit-breaker.ts +++ b/apps/web/src/infrastructure/resilience/circuit-breaker.ts @@ -1 +1,48 @@ -export class CircuitBreaker {} +/** Thrown instead of calling a provider that keeps failing. */ +export class CircuitOpenError extends Error { + constructor(name: string) { + super(`${name} is temporarily unavailable`); + this.name = "CircuitOpenError"; + } +} + +/** + * Stops calling a provider after `failureThreshold` consecutive failures, for + * `resetAfterMs`. Then one trial call is let through: success closes the + * circuit, failure opens it again. Keeps an outage from adding a timeout to + * every request. + */ +export class CircuitBreaker { + private failures = 0; + private openedAt: number | null = null; + private trialRunning = false; + + constructor( + private readonly name: string, + private readonly options: { failureThreshold: number; resetAfterMs: number } = { failureThreshold: 5, resetAfterMs: 30_000 }, + private readonly now: () => number = Date.now + ) {} + + get state(): "closed" | "open" | "half-open" { + if (this.openedAt === null) return "closed"; + return this.now() - this.openedAt >= this.options.resetAfterMs ? "half-open" : "open"; + } + + async execute(call: () => Promise): Promise { + const state = this.state; + if (state === "open" || (state === "half-open" && this.trialRunning)) throw new CircuitOpenError(this.name); + if (state === "half-open") this.trialRunning = true; + try { + const result = await call(); + this.failures = 0; + this.openedAt = null; + return result; + } catch (error) { + this.failures += 1; + if (state === "half-open" || this.failures >= this.options.failureThreshold) this.openedAt = this.now(); + throw error; + } finally { + if (state === "half-open") this.trialRunning = false; + } + } +} diff --git a/packages/db/migrations/0013_model_gateway.sql b/packages/db/migrations/0013_model_gateway.sql new file mode 100644 index 0000000..91fac31 --- /dev/null +++ b/packages/db/migrations/0013_model_gateway.sql @@ -0,0 +1,22 @@ +-- Model gateway accounting and versioned embeddings. +-- +-- model_usage: one row per provider call (provider and model, operation, +-- outcome, latency, approximate tokens) for cost and reliability reports. +-- Kept 90 days by the housekeeping sweep. +-- +-- event_participants.embedding_model: which provider/model produced the +-- stored vector. Vectors from different models live in different spaces and +-- are never compared; a profile embedded by another model is embedded again. + +create table if not exists model_usage ( + id bigserial primary key, + provider text not null, + operation text not null, + outcome text not null check (outcome in ('ok', 'error', 'timeout', 'rejected')), + latency_ms integer not null, + input_chars integer not null default 0, + created_at timestamptz not null default now() +); +create index if not exists idx_model_usage_created on model_usage (created_at); + +alter table event_participants add column if not exists embedding_model text; diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts index 596eb49..94bc070 100644 --- a/packages/db/src/index.ts +++ b/packages/db/src/index.ts @@ -13,3 +13,4 @@ export * as events from "./repositories/events"; export * as matchingJobs from "./repositories/matching-jobs"; export * as housekeeping from "./repositories/housekeeping"; export * as audit from "./repositories/audit"; +export * as modelUsage from "./repositories/model-usage"; diff --git a/packages/db/src/repositories/housekeeping.ts b/packages/db/src/repositories/housekeeping.ts index 7fe1803..c6798bb 100644 --- a/packages/db/src/repositories/housekeeping.ts +++ b/packages/db/src/repositories/housekeeping.ts @@ -1,6 +1,7 @@ import { query } from "../client"; import { deleteExpired as deleteExpiredChallenges } from "./login-challenges"; import { AUDIT_RETENTION_DAYS } from "./audit"; +import { USAGE_RETENTION_DAYS } from "./model-usage"; /** How long a dead row is kept before the sweep removes it. */ export const RETENTION = { @@ -28,6 +29,7 @@ export async function sweepExpired(): Promise { const cache = await query(`delete from retrieval_cache where expires_at < now()`); const explanations = await query(`delete from pair_explanations where expires_at < now()`); await query(`delete from cache_locks where expires_at < now()`); + await query(`delete from model_usage where created_at < now() - make_interval(days => $1)`, [USAGE_RETENTION_DAYS]); const audits = await query(`delete from audit_events where created_at < now() - make_interval(days => $1)`, [AUDIT_RETENTION_DAYS]); return { loginChallenges, rateLimitBuckets: buckets.rowCount ?? 0, retrievalCache: cache.rowCount ?? 0, diff --git a/packages/db/src/repositories/model-usage.ts b/packages/db/src/repositories/model-usage.ts new file mode 100644 index 0000000..fe003f8 --- /dev/null +++ b/packages/db/src/repositories/model-usage.ts @@ -0,0 +1,42 @@ +import { query } from "../client"; + +/** Usage rows are kept this long, then swept. */ +export const USAGE_RETENTION_DAYS = 90; + +export async function record(entry: { + provider: string; + operation: string; + outcome: "ok" | "error" | "timeout" | "rejected"; + latencyMs: number; + inputChars: number; +}): Promise { + await query( + `insert into model_usage (provider, operation, outcome, latency_ms, input_chars) values ($1, $2, $3, $4, $5)`, + [entry.provider, entry.operation, entry.outcome, Math.round(entry.latencyMs), entry.inputChars] + ); +} + +export interface UsageSummary { + provider: string; + operation: string; + calls: number; + failures: number; + avg_latency_ms: number; + p95_latency_ms: number; + /** Rough token estimate (characters / 4). */ + approx_tokens: number; +} + +export async function summary(hours = 24): Promise { + const { rows } = await query( + `select provider, operation, count(*)::int as calls, + count(*) filter (where outcome <> 'ok')::int as failures, + round(avg(latency_ms))::int as avg_latency_ms, + round(percentile_cont(0.95) within group (order by latency_ms))::int as p95_latency_ms, + (sum(input_chars) / 4)::int as approx_tokens + from model_usage where created_at > now() - make_interval(hours => $1) + group by provider, operation order by provider, operation`, + [hours] + ); + return rows; +} From b9fc8ee23fffe8f02b74e372676314fadafa9364 Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 09:16:31 +0530 Subject: [PATCH 02/23] Test the model gateway and add a usage report (R22 part 2) - Unit tests: circuit breaker open/half-open/close, bulkhead limits and queue timeout, transient-only retries with every attempt recorded, budget timeouts, query vs profile fallbacks, circuit stopping calls, and rerank skipped when the request is nearly out of time - npm run models:usage [-- ] reports calls, failures, average and p95 latency, approximate tokens and, with MODEL_PRICE_PER_1K_TOKENS, estimated cost per provider and operation --- package.json | 3 +- tests/unit/model-gateway.test.ts | 115 +++++++++++++++++++++++++++++++ tools/model-usage.ts | 28 ++++++++ 3 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 tests/unit/model-gateway.test.ts create mode 100644 tools/model-usage.ts diff --git a/package.json b/package.json index 1aa9a2d..36c262a 100644 --- a/package.json +++ b/package.json @@ -34,7 +34,8 @@ "account:revoke-sessions": "tsx tools/manage-account.ts revoke-sessions", "account:erase": "tsx tools/manage-account.ts erase", "jobs:failed": "tsx tools/manage-jobs.ts failed", - "jobs:retry": "tsx tools/manage-jobs.ts retry" + "jobs:retry": "tsx tools/manage-jobs.ts retry", + "models:usage": "tsx tools/model-usage.ts" }, "devDependencies": { "@types/node": "^22.10.2", diff --git a/tests/unit/model-gateway.test.ts b/tests/unit/model-gateway.test.ts new file mode 100644 index 0000000..4670b88 --- /dev/null +++ b/tests/unit/model-gateway.test.ts @@ -0,0 +1,115 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { CircuitBreaker, CircuitOpenError } from "@/src/infrastructure/resilience/circuit-breaker"; +import { Bulkhead, BulkheadFullError } from "@/src/infrastructure/resilience/bulkhead"; +import { GatewayEmbeddingProvider, GatewayLlmProvider, guardedCall, isTransient } from "@/src/infrastructure/providers/model-gateway"; +import { LlmRerankStage } from "@/src/domain/matching/stages/llm-rerank.stage"; +import type { ModelUsageLog } from "@/src/application/ports/model-usage"; +import { Intent } from "@/src/domain/participant/intent"; +import type { ParticipantProfile } from "@/src/domain/participant/participant.entity"; + +const usage = (): ModelUsageLog & { entries: Array<{ outcome: string }> } => { + const entries: Array<{ outcome: string }> = []; + return { entries, record: vi.fn((entry) => { entries.push(entry); }) }; +}; +const guards = (log = usage()) => ({ breaker: new CircuitBreaker("t"), bulkhead: new Bulkhead("t"), usage: log }); +const viewer: ParticipantProfile = { + eventId: "e", attendeeId: "v", name: "v", designation: null, domain: null, aboutMe: null, selfDescription: null, + yearsOfExperience: null, mostImpressiveBuild: null, intent: Intent.NETWORKING, interests: [], venueZone: null, visible: true, +}; + +beforeEach(() => { + vi.spyOn(console, "warn").mockImplementation(() => {}); +}); + +describe("circuit breaker", () => { + it("opens after repeated failures, then lets one trial call through", async () => { + let now = 0; + const breaker = new CircuitBreaker("p", { failureThreshold: 2, resetAfterMs: 1000 }, () => now); + const fail = () => breaker.execute(async () => { throw new Error("down"); }); + await expect(fail()).rejects.toThrow("down"); + await expect(fail()).rejects.toThrow("down"); + await expect(breaker.execute(async () => "ok")).rejects.toBeInstanceOf(CircuitOpenError); + now = 1000; + expect(breaker.state).toBe("half-open"); + await expect(breaker.execute(async () => "ok")).resolves.toBe("ok"); + expect(breaker.state).toBe("closed"); + }); +}); + +describe("bulkhead", () => { + it("limits concurrency, queues briefly, and rejects when full", async () => { + const bulkhead = new Bulkhead("p", { maxConcurrent: 1, maxQueue: 1, queueTimeoutMs: 50 }); + let release!: () => void; + const first = bulkhead.run(() => new Promise((resolve) => { release = () => resolve("first"); })); + const second = bulkhead.run(async () => "second"); + await expect(bulkhead.run(async () => "third")).rejects.toBeInstanceOf(BulkheadFullError); + release(); + await expect(Promise.all([first, second])).resolves.toEqual(["first", "second"]); + }); + + it("gives up waiting after the queue timeout", async () => { + const bulkhead = new Bulkhead("p", { maxConcurrent: 1, maxQueue: 5, queueTimeoutMs: 30 }); + const busy = bulkhead.run(() => new Promise((resolve) => setTimeout(resolve, 200))); + await expect(bulkhead.run(async () => "late")).rejects.toBeInstanceOf(BulkheadFullError); + await busy; + }); +}); + +describe("guarded provider calls", () => { + it("retries a transient error and records every attempt", async () => { + const log = usage(); + const call = vi.fn().mockRejectedValueOnce(new Error("Gemini embedding failed (429): slow down")).mockResolvedValue("ok"); + await expect(guardedCall({ provider: "p", operation: "embed:query", inputChars: 4, policy: { timeoutMs: 2000, retries: 1 }, guards: guards(log), call })) + .resolves.toBe("ok"); + expect(call).toHaveBeenCalledTimes(2); + expect(log.entries.map((entry) => entry.outcome)).toEqual(["error", "ok"]); + }); + + it("does not retry a permanent error", async () => { + const call = vi.fn().mockRejectedValue(new Error("Gemini embedding failed (400): bad request")); + await expect(guardedCall({ provider: "p", operation: "x", inputChars: 0, policy: { timeoutMs: 2000, retries: 2 }, guards: guards(), call })).rejects.toThrow("(400)"); + expect(call).toHaveBeenCalledTimes(1); + }); + + it("aborts a call that exceeds its budget", async () => { + const log = usage(); + const call = (signal: AbortSignal) => new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason))); + await expect(guardedCall({ provider: "p", operation: "x", inputChars: 0, policy: { timeoutMs: 10_000, retries: 2 }, budgetMs: 80, guards: guards(log), call })).rejects.toThrow(/timeout/); + expect(log.entries.map((entry) => entry.outcome)).toEqual(["timeout"]); + }); + + it("classifies transient errors", () => { + expect(isTransient(new Error("failed (503)"))).toBe(true); + expect(isTransient(new TypeError("fetch failed"))).toBe(true); + expect(isTransient(new Error("failed (401)"))).toBe(false); + }); +}); + +describe("gateway fallbacks", () => { + it("returns no query embedding on failure (search uses words) but surfaces profile failures", async () => { + const inner = { id: "m", embed: vi.fn().mockRejectedValue(new Error("failed (401)")) }; + const gateway = new GatewayEmbeddingProvider(inner, usage()); + await expect(gateway.embed("climate", "query")).resolves.toBeNull(); + await expect(gateway.embed("profile text", "profile")).rejects.toThrow("(401)"); + expect(gateway.id).toBe("m"); + }); + + it("stops calling a failing model once its circuit opens", async () => { + const inner = { id: "m", embed: vi.fn().mockRejectedValue(new Error("failed (500)")) }; + const gateway = new GatewayEmbeddingProvider(inner, usage()); + for (let i = 0; i < 6; i++) await gateway.embed("q", "query"); + const calls = inner.embed.mock.calls.length; + await gateway.embed("q", "query"); + expect(inner.embed.mock.calls.length).toBe(calls); + }); + + it("skips the rerank when the request has too little time left", async () => { + const rerank = vi.fn(async (_viewer, list) => list); + const llm = new GatewayLlmProvider({ id: "llm", promptVersion: "p1", rerank }, usage()); + const candidate = { participant: { ...viewer, attendeeId: "c" }, score: 50, scoreBreakdown: {}, mutualInterest: false, reason: null }; + const result = await new LlmRerankStage(llm).execute(viewer, [candidate], "profile", { timeoutMs: 200 }); + expect(rerank).not.toHaveBeenCalled(); + expect(result.rankedBy).toBe("score"); + expect(result.candidates[0].reason).toBeTruthy(); + }); +}); diff --git a/tools/model-usage.ts b/tools/model-usage.ts new file mode 100644 index 0000000..8c7400b --- /dev/null +++ b/tools/model-usage.ts @@ -0,0 +1,28 @@ +/** + * Model usage, reliability and approximate cost for the last N hours: + * + * npm run models:usage [-- ] + * + * Set MODEL_PRICE_PER_1K_TOKENS (USD) to include an estimated cost. + */ +import "dotenv/config"; +import { closePool, modelUsage } from "@match-maker/db"; +import { isMainModule } from "../packages/db/src/is-main"; + +if (isMainModule(import.meta.url)) { + const hours = Number(process.argv[2] ?? 24); + const price = Number(process.env.MODEL_PRICE_PER_1K_TOKENS ?? NaN); + try { + const rows = await modelUsage.summary(Number.isFinite(hours) && hours > 0 ? hours : 24); + if (!rows.length) console.info(`[usage] no model calls in the last ${hours} hours`); + for (const row of rows) { + const cost = Number.isFinite(price) ? ` ~$${((row.approx_tokens / 1000) * price).toFixed(4)}` : ""; + console.info(`[usage] ${row.provider} ${row.operation}: ${row.calls} calls, ${row.failures} failed, avg ${row.avg_latency_ms} ms, p95 ${row.p95_latency_ms} ms, ~${row.approx_tokens} tokens${cost}`); + } + } catch (error) { + console.error(`[usage] ${(error as Error).message}`); + process.exitCode = 1; + } finally { + await closePool(); + } +} From 0bb9a41868de825cabc72c60980ce1587c10820b Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 09:19:16 +0530 Subject: [PATCH 03/23] Version stored embeddings by model and never mix spaces (R22 part 3) Vectors from different providers or models live in different spaces, but nothing recorded which model produced a stored embedding, so switching providers would compare unrelated vectors. - event_participants.embedding_model (migration 0013) is written with every embedding (embedding_model of the gateway's provider id) - Retrieval ranks by vector only among candidates embedded by the query's model; others keep their place by text relevance - The semantic scorer and query relevance compare vectors only within one model, falling back to text otherwise - A profile embedded by another model (or before this change) is embedded again with the current one on its next matching run - Tests: scorer and relevance fallbacks, re-embedding, and real-Postgres retrieval that ignores an exact match from another model --- .../ports/participant-repository.ts | 6 ++- apps/web/src/domain/matching/pipeline.ts | 13 ++++-- .../matching/scorers/semantic.scorer.ts | 4 +- apps/web/src/domain/matching/search-query.ts | 5 +- .../domain/matching/stages/retrieve.stage.ts | 2 + .../domain/participant/participant.entity.ts | 2 + .../postgres/participant.repo.ts | 25 +++++----- packages/db/workers/embed.worker.ts | 2 +- tests/integration/search-retrieval.test.ts | 12 +++++ tests/unit/embedding-versions.test.ts | 46 +++++++++++++++++++ 10 files changed, 95 insertions(+), 22 deletions(-) create mode 100644 tests/unit/embedding-versions.test.ts diff --git a/apps/web/src/application/ports/participant-repository.ts b/apps/web/src/application/ports/participant-repository.ts index e03b7e2..c665385 100644 --- a/apps/web/src/application/ports/participant-repository.ts +++ b/apps/web/src/application/ports/participant-repository.ts @@ -12,6 +12,8 @@ export interface ParticipantRepository { /** Without an embedding, only candidates matching one of these words, best first. */ terms?: string[]; filters?: SearchFilters; + /** The model behind `embedding`; vectors from other models are not ranked against it. */ + embeddingModel?: string | null; limit?: number; }): Promise; /** Changes whenever the event's participants change; part of retrieval cache keys. */ @@ -19,9 +21,9 @@ export interface ParticipantRepository { /** Domains present among eligible participants, for the search filter. */ listDomains(eventId: string): Promise; findCandidatesByIds(eventId: string, ids: string[]): Promise; - setEmbedding(eventId: string, attendeeId: string, embedding: number[]): Promise; + setEmbedding(eventId: string, attendeeId: string, embedding: number[], model: string): Promise; /** Writes the embedding only while the profile is still at `revision`; false when it moved on. */ - setEmbeddingAt(eventId: string, attendeeId: string, embedding: number[], revision: number): Promise; + setEmbeddingAt(eventId: string, attendeeId: string, embedding: number[], revision: number, model: string): Promise; shareVenueZone(eventId: string, attendeeId: string, zone: string): Promise; hasEventAccess(eventId: string, attendeeId: string): Promise; } diff --git a/apps/web/src/domain/matching/pipeline.ts b/apps/web/src/domain/matching/pipeline.ts index d5d661e..fec3485 100644 --- a/apps/web/src/domain/matching/pipeline.ts +++ b/apps/web/src/domain/matching/pipeline.ts @@ -94,16 +94,19 @@ export class MatchingPipeline { if (input.mode === "search") return this.search(input, storedProfile); - const embedding = storedProfile.embedding ?? await this.embeddings.embed(profileText(storedProfile), "profile"); - if (embedding && !storedProfile.embedding) { - await this.participants.setEmbedding(input.eventId, input.participantId, embedding); + // A vector from another model is a different space: embed again with the current one. + const current = storedProfile.embeddingModel === this.embeddings.id ? storedProfile.embedding ?? null : null; + const embedding = current ?? await this.embeddings.embed(profileText(storedProfile), "profile"); + if (embedding && !current) { + await this.participants.setEmbedding(input.eventId, input.participantId, embedding, this.embeddings.id); } - const viewer = { ...storedProfile, embedding: embedding ?? storedProfile.embedding }; + const viewer = { ...storedProfile, embedding, embeddingModel: embedding ? this.embeddings.id : null }; const retrieved = await this.retrieve.execute({ eventId: input.eventId, viewerId: input.participantId, embedding, + embeddingSpace: this.embeddings.id, limit: 50, }); const compatible = this.filter.execute(viewer, retrieved); @@ -152,7 +155,7 @@ export class MatchingPipeline { }); const compatible = this.filter.execute(viewer, retrieved); const scored = this.score.execute(viewer, compatible).map((candidate) => { - const relevance = queryRelevance(terms, queryEmbedding, candidate.participant); + const relevance = queryRelevance(terms, queryEmbedding, candidate.participant, this.embeddings.id); return { ...candidate, score: searchScore(relevance, candidate.score), diff --git a/apps/web/src/domain/matching/scorers/semantic.scorer.ts b/apps/web/src/domain/matching/scorers/semantic.scorer.ts index a89f0b7..3b9dd49 100644 --- a/apps/web/src/domain/matching/scorers/semantic.scorer.ts +++ b/apps/web/src/domain/matching/scorers/semantic.scorer.ts @@ -7,7 +7,9 @@ export class SemanticScorer implements Scorer { readonly weight = SCORING_CONFIG.weights.semantic; score(viewer: ParticipantProfile, candidate: ParticipantProfile): number { - const vectorScore = cosineSimilarity(viewer.embedding, candidate.embedding); + // Vectors from different models are not comparable; use the text fallback instead. + const sameSpace = viewer.embeddingModel === undefined || candidate.embeddingModel === undefined || viewer.embeddingModel === candidate.embeddingModel; + const vectorScore = sameSpace ? cosineSimilarity(viewer.embedding, candidate.embedding) : 0; if (vectorScore > 0) return vectorScore; const left = tokenize([viewer.aboutMe, viewer.selfDescription, viewer.mostImpressiveBuild].join(" ")); const right = tokenize([candidate.aboutMe, candidate.selfDescription, candidate.mostImpressiveBuild].join(" ")); diff --git a/apps/web/src/domain/matching/search-query.ts b/apps/web/src/domain/matching/search-query.ts index 31ee5aa..216c7ac 100644 --- a/apps/web/src/domain/matching/search-query.ts +++ b/apps/web/src/domain/matching/search-query.ts @@ -62,8 +62,9 @@ export function lexicalRelevance(terms: string[], profile: ParticipantProfile): } /** How well a candidate answers the query: semantic when both vectors exist, otherwise lexical. */ -export function queryRelevance(terms: string[], queryEmbedding: number[] | null, profile: ParticipantProfile): number { - const semantic = cosineSimilarity(queryEmbedding, profile.embedding); +export function queryRelevance(terms: string[], queryEmbedding: number[] | null, profile: ParticipantProfile, queryModel?: string): number { + const comparable = queryModel === undefined || profile.embeddingModel === undefined || profile.embeddingModel === queryModel; + const semantic = comparable ? cosineSimilarity(queryEmbedding, profile.embedding) : 0; return semantic > 0 ? semantic : lexicalRelevance(terms, profile); } diff --git a/apps/web/src/domain/matching/stages/retrieve.stage.ts b/apps/web/src/domain/matching/stages/retrieve.stage.ts index 019b01d..e7c6598 100644 --- a/apps/web/src/domain/matching/stages/retrieve.stage.ts +++ b/apps/web/src/domain/matching/stages/retrieve.stage.ts @@ -46,6 +46,7 @@ export class RetrieveStage { eventId: input.eventId, excludeAttendeeId: null, embedding: input.embedding, + embeddingModel: input.embeddingSpace, terms: input.terms, filters, limit, @@ -62,6 +63,7 @@ export class RetrieveStage { eventId: input.eventId, excludeAttendeeId: input.viewerId, embedding: input.embedding, + embeddingModel: input.embeddingSpace, limit, }); } diff --git a/apps/web/src/domain/participant/participant.entity.ts b/apps/web/src/domain/participant/participant.entity.ts index f27cd4c..fed1537 100644 --- a/apps/web/src/domain/participant/participant.entity.ts +++ b/apps/web/src/domain/participant/participant.entity.ts @@ -26,6 +26,8 @@ export interface ParticipantProfile { /** Version of the event's profile form this profile was saved under. */ formVersion?: number; embedding?: number[] | null; + /** The provider/model that produced `embedding`; vectors are only compared within one model. */ + embeddingModel?: string | null; } export type ParticipantProfileInput = Pick< diff --git a/apps/web/src/infrastructure/postgres/participant.repo.ts b/apps/web/src/infrastructure/postgres/participant.repo.ts index 962a390..a12541c 100644 --- a/apps/web/src/infrastructure/postgres/participant.repo.ts +++ b/apps/web/src/infrastructure/postgres/participant.repo.ts @@ -24,6 +24,7 @@ interface ProfileRow { profile_updated_at?: Date | null; profile_form_version?: number; profile_revision?: number; + embedding_model?: string | null; } const PROFILE_COLUMNS = `p.event_id, a.id as attendee_id, a.name, @@ -34,7 +35,7 @@ const PROFILE_COLUMNS = `p.event_id, a.id as attendee_id, a.name, coalesce(p.years_of_experience, a.years_of_experience) as years_of_experience, coalesce(p.most_impressive_build, a.most_impressive_build) as most_impressive_build, p.intent, p.interests, - p.venue_zone, p.visible, p.embedding::text as embedding, p.profile_updated_at, p.profile_form_version, p.profile_revision::int as profile_revision`; + p.venue_zone, p.visible, p.embedding::text as embedding, p.profile_updated_at, p.profile_form_version, p.profile_revision::int as profile_revision, p.embedding_model`; const PROFILE_FROM = `from event_participants p join registered_attendees a on a.id = p.attendee_id`; /** @@ -95,6 +96,8 @@ export class PostgresParticipantRepository implements ParticipantRepository { embedding?: number[] | null; terms?: string[]; filters?: SearchFilters; + /** The model that produced `embedding`; only candidates embedded by it are ranked by vector. */ + embeddingModel?: string | null; limit?: number; }): Promise { const vector = toVector(input.embedding ?? null); @@ -106,13 +109,13 @@ export class PostgresParticipantRepository implements ParticipantRepository { and ($5::text is null or p.intent = $5) and ($6::text is null or lower(p.domain) = lower($6)) and ($7::text is null or ${SEARCH_DOCUMENT} @@ to_tsquery('simple', $7)) - order by case when $3::vector is not null and p.embedding is not null then 0 else 1 end, - p.embedding <=> $3::vector nulls last, + order by case when $3::vector is not null and p.embedding is not null and p.embedding_model is not distinct from $8 then 0 else 1 end, + case when p.embedding_model is not distinct from $8 then p.embedding <=> $3::vector end nulls last, case when $7::text is null then 0 else ts_rank(${SEARCH_DOCUMENT}, to_tsquery('simple', $7)) end desc, a.name asc limit $4`, [input.eventId, input.excludeAttendeeId, vector, Math.max(1, Math.min(100, input.limit ?? 50)), - input.filters?.intent ?? null, input.filters?.domain ?? null, tsQuery] + input.filters?.intent ?? null, input.filters?.domain ?? null, tsQuery, input.embeddingModel ?? null] ); return rows.map(mapProfile); } @@ -144,21 +147,20 @@ export class PostgresParticipantRepository implements ParticipantRepository { return rows.map(mapProfile); } - async setEmbeddingAt(eventId: string, attendeeId: string, embedding: number[], revision: number): Promise { + async setEmbeddingAt(eventId: string, attendeeId: string, embedding: number[], revision: number, model: string): Promise { const { rowCount } = await query( - `update event_participants set embedding = $3::vector, updated_at = now() + `update event_participants set embedding = $3::vector, embedding_model = $5, updated_at = now() where event_id = $1 and attendee_id = $2 and profile_revision = $4`, - [eventId, attendeeId, toVector(embedding), revision] + [eventId, attendeeId, toVector(embedding), revision, model] ); return (rowCount ?? 0) > 0; } - async setEmbedding(eventId: string, attendeeId: string, embedding: number[]): Promise { - const vector = toVector(embedding); + async setEmbedding(eventId: string, attendeeId: string, embedding: number[], model: string): Promise { await query( - `update event_participants set embedding = $3::vector, updated_at = now() + `update event_participants set embedding = $3::vector, embedding_model = $4, updated_at = now() where event_id = $1 and attendee_id = $2`, - [eventId, attendeeId, vector] + [eventId, attendeeId, toVector(embedding), model] ); } @@ -205,6 +207,7 @@ function mapProfile(row: ProfileRow): ParticipantProfile { profileComplete: Boolean(row.profile_updated_at), formVersion: row.profile_form_version ?? 0, revision: row.profile_revision ?? 0, + embeddingModel: row.embedding_model ?? null, profileRevision: row.profile_updated_at ? new Date(row.profile_updated_at).toISOString() : null, embedding: parseEmbedding(row.embedding), }; diff --git a/packages/db/workers/embed.worker.ts b/packages/db/workers/embed.worker.ts index 00553c1..4cd250e 100644 --- a/packages/db/workers/embed.worker.ts +++ b/packages/db/workers/embed.worker.ts @@ -21,7 +21,7 @@ export async function processEmbedJob(): Promise { return true; } const embedding = await container.embeddings.embed(profileText(profile), "profile"); - if (embedding && !(await container.participants.setEmbeddingAt(job.event_id, job.participant_id, embedding, job.revision))) { + if (embedding && !(await container.participants.setEmbeddingAt(job.event_id, job.participant_id, embedding, job.revision, container.embeddings.id))) { await matchingJobs.complete(job.id); return true; } diff --git a/tests/integration/search-retrieval.test.ts b/tests/integration/search-retrieval.test.ts index b404d42..66695d8 100644 --- a/tests/integration/search-retrieval.test.ts +++ b/tests/integration/search-retrieval.test.ts @@ -68,6 +68,18 @@ describeDb("search retrieval", () => { expect((await names({ eventId, excludeAttendeeId: null, filters: { intent: null, domain: "AI" } })).sort()).toEqual(["Ben Iyer", "Cy Das"]); }); + it("ranks by vector only among candidates embedded by the query's model", async () => { + const unit = (index: number) => Array.from({ length: 768 }, (_, i) => (i === index ? 1 : 0)); + // Ana's vector matches the query exactly but comes from another model; Ben's is close and from the same one. + await query(`update event_participants set embedding = $3::vector, embedding_model = 'other-model' where event_id = $1 and attendee_id = $2`, + [eventId, ids.designer, `[${unit(0).join(",")}]`]); + await query(`update event_participants set embedding = $3::vector, embedding_model = 'query-model' where event_id = $1 and attendee_id = $2`, + [eventId, ids.engineer, `[${unit(0).map((v, i) => (i === 1 ? 0.5 : v)).join(",")}]`]); + const ranked = await names({ eventId, excludeAttendeeId: null, embedding: unit(0), embeddingModel: "query-model" }); + expect(ranked[0]).toBe("Ben Iyer"); + expect(ranked).toContain("Ana Rao"); + }); + it("lists each domain present once", async () => { expect(await repo.listDomains(eventId)).toEqual(["AI", "Design"]); }); diff --git a/tests/unit/embedding-versions.test.ts b/tests/unit/embedding-versions.test.ts new file mode 100644 index 0000000..e57200b --- /dev/null +++ b/tests/unit/embedding-versions.test.ts @@ -0,0 +1,46 @@ +import { describe, expect, it, vi } from "vitest"; +import { SemanticScorer } from "@/src/domain/matching/scorers/semantic.scorer"; +import { queryRelevance } from "@/src/domain/matching/search-query"; +import { MatchingPipeline } from "@/src/domain/matching/pipeline"; +import type { ParticipantRepository } from "@/src/application/ports/participant-repository"; +import { Intent } from "@/src/domain/participant/intent"; +import type { ParticipantProfile } from "@/src/domain/participant/participant.entity"; + +const person = (attendeeId: string, overrides: Partial = {}): ParticipantProfile => ({ + eventId: "event", attendeeId, name: attendeeId, designation: null, domain: "AI", aboutMe: "builds search tools", selfDescription: null, + yearsOfExperience: null, mostImpressiveBuild: null, intent: Intent.NETWORKING, interests: [], venueZone: null, visible: true, + profileComplete: true, revision: 1, ...overrides, +}); + +describe("embeddings from different models", () => { + it("are never compared by the semantic scorer", () => { + const scorer = new SemanticScorer(); + const a = person("a", { embedding: [1, 0], embeddingModel: "model-a" }); + expect(scorer.score(a, person("b", { embedding: [1, 0], embeddingModel: "model-a" }))).toBeCloseTo(1); + // Same numbers, other model: falls back to the text overlap instead of a meaningless cosine. + expect(scorer.score(a, person("c", { embedding: [1, 0], embeddingModel: "model-b", aboutMe: "unrelated words" }))).toBeLessThan(0.5); + }); + + it("make query relevance fall back to words", () => { + const candidate = person("c", { embedding: [1, 0], embeddingModel: "old-model" }); + expect(queryRelevance(["nothing"], [1, 0], candidate, "new-model")).toBe(0); + expect(queryRelevance(["search"], [1, 0], candidate, "new-model")).toBe(1); + expect(queryRelevance(["nothing"], [1, 0], { ...candidate, embeddingModel: "new-model" }, "new-model")).toBeCloseTo(1); + }); + + it("are replaced: a profile embedded by another model is embedded again", async () => { + const viewer = person("viewer", { embedding: [0, 1], embeddingModel: "old-model" }); + const participants = { + findProfile: vi.fn(async () => viewer), + listCandidates: vi.fn(async () => []), + setEmbedding: vi.fn(), + } as unknown as ParticipantRepository; + const embeddings = { id: "new-model", embed: vi.fn(async () => [1, 0]) }; + const matches = { save: vi.fn(async () => true), listForParticipant: vi.fn() }; + const cache = { get: vi.fn(), set: vi.fn(), getVector: vi.fn(), setVector: vi.fn(), acquire: vi.fn(), release: vi.fn() }; + await new MatchingPipeline(participants, matches, embeddings, null, cache).run({ eventId: "event", participantId: "viewer", mode: "profile" }); + expect(embeddings.embed).toHaveBeenCalledWith(expect.any(String), "profile"); + expect(participants.setEmbedding).toHaveBeenCalledWith("event", "viewer", [1, 0], "new-model"); + expect(participants.listCandidates).toHaveBeenCalledWith(expect.objectContaining({ embedding: [1, 0], embeddingModel: "new-model" })); + }); +}); From 74c31db1c9d51a26f3feaf981235bda0f5960d51 Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 09:22:08 +0530 Subject: [PATCH 04/23] Deliver intro notifications through a durable outbox (R23 part 1) Notification e-mails were sent inline after the action and a failure was only logged, so a mail outage lost the message. - Migration 0014: notification_outbox (unique dedupe key, attempts, lease, last error) and location_requests (used by part 2); the sweep removes sent notifications after 30 days and location requests after a day - An intro request and its notification, and an acceptance and its notice to the requester, commit in one transaction - The worker delivers queued notifications with a 2-minute lease and backoff retries (30s ... 15 min, 5 attempts); details are read at send time and an interaction that no longer applies is closed without sending; replays never send twice - E-mails carry a deep link to the connection on the Connections page; the notifier gains location-request and reply messages - Real-Postgres tests: queued once with the request, delivered with the link, acceptance notice, and a failed send kept for retry --- .../web/src/application/ports/notification.ts | 16 +++- .../application/use-cases/request-intro.ts | 13 +--- .../application/use-cases/respond-to-intro.ts | 16 +--- .../notifications/realtime.notifier.ts | 32 +++++--- .../src/infrastructure/postgres/intro.repo.ts | 46 ++++++----- .../0014_outbox_location_requests.sql | 48 ++++++++++++ packages/db/src/index.ts | 1 + packages/db/src/repositories/events.ts | 6 ++ packages/db/src/repositories/housekeeping.ts | 4 + packages/db/src/repositories/outbox.ts | 76 +++++++++++++++++++ packages/db/workers/notification.worker.ts | 55 ++++++++++++++ packages/db/workers/worker.ts | 4 +- tests/integration/notification-outbox.test.ts | 74 ++++++++++++++++++ 13 files changed, 333 insertions(+), 58 deletions(-) create mode 100644 packages/db/migrations/0014_outbox_location_requests.sql create mode 100644 packages/db/src/repositories/outbox.ts create mode 100644 packages/db/workers/notification.worker.ts create mode 100644 tests/integration/notification-outbox.test.ts diff --git a/apps/web/src/application/ports/notification.ts b/apps/web/src/application/ports/notification.ts index 7db58ee..8bdd3bf 100644 --- a/apps/web/src/application/ports/notification.ts +++ b/apps/web/src/application/ports/notification.ts @@ -1,5 +1,17 @@ +/** One delivered message: who it goes to and the page it links to. */ +export interface NotificationTarget { + recipientEmail: string; + recipientName: string; + otherName: string; + eventName: string; + /** Deep link to the interaction, e.g. the connection on the Connections page. */ + link: string; +} + export interface NotificationPort { invitation(input: { email: string; name: string | null; eventName: string; organizationName: string; eventUrl: string }): Promise; - introRequested(input: { recipientEmail: string; recipientName: string; requesterName: string; eventName: string; introId: string }): Promise; - introResponded(input: { recipientEmail: string; recipientName: string; requesterName: string; eventName: string; accepted: boolean }): Promise; + introRequested(input: NotificationTarget): Promise; + introAccepted(input: NotificationTarget): Promise; + locationRequested(input: NotificationTarget): Promise; + locationAnswered(input: NotificationTarget & { zone: string | null }): Promise; } diff --git a/apps/web/src/application/use-cases/request-intro.ts b/apps/web/src/application/use-cases/request-intro.ts index ed31eee..7be99a7 100644 --- a/apps/web/src/application/use-cases/request-intro.ts +++ b/apps/web/src/application/use-cases/request-intro.ts @@ -1,13 +1,12 @@ import type { IntroRepository } from "../ports/intro-repository"; import type { ParticipantRepository } from "../ports/participant-repository"; -import type { NotificationPort } from "../ports/notification"; import { boundedText, LIMITS } from "../../domain/shared/validation"; import { INTRO_LIMITS, introRequestRefusal } from "../../domain/connection/connection.rules"; import type { RateLimiter } from "../ports/rate-limiter"; export async function requestIntro( input: { eventId: string; requesterId: string; recipientId: string; message?: string | null; eventName?: string }, - dependencies: { participants: ParticipantRepository; intros: IntroRepository; notifications?: NotificationPort; limiter?: RateLimiter } + dependencies: { participants: ParticipantRepository; intros: IntroRepository; limiter?: RateLimiter } ) { if (input.requesterId === input.recipientId) throw new Error("You cannot request an intro to yourself"); if (!(await dependencies.participants.hasEventAccess(input.eventId, input.requesterId))) throw new Error("You are not registered for this event"); @@ -26,15 +25,7 @@ export async function requestIntro( if (dependencies.limiter && !(await dependencies.limiter.consume(`intro:${input.eventId}:${input.requesterId}`, INTRO_LIMITS.perHour, 3600))) { throw new Error("You have sent many introduction requests this hour. Please try again later."); } + // The notification is queued with the request (outbox) and delivered by the worker. const intro = await dependencies.intros.create({ ...input, message }); - if (recipient.email && dependencies.notifications) { - await dependencies.notifications.introRequested({ - recipientEmail: recipient.email, - recipientName: recipient.name, - requesterName: requester.name, - eventName: input.eventName ?? "your event", - introId: intro.id, - }).catch((error) => console.warn("[intro] notification failed", error)); - } return intro; } diff --git a/apps/web/src/application/use-cases/respond-to-intro.ts b/apps/web/src/application/use-cases/respond-to-intro.ts index fe9492d..5f67aea 100644 --- a/apps/web/src/application/use-cases/respond-to-intro.ts +++ b/apps/web/src/application/use-cases/respond-to-intro.ts @@ -1,11 +1,10 @@ import type { IntroRepository } from "../ports/intro-repository"; -import type { NotificationPort } from "../ports/notification"; import type { ParticipantRepository } from "../ports/participant-repository"; import type { AuditLog } from "../ports/audit-log"; export async function respondToIntro( input: { eventId: string; introId: string; actorId: string; accept: boolean; eventName?: string }, - dependencies: { intros: IntroRepository; participants: ParticipantRepository; notifications?: NotificationPort; audit?: AuditLog } + dependencies: { intros: IntroRepository; participants: ParticipantRepository; audit?: AuditLog } ) { const existing = await dependencies.intros.findById(input.eventId, input.introId); if (!existing) throw new Error("Intro request not found"); @@ -16,18 +15,5 @@ export async function respondToIntro( if (updated.status === "accepted") { await dependencies.audit?.record({ eventId: input.eventId, actorId: input.actorId, action: "contacts.revealed", subjectId: updated.requesterId }); } - if (updated.status === "accepted" && dependencies.notifications) { - const requester = await dependencies.participants.findProfile(input.eventId, updated.requesterId); - const recipient = await dependencies.participants.findProfile(input.eventId, updated.recipientId); - if (requester?.email) { - await dependencies.notifications.introResponded({ - recipientEmail: requester.email, - recipientName: requester.name, - requesterName: recipient?.name ?? "Your connection", - eventName: input.eventName ?? "your event", - accepted: true, - }).catch((error) => console.warn("[intro] notification failed", error)); - } - } return updated; } diff --git a/apps/web/src/infrastructure/notifications/realtime.notifier.ts b/apps/web/src/infrastructure/notifications/realtime.notifier.ts index b5ca8fa..4b61de9 100644 --- a/apps/web/src/infrastructure/notifications/realtime.notifier.ts +++ b/apps/web/src/infrastructure/notifications/realtime.notifier.ts @@ -1,27 +1,35 @@ import { renderInvitationEmail, sendNotificationEmail } from "@match-maker/email"; -import type { NotificationPort } from "../../application/ports/notification"; +import type { NotificationPort, NotificationTarget } from "../../application/ports/notification"; export class RealtimeNotifier implements NotificationPort { async invitation(input: { email: string; name: string | null; eventName: string; organizationName: string; eventUrl: string }): Promise { await sendNotificationEmail({ to: input.email, ...renderInvitationEmail(input) }); } - async introRequested(input: { recipientEmail: string; recipientName: string; requesterName: string; eventName: string; introId: string }): Promise { - const subject = `${input.requesterName} would like to meet at ${input.eventName}`; - const text = `Hi ${input.recipientName},\n\n${input.requesterName} requested an introduction at ${input.eventName}. Sign in to Mr. Bridge to respond.`; - await sendNotificationEmail({ to: input.recipientEmail, subject, text, html: emailHtml(input.recipientName, input.requesterName, input.eventName, "requested an introduction. Sign in to Mr. Bridge to respond.") }); + introRequested(input: NotificationTarget): Promise { + return send(input, `${input.otherName} would like to meet at ${input.eventName}`, `${input.otherName} requested an introduction. Accept to share contact details.`, "Respond"); } - async introResponded(input: { recipientEmail: string; recipientName: string; requesterName: string; eventName: string; accepted: boolean }): Promise { - const status = input.accepted ? "accepted" : "declined"; - const subject = `Your introduction request was ${status}`; - const text = `Hi ${input.recipientName},\n\n${input.requesterName} ${status} your introduction request for ${input.eventName}.`; - await sendNotificationEmail({ to: input.recipientEmail, subject, text, html: emailHtml(input.recipientName, input.requesterName, input.eventName, `${status} your introduction request.`) }); + introAccepted(input: NotificationTarget): Promise { + return send(input, `${input.otherName} accepted your introduction`, `${input.otherName} accepted your introduction request. Their contact details are now on your Connections page.`, "See contact"); + } + + locationRequested(input: NotificationTarget): Promise { + return send(input, `${input.otherName} is asking where you are`, `${input.otherName} would like to find you at ${input.eventName}. Sharing your venue zone is up to you.`, "Reply"); + } + + locationAnswered(input: NotificationTarget & { zone: string | null }): Promise { + const text = input.zone ? `${input.otherName} is at ${input.zone}.` : `${input.otherName} would rather not share their location right now.`; + return send(input, input.zone ? `${input.otherName} is at ${input.zone}` : `${input.otherName} replied to your location request`, text, "Open connections"); } } -function emailHtml(name: string, otherPerson: string, event: string, action: string): string { - return `

Mr. Bridge

Hi ${escapeHtml(name)},

${escapeHtml(otherPerson)} ${escapeHtml(action)}

Event: ${escapeHtml(event)}

Open Mr. Bridge to view your connections.

`; +async function send(input: NotificationTarget, subject: string, line: string, action: string): Promise { + const text = `Hi ${input.recipientName},\n\n${line}\n\n${action}: ${input.link}`; + const html = `

Mr. Bridge

` + + `

Hi ${escapeHtml(input.recipientName)},

${escapeHtml(line)}

Event: ${escapeHtml(input.eventName)}

` + + `

${escapeHtml(action)}

`; + await sendNotificationEmail({ to: input.recipientEmail, subject, text, html }); } function escapeHtml(value: string): string { diff --git a/apps/web/src/infrastructure/postgres/intro.repo.ts b/apps/web/src/infrastructure/postgres/intro.repo.ts index 88595fe..652c159 100644 --- a/apps/web/src/infrastructure/postgres/intro.repo.ts +++ b/apps/web/src/infrastructure/postgres/intro.repo.ts @@ -1,4 +1,4 @@ -import { query } from "@match-maker/db"; +import { outbox, query, transaction } from "@match-maker/db"; import type { IntroRepository } from "../../application/ports/intro-repository"; import type { IntroRequest, IntroStatus } from "../../domain/connection/intro-request.entity"; @@ -20,14 +20,20 @@ export class PostgresIntroRepository implements IntroRepository { async create(input: { eventId: string; requesterId: string; recipientId: string; message?: string | null }): Promise { if (input.requesterId === input.recipientId) throw new Error("You cannot request an intro to yourself"); const message = input.message?.trim().slice(0, 500) || null; - const { rows } = await query( - `insert into intro_requests (event_id, requester_id, recipient_id, message) - values ($1, $2, $3, $4) - on conflict (event_id, requester_id, recipient_id) do nothing - returning ${INTRO_COLUMNS}`, - [input.eventId, input.requesterId, input.recipientId, message] - ); - if (rows[0]) return mapIntro(rows[0]); + // The request and its notification commit together, so neither is lost. + const created = await transaction(async (client) => { + const { rows } = await client.query( + `insert into intro_requests (event_id, requester_id, recipient_id, message) + values ($1, $2, $3, $4) + on conflict (event_id, requester_id, recipient_id) do nothing + returning ${INTRO_COLUMNS}`, + [input.eventId, input.requesterId, input.recipientId, message] + ); + if (!rows[0]) return null; + await outbox.enqueue({ eventId: input.eventId, recipientId: input.recipientId, kind: "intro.requested", subjectId: rows[0].id, dedupeKey: `intro.requested:${rows[0].id}` }, client); + return rows[0]; + }); + if (created) return mapIntro(created); throw new Error("An intro request already exists between these participants"); } @@ -40,14 +46,20 @@ export class PostgresIntroRepository implements IntroRepository { } async respond(eventId: string, introId: string, actorId: string, status: Extract): Promise { - const { rows } = await query( - `update intro_requests set status = $4, responded_at = now() - where event_id = $1 and id = $2 and recipient_id = $3 and status = 'pending' - returning ${INTRO_COLUMNS}`, - [eventId, introId, actorId, status] - ); - if (!rows[0]) throw new Error("Only the recipient can respond to a pending intro request"); - return mapIntro(rows[0]); + const updated = await transaction(async (client) => { + const { rows } = await client.query( + `update intro_requests set status = $4, responded_at = now() + where event_id = $1 and id = $2 and recipient_id = $3 and status = 'pending' + returning ${INTRO_COLUMNS}`, + [eventId, introId, actorId, status] + ); + if (rows[0]?.status === "accepted") { + await outbox.enqueue({ eventId, recipientId: rows[0].requester_id, kind: "intro.accepted", subjectId: rows[0].id, dedupeKey: `intro.accepted:${rows[0].id}` }, client); + } + return rows[0] ?? null; + }); + if (!updated) throw new Error("Only the recipient can respond to a pending intro request"); + return mapIntro(updated); } async findBetween(eventId: string, a: string, b: string): Promise { diff --git a/packages/db/migrations/0014_outbox_location_requests.sql b/packages/db/migrations/0014_outbox_location_requests.sql new file mode 100644 index 0000000..4cbc7e0 --- /dev/null +++ b/packages/db/migrations/0014_outbox_location_requests.sql @@ -0,0 +1,48 @@ +-- Reliable notifications and venue location requests. +-- +-- notification_outbox: written in the same transaction as the interaction it +-- announces (an intro request, an acceptance, a location request or reply), +-- then delivered by the worker with retries. dedupe_key makes each +-- notification unique, so retries and replays never send duplicates. +-- Sent rows are swept after 30 days. +-- +-- location_requests: "where are you?" between two accepted connections. The +-- recipient may reply with a configured venue zone or decline; the reply is +-- visible only to the person who asked, for 15 minutes. Pending requests +-- expire after 30 minutes. Rows are swept after a day. + +create table if not exists notification_outbox ( + id bigserial primary key, + event_id uuid references events(id) on delete cascade, + recipient_id uuid not null, + kind text not null, + subject_id uuid not null, + dedupe_key text not null unique, + status text not null default 'pending' check (status in ('pending', 'running', 'sent', 'failed')), + attempts integer not null default 0, + available_at timestamptz not null default now(), + lease_until timestamptz, + last_error text, + created_at timestamptz not null default now(), + sent_at timestamptz +); +create index if not exists idx_notification_outbox_due on notification_outbox (available_at) where status in ('pending', 'running'); + +create table if not exists location_requests ( + id uuid primary key default gen_random_uuid(), + event_id uuid not null references events(id) on delete cascade, + intro_id uuid not null references intro_requests(id) on delete cascade, + requester_id uuid not null, + recipient_id uuid not null, + status text not null default 'pending' check (status in ('pending', 'answered', 'declined')), + zone text, + created_at timestamptz not null default now(), + expires_at timestamptz not null, + answered_at timestamptz, + zone_expires_at timestamptz, + check (requester_id <> recipient_id) +); +-- One open request per direction of a connection. +create unique index if not exists idx_location_requests_one_pending + on location_requests (intro_id, requester_id) where status = 'pending'; +create index if not exists idx_location_requests_people on location_requests (event_id, recipient_id, created_at desc); diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts index 94bc070..a13636c 100644 --- a/packages/db/src/index.ts +++ b/packages/db/src/index.ts @@ -14,3 +14,4 @@ export * as matchingJobs from "./repositories/matching-jobs"; export * as housekeeping from "./repositories/housekeeping"; export * as audit from "./repositories/audit"; export * as modelUsage from "./repositories/model-usage"; +export * as outbox from "./repositories/outbox"; diff --git a/packages/db/src/repositories/events.ts b/packages/db/src/repositories/events.ts index 979dc01..f848286 100644 --- a/packages/db/src/repositories/events.ts +++ b/packages/db/src/repositories/events.ts @@ -126,6 +126,12 @@ export async function update(input: { return findBySlug(old.organization_slug, old.slug); } +/** Name and public slug, for notification text and links. */ +export async function basics(eventId: string): Promise<{ name: string; slug: string } | null> { + const { rows } = await query<{ name: string; slug: string }>(`select name, slug from events where id = $1`, [eventId]); + return rows[0] ?? null; +} + /** The event's status, or null when the event no longer exists. */ export async function statusOf(eventId: string): Promise { const { rows } = await query<{ status: EventRecord["status"] }>(`select status from events where id = $1`, [eventId]); diff --git a/packages/db/src/repositories/housekeeping.ts b/packages/db/src/repositories/housekeeping.ts index c6798bb..f918561 100644 --- a/packages/db/src/repositories/housekeeping.ts +++ b/packages/db/src/repositories/housekeeping.ts @@ -2,6 +2,7 @@ import { query } from "../client"; import { deleteExpired as deleteExpiredChallenges } from "./login-challenges"; import { AUDIT_RETENTION_DAYS } from "./audit"; import { USAGE_RETENTION_DAYS } from "./model-usage"; +import { SENT_RETENTION_DAYS } from "./outbox"; /** How long a dead row is kept before the sweep removes it. */ export const RETENTION = { @@ -30,6 +31,9 @@ export async function sweepExpired(): Promise { const explanations = await query(`delete from pair_explanations where expires_at < now()`); await query(`delete from cache_locks where expires_at < now()`); await query(`delete from model_usage where created_at < now() - make_interval(days => $1)`, [USAGE_RETENTION_DAYS]); + await query(`delete from notification_outbox where status = 'sent' and sent_at < now() - make_interval(days => $1)`, [SENT_RETENTION_DAYS]); + // Venue locations are only meaningful during the event day. + await query(`delete from location_requests where created_at < now() - interval '1 day'`); const audits = await query(`delete from audit_events where created_at < now() - make_interval(days => $1)`, [AUDIT_RETENTION_DAYS]); return { loginChallenges, rateLimitBuckets: buckets.rowCount ?? 0, retrievalCache: cache.rowCount ?? 0, diff --git a/packages/db/src/repositories/outbox.ts b/packages/db/src/repositories/outbox.ts new file mode 100644 index 0000000..ec6fa35 --- /dev/null +++ b/packages/db/src/repositories/outbox.ts @@ -0,0 +1,76 @@ +import { query, transaction } from "../client"; + +export type NotificationKind = "intro.requested" | "intro.accepted" | "location.requested" | "location.answered"; + +export interface OutboxItem { + id: number; + event_id: string | null; + recipient_id: string; + kind: NotificationKind; + subject_id: string; + attempts: number; +} + +export const MAX_ATTEMPTS = 5; +const LEASE_SECONDS = 120; +/** Sent notifications are kept this long, then swept. */ +export const SENT_RETENTION_DAYS = 30; + +/** + * Queues a notification. Pass the transaction's client so it commits or + * rolls back with the interaction it announces. A repeated dedupe key is + * ignored, so the same notification is never queued twice. + */ +export async function enqueue( + item: { eventId: string; recipientId: string; kind: NotificationKind; subjectId: string; dedupeKey: string }, + client: { query: typeof query } = { query } +): Promise { + await client.query( + `insert into notification_outbox (event_id, recipient_id, kind, subject_id, dedupe_key) + values ($1, $2, $3, $4, $5) on conflict (dedupe_key) do nothing`, + [item.eventId, item.recipientId, item.kind, item.subjectId, item.dedupeKey] + ); +} + +/** Claims the oldest due notification (or one whose sender crashed) for delivery. */ +export async function claim(onlyEventId: string | null = null): Promise { + return transaction(async (client) => { + await client.query( + `update notification_outbox set status = 'failed', last_error = coalesce(last_error, 'sender stopped responding') + where status = 'running' and lease_until < now() and attempts >= $1`, [MAX_ATTEMPTS]); + const { rows } = await client.query( + `with next_item as ( + select id from notification_outbox + where attempts < $1 and ($3::uuid is null or event_id = $3) + and ((status = 'pending' and available_at <= now()) or (status = 'running' and lease_until < now())) + order by available_at, id for update skip locked limit 1 + ) + update notification_outbox o set status = 'running', attempts = attempts + 1, lease_until = now() + make_interval(secs => $2) + from next_item where o.id = next_item.id + returning o.id::int as id, o.event_id, o.recipient_id, o.kind, o.subject_id, o.attempts`, + [MAX_ATTEMPTS, LEASE_SECONDS, onlyEventId] + ); + return rows[0] ?? null; + }); +} + +export async function markSent(id: number): Promise { + await query(`update notification_outbox set status = 'sent', sent_at = now(), lease_until = null where id = $1`, [id]); +} + +/** Retries after 30s, 60s, 120s... (capped at 15 minutes); fails for good after the last attempt. */ +export async function fail(id: number, error: string): Promise { + await query( + `update notification_outbox + set status = case when attempts >= $3 then 'failed' else 'pending' end, + available_at = now() + make_interval(secs => least(30 * power(2, greatest(attempts - 1, 0)), 900)), + lease_until = null, last_error = left($2, 1000) + where id = $1`, + [id, error, MAX_ATTEMPTS] + ); +} + +/** Nothing left to send (e.g. the interaction was deleted): close it without delivery. */ +export async function skip(id: number, reason: string): Promise { + await query(`update notification_outbox set status = 'sent', sent_at = now(), lease_until = null, last_error = $2 where id = $1`, [id, reason]); +} diff --git a/packages/db/workers/notification.worker.ts b/packages/db/workers/notification.worker.ts new file mode 100644 index 0000000..061844b --- /dev/null +++ b/packages/db/workers/notification.worker.ts @@ -0,0 +1,55 @@ +import { events, outbox, query } from "../src/index"; +import { getContainer } from "../../../apps/web/src/composition/container"; + +/** + * Delivers one queued notification. Details are read at send time, so the + * message reflects the current state; an interaction that no longer exists + * is closed without sending. Failures retry with backoff (see outbox.fail). + */ +export async function processNotification(onlyEventId: string | null = null): Promise { + const item = await outbox.claim(onlyEventId); + if (!item) return false; + try { + const delivered = await deliver(item); + if (delivered) await outbox.markSent(item.id); + else await outbox.skip(item.id, "nothing to send any more"); + } catch (error) { + console.error(`[worker:notify] ${item.kind} #${item.id} failed`, error); + await outbox.fail(item.id, error instanceof Error ? error.message : String(error)); + } + return true; +} + +async function deliver(item: outbox.OutboxItem): Promise { + if (!item.event_id) return false; + const { participants, notifications } = getContainer(); + const event = await events.basics(item.event_id); + const recipient = await participants.findProfile(item.event_id, item.recipient_id); + if (!event || !recipient?.email) return false; + + const base = (process.env.APP_BASE_URL || "").replace(/\/$/, ""); + if (item.kind === "intro.requested" || item.kind === "intro.accepted") { + const { rows: [intro] } = await query<{ requester_id: string; recipient_id: string; status: string }>( + `select requester_id, recipient_id, status from intro_requests where id = $1`, [item.subject_id]); + if (!intro || (item.kind === "intro.accepted" && intro.status !== "accepted")) return false; + const otherId = intro.requester_id === item.recipient_id ? intro.recipient_id : intro.requester_id; + const other = await participants.findProfile(item.event_id, otherId); + const target = { recipientEmail: recipient.email, recipientName: recipient.name, otherName: other?.name ?? "A participant", eventName: event.name, link: `${base}/e/${event.slug}/connections#intro-${item.subject_id}` }; + await (item.kind === "intro.requested" ? notifications.introRequested(target) : notifications.introAccepted(target)); + return true; + } + + const { rows: [request] } = await query<{ intro_id: string; requester_id: string; recipient_id: string; status: string; zone: string | null }>( + `select intro_id, requester_id, recipient_id, status, zone from location_requests where id = $1`, [item.subject_id]); + if (!request) return false; + const otherId = request.requester_id === item.recipient_id ? request.recipient_id : request.requester_id; + const other = await participants.findProfile(item.event_id, otherId); + const target = { recipientEmail: recipient.email, recipientName: recipient.name, otherName: other?.name ?? "A participant", eventName: event.name, link: `${base}/e/${event.slug}/connections#intro-${request.intro_id}` }; + if (item.kind === "location.requested") { + if (request.status !== "pending") return false; + await notifications.locationRequested(target); + } else { + await notifications.locationAnswered({ ...target, zone: request.status === "answered" ? request.zone : null }); + } + return true; +} diff --git a/packages/db/workers/worker.ts b/packages/db/workers/worker.ts index 5650e2d..80af71c 100644 --- a/packages/db/workers/worker.ts +++ b/packages/db/workers/worker.ts @@ -4,6 +4,7 @@ import { closePool } from "../src/client"; import { processEmbedJob } from "./embed.worker"; import { processMatchJob } from "./match.worker"; import { sweepIfDue } from "./housekeeping.worker"; +import { processNotification } from "./notification.worker"; let stopping = false; process.on("SIGINT", () => { stopping = true; }); @@ -16,7 +17,8 @@ async function main() { await sweepIfDue(); const embedded = await processEmbedJob(); const matched = await processMatchJob(); - if (!embedded && !matched) await new Promise((resolve) => setTimeout(resolve, 1200)); + const notified = await processNotification(); + if (!embedded && !matched && !notified) await new Promise((resolve) => setTimeout(resolve, 1200)); } await closePool(); console.info("[worker] stopped"); diff --git a/tests/integration/notification-outbox.test.ts b/tests/integration/notification-outbox.test.ts new file mode 100644 index 0000000..d917c70 --- /dev/null +++ b/tests/integration/notification-outbox.test.ts @@ -0,0 +1,74 @@ +/** + * Notifications go through an outbox written with the interaction, and are + * delivered with retries. Real Postgres; delivery uses the e-mail dev + * fallback. Claims are scoped to this test's event. Skipped without DATABASE_URL. + */ +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; +import { attendees, closePool, events, outbox, query } from "@match-maker/db"; +import { migrate } from "../../packages/db/src/migrate"; +import { PostgresIntroRepository } from "../../apps/web/src/infrastructure/postgres/intro.repo"; +import { processNotification } from "../../packages/db/workers/notification.worker"; +import { getContainer } from "../../apps/web/src/composition/container"; + +const describeDb = process.env.DATABASE_URL ? describe : describe.skip; +const RUN = Date.now().toString(36); +const ORG = `outbox-${RUN}`; +const email = (key: string) => `outbox-${key}-${RUN}@example.com`; + +describeDb("notification outbox", () => { + const intros = new PostgresIntroRepository(); + const ids: Record = {}; + let eventId: string; + let introId: string; + const queued = async () => (await query<{ kind: string; recipient_id: string; status: string; attempts: number; last_error: string | null }>( + `select kind, recipient_id, status, attempts, last_error from notification_outbox where event_id = $1 order by id`, [eventId])).rows; + + beforeAll(async () => { + process.env.EMAIL_DEV_FALLBACK = "true"; + await migrate(); + await attendees.upsertMany(["amy", "ben"].map((key) => ({ name: `Outbox ${key}`, email: email(key) }))); + for (const key of ["amy", "ben"]) ids[key] = (await attendees.findByEmail(email(key)))!.id; + const { rows: [org] } = await query<{ id: string }>(`insert into organizations (name, slug) values ($1, $1) returning id`, [ORG]); + eventId = (await query<{ id: string }>(`insert into events (organization_id, name, slug, status) values ($1, $2, $2, 'open') returning id`, [org.id, ORG])).rows[0].id; + await events.attachRoster(eventId, Object.values(ids)); + }); + + afterAll(async () => { + await query(`delete from organizations where slug = $1`, [ORG]); + await query(`delete from registered_attendees where email like $1`, [`outbox-%-${RUN}@example.com`]); + await closePool(); + }); + + it("queues the notification with the request, once", async () => { + introId = (await intros.create({ eventId, requesterId: ids.amy, recipientId: ids.ben })).id; + await outbox.enqueue({ eventId, recipientId: ids.ben, kind: "intro.requested", subjectId: introId, dedupeKey: `intro.requested:${introId}` }); + expect(await queued()).toEqual([expect.objectContaining({ kind: "intro.requested", recipient_id: ids.ben, status: "pending" })]); + }); + + it("delivers it with a link to the connection", async () => { + const info = vi.spyOn(console, "info").mockImplementation(() => {}); + expect(await processNotification(eventId)).toBe(true); + expect((await queued())[0].status).toBe("sent"); + const message = info.mock.calls.map((call) => String(call[0])).find((line) => line.includes(email("ben"))); + expect(message).toContain(`/e/${ORG}/connections#intro-${introId}`); + info.mockRestore(); + }); + + it("queues an acceptance notice for the requester", async () => { + await intros.respond(eventId, introId, ids.ben, "accepted"); + expect((await queued()).at(-1)).toMatchObject({ kind: "intro.accepted", recipient_id: ids.amy, status: "pending" }); + }); + + it("keeps a failed delivery for retry instead of losing it", async () => { + const container = getContainer(); + const failing = vi.spyOn(container.notifications, "introAccepted").mockRejectedValueOnce(new Error("Resend failed (503)")); + vi.spyOn(console, "error").mockImplementation(() => {}); + await processNotification(eventId); + expect((await queued()).at(-1)).toMatchObject({ status: "pending", attempts: 1, last_error: "Resend failed (503)" }); + failing.mockRestore(); + await query(`update notification_outbox set available_at = now() where event_id = $1 and status = 'pending'`, [eventId]); + vi.spyOn(console, "info").mockImplementation(() => {}); + await processNotification(eventId); + expect((await queued()).at(-1)).toMatchObject({ status: "sent", attempts: 2 }); + }); +}); From 0a9deda89b0ecb801b8e5befdc93a6e66c34c641 Mon Sep 17 00:00:00 2001 From: SURYANSH-RAI Date: Mon, 19 Oct 2026 09:25:44 +0530 Subject: [PATCH 05/23] Add "where are you?" location requests with voluntary replies (R23 part 2) "Ping zone" only overwrote the sender's own zone for every connection; there was no way to ask a connection where they are, and no reply. - domain/connection/location.rules.ts: a request is a question, not tracking. One open request per direction of an accepted connection; unanswered requests expire after 30 minutes; a shared zone is visible only to the person who asked, for 15 minutes; 10 requests per person and hour - LocationRepository (Postgres): creating a request and answering it (a configured zone, or "not now") each queue their notification in the same transaction, so the interaction is never lost - Connections page: "Ask where they are", an incoming request with "Share with " / "Not now", the reply or decline for the asker, and the existing broadcast labelled "Share with all my connections"; each connection has an anchor for e-mail deep links - Tests: state and rules, the use cases, real-Postgres visibility, expiry and replacement, and a browser run where the worker e-mails the request, acceptance, location request and reply --- .../e/[eventSlug]/connections/page.tsx | 32 ++++++-- apps/web/app/actions/intro.actions.ts | 37 ++++++++- .../application/ports/location-repository.ts | 14 ++++ .../use-cases/location-requests.ts | 34 ++++++++ apps/web/src/composition/container.ts | 2 + .../src/domain/connection/location.rules.ts | 33 ++++++++ .../infrastructure/postgres/location.repo.ts | 77 +++++++++++++++++++ tests/integration/location-requests.test.ts | 74 ++++++++++++++++++ tests/unit/location-requests.test.ts | 57 ++++++++++++++ 9 files changed, 353 insertions(+), 7 deletions(-) create mode 100644 apps/web/src/application/ports/location-repository.ts create mode 100644 apps/web/src/application/use-cases/location-requests.ts create mode 100644 apps/web/src/domain/connection/location.rules.ts create mode 100644 apps/web/src/infrastructure/postgres/location.repo.ts create mode 100644 tests/integration/location-requests.test.ts create mode 100644 tests/unit/location-requests.test.ts diff --git a/apps/web/app/(participant)/e/[eventSlug]/connections/page.tsx b/apps/web/app/(participant)/e/[eventSlug]/connections/page.tsx index f95bc06..e961833 100644 --- a/apps/web/app/(participant)/e/[eventSlug]/connections/page.tsx +++ b/apps/web/app/(participant)/e/[eventSlug]/connections/page.tsx @@ -1,13 +1,13 @@ import Link from "next/link"; import SignOutButton from "@/components/ui/SignOutButton"; -import { getParticipantConnections, respondToParticipantIntro, shareVenueZoneAction } from "../../../../actions/intro.actions"; +import { answerLocationAction, getParticipantConnections, requestLocationAction, respondToParticipantIntro, shareVenueZoneAction } from "../../../../actions/intro.actions"; import { requireParticipantEvent } from "@/src/lib/auth"; import { ActionForm } from "@/components/ui/form"; import { eventAllows } from "@/src/domain/shared/event-lifecycle"; export default async function ConnectionsPage({ params, searchParams }: { params: Promise<{ eventSlug: string }>; - searchParams: Promise<{ requested?: string; location?: string }>; + searchParams: Promise<{ requested?: string; location?: string; asked?: string; replied?: string; declined?: string }>; }) { const { eventSlug } = await params; const notice = await searchParams; @@ -18,9 +18,12 @@ export default async function ConnectionsPage({ params, searchParams }: { INTRODUCTIONS · {event.name}

Connections

{notice.requested &&

Intro request sent. You will see their contact details once they accept.

} - {notice.location &&

Your venue zone is shared with your accepted connections.

} + {notice.location &&

Your venue zone is shared with all your accepted connections for 15 minutes.

} + {notice.asked &&

Request sent. They decide whether to share where they are.

} + {notice.replied &&

Your zone is shared with them for 15 minutes.

} + {notice.declined &&

Request declined. They have been told you would rather not share right now.

} {!connections.length ?

Your intro requests will show up here. Find someone you would like to meet from your matches or search.

:
- {connections.map((connection) =>
+ {connections.map((connection) =>

{connection.participant.name}

{[connection.participant.designation, connection.participant.domain].filter(Boolean).join(" · ")}

@@ -31,7 +34,25 @@ export default async function ConnectionsPage({ params, searchParams }: { {connection.contact.email && } {connection.contact.phone && } {connection.contact.venueZone &&
At the venue: {connection.contact.venueZone}
} - {event.zones.length > 0 && eventAllows(event.status, "shareZone") && + {connection.locationAsked?.status === "answered" &&
Replied: at {connection.locationAsked.zone}
} + {connection.locationAsked?.status === "pending" &&
Asked where they are. Waiting for a reply.
} + {connection.locationAsked?.status === "declined" &&
They would rather not share where they are right now.
} + {event.zones.length > 0 && eventAllows(event.status, "shareZone") && <> + {connection.locationIncoming &&
+ {connection.participant.name} is asking where you are. Sharing is up to you; only they will see it, for 15 minutes. +
+ + + + + +
+
} + {connection.locationAsked?.status !== "pending" && } + } + {event.zones.length > 0 && eventAllows(event.status, "shareZone") &&