feat(voice): add noise suppression backends and rollout (#2706)

fluxer_api/src/api/admin/controllers/InstanceConfigAdminController.ts

@@ -14,7 +14,9 @@ import {
 	RegistrationUrlIdParam,
 } from '@fluxer/schema/src/domains/admin/AdminSchemas';
 import {GatewayRolloutConfigSchema} from '@fluxer/schema/src/domains/admin/GatewayRolloutSchemas';
+import {VoiceNoiseSuppressionConfigSchema} from '@fluxer/schema/src/domains/admin/VoiceNoiseSuppressionSchemas';
 import {UserIdParam} from '@fluxer/schema/src/domains/common/CommonParamSchemas';
+import {ExperimentDeliveryConfigSchema} from '@fluxer/schema/src/domains/experiment/ExperimentSchemas';
 import {SmtpEmailProvider} from '@pkgs/email/src/SmtpEmailProvider';
 import type {Context} from 'hono';
 import {createMiddleware} from 'hono/factory';
@@ -51,9 +53,19 @@ function omitUndefinedFields<T extends object>(value: T): Partial<T> {
 
 async function buildInstanceConfigResponse(): Promise<InstanceConfigResponse> {
 	const instanceConfigRepository = getInstanceConfigRepository();
-	const [ssoConfig, gatewayRollout, registrationConfig, registrationUrls, pendingRegistrations] = await Promise.all([
+	const [
+		ssoConfig,
+		gatewayRollout,
+		voiceNoiseSuppression,
+		experimentDelivery,
+		registrationConfig,
+		registrationUrls,
+		pendingRegistrations,
+	] = await Promise.all([
 		instanceConfigRepository.getSsoConfig(),
 		instanceConfigRepository.getGatewayRolloutConfig(),
+		instanceConfigRepository.getVoiceNoiseSuppressionConfig(),
+		instanceConfigRepository.getExperimentDeliveryConfig(),
 		instanceConfigRepository.getRegistrationConfig(),
 		instanceConfigRepository.getRegistrationUrlsForAdmin(),
 		instanceConfigRepository.getPendingRegistrations(),
@@ -83,6 +95,8 @@ async function buildInstanceConfigResponse(): Promise<InstanceConfigResponse> {
 			redirect_uri: deriveSsoRedirectUri(Config.endpoints.webApp),
 		},
 		gateway_rollout: gatewayRollout,
+		voice_noise_suppression: voiceNoiseSuppression,
+		experiment_delivery: experimentDelivery,
 		registration: {
 			...registrationConfig,
 			urls: registrationUrls,
@@ -214,6 +228,23 @@ export function InstanceConfigAdminController(app: HonoApp) {
 				await instanceConfigRepository.setGatewayRolloutConfig(validated);
 				await getGatewayRolloutConfigPublisher().publish(validated);
 			}
+			if (data.voice_noise_suppression) {
+				const currentNoiseSuppression = await instanceConfigRepository.getVoiceNoiseSuppressionConfig();
+				const validated = VoiceNoiseSuppressionConfigSchema.parse({
+					...currentNoiseSuppression,
+					...data.voice_noise_suppression,
+					config_version: currentNoiseSuppression.config_version + 1,
+				});
+				await instanceConfigRepository.setVoiceNoiseSuppressionConfig(validated);
+			}
+			if (data.experiment_delivery) {
+				const currentExperimentDelivery = await instanceConfigRepository.getExperimentDeliveryConfig();
+				const validated = ExperimentDeliveryConfigSchema.parse({
+					...currentExperimentDelivery,
+					...data.experiment_delivery,
+				});
+				await instanceConfigRepository.setExperimentDeliveryConfig(validated);
+			}
 			if (data.sso) {
 				const sso = data.sso;
 				const current = await instanceConfigRepository.getSsoConfig({includeSecret: true});

fluxer_api/src/api/app/ControllerRegistry.ts

@@ -9,6 +9,7 @@ import type {APIConfig} from '../config/APIConfig';
 import {ConnectionController} from '../connection/ConnectionController';
 import {DonationController} from '../donation/DonationController';
 import {DownloadController} from '../download/DownloadController';
+import {ExperimentController} from '../experiment/ExperimentController';
 import {FavoriteGifController} from '../favorite_gif/FavoriteGifController';
 import {FavoriteMemeController} from '../favorite_meme/FavoriteMemeController';
 import {GatewayController} from '../gateway/GatewayController';
@@ -50,6 +51,7 @@ export function registerControllers(routes: HonoApp, config: APIConfig): void {
 	InstanceController(routes);
 	OpenAPIController(routes);
 	DownloadController(routes);
+	ExperimentController(routes);
 	FavoriteGifController(routes);
 	FavoriteMemeController(routes);
 	InviteController(routes);

fluxer_api/src/api/app/MiddlewarePipeline.ts

@@ -52,7 +52,18 @@ export function configureMiddleware(routes: HonoApp, options: MiddlewarePipeline
 	);
 	applyMiddlewareStack(routes, {
 		requestId: {},
-		cors: {origins: corsOrigins, exposedHeaders: [HttpHeaders.X_FLUXER_VERSION]},
+		cors: {
+			origins: corsOrigins,
+			allowedHeaders: [
+				HttpHeaders.CONTENT_TYPE,
+				HttpHeaders.AUTHORIZATION,
+				'X-Requested-With',
+				'Accept-Language',
+				HttpHeaders.X_REQUEST_ID,
+				HttpHeaders.IF_NONE_MATCH,
+			],
+			exposedHeaders: [HttpHeaders.X_FLUXER_VERSION, HttpHeaders.ETAG],
+		},
 		skipLogger: true,
 		skipErrorHandler: true,
 	});

fluxer_api/src/api/experiment/ExperimentController.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {createHash} from 'node:crypto';
+import {Headers as HttpHeaders} from '@fluxer/constants/src/Headers';
+import {resolveVoiceNoiseSuppressionAssignment} from '@fluxer/schema/src/domains/admin/VoiceNoiseSuppressionSchemas';
+import {ExperimentAssignmentsResponse} from '@fluxer/schema/src/domains/experiment/ExperimentSchemas';
+import {LoginRequired} from '../middleware/AuthMiddleware';
+import {RateLimitMiddleware} from '../middleware/RateLimitMiddleware';
+import {OpenAPI} from '../middleware/ResponseTypeMiddleware';
+import {RateLimitConfigs} from '../RateLimitConfig';
+import type {HonoApp} from '../types/HonoEnv';
+import {entityTagMatches} from '../utils/EntityTag';
+
+export function ExperimentController(app: HonoApp) {
+	app.get(
+		'/experiments',
+		RateLimitMiddleware(RateLimitConfigs.DEFAULT),
+		LoginRequired,
+		OpenAPI({
+			operationId: 'get_experiments',
+			summary: 'Get the experiment assignments',
+			description:
+				'Returns the polling cadence and every experiment assignment resolved for the authenticated user from the instance configuration. Clients revalidate with If-None-Match and receive 304 when nothing changed.',
+			responseSchema: ExperimentAssignmentsResponse,
+			statusCode: 200,
+			security: ['bearerToken', 'sessionToken', 'botToken'],
+			tags: ['Experiments'],
+		}),
+		async (ctx) => {
+			const instanceConfigRepository = ctx.get('instanceConfigRepository');
+			const [delivery, voiceConfig] = await Promise.all([
+				instanceConfigRepository.getExperimentDeliveryConfig(),
+				instanceConfigRepository.getVoiceNoiseSuppressionConfig(),
+			]);
+			const body: ExperimentAssignmentsResponse = {
+				poll_interval_seconds: delivery.poll_interval_seconds,
+				poll_jitter_percent: delivery.poll_jitter_percent,
+				assignments: {
+					voice_noise_suppression: resolveVoiceNoiseSuppressionAssignment(voiceConfig, ctx.get('user').id.toString()),
+				},
+			};
+			const etag = `"${createHash('sha256').update(JSON.stringify(body)).digest('hex')}"`;
+			ctx.header(HttpHeaders.ETAG, etag);
+			ctx.header(HttpHeaders.CACHE_CONTROL, 'private, no-cache');
+			ctx.header('Vary', 'Authorization');
+			const ifNoneMatch = ctx.req.header(HttpHeaders.IF_NONE_MATCH);
+			if (ifNoneMatch !== undefined && entityTagMatches(ifNoneMatch, etag)) {
+				return ctx.body(null, 304);
+			}
+			return ctx.json(body);
+		},
+	);
+}

fluxer_api/src/api/experiment/tests/ExperimentController.test.ts

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {AdminACLs} from '@fluxer/constants/src/AdminACLs';
+import {
+	DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+	INERT_VOICE_NOISE_SUPPRESSION_ASSIGNMENT,
+} from '@fluxer/schema/src/domains/admin/VoiceNoiseSuppressionSchemas';
+import {
+	DEFAULT_EXPERIMENT_POLL_INTERVAL_SECONDS,
+	DEFAULT_EXPERIMENT_POLL_JITTER_PERCENT,
+	type ExperimentAssignmentsResponse,
+	type ExperimentDeliveryConfigResponse,
+	readVoiceNoiseSuppressionAssignment,
+} from '@fluxer/schema/src/domains/experiment/ExperimentSchemas';
+import {afterAll, beforeAll, beforeEach, describe, expect, it} from 'vitest';
+import {createTestAccount, setUserACLs} from '../../auth/tests/AuthTestUtils';
+import {getInstanceConfigRepository} from '../../middleware/ServiceSingletons';
+import {type ApiTestHarness, createApiTestHarness} from '../../test/ApiTestHarness';
+import {HTTP_STATUS} from '../../test/TestConstants';
+import {createBuilder, createBuilderWithoutAuth} from '../../test/TestRequestBuilder';
+
+const NOT_MODIFIED = 304;
+const ENDPOINT = '/experiments';
+
+describe('GET /experiments', () => {
+	let harness: ApiTestHarness;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+	});
+
+	beforeEach(async () => {
+		await harness.reset();
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+	});
+
+	it('rejects an unauthenticated caller', async () => {
+		await createBuilderWithoutAuth(harness).get(ENDPOINT).expect(HTTP_STATUS.UNAUTHORIZED).execute();
+	});
+
+	it('returns the default delivery cadence and the inert assignment while the feature is disabled', async () => {
+		const account = await createTestAccount(harness);
+
+		const body = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token).get(ENDPOINT).execute();
+
+		expect(body).toEqual({
+			poll_interval_seconds: DEFAULT_EXPERIMENT_POLL_INTERVAL_SECONDS,
+			poll_jitter_percent: DEFAULT_EXPERIMENT_POLL_JITTER_PERCENT,
+			assignments: {voice_noise_suppression: INERT_VOICE_NOISE_SUPPRESSION_ASSIGNMENT},
+		});
+	});
+
+	it('returns the inert assignment while the stored config is disabled but populated', async () => {
+		const account = await createTestAccount(harness);
+		await getInstanceConfigRepository().setVoiceNoiseSuppressionConfig({
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: false,
+			config_version: 9,
+			rollout_basis_points: 10000,
+			included_user_ids: [account.userId],
+		});
+
+		const body = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token).get(ENDPOINT).execute();
+
+		expect(body.assignments.voice_noise_suppression).toEqual({
+			...INERT_VOICE_NOISE_SUPPRESSION_ASSIGNMENT,
+			config_version: 9,
+		});
+	});
+
+	it('populates the voice assignment key even when the rollout is disabled', async () => {
+		const account = await createTestAccount(harness);
+
+		const body = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token).get(ENDPOINT).execute();
+
+		expect(Object.hasOwn(body.assignments, 'voice_noise_suppression')).toBe(true);
+		expect(readVoiceNoiseSuppressionAssignment(body).enabled).toBe(false);
+	});
+
+	it('serves the delivery cadence from the delivery config and not from the voice config', async () => {
+		const account = await createTestAccount(harness);
+		await getInstanceConfigRepository().setExperimentDeliveryConfig({
+			poll_interval_seconds: 7200,
+			poll_jitter_percent: 45,
+		});
+		await getInstanceConfigRepository().setVoiceNoiseSuppressionConfig({
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: true,
+			config_version: 3,
+			rollout_basis_points: 10000,
+		});
+
+		const body = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token).get(ENDPOINT).execute();
+
+		expect(body.poll_interval_seconds).toBe(7200);
+		expect(body.poll_jitter_percent).toBe(45);
+		expect(body.assignments.voice_noise_suppression).toMatchObject({enabled: true, config_version: 3});
+		expect(body.assignments.voice_noise_suppression).not.toHaveProperty('poll_interval_seconds');
+		expect(body.assignments.voice_noise_suppression).not.toHaveProperty('poll_jitter_percent');
+	});
+
+	it('echoes the config version and resolves the caller through the allowlist', async () => {
+		const targeted = await createTestAccount(harness);
+		const untargeted = await createTestAccount(harness);
+		await getInstanceConfigRepository().setVoiceNoiseSuppressionConfig({
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: true,
+			config_version: 14,
+			default_backend: 'rnnoise',
+			rollout_basis_points: 0,
+			included_user_ids: [targeted.userId],
+		});
+
+		const targetedBody = await createBuilder<ExperimentAssignmentsResponse>(harness, targeted.token)
+			.get(ENDPOINT)
+			.execute();
+		expect(targetedBody.assignments.voice_noise_suppression).toMatchObject({
+			enabled: true,
+			config_version: 14,
+			user_targeted: true,
+			backend: 'rnnoise',
+			source: 'user_rule',
+		});
+
+		const untargetedBody = await createBuilder<ExperimentAssignmentsResponse>(harness, untargeted.token)
+			.get(ENDPOINT)
+			.execute();
+		expect(untargetedBody.assignments.voice_noise_suppression).toMatchObject({
+			enabled: true,
+			config_version: 14,
+			user_targeted: false,
+			backend: null,
+			source: null,
+		});
+	});
+
+	it('revalidates with a strong etag and answers 304 when nothing changed', async () => {
+		const account = await createTestAccount(harness);
+
+		const first = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token)
+			.get(ENDPOINT)
+			.executeWithResponse();
+		const etag = first.response.headers.get('etag');
+		expect(etag).toMatch(/^"[0-9a-f]{64}"$/);
+		expect(first.response.headers.get('cache-control')).toBe('private, no-cache');
+		expect(first.response.headers.get('vary')).toBe('Authorization');
+
+		const revalidated = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token)
+			.get(ENDPOINT)
+			.header('If-None-Match', etag as string)
+			.expect(NOT_MODIFIED)
+			.executeWithResponse();
+		expect(revalidated.response.status).toBe(NOT_MODIFIED);
+		expect(revalidated.json).toBeUndefined();
+		expect(revalidated.response.headers.get('etag')).toBe(etag);
+	});
+
+	it('lets a cross-origin client send If-None-Match and read the etag back', async () => {
+		const preflight = await harness.requestJson({path: ENDPOINT, method: 'OPTIONS'});
+
+		expect(preflight.headers.get('access-control-allow-headers')).toContain('If-None-Match');
+		expect(preflight.headers.get('access-control-expose-headers')).toContain('ETag');
+	});
+
+	it('serves a fresh body once the voice config changes', async () => {
+		const account = await createTestAccount(harness);
+
+		const first = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token)
+			.get(ENDPOINT)
+			.executeWithResponse();
+		const staleEtag = first.response.headers.get('etag') as string;
+
+		await getInstanceConfigRepository().setVoiceNoiseSuppressionConfig({
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: true,
+			config_version: 1,
+			rollout_basis_points: 10000,
+		});
+
+		const refreshed = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token)
+			.get(ENDPOINT)
+			.header('If-None-Match', staleEtag)
+			.executeWithResponse();
+		expect(refreshed.response.status).toBe(HTTP_STATUS.OK);
+		expect(refreshed.response.headers.get('etag')).not.toBe(staleEtag);
+		expect(refreshed.json?.assignments.voice_noise_suppression).toMatchObject({
+			enabled: true,
+			config_version: 1,
+			user_targeted: true,
+		});
+	});
+
+	it('serves a fresh body once the delivery config changes', async () => {
+		const account = await createTestAccount(harness);
+
+		const first = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token)
+			.get(ENDPOINT)
+			.executeWithResponse();
+		const staleEtag = first.response.headers.get('etag') as string;
+
+		await getInstanceConfigRepository().setExperimentDeliveryConfig({
+			poll_interval_seconds: 1800,
+			poll_jitter_percent: 5,
+		});
+
+		const refreshed = await createBuilder<ExperimentAssignmentsResponse>(harness, account.token)
+			.get(ENDPOINT)
+			.header('If-None-Match', staleEtag)
+			.executeWithResponse();
+		expect(refreshed.response.status).toBe(HTTP_STATUS.OK);
+		expect(refreshed.response.headers.get('etag')).not.toBe(staleEtag);
+		expect(refreshed.json?.poll_interval_seconds).toBe(1800);
+		expect(refreshed.json?.poll_jitter_percent).toBe(5);
+	});
+
+	it('bumps the config version on every admin update without the client sending one', async () => {
+		const admin = await setUserACLs(harness, await createTestAccount(harness), [
+			AdminACLs.AUTHENTICATE,
+			AdminACLs.INSTANCE_CONFIG_VIEW,
+			AdminACLs.INSTANCE_CONFIG_UPDATE,
+		]);
+
+		const afterFirst = await createBuilder<{voice_noise_suppression: {config_version: number; enabled: boolean}}>(
+			harness,
+			admin.token,
+		)
+			.patch('/admin/instance/config')
+			.body({voice_noise_suppression: {enabled: true, rollout_basis_points: 10000}})
+			.execute();
+		expect(afterFirst.voice_noise_suppression).toMatchObject({config_version: 1, enabled: true});
+
+		const afterSecond = await createBuilder<{voice_noise_suppression: {config_version: number; enabled: boolean}}>(
+			harness,
+			admin.token,
+		)
+			.patch('/admin/instance/config')
+			.body({voice_noise_suppression: {suppression_strength: 42}})
+			.execute();
+		expect(afterSecond.voice_noise_suppression).toMatchObject({config_version: 2, enabled: true});
+
+		const body = await createBuilder<ExperimentAssignmentsResponse>(harness, admin.token).get(ENDPOINT).execute();
+		expect(body.assignments.voice_noise_suppression).toMatchObject({
+			enabled: true,
+			config_version: 2,
+			suppression_strength: 42,
+		});
+	});
+
+	it('leaves the config version alone for an admin update that sets no field', async () => {
+		const admin = await setUserACLs(harness, await createTestAccount(harness), [
+			AdminACLs.AUTHENTICATE,
+			AdminACLs.INSTANCE_CONFIG_VIEW,
+			AdminACLs.INSTANCE_CONFIG_UPDATE,
+		]);
+
+		const afterFirst = await createBuilder<{voice_noise_suppression: {config_version: number; enabled: boolean}}>(
+			harness,
+			admin.token,
+		)
+			.patch('/admin/instance/config')
+			.body({voice_noise_suppression: {enabled: true}})
+			.execute();
+		expect(afterFirst.voice_noise_suppression).toMatchObject({config_version: 1, enabled: true});
+
+		const afterEmpty = await createBuilder<{voice_noise_suppression: {config_version: number; enabled: boolean}}>(
+			harness,
+			admin.token,
+		)
+			.patch('/admin/instance/config')
+			.body({voice_noise_suppression: {}})
+			.execute();
+		expect(afterEmpty.voice_noise_suppression).toMatchObject({config_version: 1, enabled: true});
+
+		const afterUndefined = await createBuilder<{voice_noise_suppression: {config_version: number; enabled: boolean}}>(
+			harness,
+			admin.token,
+		)
+			.patch('/admin/instance/config')
+			.body({voice_noise_suppression: {enabled: undefined}})
+			.execute();
+		expect(afterUndefined.voice_noise_suppression).toMatchObject({config_version: 1, enabled: true});
+	});
+
+	it('serves the delivery cadence an admin set through the instance config', async () => {
+		const admin = await setUserACLs(harness, await createTestAccount(harness), [
+			AdminACLs.AUTHENTICATE,
+			AdminACLs.INSTANCE_CONFIG_VIEW,
+			AdminACLs.INSTANCE_CONFIG_UPDATE,
+		]);
+
+		const updated = await createBuilder<{experiment_delivery: ExperimentDeliveryConfigResponse}>(harness, admin.token)
+			.patch('/admin/instance/config')
+			.body({experiment_delivery: {poll_interval_seconds: 3600}})
+			.execute();
+		expect(updated.experiment_delivery).toEqual({
+			poll_interval_seconds: 3600,
+			poll_jitter_percent: DEFAULT_EXPERIMENT_POLL_JITTER_PERCENT,
+		});
+
+		const body = await createBuilder<ExperimentAssignmentsResponse>(harness, admin.token).get(ENDPOINT).execute();
+		expect(body.poll_interval_seconds).toBe(3600);
+		expect(body.poll_jitter_percent).toBe(DEFAULT_EXPERIMENT_POLL_JITTER_PERCENT);
+	});
+});

