TypeScript SDK

Files and Git

Read, write and watch sandbox files, and read and change git repositories, with @tektona/sdk.

sandbox.files and sandbox.git work with the file system of a sandbox. Every operation runs as the image user by default. A path is absolute, or relative to the sandbox working directory. ~ and ~/… name the home directory of the user that the operation runs as. See Files and Git for the access rules and the limits.

The SDK sends these requests to the access endpoint of the sandbox, not to apiUrl, with the API key of the client. It reads the endpoint from the sandbox once. Without an API key, a files or git call throws AuthenticationError.

Files

const sandbox = await tek.sandbox.get('01J9F3ZK7QW4B2Y8N5T1QAZ6RX');

const { entries } = await sandbox.files.list('src', { depth: 2 });
const { size, etag: currentEtag } = await sandbox.files.stat('src/main.go');

const { bytes, etag } = await sandbox.files.read('logo.png');
const { text } = await sandbox.files.readText('src/main.go'); // throws on bytes that are not UTF-8

await sandbox.files.write('src/main.go', text + '\n// done\n', { ifMatch: etag });
await sandbox.files.write('notes.md', '# Notes\n', { createOnly: true });
await sandbox.files.move('notes.md', 'docs/notes.md', { overwrite: false });
await sandbox.files.remove('build', { recursive: true });
await sandbox.files.makeDir('build/out', { mode: 0o700 });
await sandbox.files.write('run.sh', '#!/bin/sh\necho ok\n', { mode: 0o755 });
await sandbox.files.setMode('run.sh', 0o700);
MethodNotes
list(path, { depth, limit, perDirLimit, exclude, gitignore })depth defaults to 1, limit to 5000. Symlinks are listed, not followed. exclude skips matching folders and files; gitignore skips what git ignores and needs write access. perDirLimit keeps the first entries of each folder. A cut list sets truncated and names the folders that it did not fully list in truncated_paths.
stat(path)File size and an ETag for files up to 1 GiB.
etag(path)The file ETag, if one is available.
read(path){ bytes, etag? } for a file of any size.
readText(path){ text, etag? }.
write(path, data, { ifMatch, createOnly, mode })Stream a string, Uint8Array, Blob or ReadableStream of any size. mode (for example 0o755) is set before the file replaces the target. Returns { entry, etag }.
readStream(path)A ReadableStream of the file. It rejects a short body.
readStream(path, { offset, ifRange })Resume at offset. Returns { stream, partial, etag }: append when partial, else the stream is the whole file.
remove(path, { recursive })A directory that is not empty needs recursive.
move(from, to, { overwrite })Returns the entry at to.
makeDir(path, { mode })Creates missing parents too. Returns { entry, created }; created is false for an existing directory.
setMode(path, mode)Like chmod; follows a symlink. Returns the entry.
setOwner(path, { owner, group })Like chown; names or numbers, follows a symlink. Returns the entry.

Pass a mode as an octal literal such as 0o755; the API carries it as a decimal integer. An entry has uid, gid and, when the sandbox has names for them, owner and group.

A write uses a temporary file. A failed upload leaves the target unchanged. When write returns, the file is synced to disk, if the sandbox image has a sync command. A failed sync fails the write and keeps the old file. The new file has a new inode; hard links keep the old bytes. ifMatch protects against other API writes, but not against processes in the sandbox.

A sandbox has at most 32 open transfers. More return 429 too_many_transfers. A transfer stops when it moves less than 256 KiB in a minute. Files above 1 GiB do not support conditional saves. Use stat to get an ETag before you save a large file.

const res = await fetch('https://example.com/dataset.tar');
await sandbox.files.write('data/dataset.tar', res.body!);

const stream = await sandbox.files.readStream('out/report.pdf');

// A whole folder as tar.gz, without build output.
const archive = await sandbox.files.downloadArchive('app', { format: 'tar.gz', exclude: ['node_modules', '.git'] });

downloadArchive also takes a list of paths; each goes into the archive under its base name. It returns a stream that rejects when the download breaks.

Write many files in one request, or upload an archive:

await sandbox.files.writeFiles([
  { path: 'app/src/index.ts', data: source },
  { path: 'app/bin/run', data: script, mode: 0o755 },
]);
await sandbox.files.uploadArchive('app', archiveBytes, { format: 'tar.gz' });

Hand one file to a client without credentials:

