Add optional depth parameter to SDK file listing methods.

packages/js-sdk/src/envd/filesystem/filesystem_pb.ts

@@ -10,7 +10,7 @@ import type { Message } from "@bufbuild/protobuf";
  * Describes the file filesystem/filesystem.proto.
  */
 export const file_filesystem_filesystem: GenFile = /*@__PURE__*/
-  fileDesc("ChtmaWxlc3lzdGVtL2ZpbGVzeXN0ZW0ucHJvdG8SCmZpbGVzeXN0ZW0iMgoLTW92ZVJlcXVlc3QSDgoGc291cmNlGAEgASgJEhMKC2Rlc3RpbmF0aW9uGAIgASgJIjQKDE1vdmVSZXNwb25zZRIkCgVlbnRyeRgBIAEoCzIVLmZpbGVzeXN0ZW0uRW50cnlJbmZvIh4KDk1ha2VEaXJSZXF1ZXN0EgwKBHBhdGgYASABKAkiNwoPTWFrZURpclJlc3BvbnNlEiQKBWVudHJ5GAEgASgLMhUuZmlsZXN5c3RlbS5FbnRyeUluZm8iHQoNUmVtb3ZlUmVxdWVzdBIMCgRwYXRoGAEgASgJIhAKDlJlbW92ZVJlc3BvbnNlIhsKC1N0YXRSZXF1ZXN0EgwKBHBhdGgYASABKAkiNAoMU3RhdFJlc3BvbnNlEiQKBWVudHJ5GAEgASgLMhUuZmlsZXN5c3RlbS5FbnRyeUluZm8iSwoJRW50cnlJbmZvEgwKBG5hbWUYASABKAkSIgoEdHlwZRgCIAEoDjIULmZpbGVzeXN0ZW0uRmlsZVR5cGUSDAoEcGF0aBgDIAEoCSIeCg5MaXN0RGlyUmVxdWVzdBIMCgRwYXRoGAEgASgJIjkKD0xpc3REaXJSZXNwb25zZRImCgdlbnRyaWVzGAEgAygLMhUuZmlsZXN5c3RlbS5FbnRyeUluZm8iMgoPV2F0Y2hEaXJSZXF1ZXN0EgwKBHBhdGgYASABKAkSEQoJcmVjdXJzaXZlGAIgASgIIkQKD0ZpbGVzeXN0ZW1FdmVudBIMCgRuYW1lGAEgASgJEiMKBHR5cGUYAiABKA4yFS5maWxlc3lzdGVtLkV2ZW50VHlwZSLgAQoQV2F0Y2hEaXJSZXNwb25zZRI4CgVzdGFydBgBIAEoCzInLmZpbGVzeXN0ZW0uV2F0Y2hEaXJSZXNwb25zZS5TdGFydEV2ZW50SAASMQoKZmlsZXN5c3RlbRgCIAEoCzIbLmZpbGVzeXN0ZW0uRmlsZXN5c3RlbUV2ZW50SAASOwoJa2VlcGFsaXZlGAMgASgLMiYuZmlsZXN5c3RlbS5XYXRjaERpclJlc3BvbnNlLktlZXBBbGl2ZUgAGgwKClN0YXJ0RXZlbnQaCwoJS2VlcEFsaXZlQgcKBWV2ZW50IjcKFENyZWF0ZVdhdGNoZXJSZXF1ZXN0EgwKBHBhdGgYASABKAkSEQoJcmVjdXJzaXZlGAIgASgIIisKFUNyZWF0ZVdhdGNoZXJSZXNwb25zZRISCgp3YXRjaGVyX2lkGAEgASgJIi0KF0dldFdhdGNoZXJFdmVudHNSZXF1ZXN0EhIKCndhdGNoZXJfaWQYASABKAkiRwoYR2V0V2F0Y2hlckV2ZW50c1Jlc3BvbnNlEisKBmV2ZW50cxgBIAMoCzIbLmZpbGVzeXN0ZW0uRmlsZXN5c3RlbUV2ZW50IioKFFJlbW92ZVdhdGNoZXJSZXF1ZXN0EhIKCndhdGNoZXJfaWQYASABKAkiFwoVUmVtb3ZlV2F0Y2hlclJlc3BvbnNlKlIKCEZpbGVUeXBlEhkKFUZJTEVfVFlQRV9VTlNQRUNJRklFRBAAEhIKDkZJTEVfVFlQRV9GSUxFEAESFwoTRklMRV9UWVBFX0RJUkVDVE9SWRACKpgBCglFdmVudFR5cGUSGgoWRVZFTlRfVFlQRV9VTlNQRUNJRklFRBAAEhUKEUVWRU5UX1RZUEVfQ1JFQVRFEAESFAoQRVZFTlRfVFlQRV9XUklURRACEhUKEUVWRU5UX1RZUEVfUkVNT1ZFEAMSFQoRRVZFTlRfVFlQRV9SRU5BTUUQBBIUChBFVkVOVF9UWVBFX0NITU9EEAUynwUKCkZpbGVzeXN0ZW0SOQoEU3RhdBIXLmZpbGVzeXN0ZW0uU3RhdFJlcXVlc3QaGC5maWxlc3lzdGVtLlN0YXRSZXNwb25zZRJCCgdNYWtlRGlyEhouZmlsZXN5c3RlbS5NYWtlRGlyUmVxdWVzdBobLmZpbGVzeXN0ZW0uTWFrZURpclJlc3BvbnNlEjkKBE1vdmUSFy5maWxlc3lzdGVtLk1vdmVSZXF1ZXN0GhguZmlsZXN5c3RlbS5Nb3ZlUmVzcG9uc2USQgoHTGlzdERpchIaLmZpbGVzeXN0ZW0uTGlzdERpclJlcXVlc3QaGy5maWxlc3lzdGVtLkxpc3REaXJSZXNwb25zZRI/CgZSZW1vdmUSGS5maWxlc3lzdGVtLlJlbW92ZVJlcXVlc3QaGi5maWxlc3lzdGVtLlJlbW92ZVJlc3BvbnNlEkcKCFdhdGNoRGlyEhsuZmlsZXN5c3RlbS5XYXRjaERpclJlcXVlc3QaHC5maWxlc3lzdGVtLldhdGNoRGlyUmVzcG9uc2UwARJUCg1DcmVhdGVXYXRjaGVyEiAuZmlsZXN5c3RlbS5DcmVhdGVXYXRjaGVyUmVxdWVzdBohLmZpbGVzeXN0ZW0uQ3JlYXRlV2F0Y2hlclJlc3BvbnNlEl0KEEdldFdhdGNoZXJFdmVudHMSIy5maWxlc3lzdGVtLkdldFdhdGNoZXJFdmVudHNSZXF1ZXN0GiQuZmlsZXN5c3RlbS5HZXRXYXRjaGVyRXZlbnRzUmVzcG9uc2USVAoNUmVtb3ZlV2F0Y2hlchIgLmZpbGVzeXN0ZW0uUmVtb3ZlV2F0Y2hlclJlcXVlc3QaIS5maWxlc3lzdGVtLlJlbW92ZVdhdGNoZXJSZXNwb25zZUJpCg5jb20uZmlsZXN5c3RlbUIPRmlsZXN5c3RlbVByb3RvUAGiAgNGWFiqAgpGaWxlc3lzdGVtygIKRmlsZXN5c3RlbeICFkZpbGVzeXN0ZW1cR1BCTWV0YWRhdGHqAgpGaWxlc3lzdGVtYgZwcm90bzM");
+  fileDesc("ChtmaWxlc3lzdGVtL2ZpbGVzeXN0ZW0ucHJvdG8SCmZpbGVzeXN0ZW0iMgoLTW92ZVJlcXVlc3QSDgoGc291cmNlGAEgASgJEhMKC2Rlc3RpbmF0aW9uGAIgASgJIjQKDE1vdmVSZXNwb25zZRIkCgVlbnRyeRgBIAEoCzIVLmZpbGVzeXN0ZW0uRW50cnlJbmZvIh4KDk1ha2VEaXJSZXF1ZXN0EgwKBHBhdGgYASABKAkiNwoPTWFrZURpclJlc3BvbnNlEiQKBWVudHJ5GAEgASgLMhUuZmlsZXN5c3RlbS5FbnRyeUluZm8iHQoNUmVtb3ZlUmVxdWVzdBIMCgRwYXRoGAEgASgJIhAKDlJlbW92ZVJlc3BvbnNlIhsKC1N0YXRSZXF1ZXN0EgwKBHBhdGgYASABKAkiNAoMU3RhdFJlc3BvbnNlEiQKBWVudHJ5GAEgASgLMhUuZmlsZXN5c3RlbS5FbnRyeUluZm8iSwoJRW50cnlJbmZvEgwKBG5hbWUYASABKAkSIgoEdHlwZRgCIAEoDjIULmZpbGVzeXN0ZW0uRmlsZVR5cGUSDAoEcGF0aBgDIAEoCSItCg5MaXN0RGlyUmVxdWVzdBIMCgRwYXRoGAEgASgJEg0KBWRlcHRoGAIgASgNIjkKD0xpc3REaXJSZXNwb25zZRImCgdlbnRyaWVzGAEgAygLMhUuZmlsZXN5c3RlbS5FbnRyeUluZm8iMgoPV2F0Y2hEaXJSZXF1ZXN0EgwKBHBhdGgYASABKAkSEQoJcmVjdXJzaXZlGAIgASgIIkQKD0ZpbGVzeXN0ZW1FdmVudBIMCgRuYW1lGAEgASgJEiMKBHR5cGUYAiABKA4yFS5maWxlc3lzdGVtLkV2ZW50VHlwZSLgAQoQV2F0Y2hEaXJSZXNwb25zZRI4CgVzdGFydBgBIAEoCzInLmZpbGVzeXN0ZW0uV2F0Y2hEaXJSZXNwb25zZS5TdGFydEV2ZW50SAASMQoKZmlsZXN5c3RlbRgCIAEoCzIbLmZpbGVzeXN0ZW0uRmlsZXN5c3RlbUV2ZW50SAASOwoJa2VlcGFsaXZlGAMgASgLMiYuZmlsZXN5c3RlbS5XYXRjaERpclJlc3BvbnNlLktlZXBBbGl2ZUgAGgwKClN0YXJ0RXZlbnQaCwoJS2VlcEFsaXZlQgcKBWV2ZW50IjcKFENyZWF0ZVdhdGNoZXJSZXF1ZXN0EgwKBHBhdGgYASABKAkSEQoJcmVjdXJzaXZlGAIgASgIIisKFUNyZWF0ZVdhdGNoZXJSZXNwb25zZRISCgp3YXRjaGVyX2lkGAEgASgJIi0KF0dldFdhdGNoZXJFdmVudHNSZXF1ZXN0EhIKCndhdGNoZXJfaWQYASABKAkiRwoYR2V0V2F0Y2hlckV2ZW50c1Jlc3BvbnNlEisKBmV2ZW50cxgBIAMoCzIbLmZpbGVzeXN0ZW0uRmlsZXN5c3RlbUV2ZW50IioKFFJlbW92ZVdhdGNoZXJSZXF1ZXN0EhIKCndhdGNoZXJfaWQYASABKAkiFwoVUmVtb3ZlV2F0Y2hlclJlc3BvbnNlKlIKCEZpbGVUeXBlEhkKFUZJTEVfVFlQRV9VTlNQRUNJRklFRBAAEhIKDkZJTEVfVFlQRV9GSUxFEAESFwoTRklMRV9UWVBFX0RJUkVDVE9SWRACKpgBCglFdmVudFR5cGUSGgoWRVZFTlRfVFlQRV9VTlNQRUNJRklFRBAAEhUKEUVWRU5UX1RZUEVfQ1JFQVRFEAESFAoQRVZFTlRfVFlQRV9XUklURRACEhUKEUVWRU5UX1RZUEVfUkVNT1ZFEAMSFQoRRVZFTlRfVFlQRV9SRU5BTUUQBBIUChBFVkVOVF9UWVBFX0NITU9EEAUynwUKCkZpbGVzeXN0ZW0SOQoEU3RhdBIXLmZpbGVzeXN0ZW0uU3RhdFJlcXVlc3QaGC5maWxlc3lzdGVtLlN0YXRSZXNwb25zZRJCCgdNYWtlRGlyEhouZmlsZXN5c3RlbS5NYWtlRGlyUmVxdWVzdBobLmZpbGVzeXN0ZW0uTWFrZURpclJlc3BvbnNlEjkKBE1vdmUSFy5maWxlc3lzdGVtLk1vdmVSZXF1ZXN0GhguZmlsZXN5c3RlbS5Nb3ZlUmVzcG9uc2USQgoHTGlzdERpchIaLmZpbGVzeXN0ZW0uTGlzdERpclJlcXVlc3QaGy5maWxlc3lzdGVtLkxpc3REaXJSZXNwb25zZRI/CgZSZW1vdmUSGS5maWxlc3lzdGVtLlJlbW92ZVJlcXVlc3QaGi5maWxlc3lzdGVtLlJlbW92ZVJlc3BvbnNlEkcKCFdhdGNoRGlyEhsuZmlsZXN5c3RlbS5XYXRjaERpclJlcXVlc3QaHC5maWxlc3lzdGVtLldhdGNoRGlyUmVzcG9uc2UwARJUCg1DcmVhdGVXYXRjaGVyEiAuZmlsZXN5c3RlbS5DcmVhdGVXYXRjaGVyUmVxdWVzdBohLmZpbGVzeXN0ZW0uQ3JlYXRlV2F0Y2hlclJlc3BvbnNlEl0KEEdldFdhdGNoZXJFdmVudHMSIy5maWxlc3lzdGVtLkdldFdhdGNoZXJFdmVudHNSZXF1ZXN0GiQuZmlsZXN5c3RlbS5HZXRXYXRjaGVyRXZlbnRzUmVzcG9uc2USVAoNUmVtb3ZlV2F0Y2hlchIgLmZpbGVzeXN0ZW0uUmVtb3ZlV2F0Y2hlclJlcXVlc3QaIS5maWxlc3lzdGVtLlJlbW92ZVdhdGNoZXJSZXNwb25zZUJpCg5jb20uZmlsZXN5c3RlbUIPRmlsZXN5c3RlbVByb3RvUAGiAgNGWFiqAgpGaWxlc3lzdGVtygIKRmlsZXN5c3RlbeICFkZpbGVzeXN0ZW1cR1BCTWV0YWRhdGHqAgpGaWxlc3lzdGVtYgZwcm90bzM");
 
 /**
  * @generated from message filesystem.MoveRequest
@@ -184,6 +184,11 @@ export type ListDirRequest = Message<"filesystem.ListDirRequest"> & {
    * @generated from field: string path = 1;
    */
   path: string;
