Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp

feat(api): store community visits and restore them per session

Hampus772d450b54da
diff --git a/fluxer_api/src/api/database/types/GuildVisitTypes.ts b/fluxer_api/src/api/database/types/GuildVisitTypes.ts
new file mode 100644
index 000000000..d615e958a
--- /dev/null
+++ b/fluxer_api/src/api/database/types/GuildVisitTypes.ts
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {GuildID, UserID} from '@app/api/BrandedTypes';
+
+export interface GuildVisitRow {
+ user_id: UserID;
+ guild_id: GuildID;
+ source: number;
+ invite_code: string | null;
+ invite_expires_at: Date | null;
+ started_at: Date;
+ opened_at: Date;
+}
+
+export const GUILD_VISIT_COLUMNS = [
+ 'user_id',
+ 'guild_id',
+ 'source',
+ 'invite_code',
+ 'invite_expires_at',
+ 'started_at',
+ 'opened_at',
+] as const satisfies ReadonlyArray<keyof GuildVisitRow>;
diff --git a/fluxer_api/src/api/experiment/GuildVisitsGate.ts b/fluxer_api/src/api/experiment/GuildVisitsGate.ts
new file mode 100644
index 000000000..101868740
--- /dev/null
+++ b/fluxer_api/src/api/experiment/GuildVisitsGate.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {UserID} from '@app/api/BrandedTypes';
+import {GuildFeatures} from '@fluxer/constants/src/GuildConstants';
+import {
+ type GuildVisitsConfig,
+ GuildVisitsConfigSchema,
+ guildVisitsUserActive,
+} from '@fluxer/schema/src/domains/admin/GuildVisitsSchemas';
+import {EXPERIMENT_BUCKET_RESOLUTION} from '@fluxer/schema/src/domains/experiment/ExperimentBucket';
+
+const DEFAULT_CONFIG: GuildVisitsConfig = GuildVisitsConfigSchema.parse({});
+
+let cachedConfig: GuildVisitsConfig = DEFAULT_CONFIG;
+
+export function setCachedGuildVisitsConfig(config: GuildVisitsConfig | null): void {
+ cachedConfig = config ?? DEFAULT_CONFIG;
+}
+
+export function userGuildVisitsActive(userId: UserID | bigint | string): boolean {
+ return guildVisitsUserActive(cachedConfig, userId.toString());
+}
+
+export function guildVisitsOffer(
+ features: Iterable<string>,
+ userId: UserID | bigint | string | null | undefined,
+): {visits_enabled?: boolean} {
+ let active: boolean;
+ if (userId == null) {
+ active =
+ cachedConfig.enabled &&
+ cachedConfig.excluded_user_ids.length === 0 &&
+ cachedConfig.user_basis_points >= EXPERIMENT_BUCKET_RESOLUTION;
+ } else {
+ active = userGuildVisitsActive(userId);
+ }
+ if (!active) return {};
+ const set = new Set(features);
+ return {visits_enabled: set.has(GuildFeatures.VISITS_ENABLED) && !set.has(GuildFeatures.INVITES_DISABLED)};
+}
diff --git a/fluxer_api/src/api/guild/visits/GuildVisitLifecycle.ts b/fluxer_api/src/api/guild/visits/GuildVisitLifecycle.ts
new file mode 100644
index 000000000..3b7957d8f
--- /dev/null
+++ b/fluxer_api/src/api/guild/visits/GuildVisitLifecycle.ts
@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {GuildID, UserID} from '@app/api/BrandedTypes';
+import {isIpBanExempt} from '@app/api/ban/IpBanExemptions';
+import type {GuildVisitRow} from '@app/api/database/types/GuildVisitTypes';
+import {userGuildVisitsActive} from '@app/api/experiment/GuildVisitsGate';
+import {guildVisitEndedTotal} from '@app/api/guild/visits/GuildVisitMetrics';
+import {forgetGuildVisitRow, guildVisitRepository, markGuildVisitEnded} from '@app/api/guild/visits/GuildVisitorAccess';
+import {bumpGuildVisitorViewGeneration} from '@app/api/guild/visits/GuildVisitorViewGeneration';
+import {emitActivity} from '@app/api/infrastructure/activity/ActivityEvents';
+import type {IGatewayService} from '@app/api/infrastructure/IGatewayService';
+import {Logger} from '@app/api/Logger';
+import {getGatewayService, getKVClient, getWorkerService} from '@app/api/middleware/ServiceRegistry';
+import {getGuildRepository} from '@app/api/middleware/ServiceSingletons';
+import type {User} from '@app/api/models/User';
+import {GuildFeatures} from '@fluxer/constants/src/GuildConstants';
+import {
+ type GuildVisitEndReason,
+ GuildVisitEndReasons,
+ GuildVisitSources,
+} from '@fluxer/constants/src/GuildVisitConstants';
+import {BannedFromGuildError} from '@fluxer/errors/src/domains/guild/BannedFromGuildError';
+import {IpBannedFromGuildError} from '@fluxer/errors/src/domains/guild/IpBannedFromGuildError';
+import {getSameIpDecisionKey, isSameIpDecisionMatch} from '@fluxer/ip_utils/src/IpAddress';
+
+const BAN_MEMO_TTL_SECONDS = 600;
+const GUILD_PAGE_SIZE = 1000;
+
+const END_GUILD_VISITS_FOR_CODE_TASK = 'endGuildVisitsForCode';
+const PRUNE_GUILD_VISITS_TASK = 'pruneGuildVisits';
+const END_UNASSIGNED_GUILD_VISITS_TASK = 'endUnassignedGuildVisits';
+
+export type GuildVisitPruneMode = 'disabled' | 'age_restricted' | 'deleted';
+
+export async function endGuildVisit(params: {
+ userId: UserID;
+ guildId: GuildID;
+ reason: GuildVisitEndReason;
+ gateway?: IGatewayService;
+ notify?: boolean;
+}): Promise<void> {
+ const {userId, guildId, reason} = params;
+ forgetGuildVisitRow(userId, guildId);
+ await markGuildVisitEnded(userId, guildId).catch((error: unknown) =>
+ Logger.warn({userId: userId.toString(), guildId: guildId.toString(), error}, 'Failed to mark a visit as ended'),
+ );
+ await guildVisitRepository().delete(userId, guildId);
+ if (params.notify !== false) {
+ try {
+ await (params.gateway ?? getGatewayService()).endVisit({userId, guildId});
+ } catch (error) {
+ Logger.warn(
+ {userId: userId.toString(), guildId: guildId.toString(), error},
+ 'Failed to end a visit on the gateway',
+ );
+ }
+ }
+ guildVisitEndedTotal.inc(`reason="${reason}"`);
+ void emitActivity('guild_visit_ended', userId.toString(), {
+ user_id: userId.toString(),
+ guild_id: guildId.toString(),
+ cause: reason,
+ });
+}
+
+function banGenerationKey(guildId: GuildID): string {
+ return `guild:ban_gen:${guildId}`;
+}
+
+export async function bumpGuildBanGeneration(guildId: GuildID): Promise<void> {
+ await getKVClient().incr(banGenerationKey(guildId));
+}
+
+export async function assertNotBannedFromGuildVisit(params: {
+ guildId: GuildID;
+ user: Pick<User, 'id' | 'email' | 'lastActiveIp'>;
+ ip: string | null;
+}): Promise<void> {
+ const {guildId, user, ip} = params;
+ const kv = getKVClient();
+ const generation = (await kv.get(banGenerationKey(guildId))) ?? '0';
+ const ipKey = ip ? (getSameIpDecisionKey(ip) ?? ip) : '-';
+ const memoKey = `guild_visit:ban_ok:${guildId}:${user.id}:${ipKey}:${generation}`;
+ if ((await kv.get(memoKey)) !== null) return;
+ const guildRepository = getGuildRepository();
+ const bans = await guildRepository.listBans(guildId);
+ const ips = [ip, user.lastActiveIp].filter((value): value is string => typeof value === 'string' && value !== '');
+ for (const ban of bans) {
+ if (ban.userId === user.id) throw new BannedFromGuildError();
+ for (const candidate of ips) {
+ if (isSameIpDecisionMatch(candidate, ban.ipAddress) && !isIpBanExempt(candidate)) {
+ throw new IpBannedFromGuildError();
+ }
+ }
+ }
+ const email = user.email?.toLowerCase();
+ if (email && (await guildRepository.getBanByEmail(guildId, email))) throw new BannedFromGuildError();
+ await kv.setex(memoKey, BAN_MEMO_TTL_SECONDS, '1');
+}
+
+export async function onGuildBanAdded(params: {
+ guildId: GuildID;
+ targetUserId: UserID;
+ targetIp: string | null;
+ gateway: IGatewayService;
+}): Promise<void> {
+ const {guildId, targetUserId, targetIp, gateway} = params;
+ await bumpGuildBanGeneration(guildId);
+ await bumpGuildVisitorViewGeneration(guildId);
+ if (await guildVisitRepository().get(targetUserId, guildId)) {
+ await endGuildVisit({userId: targetUserId, guildId, reason: GuildVisitEndReasons.BANNED, gateway});
+ }
+ const ipKey = targetIp ? getSameIpDecisionKey(targetIp) : null;
+ if (!ipKey) return;
+ let evicted: Array<UserID> = [];
+ try {
+ evicted = await gateway.evictVisitors({guildId, ipKeys: [ipKey]});
+ } catch (error) {
+ Logger.warn({guildId: guildId.toString(), error}, 'Failed to evict visitors on a banned address');
+ }
+ for (const userId of evicted) {
+ if (userId === targetUserId) continue;
+ await endGuildVisit({userId, guildId, reason: GuildVisitEndReasons.BANNED, gateway});
+ }
+}
+
+export async function enqueueEndGuildVisitsForCode(guildId: GuildID, code: string): Promise<void> {
+ try {
+ await getWorkerService().addJob(END_GUILD_VISITS_FOR_CODE_TASK, {guildId: guildId.toString(), code});
+ } catch (error) {
+ Logger.error({guildId: guildId.toString(), error}, 'Failed to queue ending visits for an invite');
+ }
+}
+
+export async function enqueuePruneGuildVisits(guildId: GuildID, mode: GuildVisitPruneMode): Promise<void> {
+ try {
+ await getWorkerService().addJob(PRUNE_GUILD_VISITS_TASK, {guildId: guildId.toString(), mode});
+ } catch (error) {
+ Logger.error({guildId: guildId.toString(), error}, 'Failed to queue pruning guild visits');
+ }
+}
+
+export async function enqueueEndUnassignedGuildVisits(): Promise<void> {
+ try {
+ await getWorkerService().addJob(END_UNASSIGNED_GUILD_VISITS_TASK, {});
+ } catch (error) {
+ Logger.error({error}, 'Failed to queue ending visits outside the guild visits experiment');
+ }
+}
+
+export async function endUnassignedGuildVisits(gateway: IGatewayService = getGatewayService()): Promise<number> {
+ const repository = guildVisitRepository();
+ let after: UserID | null = null;
+ let ended = 0;
+ do {
+ const page: {userIds: Array<UserID>; next: UserID | null} = await repository.pageVisitorIds(after, GUILD_PAGE_SIZE);
+ for (const userId of page.userIds) {
+ if (userGuildVisitsActive(userId)) continue;
+ for (const row of await repository.list(userId)) {
+ forgetGuildVisitRow(userId, row.guild_id);
+ try {
+ await gateway.endVisit({userId, guildId: row.guild_id});
+ ended++;
+ } catch (error) {
+ Logger.warn(
+ {userId: userId.toString(), guildId: row.guild_id.toString(), error},
+ 'Failed to end a visit on the gateway',
+ );
+ }
+ }
+ }
+ after = page.next;
+ } while (after !== null);
+ return ended;
+}
+
+export async function onGuildVisitSettingsChanged(params: {
+ guildId: GuildID;
+ before: {features: ReadonlySet<string>; nsfw: boolean};
+ after: {features: ReadonlySet<string>; nsfw: boolean};
+}): Promise<void> {
+ const {guildId, before, after} = params;
+ await bumpGuildVisitorViewGeneration(guildId);
+ if (before.features.has(GuildFeatures.VISITS_ENABLED) && !after.features.has(GuildFeatures.VISITS_ENABLED)) {
+ await enqueuePruneGuildVisits(guildId, 'disabled');
+ }
+ if (!before.nsfw && after.nsfw) {
+ await enqueuePruneGuildVisits(guildId, 'age_restricted');
+ }
+}
+
+async function forEachGuildVisit(guildId: GuildID, visit: (row: GuildVisitRow) => Promise<void>): Promise<number> {
+ let after: UserID | null = null;
+ let count = 0;
+ do {
+ const page: {rows: Array<GuildVisitRow>; next: UserID | null} = await guildVisitRepository().pageByGuild(
+ guildId,
+ after,
+ GUILD_PAGE_SIZE,
+ );
+ for (const row of page.rows) {
+ await visit(row);
+ count++;
+ }
+ after = page.next;
+ } while (after !== null);
+ return count;
+}
+
+export async function endGuildVisitsForCode(guildId: GuildID, code: string): Promise<number> {
+ let ended = 0;
+ await forEachGuildVisit(guildId, async (row) => {
+ if (row.invite_code !== code) return;
+ await endGuildVisit({userId: row.user_id, guildId, reason: GuildVisitEndReasons.INVITE_REVOKED});
+ ended++;
+ });
+ return ended;
+}
+
+export async function pruneGuildVisits(
+ guildId: GuildID,
+ mode: GuildVisitPruneMode,
+ adultContentAllowed: (userId: UserID) => Promise<boolean>,
+): Promise<number> {
+ let ended = 0;
+ await forEachGuildVisit(guildId, async (row) => {
+ if (mode === 'disabled' && row.source === GuildVisitSources.OPERATOR) return;
+ if (mode === 'age_restricted' && (await adultContentAllowed(row.user_id))) return;
+ const reason = mode === 'age_restricted' ? GuildVisitEndReasons.AGE_RESTRICTED : GuildVisitEndReasons.DISABLED;
+ await endGuildVisit({userId: row.user_id, guildId, reason});
+ ended++;
+ });
+ return ended;
+}
diff --git a/fluxer_api/src/api/guild/visits/GuildVisitMetrics.ts b/fluxer_api/src/api/guild/visits/GuildVisitMetrics.ts
new file mode 100644
index 000000000..8cae656e4
--- /dev/null
+++ b/fluxer_api/src/api/guild/visits/GuildVisitMetrics.ts
@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {registerCounter} from '@fluxer/hono/src/middleware/Metrics';
+
+export const guildVisitStartTotal = registerCounter(
+ 'fluxer_api_guild_visit_start_total',
+ 'Guild visits started, by source and account tier',
+);
+export const guildVisitEndedTotal = registerCounter(
+ 'fluxer_api_guild_visit_end_total',
+ 'Guild visits ended, by reason',
+);
+export const guildVisitJoinTotal = registerCounter(
+ 'fluxer_api_guild_visit_join_total',
+ 'Guild visits converted into membership',
+);
+export const guildVisitorRateLimitedTotal = registerCounter(
+ 'fluxer_api_guild_visitor_rate_limited_total',
+ 'Visitor reads refused by a visitor bucket, by key kind',
+);
+export const guildVisitHistoryWindowTotal = registerCounter(
+ 'fluxer_api_guild_visit_history_window_total',
+ 'Visitor reads that hit the history window for accounts without a confirmed email',
+);
diff --git a/fluxer_api/src/api/guild/visits/GuildVisitRepository.ts b/fluxer_api/src/api/guild/visits/GuildVisitRepository.ts
new file mode 100644
index 000000000..567a7ba1c
--- /dev/null
+++ b/fluxer_api/src/api/guild/visits/GuildVisitRepository.ts
@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {GuildID, UserID} from '@app/api/BrandedTypes';
+import {BatchBuilder, fetchMany, fetchOne} from '@app/api/database/CassandraQueryExecution';
+import type {GuildVisitRow} from '@app/api/database/types/GuildVisitTypes';
+import {GuildVisitsByGuild, GuildVisitsByUser} from '@app/api/Tables';
+import {GUILD_VISIT_TTL_SECONDS} from '@fluxer/constants/src/GuildVisitConstants';
+
+const MAX_GUILD_PAGE = 5000;
+const USER_PARTITION_LIMIT = 200;
+
+const GET_CQL = GuildVisitsByUser.selectCql({
+ where: [GuildVisitsByUser.where.eq('user_id'), GuildVisitsByUser.where.eq('guild_id')],
+ limit: 1,
+});
+const LIST_CQL = GuildVisitsByUser.selectCql({
+ where: GuildVisitsByUser.where.eq('user_id'),
+ limit: USER_PARTITION_LIMIT,
+});
+const pageByGuildQuery = (limit: number) =>
+ GuildVisitsByGuild.select({
+ where: [GuildVisitsByGuild.where.eq('guild_id'), GuildVisitsByGuild.where.gt('user_id', 'after_user_id')],
+ limit,
+ });
+const firstPageByGuildQuery = (limit: number) =>
+ GuildVisitsByGuild.select({where: GuildVisitsByGuild.where.eq('guild_id'), limit});
+const pageAllQuery = (limit: number) =>
+ GuildVisitsByUser.select({where: GuildVisitsByUser.where.tokenGt('user_id', 'after_user_id'), limit});
+const firstPageAllQuery = (limit: number) => GuildVisitsByUser.select({limit});
+
+export class GuildVisitRepository {
+ async get(userId: UserID, guildId: GuildID): Promise<GuildVisitRow | null> {
+ return fetchOne<GuildVisitRow>(GET_CQL, {user_id: userId, guild_id: guildId});
+ }
+
+ async list(userId: UserID): Promise<Array<GuildVisitRow>> {
+ return fetchMany<GuildVisitRow>(LIST_CQL, {user_id: userId});
+ }
+
+ async upsert(row: GuildVisitRow, now: Date = new Date()): Promise<boolean> {
+ let ttl: number;
+ if (row.invite_expires_at === null) {
+ ttl = GUILD_VISIT_TTL_SECONDS;
+ } else {
+ const remaining = Math.floor((row.invite_expires_at.getTime() - now.getTime()) / 1000);
+ ttl = Math.max(0, Math.min(GUILD_VISIT_TTL_SECONDS, remaining));
+ }
+ if (ttl <= 0) return false;
+ const batch = new BatchBuilder();
+ batch.addPrepared(GuildVisitsByUser.insertWithTtl(row, ttl));
+ batch.addPrepared(GuildVisitsByGuild.insertWithTtl(row, ttl));
+ await batch.execute();
+ return true;
+ }
+
+ async touch(row: GuildVisitRow, now: Date = new Date()): Promise<GuildVisitRow> {
+ const touched = {...row, opened_at: now};
+ await this.upsert(touched, now);
+ return touched;
+ }
+
+ async delete(userId: UserID, guildId: GuildID): Promise<void> {
+ const batch = new BatchBuilder();
+ batch.addPrepared(GuildVisitsByUser.deleteByPk({user_id: userId, guild_id: guildId}));
+ batch.addPrepared(GuildVisitsByGuild.deleteByPk({guild_id: guildId, user_id: userId}));
+ await batch.execute();
+ }
+
+ async deleteAllForUser(userId: UserID): Promise<Array<GuildID>> {
+ const rows = await this.list(userId);
+ for (const row of rows) {
+ await this.delete(userId, row.guild_id);
+ }
+ return rows.map((row) => row.guild_id);
+ }
+
+ async pageByGuild(
+ guildId: GuildID,
+ afterUserId: UserID | null,
+ limit: number,
+ ): Promise<{rows: Array<GuildVisitRow>; next: UserID | null}> {
+ const bounded = Math.max(1, Math.min(MAX_GUILD_PAGE, Math.floor(limit)));
+ const rows =
+ afterUserId === null
+ ? await fetchMany<GuildVisitRow>(firstPageByGuildQuery(bounded).bind({guild_id: guildId}))
+ : await fetchMany<GuildVisitRow>(
+ pageByGuildQuery(bounded).bind({guild_id: guildId, after_user_id: afterUserId}),
+ );
+ const next = rows.length === bounded ? rows[rows.length - 1]!.user_id : null;
+ return {rows, next};
+ }
+
+ async pageVisitorIds(
+ afterUserId: UserID | null,
+ limit: number,
+ ): Promise<{userIds: Array<UserID>; next: UserID | null}> {
+ const bounded = Math.max(1, Math.min(MAX_GUILD_PAGE, Math.floor(limit)));
+ const rows =
+ afterUserId === null
+ ? await fetchMany<GuildVisitRow>(firstPageAllQuery(bounded).bind({}))
+ : await fetchMany<GuildVisitRow>(pageAllQuery(bounded).bind({after_user_id: afterUserId}));
+ const userIds = [...new Set(rows.map((row) => row.user_id))];
+ const next = rows.length === bounded ? rows[rows.length - 1]!.user_id : null;
+ return {userIds, next};
+ }
+}
diff --git a/fluxer_api/src/api/guild/visits/GuildVisitSession.ts b/fluxer_api/src/api/guild/visits/GuildVisitSession.ts
new file mode 100644
index 000000000..c5608da84
--- /dev/null
+++ b/fluxer_api/src/api/guild/visits/GuildVisitSession.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {createInviteCode, type GuildID} from '@app/api/BrandedTypes';
+import type {GuildVisitRow} from '@app/api/database/types/GuildVisitTypes';
+import {userGuildVisitsActive} from '@app/api/experiment/GuildVisitsGate';
+import {assertNotBannedFromGuildVisit, endGuildVisit} from '@app/api/guild/visits/GuildVisitLifecycle';
+import {
+ guildVisitAuthorizedByView,
+ guildVisitRepository,
+ loadGuildVisitorView,
+} from '@app/api/guild/visits/GuildVisitorAccess';
+import {maxGuildVisitsFor} from '@app/api/guild/visits/GuildVisitService';
+import {getInviteRepository, getLimitConfigService} from '@app/api/middleware/ServiceSingletons';
+import type {User} from '@app/api/models/User';
+import {canUserAccessNsfwContent} from '@app/api/utils/AgeUtils';
+import {GuildVisitEndReasons, GuildVisitSources} from '@fluxer/constants/src/GuildVisitConstants';
+import {BannedFromGuildError} from '@fluxer/errors/src/domains/guild/BannedFromGuildError';
+import {IpBannedFromGuildError} from '@fluxer/errors/src/domains/guild/IpBannedFromGuildError';
+
+export interface SessionGuildVisit {
+ guildId: GuildID;
+ operator: boolean;
+}
+
+type SessionVisitCheck = 'keep' | 'drop' | keyof typeof GuildVisitEndReasons;
+
+async function checkSessionVisit(
+ row: GuildVisitRow,
+ user: User,
+ ip: string | null,
+ now: number,
+): Promise<SessionVisitCheck> {
+ if (row.invite_expires_at !== null && row.invite_expires_at.getTime() <= now) return 'EXPIRED';
+ const view = await loadGuildVisitorView(row.guild_id);
+ if (!view || !guildVisitAuthorizedByView(row, view)) return 'drop';
+ if (view.guild.nsfw && !canUserAccessNsfwContent(user)) return 'drop';
+ if (row.source === GuildVisitSources.INVITE || row.source === GuildVisitSources.VANITY_URL) {
+ const invite = row.invite_code ? await getInviteRepository().findUnique(createInviteCode(row.invite_code)) : null;
+ if (!invite || invite.guildId !== row.guild_id) return 'INVITE_REVOKED';
+ }
+ try {
+ await assertNotBannedFromGuildVisit({guildId: row.guild_id, user, ip});
+ } catch (error) {
+ if (error instanceof BannedFromGuildError || error instanceof IpBannedFromGuildError) {
+ return 'BANNED';
+ }
+ throw error;
+ }
+ return 'keep';
+}
+
+export async function resolveSessionGuildVisits(params: {
+ user: User;
+ ip: string | null;
+ memberGuildIds: ReadonlyArray<GuildID>;
+}): Promise<Array<SessionGuildVisit>> {
+ const {user, ip} = params;
+ if (user.isBot || !userGuildVisitsActive(user.id)) return [];
+ const members = new Set(params.memberGuildIds.map((guildId) => guildId.toString()));
+ const rows = await guildVisitRepository().list(user.id);
+ const now = Date.now();
+ const kept: Array<SessionGuildVisit> = [];
+ const cap = maxGuildVisitsFor(user, getLimitConfigService());
+ const ordered = [...rows].sort((left, right) => right.opened_at.getTime() - left.opened_at.getTime());
+ for (const row of ordered) {
+ if (members.has(row.guild_id.toString())) {
+ await guildVisitRepository().delete(user.id, row.guild_id);
+ continue;
+ }
+ if (kept.length >= cap) break;
+ const check = await checkSessionVisit(row, user, ip, now);
+ if (check === 'keep') {
+ kept.push({guildId: row.guild_id, operator: row.source === GuildVisitSources.OPERATOR});
+ } else if (check !== 'drop') {
+ await endGuildVisit({userId: user.id, guildId: row.guild_id, reason: GuildVisitEndReasons[check], notify: false});
+ }
+ }
+ return kept;
+}
diff --git a/fluxer_api/src/api/guild/visits/GuildVisitorViewGeneration.ts b/fluxer_api/src/api/guild/visits/GuildVisitorViewGeneration.ts
new file mode 100644
index 000000000..343bab632
--- /dev/null
+++ b/fluxer_api/src/api/guild/visits/GuildVisitorViewGeneration.ts
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {GuildID} from '@app/api/BrandedTypes';
+import type {GuildRow} from '@app/api/database/types/GuildTypes';
+import {getKVClient} from '@app/api/middleware/ServiceRegistry';
+
+const VISITOR_VIEW_FIELDS = [
+ 'features',
+ 'nsfw',
+ 'nsfw_level',
+ 'message_history_cutoff',
+ 'disabled_operations',
+] as const satisfies ReadonlyArray<keyof GuildRow>;
+
+function guildVisitorViewGenerationKey(guildId: GuildID): string {
+ return `guild:visitor_view_gen:${guildId}`;
+}
+
+export async function readGuildVisitorViewGeneration(guildId: GuildID): Promise<string> {
+ return (await getKVClient().get(guildVisitorViewGenerationKey(guildId))) ?? '0';
+}
+
+export async function bumpGuildVisitorViewGeneration(guildId: GuildID): Promise<void> {
+ await getKVClient().incr(guildVisitorViewGenerationKey(guildId));
+}
+
+function sameValue(left: unknown, right: unknown): boolean {
+ if (left instanceof Set && right instanceof Set) {
+ return left.size === right.size && [...left].every((value) => right.has(value));
+ }
+ if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+ return (left ?? null) === (right ?? null);
+}
+
+export function touchesGuildVisitorView(patch: Partial<GuildRow>, previous: GuildRow | null | undefined): boolean {
+ return VISITOR_VIEW_FIELDS.some(
+ (field) => field in patch && (previous == null || !sameValue(patch[field], previous[field])),
+ );
+}
diff --git a/fluxer_api/src/api/rate_limit_configs/GuildVisitRateLimitConfig.ts b/fluxer_api/src/api/rate_limit_configs/GuildVisitRateLimitConfig.ts
new file mode 100644
index 000000000..6cf01f85c
--- /dev/null
+++ b/fluxer_api/src/api/rate_limit_configs/GuildVisitRateLimitConfig.ts
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {RouteRateLimitConfig} from '@app/api/middleware/RateLimitMiddleware';
+import {ms} from 'itty-time';
+
+export const GuildVisitRateLimitConfigs = {
+ GUILD_VISIT_START: {
+ bucket: 'guild:visit:start',
+ config: {limit: 10, windowMs: ms('60 seconds')},
+ } as RouteRateLimitConfig,
+ USER_GUILD_VISITS: {
+ bucket: 'user:guild_visits',
+ config: {limit: 30, windowMs: ms('10 seconds')},
+ } as RouteRateLimitConfig,
+} as const;
diff --git a/fluxer_api/src/api/worker/tasks/GuildVisitTasks.ts b/fluxer_api/src/api/worker/tasks/GuildVisitTasks.ts
new file mode 100644
index 000000000..3e2f28589
--- /dev/null
+++ b/fluxer_api/src/api/worker/tasks/GuildVisitTasks.ts
@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {createGuildID, type UserID} from '@app/api/BrandedTypes';
+import {
+ endGuildVisitsForCode,
+ endUnassignedGuildVisits,
+ pruneGuildVisits,
+} from '@app/api/guild/visits/GuildVisitLifecycle';
+import {getInstanceConfigRepository, getUserRepository} from '@app/api/middleware/ServiceSingletons';
+import {canUserAccessNsfwContent} from '@app/api/utils/AgeUtils';
+import type {WorkerTaskHandler} from '@pkgs/worker/src/contracts/WorkerTask';
+import {z} from 'zod';
+
+const EndForCodePayload = z.object({
+ guildId: z.string().regex(/^\d{1,20}$/u),
+ code: z.string().min(1).max(64),
+});
+
+const PrunePayload = z.object({
+ guildId: z.string().regex(/^\d{1,20}$/u),
+ mode: z.enum(['disabled', 'age_restricted', 'deleted']),
+});
+
+async function adultContentAllowed(userId: UserID): Promise<boolean> {
+ const user = await getUserRepository().findUnique(userId);
+ return user !== null && canUserAccessNsfwContent(user);
+}
+
+export const endGuildVisitsForCodeTask: WorkerTaskHandler = async (payload, helpers) => {
+ const {guildId, code} = EndForCodePayload.parse(payload);
+ const ended = await endGuildVisitsForCode(createGuildID(BigInt(guildId)), code);
+ helpers.logger.debug({guildId, ended}, 'Ended visits for a removed invite');
+};
+
+export const pruneGuildVisitsTask: WorkerTaskHandler = async (payload, helpers) => {
+ const {guildId, mode} = PrunePayload.parse(payload);
+ const ended = await pruneGuildVisits(createGuildID(BigInt(guildId)), mode, adultContentAllowed);
+ helpers.logger.debug({guildId, mode, ended}, 'Pruned guild visits');
+};
+
+export const endUnassignedGuildVisitsTask: WorkerTaskHandler = async (_payload, helpers) => {
+ await getInstanceConfigRepository().getGuildVisitsConfig();
+ const ended = await endUnassignedGuildVisits();
+ helpers.logger.debug({ended}, 'Ended visits outside the guild visits experiment');
+};