Skip to content

Commit 2d0bb75

Browse files
committed
wip: attachUploadAs commits a member's own pending upload and attaches it as them
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibvynRbCtMndW8EHNGc
1 parent b905481 commit 2d0bb75

5 files changed

Lines changed: 210 additions & 19 deletions

File tree

‎content/docs/references/api/storage.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,14 @@ const result = CompleteChunkedUploadRequestSchema.parse(data);
103103
| :--- | :--- | :--- | :--- |
104104
| **fileId** | `string` | ✅ | File ID returned from presigned request |
105105
| **eTag** | `string` | optional | ETag the client reports for the uploaded object. Stored on the file record as sent and not compared with anything: no storage adapter reports a stored object's ETag. Before committing, the door checks that the storage backend holds bytes under the file's key and, when the upload declared a size, that the held size equals it. |
106+
| **attachTo** | `{ parentObject: string; parentId: string }` | optional | Attach the uploaded file to this record in the same call, as the signed-in caller: the commit and the attachment row are one unit, and the answer carries the new attachmentId. Only the uploader's own pending upload in the attachments scope can be attached this way. The attachment is judged as the caller's own create: the permission to create an attachment, edit access to the record, and the record object's enable.files opt-in. A refused attach leaves the upload pending and uncommitted. |
107+
108+
### Nested Shape: `CompleteUploadRequest.attachTo`
109+
110+
| Property | Type | Required | Description |
111+
| :--- | :--- | :--- | :--- |
112+
| **parentObject** | `string` | ✅ | Object of the record the file is attached to (enable.files: true) |
113+
| **parentId** | `string` | ✅ | Id of the record the file is attached to |
106114

107115

108116
---
@@ -211,6 +219,7 @@ const result = CompleteChunkedUploadRequestSchema.parse(data);
211219
| **created** | `string` | ✅ | Creation timestamp |
212220
| **etag** | `string` | optional | Entity tag |
213221
| **fileId** | `string` | optional | Opaque sys_file id (ADR-0104 D3 file-as-reference) |
222+
| **attachmentId** | `string` | optional | Id of the sys_attachment row the commit created, when the request carried attachTo |
214223

215224

216225
---

‎docs/audits/2026-07-unknown-key-strictness-ledger.counts/api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ hand-patch a number here** — fix the code or the verdict and regenerate.
1919

2020
| Dir | Sites |
2121
|---|---|
22-
| `api/` | 500 |
22+
| `api/` | 501 |

‎packages/services/service-storage/src/file-attachment-service.ts‎

