From f3f4ca2c9fd234522d96306d51a9230856d085a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20M=C3=BCller?= Date: Mon, 16 Nov 2026 17:48:33 +0100 Subject: [PATCH] Answer a retried feedback submission with the one already saved When a submission saved but its response never reached the phone, the form showed an error, the visitor tapped "Feedback absenden" again, and a second identical row was stored (seen twice in production: 82/83, 87/88). The form now sends a clientToken, one UUID per visit, on every attempt. A token that is already stored returns the original submissionId and saves nothing; the lookup runs before the eligibility check, so a retry still succeeds if the feedback window closed in between. Two concurrent retries are settled by a UNIQUE index on submissions.client_token: the loser gets ER_DUP_ENTRY, rolls back and returns the winner's id. A missing or non-UUID token behaves as before, so cached copies of the old form still submit. Migration 003 must be applied before this is deployed - the INSERT now writes client_token. Co-Authored-By: Claude Opus 5.5 --- docker/init/02-feedback-schema.sql | 1 + .../003_add_submission_client_token.sql | 14 ++ .../feedback/public/submission.interface.ts | 5 + .../feedback/public/submissions.service.ts | 66 +++++++-- test/feedback/submissions.idempotency.test.ts | 127 ++++++++++++++++++ 5 files changed, 202 insertions(+), 11 deletions(-) create mode 100644 sql/feedback/003_add_submission_client_token.sql create mode 100644 test/feedback/submissions.idempotency.test.ts diff --git a/docker/init/02-feedback-schema.sql b/docker/init/02-feedback-schema.sql index 26546b0..48e7a83 100644 --- a/docker/init/02-feedback-schema.sql +++ b/docker/init/02-feedback-schema.sql @@ -1,3 +1,4 @@ USE nachklang_feedback; SOURCE /migrations/feedback/001_init.sql; SOURCE /migrations/feedback/002_add_poster_image_url.sql; +SOURCE /migrations/feedback/003_add_submission_client_token.sql; diff --git a/sql/feedback/003_add_submission_client_token.sql b/sql/feedback/003_add_submission_client_token.sql new file mode 100644 index 0000000..f91b461 --- /dev/null +++ b/sql/feedback/003_add_submission_client_token.sql @@ -0,0 +1,14 @@ +-- Nachklang e.V. Feedback module — makes submitting idempotent per form visit. +-- Apply manually against the FEEDBACK_DB database, after 002_add_poster_image_url.sql: +-- mysql -h -u -p < 003_add_submission_client_token.sql +-- +-- The form generates one UUID per visit and resends it on every retry. When +-- a submission saved but its response never reached the phone, the visitor +-- sees an error and taps "absenden" again; the API now finds the stored token +-- and answers with the original submission instead of saving a copy. +-- +-- NULL for every row written before this migration and for any client that +-- sends no token; a UNIQUE index allows any number of NULLs. +ALTER TABLE submissions + ADD COLUMN client_token CHAR(36) NULL AFTER ip_hash, + ADD UNIQUE KEY uq_sub_client_token (client_token); diff --git a/src/models/feedback/public/submission.interface.ts b/src/models/feedback/public/submission.interface.ts index 933d098..be5fcbe 100644 --- a/src/models/feedback/public/submission.interface.ts +++ b/src/models/feedback/public/submission.interface.ts @@ -56,6 +56,10 @@ * website: * type: string * description: Honeypot field. Must stay empty; a real visitor never fills it in. + * clientToken: + * type: string + * format: uuid + * description: Generated once per form and resent on every retry. A retry whose token is already stored returns the original submissionId instead of saving a duplicate. Optional; a value that isn't a UUID is ignored. * SubmissionResponse: * type: object * properties: @@ -95,4 +99,5 @@ export interface SubmissionRequestBody { guestBook?: GuestBookInput; newsletter?: NewsletterInput; website?: string; + clientToken?: string; } diff --git a/src/models/feedback/public/submissions.service.ts b/src/models/feedback/public/submissions.service.ts index 900ba93..51d2dfd 100644 --- a/src/models/feedback/public/submissions.service.ts +++ b/src/models/feedback/public/submissions.service.ts @@ -11,6 +11,8 @@ const CONSENT_TEXT_VERSION = '2026-08-02'; const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; +const CLIENT_TOKEN_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; + // A real setlist tops out around a few dozen songs and a handful of // questions, so a legitimate submission never comes close to this. Caps // total generated rows regardless of how large the client's answers/ratings @@ -136,6 +138,27 @@ export const validateNewsletter = (input?: NewsletterInput): ValidatedNewsletter return {firstName, lastName, email}; }; +/** + * The form generates one UUID per visit and resends it on every retry, so a + * request whose response was lost (the row saved, but the phone never heard + * back) can be told apart from a genuinely new submission. Anything that + * isn't a UUID is treated as "no token" rather than rejected - an old cached + * copy of the form must still be able to submit. + */ +export const normalizeClientToken = (token: unknown): string | null => { + return typeof token === 'string' && CLIENT_TOKEN_RE.test(token) ? token.toLowerCase() : null; +}; + +const findSubmissionIdByClientToken = async (clientToken: string): Promise => { + const conn = await NachklangFeedbackDB.getConnection(); + try { + const rows = await conn.query('SELECT submission_id FROM submissions WHERE client_token = ?', [clientToken]); + return rows.length > 0 ? rows[0].submission_id : null; + } finally { + await conn.end(); + } +}; + export type SubmitResult = | { status: 'OK'; submissionId: number; newsletterDropped: boolean } | { status: 'NOT_FOUND' } @@ -146,9 +169,29 @@ export type SubmitResult = * Validates and persists one feedback submission. Re-checks event * eligibility (the window may have closed between page load and submit), * validates every answer against the event's live questions/songs, then - * inserts everything in a single transaction. + * inserts everything in a single transaction. A retry carrying an already + * stored client token gets the original submission back instead of a copy. */ export const submitFeedback = async (slug: string, body: SubmissionRequestBody, ipHash: string | null): Promise => { + const clientToken = normalizeClientToken(body.clientToken); + const newsletter = validateNewsletter(body.newsletter); + // body.newsletter is only sent at all when the visitor had the opt-in + // checkbox on (see FeedbackForm.tsx), so a present-but-invalid block + // (e.g. a mistyped email) is distinguishable from "didn't opt in" - the + // rest of the submission still saves, but the client can tell the + // visitor their newsletter signup specifically didn't go through. + const newsletterDropped = !!body.newsletter && !newsletter; + + // Checked before eligibility, so a retry still succeeds if the feedback + // window closed in the seconds after the original saved. + if (clientToken) { + const existingId = await findSubmissionIdByClientToken(clientToken); + if (existingId !== null) { + logger.info('Feedback submission retry answered with the stored submission', {submissionId: existingId}); + return {status: 'OK', submissionId: existingId, newsletterDropped}; + } + } + const lookup = await getEventConfigBySlug(slug); if (lookup.status === 'NOT_FOUND') return {status: 'NOT_FOUND'}; if (lookup.status === 'CLOSED') return {status: 'CLOSED'}; @@ -159,13 +202,6 @@ export const submitFeedback = async (slug: string, body: SubmissionRequestBody, const answerRows = validateAnswers(body.answers || [], questionsById, songTitleById); const guestBook = validateGuestBook(body.guestBook); - const newsletter = validateNewsletter(body.newsletter); - // body.newsletter is only sent at all when the visitor had the opt-in - // checkbox on (see FeedbackForm.tsx), so a present-but-invalid block - // (e.g. a mistyped email) is distinguishable from "didn't opt in" - the - // rest of the submission still saves, but the client can tell the - // visitor their newsletter signup specifically didn't go through. - const newsletterDropped = !!body.newsletter && !newsletter; if (answerRows.length === 0 && !guestBook && !newsletter) { return {status: 'EMPTY'}; @@ -175,8 +211,8 @@ export const submitFeedback = async (slug: string, body: SubmissionRequestBody, try { await conn.beginTransaction(); - const subQuery = 'INSERT INTO submissions (event_id, ip_hash, has_guestbook, has_newsletter) VALUES (?,?,?,?) RETURNING submission_id'; - const subRes = await conn.query(subQuery, [eventId, ipHash, guestBook ? 1 : 0, newsletter ? 1 : 0]); + const subQuery = 'INSERT INTO submissions (event_id, ip_hash, has_guestbook, has_newsletter, client_token) VALUES (?,?,?,?,?) RETURNING submission_id'; + const subRes = await conn.query(subQuery, [eventId, ipHash, guestBook ? 1 : 0, newsletter ? 1 : 0, clientToken]); const submissionId = subRes[0].submission_id; for (const row of answerRows) { @@ -220,8 +256,16 @@ export const submitFeedback = async (slug: string, body: SubmissionRequestBody, } return {status: 'OK', submissionId, newsletterDropped}; - } catch (err) { + } catch (err: any) { await conn.rollback(); + // Two copies of the same retry both got past the lookup above; the + // unique index on client_token let only one of them commit. + if (clientToken && err?.code === 'ER_DUP_ENTRY') { + const existingId = await findSubmissionIdByClientToken(clientToken); + if (existingId !== null) { + return {status: 'OK', submissionId: existingId, newsletterDropped}; + } + } throw err; } finally { await conn.end(); diff --git a/test/feedback/submissions.idempotency.test.ts b/test/feedback/submissions.idempotency.test.ts new file mode 100644 index 0000000..e78f5b9 --- /dev/null +++ b/test/feedback/submissions.idempotency.test.ts @@ -0,0 +1,127 @@ +import {vi, describe, it, expect, beforeEach, type Mock} from 'vitest'; +vi.mock('../../src/models/feedback/Feedback.db.js', () => ({ + NachklangFeedbackDB: {getConnection: vi.fn()} +})); +vi.mock('../../src/models/feedback/public/events.public.service.js', () => ({ + getEventConfigBySlug: vi.fn() +})); +vi.mock('../../src/models/feedback/integrations/salesforce.service.js', () => ({ + syncNewsletterSignup: vi.fn().mockResolvedValue(undefined) +})); +vi.mock('../../src/middleware/logger.js', () => ({ + __esModule: true, + default: {info: vi.fn(), error: vi.fn()} +})); + +import {NachklangFeedbackDB} from '../../src/models/feedback/Feedback.db.js'; +import {getEventConfigBySlug} from '../../src/models/feedback/public/events.public.service.js'; +import {submitFeedback} from '../../src/models/feedback/public/submissions.service.js'; + +const mockGetConnection = NachklangFeedbackDB.getConnection as Mock; +const mockGetEventConfigBySlug = getEventConfigBySlug as Mock; + +const TOKEN = '3f2b8c1e-4d5a-4b6c-9e7f-0a1b2c3d4e5f'; +const BODY = {answers: [{eventQuestionId: 26, text: 'Danke!'}], clientToken: TOKEN}; + +// One fake connection serves every query; `existingId` is what a lookup by +// client_token finds, and `insertError` makes the submissions INSERT throw. +const makeConn = ({existingId = null, insertError = null}: {existingId?: number | null; insertError?: any} = {}) => ({ + query: vi.fn(async (sql: string) => { + if (sql.startsWith('SELECT submission_id FROM submissions')) { + return existingId === null ? [] : [{submission_id: existingId}]; + } + if (sql.startsWith('INSERT INTO submissions')) { + if (insertError) throw insertError; + return [{submission_id: 90}]; + } + return []; + }), + beginTransaction: vi.fn().mockResolvedValue(undefined), + commit: vi.fn().mockResolvedValue(undefined), + rollback: vi.fn().mockResolvedValue(undefined), + end: vi.fn().mockResolvedValue(undefined) +}); + +const allQueries = (conn: ReturnType): [string, any[]][] => conn.query.mock.calls as any; + +describe('submitFeedback - client token idempotency', () => { + beforeEach(() => { + mockGetConnection.mockReset(); + mockGetEventConfigBySlug.mockReset(); + mockGetEventConfigBySlug.mockResolvedValue({ + status: 'OK', + eventId: 22, + event: { + questions: [{eventQuestionId: 26, questionId: 4, type: 'FREE_TEXT', label: 'Sonstiges', position: 0}], + songs: [] + } + }); + }); + + it('returns the already-saved submission for a repeated token without inserting again', async () => { + const conn = makeConn({existingId: 82}); + mockGetConnection.mockResolvedValue(conn); + + const result = await submitFeedback('sommerkonzert-2026', BODY, 'hash'); + + expect(result).toEqual({status: 'OK', submissionId: 82, newsletterDropped: false}); + expect(allQueries(conn).some(([sql]) => sql.startsWith('INSERT'))).toBe(false); + }); + + it('still answers a retry with the saved submission after the feedback window closed', async () => { + mockGetConnection.mockResolvedValue(makeConn({existingId: 82})); + mockGetEventConfigBySlug.mockResolvedValue({status: 'CLOSED'}); + + const result = await submitFeedback('sommerkonzert-2026', BODY, 'hash'); + + expect(result).toEqual({status: 'OK', submissionId: 82, newsletterDropped: false}); + }); + + it('stores a new token, lowercased, on the submissions row', async () => { + const conn = makeConn(); + mockGetConnection.mockResolvedValue(conn); + + const result = await submitFeedback('sommerkonzert-2026', {...BODY, clientToken: TOKEN.toUpperCase()}, 'hash'); + + expect(result).toEqual({status: 'OK', submissionId: 90, newsletterDropped: false}); + const insert = allQueries(conn).find(([sql]) => sql.startsWith('INSERT INTO submissions'))!; + expect(insert[1]).toContain(TOKEN); + }); + + it('ignores a malformed token: no lookup, and the row is stored without one', async () => { + const conn = makeConn(); + mockGetConnection.mockResolvedValue(conn); + + await submitFeedback('sommerkonzert-2026', {...BODY, clientToken: 'not-a-uuid'}, 'hash'); + + expect(allQueries(conn).some(([sql]) => sql.startsWith('SELECT submission_id FROM submissions'))).toBe(false); + const insert = allQueries(conn).find(([sql]) => sql.startsWith('INSERT INTO submissions'))!; + expect(insert[1]).not.toContain('not-a-uuid'); + expect(insert[1][insert[1].length - 1]).toBeNull(); + }); + + it('resolves a concurrent duplicate that loses the race on the unique index to the winning submission', async () => { + const dupError = Object.assign(new Error('Duplicate entry'), {code: 'ER_DUP_ENTRY', errno: 1062}); + const racingConn = makeConn({insertError: dupError}); + // First lookup (before the INSERT) finds nothing; the one after the + // duplicate-key error finds the row the other request committed. + const lookupAfterRace = makeConn({existingId: 83}); + mockGetConnection + .mockResolvedValueOnce(makeConn()) + .mockResolvedValueOnce(racingConn) + .mockResolvedValueOnce(lookupAfterRace); + + const result = await submitFeedback('sommerkonzert-2026', BODY, 'hash'); + + expect(result).toEqual({status: 'OK', submissionId: 83, newsletterDropped: false}); + expect(racingConn.rollback).toHaveBeenCalled(); + expect(racingConn.commit).not.toHaveBeenCalled(); + }); + + it('rethrows a duplicate-key error when the request carried no token', async () => { + const dupError = Object.assign(new Error('Duplicate entry'), {code: 'ER_DUP_ENTRY', errno: 1062}); + mockGetConnection.mockResolvedValue(makeConn({insertError: dupError})); + + await expect(submitFeedback('sommerkonzert-2026', {answers: BODY.answers}, 'hash')).rejects.toThrow('Duplicate entry'); + }); +});