fluxer_api/src/api/instance/InstanceConfigRepository.test.ts

@@ -1,5 +1,13 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+import {
+	DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+	type VoiceNoiseSuppressionConfig,
+} from '@fluxer/schema/src/domains/admin/VoiceNoiseSuppressionSchemas';
+import {
+	DEFAULT_EXPERIMENT_DELIVERY_CONFIG,
+	type ExperimentDeliveryConfig,
+} from '@fluxer/schema/src/domains/experiment/ExperimentSchemas';
 import {afterEach, describe, expect, it, vi} from 'vitest';
 import {setCassandraQueryExecutorForTesting} from '../database/CassandraQueryExecution';
 import type {PreparedQuery} from '../database/CassandraTypes';
@@ -11,6 +19,9 @@ import {
 	type InstanceRegistrationConfig,
 } from './InstanceConfigRepository';
 
+const VOICE_NOISE_SUPPRESSION_CONFIG_KEY = 'voice_noise_suppression_config';
+const EXPERIMENT_DELIVERY_CONFIG_KEY = 'experiment_delivery_config';
+
 class CountingInMemoryCassandraQueryExecutor extends InMemoryCassandraQueryExecutor {
 	instanceConfigSelects = 0;
 
@@ -147,6 +158,148 @@ describe('InstanceConfigRepository', () => {
 		});
 	});
 
