feat(votes): add proxy endpoint for submitting vote responses (#657)

audigregorie · cursoragent · asithade · web-flow · commit c9ecc4350be1 · 2026-05-07T12:59:19.000-07:00
* feat(votes): add proxy endpoint for submitting vote responses (LFXV2-1585) Adds POST /votes/responses on the SSR server that proxies a ballot submission to the upstream POST /vote_responses using the user's bearer token, so the response is attributed to the actual voter (no M2M). After the write, polls the query service until the indexed vote_response reflects 'submitted' status, mirroring the fetchPendingVotes query shape so the next pending-actions read is consistent with the write. Promotes the inline VoteResponseRow type from user.service.ts to a shared IndexedVoteResponse interface in @lfx-one/shared, and adds shared CreateVoteResponseRequest / VoteAnswerInput / RankedChoiceInput request types aligned with the upstream voting service contract. Disambiguates UID validation errors via an optional fieldName on validateUidParameter (defaults to 'uid' to preserve existing call sites), and reorders the literal-segment POST /responses route above the /:uid handlers as a forward-compat safety net for any future POST /:uid route. Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(votes): reject vote content when abstaining (LFXV2-1585) Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(votes): guard validateUidParameter against non-string input (LFXV2-1585) Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(votes): reject any user_vote_content presence when abstaining (LFXV2-1585) Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(votes): normalize abstain payload and validate answer shape (LFXV2-1585) Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(votes): use validateRequiredParameter for body fields (LFXV2-1585) Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(votes): address PR review feedback (LFXV2-1585) Extract validationContext, guard against null answer elements, add X-Sync header to vote response POST, and add INFO log for ballot acceptance. Signed-off-by: Audi Young <audi.mycloud@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> * style(votes): collapse ServiceValidationError calls to match printWidth=160 (LFXV2-1585) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Audi Young <audi.mycloud@gmail.com> * fix(votes): align createVoteResponse with codebase patterns (LFXV2-1585) - Demote post-POST INFO log to DEBUG to match createVote, enableVote, createSurvey, createMeeting which all rely on the controller's logger.success for the single INFO line per write request. - Build upstream payload immutably in createVoteResponse controller instead of mutating req.body.user_vote_content. - Include vote_id in pendingVoteUids fallback chain so v1-only indexer rows are not silently dropped. Signed-off-by: Asitha de Silva <asithade@gmail.com> --------- Signed-off-by: Audi Young <audi.mycloud@gmail.com> Signed-off-by: Asitha de Silva <asithade@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Asitha de Silva <asithade@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
diff --git a/apps/lfx-one/src/server/controllers/vote.controller.ts b/apps/lfx-one/src/server/controllers/vote.controller.ts
@@ -1,10 +1,11 @@
 // Copyright The Linux Foundation and each contributor to LFX.
 // SPDX-License-Identifier: MIT
 
-import { CreateVoteRequest, UpdateVoteRequest } from '@lfx-one/shared/interfaces';
+import { CreateVoteRequest, CreateVoteResponseRequest, UpdateVoteRequest } from '@lfx-one/shared/interfaces';
 import { NextFunction, Request, Response } from 'express';
 
-import { validateUidParameter } from '../helpers/validation.helper';
+import { ServiceValidationError } from '../errors';
+import { validateRequestBody, validateRequiredParameter, validateUidParameter } from '../helpers/validation.helper';
 import { logger } from '../services/logger.service';
 import { VoteService } from '../services/vote.service';
 
@@ -235,6 +236,90 @@ export class VoteController {
     }
   }
 