Lines changed: 194 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ import type { ExecutionContext } from '@objectstack/spec/kernel';
1515
// The one reference this verb's caller-scoped insert vouches for: the file it
1616
// created in the same call (see step ⑤).
1717
import { vouchForReference } from '@objectstack/core';
18-
import { StorageMetadataStore, type StorageWriteContext } from './metadata-store.js';
18+
import { StorageMetadataStore, organizationOutOfWriteReach, type StorageWriteContext } from './metadata-store.js';
19+
// The upload ownership rule, asked of the upload the attach-on-commit verb
20+
// names — the commit door's own rule and its one refusal.
21+
import { isFileUploader, NOT_UPLOADER_CODE, NOT_UPLOADER_MESSAGE, NOT_UPLOADER_STATUS } from './upload-ownership.js';
1922
// The attach rule's one verdict (parent EDIT), asked here before a producer
2023
// spends work on a file it could not attach.
2124
import {
@@ -35,8 +38,9 @@ import {
3538
UPLOAD_TOO_LARGE_STATUS,
3639
type StorageLimitsSnapshot,
3740
} from './storage-limits.js';
38-
// The upload doors' own storage-key layout.
39-
import { buildKey } from './storage-routes.js';
41+
// The upload doors' own storage-key layout, and the commit door's question
42+
// of whether the backend holds an upload's bytes.
43+
import { buildKey, heldBytesRefusal } from './storage-routes.js';
4044

4145
/**
4246
* [#23306] The server-side attach verb — `IFileAttachmentService`, registered
@@ -157,6 +161,42 @@ export interface ICallerFileAttachmentService {
157161
* `403`: the system has `attachFile`.
158162
*/
159163
attachFileAs(input: AttachFileInput, context: ExecutionContext): Promise<AttachedFile>;
164+
/**
165+
* Attach the caller's own browser upload to a record, and commit it, in one
166+
* unit, as `context`'s user: the attach verb of the record attachments
167+
* surface, asked by the upload-complete door when its request carries
168+
* `attachTo` (`POST /api/v1/storage/upload/complete`).
169+
*
170+
* The file must be the upload the caller is completing: a `sys_file` row
171+
* whose `owner_id` is the caller (the upload doors stamp it from the
172+
* session), still `pending`, in the `attachments` scope, in the caller's
173+
* organization, with its bytes held by the storage backend. Any other id —
174+
* another user's upload, an id that names no file — is refused with the
175+
* upload ownership rule's one answer (`PERMISSION_DENIED` / `403`, the same
176+
* body for both); a committed file `RESOURCE_CONFLICT` / `409`; another
177+
* scope `INVALID_REQUEST` / `400`.
178+
*
179+
* Then the attach authorization, before any write: {@link assertMayAttach}
180+
* (the permission to create an attachment, and the parent-EDIT attach rule),
181+
* and the parent read as the caller (`RECORD_NOT_FOUND` / `404`, as
182+
* {@link attachFileAs} answers). The `sys_attachment` insert runs as the
183+
* caller, so every gate on it judges the caller, and it vouches for this
184+
* one file id and for nothing else (`vouchForReference`, `@objectstack/core`).
185+
* A refusal leaves the upload `pending`, its bytes stored, and no attachment.
186+
*/
187+
attachUploadAs(input: AttachUploadInput, context: ExecutionContext): Promise<AttachedFile>;
188+
}
189+
190+
/** What {@link ICallerFileAttachmentService.attachUploadAs} attaches: an upload, and the record it is attached to. */
191+
export interface AttachUploadInput {
192+
/** The `sys_file` id the upload-start door returned to the caller. */
193+
fileId: string;
194+
/** The object of the record the file is attached to. */
195+
parentObject: string;
196+
/** The id of the record the file is attached to. */
197+
parentId: string;
198+
/** The ETag the client reports for the uploaded bytes, stored on the file as the commit door stores it. */
199+
eTag?: string;
160200
}
161201

162202
/** The upload scope of every file this verb writes: the attachments surface. */
@@ -213,6 +253,17 @@ function validateAttachFileInput(input: AttachFileInput): AttachFileInput {
213253
return input;
214254
}
215255

256+
/** {@link validateAttachFileInput}'s counterpart for {@link AttachUploadInput}. */
257+
function validateAttachUploadInput(input: AttachUploadInput): AttachUploadInput {
258+
const fail = (message: string): never => refuse('VALIDATION_ERROR', 400, `attachUploadAs: ${message}`);
259+
if (!input || typeof input !== 'object') fail('the input must be an object');
260+
for (const field of ['fileId', 'parentObject', 'parentId'] as const) {
261+
if (!nonEmptyString(input[field])) fail(`'${field}' must be a non-empty string`);
262+
}
263+
if (input.eTag !== undefined && typeof input.eTag !== 'string') fail("'eTag' must be a string when it is given");
264+
return input;
265+
}
266+
216267
export class FileAttachmentService implements IFileAttachmentService, ICallerFileAttachmentService {
217268
constructor(private readonly deps: FileAttachmentServiceDeps) {}
218269

@@ -224,6 +275,119 @@ export class FileAttachmentService implements IFileAttachmentService, ICallerFil
224275
return this.attach(input, requireUserContext(context));
225276
}
226277

