RDBC-1011 refactor: update remote attachment handling

- Replaced `RemoteAttachmentFlags` enum with string literals for enhanced type safety.
- Introduced new remote attachment parameters with extended metadata handling.
- Updated GetAttachmentOperation to integrate remote attachment processing using HTTP headers.
- Improved metadata transformation logic for attachments and refactored utility methods.

Author: M4xymm

src/Documents/Attachments/RemoteAttachmentFlags.ts

@@ -1,14 +1,4 @@
 /**
  * Flags that indicate the location and characteristics of an attachment.
  */
-export enum RemoteAttachmentFlags {
-    /**
-     * No flags are set. The attachment is stored locally.
-     */
-    None = 0,
-
-    /**
-     * The attachment is stored remotely in cloud storage rather than in the local database.
-     */
-    Remote = 0x1
-}
+export type RemoteAttachmentFlags = "None" | "Remote"

src/Documents/Attachments/index.ts

@@ -2,7 +2,7 @@ import { Readable } from "node:stream";
 import { HttpResponse } from "../../Primitives/Http.js";
 import { closeHttpResponse } from "../../Utility/HttpUtil.js";
 import { CapitalizeType } from "../../Types/index.js";
-import { RemoteAttachmentFlags } from "./RemoteAttachmentFlags.js";
+import { RemoteAttachmentParameters } from "../Operations/Attachments/RemoteAttachmentParameters.js";
 
 export type AttachmentType = "Document" | "Revision";
 
