feat(storage): support for proper disposition headers to maintain true filenames when using aliases (#1358)

kkopanidis · web-flow · commit ffaab4e919b7 · 2025-08-07T13:06:48.000+03:00
feat(storage): support for attachment disposition header to request immediate downloads
diff --git a/modules/storage/src/Storage.ts b/modules/storage/src/Storage.ts
@@ -224,7 +224,7 @@ export default class Storage extends ManagedModule<Config> {
     const request = createParsedRouterRequest(
       call.request,
       undefined,
-      { scope: call.request.scope },
+      { scope: call.request.scope, download: call.request.download },
       undefined,
       undefined,
       undefined,
diff --git a/modules/storage/src/admin/adminFile.ts b/modules/storage/src/admin/adminFile.ts
@@ -9,7 +9,7 @@ import { ConfigController } from '@conduitplatform/module-tools';
 import { status } from '@grpc/grpc-js';
 import { isNil, isString } from 'lodash-es';
 import { _StorageContainer, _StorageFolder, File } from '../models/index.js';
-import { IStorageProvider } from '../interfaces/index.js';
+import { IStorageProvider, UrlOptions } from '../interfaces/index.js';
 import {
   _createFileUploadUrl,
   _updateFile,
@@ -208,9 +208,13 @@ export class AdminFileHandlers {
         }
         return { redirect: found.url };
       }
+      let options: UrlOptions = {
+        download: call.request.params.download ?? false,
+        fileName: found.alias ?? found.name,
+      };
       const url = await this.storageProvider
         .container(found.container)
-        .getSignedUrl((found.folder === '/' ? '' : found.folder) + found.name);
+        .getSignedUrl((found.folder === '/' ? '' : found.folder) + found.name, options);
 
       if (!call.request.params.redirect) {
         return { result: url };
diff --git a/modules/storage/src/handlers/file.ts b/modules/storage/src/handlers/file.ts
@@ -10,7 +10,7 @@ import { ConfigController } from '@conduitplatform/module-tools';
 import { status } from '@grpc/grpc-js';
 import { isNil, isString } from 'lodash-es';
 import { _StorageContainer, _StorageFolder, File } from '../models/index.js';
-import { IStorageProvider } from '../interfaces/index.js';
+import { IStorageProvider, UrlOptions } from '../interfaces/index.js';
 import {
   _createFileUploadUrl,
   _updateFile,
@@ -275,9 +275,13 @@ export class FileHandlers {
         return { redirect: found.url };
       }
       await this.fileAccessCheck('read', call.request, found);
+      const options: UrlOptions = {
+        download: call.request.params.download ?? false,
+        fileName: found.alias ?? found.name,
+      };
       const url = await this.storageProvider
         .container(found.container)
-        .getSignedUrl((found.folder === '/' ? '' : found.folder) + found.name);
+        .getSignedUrl((found.folder === '/' ? '' : found.folder) + found.name, options);
 
       if (!call.request.params.redirect) {
         return { result: url };
diff --git a/modules/storage/src/interfaces/IStorageProvider.ts b/modules/storage/src/interfaces/IStorageProvider.ts
@@ -1,3 +1,8 @@
+export type UrlOptions = {
+  download?: boolean;
+  fileName?: string;
+};
+
 export interface IStorageProvider {
   store(fileName: string, data: any, isPublic?: boolean): Promise<boolean | Error>;
 
@@ -34,7 +39,7 @@ export interface IStorageProvider {
 
   get(fileName: string, downloadPath?: string): Promise<Buffer | Error>;
 
-  getSignedUrl(fileName: string): Promise<any | Error>;
+  getSignedUrl(fileName: string, options?: UrlOptions): Promise<any | Error>;
 
   getPublicUrl(fileName: string): Promise<any | Error>;
 
diff --git a/modules/storage/src/providers/aliyun/index.ts b/modules/storage/src/providers/aliyun/index.ts
@@ -1,8 +1,9 @@
-import { IStorageProvider, StorageConfig } from '../../interfaces/index.js';
+import { IStorageProvider, StorageConfig, UrlOptions } from '../../interfaces/index.js';
 import OSS from 'ali-oss';
 import fs from 'fs';
 import { ConduitGrpcSdk } from '@conduitplatform/grpc-sdk';
 import { SIGNED_URL_EXPIRY_SECONDS } from '../../constants/expiry.js';
+import { constructDispositionHeader } from '../../utils/index.js';
 
 export class AliyunStorage implements IStorageProvider {
   private _activeContainer: string = '';
@@ -135,13 +136,14 @@ export class AliyunStorage implements IStorageProvider {
     return content;
   }
 
-  async getSignedUrl(fileName: string): Promise<any | Error> {
-    const url = this._ossClient.signatureUrl(fileName, {
+  async getSignedUrl(fileName: string, options?: UrlOptions): Promise<any | Error> {
+    return this._ossClient.signatureUrl(fileName, {
       expires: SIGNED_URL_EXPIRY_SECONDS,
       method: 'GET',
+      response: {
+        'content-disposition': constructDispositionHeader(fileName, options),
+      },
     });
-
-    return url;
   }
 
   async getPublicUrl(fileName: string): Promise<any | Error> {
diff --git a/modules/storage/src/providers/aws/index.ts b/modules/storage/src/providers/aws/index.ts
@@ -1,4 +1,4 @@
-import { IStorageProvider, StorageConfig } from '../../interfaces/index.js';
+import { IStorageProvider, StorageConfig, UrlOptions } from '../../interfaces/index.js';
 import {
   CreateBucketCommand,
   DeleteBucketCommand,
@@ -12,7 +12,7 @@ import {
   S3ClientConfig,
 } from '@aws-sdk/client-s3';
 import { Readable } from 'stream';
-import { streamToBuffer } from '../../utils/index.js';
+import { constructDispositionHeader, streamToBuffer } from '../../utils/index.js';
 import fs from 'fs';
 import { getSignedUrl as awsGetSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { ConduitGrpcSdk } from '@conduitplatform/grpc-sdk';
@@ -202,10 +202,11 @@ export class AWSS3Storage implements IStorageProvider {
     }
   }
 
-  async getSignedUrl(fileName: string) {
+  async getSignedUrl(fileName: string, options?: UrlOptions) {
     const command = new GetObjectCommand({
       Bucket: this._activeContainer,
       Key: fileName,
+      ResponseContentDisposition: constructDispositionHeader(fileName, options),
     });
     return awsGetSignedUrl(this._storage, command, {
       expiresIn: SIGNED_URL_EXPIRY_SECONDS,
diff --git a/modules/storage/src/providers/azure/index.ts b/modules/storage/src/providers/azure/index.ts
@@ -1,4 +1,4 @@
-import { IStorageProvider, StorageConfig } from '../../interfaces/index.js';
+import { IStorageProvider, StorageConfig, UrlOptions } from '../../interfaces/index.js';
 import {
   BlobClient,
   BlobSASPermissions,
@@ -8,7 +8,7 @@ import {
 } from '@azure/storage-blob';
 import fs from 'fs';
 import { ConduitGrpcSdk } from '@conduitplatform/grpc-sdk';
-import { streamToBuffer } from '../../utils/index.js';
+import { constructDispositionHeader, streamToBuffer } from '../../utils/index.js';
 import { SIGNED_URL_EXPIRY_DATE } from '../../constants/expiry.js';
 
 export class AzureStorage implements IStorageProvider {
@@ -122,14 +122,17 @@ export class AzureStorage implements IStorageProvider {
     return data;
   }
 
-  async getSignedUrl(fileName: string): Promise<any | Error> {
+  async getSignedUrl(fileName: string, options: UrlOptions): Promise<any | Error> {
     const containerClient = this._storage.getContainerClient(this._activeContainer);
     const sasOptions: BlobSASSignatureValues = {
       containerName: containerClient.containerName,
       blobName: fileName,
       expiresOn: new Date(SIGNED_URL_EXPIRY_DATE()),
       permissions: BlobSASPermissions.parse('r'),
     };
+    if (options) {
+      sasOptions.contentDisposition = constructDispositionHeader(fileName, options);
+    }
     return this.blobClient(fileName).generateSasUrl(sasOptions);
   }
 
diff --git a/modules/storage/src/providers/google/index.ts b/modules/storage/src/providers/google/index.ts
@@ -1,7 +1,8 @@
-import { IStorageProvider, StorageConfig } from '../../interfaces/index.js';
+import { IStorageProvider, StorageConfig, UrlOptions } from '../../interfaces/index.js';
 import { Storage } from '@google-cloud/storage';
 import { ConduitGrpcSdk } from '@conduitplatform/grpc-sdk';
 import { SIGNED_URL_EXPIRY_DATE } from '../../constants/expiry.js';
+import { constructDispositionHeader } from '../../utils/index.js';
 
 /**
  * WARNING: DO NOT USE THIS, IT NEEDS A REWRITE
@@ -103,13 +104,14 @@ export class GoogleCloudStorage implements IStorageProvider {
     });
   }
 
-  async getSignedUrl(fileName: string): Promise<any | Error> {
+  async getSignedUrl(fileName: string, options?: UrlOptions): Promise<any | Error> {
     this._storage
       .bucket(this._activeBucket)
       .file(fileName)
       .getSignedUrl({
         action: 'read',
         expires: SIGNED_URL_EXPIRY_DATE(),
+        responseDisposition: constructDispositionHeader(fileName, options),
       })
       .then((r: any) => {
         if (r.data && r.data[0]) {
@@ -120,8 +122,7 @@ export class GoogleCloudStorage implements IStorageProvider {
   }
 
   async getPublicUrl(fileName: string): Promise<any | Error> {
-    await this._storage.bucket(this._activeBucket).file(fileName).isPublic();
-    return this._storage.bucket(this._activeBucket).file(fileName).baseUrl;
+    return this._storage.bucket(this._activeBucket).file(fileName).publicUrl();
   }
 
   async store(
diff --git a/modules/storage/src/routes/index.ts b/modules/storage/src/routes/index.ts
@@ -53,6 +53,7 @@ export class StorageRoutes {
         },
         queryParams: {
           redirect: { type: TYPE.Boolean, required: false },
+          download: { type: TYPE.Boolean, required: false },
           ...(authzEnabled && { scope: { type: TYPE.String, required: false } }),
         },
         middlewares: ['authMiddleware?'],
diff --git a/modules/storage/src/storage.proto b/modules/storage/src/storage.proto
@@ -11,6 +11,7 @@ message GetFileUrlRequest {
   string id = 1;
   optional string userId = 2;
   optional string scope = 3;
+  optional bool download = 4;
 
 }
 message GetFileUrlResponse {
diff --git a/modules/storage/src/utils/index.ts b/modules/storage/src/utils/index.ts
@@ -1,5 +1,10 @@
 import { GetUserCommand, IAMClient } from '@aws-sdk/client-iam';
-import { IFileParams, IStorageProvider, StorageConfig } from '../interfaces/index.js';
+import {
+  IFileParams,
+  IStorageProvider,
+  StorageConfig,
+  UrlOptions,
+} from '../interfaces/index.js';
 import { isNil } from 'lodash-es';
 import path from 'path';
 import { File } from '../models/index.js';
@@ -254,3 +259,18 @@ export async function validateName(
     return `${name} (${count})`;
   }
 }
+
+export const constructDispositionHeader = (
+  fileName: string,
+  options?: UrlOptions,
+): string | undefined => {
+  if (!options || (!options.download && !options.fileName)) {
+    return undefined;
+  }
+  const disposition = options.download ? 'attachment' : 'inline';
+  const _fileName = `; filename="${options.fileName ?? fileName}"`;
+  const _fileNameUtf8 = `; filename*=UTF-8''${encodeURIComponent(
+    options.fileName ?? fileName,
+  )}`;
+  return `${disposition}${_fileName}${_fileNameUtf8}`;
+};

Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,7 @@ message GetFileUrlRequest {`
`11`	`11`	`string id = 1;`
`12`	`12`	`optional string userId = 2;`
`13`	`13`	`optional string scope = 3;`
	`14`	`+ optional bool download = 4;`
`14`	`15`
`15`	`16`	`}`
`16`	`17`	`message GetFileUrlResponse {`