Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

Give the search read path its own switch

Rafie47248af82f4
diff --git a/apps/web/.env.example b/apps/web/.env.example
index be4ca1a9f9..71df24de99 100644
--- a/apps/web/.env.example
+++ b/apps/web/.env.example
@@ -24,7 +24,13 @@ UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
# Full-text partner search. Unset falls back to the database search path.
+# The key alone only starts the index syncs; reads stay on the database until
+# PARTNER_SEARCH_READ_ENABLED is "true". Set the key once and leave it set —
+# only the live sync hooks can remove a document, so any window where the app
+# runs without it strands the enrollments deleted meanwhile. Turning search off
+# means clearing the read flag, never the key.
TURBOPUFFER_API_KEY=
+PARTNER_SEARCH_READ_ENABLED=
# Upstash QStash – required for queues and background jobs
# Get your QStash Token here: https://upstash.com/docs/qstash/overall/getstarted
diff --git a/apps/web/lib/api/partners/get-partners-count.ts b/apps/web/lib/api/partners/get-partners-count.ts
index 36dad50ff8..4ef8b68948 100644
--- a/apps/web/lib/api/partners/get-partners-count.ts
+++ b/apps/web/lib/api/partners/get-partners-count.ts
@@ -12,7 +12,7 @@ import {
import {
buildPartnerSearchCandidateQuery,
findPartnerSearchCandidates,
- getPartnerSearchProvider,
+ getPartnerSearchReadProvider,
PartnerSearchProvider,
} from "./search";
@@ -26,7 +26,7 @@ type PartnersCountFilters = z.infer<typeof partnersCountQuerySchema> & {
export async function getPartnersCount<T>(
filters: PartnersCountFilters,
{
- searchProvider = getPartnerSearchProvider(),
+ searchProvider = getPartnerSearchReadProvider(),
throwOnSearchError = false,
}: {
searchProvider?: PartnerSearchProvider | null;
diff --git a/apps/web/lib/api/partners/get-partners.ts b/apps/web/lib/api/partners/get-partners.ts
index a71c324892..7e1a234561 100644
--- a/apps/web/lib/api/partners/get-partners.ts
+++ b/apps/web/lib/api/partners/get-partners.ts
@@ -5,7 +5,7 @@ import { buildProgramEnrollmentWhereForList } from "./program-enrollment-query";
import {
buildPartnerSearchCandidateQuery,
findPartnerSearchCandidates,
- getPartnerSearchProvider,
+ getPartnerSearchReadProvider,
orderByPartnerSearchHits,
PartnerSearchProvider,
PartnerSearchQueryInput,
@@ -23,7 +23,7 @@ interface GetPartnersOptions {
export async function getPartners(
filters: PartnerFilters,
{
- searchProvider = getPartnerSearchProvider(),
+ searchProvider = getPartnerSearchReadProvider(),
throwOnSearchError = false,
}: GetPartnersOptions = {},
) {
diff --git a/apps/web/lib/api/partners/search/provider.ts b/apps/web/lib/api/partners/search/provider.ts
index 0d1c6d692d..34ba37cd3c 100644
--- a/apps/web/lib/api/partners/search/provider.ts
+++ b/apps/web/lib/api/partners/search/provider.ts
@@ -6,9 +6,18 @@ import type { PartnerSearchProvider } from "./types";
let cachedSearchProvider: PartnerSearchProvider | null = null;
/**
+ * The provider for everything that writes: the sync jobs, the backfill, and the
+ * reconciliation sweep.
+ *
* Null until turbopuffer is configured, which is what keeps this dark: every
* caller falls back to the database search path when there is no provider, so
* an unset key costs the wider field coverage rather than the partner list.
+ *
+ * Once set in an environment that serves traffic, leave it set. Removing a
+ * document is something only the live sync hooks can do — the backfill and the
+ * sweep upsert and never delete — so any window where the app runs with this
+ * unset turns every enrollment deleted during it into a document nothing can
+ * remove short of rebuilding the namespace.
*/
export function getPartnerSearchProvider(): PartnerSearchProvider | null {
if (!process.env.TURBOPUFFER_API_KEY?.trim()) {
@@ -19,3 +28,27 @@ export function getPartnerSearchProvider(): PartnerSearchProvider | null {
return cachedSearchProvider;
}
+
+/**
+ * Whether the partners list and count read from the index rather than the
+ * database.
+ *
+ * Reads get their own switch so that turning search off never means turning
+ * indexing off. That is the whole point: writes stay on from the first day and
+ * are never flipped, so the index keeps tracking deletions even while nothing
+ * is reading it, and coming back is flipping this one flag rather than
+ * rebuilding a namespace.
+ *
+ * It also keeps the initial rollout honest. An empty index does not degrade
+ * gracefully — a program with no documents yet produces a successful, empty
+ * candidate list, which the callers apply as `id IN ()` after clearing the
+ * database search predicate, so every query returns nothing. Reads therefore
+ * stay off until the backfill has finished.
+ */
+export function isPartnerSearchReadEnabled(): boolean {
+ return process.env.PARTNER_SEARCH_READ_ENABLED?.trim() === "true";
+}
+
+export function getPartnerSearchReadProvider(): PartnerSearchProvider | null {
+ return isPartnerSearchReadEnabled() ? getPartnerSearchProvider() : null;
+}
diff --git a/apps/web/tests/partners/partner-search-provider-switches.test.ts b/apps/web/tests/partners/partner-search-provider-switches.test.ts
new file mode 100644
index 0000000000..78e2db08ce
--- /dev/null
+++ b/apps/web/tests/partners/partner-search-provider-switches.test.ts
@@ -0,0 +1,79 @@
+import {
+ getPartnerSearchProvider,
+ getPartnerSearchReadProvider,
+ isPartnerSearchReadEnabled,
+} from "@/lib/api/partners/search";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/lib/api/partners/search/providers/turbopuffer", () => ({
+ createTurbopufferPartnerSearchProvider: () => ({
+ searchCandidates: vi.fn(),
+ countCandidates: vi.fn(),
+ upsert: vi.fn(),
+ delete: vi.fn(),
+ }),
+}));
+
+const originalEnv = { ...process.env };
+
+describe("partner search switches", () => {
+ beforeEach(() => {
+ delete process.env.TURBOPUFFER_API_KEY;
+ delete process.env.PARTNER_SEARCH_READ_ENABLED;
+ });
+
+ afterEach(() => {
+ process.env = { ...originalEnv };
+ });
+
+ it("writes nowhere until the key is configured", () => {
+ expect(getPartnerSearchProvider()).toBeNull();
+ });
+
+ // The rollout depends on this. Syncs have to run for the whole backfill
+ // before the index is complete enough to read, so the key alone must not
+ // turn reads on.
+ it("keeps reads on the database when only the key is configured", () => {
+ process.env.TURBOPUFFER_API_KEY = "tpuf_test";
+
+ expect(getPartnerSearchProvider()).not.toBeNull();
+ expect(isPartnerSearchReadEnabled()).toBe(false);
+ expect(getPartnerSearchReadProvider()).toBeNull();
+ });
+
+ it("reads from the index once both switches are on", () => {
+ process.env.TURBOPUFFER_API_KEY = "tpuf_test";
+ process.env.PARTNER_SEARCH_READ_ENABLED = "true";
+
+ expect(getPartnerSearchReadProvider()).not.toBeNull();
+ });
+
+ // The point of the split: clearing the read flag stops search without
+ // stopping indexing, so deletions keep being applied while rolled back and
+ // coming back needs no rebuild.
+ it("keeps writing while reads are switched off", () => {
+ process.env.TURBOPUFFER_API_KEY = "tpuf_test";
+ process.env.PARTNER_SEARCH_READ_ENABLED = "false";
+
+ expect(getPartnerSearchReadProvider()).toBeNull();
+ expect(getPartnerSearchProvider()).not.toBeNull();
+ });
+
+ // Otherwise the read flag alone would look enabled with no index behind it,
+ // which is the one combination that returns empty results rather than
+ // falling back.
+ it("cannot read without a key, however the read flag is set", () => {
+ process.env.PARTNER_SEARCH_READ_ENABLED = "true";
+
+ expect(getPartnerSearchReadProvider()).toBeNull();
+ });
+
+ it('treats anything other than "true" as off', () => {
+ process.env.TURBOPUFFER_API_KEY = "tpuf_test";
+
+ for (const value of ["", "false", "1", "yes", "TRUE"]) {
+ process.env.PARTNER_SEARCH_READ_ENABLED = value;
+ expect(getPartnerSearchReadProvider()).toBeNull();
+ }
+ });
+});