const { url } = await sandbox.files.signedUrl('dist/app.zip', { method: 'GET', expiresIn: 300 });
const upload = await sandbox.files.signedUrl('inbox/report.pdf', { method: 'PUT' });
await fetch(upload.url, { method: 'PUT', body: pdf }); // uploads once

writeFiles packs the files into one tar for their common directory. A file without mode keeps the mode of the file that it replaces, or gets 0o644 when it is new. Each file is replaced atomically, the set is not: a failure keeps the files before it.

Edit files as root

Every sandbox.files method takes a user option, a user name or a uid. The operation then runs as that user. Use it for files that the image user cannot change:

const { text, etag } = await sandbox.files.readText('/etc/hosts', { user: 'root' });
await sandbox.files.write('/etc/hosts', text + '127.0.0.1 api.local\n', { user: 'root', ifMatch: etag });

An operation with user needs permission to operate the sandbox, also a read.

A refused operation throws an ApiError subclass. error.code holds the reason, for example precondition_failed, file_too_large or directory_not_empty.

Git

Git operations need permission to operate the sandbox.

const status = await sandbox.git.status('.');
const diff = await sandbox.git.diff('.', { base: 'main' });
const summary = await sandbox.git.diffSummary('.', { base: 'main' });
for (const f of diff.files) {
  const before = f.old_oid ? await sandbox.git.blob('.', f.old_oid) : new Uint8Array();
  const after = f.status === 'deleted' ? new Uint8Array() : (await sandbox.files.read(`${diff.root}/${f.path}`)).bytes;
  showDiff(f.path, before, after);
}
const { paths } = await sandbox.git.files('.');

diff.files has a lines object for each file with known changed-line counts. The value is null if the count is unknown. summary.files.binary counts files without a known line count. summary.lines adds only the known changed-line counts. patch returns every change as one patch for git apply -p1, untracked and binary files included. Write bytes to a file, not patch: a file that is not UTF-8 keeps its exact bytes only there.

const { bytes, truncated } = await sandbox.git.patch('.', { files: ['src/login.ts'] });

In a very large work tree, status, diff and diffSummary return truncated: true and a part of the files instead of an error.

Change a repository:

const root = await sandbox.git.clone('https://github.com/acme/app.git', 'app');
await sandbox.git.createBranch(root, 'fix-login', { checkout: true });
await sandbox.git.stage(root, ['src/login.ts']);
const oid = await sandbox.git.commit(root, 'Fix the login form', {
  authorName: 'Agent',
  authorEmail: 'agent@example.com',
});
await sandbox.git.push(root, { branch: 'fix-login', setUpstream: true });
const commits = await sandbox.git.log(root, { limit: 20 });

log, branches, checkout, unstage, discard, deleteBranch, fetch, pull, init, reset, restore, remotes, addRemote, removeRemote, getConfig and setConfig work the same way. getConfig and setConfig take only user.name, user.email, core.autocrlf, pull.rebase and init.defaultBranch. A commit without an author and without user.name and user.email in the sandbox throws with the code git_identity_missing. A commit with nothing to commit throws with nothing_to_commit. A command that git refuses throws with git_failed.

To keep a change view current, call status 300 ms after the last changes frame of a watch, and every 30 seconds while the view is visible.

Watch

watch returns an async iterable of ready, changes, resync and a last end event:

import { FilesWatchLostError } from '@tektona/sdk';

async function follow(): Promise<void> {
  let delay = 500;
  for (;;) {
    const watch = sandbox.files.watch('src', { recursive: true, exclude: ['node_modules'] });
    try {
      for await (const ev of watch) {
        if (ev.type === 'ready' || ev.type === 'resync') {
          loadTree(await sandbox.files.list('src', { depth: 4, exclude: ['node_modules'] }));
          delay = 500;
        } else if (ev.type === 'changes') {
          applyChanges(ev.changes);
        } else {
          console.log('watch ended:', ev.reason);
          return;
        }
      }
      return;
    } catch (e) {
      if (!(e instanceof FilesWatchLostError)) throw e;
      await sandbox.files.stat('src'); // Stop if access was revoked.
      await new Promise((resolve) => setTimeout(resolve, delay));
      delay = Math.min(delay * 2, 30_000);
    }
  }
}

The iteration throws FilesWatchLostError when a seq is skipped, a frame is not valid, or the socket closes without end. Call watch again and list again. watch.close() stops the watch without an error. reason is expired, server_shutdown, or connection_lost. After a lost watch, wait up to 30 seconds before you reopen it. The SDK does not reconnect for you.

On this page