deno.land / std@0.224.0 / archive / tar.ts
tar.ts
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license./*! * Ported and modified from: https://github.com/beatgammit/tar-js and * licensed as: * * (The MIT License) * * Copyright (c) 2011 T. Jameson Little * Copyright (c) 2019 Jun Kato * Copyright (c) 2018-2024 the Deno authors * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. */
import { FileTypes, type TarInfo, type TarMeta, USTAR_STRUCTURE,} from "./_common.ts";import type { Reader } from "../io/types.ts";import { MultiReader } from "../io/multi_reader.ts";import { Buffer } from "../io/buffer.ts";import { assert } from "../assert/assert.ts";import { HEADER_LENGTH } from "./_common.ts";
export type { TarInfo, TarMeta };
/** Options for {@linkcode Tar.append}. */export interface TarOptions extends TarInfo { /** * Filepath of the file to append to the archive */ filePath?: string;
/** * A Reader of any arbitrary content to append to the archive */ reader?: Reader;
/** * Size of the content to be appended. This is only required * when passing a reader to the archive. */ contentSize?: number;}
const USTAR_MAGIC_HEADER = "ustar\u000000" as const;
/** * Simple file reader */class FileReader implements Reader { #file?: Deno.FsFile;
constructor(private filePath: string) {}
public async read(p: Uint8Array): Promise<number | null> { if (!this.#file) { this.#file = await Deno.open(this.filePath, { read: true }); } const res = await this.#file.read(p); if (res === null) { this.#file.close(); this.#file = undefined; } return res; }}
/** * Pads a number with leading zeros to a specified number of bytes. * * @param num The number to pad. * @param bytes The number of bytes to pad the number to. * @returns The padded number as a string. */function pad(num: number, bytes: number): string { return num.toString(8).padStart(bytes, "0");}
/** * Formats the header data for a tar file entry. * * @param data The data object containing the values for the tar header fields. * @returns The formatted header data as a Uint8Array. */function formatHeader(data: TarData): Uint8Array { const encoder = new TextEncoder(); const buffer = new Uint8Array(HEADER_LENGTH); let offset = 0; for (const { field, length } of USTAR_STRUCTURE) { const entry = encoder.encode(data[field as keyof TarData] || ""); buffer.set(entry, offset); offset += length; } return buffer;}
/** Base interface for {@linkcode TarDataWithSource}. */export interface TarData { /** Name of the file, excluding directory names (if any). */ fileName?: string; /** Directory names preceding the file name (if any). */ fileNamePrefix?: string; /** * The underlying raw `st_mode` bits that contain the standard Unix * permissions for this file/directory. */ fileMode?: string; /** * Numeric user ID of the file owner. This is ignored if the operating system * does not support numeric user IDs. */ uid?: string; /** * Numeric group ID of the file owner. This is ignored if the operating * system does not support numeric group IDs. */ gid?: string; /** * The size of the file in bytes; for archive members that are symbolic or * hard links to another file, this field is specified as zero. */ fileSize?: string; /** * Data modification time of the file at the time it was archived. It * represents the integer number of seconds since January 1, 1970, 00:00 UTC. */ mtime?: string; /** The simple sum of all bytes in the header block */ checksum?: string; /** * The type of file archived. * * @see {@linkcode FileTypes} */ type?: string; /** Ustar magic header */ ustar?: string; /** The name of the file owner. */ owner?: string; /** The group that the file owner belongs to. */ group?: string;}
/** Tar data interface for {@linkcode Tar.data}. */export interface TarDataWithSource extends TarData { /** * Path of the file to read. */ filePath?: string; /** * Buffer reader. */ reader?: Reader;}
/** * ### Overview * A class to create a tar archive. Tar archives allow for storing multiple files in a * single file (called an archive, or sometimes a tarball). These archives typically * have the '.tar' extension. * * ### Usage * The workflow is to create a Tar instance, append files to it, and then write the * tar archive to the filesystem (or other output stream). See the worked example * below for details. * * ### Compression * Tar archives are not compressed by default. If you want to compress the archive, * you may compress the tar archive after creation, but this capability is not provided * here. * * ### File format and limitations * * The ustar file format is used for creating the archive file. * While this format is compatible with most tar readers, * the format has several limitations, including: * * Files must be smaller than 8GiB * * Filenames (including path) must be shorter than 256 characters * * Filenames (including path) cannot contain non-ASCII characters * * Sparse files are not supported * * @example * ```ts * import { Tar } from "https://deno.land/std@$STD_VERSION/archive/tar.ts"; * import { Buffer } from "https://deno.land/std@$STD_VERSION/io/buffer.ts"; * import { copy } from "https://deno.land/std@$STD_VERSION/io/copy.ts"; * * const tar = new Tar(); * * // Now that we've created our tar, let's add some files to it: * * const content = new TextEncoder().encode("Some arbitrary content"); * await tar.append("deno.txt", { * reader: new Buffer(content), * contentSize: content.byteLength, * }); * * // This file is sourced from the filesystem (and renamed in the archive) * await tar.append("filename_in_archive.txt", { * filePath: "./filename_on_filesystem.txt", * }); * * // Now let's write the tar (with it's two files) to the filesystem * // use tar.getReader() to read the contents. * * const writer = await Deno.open("./out.tar", { write: true, create: true }); * await copy(tar.getReader(), writer); * writer.close(); * ``` */export class Tar { /** Tar data. */ data: TarDataWithSource[];
/** Constructs a new instance. */ constructor() { this.data = []; }
/** * Append a file or reader of arbitrary content to this tar archive. Directories * appended to the archive append only the directory itself to the archive, not * its contents. To add a directory and its contents, recursively append the * directory's contents. Directories and subdirectories will be created automatically * in the archive as required. * * @param filenameInArchive File name of the content in the archive. E.g. * `test.txt`. Use slash for directory separators. * @param source Details of the source of the content including the * reference to the content itself and potentially any related metadata. */ async append(filenameInArchive: string, source: TarOptions) { if (typeof filenameInArchive !== "string") { throw new Error("file name not specified"); } let fileName = filenameInArchive;
/** * Ustar format has a limitation of file name length. Specifically: * 1. File names can contain at most 255 bytes. * 2. File names longer than 100 bytes must be split at a directory separator in two parts, * the first being at most 155 bytes long. So, in most cases file names must be a bit shorter * than 255 bytes. */ // separate file name into two parts if needed let fileNamePrefix: string | undefined; if (fileName.length > 100) { let i = fileName.length; while (i >= 0) { i = fileName.lastIndexOf("/", i); if (i <= 155) { fileNamePrefix = fileName.slice(0, i); fileName = fileName.slice(i + 1); break; } i--; } const errMsg = "ustar format does not allow a long file name (length of [file name" + "prefix] + / + [file name] must be shorter than 256 bytes)"; if (i < 0 || fileName.length > 100) { throw new Error(errMsg); } else { assert(fileNamePrefix !== undefined); if (fileNamePrefix.length > 155) { throw new Error(errMsg); } } }
source = source || {};
// set meta data let info: Deno.FileInfo | undefined; if (source.filePath) { info = await Deno.stat(source.filePath); if (info.isDirectory) { info.size = 0; source.reader = new Buffer(); } }
const mode = source.fileMode || (info && info.mode) || parseInt("777", 8) & 0xfff /* 511 */; const mtime = Math.floor( source.mtime ?? (info?.mtime ?? new Date()).valueOf() / 1000, ); const uid = source.uid || 0; const gid = source.gid || 0;
if (typeof source.owner === "string" && source.owner.length >= 32) { throw new Error( "ustar format does not allow owner name length >= 32 bytes", ); } if (typeof source.group === "string" && source.group.length >= 32) { throw new Error( "ustar format does not allow group name length >= 32 bytes", ); }
const fileSize = info?.size ?? source.contentSize; assert(fileSize !== undefined, "fileSize must be set");
const type = source.type ? FileTypes[source.type as keyof typeof FileTypes] : (info?.isDirectory ? FileTypes.directory : FileTypes.file); const tarData: TarDataWithSource = { fileName, fileNamePrefix, fileMode: pad(mode, 7), uid: pad(uid, 7), gid: pad(gid, 7), fileSize: pad(fileSize, 11), mtime: pad(mtime, 11), checksum: " ", type: type.toString(), ustar: USTAR_MAGIC_HEADER, owner: source.owner || "", group: source.group || "", filePath: source.filePath, reader: source.reader, };
// calculate the checksum let checksum = 0; const encoder = new TextEncoder(); Object.keys(tarData) .filter((key): boolean => ["filePath", "reader"].indexOf(key) < 0) .forEach(function (key) { checksum += encoder .encode(tarData[key as keyof TarData]) .reduce((p, c): number => p + c, 0); });
tarData.checksum = pad(checksum, 6) + "\u0000 "; this.data.push(tarData); }
/** * Get a Reader instance for this tar archive. */ getReader(): Reader { const readers: Reader[] = []; this.data.forEach((tarData) => { let { reader } = tarData; const { filePath } = tarData; const headerArr = formatHeader(tarData); readers.push(new Buffer(headerArr)); if (!reader) { assert(filePath !== undefined); reader = new FileReader(filePath); } readers.push(reader);
// to the nearest multiple of recordSize assert(tarData.fileSize !== undefined, "fileSize must be set"); readers.push( new Buffer( new Uint8Array( HEADER_LENGTH - (parseInt(tarData.fileSize, 8) % HEADER_LENGTH || HEADER_LENGTH), ), ), ); });
// append 2 empty records readers.push(new Buffer(new Uint8Array(HEADER_LENGTH * 2))); return new MultiReader(readers); }}
std
Version Info
6 months ago
