Skip to content

unpack ​

unpack extrae un archivo ZIP, TAR o TAR.GZ en un directorio de destino y lo crea cuando no existe. El formato se identifica por el contenido, nunca por el nombre del archivo.

Firmaunpack(archive: string, destination: string, options?: UnpackOptions): Promise<Result<ArchiveSummary, ArchiveError>>

Ejemplo mínimo ​

tyrus
import { ArchiveError, ArchiveSummary, unpack } from "tyrus:archive";

async function extract(): Promise<Result<ArchiveSummary, ArchiveError>> {
    return await unpack("./upload.zip", "./workspace/upload");
}

Todas las opciones ​

tyrus
import { ArchiveError, ArchiveSummary, UnpackOptions, unpack } from "tyrus:archive";

async function extract(): Promise<Result<void, ArchiveError>> {
    const summary: ArchiveSummary = await unpack("./tool-v2.tar.gz", "./vendor/tool", {
        overwrite: true, // replace existing files; default false
        stripComponents: 1, // drop leading path components; default 0
        maxEntries: 10_000, // reject archives with more entries; default 100000
        maxBytes: 2_000_000_000, // reject more extracted bytes; default 4 GiB
        maxRatio: 500, // reject entries that expand more than this; default 200
        timeoutMs: 120_000, // give up after this many milliseconds; default 600000 (10 minutes)
    })?;
    print(summary.entries); // 57
    print(summary.bytes); // 3145728
    return Ok();
}
OpciónTipoPor defectoEfecto
overwritebooleanfalseReemplaza archivos que ya existen en el destino. Los directorios y enlaces nunca se reemplazan.
stripComponentsu320Elimina esa cantidad de componentes iniciales de la ruta de cada entrada; las entradas que quedan vacías se omiten.
maxEntriesu64100000Rechaza archivos con más entradas.
maxBytesu644 GiBRechaza la extracción que escribiría más bytes, contados a medida que se escriben.
maxRatiou32200Rechaza una entrada ZIP que se expande más de esa cantidad de veces su tamaño comprimido, y un archivo TAR.GZ cuyos bytes escritos superan esa cantidad de veces los bytes comprimidos leídos hasta ese momento, una vez escrito más de 1 MiB.
timeoutMsu64600000 (10 minutos)Desiste con ERR_ARCHIVE_TIMEOUT cuando la operación tarda más, eliminando lo que creó.

Los límites pueden aumentarse, pero nunca desactivarse: 0 falla con ERR_ARCHIVE_INVALID_OPTION.

Seguridad ​

  • Todo nombre de entrada se valida antes de crear cualquier cosa: se rechazan rutas absolutas, componentes .., prefijos de unidad, barras invertidas y nombres que alguna plataforma no puede crear, como CON o nombres que terminan en punto.
  • Las escrituras permanecen dentro del destino incluso cuando ya contiene un enlace simbólico: la extracción nunca atraviesa un enlace.
  • Los enlaces simbólicos, enlaces duros, dispositivos y otras entradas especiales se rechazan en lugar de recrearse.
  • Dos entradas que resultan en la misma ruta, incluidos los nombres que solo difieren en mayúsculas o en la normalización Unicode, se rechazan.
  • Cada archivo se escribe con un nombre temporal y se renombra al terminar, y ante cualquier falla se eliminan los archivos y directorios creados por esta llamada. El contenido que ya existía en el destino queda intacto.
  • Los archivos extraídos nunca reciben bits de permiso especiales; solo se conserva el permiso de ejecución del propietario, para que los programas extraídos sigan siendo ejecutables.
  • Antes de extraer un archivo ZIP, los tamaños que declara, limitados a maxBytes, se comparan con el espacio libre en el destino, y un archivo que no cabe se rechaza con ERR_ARCHIVE_NO_SPACE antes de crear cualquier archivo. Fuera de eso los tamaños nunca se consideran confiables: los límites cuentan los bytes realmente escritos, y un disco que se llena durante la extracción también rechaza con ERR_ARCHIVE_NO_SPACE.
  • Los archivos comprimidos dentro del archivo nunca se extraen: una entrada .zip o .tar.gz se escribe como un archivo común.
  • unpack nunca ejecuta, abre ni interpreta nada de lo que extrae.

Manejo de errores ​

error

tyrus
import { ArchiveError, ArchiveSummary, unpack } from "tyrus:archive";

async function extractUpload(): Promise<void> {
    match (await unpack("./untrusted.zip", "./workspace/upload")) {
        Ok(summary) => { print(summary.entries); }
        Err(error) => {
            printError(error.code); // ERR_ARCHIVE_PATH_ESCAPE
            printError(error.entry ?? ""); // ../../.bashrc
        }
    }
}