+  /**
+   * POST /votes/responses
+   */
+  public async createVoteResponse(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const payload: CreateVoteResponseRequest = req.body;
+    const startTime = logger.startOperation(req, 'create_vote_response', {
+      vote_uid: payload?.vote_uid,
+      vote_response_uid: payload?.vote_response_uid,
+      abstain: payload?.abstain,
+    });
+
+    try {
+      const validationContext = { operation: 'create_vote_response', service: 'vote_controller' } as const;
+
+      if (!validateRequestBody(payload, req, next, validationContext)) {
+        return;
+      }
+
+      if (!validateRequiredParameter(payload.vote_uid, 'vote_uid', req, next, validationContext)) {
+        return;
+      }
+
+      if (!validateRequiredParameter(payload.vote_response_uid, 'vote_response_uid', req, next, validationContext)) {
+        return;
+      }
+
+      if (typeof payload.abstain !== 'boolean') {
+        throw ServiceValidationError.forField('abstain', 'abstain is required and must be a boolean', validationContext);
+      }
+
+      // Build the upstream payload immutably: when abstaining we drop user_vote_content entirely;
+      // when not abstaining we validate each answer and forward the original content.
+      let upstreamPayload: CreateVoteResponseRequest;
+
+      if (payload.abstain) {
+        upstreamPayload = {
+          vote_uid: payload.vote_uid,
+          vote_response_uid: payload.vote_response_uid,
+          abstain: true,
+        };
+      } else {
+        if (!Array.isArray(payload.user_vote_content) || payload.user_vote_content.length === 0) {
+          throw ServiceValidationError.forField('user_vote_content', 'user_vote_content is required when not abstaining', validationContext);
+        }
+
+        for (const [index, answer] of payload.user_vote_content.entries()) {
+          if (!answer || typeof answer !== 'object') {
+            throw ServiceValidationError.forField(`user_vote_content[${index}]`, 'Each answer must be a non-null object', validationContext);
+          }
+
+          if (!answer.question_id || typeof answer.question_id !== 'string') {
+            throw ServiceValidationError.forField(`user_vote_content[${index}].question_id`, 'question_id is required for each answer', validationContext);
+          }
+
+          const hasChoiceIds = Array.isArray(answer.choice_ids) && answer.choice_ids.length > 0;
+          const hasRankedChoices = Array.isArray(answer.ranked_choices) && answer.ranked_choices.length > 0;
+
+          if (!hasChoiceIds && !hasRankedChoices) {
+            throw ServiceValidationError.forField(
+              `user_vote_content[${index}]`,
+              'Each answer must include either choice_ids or ranked_choices',
+              validationContext
+            );
+          }
+        }
+
+        upstreamPayload = payload;
+      }
+
+      await this.voteService.createVoteResponse(req, upstreamPayload);
+
+      logger.success(req, 'create_vote_response', startTime, {
+        vote_uid: upstreamPayload.vote_uid,
+        vote_response_uid: upstreamPayload.vote_response_uid,
+        abstain: upstreamPayload.abstain,
+        status_code: 204,
+      });
+
+      res.status(204).send();
+    } catch (error) {
+      next(error);
+    }
+  }
+
   /**
    * PUT /votes/:uid/enable
    */
diff --git a/apps/lfx-one/src/server/helpers/validation.helper.ts b/apps/lfx-one/src/server/helpers/validation.helper.ts
@@ -24,15 +24,11 @@ interface ValidationOptions {
 }
 
 /**
- * Validates that a UID parameter exists and is not empty
- * @param uid The UID value to validate
- * @param req Express request object
- * @param next Express next function for error handling
- * @param options Validation options including operation name
- * @returns true if validation passes, false if validation fails (error sent to next)
+ * Validates that a UID route parameter exists and is not empty.
+ * For validating named body/query fields, use validateRequiredParameter instead.
  */
