fix(upload): an idempotent retry returns the same verified receipt
CI (SIAX Cloud) / sonar (pull_request) Skipped
masterplan-lock / check (push) Successful in 4s
masterplan-lock / check (pull_request) Successful in 5s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 16s
CI (SIAX Cloud) / security (pull_request) Successful in 35s
CI (SIAX Cloud) / integration (pull_request) Successful in 37s
CI (SIAX Cloud) / quality (pull_request) Successful in 43s

A client retry with the same idempotency key replayed the journal and got
'outcome_unknown' even when the first upload had succeeded, because the
verified DOC0 receipt was never persisted. Store document/version/checksum/
stage on the attempt (sql/021) and return it on replay; only a missing receipt
falls back to observation. No second POST, no duplicate document.
This commit is contained in:
2026-11-03 00:35:32 +01:00
parent 96d61d1308
commit 92eb78ba0a
4 changed files with 234 additions and 46 deletions
+85 -8
View File
@@ -13,6 +13,12 @@ export interface UploadAttemptIdentity {
requestFingerprint: string;
}
export type UploadAttemptState = 'prepared' | 'dispatch_started';
export interface StoredUploadReceipt {
documentId: string;
versionId: string;
checksumSha256: string;
pipelineStage: string;
}
interface Row {
source_sha256: string;
source_size_bytes: string;
@@ -21,10 +27,15 @@ interface Row {
}
function validate(input: UploadAttemptIdentity): void {
if (![input.tenantId, input.projectId, input.actorId, input.attemptId].every(
(value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 256,
) || !/^[0-9a-f]{64}$/.test(input.sourceSha256) || !/^[0-9a-f]{64}$/.test(input.requestFingerprint)
|| !Number.isSafeInteger(input.sourceSizeBytes) || input.sourceSizeBytes <= 0) {
if (
![input.tenantId, input.projectId, input.actorId, input.attemptId].every(
(value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 256,
) ||
!/^[0-9a-f]{64}$/.test(input.sourceSha256) ||
!/^[0-9a-f]{64}$/.test(input.requestFingerprint) ||
!Number.isSafeInteger(input.sourceSizeBytes) ||
input.sourceSizeBytes <= 0
) {
throw new Error('Invalid document upload attempt');
}
}
@@ -40,12 +51,16 @@ function validate(input: UploadAttemptIdentity): void {
export class PostgresUploadAttemptStore {
constructor(private readonly sql: RepositorySql) {}
private async scoped<T>(input: UploadAttemptIdentity, action: (tx: postgres.TransactionSql) => Promise<T>): Promise<T> {
private async scoped<T>(
input: UploadAttemptIdentity,
action: (tx: postgres.TransactionSql) => Promise<T>,
): Promise<T> {
validate(input);
return this.sql.begin(async (tx) => {
const roles = await tx<{ rolsuper: boolean; rolbypassrls: boolean }[]>`
SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`;
if (!roles[0] || roles[0].rolsuper || roles[0].rolbypassrls) throw new Error('Upload attempts require an RLS-enforced database role');
if (!roles[0] || roles[0].rolsuper || roles[0].rolbypassrls)
throw new Error('Upload attempts require an RLS-enforced database role');
await tx`SELECT set_config('app.opt_tenant_id', ${input.tenantId}, true), set_config('app.opt_project_id', ${input.projectId}, true), set_config('app.opt_actor_id', ${input.actorId}, true)`;
return action(tx);
}) as Promise<T>;
@@ -57,11 +72,18 @@ export class PostgresUploadAttemptStore {
INSERT INTO opt_document_upload_attempts (tenant_id,project_id,actor_id,attempt_id,source_sha256,source_size_bytes,request_fingerprint,state)
VALUES (${input.tenantId},${input.projectId},${input.actorId},${input.attemptId},${input.sourceSha256},${input.sourceSizeBytes},${input.requestFingerprint},'prepared')
ON CONFLICT (tenant_id,attempt_id) DO NOTHING RETURNING source_sha256,source_size_bytes,request_fingerprint,state`;
const rows = inserted.length ? inserted : await tx<Row[]>`
const rows = inserted.length
? inserted
: await tx<Row[]>`
SELECT source_sha256,source_size_bytes,request_fingerprint,state FROM opt_document_upload_attempts
WHERE tenant_id=${input.tenantId} AND project_id=${input.projectId} AND actor_id=${input.actorId} AND attempt_id=${input.attemptId}`;
const row = rows[0];
if (!row || row.source_sha256 !== input.sourceSha256 || row.source_size_bytes !== String(input.sourceSizeBytes) || row.request_fingerprint !== input.requestFingerprint) {
if (
!row ||
row.source_sha256 !== input.sourceSha256 ||
row.source_size_bytes !== String(input.sourceSizeBytes) ||
row.request_fingerprint !== input.requestFingerprint
) {
throw new Error('Document upload attempt cannot be reused');
}
return { state: row.state, replay: inserted.length === 0 };
@@ -80,4 +102,59 @@ export class PostgresUploadAttemptStore {
return rows.length === 1;
});
}
/**
* Persist the verified DOC0 receipt so a retry with the same idempotency key
* returns the SAME 201 receipt instead of "outcome unknown". Only the fields
* DOC0 itself returned are stored; storage/extraction are not re-proven here.
*/
async recordReceipt(input: UploadAttemptIdentity, receipt: StoredUploadReceipt): Promise<void> {
if (
![receipt.documentId, receipt.versionId, receipt.pipelineStage].every(
(value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 256,
) ||
!/^[0-9a-f]{64}$/.test(receipt.checksumSha256)
) {
throw new Error('Invalid upload receipt');
}
await this.scoped(input, async (tx) => {
const rows = await tx<{ attempt_id: string }[]>`
UPDATE opt_document_upload_attempts
SET document_id=${receipt.documentId}, version_id=${receipt.versionId},
receipt_checksum=${receipt.checksumSha256}, pipeline_stage=${receipt.pipelineStage},
verified_at=clock_timestamp(), updated_at=clock_timestamp()
WHERE tenant_id=${input.tenantId} AND project_id=${input.projectId} AND actor_id=${input.actorId}
AND attempt_id=${input.attemptId} AND source_sha256=${input.sourceSha256}
AND source_size_bytes=${input.sourceSizeBytes} AND request_fingerprint=${input.requestFingerprint}
RETURNING attempt_id`;
if (rows.length !== 1) throw new Error('Upload attempt receipt could not be recorded');
});
}
async getReceipt(input: UploadAttemptIdentity): Promise<StoredUploadReceipt | undefined> {
return this.scoped(input, async (tx) => {
const rows = await tx<
{
document_id: string | null;
version_id: string | null;
receipt_checksum: string | null;
pipeline_stage: string | null;
}[]
>`
SELECT document_id, version_id, receipt_checksum, pipeline_stage
FROM opt_document_upload_attempts
WHERE tenant_id=${input.tenantId} AND project_id=${input.projectId} AND actor_id=${input.actorId}
AND attempt_id=${input.attemptId} AND source_sha256=${input.sourceSha256}
AND source_size_bytes=${input.sourceSizeBytes} AND request_fingerprint=${input.requestFingerprint}`;
const row = rows[0];
if (!row?.document_id || !row.version_id || !row.receipt_checksum || !row.pipeline_stage)
return undefined;
return {
documentId: row.document_id,
versionId: row.version_id,
checksumSha256: row.receipt_checksum,
pipelineStage: row.pipeline_stage,
};
});
}
}
+40 -12
View File
@@ -6,12 +6,15 @@ import {
type Doc0UploadInput,
type Doc0UploadReceipt,
} from './doc0-upload-client';
import type { UploadAttemptIdentity, UploadAttemptState } from './upload-attempt-store';
import type { StoredUploadReceipt, UploadAttemptIdentity, UploadAttemptState } from './upload-attempt-store';
type Scope = Pick<Doc0UploadInput, 'tenantId' | 'projectId' | 'actorId'>;
type Attempts = {
prepare(input: UploadAttemptIdentity): Promise<{ state: UploadAttemptState; replay: boolean }>;
startDispatch(input: UploadAttemptIdentity): Promise<boolean>;
/** Optional so lightweight tests/implementations keep working. */
recordReceipt?(input: UploadAttemptIdentity, receipt: StoredUploadReceipt): Promise<void>;
getReceipt?(input: UploadAttemptIdentity): Promise<StoredUploadReceipt | undefined>;
};
type Doc0 = {
upload(input: Doc0UploadInput): Promise<Doc0UploadReceipt>;
@@ -28,12 +31,14 @@ export type CoordinatedUpload =
* be deployed and verified before this coordinator can serve customer data.
*/
export class DocumentUploadCoordinator {
constructor(private readonly deps: {
attempts: Attempts;
doc0: Doc0;
authorize: (scope: Scope) => Promise<boolean>;
maxBytes: number;
}) {
constructor(
private readonly deps: {
attempts: Attempts;
doc0: Doc0;
authorize: (scope: Scope) => Promise<boolean>;
maxBytes: number;
},
) {
if (!Number.isSafeInteger(deps.maxBytes) || deps.maxBytes <= 0) throw new Error('Invalid upload limit');
}
@@ -48,27 +53,50 @@ export class DocumentUploadCoordinator {
const scope = { tenantId: snapshot.tenantId, projectId: snapshot.projectId, actorId: snapshot.actorId };
if ((await this.deps.authorize(scope)) !== true) throw new Error('Document upload not authorized');
const attempt: UploadAttemptIdentity = {
...scope, attemptId: snapshot.idempotencyKey, sourceSha256: details.sourceSha256,
sourceSizeBytes: details.sourceSizeBytes, requestFingerprint: details.requestFingerprint,
...scope,
attemptId: snapshot.idempotencyKey,
sourceSha256: details.sourceSha256,
sourceSizeBytes: details.sourceSizeBytes,
requestFingerprint: details.requestFingerprint,
};
await this.deps.attempts.prepare(attempt);
// A database error here also stops the operation: the update might have
// committed and must never be followed by an unrecorded network write.
if ((await this.deps.attempts.startDispatch(attempt)) === true) {
try {
return { status: 'receipt_verified', receipt: await this.deps.doc0.upload(snapshot) };
const receipt = await this.deps.doc0.upload(snapshot);
// Persist the verified receipt so retrying with the same idempotency
// key returns this exact 201 instead of "outcome unknown". A journal
// write failure must not turn a real upload into an error response.
try {
await this.deps.attempts.recordReceipt?.(attempt, receipt);
} catch {
/* receipt stays unpersisted; a retry falls back to observation */
}
return { status: 'receipt_verified', receipt };
} catch (error) {
// The client marks every potentially committed POST as unknown. Any
// other error propagates, while the one-way dispatch remains recorded.
if (!(error instanceof Doc0UploadOutcomeUnknownError)) throw error;
}
}
// A retry of an already-dispatched attempt: if the first dispatch returned
// a verified receipt, return it again (same document, same checksum).
try {
const stored = await this.deps.attempts.getReceipt?.(attempt);
if (stored) return { status: 'receipt_verified', receipt: stored };
} catch {
/* fall through to observation */
}
// Observation only. Even not_found does not prove that a write cannot
// still arrive; completed_recorded does not prove storage or extraction.
try {
const observation = await this.deps.doc0.inspect({
...scope, requestId: snapshot.requestId, idempotencyKey: snapshot.idempotencyKey,
sourceSha256: details.sourceSha256, sourceSizeBytes: details.sourceSizeBytes,
...scope,
requestId: snapshot.requestId,
idempotencyKey: snapshot.idempotencyKey,
sourceSha256: details.sourceSha256,
sourceSizeBytes: details.sourceSizeBytes,
requestFingerprint: details.requestFingerprint,
});
return { status: 'outcome_unknown', observation };