@@ -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 ⑤).
1717import { 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.
2124import {
@@ -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+
216267export 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 ) ;
0 commit comments