mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-21 02:53:06 +00:00
168 lines
5.9 KiB
TypeScript
168 lines
5.9 KiB
TypeScript
import 'server-only'
|
|
|
|
import { normalizeForSearch } from '@/lib/speechSearch'
|
|
import type { ThemeSearchExpansionResolver } from '@/utilities/ai/expandSpeechSearchTheme'
|
|
|
|
/**
|
|
* S28 — the anonymous guard of the public theme search. The Central de Conteúdos
|
|
* has no login and the expansion is an LLM call, so the mode needs a use limit
|
|
* and must never be driven by a bot/crawler/prefetch. Both the limiter and the
|
|
* expansion cache are in-memory (single self-hosted instance; reset on deploy,
|
|
* same contract as `rateLimit.ts`) and live outside `unstable_cache` because
|
|
* they read request headers. Overflow always degrades to the literal search —
|
|
* never a 429 in the voter's face.
|
|
*/
|
|
|
|
/** The headers subset the guard reads (a `Headers` instance satisfies it). */
|
|
export type ThemeSearchHeaders = Pick<Headers, 'get'>
|
|
|
|
const PREFETCH_HEADER = 'next-router-prefetch'
|
|
const FETCH_MODE_HEADER = 'sec-fetch-mode'
|
|
/** Borda (Cloudflare tunnel) first: not forgeable by the client. */
|
|
const CLIENT_IP_HEADERS = ['cf-connecting-ip', 'x-forwarded-for', 'x-real-ip'] as const
|
|
|
|
const THEME_SEARCH_MAX_EXPANSIONS = 8
|
|
const THEME_SEARCH_WINDOW_MS = 15 * 60 * 1000
|
|
const THEME_SEARCH_CACHE_TTL_MS = 30 * 60 * 1000
|
|
const THEME_SEARCH_CACHE_MAX_ENTRIES = 200
|
|
|
|
/**
|
|
* A theme expansion only runs for a browser-initiated request. Next 15 consumes
|
|
* `RSC`/`Next-Router-Prefetch` before userland (`headers()` never sees them —
|
|
* verified against the running app), so the gate is the Fetch Metadata that
|
|
* does arrive: `navigate` (a document load, JS-less form GET included) or
|
|
* `cors` (the router's RSC fetch — the same one a client-side navigation uses,
|
|
* which must expand). `no-cors` is refused so a foreign `<link rel=prefetch>`
|
|
* or an `<img>` cannot trigger an expansion, and a scraper without the
|
|
* Sec-Fetch headers stays literal. The first line against Next's own prefetch
|
|
* is the UI: every theme-preserving link renders with `prefetch={false}`, since
|
|
* the router's prefetch is indistinguishable from a navigation here.
|
|
*/
|
|
export const isThemeSearchRequestEligible = (headers: ThemeSearchHeaders): boolean => {
|
|
if (headers.get(PREFETCH_HEADER)) return false
|
|
const mode = headers.get(FETCH_MODE_HEADER)
|
|
return mode === 'navigate' || mode === 'cors'
|
|
}
|
|
|
|
/**
|
|
* Anonymous client key for the limiter: the edge IP headers in order, with the
|
|
* first `x-forwarded-for` hop as the first fallback. Missing all of them shares
|
|
* the `unknown` bucket (fail-closed: the tightest limit applies).
|
|
*/
|
|
export const themeSearchClientKey = (headers: ThemeSearchHeaders): string => {
|
|
for (const name of CLIENT_IP_HEADERS) {
|
|
const value = headers.get(name)?.split(',')[0]?.trim()
|
|
if (value) return value
|
|
}
|
|
return 'unknown'
|
|
}
|
|
|
|
type ThemeSearchWindow = {
|
|
count: number
|
|
resetAt: number
|
|
}
|
|
|
|
type ThemeSearchCacheEntry = {
|
|
terms: string[]
|
|
expiresAt: number
|
|
}
|
|
|
|
export type ThemeSearchGuardOptions = {
|
|
max?: number
|
|
windowMs?: number
|
|
ttlMs?: number
|
|
maxEntries?: number
|
|
/** Injectable clock for the unit tests. */
|
|
now?: () => number
|
|
}
|
|
|
|
type ResolveThemeExpansionInput = {
|
|
q: string
|
|
headers: ThemeSearchHeaders
|
|
expandTheme: ThemeSearchExpansionResolver
|
|
}
|
|
|
|
export type ThemeSearchGuard = {
|
|
/**
|
|
* `{ terms }` when the expansion ran (or was served from the cache) — the
|
|
* empty list included — and `null` whenever the caller must degrade to the
|
|
* literal search with the notice (ineligible request, quota, unavailable).
|
|
*/
|
|
resolve: (input: ResolveThemeExpansionInput) => Promise<{ terms: string[] } | null>
|
|
}
|
|
|
|
export const createThemeSearchGuard = (options: ThemeSearchGuardOptions = {}): ThemeSearchGuard => {
|
|
const max = options.max ?? THEME_SEARCH_MAX_EXPANSIONS
|
|
const windowMs = options.windowMs ?? THEME_SEARCH_WINDOW_MS
|
|
const ttlMs = options.ttlMs ?? THEME_SEARCH_CACHE_TTL_MS
|
|
const maxEntries = options.maxEntries ?? THEME_SEARCH_CACHE_MAX_ENTRIES
|
|
const now = options.now ?? Date.now
|
|
|
|
const windows = new Map<string, ThemeSearchWindow>()
|
|
const cache = new Map<string, ThemeSearchCacheEntry>()
|
|
|
|
const cleanWindows = (at: number) => {
|
|
for (const [key, entry] of windows) {
|
|
if (at >= entry.resetAt) windows.delete(key)
|
|
}
|
|
}
|
|
|
|
const cleanCache = (at: number) => {
|
|
for (const [key, entry] of cache) {
|
|
if (at >= entry.expiresAt) cache.delete(key)
|
|
}
|
|
}
|
|
|
|
/** A hit does not consume quota: the provider call was already paid for. */
|
|
const withinLimit = (clientKey: string, at: number): boolean => {
|
|
const existing = windows.get(clientKey)
|
|
if (!existing || at >= existing.resetAt) {
|
|
windows.set(clientKey, { count: 1, resetAt: at + windowMs })
|
|
return true
|
|
}
|
|
if (existing.count >= max) return false
|
|
existing.count += 1
|
|
return true
|
|
}
|
|
|
|
const resolve = async ({
|
|
q,
|
|
headers,
|
|
expandTheme,
|
|
}: ResolveThemeExpansionInput): Promise<{ terms: string[] } | null> => {
|
|
if (!isThemeSearchRequestEligible(headers)) return null
|
|
|
|
const theme = q.trim()
|
|
const cacheKey = normalizeForSearch(theme)
|
|
if (!cacheKey) return null
|
|
|
|
const at = now()
|
|
cleanCache(at)
|
|
const cached = cache.get(cacheKey)
|
|
if (cached) return { terms: cached.terms }
|
|
|
|
cleanWindows(at)
|
|
if (!withinLimit(themeSearchClientKey(headers), at)) return null
|
|
|
|
const expansion = await expandTheme(theme)
|
|
// `null` is transient (missing key/timeout/provider error): never cached.
|
|
if (!expansion) return null
|
|
|
|
if (cache.size >= maxEntries) {
|
|
const oldest = cache.keys().next().value
|
|
if (oldest !== undefined) cache.delete(oldest)
|
|
}
|
|
cache.set(cacheKey, { terms: expansion.terms, expiresAt: now() + ttlMs })
|
|
|
|
return { terms: expansion.terms }
|
|
}
|
|
|
|
return { resolve }
|
|
}
|
|
|
|
/**
|
|
* The process-wide guard: one in-memory limiter and cache, reset on deploy. The
|
|
* cache key is the normalized public query (no PII, no user id); a `null`
|
|
* expansion is never stored, so a later request can retry.
|
|
*/
|
|
export const resolveGuardedThemeExpansion = createThemeSearchGuard().resolve
|