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
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:
@@ -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,
|
||||
};
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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 };
|
||||
|
||||
Reference in New Issue
Block a user