+	it('returns the default voice noise suppression config when the key is absent', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		await expect(repository.getVoiceNoiseSuppressionConfig()).resolves.toEqual(DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG);
+	});
+
+	it.each([
+		{name: 'unparseable text', stored: 'not-json'},
+		{name: 'a json array', stored: '[]'},
+		{name: 'out-of-range values', stored: '{"rollout_basis_points":99999}'},
+		{name: 'an unknown backend', stored: '{"default_backend":"magic"}'},
+	])('falls back to the default voice noise suppression config for $name', async ({stored}) => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		await repository.setConfig(VOICE_NOISE_SUPPRESSION_CONFIG_KEY, stored);
+
+		await expect(repository.getVoiceNoiseSuppressionConfig()).resolves.toEqual(DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG);
+	});
+
+	it('round-trips a stored voice noise suppression config', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		const config: VoiceNoiseSuppressionConfig = {
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: true,
+			config_version: 3,
+			default_backend: 'rnnoise',
+			enabled_backends: ['none', 'standard', 'rnnoise'],
+			allow_user_override: false,
+			rollout_basis_points: 2500,
+			rollout_salt: 'voice-ns-v2',
+			included_user_ids: ['1400000000000000001'],
+			excluded_user_ids: ['1400000000000000002'],
+			guild_overrides: [{guild_id: '2400000000000000001', backend: 'rnnoise'}],
+			stereo_enabled: true,
+			suppression_strength: 55,
+		};
+		await repository.setVoiceNoiseSuppressionConfig(config);
+
+		await expect(repository.getVoiceNoiseSuppressionConfig()).resolves.toEqual(config);
+	});
+
+	it('fills newly added voice noise suppression fields from the schema defaults', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		await repository.setConfig(
+			VOICE_NOISE_SUPPRESSION_CONFIG_KEY,
+			JSON.stringify({enabled: true, config_version: 2, rollout_basis_points: 1000}),
+		);
+
+		await expect(repository.getVoiceNoiseSuppressionConfig()).resolves.toEqual({
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: true,
+			config_version: 2,
+			rollout_basis_points: 1000,
+		});
+	});
+
+	it('returns the default experiment delivery config when the key is absent', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		await expect(repository.getExperimentDeliveryConfig()).resolves.toEqual(DEFAULT_EXPERIMENT_DELIVERY_CONFIG);
+	});
+
+	it.each([
+		{name: 'unparseable text', stored: 'not-json'},
+		{name: 'a json array', stored: '[]'},
+		{name: 'an out-of-range poll interval', stored: '{"poll_interval_seconds":1}'},
+		{name: 'an out-of-range jitter', stored: '{"poll_jitter_percent":99}'},
+		{name: 'a non-numeric poll interval', stored: '{"poll_interval_seconds":"often"}'},
+	])('falls back to the default experiment delivery config for $name', async ({stored}) => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		await repository.setConfig(EXPERIMENT_DELIVERY_CONFIG_KEY, stored);
+
+		await expect(repository.getExperimentDeliveryConfig()).resolves.toEqual(DEFAULT_EXPERIMENT_DELIVERY_CONFIG);
+	});
+
+	it('round-trips a stored experiment delivery config', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		const config: ExperimentDeliveryConfig = {poll_interval_seconds: 900, poll_jitter_percent: 0};
+		await repository.setExperimentDeliveryConfig(config);
+
+		await expect(repository.getExperimentDeliveryConfig()).resolves.toEqual(config);
+	});
+
+	it('fills missing experiment delivery fields from the schema defaults', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const repository = createRepository(kvProvider);
+
+		await repository.setConfig(EXPERIMENT_DELIVERY_CONFIG_KEY, JSON.stringify({poll_interval_seconds: 3600}));
+
+		await expect(repository.getExperimentDeliveryConfig()).resolves.toEqual({
+			...DEFAULT_EXPERIMENT_DELIVERY_CONFIG,
+			poll_interval_seconds: 3600,
+		});
+	});
+
+	it('publishes a refresh so another repository observes the voice noise suppression config', async () => {
+		const executor = new CountingInMemoryCassandraQueryExecutor();
+		setCassandraQueryExecutorForTesting(executor);
+		const kvProvider = new MockKVProvider();
+		const reader = createRepository(kvProvider);
+		const writer = createRepository(kvProvider);
+
+		await expect(reader.getVoiceNoiseSuppressionConfig()).resolves.toEqual(DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG);
+
+		await writer.setVoiceNoiseSuppressionConfig({
+			...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+			enabled: true,
+			config_version: 1,
+		});
+
+		await vi.waitFor(async () => {
+			expect(await reader.getVoiceNoiseSuppressionConfig()).toMatchObject({enabled: true, config_version: 1});
+		});
+	});
+
 	it('uses the registration URL id as the admin-visible registration code', async () => {
 		const executor = new CountingInMemoryCassandraQueryExecutor();
 		setCassandraQueryExecutorForTesting(executor);

fluxer_api/src/api/instance/InstanceConfigRepository.ts

@@ -6,6 +6,16 @@ import {
 	type GatewayRolloutConfig,
 	GatewayRolloutConfigSchema,
 } from '@fluxer/schema/src/domains/admin/GatewayRolloutSchemas';
+import {
+	DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+	type VoiceNoiseSuppressionConfig,
+	VoiceNoiseSuppressionConfigSchema,
+} from '@fluxer/schema/src/domains/admin/VoiceNoiseSuppressionSchemas';
+import {
+	DEFAULT_EXPERIMENT_DELIVERY_CONFIG,
+	type ExperimentDeliveryConfig,
+	ExperimentDeliveryConfigSchema,
+} from '@fluxer/schema/src/domains/experiment/ExperimentSchemas';
 import type {IKVProvider, IKVSubscription} from '@pkgs/kv_client/src/IKVProvider';
 import {Config} from '../Config';
 import type {APIConfig, BlueskyOAuthConfig, BlueskyOAuthKeyConfig} from '../config/APIConfig';
@@ -21,6 +31,8 @@ import {getDefaultDateOfBirthCollection, setCachedDateOfBirthCollection} from '.
 import {normalizeSsoAllowedEmailDomains} from './SsoConfigValidation';
 
 const GATEWAY_ROLLOUT_CONFIG_KEY = 'gateway_rollout_config';
+const VOICE_NOISE_SUPPRESSION_CONFIG_KEY = 'voice_noise_suppression_config';
+const EXPERIMENT_DELIVERY_CONFIG_KEY = 'experiment_delivery_config';
 const REGISTRATION_CONFIG_KEY = 'registration_config';
 const REGISTRATION_URLS_KEY = 'registration_urls';
 const REGISTRATION_PENDING_APPROVALS_KEY = 'registration_pending_approvals';
@@ -43,6 +55,20 @@ const DEFAULT_GATEWAY_ROLLOUT_CONFIG: GatewayRolloutConfig = {
 	gateway_dispatch_relay_max_queue: 50000,
 	voice_e2ee_scope: 'guild_feature_only',
 };
+
+function cloneDefaultVoiceNoiseSuppressionConfig(): VoiceNoiseSuppressionConfig {
+	return {
+		...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG,
+		enabled_backends: [...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG.enabled_backends],
+		included_user_ids: [...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG.included_user_ids],
+		excluded_user_ids: [...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG.excluded_user_ids],
+		guild_overrides: [...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG.guild_overrides],
+	};
+}
+
+function cloneDefaultExperimentDeliveryConfig(): ExperimentDeliveryConfig {
+	return {...DEFAULT_EXPERIMENT_DELIVERY_CONFIG};
+}
 export type InstanceRegistrationMode = 'open' | 'approval' | 'closed';
 export interface InstanceRegistrationConfig {
 	mode: InstanceRegistrationMode;
@@ -1050,6 +1076,48 @@ export class InstanceConfigRepository {
 		await this.setConfig(GATEWAY_ROLLOUT_CONFIG_KEY, JSON.stringify(config));
 	}
 
+	async getVoiceNoiseSuppressionConfig(): Promise<VoiceNoiseSuppressionConfig> {
+		const raw = await this.getConfig(VOICE_NOISE_SUPPRESSION_CONFIG_KEY);
+		if (!raw) {
+			return cloneDefaultVoiceNoiseSuppressionConfig();
+		}
+		const parsed = parseJsonRecord(raw);
+		if (!parsed) {
+			return cloneDefaultVoiceNoiseSuppressionConfig();
+		}
+		const result = VoiceNoiseSuppressionConfigSchema.safeParse({...DEFAULT_VOICE_NOISE_SUPPRESSION_CONFIG, ...parsed});
+		if (!result.success) {
+			Logger.error({error: result.error}, 'Invalid voice noise suppression config');
+			return cloneDefaultVoiceNoiseSuppressionConfig();
+		}
+		return result.data;
+	}
+
+	async setVoiceNoiseSuppressionConfig(config: VoiceNoiseSuppressionConfig): Promise<void> {
+		await this.setConfig(VOICE_NOISE_SUPPRESSION_CONFIG_KEY, JSON.stringify(config));
+	}
+
+	async getExperimentDeliveryConfig(): Promise<ExperimentDeliveryConfig> {
+		const raw = await this.getConfig(EXPERIMENT_DELIVERY_CONFIG_KEY);
+		if (!raw) {
+			return cloneDefaultExperimentDeliveryConfig();
+		}
+		const parsed = parseJsonRecord(raw);
+		if (!parsed) {
+			return cloneDefaultExperimentDeliveryConfig();
+		}
+		const result = ExperimentDeliveryConfigSchema.safeParse({...DEFAULT_EXPERIMENT_DELIVERY_CONFIG, ...parsed});
+		if (!result.success) {
+			Logger.error({error: result.error}, 'Invalid experiment delivery config');
+			return cloneDefaultExperimentDeliveryConfig();
+		}
+		return result.data;
+	}
+
+	async setExperimentDeliveryConfig(config: ExperimentDeliveryConfig): Promise<void> {
+		await this.setConfig(EXPERIMENT_DELIVERY_CONFIG_KEY, JSON.stringify(config));
+	}
+
 	async hasLimitConfig(): Promise<boolean> {
 		const raw = await this.getConfig('limit_config');
 		return raw !== null;

fluxer_api/src/api/openapi/openapi.json

@@ -6504,6 +6504,73 @@
 				]
 			}
 		},
+		"/experiments": {
+			"get": {
+				"operationId": "get_experiments",
+				"summary": "Get the experiment assignments",
+				"tags": ["Experiments"],
+				"responses": {
+					"200": {
+						"description": "Success",
+						"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExperimentAssignmentsResponse"}}}
+					},
+					"400": {
+						"description": "Bad Request - The request was malformed or contained invalid data",
+						"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
+					},
+					"401": {
+						"description": "Unauthorized - Authentication is required or the token is invalid",
+						"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
+					},
+					"403": {
+						"description": "Forbidden - You do not have permission to perform this action",
+						"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
+					},
+					"429": {
+						"description": "Too Many Requests - You are being rate limited",
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"properties": {
+										"code": {"type": "string", "enum": ["RATE_LIMITED"]},
+										"message": {"type": "string"},
+										"retry_after": {"type": "number", "description": "Seconds to wait before retrying"},
+										"global": {"type": "boolean", "description": "Whether this is a global rate limit"}
+									},
+									"required": ["code", "message", "retry_after"]
+								}
+							}
+						},
+						"headers": {
+							"Retry-After": {
+								"description": "Number of seconds to wait before retrying (only on 429)",
+								"schema": {"type": "integer"}
+							},
+							"X-RateLimit-Limit": {
+								"description": "The number of requests that can be made in the current window",
+								"schema": {"type": "integer"}
+							},
+							"X-RateLimit-Remaining": {
+								"description": "The number of remaining requests that can be made",
+								"schema": {"type": "integer"}
+							},
+							"X-RateLimit-Reset": {
+								"description": "Unix timestamp when the rate limit resets",
+								"schema": {"type": "integer"}
+							}
+						}
+					},
+					"500": {
+						"description": "Internal Server Error - An unexpected error occurred",
+						"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
+					}
+				},
+				"x-mint": {"metadata": {"title": "Get the experiment assignments"}},
+				"description": "Returns the polling cadence and every experiment assignment resolved for the authenticated user from the instance configuration. Clients revalidate with If-None-Match and receive 304 when nothing changed.",
+				"security": [{"sessionToken": []}, {"botToken": []}]
+			}
+		},
 		"/gateway/bot": {
 			"get": {
 				"operationId": "get_gateway_bot",
@@ -29193,6 +29260,82 @@
 				},
 				"required": ["id", "guild_id", "name", "animated", "allow_cloning"]
 			},
