feat: coordinate journaled document upload attempts
CI (SIAX Cloud) / integration (push) Skipped
CI (SIAX Cloud) / sonar (push) Skipped
masterplan-lock / check (push) Successful in 4s
CI (SIAX Cloud) / security (push) Successful in 17s
Security Scan (SIAX Cloud) / security (push) Successful in 18s
CI (SIAX Cloud) / sonar (pull_request) Skipped
masterplan-lock / check (pull_request) Successful in 4s
CI (SIAX Cloud) / security (pull_request) Successful in 15s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 17s
CI (SIAX Cloud) / quality (push) Successful in 50s
CI (SIAX Cloud) / integration (pull_request) Successful in 33s
CI (SIAX Cloud) / quality (pull_request) Successful in 39s

This commit is contained in:
2026-11-02 07:17:32 +01:00
parent 347b81ceb4
commit ce41d601f7
3 changed files with 163 additions and 1 deletions
@@ -0,0 +1,79 @@
import {
Doc0UploadOutcomeUnknownError,
prepareDoc0UploadIdentity,
type Doc0Inspection,
type Doc0InspectionInput,
type Doc0UploadInput,
type Doc0UploadReceipt,
} from './doc0-upload-client';
import type { 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>;
};
type Doc0 = {
upload(input: Doc0UploadInput): Promise<Doc0UploadReceipt>;
inspect(input: Doc0InspectionInput): Promise<Doc0Inspection>;
};
export type CoordinatedUpload =
| { status: 'receipt_verified'; receipt: Doc0UploadReceipt }
| { status: 'outcome_unknown'; observation?: Doc0Inspection };
/**
* Internal only: no customer routes are wired. Scope must be derived from an
* authenticated principal and independently authorized by the injected policy.
* The DOC0 journal, RLS database role, storage and project authorization must
* 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;
}) {
if (!Number.isSafeInteger(deps.maxBytes) || deps.maxBytes <= 0) throw new Error('Invalid upload limit');
}
async execute(input: Doc0UploadInput): Promise<CoordinatedUpload> {
if (!(input.bytes instanceof Uint8Array) || input.bytes.byteLength > this.deps.maxBytes) {
throw new Error('Invalid upload input');
}
// Snapshot both metadata and bytes before the first await: a caller cannot
// mutate the request between the durable fingerprint and the actual POST.
const snapshot: Doc0UploadInput = { ...input, bytes: new Uint8Array(input.bytes) };
const details = prepareDoc0UploadIdentity(snapshot);
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,
};
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) };
} 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;
}
}
// 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,
requestFingerprint: details.requestFingerprint,
});
return { status: 'outcome_unknown', observation };
} catch {
return { status: 'outcome_unknown' };
}
}
}