feat: add gzip content encoding option for file operations (#1252)

## Summary

- Adds optional `gzip` parameter to sandbox file read/write operations
across JS and Python SDKs
- Uploads are gzip-compressed via `CompressionStream` (JS) /
`gzip.compress` (Python) when enabled, downloads request
`Accept-Encoding: gzip`
- Only applies to the octet-stream upload path (envd >= 0.5.7), so older
envd versions are unaffected
- Includes tests for both SDKs covering write+read with gzip, write gzip
+ read plain, multi-file writes, and byte format reads

## Test plan

- [ ] Run JS SDK content encoding tests (`contentEncoding.test.ts`)
- [ ] Run Python async/sync content encoding tests
(`test_content_encoding.py`)
- [ ] Integration test with envd backend supporting `Content-Encoding:
gzip`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: mishushakov

.changeset/gzip-file-upload.md

@@ -0,0 +1,6 @@
+---
+'@e2b/python-sdk': patch
+'e2b': patch
+---
+
+added gzip support for sandbox file upload/download

packages/js-sdk/src/index.ts

@@ -25,7 +25,13 @@ export type { Logger } from './logs'
 export { getSignature } from './sandbox/signature'
 
 export { FileType } from './sandbox/filesystem'
-export type { WriteInfo, EntryInfo, Filesystem } from './sandbox/filesystem'
+export type {
+  WriteInfo,
+  EntryInfo,
+  Filesystem,
+  FilesystemWriteOpts,
+  FilesystemReadOpts,
+} from './sandbox/filesystem'
 export { FilesystemEventType } from './sandbox/filesystem/watchHandle'
 export type {
   FilesystemEvent,

packages/js-sdk/src/sandbox/filesystem/index.ts

@@ -37,7 +37,7 @@ import {
   InvalidArgumentError,
   TemplateError,
 } from '../../errors'
-import { toBlob } from '../../utils'
+import { toBlob, toUploadBody } from '../../utils'
 
 const FILESYSTEM_HTTP_ERROR_MAP: Record<number, (message: string) => Error> = {
   404: (message: string) => new FileNotFoundError(message),
@@ -164,6 +164,26 @@ export interface FilesystemRequestOpts
   user?: Username
 }
 
+/**
+ * Options for writing files to the sandbox filesystem.
+ */
+export interface FilesystemWriteOpts extends FilesystemRequestOpts {
+  /**
+   * When true, the upload will be gzip-compressed.
+   */
+  gzip?: boolean
+}
+
+/**
+ * Options for reading files from the sandbox filesystem.
+ */
+export interface FilesystemReadOpts extends FilesystemRequestOpts {
+  /**
+   * When true, the download will request gzip-encoded responses.
+   */
+  gzip?: boolean
+}
+
 export interface FilesystemListOpts extends FilesystemRequestOpts {
   /**
    * Depth of the directory to list.
@@ -222,7 +242,7 @@ export class Filesystem {
    */
   async read(
     path: string,
-    opts?: FilesystemRequestOpts & { format?: 'text' }
+    opts?: FilesystemReadOpts & { format?: 'text' }
   ): Promise<string>
   /**
    * Read file content as a `Uint8Array`.
@@ -237,7 +257,7 @@ export class Filesystem {
    */
   async read(
     path: string,
-    opts?: FilesystemRequestOpts & { format: 'bytes' }
+    opts?: FilesystemReadOpts & { format: 'bytes' }
   ): Promise<Uint8Array>
   /**
    * Read file content as a `Blob`.
@@ -252,7 +272,7 @@ export class Filesystem {
    */
   async read(
     path: string,
-    opts?: FilesystemRequestOpts & { format: 'blob' }
+    opts?: FilesystemReadOpts & { format: 'blob' }
   ): Promise<Blob>
   /**
    * Read file content as a `ReadableStream`.
@@ -267,12 +287,12 @@ export class Filesystem {
    */
   async read(
     path: string,
-    opts?: FilesystemRequestOpts & { format: 'stream' }
+    opts?: FilesystemReadOpts & { format: 'stream' }
   ): Promise<ReadableStream<Uint8Array>>
   async read(
     path: string,
-    opts?: FilesystemRequestOpts & {
-      format?: 'text' | 'stream' | 'bytes' | 'blob'
+    opts?: FilesystemReadOpts & {
+      format?: 'text' | 'bytes' | 'blob' | 'stream'
     }
   ): Promise<unknown> {
     const format = opts?.format ?? 'text'
@@ -285,6 +305,11 @@ export class Filesystem {
       user = defaultUsername
     }
 
+    const headers: Record<string, string> = {}
+    if (opts?.gzip) {
+      headers['Accept-Encoding'] = 'gzip'
+    }
+
     const res = await this.envdApi.api.GET('/files', {
       params: {
         query: {
@@ -294,6 +319,7 @@ export class Filesystem {
       },
       parseAs: format === 'bytes' ? 'arrayBuffer' : format,
       signal: this.connectionConfig.getSignal(opts?.requestTimeoutMs),
+      headers,
     })
 
     const err = await handleFilesystemEnvdApiError(res)
@@ -332,11 +358,11 @@ export class Filesystem {
   async write(
     path: string,
     data: string | ArrayBuffer | Blob | ReadableStream,
-    opts?: FilesystemRequestOpts
+    opts?: FilesystemWriteOpts
   ): Promise<WriteInfo>
   async write(
     files: WriteEntry[],
-    opts?: FilesystemRequestOpts
+    opts?: FilesystemWriteOpts
   ): Promise<WriteInfo[]>
   async write(
     pathOrFiles: string | WriteEntry[],
@@ -345,8 +371,8 @@ export class Filesystem {
       | ArrayBuffer
       | Blob
       | ReadableStream
-      | FilesystemRequestOpts,
-    opts?: FilesystemRequestOpts
+      | FilesystemWriteOpts,
+    opts?: FilesystemWriteOpts
   ): Promise<WriteInfo | WriteInfo[]> {
     if (typeof pathOrFiles !== 'string' && !Array.isArray(pathOrFiles)) {
       throw new Error('Path or files are required')
@@ -362,7 +388,7 @@ export class Filesystem {
       typeof pathOrFiles === 'string'
         ? {
             path: pathOrFiles,
-            writeOpts: opts as FilesystemRequestOpts,
+            writeOpts: opts as FilesystemWriteOpts,
             writeFiles: [
               {
                 data: dataOrOpts as
@@ -375,7 +401,7 @@ export class Filesystem {
           }
         : {
             path: undefined,
-            writeOpts: dataOrOpts as FilesystemRequestOpts,
+            writeOpts: dataOrOpts as FilesystemWriteOpts,
             writeFiles: pathOrFiles as WriteEntry[],
           }
 
@@ -394,11 +420,20 @@ export class Filesystem {
 
     const results: WriteInfo[] = []
 
+    const useGzip = writeOpts?.gzip === true
+
     if (useOctetStream) {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/octet-stream',
+      }
+      if (useGzip) {
+        headers['Content-Encoding'] = 'gzip'
+      }
+
       const uploadResults = await Promise.all(
         writeFiles.map(async (file) => {
           const filePath = path ?? (file as WriteEntry).path
-          const blob = await toBlob(file.data)
+          const body = await toUploadBody(file.data, useGzip)
 
           const res = await this.envdApi.api.POST('/files', {
             params: {
@@ -407,10 +442,8 @@ export class Filesystem {
                 username: user,
               },
             },
-            bodySerializer: () => blob,
-            headers: {
-              'Content-Type': 'application/octet-stream',
-            },
+            bodySerializer: () => body,
+            headers,
             signal: this.connectionConfig.getSignal(
               writeOpts?.requestTimeoutMs
             ),
@@ -491,7 +524,7 @@ export class Filesystem {
    */
   async writeFiles(
     files: WriteEntry[],
-    opts?: FilesystemRequestOpts
+    opts?: FilesystemWriteOpts
   ): Promise<WriteInfo[]> {
     return this.write(files, opts) as Promise<WriteInfo[]>
   }

packages/js-sdk/src/utils.ts

@@ -124,3 +124,25 @@ export function toBlob(
   // ReadableStream - must consume to get Blob
   return new Response(data).blob()
 }
+
+/**
+ * Prepare data for upload as a BodyInit, optionally gzip-compressed.
+ * When gzip is enabled, compresses the data and returns a Blob.
+ */
+export async function toUploadBody(
+  data: string | ArrayBuffer | Blob | ReadableStream,
+  gzip?: boolean
+): Promise<BodyInit> {
+  if (gzip) {
+    const stream =
+      data instanceof ReadableStream
+        ? data
+        : data instanceof Blob
+          ? data.stream()
+          : new Blob([data]).stream()
+    const compressed = stream.pipeThrough(new CompressionStream('gzip'))
+    return new Response(compressed).blob()
+  }
+
+  return toBlob(data)
+}

packages/js-sdk/tests/sandbox/files/contentEncoding.test.ts

@@ -0,0 +1,94 @@
+import { assert } from 'vitest'
+
+import { WriteEntry } from '../../../src/sandbox/filesystem'
+import { isDebug, sandboxTest } from '../../setup.js'
+
+sandboxTest(
+  'write and read file with gzip content encoding',
+  async ({ sandbox }) => {
+    const filename = 'test_gzip_write.txt'
+    const content = 'This is a test file with gzip encoding.'
+
+    const info = await sandbox.files.write(filename, content, {
+      gzip: true,
+    })
+    assert.equal(info.name, filename)
+    assert.equal(info.type, 'file')
+    assert.equal(info.path, `/home/user/${filename}`)
+
+    const readContent = await sandbox.files.read(filename, {
+      gzip: true,
+    })
+    assert.equal(readContent, content)
+
+    if (isDebug) {
+      await sandbox.files.remove(filename)
+    }
+  }
+)
+
+sandboxTest(
+  'write with gzip and read without encoding',
+  async ({ sandbox }) => {
+    const filename = 'test_gzip_write_plain_read.txt'
+    const content = 'Written with gzip, read without.'
+
+    await sandbox.files.write(filename, content, {
+      gzip: true,
+    })
+
+    const readContent = await sandbox.files.read(filename)
+    assert.equal(readContent, content)
+
+    if (isDebug) {
+      await sandbox.files.remove(filename)
+    }
+  }
+)
+
+sandboxTest('writeFiles with gzip content encoding', async ({ sandbox }) => {
+  const files: WriteEntry[] = [
+    { path: 'gzip_multi_1.txt', data: 'File 1 content' },
+    { path: 'gzip_multi_2.txt', data: 'File 2 content' },
+    { path: 'gzip_multi_3.txt', data: 'File 3 content' },
+  ]
+
+  const infos = await sandbox.files.writeFiles(files, {
+    gzip: true,
+  })
+
+  assert.equal(infos.length, files.length)
+
+  for (let i = 0; i < files.length; i++) {
+    const readContent = await sandbox.files.read(files[i].path)
+    assert.equal(readContent, files[i].data)
+  }
+
+  if (isDebug) {
+    for (const file of files) {
+      await sandbox.files.remove(file.path)
+    }
+  }
+})
+
+sandboxTest(
+  'read file as bytes with gzip content encoding',
+  async ({ sandbox }) => {
+    const filename = 'test_gzip_bytes.txt'
+    const content = 'Binary content with gzip.'
+
+    await sandbox.files.write(filename, content)
+
+    const readBytes = await sandbox.files.read(filename, {
+      format: 'bytes',
+      gzip: true,
+    })
+    assert.instanceOf(readBytes, Uint8Array)
+    const decoded = new TextDecoder().decode(readBytes)
+    assert.equal(decoded, content)
+
+    if (isDebug) {
+      await sandbox.files.remove(filename)
+    }
+  }
+)

packages/python-sdk/e2b/sandbox/filesystem/filesystem.py

@@ -1,9 +1,12 @@
+import gzip
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
+from io import IOBase, TextIOBase
 from typing import IO, Optional, Union, TypedDict
 
 from e2b.envd.filesystem import filesystem_pb2
+from e2b.exceptions import InvalidArgumentException
 
 
 class FileType(Enum):
@@ -92,3 +95,22 @@ class WriteEntry(TypedDict):
 
     path: str
     data: Union[str, bytes, IO]
+
+
+def to_upload_body(
+    data: Union[str, bytes, IO],
+    use_gzip: bool = False,
+) -> bytes:
+    """Prepare file data for upload, optionally gzip-compressed."""
+    if isinstance(data, str):
+        raw = data.encode("utf-8")
+    elif isinstance(data, bytes):
+        raw = data
+    elif isinstance(data, TextIOBase):
+        raw = data.read().encode("utf-8")
+    elif isinstance(data, IOBase):
+        raw = data.read()
+    else:
+        raise InvalidArgumentException(f"Unsupported data type: {type(data)}")
+
+    return gzip.compress(raw) if use_gzip else raw