+
+  /**
+   * @generated from field: uint32 depth = 2;
+   */
+  depth: number;
 };
 
 /**

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

@@ -26,7 +26,7 @@ import {
 import { FilesystemEvent, WatchHandle } from './watchHandle'
 
 import { compareVersions } from 'compare-versions'
-import { TemplateError } from '../../errors'
+import { InvalidArgumentError, TemplateError } from '../../errors'
 import { ENVD_VERSION_RECURSIVE_WATCH } from '../../envd/versions'
 
 /**
@@ -87,6 +87,13 @@ export interface FilesystemRequestOpts
   user?: Username
 }
 
+export interface FilesystemListOpts extends FilesystemRequestOpts {
+  /**
+   * Depth of the directory to list.
+   */
+  depth?: number
+}
+
 /**
  * Options for watching a directory.
  */
@@ -339,10 +346,17 @@ export class Filesystem {
    *
    * @returns list of entries in the sandbox filesystem directory.
    */
-  async list(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo[]> {
+  async list(path: string, opts?: FilesystemListOpts): Promise<EntryInfo[]> {
+    if (typeof opts?.depth === 'number' && opts.depth < 1) {
+      throw new InvalidArgumentError('depth should be at least one')
+    }
+
     try {
       const res = await this.rpc.listDir(
-        { path },
+        {
+          path,
+          depth: opts?.depth ?? 1,
+        },
         {
           headers: authenticationHeader(opts?.user),
           signal: this.connectionConfig.getSignal(opts?.requestTimeoutMs),

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

@@ -1,23 +1,121 @@
-import { assert } from 'vitest'
+import { assert, onTestFinished } from 'vitest'
 
-import { sandboxTest } from '../../setup.js'
+import { sandboxTest, wait } from '../../setup.js'
+
+const parentDirName = 'test_directory'
 
 sandboxTest('list directory', async ({ sandbox }) => {
-  const dirName = 'test_directory4'
+  const homeDirName = '/home/user'
+  await sandbox.files.makeDir(parentDirName)
+  await sandbox.files.makeDir(`${parentDirName}/subdir1`)
+  await sandbox.files.makeDir(`${parentDirName}/subdir2`)
+  await sandbox.files.makeDir(`${parentDirName}/subdir1/subdir1_1`)
+  await sandbox.files.makeDir(`${parentDirName}/subdir1/subdir1_2`)
+  await sandbox.files.makeDir(`${parentDirName}/subdir2/subdir2_1`)
+  await sandbox.files.makeDir(`${parentDirName}/subdir2/subdir2_2`)
+  await sandbox.files.write(`${parentDirName}/file1.txt`, 'Hello, world!')
 
-  await sandbox.files.makeDir(dirName)
+  const testCases = [
+    {
+      test_name: 'default depth (1)',
+      depth: undefined,
+      expectedLen: 3,
+      expectedFileNames: ['file1.txt', 'subdir1', 'subdir2'],
+      expectedFileTypes: ['file', 'dir', 'dir'],
+      expectedFilePaths: [
+        `${homeDirName}/${parentDirName}/file1.txt`,
+        `${homeDirName}/${parentDirName}/subdir1`,
+        `${homeDirName}/${parentDirName}/subdir2`,
+      ],
+    },
+    {
+      test_name: 'explicit depth 1',
+      depth: 1,
+      expectedLen: 3,
+      expectedFileNames: ['file1.txt', 'subdir1', 'subdir2'],
+      expectedFileTypes: ['file', 'dir', 'dir'],
+      expectedFilePaths: [
+        `${homeDirName}/${parentDirName}/file1.txt`,
+        `${homeDirName}/${parentDirName}/subdir1`,
+        `${homeDirName}/${parentDirName}/subdir2`,
+      ],
+    },
+    {
+      test_name: 'explicit depth 2',
+      depth: 2,
+      expectedLen: 7,
+      expectedFileTypes: ['file', 'dir', 'dir', 'dir', 'dir', 'dir', 'dir'],
+      expectedFileNames: [
+        'file1.txt',
+        'subdir1',
+        'subdir1_1',
+        'subdir1_2',
+        'subdir2',
+        'subdir2_1',
+        'subdir2_2',
+      ],
+      expectedFilePaths: [
+        `${homeDirName}/${parentDirName}/file1.txt`,
+        `${homeDirName}/${parentDirName}/subdir1`,
+        `${homeDirName}/${parentDirName}/subdir1/subdir1_1`,
+        `${homeDirName}/${parentDirName}/subdir1/subdir1_2`,
+        `${homeDirName}/${parentDirName}/subdir2`,
+        `${homeDirName}/${parentDirName}/subdir2/subdir2_1`,
+        `${homeDirName}/${parentDirName}/subdir2/subdir2_2`,
+      ],
+    },
+    {
+      test_name: 'explicit depth 3 (should be the same as depth 2)',
+      depth: 3,
+      expectedLen: 7,
+      expectedFileTypes: ['file', 'dir', 'dir', 'dir', 'dir', 'dir', 'dir'],
+      expectedFileNames: [
+        'file1.txt',
+        'subdir1',
+        'subdir1_1',
+        'subdir1_2',
+        'subdir2',
+        'subdir2_1',
+        'subdir2_2',
+      ],
+      expectedFilePaths: [
+        `${homeDirName}/${parentDirName}/file1.txt`,
+        `${homeDirName}/${parentDirName}/subdir1`,
+        `${homeDirName}/${parentDirName}/subdir1/subdir1_1`,
+        `${homeDirName}/${parentDirName}/subdir1/subdir1_2`,
+        `${homeDirName}/${parentDirName}/subdir2`,
+        `${homeDirName}/${parentDirName}/subdir2/subdir2_1`,
+        `${homeDirName}/${parentDirName}/subdir2/subdir2_2`,
+      ],
+    },
+  ]
 
-  const files = await sandbox.files.list(dirName)
-  assert.equal(files.length, 0)
+  for (const testCase of testCases) {
+    const files = await sandbox.files.list(
+      parentDirName,
+      testCase.depth !== undefined ? { depth: testCase.depth } : undefined
+    )
+    assert.equal(files.length, testCase.expectedLen)
 
-  await sandbox.files.write('test_directory4/test_file', 'test')
+    for (let i = 0; i < testCase.expectedFilePaths.length; i++) {
+      assert.equal(files[i].type, testCase.expectedFileTypes[i])
+      assert.equal(files[i].name, testCase.expectedFileNames[i])
+      assert.equal(files[i].path, testCase.expectedFilePaths[i])
+    }
+  }
+})
 
-  const files1 = await sandbox.files.list(dirName)
-  assert.equal(files1.length, 1)
-  assert.equal(files1[0].name, 'test_file')
-  assert.equal(files1[0].type, 'file')
-  assert.equal(files1[0].path, `/home/user/${dirName}/test_file`)
+sandboxTest('list directory with invalid depth', async ({ sandbox }) => {
+  await sandbox.files.makeDir(parentDirName)
 
-  const exists = await sandbox.files.exists(dirName)
-  assert.isTrue(exists)
+  try {
+    await sandbox.files.list(parentDirName, { depth: -1 })
+    assert.fail('Expected error but none was thrown')
+  } catch (err) {
+    const expectedErrorMessage = 'depth should be at least one'
+    assert.ok(
+      err.message.includes(expectedErrorMessage),
+      `expected error message to include "${expectedErrorMessage}"`
+    )
+  }
 })