+			"ExperimentAssignmentsResponse": {
+				"type": "object",
+				"properties": {
+					"poll_interval_seconds": {"type": "integer", "format": "int53"},
+					"poll_jitter_percent": {"type": "integer", "minimum": 0, "maximum": 50, "format": "int32"},
+					"assignments": {
+						"type": "object",
+						"properties": {
+							"voice_noise_suppression": {"$ref": "#/components/schemas/VoiceNoiseSuppressionAssignmentResponse"}
+						}
+					}
+				},
+				"required": ["poll_interval_seconds", "poll_jitter_percent", "assignments"]
+			},
+			"VoiceNoiseSuppressionAssignmentResponse": {
+				"type": "object",
+				"properties": {
+					"enabled": {"type": "boolean"},
+					"config_version": {"type": "integer", "format": "int53"},
+					"user_targeted": {"type": "boolean"},
+					"backend": {
+						"anyOf": [
+							{
+								"enum": ["none", "standard", "gate", "speex", "rnnoise", "gtcrn", "deep_filter"],
+								"type": "string",
+								"x-enumNames": ["none", "standard", "gate", "speex", "rnnoise", "gtcrn", "deep_filter"]
+							},
+							{"type": "null"}
+						]
+					},
+					"source": {
+						"anyOf": [
+							{"enum": ["user_rule", "canary"], "type": "string", "x-enumNames": ["user_rule", "canary"]},
+							{"type": "null"}
+						]
+					},
+					"guild_overrides": {
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"guild_id": {"type": "string", "pattern": "^\\d{1,20}$"},
+								"backend": {
+									"enum": ["none", "standard", "gate", "speex", "rnnoise", "gtcrn", "deep_filter"],
+									"type": "string",
+									"x-enumNames": ["none", "standard", "gate", "speex", "rnnoise", "gtcrn", "deep_filter"]
+								}
+							},
+							"required": ["guild_id", "backend"]
+						}
+					},
+					"enabled_backends": {
+						"type": "array",
+						"items": {
+							"enum": ["none", "standard", "gate", "speex", "rnnoise", "gtcrn", "deep_filter"],
+							"type": "string",
+							"x-enumNames": ["none", "standard", "gate", "speex", "rnnoise", "gtcrn", "deep_filter"]
+						}
+					},
+					"allow_user_override": {"type": "boolean"},
+					"stereo_enabled": {"type": "boolean"},
+					"suppression_strength": {"type": "integer", "minimum": 0, "maximum": 100, "format": "int32"}
+				},
+				"required": [
+					"enabled",
+					"config_version",
+					"user_targeted",
+					"backend",
+					"source",
+					"guild_overrides",
+					"enabled_backends",
+					"allow_user_override",
+					"stereo_enabled",
+					"suppression_strength"
+				]
+			},
 			"GatewayBotResponse": {
 				"type": "object",
 				"properties": {
@@ -37887,6 +38030,7 @@
 		{"name": "Connections"},
 		{"name": "Messages"},
 		{"name": "Donations"},
+		{"name": "Experiments"},
 		{"name": "Geolocation"},
 		{"name": "GIFs"},
 		{"name": "GIFs (Deprecated)"},