-export function validateUidParameter(uid: string | undefined, req: Request, next: NextFunction, options: ValidationOptions): uid is string {
-  if (!uid || uid.trim() === '') {
+export function validateUidParameter(uid: unknown, req: Request, next: NextFunction, options: ValidationOptions): uid is string {
+  if (typeof uid !== 'string' || uid.trim() === '') {
     const validationError = ServiceValidationError.forField('uid', 'UID is required', {
       operation: options.operation,
       service: options.service || 'controller',
diff --git a/apps/lfx-one/src/server/routes/votes.route.ts b/apps/lfx-one/src/server/routes/votes.route.ts
@@ -18,6 +18,11 @@ router.get('/count', (req, res, next) => voteController.getVotesCount(req, res,
 // GET /votes/my-votes - get votes the current user has been invited to
 router.get('/my-votes', (req, res, next) => voteController.getMyVotes(req, res, next));
 
+// POST /votes/responses - submit a vote response (ballot)
+// Note: literal-segment routes must precede '/:uid' handlers so Express
+// doesn't accidentally match 'responses' as a uid for any future POST /:uid/* route.
+router.post('/responses', (req, res, next) => voteController.createVoteResponse(req, res, next));
+
 // GET /votes/:uid/results - get vote results
 router.get('/:uid/results', (req, res, next) => voteController.getVoteResults(req, res, next));
 
diff --git a/apps/lfx-one/src/server/services/user.service.ts b/apps/lfx-one/src/server/services/user.service.ts
@@ -14,6 +14,7 @@ import {
   ActiveWeeksStreakResponse,
   ActiveWeeksStreakRow,
   ApiGatewayUserProfile,
+  IndexedVoteResponse,
   Meeting,
   MeetingOccurrence,
   MeetingRegistrant,
@@ -1088,21 +1089,12 @@ export class UserService {
    * `end_time`, and `status` — everything the `transformVotesToActions` consumer needs.
    */
   private async fetchPendingVotes(req: Request, projectUid?: string): Promise<Vote[]> {
-    interface VoteResponseRow {
-      vote_uid?: string;
-      vote_id?: string;
-      poll_id?: string;
-      project_uid?: string;
-      vote_status?: string;
-      voter_removed?: boolean;
-    }
-
     // failOnPartial: completeness matters — a truncated response can silently miss a pending
     // invitation. The caller already catches and degrades, so fail closed here.
-    const responses = await fetchAllQueryResources<VoteResponseRow>(
+    const responses = await fetchAllQueryResources<IndexedVoteResponse>(
       req,
       (pageToken) =>
-        this.microserviceProxy.proxyRequest<QueryServiceResponse<VoteResponseRow>>(req, 'LFX_V2_SERVICE', '/query/resources', 'GET', {
+        this.microserviceProxy.proxyRequest<QueryServiceResponse<IndexedVoteResponse>>(req, 'LFX_V2_SERVICE', '/query/resources', 'GET', {
           type: 'vote_response',
           filter_grants: 'direct',
           ...(projectUid && { filters: [`project_uid:${projectUid}`] }),
@@ -1111,13 +1103,13 @@ export class UserService {
       { failOnPartial: true }
     );
 
-    // `vote_uid` is the v2 parent poll UID (what `/votes/{uid}` expects); `poll_id` is the v1
-    // fallback per the upstream indexer contract. Neither is the individual-response id.
+    // `vote_uid` is the v2 parent poll UID (what `/votes/{uid}` expects); `vote_id` and `poll_id`
+    // are v1 fallbacks per the upstream indexer contract. None of these is the individual-response id.
     const pendingVoteUids = Array.from(
       new Set(
         responses
           .filter((r) => r.vote_status !== 'submitted' && !r.voter_removed)
-          .map((r) => r.vote_uid ?? r.poll_id)
+          .map((r) => r.vote_uid ?? r.vote_id ?? r.poll_id)
           .filter((uid): uid is string => !!uid)
       )
     );
diff --git a/apps/lfx-one/src/server/services/vote.service.ts b/apps/lfx-one/src/server/services/vote.service.ts
@@ -3,7 +3,9 @@
 
 import {
   CreateVoteRequest,
+  CreateVoteResponseRequest,
   IndexedVote,
+  IndexedVoteResponse,
   QueryServiceCountResponse,
   QueryServiceResponse,
   UpdateVoteRequest,
@@ -246,6 +248,57 @@ export class VoteService {
     return results;
   }
 
+  /**
+   * Submits a ballot via POST /vote_responses using the user's bearer token (no M2M),
+   * then polls until the query service indexes the response as 'submitted'.
+   */
+  public async createVoteResponse(req: Request, payload: CreateVoteResponseRequest): Promise<void> {
+    logger.debug(req, 'create_vote_response', 'Submitting vote response', {
+      vote_uid: payload.vote_uid,
+      vote_response_uid: payload.vote_response_uid,
+      abstain: payload.abstain,
+      answer_count: payload.user_vote_content?.length ?? 0,
+    });
+
+    await this.microserviceProxy.proxyRequest<void>(req, 'LFX_V2_SERVICE', '/vote_responses', 'POST', undefined, payload, {
+      ['X-Sync']: 'true',
+    });
+
+    logger.debug(req, 'create_vote_response', 'Ballot accepted by upstream voting service, polling query service', {
+      vote_uid: payload.vote_uid,
+      vote_response_uid: payload.vote_response_uid,
+    });
+
+    const resolved = await pollEndpoint({
+      req,
+      operation: 'create_vote_response_poll',
+      pollFn: async () => {
+        const { resources } = await this.microserviceProxy.proxyRequest<QueryServiceResponse<IndexedVoteResponse>>(
+          req,
+          'LFX_V2_SERVICE',
+          '/query/resources',
+          'GET',
+          {
+            type: 'vote_response',
+            filter_grants: 'direct',
+            filters: [`vote_uid:${payload.vote_uid}`],
+          }
+        );
+        return resources.some((r) => r.data.uid === payload.vote_response_uid && r.data.vote_status === 'submitted');
+      },
+      maxRetries: 5,
+      retryDelayMs: 1000,
+      metadata: { vote_uid: payload.vote_uid, vote_response_uid: payload.vote_response_uid },
+    });
+
+    if (!resolved) {
+      logger.warning(req, 'create_vote_response', 'Vote response not yet indexed, client may see stale state', {
+        vote_uid: payload.vote_uid,
+        vote_response_uid: payload.vote_response_uid,
+      });
+    }
+  }
+
   // ============================================
   // My Votes (Me Lens)
   // ============================================
diff --git a/packages/shared/src/interfaces/poll.interface.ts b/packages/shared/src/interfaces/poll.interface.ts
@@ -227,6 +227,29 @@ export interface IndexedVote extends Omit<Vote, 'uid'> {
   uid?: string;
 }
 
+/**
+ * Vote response row from the query service indexer (`lfx.index.vote_response`).
+ * Tagged by `vote_uid` (not `vote_response_uid`); use `filter_grants=direct` to
+ * scope to the current user's rows. `vote_status` is `string` — the indexer's
+ * vocabulary is broader than the UI enums.
+ */
+export interface IndexedVoteResponse {
+  /** Vote response (ballot) identifier — the row's own primary key */
+  uid?: string;
+  /** Parent poll identifier (v2). Indexer tag key. */
+  vote_uid?: string;
+  /** V1 fallback for the parent poll identifier */
+  vote_id?: string;
+  /** V1 alias for `vote_id` carried by older indexer versions */
+  poll_id?: string;
+  /** V2 project UID the response belongs to */
+  project_uid?: string;
+  /** Upstream submission status (e.g. `'submitted'`, `'awaiting_response'`) */
+  vote_status?: string;
+  /** Whether the voter has been removed from the poll's eligible list */
+  voter_removed?: boolean;
+}
+
 /**
  * Individual Vote entity from query service
  * @description Represents a user's participation record from lfx.index.individual_vote
@@ -563,6 +586,48 @@ export interface CreateVoteRequest {
   winning_threshold_percentage?: number;
 }
 
+/**
+ * Ranked choice submission for a single choice in a ranked-choice question
+ * @description Aligns with upstream RankedChoiceInput
+ * @see https://github.com/linuxfoundation/lfx-v2-voting-service
+ */
+export interface RankedChoiceInput {
+  /** Choice identifier (UUID) */
+  choice_id: string;
+  /** 1-based rank assigned to the choice */
+  choice_rank: number;
+}
+
+/**
+ * Voter's answer to a single question on a ballot submission
+ * @description Aligns with upstream VoteAnswerInput
+ * @see https://github.com/linuxfoundation/lfx-v2-voting-service
+ */
+export interface VoteAnswerInput {
+  /** Question identifier (UUID) */
+  question_id: string;
+  /** Selected choice IDs for generic / single-choice / multi-choice questions */
+  choice_ids?: string[];
+  /** Ranked choices for ranked-choice voting questions */
+  ranked_choices?: RankedChoiceInput[];
+}
+
+/**
+ * Request body for submitting a vote response (ballot)
+ * @description Aligns with upstream POST /vote_responses
+ * @see https://github.com/linuxfoundation/lfx-v2-voting-service
+ */
+export interface CreateVoteResponseRequest {
+  /** Client-generated vote response identifier (UUID) */
+  vote_response_uid: string;
+  /** Vote/poll identifier this response belongs to (UUID) */
+  vote_uid: string;
+  /** Whether the voter is abstaining */
+  abstain: boolean;
+  /** Voter's answers — required when not abstaining */
+  user_vote_content?: VoteAnswerInput[];
+}
+
 /**
  * Request body for updating a vote/poll
  * @description Only permitted when vote status is "disabled"
