feat: restructured project to be more functional

Author: aryanjassal

src/Generator.ts

@@ -1,35 +1,10 @@
-import type {
-  EntryType,
-  DirectoryContent,
-  HeaderOptions,
-  ReadFileOptions,
-  WalkDirectoryOptions,
-  TarOptions,
-} from './types';
-import fs from 'fs';
-import path from 'path';
-import { EntryTypes } from './types';
+import type { FileStat } from './types';
+import { EntryType, HeaderSize, HeaderOffset } from './types';
 import * as errors from './errors';
+import * as utils from './utils';
+import * as constants from './constants';
 
-// Set defaults to the options used by the generators
-const defaultHeaderOptions: HeaderOptions = {
-  fileNameEncoding: 'utf8',
-  blockSize: 512,
-};
-const defaultReadFileOptions: ReadFileOptions = {
-  fs: fs.promises,
-  blockSize: 512,
-};
-const defaultWalkDirectoryOptions: WalkDirectoryOptions = {
-  fs: fs.promises,
-  blockSize: 512,
-};
-const defaultTarOptions: TarOptions = {
-  fs: fs.promises,
-  blockSize: 512,
-  fileNameEncoding: 'utf8',
-};
-
+// Computes the checksum by adding the value of every single byte in the header
 function computeChecksum(header: Buffer): number {
   if (!header.subarray(148, 156).every((byte) => byte === 32)) {
     throw new errors.ErrorVirtualTarInvalidHeader(
@@ -39,24 +14,41 @@ function computeChecksum(header: Buffer): number {
   return header.reduce((sum, byte) => sum + byte, 0);
 }
 
+// TODO: Should logging be included?
 function createHeader(
   filePath: string,
-  stat: fs.Stats,
+  stat: FileStat,
   type: EntryType,
-  options: Partial<HeaderOptions> = defaultHeaderOptions,
 ): Buffer {
+  // TODO: implement long-file-name headers
   if (filePath.length < 1 || filePath.length > 255) {
     throw new errors.ErrorVirtualTarInvalidFileName(
       'The file name must be longer than 1 character and shorter than 255 characters',
     );
   }
 
-  // Merge the defaults with the provided options
-  const opts: HeaderOptions = { ...defaultHeaderOptions, ...options };
+  // The file path must not contain any directories, and must only contain a
+  // file name. This guard checks that.
+  if (filePath.includes('/')) {
+    throw new errors.ErrorVirtualTarInvalidFileName(
+      'File name must not contain /',
+    );
+  }
+
+  // As the size does not matter for directories, it can be undefined. However,
+  // if the header is being generated for a file, then it needs to have a valid
+  // size. This guard checks that.
+  if (stat.size == null && type === EntryType.FILE) {
+    throw new errors.ErrorVirtualTarInvalidStat('Size must be set for files');
+  }
+  const size = type === EntryType.FILE ? stat.size : 0;
+
+  // The time can be undefined, which would be referring to epoch 0.
+  const time = utils.dateToUnixTime(stat.mtime ?? new Date());
 
-  const size = type === EntryTypes.FILE ? stat.size : 0;
-  const time = parseInt((stat.mtime.getTime() / 1000).toFixed(0)); // Unix time
-  const header = Buffer.alloc(opts.blockSize, 0);
+  // Make sure to initialise the header with zeros to avoid writing nullish
+  // blocks.
+  const header = Buffer.alloc(constants.BLOCK_SIZE, 0);
 
   // The TAR headers follow this structure
   // Start    Size    Description
@@ -68,7 +60,7 @@ function createHeader(
   // 124      12      File size (null-padded octal, 0 for directories)
   // 136      12      Mtime (null-padded octal)
   // 148      8       Checksum (fill with ASCII spaces for computation)
-  // 156      1       Type flag (0 for file, 5 for directory)
+  // 156      1       Type flag ('0' for file, '5' for directory)
   // 157      100     File owner name (null-terminated ASCII/UTF-8)
   // 257      6       'ustar\0' (magic string)
   // 263      2       '00' (ustar version)
@@ -78,119 +70,146 @@ function createHeader(
   // 337      8       Device minor (unset in this implementation)
   // 345      155     File name (last 155 bytes, total 255 bytes, null-padded)
   // 500      12      '\0' (unused)
+  //
+  // Note that all values are in ASCII format, which is different from the
+  // default formatting of UTF-8 for Buffer.write(). All numbers are also in
+  // octal format as opposed to decimal or hexadecimal.
+
+  // The first half of the file name (upto 100 bytes) is stored here.
+  header.write(
+    utils.splitFileName(filePath, 0, HeaderSize.FILE_NAME),
+    HeaderOffset.FILE_NAME,
+    HeaderSize.FILE_NAME,
+    constants.HEADER_ENCODING,
+  );
+
+  // The file permissions, or the mode, is stored in the next chunk. This is
+  // stored in an octal number format.
+  header.write(
+    utils.pad(stat.mode ?? '', HeaderSize.FILE_MODE, '0', '\0'),
+    HeaderOffset.FILE_MODE,
+    HeaderSize.FILE_MODE,
+    constants.HEADER_ENCODING,
+  );
+
+  // The owner UID is stored in this chunk
+  header.write(
+    utils.pad(stat.uid ?? '', HeaderSize.OWNER_UID, '0', '\0'),
+    HeaderOffset.OWNER_UID,
+    HeaderSize.OWNER_UID,
+    constants.HEADER_ENCODING,
+  );
+
+  // The owner GID is stored in this chunk
+  header.write(
+    utils.pad(stat.gid ?? '', HeaderSize.OWNER_GID, '0', '\0'),
+    HeaderOffset.OWNER_GID,
+    HeaderSize.OWNER_GID,
+    constants.HEADER_ENCODING,
+  );
+
+  // The file size is stored in this chunk. The file size must be zero for
+  // directories, and it must be set for files.
+  header.write(
+    utils.pad(size ?? '', HeaderSize.FILE_SIZE, '0', '\0'),
+    HeaderOffset.FILE_SIZE,
+    HeaderSize.FILE_SIZE,
+    constants.HEADER_ENCODING,
+  );
+
+  // The file mtime is stored in this chunk. As the mtime is not modified when
+  // extracting a TAR file, the mtime can be preserved while still getting
+  // deterministic archives.
+  header.write(
+    utils.pad(time, HeaderSize.FILE_MTIME, '0', '\0'),
+    HeaderOffset.FILE_MTIME,
+    HeaderSize.FILE_MTIME,
+    constants.HEADER_ENCODING,
+  );
+
+  // The checksum is calculated as the sum of all bytes in the header. It is
+  // padded using ASCII spaces, as we currently don't have all the data yet.
+  header.write(
+    utils.pad('', HeaderSize.CHECKSUM, ' '),
+    HeaderOffset.CHECKSUM,
+    HeaderSize.CHECKSUM,
+    constants.HEADER_ENCODING,
+  );
 
+  // The type of file is written as a single byte in the header.
   header.write(
-    filePath.slice(0, 99).padEnd(100, '\0'),
-    0,
-    100,
-    opts.fileNameEncoding,
+    type,
+    HeaderOffset.TYPE_FLAG,
+    HeaderSize.TYPE_FLAG,
+    constants.HEADER_ENCODING,
   );
-  header.write(stat.mode.toString(8).padStart(7, '0') + '\0', 100, 12, 'ascii');
-  header.write(stat.uid.toString(8).padStart(7, '0') + '\0', 108, 12, 'ascii');
-  header.write(stat.gid.toString(8).padStart(7, '0') + '\0', 116, 12, 'ascii');
-  header.write(size.toString(8).padStart(7, '0') + '\0', 124, 12, 'ascii');
-  header.write(time.toString(8).padStart(7, '0') + '\0', 136, 12, 'ascii');
-  header.write('        ', 148, 8, 'ascii'); // Placeholder for checksum
-  header.write(type, 156, 1, 'ascii');
-  // File owner name will be null
-  header.write('ustar\0', 257, 'ascii');
-  header.write('00', 263, 2, 'ascii');
-  // Owner user name will be null
-  // Owner group name will be null
-  // Device major will be null
-  // Device minor will be null
+
+  // File owner name will be null, as regular stat-ing cannot extract that
+  // information.
+
+  // This value is the USTAR magic string which makes this file appear as
+  // a tar file. Without this, the file cannot be parsed and extracted.
+  header.write(
+    constants.USTAR_NAME,
+    HeaderOffset.USTAR_NAME,
+    HeaderSize.USTAR_NAME,
+    constants.HEADER_ENCODING,
+  );
+
+  // This chunk stores the version of USTAR, which is '00' in this case.
+  header.write(
+    constants.USTAR_VERSION,
+    HeaderOffset.USTAR_VERSION,
+    HeaderSize.USTAR_VERSION,
+    constants.HEADER_ENCODING,
+  );
+
+  // Owner user name will be null, as regular stat-ing cannot extract this
+  // information.
+
+  // Owner group name will be null, as regular stat-ing cannot extract this
+  // information.
+
+  // Device major will be null, as this specific to linux kernel knowing what
+  // drivers to use for executing certain files, and is irrelevant here.
+
+  // Device minor will be null, as this specific to linux kernel knowing what
+  // drivers to use for executing certain files, and is irrelevant here.
+
+  // The second half of the file name is entered here. This chunk handles file
+  // names ranging 100 to 255 characters.
   header.write(
-    filePath.slice(100).padEnd(155, '\0'),
-    345,
-    155,
-    opts.fileNameEncoding,
+    utils.splitFileName(
+      filePath,
+      HeaderSize.FILE_NAME,
+      HeaderSize.FILE_NAME_EXTRA,
+    ),
+    HeaderOffset.FILE_NAME_EXTRA,
+    HeaderSize.FILE_NAME_EXTRA,
+    constants.HEADER_ENCODING,
   );
 
   // Updating with the new checksum
   const checksum = computeChecksum(header);
-  header.write(checksum.toString(8).padStart(6, '0') + '\0 ', 148, 8, 'ascii');
-
-  return header;
-}
 
-async function* readFile(
-  filePath: string,
-  options: Partial<ReadFileOptions> = defaultReadFileOptions,
-): AsyncGenerator<Buffer, void, void> {
-  const opts: ReadFileOptions = { ...defaultReadFileOptions, ...options };
-  const fileHandle = await opts.fs.open(filePath, 'r');
-  const buffer = Buffer.alloc(opts.blockSize);
-  let bytesRead = -1; // Initialisation value
-
-  try {
-    while (bytesRead !== 0) {
-      buffer.fill(0);
-      const result = await fileHandle.read(buffer, 0, opts.blockSize, null);
-      bytesRead = result.bytesRead;
-
-      if (bytesRead === 0) break; // EOF reached
-      if (bytesRead < 512) buffer.fill(0, bytesRead, opts.blockSize);
-
-      yield buffer;
-    }
-  } finally {
-    await fileHandle.close();
-  }
-}
+  // Note the extra space in the padding for the checksum value. It is
+  // intentionally placed there. The padding for checksum is ASCII spaces
+  // instead of null, which is why it is used like this here.
+  header.write(
+    utils.pad(checksum, HeaderSize.CHECKSUM, '0', '\0 '),
+    HeaderOffset.CHECKSUM,
+    HeaderSize.CHECKSUM,
+    constants.HEADER_ENCODING,
+  );
 
-/**
- * Traverse a directory recursively and yield file entries.
- */
-async function* walkDirectory(
-  baseDir: string,
-  relativePath: string = '',
-  options: Partial<WalkDirectoryOptions> = defaultWalkDirectoryOptions,
-): AsyncGenerator<DirectoryContent> {
-  const opts: WalkDirectoryOptions = {
-    ...defaultWalkDirectoryOptions,
-    ...options,
-  };
-  const entries = await opts.fs.readdir(path.join(baseDir, relativePath));
-
-  // Sort the entries lexicographically
-  for (const entry of entries.sort()) {
-    const fullPath = path.join(baseDir, relativePath, entry);
-    const stat = await opts.fs.stat(fullPath);
-    const tarPath = path.join(relativePath, entry);
-
-    if (stat.isDirectory()) {
-      yield { path: tarPath + '/', stat: stat, type: EntryTypes.DIRECTORY };
-      yield* walkDirectory(baseDir, path.join(relativePath, entry));
-    } else if (stat.isFile()) {
-      yield { path: tarPath, stat: stat, type: EntryTypes.FILE };
-    }
-  }
+  return header;
 }
 
-async function* createTar(
-  baseDir: string,
-  options: Partial<TarOptions> = defaultTarOptions,
-): AsyncGenerator<Buffer, void, void> {
-  const opts = { ...defaultTarOptions, ...options };
-  const entryGen = walkDirectory(baseDir, '', {
-    fs: opts.fs,
-    blockSize: opts.blockSize,
-  });
-
-  for await (const entry of entryGen) {
-    yield createHeader(entry.path, entry.stat, entry.type);
-
-    if (entry.type === EntryTypes.FILE) {
-      yield* readFile(path.join(baseDir, entry.path), {
-        fs: opts.fs,
-        blockSize: opts.blockSize,
-      });
-    }
-  }
-
-  // End-of-archive marker - two 512-byte null blocks
-  yield Buffer.alloc(opts.blockSize, 0);
-  yield Buffer.alloc(opts.blockSize, 0);
+// Creates blocks marking the ned of the header. Returns one buffer of 1024
+// bytes filled with nulls. This aligns with the tar end-of-archive marker
+// being two null-filled blocks.
+function generateEndMarker() {
+  return [Buffer.alloc(512, 0), Buffer.alloc(512, 0)];
 }
 
-export { createHeader, readFile, createTar };
+export { createHeader, generateEndMarker };

src/constants.ts

@@ -0,0 +1,4 @@
+export const BLOCK_SIZE = 512;
+export const USTAR_NAME = 'ustar\0';
+export const USTAR_VERSION = '00';
+export const HEADER_ENCODING = 'ascii';

src/errors.ts

@@ -16,9 +16,14 @@ class ErrorVirtualTarInvalidHeader<T> extends ErrorVirtualTar<T> {
   static description = 'The header has invalid data';
 }
 
+class ErrorVirtualTarInvalidStat<T> extends ErrorVirtualTar<T> {
+  static description = 'The stat contains invalid data';
+}
+
 export {
   ErrorVirtualTar,
   ErrorVirtualTarUndefinedBehaviour,
   ErrorVirtualTarInvalidFileName,
   ErrorVirtualTarInvalidHeader,
+  ErrorVirtualTarInvalidStat,
 };