Skip to content

The open alternative to Salesforce, designed for AI.

Support HTTP range requests for streamed files (#24517)

nitin641797cfe3ad
diff --git a/packages/twenty-server/src/engine/core-modules/exception-handler/http-exception-handler.service.ts b/packages/twenty-server/src/engine/core-modules/exception-handler/http-exception-handler.service.ts
index 9b7e5715b33..ce30f9bcaf1 100644
--- a/packages/twenty-server/src/engine/core-modules/exception-handler/http-exception-handler.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/exception-handler/http-exception-handler.service.ts
@@ -45,6 +45,8 @@ const getErrorNameFromStatusCode = (statusCode: number) => {
return 'MethodNotAllowedException';
case 409:
return 'ConflictException';
+ case 416:
+ return 'RequestedRangeNotSatisfiableException';
case 422:
return 'UnprocessableEntityException';
case 500:
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/local.driver.spec.ts b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/local.driver.spec.ts
index f23784fd9fd..b95ea808d23 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/local.driver.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/local.driver.spec.ts
@@ -14,8 +14,9 @@ import { Readable } from 'stream';
import { FileStorageExceptionCode } from 'src/engine/core-modules/file-storage/interfaces/file-storage-exception';
import { LocalDriver } from 'src/engine/core-modules/file-storage/drivers/local.driver';
+import { streamToBuffer } from 'src/utils/stream-to-buffer';
-describe('LocalDriver security hardening', () => {
+describe('LocalDriver', () => {
const cleanupPaths: string[] = [];
const createTempDirectory = async (prefix: string) => {
@@ -34,6 +35,26 @@ describe('LocalDriver security hardening', () => {
);
});
+ describe('readFile', () => {
+ it('should read only the requested byte range', async () => {
+ const storagePath = await createTempDirectory('local-driver-storage-');
+ const folderPath = path.join(storagePath, 'workspace', 'app');
+
+ await mkdir(folderPath, { recursive: true });
+ await writeFile(path.join(folderPath, 'file.txt'), '0123456789');
+
+ const driver = new LocalDriver({ storagePath });
+ const stream = await driver.readFile({
+ filePath: 'workspace/app/file.txt',
+ byteRange: { startByte: 2, endByte: 5 },
+ });
+
+ await expect(streamToBuffer(stream)).resolves.toEqual(
+ Buffer.from('2345'),
+ );
+ });
+ });
+
it('should reject writeFile when target is a symlink', async () => {
const storagePath = await createTempDirectory('local-driver-storage-');
const outsidePath = await createTempDirectory('local-driver-outside-');
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/s3.driver.spec.ts b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/s3.driver.spec.ts
index 3e227af4ac4..1babdf95d83 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/s3.driver.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/__tests__/s3.driver.spec.ts
@@ -1,14 +1,18 @@
import { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { Readable } from 'stream';
+
import { S3Driver } from 'src/engine/core-modules/file-storage/drivers/s3.driver';
+const mockS3Send = jest.fn();
+
jest.mock('@aws-sdk/client-s3', () => {
const actual = jest.requireActual('@aws-sdk/client-s3');
return {
...actual,
- S3: jest.fn().mockImplementation(() => ({})),
+ S3: jest.fn().mockImplementation(() => ({ send: mockS3Send })),
};
});
@@ -16,6 +20,40 @@ jest.mock('@aws-sdk/s3-request-presigner', () => ({
getSignedUrl: jest.fn(),
}));
+describe('S3Driver.readFile', () => {
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('should request only the specified byte range', async () => {
+ mockS3Send.mockResolvedValue({
+ Body: Readable.from([Buffer.from('requested bytes')]),
+ });
+
+ const driver = new S3Driver({
+ bucketName: 'test-bucket',
+ region: 'us-east-1',
+ });
+
+ await driver.readFile({
+ filePath: 'recordings/video.mp4',
+ byteRange: { startByte: 100, endByte: 199 },
+ });
+
+ expect(mockS3Send).toHaveBeenCalledTimes(1);
+
+ expect(mockS3Send).toHaveBeenCalledWith(
+ expect.objectContaining({
+ input: expect.objectContaining({
+ Bucket: 'test-bucket',
+ Key: 'recordings/video.mp4',
+ Range: 'bytes=100-199',
+ }),
+ }),
+ );
+ });
+});
+
describe('S3Driver.getPresignedUrl', () => {
afterEach(() => {
jest.clearAllMocks();
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/interfaces/storage-driver.interface.ts b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/interfaces/storage-driver.interface.ts
index 890cf351dd2..805ab3358cb 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/interfaces/storage-driver.interface.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/interfaces/storage-driver.interface.ts
@@ -1,7 +1,12 @@
import { type Readable } from 'stream';
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
+
export interface StorageDriver {
- readFile(params: { filePath: string }): Promise<Readable>;
+ readFile(params: {
+ filePath: string;
+ byteRange?: ByteRange;
+ }): Promise<Readable>;
writeFile(params: {
filePath: string;
sourceFile: Buffer | Uint8Array | string;
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/local.driver.ts b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/local.driver.ts
index cea0fdd24f8..8c4c9d08087 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/local.driver.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/local.driver.ts
@@ -9,11 +9,14 @@ import path, { dirname, join } from 'path';
import { type Readable } from 'stream';
import { pipeline } from 'stream/promises';
+import { isDefined } from 'twenty-shared/utils';
+
import { type StorageDriver } from 'src/engine/core-modules/file-storage/drivers/interfaces/storage-driver.interface';
import {
FileStorageException,
FileStorageExceptionCode,
} from 'src/engine/core-modules/file-storage/interfaces/file-storage-exception';
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
export interface LocalDriverOptions {
storagePath: string;
@@ -41,7 +44,10 @@ export class LocalDriver implements StorageDriver {
}
}
- async readFile(params: { filePath: string }): Promise<Readable> {
+ async readFile(params: {
+ filePath: string;
+ byteRange?: ByteRange;
+ }): Promise<Readable> {
const joinedPath = join(this.options.storagePath, params.filePath);
let filePath: string;
@@ -57,7 +63,12 @@ export class LocalDriver implements StorageDriver {
this.assertRealPathIsWithinStorage(filePath);
try {
- return createReadStream(filePath);
+ return createReadStream(
+ filePath,
+ isDefined(params.byteRange)
+ ? { start: params.byteRange.startByte, end: params.byteRange.endByte }
+ : undefined,
+ );
} catch (error) {
if (error.code === 'ENOENT') {
throw new FileStorageException(
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/s3.driver.ts b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/s3.driver.ts
index 1ced1877cc4..88a83d33fc8 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/s3.driver.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/s3.driver.ts
@@ -34,6 +34,7 @@ import {
FileStorageException,
FileStorageExceptionCode,
} from 'src/engine/core-modules/file-storage/interfaces/file-storage-exception';
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
import { buildAwsRequestHandlerOptions } from 'src/utils/aws-request-handler.util';
export interface S3DriverOptions extends S3ClientConfig {
@@ -89,10 +90,16 @@ export class S3Driver implements StorageDriver {
return this.s3Client;
}
- async readFile(params: { filePath: string }): Promise<Readable> {
+ async readFile(params: {
+ filePath: string;
+ byteRange?: ByteRange;
+ }): Promise<Readable> {
const command = new GetObjectCommand({
Key: params.filePath,
Bucket: this.bucketName,
+ Range: isDefined(params.byteRange)
+ ? `bytes=${params.byteRange.startByte}-${params.byteRange.endByte}`
+ : undefined,
});
try {
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/validated-storage.driver.ts b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/validated-storage.driver.ts
index 73fdf336532..62ff94ff010 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/drivers/validated-storage.driver.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/drivers/validated-storage.driver.ts
@@ -3,11 +3,15 @@ import { type Readable } from 'stream';
import { type StorageDriver } from 'src/engine/core-modules/file-storage/drivers/interfaces/storage-driver.interface';
import { assertStoragePathIsSafe } from 'src/engine/core-modules/file-storage/utils/assert-storage-path-is-safe.util';
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
export class ValidatedStorageDriver implements StorageDriver {
constructor(private readonly delegate: StorageDriver) {}
- async readFile(params: { filePath: string }): Promise<Readable> {
+ async readFile(params: {
+ filePath: string;
+ byteRange?: ByteRange;
+ }): Promise<Readable> {
assertStoragePathIsSafe(params.filePath);
return this.delegate.readFile(params);
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/services/file-storage.service.ts b/packages/twenty-server/src/engine/core-modules/file-storage/services/file-storage.service.ts
index 3d46698d85b..893dc2b1f5d 100644
--- a/packages/twenty-server/src/engine/core-modules/file-storage/services/file-storage.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/services/file-storage.service.ts
@@ -11,6 +11,7 @@ import { ApplicationEntity } from 'src/engine/core-modules/application/applicati
import { findActiveFlatApplicationById } from 'src/engine/core-modules/application/utils/find-active-flat-application-by-id.util';
import { findActiveFlatApplicationByUniversalIdentifier } from 'src/engine/core-modules/application/utils/find-active-flat-application-by-universal-identifier.util';
import { FileStorageDriverFactory } from 'src/engine/core-modules/file-storage/file-storage-driver.factory';
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
import {
FileStorageException,
FileStorageExceptionCode,
@@ -373,13 +374,18 @@ export class FileStorageService {
});
}
- readFile(params: ResourceIdentifier): Promise<Readable> {
+ readFile(
+ params: ResourceIdentifier & { byteRange?: ByteRange },
+ ): Promise<Readable> {
const driver = this.fileStorageDriverFactory.getCurrentDriver();
const { onStorageFilePath } =
this.validateAndBuildFileStoragePathOrThrow(params);
- return driver.readFile({ filePath: onStorageFilePath });
+ return driver.readFile({
+ filePath: onStorageFilePath,
+ byteRange: params.byteRange,
+ });
}
downloadFile(
diff --git a/packages/twenty-server/src/engine/core-modules/file-storage/types/byte-range.type.ts b/packages/twenty-server/src/engine/core-modules/file-storage/types/byte-range.type.ts
new file mode 100644
index 00000000000..5decc0da1ce
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/file-storage/types/byte-range.type.ts
@@ -0,0 +1,4 @@
+export type ByteRange = {
+ startByte: number;
+ endByte: number;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.spec.ts b/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.spec.ts
index 0fb5d679b45..580eb1f1b9b 100644
--- a/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.spec.ts
@@ -41,10 +41,15 @@ const createMockResponse = ({
}: { headersSent?: boolean } = {}) => ({
setHeader: jest.fn(),
redirect: jest.fn(),
+ status: jest.fn(),
+ end: jest.fn(),
headersSent,
destroy: jest.fn(),
});
+const createMockFileRequest = (range?: string) =>
+ ({ workspaceId: 'workspace-id', headers: { range } }) as any;
+
const mockPipeline = jest.mocked(pipeline);
describe('FileController', () => {
@@ -112,7 +117,7 @@ describe('FileController', () => {
presignedUrl: 'https://s3.example.com/file?signed=abc',
});
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse() as any;
await controller.getFileById(
@@ -126,6 +131,7 @@ describe('FileController', () => {
fileId: 'file-123',
workspaceId: 'workspace-id',
fileFolder: FileFolder.Workflow,
+ rangeHeader: undefined,
});
expect(mockResponse.redirect).toHaveBeenCalledWith(
'https://s3.example.com/file?signed=abc',
@@ -144,7 +150,7 @@ describe('FileController', () => {
mimeType: 'image/png',
});
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse() as any;
await controller.getFileById(
@@ -173,6 +179,78 @@ describe('FileController', () => {
expect(mockPipeline).toHaveBeenCalledWith(mockStream, mockResponse);
});
+ it('should return the requested byte range with partial content headers', async () => {
+ const mockStream = createMockStream();
+
+ jest
+ .spyOn(fileService, 'getFilePresignedUrlOrStreamById')
+ .mockResolvedValue({
+ type: 'stream',
+ stream: mockStream,
+ mimeType: 'video/mp4',
+ contentRange: {
+ startByte: 100,
+ endByte: 199,
+ fileSizeInBytes: 1_000,
+ },
+ });
+
+ const mockRequest = createMockFileRequest('bytes=100-199');
+ const mockResponse = createMockResponse() as any;
+
+ await controller.getFileById(
+ mockResponse,
+ mockRequest,
+ FileFolder.FilesField,
+ 'file-123',
+ );
+
+ expect(fileService.getFilePresignedUrlOrStreamById).toHaveBeenCalledWith({
+ fileId: 'file-123',
+ workspaceId: 'workspace-id',
+ fileFolder: FileFolder.FilesField,
+ rangeHeader: 'bytes=100-199',
+ });
+ expect(mockResponse.status).toHaveBeenCalledWith(206);
+ expect(mockResponse.setHeader).toHaveBeenCalledWith(
+ 'Content-Range',
+ 'bytes 100-199/1000',
+ );
+ expect(mockResponse.setHeader).toHaveBeenCalledWith(
+ 'Content-Length',
+ '100',
+ );
+ expect(mockPipeline).toHaveBeenCalledWith(mockStream, mockResponse);
+ });
+
+ it('should propagate range errors unchanged for the exception filter to map', async () => {
+ const rangeError = new FileException(
+ 'Requested range not satisfiable',
+ FileExceptionCode.RANGE_NOT_SATISFIABLE,
+ { fileSizeInBytes: 1_000 },
+ );
+
+ jest
+ .spyOn(fileService, 'getFilePresignedUrlOrStreamById')
+ .mockRejectedValue(rangeError);
+
+ const mockRequest = createMockFileRequest('bytes=1000-');
+ const mockResponse = createMockResponse() as any;
+
+ mockPipeline.mockClear();
+
+ await expect(
+ controller.getFileById(
+ mockResponse,
+ mockRequest,
+ FileFolder.FilesField,
+ 'file-123',
+ ),
+ ).rejects.toBe(rangeError);
+
+ expect(mockPipeline).not.toHaveBeenCalled();
+ });
+
it('should force attachment disposition for non-safe MIME types', async () => {
const mockStream = createMockStream();
@@ -184,7 +262,7 @@ describe('FileController', () => {
mimeType: 'text/html',
});
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse() as any;
await controller.getFileById(
@@ -209,7 +287,7 @@ describe('FileController', () => {
.spyOn(fileService, 'getFilePresignedUrlOrStreamById')
.mockResolvedValue(null);
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse() as any;
await expect(
@@ -236,7 +314,7 @@ describe('FileController', () => {
.spyOn(fileService, 'getFilePresignedUrlOrStreamById')
.mockRejectedValue(underlyingError);
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse() as any;
const promise = controller.getFileById(
@@ -273,7 +351,7 @@ describe('FileController', () => {
mockPipeline.mockRejectedValue(new Error('source backend exploded'));
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse({ headersSent: false }) as any;
await expect(
@@ -306,7 +384,7 @@ describe('FileController', () => {
mockPipeline.mockRejectedValue(new Error('socket reset mid-flight'));
- const mockRequest = { workspaceId: 'workspace-id' } as any;
+ const mockRequest = createMockFileRequest();
const mockResponse = createMockResponse({ headersSent: true }) as any;
// No throw expected — once headers are out, the controller cannot honestly
diff --git a/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.ts b/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.ts
index f7e19edcbae..c736880aae8 100644
--- a/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/controllers/file.controller.ts
@@ -15,6 +15,7 @@ import { type Readable } from 'stream';
import { Request, Response } from 'express';
import { ApiPath, FileFolder, ServerFileFolder } from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
import {
FileStorageException,
@@ -37,6 +38,9 @@ import { setFileResponseHeaders } from 'src/engine/core-modules/file/utils/set-f
import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';
import { PublicEndpointGuard } from 'src/engine/guards/public-endpoint.guard';
+// workspaceId is bound onto the request by FileByIdGuard.
+type FileByIdRequest = Request & { workspaceId: string };
+
@Controller()
@UseFilters(FileApiExceptionFilter)
export class FileController {
@@ -189,20 +193,24 @@ export class FileController {
@UseGuards(FileByIdGuard, NoPermissionGuard)
async getFileById(
@Res() res: Response,
- @Req() req: Request,
+ @Req() req: FileByIdRequest,
@Param('fileFolder') fileFolder: SupportedFileFolder,
@Param('id') fileId: string,
) {
- // oxlint-disable-next-line typescript/no-explicit-any
- const workspaceId = (req as any)?.workspaceId;
+ const workspaceId = req.workspaceId;
const fileResponse = await this.fileService
.getFilePresignedUrlOrStreamById({
fileId,
workspaceId,
fileFolder,
+ rangeHeader: req.headers.range,
})
.catch((error) => {
+ if (error instanceof FileException) {
+ throw error;
+ }
+
this.logger.error(
'getFilePresignedUrlOrStreamById failed unexpectedly',
{
@@ -228,6 +236,18 @@ export class FileController {
}
setFileResponseHeaders(res, fileResponse.mimeType, fileFolder);
+ res.setHeader('Accept-Ranges', 'bytes');
+
+ if (isDefined(fileResponse.contentRange)) {
+ const { startByte, endByte, fileSizeInBytes } = fileResponse.contentRange;
+
+ res.status(206);
+ res.setHeader(
+ 'Content-Range',
+ `bytes ${startByte}-${endByte}/${fileSizeInBytes}`,
+ );
+ res.setHeader('Content-Length', String(endByte - startByte + 1));
+ }
try {
await pipeline(fileResponse.stream, res);
diff --git a/packages/twenty-server/src/engine/core-modules/file/file.exception.ts b/packages/twenty-server/src/engine/core-modules/file/file.exception.ts
index 7ee7de51d76..4e6641368c1 100644
--- a/packages/twenty-server/src/engine/core-modules/file/file.exception.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/file.exception.ts
@@ -13,6 +13,7 @@ export const FileExceptionCode = appendCommonExceptionCode({
FILE_NOT_FOUND: 'FILE_NOT_FOUND',
INVALID_FILE_FOLDER: 'INVALID_FILE_FOLDER',
TEMPORARY_FILE_NOT_ALLOWED: 'TEMPORARY_FILE_NOT_ALLOWED',
+ RANGE_NOT_SATISFIABLE: 'RANGE_NOT_SATISFIABLE',
} as const);
const getFileExceptionUserFriendlyMessage = (
@@ -27,6 +28,8 @@ const getFileExceptionUserFriendlyMessage = (
return msg`Invalid file folder.`;
case FileExceptionCode.TEMPORARY_FILE_NOT_ALLOWED:
return msg`Temporary file cannot be downloaded.`;
+ case FileExceptionCode.RANGE_NOT_SATISFIABLE:
+ return msg`Requested file range cannot be served.`;
case FileExceptionCode.INTERNAL_SERVER_ERROR:
return STANDARD_ERROR_MESSAGE;
default:
@@ -37,14 +40,23 @@ const getFileExceptionUserFriendlyMessage = (
export class FileException extends CustomException<
keyof typeof FileExceptionCode
> {
+ fileSizeInBytes?: number;
+
constructor(
message: string,
code: keyof typeof FileExceptionCode,
- { userFriendlyMessage }: { userFriendlyMessage?: MessageDescriptor } = {},
+ {
+ userFriendlyMessage,
+ fileSizeInBytes,
+ }: {
+ userFriendlyMessage?: MessageDescriptor;
+ fileSizeInBytes?: number;
+ } = {},
) {
super(message, code, {
userFriendlyMessage:
userFriendlyMessage ?? getFileExceptionUserFriendlyMessage(code),
});
+ this.fileSizeInBytes = fileSizeInBytes;
}
}
diff --git a/packages/twenty-server/src/engine/core-modules/file/filters/file-api-exception.filter.ts b/packages/twenty-server/src/engine/core-modules/file/filters/file-api-exception.filter.ts
index dbac5522661..625dccef7e2 100644
--- a/packages/twenty-server/src/engine/core-modules/file/filters/file-api-exception.filter.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/filters/file-api-exception.filter.ts
@@ -5,6 +5,7 @@ import {
} from '@nestjs/common';
import { type Response } from 'express';
+import { isDefined } from 'twenty-shared/utils';
import { HttpExceptionHandlerService } from 'src/engine/core-modules/exception-handler/http-exception-handler.service';
import {
@@ -35,6 +36,19 @@ export class FileApiExceptionFilter implements ExceptionFilter {
response,
404,
);
+ case FileExceptionCode.RANGE_NOT_SATISFIABLE:
+ if (isDefined(exception.fileSizeInBytes)) {
+ response.setHeader(
+ 'Content-Range',
+ `bytes */${exception.fileSizeInBytes}`,
+ );
+ }
+
+ return this.httpExceptionHandlerService.handleError(
+ exception,
+ response,
+ 416,
+ );
case FileExceptionCode.INTERNAL_SERVER_ERROR:
default:
return this.httpExceptionHandlerService.handleError(
diff --git a/packages/twenty-server/src/engine/core-modules/file/services/file.service.ts b/packages/twenty-server/src/engine/core-modules/file/services/file.service.ts
index f25cbcc01d5..77ae7c58da7 100644
--- a/packages/twenty-server/src/engine/core-modules/file/services/file.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/services/file.service.ts
@@ -4,6 +4,7 @@ import { InjectRepository } from '@nestjs/typeorm';
import { type Readable } from 'stream';
import { FileFolder } from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
import { Like, Repository } from 'typeorm';
import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
@@ -14,10 +15,15 @@ import {
} from 'src/engine/core-modules/file-storage/interfaces/file-storage-exception';
import { FileEntity } from 'src/engine/core-modules/file/entities/file.entity';
import { fileFolderConfigs } from 'src/engine/core-modules/file/interfaces/file-folder.interface';
+import {
+ FileException,
+ FileExceptionCode,
+} from 'src/engine/core-modules/file/file.exception';
import { type FileResponse } from 'src/engine/core-modules/file/types/file-response.type';
import { FILE_STATUS } from 'src/engine/core-modules/file/types/file-status.types';
import { getContentDisposition } from 'src/engine/core-modules/file/utils/get-content-disposition.utils';
import { removeFileFolderFromFileEntityPath } from 'src/engine/core-modules/file/utils/remove-file-folder-from-file-entity-path.utils';
+import { resolveByteRange } from 'src/engine/core-modules/file/utils/resolve-byte-range.utils';
import { JwtWrapperService } from 'src/engine/core-modules/jwt/services/jwt-wrapper.service';
import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';
import { InjectWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/inject-workspace-scoped-repository.decorator';
@@ -150,6 +156,7 @@ export class FileService {
fileId: string;
workspaceId: string;
fileFolder: FileFolder;
+ rangeHeader?: string;
}): Promise<FileResponse | null> {
const file = await this.fileRepository.findOne(params.workspaceId, {
where: {
@@ -184,6 +191,8 @@ export class FileService {
applicationUniversalIdentifier: application.universalIdentifier,
workspaceId: params.workspaceId,
mimeType: file.mimeType,
+ fileSizeInBytes: Number(file.size),
+ rangeHeader: params.rangeHeader,
});
}
@@ -193,12 +202,16 @@ export class FileService {
applicationUniversalIdentifier,
workspaceId,
mimeType,
+ fileSizeInBytes,
+ rangeHeader,
}: {
resourcePath: string;
fileFolder: FileFolder;
applicationUniversalIdentifier: string;
workspaceId: string;
mimeType: string;
+ fileSizeInBytes?: number;
+ rangeHeader?: string;
}): Promise<FileResponse | null> {
const resourceIdentifier = {
resourcePath,
@@ -218,11 +231,42 @@ export class FileService {
fileFolderConfigs[fileFolder].cacheControl ?? undefined,
});
- if (presignedUrl) {
+ if (isDefined(presignedUrl)) {
+ // The storage provider serves presigned downloads directly and handles
+ // Range requests without proxying the file through the server.
return { type: 'redirect', presignedUrl };
}
try {
+ if (isDefined(fileSizeInBytes)) {
+ const resolvedByteRange = resolveByteRange({
+ rangeHeader,
+ fileSizeInBytes,
+ });
+
+ if (resolvedByteRange.type === 'unsatisfiable') {
+ throw new FileException(
+ 'Requested range not satisfiable',
+ FileExceptionCode.RANGE_NOT_SATISFIABLE,
+ { fileSizeInBytes },
+ );
+ }
+
+ if (resolvedByteRange.type === 'partial') {
+ const stream = await this.fileStorageService.readFile({
+ ...resourceIdentifier,
+ byteRange: resolvedByteRange.byteRange,
+ });
+
+ return {
+ type: 'stream',
+ stream,
+ mimeType,
+ contentRange: { ...resolvedByteRange.byteRange, fileSizeInBytes },
+ };
+ }
+ }
+
const stream = await this.fileStorageService.readFile(resourceIdentifier);
return { type: 'stream', stream, mimeType };
diff --git a/packages/twenty-server/src/engine/core-modules/file/types/content-range.type.ts b/packages/twenty-server/src/engine/core-modules/file/types/content-range.type.ts
new file mode 100644
index 00000000000..861772857c4
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/file/types/content-range.type.ts
@@ -0,0 +1,5 @@
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
+
+export type ContentRange = ByteRange & {
+ fileSizeInBytes: number;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/file/types/file-response.type.ts b/packages/twenty-server/src/engine/core-modules/file/types/file-response.type.ts
index a4bd210fecc..c0598c5274c 100644
--- a/packages/twenty-server/src/engine/core-modules/file/types/file-response.type.ts
+++ b/packages/twenty-server/src/engine/core-modules/file/types/file-response.type.ts
@@ -1,5 +1,12 @@
import { type Readable } from 'stream';
+import { type ContentRange } from 'src/engine/core-modules/file/types/content-range.type';
+
export type FileResponse =
| { type: 'redirect'; presignedUrl: string }
- | { type: 'stream'; stream: Readable; mimeType: string };
+ | {
+ type: 'stream';
+ stream: Readable;
+ mimeType: string;
+ contentRange?: ContentRange;
+ };
diff --git a/packages/twenty-server/src/engine/core-modules/file/types/resolved-byte-range.type.ts b/packages/twenty-server/src/engine/core-modules/file/types/resolved-byte-range.type.ts
new file mode 100644
index 00000000000..fa39704df09
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/file/types/resolved-byte-range.type.ts
@@ -0,0 +1,6 @@
+import { type ByteRange } from 'src/engine/core-modules/file-storage/types/byte-range.type';
+
+export type ResolvedByteRange =
+ | { type: 'full' }
+ | { type: 'partial'; byteRange: ByteRange }
+ | { type: 'unsatisfiable' };
diff --git a/packages/twenty-server/src/engine/core-modules/file/utils/__tests__/resolve-byte-range.utils.spec.ts b/packages/twenty-server/src/engine/core-modules/file/utils/__tests__/resolve-byte-range.utils.spec.ts
new file mode 100644
index 00000000000..11791e9159d
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/file/utils/__tests__/resolve-byte-range.utils.spec.ts
@@ -0,0 +1,82 @@
+import { resolveByteRange } from 'src/engine/core-modules/file/utils/resolve-byte-range.utils';
+
+describe('resolveByteRange', () => {
+ it('should return full when no range header is present', () => {
+ expect(
+ resolveByteRange({ rangeHeader: undefined, fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'full' });
+ });
+
+ it.each(['bits=0-10', 'bytes=0-10,20-30', 'bytes=abc-def', 'bytes=-'])(
+ 'should return full for malformed or multi-range header %s',
+ (rangeHeader) => {
+ expect(resolveByteRange({ rangeHeader, fileSizeInBytes: 100 })).toEqual({
+ type: 'full',
+ });
+ },
+ );
+
+ it('should resolve an open-ended range from the start byte', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=0-', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'partial', byteRange: { startByte: 0, endByte: 99 } });
+ });
+
+ it('should resolve a bounded range', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=10-19', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'partial', byteRange: { startByte: 10, endByte: 19 } });
+ });
+
+ it.each(['Bytes=10-19', 'BYTES=10-19'])(
+ 'should match the byte range unit case-insensitively for %s',
+ (rangeHeader) => {
+ expect(resolveByteRange({ rangeHeader, fileSizeInBytes: 100 })).toEqual({
+ type: 'partial',
+ byteRange: { startByte: 10, endByte: 19 },
+ });
+ },
+ );
+
+ it('should clamp the end byte to the file size', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=90-1000', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'partial', byteRange: { startByte: 90, endByte: 99 } });
+ });
+
+ it('should resolve a suffix range to the last bytes of the file', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=-30', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'partial', byteRange: { startByte: 70, endByte: 99 } });
+ });
+
+ it('should clamp a suffix range longer than the file to the whole file', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=-500', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'partial', byteRange: { startByte: 0, endByte: 99 } });
+ });
+
+ it('should return unsatisfiable when the start byte is past the file end', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=100-', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'unsatisfiable' });
+ });
+
+ it('should return unsatisfiable for a zero-length suffix', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=-0', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'unsatisfiable' });
+ });
+
+ it('should return unsatisfiable for any range on an empty file', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=0-', fileSizeInBytes: 0 }),
+ ).toEqual({ type: 'unsatisfiable' });
+ });
+
+ it('should return full when the end byte precedes the start byte', () => {
+ expect(
+ resolveByteRange({ rangeHeader: 'bytes=20-10', fileSizeInBytes: 100 }),
+ ).toEqual({ type: 'full' });
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/file/utils/resolve-byte-range.utils.ts b/packages/twenty-server/src/engine/core-modules/file/utils/resolve-byte-range.utils.ts
new file mode 100644
index 00000000000..5b0e545fdc8
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/file/utils/resolve-byte-range.utils.ts
@@ -0,0 +1,76 @@
+import { isDefined } from 'twenty-shared/utils';
+
+import { type ResolvedByteRange } from 'src/engine/core-modules/file/types/resolved-byte-range.type';
+
+// Single-range subset of RFC 9110 Range requests; malformed or multi-range
+// headers fall back to a full response, which is always a valid answer.
+const SINGLE_BYTE_RANGE_HEADER_PATTERN = /^bytes=(\d*)-(\d*)$/i;
+
+export const resolveByteRange = ({
+ rangeHeader,
+ fileSizeInBytes,
+}: {
+ rangeHeader: string | undefined;
+ fileSizeInBytes: number;
+}): ResolvedByteRange => {
+ if (!isDefined(rangeHeader)) {
+ return { type: 'full' };
+ }
+
+ const rangeHeaderMatch = rangeHeader.match(SINGLE_BYTE_RANGE_HEADER_PATTERN);
+
+ if (!isDefined(rangeHeaderMatch)) {
+ return { type: 'full' };
+ }
+
+ const [, startPart, endPart] = rangeHeaderMatch;
+
+ if (startPart === '' && endPart === '') {
+ return { type: 'full' };
+ }
+
+ const lastByteIndex = fileSizeInBytes - 1;
+
+ if (startPart === '') {
+ const suffixLength = Number(endPart);
+
+ if (suffixLength === 0 || fileSizeInBytes === 0) {
+ return { type: 'unsatisfiable' };
+ }
+
+ return {
+ type: 'partial',
+ byteRange: {
+ startByte: Math.max(fileSizeInBytes - suffixLength, 0),
+ endByte: lastByteIndex,
+ },
+ };
+ }
+
+ const startByte = Number(startPart);
+
+ if (startByte > lastByteIndex) {
+ return { type: 'unsatisfiable' };
+ }
+
+ if (endPart === '') {
+ return {
+ type: 'partial',
+ byteRange: { startByte, endByte: lastByteIndex },
+ };
+ }
+
+ const requestedEndByte = Number(endPart);
+
+ if (requestedEndByte < startByte) {
+ return { type: 'full' };
+ }
+
+ return {
+ type: 'partial',
+ byteRange: {
+ startByte,
+ endByte: Math.min(requestedEndByte, lastByteIndex),
+ },
+ };
+};
diff --git a/packages/twenty-server/test/integration/metadata/suites/file/successful-file-by-id-download.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/file/successful-file-by-id-download.integration-spec.ts
index f9459b7f658..157a2163f2b 100644
--- a/packages/twenty-server/test/integration/metadata/suites/file/successful-file-by-id-download.integration-spec.ts
+++ b/packages/twenty-server/test/integration/metadata/suites/file/successful-file-by-id-download.integration-spec.ts
@@ -48,4 +48,89 @@ describe('File-by-id controller download should succeed', () => {
expect(body.equals(ONE_BY_ONE_TRANSPARENT_PNG)).toBe(true);
}, 30000);
+
+ it('should stream a requested byte range using the persisted file size', async () => {
+ jest.useRealTimers();
+
+ const response = await request(global.app.getHttpServer())
+ .get(extractPathAndQueryFromUrl(signedUrl))
+ .set('Range', 'bytes=0-9')
+ .buffer(true)
+ .parse((res, callback) => {
+ const chunks: Buffer[] = [];
+
+ res.on('data', (chunk) => chunks.push(chunk));
+ res.on('end', () => callback(null, Buffer.concat(chunks)));
+ });
+
+ jest.useFakeTimers();
+
+ expect(response.status).toBe(206);
+ expect(response.headers['accept-ranges']).toBe('bytes');
+ expect(response.headers['content-range']).toBe(
+ `bytes 0-9/${ONE_BY_ONE_TRANSPARENT_PNG.length}`,
+ );
+ expect(response.headers['content-length']).toBe('10');
+ expect(response.body).toEqual(ONE_BY_ONE_TRANSPARENT_PNG.subarray(0, 10));
+ }, 30000);
+
+ it('should stream from the requested offset to the end for an open-ended range', async () => {
+ jest.useRealTimers();
+
+ const response = await request(global.app.getHttpServer())
+ .get(extractPathAndQueryFromUrl(signedUrl))
+ .set('Range', 'bytes=10-')
+ .buffer(true)
+ .parse((res, callback) => {
+ const chunks: Buffer[] = [];
+
+ res.on('data', (chunk) => chunks.push(chunk));
+ res.on('end', () => callback(null, Buffer.concat(chunks)));
+ });
+
+ jest.useFakeTimers();
+
+ expect(response.status).toBe(206);
+ expect(response.headers['content-range']).toBe(
+ `bytes 10-${ONE_BY_ONE_TRANSPARENT_PNG.length - 1}/${ONE_BY_ONE_TRANSPARENT_PNG.length}`,
+ );
+ expect(response.body).toEqual(ONE_BY_ONE_TRANSPARENT_PNG.subarray(10));
+ }, 30000);
+
+ it('should ignore a malformed range header and stream the full file', async () => {
+ jest.useRealTimers();
+
+ const response = await request(global.app.getHttpServer())
+ .get(extractPathAndQueryFromUrl(signedUrl))
+ .set('Range', 'bytes=abc')
+ .buffer(true)
+ .parse((res, callback) => {
+ const chunks: Buffer[] = [];
+
+ res.on('data', (chunk) => chunks.push(chunk));
+ res.on('end', () => callback(null, Buffer.concat(chunks)));
+ });
+
+ jest.useFakeTimers();
+
+ expect(response.status).toBe(200);
+ expect((response.body as Buffer).equals(ONE_BY_ONE_TRANSPARENT_PNG)).toBe(
+ true,
+ );
+ }, 30000);
+
+ it('should reject a byte range beyond the persisted file size', async () => {
+ jest.useRealTimers();
+
+ const response = await request(global.app.getHttpServer())
+ .get(extractPathAndQueryFromUrl(signedUrl))
+ .set('Range', `bytes=${ONE_BY_ONE_TRANSPARENT_PNG.length}-`);
+
+ jest.useFakeTimers();
+
+ expect(response.status).toBe(416);
+ expect(response.headers['content-range']).toBe(
+ `bytes */${ONE_BY_ONE_TRANSPARENT_PNG.length}`,
+ );
+ }, 30000);
});