Skip to content

🙌 OpenHands: AI-Driven Development

4.4 KB
Raw Blame
/**
 * Packing a handful of text files into a `.tar.gz`, in the browser.
 *
 * The automation service accepts a gzipped tar and nothing else, and the only
 * archives built here are the few small files a catalog bundle ships, so this
 * writes the original POSIX ustar format directly rather than pulling in a tar
 * library: 512-byte header, name and metadata as space-padded octal, content
 * padded to the next 512-byte boundary, two zero blocks to end the archive.
 * Gzip is the platform's own `CompressionStream`.
 *
 * Deliberately not general-purpose. Names must fit ustar's 100-byte field, and
 * only regular files are written - no directories, links, or long-name
 * extensions - because a bundle that needed any of those would be packed by
 * something that also has to unpack them.
 */

const encoder = new TextEncoder();

const BLOCK_SIZE = 512;
const NAME_FIELD_SIZE = 100;
const CHECKSUM_OFFSET = 148;
const CHECKSUM_SIZE = 8;

export interface TarFile {
  /** Path inside the archive. Must fit ustar's 100-byte name field. */
  name: string;
  content: string;
  /** Defaults to 0o644. A setup script wants 0o755. */
  mode?: number;
}

function header(file: TarFile, name: Uint8Array, size: number): Uint8Array {
  const block = new Uint8Array(BLOCK_SIZE);

  /** Host-written ASCII: the octal fields and the format's own markers. */
  const ascii = (offset: number, value: string): void => {
    for (let index = 0; index < value.length; index += 1) {
      block[offset + index] = value.charCodeAt(index) & 0x7f;
    }
  };
  /** ustar writes numbers as octal, NUL-terminated, right-aligned with zeros. */
  const octal = (offset: number, size_: number, value: number): void =>
    ascii(offset, value.toString(8).padStart(size_ - 1, "0"));

  // The name is the caller's, so it is written as the bytes it encodes to
  // rather than through `ascii`, whose mask would quietly turn `café.py` into
  // `cafi.py`. ustar's name field is bytes, and readers take them as UTF-8.
  block.set(name, 0);
  octal(100, 8, file.mode ?? 0o644);
  octal(108, 8, 0); // uid
  octal(116, 8, 0); // gid
  octal(124, 12, size);
  // A fixed mtime keeps the archive byte-identical for identical inputs, so a
  // re-upload of an unchanged bundle is visibly unchanged.
  octal(136, 12, 0);
  block[156] = "0".charCodeAt(0); // regular file
  ascii(257, "ustar");
  ascii(263, "00");

  // The checksum is computed with its own field read as spaces, then written
  // into it as octal followed by NUL and a space.
  block.fill(0x20, CHECKSUM_OFFSET, CHECKSUM_OFFSET + CHECKSUM_SIZE);
  const sum = block.reduce((total, byte) => total + byte, 0);
  ascii(CHECKSUM_OFFSET, sum.toString(8).padStart(6, "0"));
  block[CHECKSUM_OFFSET + 6] = 0;
  block[CHECKSUM_OFFSET + 7] = 0x20;

  return block;
}

/** The uncompressed archive. Exported for tests; callers want `packTarGzip`. */
export function packTar(files: readonly TarFile[]): Uint8Array<ArrayBuffer> {
  const blocks: Uint8Array[] = [];

  for (const file of files) {
    const name = encoder.encode(file.name);
    if (name.length > NAME_FIELD_SIZE) {
      throw new Error(`tar: name too long for a ustar header: ${file.name}`);
    }
    const content = encoder.encode(file.content);
    blocks.push(header(file, name, content.length));
    const padded = new Uint8Array(
      Math.ceil(content.length / BLOCK_SIZE) * BLOCK_SIZE,
    );
    padded.set(content);
    blocks.push(padded);
  }

  // Two zero blocks mark the end of the archive.
  blocks.push(new Uint8Array(BLOCK_SIZE * 2));

  const total = blocks.reduce((size, block) => size + block.length, 0);
  const archive = new Uint8Array(new ArrayBuffer(total));
  let offset = 0;
  for (const block of blocks) {
    archive.set(block, offset);
    offset += block.length;
  }
  return archive;
}

/** The gzipped archive, ready to POST as `application/gzip`. */
export async function packTarGzip(
  files: readonly TarFile[],
): Promise<Uint8Array> {
  const tar = packTar(files);
  // Streamed from the bytes rather than through a Blob: a Blob's stream() is
  // absent in the jsdom test environment, and the archive is one chunk anyway.
  const source = new ReadableStream<BufferSource>({
    start(controller) {
      controller.enqueue(tar);
      controller.close();
    },
  });
  const compressed = new Response(
    source.pipeThrough(new CompressionStream("gzip")),
  );
  return new Uint8Array(await compressed.arrayBuffer());
}