@@ -11,7 +11,7 @@ export interface AttachmentName {
     hash: string;
     contentType: string;
     size: number;
-    remoteParameters?: RemoteAttachmentFlags;
+    remoteParameters?: RemoteAttachmentParameters;
 }
 
 export interface AttachmentNameWithCount extends AttachmentName {

src/Documents/Commands/Batches/PutAttachmentCommandData.ts

@@ -4,6 +4,7 @@ import { RemoteAttachmentParameters } from "../../Operations/Attachments/RemoteA
 import { StringUtil } from "../../../Utility/StringUtil.js";
 import { throwError } from "../../../Exceptions/index.js";
 import { DocumentConventions } from "../../Conventions/DocumentConventions.js";
+import { RemoteAttachmentFlags } from "../../Attachments/RemoteAttachmentFlags.js";
 
 interface DocumentAttachmentDto {
     Id: string;
@@ -16,8 +17,8 @@ interface DocumentAttachmentDto {
 
 interface RemoteParametersDto {
     Identifier: string;
-    Flags: number;
-    At?: string;
+    Flags: RemoteAttachmentFlags;
+    At?: Date;
 }
 
 export class PutAttachmentCommandData implements ICommandData {
@@ -66,7 +67,7 @@ export class PutAttachmentCommandData implements ICommandData {
             result.RemoteParameters = {
                 Identifier: this.remoteParameters.identifier,
                 Flags: this.remoteParameters.flags,
-                At: this.remoteParameters.at?.toISOString()
+                At: this.remoteParameters.at
             };
         }
 

src/Documents/Operations/Attachments/GetAttachmentOperation.ts

@@ -1,8 +1,7 @@
 import { IOperation, OperationResultType } from "../OperationAbstractions.js";
-import { AttachmentDetails } from "../../Attachments/index.js";
+import { AttachmentDetails, AttachmentResult, AttachmentType } from "../../Attachments/index.js";
 import { getEtagHeader } from "../../../Utility/HttpUtil.js";
 import { HttpRequestParameters, HttpResponse } from "../../../Primitives/Http.js";
-import { AttachmentResult, AttachmentType } from "../../Attachments/index.js";
 import { RavenCommand, ResponseDisposeHandling } from "../../../Http/RavenCommand.js";
 import { HttpCache } from "../../../Http/HttpCache.js";
 import { IDocumentStore } from "../../IDocumentStore.js";
@@ -11,6 +10,10 @@ import { throwError } from "../../../Exceptions/index.js";
 import { StringUtil } from "../../../Utility/StringUtil.js";
 import { ServerNode } from "../../../Http/ServerNode.js";
 import { Readable } from "node:stream";
+import { HEADERS } from "../../../Constants.js";
+import { RemoteAttachmentFlags } from "../../Attachments/RemoteAttachmentFlags.js";
+import { RemoteAttachmentParameters } from "./RemoteAttachmentParameters.js";
+import { DateUtil } from "../../../Utility/DateUtil.js";
 
 export class GetAttachmentOperation implements IOperation<AttachmentResult> {
     private readonly _documentId: string;
@@ -37,6 +40,12 @@ export class GetAttachmentOperation implements IOperation<AttachmentResult> {
 
 }
 
+interface InternalRemoteAttachmentParameters {
+    identifier: string;
+    flags: RemoteAttachmentFlags;
+    at: Date;
+}
+
 export class GetAttachmentCommand extends RavenCommand<AttachmentResult> {
     private readonly _documentId: string;
     private readonly _name: string;
@@ -91,6 +100,10 @@ export class GetAttachmentCommand extends RavenCommand<AttachmentResult> {
         const hash = response.headers.get("attachment-hash") as string;
         let size = 0;
         const sizeHeader = response.headers.get("attachment-size") as string;
+        const remoteParametersIdentifier = response.headers.get(HEADERS.ATTACHMENT_REMOTE_PARAMETERS_IDENTIFIER) as string;
+        const remoteParametersAt = response.headers.get(HEADERS.ATTACHMENT_REMOTE_PARAMETERS_AT) as string; // iso date
+        const remoteParametersFlags = response.headers.get(HEADERS.ATTACHMENT_REMOTE_PARAMETERS_FLAGS) as RemoteAttachmentFlags;
+
         if (sizeHeader) {
             size = Number.parseInt(sizeHeader, 10);
         }
@@ -104,11 +117,22 @@ export class GetAttachmentCommand extends RavenCommand<AttachmentResult> {
             size
         };
 
+        if (remoteParametersIdentifier && remoteParametersAt && remoteParametersFlags) {
+            const remoteParameters: InternalRemoteAttachmentParameters = {
+                at: DateUtil.utc.parse(remoteParametersAt),
+                identifier: remoteParametersIdentifier,
+                flags: remoteParametersFlags,
+            }
+
+            details.remoteParameters = remoteParameters as RemoteAttachmentParameters
+        }
+
+
         this.result = new AttachmentResult(bodyStream, details, response);
         return "Manually";
     }
 
     public get isReadRequest() {
         return true;
     }
-}
+}

src/Documents/Operations/Attachments/RemoteAttachmentParameters.ts

@@ -26,7 +26,7 @@ export class RemoteAttachmentParameters {
 
     constructor(identifier: string, at?: Date) {
         this.identifier = identifier;
-        this._flags = RemoteAttachmentFlags.None; // Always set to None for user-created instances
+        this._flags = "None"; // Always set to None for user-created instances
         this.at = at;
     }
 
@@ -38,3 +38,4 @@ export class RemoteAttachmentParameters {
         return this._flags;
     }
 }
+

src/Utility/ObjectUtil.ts

@@ -116,6 +116,8 @@ export class ObjectUtil {
         return transformed;
     }
 
+
+
     public static transformMetadataKeys(metadata: MetadataObject, conventions: DocumentConventions) {
         if (!metadata) {
             return metadata;
@@ -128,15 +130,19 @@ export class ObjectUtil {
 
         for (const [key, value] of Object.entries(metadata)) {
             if (key === CONSTANTS.Documents.Metadata.ATTACHMENTS) {
-                result[CONSTANTS.Documents.Metadata.ATTACHMENTS] = value ? value.map(x => ObjectUtil.mapAttachmentDetailsToLocalObject(x)) : null
-            } else if (key[0] === "@" || key === "Raven-Node-Type") {
+                result[CONSTANTS.Documents.Metadata.ATTACHMENTS] = ObjectUtil.transformAttachments(value, conventions);
+                continue;
+            }
+
+            if (ObjectUtil.isSystemMetadataKey(key)) {
                 result[key] = value;
+                continue;
+            }
+
+            if (needsCaseTransformation) {
+                userMetadataFieldsToTransform[key] = value;
             } else {
-                if (needsCaseTransformation) {
-                    userMetadataFieldsToTransform[key] = value;
-                } else {
-                    result[key] = value;
-                }
+                result[key] = value;
             }
         }
 
@@ -151,14 +157,25 @@ export class ObjectUtil {
         return result;
     }
 
+    private static transformAttachments(attachments: any[], conventions: DocumentConventions): any[] {
+        return attachments?.map(x => ObjectUtil.transformObjectKeys(x, {
+            defaultTransform: conventions.serverToLocalFieldNameConverter ?? ObjectUtil.camelCase
+        })) ?? null;
+    }
+
+    private static isSystemMetadataKey(key: string): boolean {
+        return key[0] === "@" || key === "Raven-Node-Type";
+    }
+
     public static mapAttachmentDetailsToLocalObject(json: any): AttachmentDetails {
         return {
             changeVector: json.ChangeVector,
             contentType: json.ContentType,
             documentId: json.DocumentId,
             hash: json.Hash,
             name: json.Name,
-            size: json.Size
+            size: json.Size,
+            remoteParameters: json.RemoteParameters,
         };
     }
 

test/Ported/Attachments/DocumentSessionRemoteAttachmentsTests.ts

@@ -1,16 +1,18 @@
-import {testContext, disposeTestDocumentStore, RavenTestContext} from "../../Utils/TestUtil.js";
+import {disposeTestDocumentStore, RavenTestContext, testContext} from "../../Utils/TestUtil.js";
 import {
-    IDocumentStore,
     ConfigureRemoteAttachmentsOperation,
+    DateUtil,
+    IDocumentStore,
+    RemoteAttachmentParameters,
     RemoteAttachmentsConfiguration,
     RemoteAttachmentsDestinationConfiguration,
     RemoteAttachmentsS3Settings,
-    RemoteAttachmentParameters,
     StoreAttachmentParameters
 } from "../../../src/index.js";
 import {assertThat} from "../../Utils/AssertExtensions.js";
 import {Readable} from "node:stream";
 import {Buffer} from "node:buffer";
+import {addHours, addMinutes, format} from "date-fns";
 
 interface User {
     id?: string;
@@ -49,6 +51,7 @@ interface User {
     it("can store attachment with remote parameters using StoreAttachmentParameters", async () => {
         const identifier = await setupRemoteAttachmentsConfig();
         const userId = "users/1";
+        const remoteAt = new Date();
 
         {
             const session = store.openSession();
@@ -60,7 +63,7 @@ interface User {
         {
             const session = store.openSession();
             const attachmentData = Buffer.from([1, 2, 3, 4, 5]);
-            const remoteAt = new Date(Date.now() + 60000); // 1 minute from now
+
 
             const parameters = new StoreAttachmentParameters(
                 "profile.png",
@@ -84,12 +87,19 @@ interface User {
                 .isEqualTo("profile.png");
             assertThat(attachment.details.contentType)
                 .isEqualTo("image/png");
+            assertThat(format(attachment.details.remoteParameters.at, DateUtil.DEFAULT_DATE_TZ_FORMAT))
+                .isEqualTo(format(remoteAt, DateUtil.DEFAULT_DATE_TZ_FORMAT));
+            assertThat(attachment.details.remoteParameters.identifier)
+                .isEqualTo(identifier);
+            assertThat(attachment.details.remoteParameters.flags)
+                .isEqualTo("None");
         }
     });
 
     it("can store attachment with remote parameters using direct method", async () => {
         const identifier = await setupRemoteAttachmentsConfig();
         const userId = "users/2";
+            const remoteAt = new Date();
 
         {
             const session = store.openSession();
@@ -101,7 +111,6 @@ interface User {
         {
             const session = store.openSession();
             const attachmentData = Buffer.from([10, 20, 30]);
-            const remoteAt = new Date(Date.now() + 120000); // 2 minutes from now
 
             const parameters = new StoreAttachmentParameters(
                 "document.pdf",
@@ -126,6 +135,12 @@ interface User {
                 .isEqualTo(1);
             assertThat(names[0].name)
                 .isEqualTo("document.pdf");
+            assertThat(format(names[0].remoteParameters.at, DateUtil.DEFAULT_DATE_TZ_FORMAT))
+                .isEqualTo(format(remoteAt, DateUtil.DEFAULT_DATE_TZ_FORMAT));
+            assertThat(names[0].remoteParameters.identifier)
+                .isEqualTo(identifier);
+            assertThat(names[0].remoteParameters.flags)
+                .isEqualTo("None");
         }
     });
 
@@ -160,6 +175,8 @@ interface User {
 
             assertThat(attachment)
                 .isNotNull();
+            assertThat(attachment.details.remoteParameters)
+                .isUndefined();
             assertThat(attachment.details.name)
                 .isEqualTo("local-file.txt");
         }
@@ -206,7 +223,7 @@ interface User {
                 Readable.from(data1),
                 "application/octet-stream",
                 null,
-                new RemoteAttachmentParameters("S3-Primary", new Date(Date.now() + 60000))
+                new RemoteAttachmentParameters("S3-Primary", addMinutes(new Date(), 1))
             );
             session.advanced.attachments.store(userId, params1);
 
@@ -217,7 +234,7 @@ interface User {
                 Readable.from(data2),
                 "application/octet-stream",
                 null,
-                new RemoteAttachmentParameters("S3-Secondary", new Date(Date.now() + 120000))
+                new RemoteAttachmentParameters("S3-Secondary", addMinutes(new Date(), 2))
             );
             session.advanced.attachments.store(userId, params2);
 
@@ -237,6 +254,18 @@ interface User {
                 .isEqualTo("primary.dat");
             assertThat(namesList[1])
                 .isEqualTo("secondary.dat");
+
+            const attachment1 = await session.advanced.attachments.get(userId, "primary.dat");
+            assertThat(attachment1.details.remoteParameters.identifier)
+                .isEqualTo("S3-Primary");
+            assertThat(attachment1.details.remoteParameters.flags)
+                .isEqualTo("None");
+
+            const attachment2 = await session.advanced.attachments.get(userId, "secondary.dat");
+            assertThat(attachment2.details.remoteParameters.identifier)
+                .isEqualTo("S3-Secondary");
+            assertThat(attachment2.details.remoteParameters.flags)
+                .isEqualTo("None");
         }
     });
 
@@ -324,7 +353,7 @@ interface User {
             await session.saveChanges();
         }
 
-        const scheduledTime = new Date(Date.now() + 3600000); // 1 hour from now
+        const scheduledTime = addHours(new Date(), 1);
 
         {
             const session = store.openSession();
@@ -350,6 +379,12 @@ interface User {
                 .isNotNull();
             assertThat(attachment.details.name)
                 .isEqualTo("scheduled.dat");
+            assertThat(format(attachment.details.remoteParameters.at, DateUtil.DEFAULT_DATE_TZ_FORMAT))
+                .isEqualTo(format(scheduledTime, DateUtil.DEFAULT_DATE_TZ_FORMAT));
+            assertThat(attachment.details.remoteParameters.identifier)
+                .isEqualTo(identifier);
+            assertThat(attachment.details.remoteParameters.flags)
+                .isEqualTo("None");
         }
     });
 });

test/Utils/AssertExtensions.ts

@@ -163,4 +163,9 @@ export class JavaAssertionBuilder {
         assert.ok(satisfy, "None of items satisfy condition");
         return this;
     }
+
+    public isUndefined() {
+        assert.ok(this._value === undefined);
+        return this;
+    }
 }