278+
async attachUploadAs(input: AttachUploadInput, context: ExecutionContext): Promise<AttachedFile> {
279+
const caller = requireUserContext(context);
280+
const request = validateAttachUploadInput(input);
281+
const engine = this.deps.getEngine();
282+
const storage = this.deps.getStorage();
283+
if (!engine || !storage) refuse('SERVICE_UNAVAILABLE', 503, NOT_READY_MESSAGE);
284+
const store = new StorageMetadataStore(engine);
285+
286+
// ① The upload — the caller's own, as the store stamped it. Read as the
287+
// system, by id, as the commit door reads it; nothing about the row is
288+
// answered before the ownership rule has passed, and a missing row gets
289+
// the same answer as another user's.
290+
const file = await store.getFile(request.fileId);
291+
if (!file || !isFileUploader(caller.userId, file)) {
292+
refuse(NOT_UPLOADER_CODE, NOT_UPLOADER_STATUS, NOT_UPLOADER_MESSAGE);
293+
}
294+
if (file.status !== 'pending') {
295+
refuse(
296+
'RESOURCE_CONFLICT',
297+
409,
298+
'This upload is already completed, so it cannot be attached on completion. An upload is attached in the ' +
299+
'call that completes it: start a new upload and complete it with attachTo.',
300+
);
301+
}
302+
if (file.scope !== ATTACHMENTS_SCOPE) {
303+
refuse(
304+
'INVALID_REQUEST',
305+
400,
306+
`This upload was started in the '${String(file.scope ?? 'user')}' scope, and only an upload in the ` +
307+
`'${ATTACHMENTS_SCOPE}' scope is attached to a record. Start the upload with scope '${ATTACHMENTS_SCOPE}'.`,
308+
);
309+
}
310+
const callerOrganization = nonEmptyString(caller.tenantId) ? caller.tenantId : null;
311+
if (organizationOutOfWriteReach(store, file, { organizationId: callerOrganization }) !== null) {
312+
refuse(
313+
'PERMISSION_DENIED',
314+
403,
315+
'attachUploadAs: this upload was started in another organization than the one the caller acts in; ' +
316+
'switch back to that organization to attach it.',
317+
);
318+
}
319+
const notHeld = await heldBytesRefusal(storage, file);
320+
if (notHeld !== null) refuse('RESOURCE_CONFLICT', 409, notHeld);
321+
322+
// ② The attach authorization, before any write: the permission to create
323+
// an attachment and the attach rule (parent EDIT), then the parent read as
324+
// the caller and the organization the attachment is written in.
325+
await this.assertMayAttach(request.parentObject, request.parentId, caller);
326+
const organizationId = await this.organizationOfParent(
327+
engine,
328+
{ parentObject: request.parentObject, parentId: request.parentId, organizationId: callerOrganization },
329+
caller,
330+
);
331+
const fileOrganization = nonEmptyString(file.organization_id) ? file.organization_id : null;
332+
if (fileOrganization !== null && fileOrganization !== organizationId) {
333+
refuse(
334+
'RECORD_NOT_FOUND',
335+
404,
336+
`Cannot attach a file to ${request.parentObject}/${request.parentId}: the record does not exist in the ` +
337+
'organization the upload was started in.',
338+
);
339+
}
340+
const writeContext: StorageWriteContext = { organizationId };
341+
342+
// ③ The attachment and the commit — one unit, as the caller.
343+
let attachmentId: string | undefined;
344+
let ownedUnit = false;
345+
try {
346+
await this.inOneUnit(engine, organizationId, caller, async (unitContext, owned) => {
347+
ownedUnit = owned;
348+
const row = (await engine.insert(
349+
'sys_attachment',
350+
{
351+
parent_object: request.parentObject,
352+
parent_id: request.parentId,
353+
file_id: file.id,
354+
file_name: file.name,
355+
mime_type: file.mime_type,
356+
size: file.size,
357+
},
358+
// As in `attachFileAs`: the call vouches for the one file it judged
359+
// in ① — the caller's own pending upload, which this call commits —
360+
// and for no other value. The write-time reference check does not
361+
// ask the caller's read door for that id, and still probes that it
362+
// exists; every other gate on the insert judges the caller.
363+
{ context: vouchForReference(unitContext, { object: 'sys_attachment', field: 'file_id', id: file.id }) },
364+
)) as { id?: unknown } | null | undefined;
365+
if (row?.id === undefined || row.id === null || row.id === '') {
366+
throw new Error('attachUploadAs: the sys_attachment insert answered no row id, so the attachment cannot be named');
367+
}
368+
attachmentId = String(row.id);
369+
const committed = await store.updateFile(
370+
file.id,
371+
{ status: 'committed', ...(request.eTag !== undefined ? { etag: request.eTag } : {}) },
372+
writeContext,
373+
);
374+
if (!committed) {
375+
throw new Error(`attachUploadAs: the sys_file row ${file.id} was gone before it could be committed`);
376+
}
377+
});
378+
} catch (err) {
379+
// An owned transaction rolled the attachment back with the commit. A
380+
// unit this call does not own keeps an inserted row, so it is removed
381+
// here. The upload itself is the caller's and stays as it was —
382+
// `pending`, its bytes stored — so completing again can still commit it.
383+
if (!ownedUnit && attachmentId !== undefined) {
384+
await this.removeAttachment(engine, attachmentId, file.id, writeContext);
385+
}
386+
throw err;
387+
}
388+
return { fileId: file.id, attachmentId: attachmentId!, size: Number(file.size ?? 0) };
389+
}
390+
227391
async assertMayAttach(parentObject: string, parentId: string, context: ExecutionContext): Promise<void> {
228392
const caller = requireUserContext(context);
229393
const engine = this.deps.getEngine();
@@ -393,7 +557,7 @@ export class FileAttachmentService implements IFileAttachmentService, ICallerFil
393557
*/
394558
private async organizationOfParent(
395559
engine: FileAttachmentEngine,
396-
request: AttachFileInput,
560+
request: Pick<AttachFileInput, 'parentObject' | 'parentId' | 'organizationId'>,
397561
caller: ExecutionContext | null,
398562
): Promise<string | null> {
399563
let parent: Record<string, unknown> | null;
@@ -453,6 +617,31 @@ export class FileAttachmentService implements IFileAttachmentService, ICallerFil
453617
await engine.transaction((trxCtx, info) => work(trxCtx as Record<string, unknown>, info?.owned === true), base);
454618
}
455619

620+
/**
621+
* Remove the `sys_attachment` row a refused call inserted outside a
622+
* transaction it owns. Best-effort: the call's refusal is what is thrown.
623+
*/
624+
private async removeAttachment(
625+
engine: FileAttachmentEngine,
626+
attachmentId: string,
627+
fileId: string,
628+
writeContext: StorageWriteContext,
629+
): Promise<void> {
630+
try {
631+
const tenant = writeContext.organizationId;
632+
await engine.delete('sys_attachment', {
633+
where: { id: attachmentId },
634+
context: tenant ? { isSystem: true, tenantId: tenant } : { isSystem: true },
635+
});
636+
} catch (err) {
637+
this.deps.logger.warn(
638+
`[storage] attachFile: a refused call could not remove its sys_attachment row ${attachmentId} ` +
639+
`(${(err as Error)?.message ?? err}). It points at the pending sys_file ${fileId}; delete the ` +
640+
'attachment row by hand.',
641+
);
642+
}
643+
}
644+
456645
/**
457646
* Undo a refused call: the attachment row it still holds (if any), then the
458647
* bytes, then the pending row. Best-effort, and the caller's refusal is what
@@ -468,19 +657,7 @@ export class FileAttachmentService implements IFileAttachmentService, ICallerFil
468657
): Promise<void> {
469658
const { logger } = this.deps;
470659
if (call.attachmentId !== undefined) {
471-
try {
472-
const tenant = call.writeContext.organizationId;
473-
await engine.delete('sys_attachment', {
474-
where: { id: call.attachmentId },
475-
context: tenant ? { isSystem: true, tenantId: tenant } : { isSystem: true },
476-
});
477-
} catch (err) {
478-
logger.warn(
479-
`[storage] attachFile: a refused call could not remove its sys_attachment row ${call.attachmentId} ` +
480-
`(${(err as Error)?.message ?? err}). It points at the pending sys_file ${call.fileId}; delete the ` +
481-
'attachment row by hand.',
482-
);
483-
}
660+
await this.removeAttachment(engine, call.attachmentId, call.fileId, call.writeContext);
484661
}
485662
try {
486663
await storage.delete(call.key);

‎packages/services/service-storage/src/storage-routes.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1972,8 +1972,12 @@ function judgeCompletion(session: UploadSessionRecord, listed: ReadonlyArray<Lis
19721972
*
19731973
* The eTag a completion may carry is not compared: no adapter's `getInfo`
19741974
* reports the stored object's ETag, so there is nothing to compare it with.
1975+
*
1976+
* Package-internal (not re-exported from `index.ts`): exported so the attach
1977+
* verb's commit of an upload (`FileAttachmentService.attachUploadAs`) asks the
1978+
* same question before it commits.
19751979
*/
1976-
async function heldBytesRefusal(storage: IStorageService, file: FileRecord): Promise<string | null> {
1980+
export async function heldBytesRefusal(storage: IStorageService, file: FileRecord): Promise<string | null> {
19771981
const remedy =
19781982
'Send the file to its upload URL (start a new upload if that URL has expired), then complete again. ' +
19791983
'The file stays pending until then.';

‎packages/spec/authorable-surface/api.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,7 @@
351351
"api/CompleteChunkedUploadResponse:error",
352352
"api/CompleteChunkedUploadResponse:meta",
353353
"api/CompleteChunkedUploadResponse:success",
354+
"api/CompleteUploadRequest:attachTo",
354355
"api/CompleteUploadRequest:eTag",
355356
"api/CompleteUploadRequest:fileId",
356357
"api/ConceptListResponse:data",

0 commit comments

Comments
 (0)