Skip to content

unpack ​

unpack extrai um arquivo ZIP, TAR ou TAR.GZ para um diretório de destino, criando-o quando não existe. O formato é identificado pelo conteúdo, nunca pelo nome do arquivo.

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

Exemplo 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 as opções ​

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();
}
OpçãoTipoPadrãoEfeito
overwritebooleanfalseSubstitui arquivos que já existem no destino. Diretórios e links nunca são substituídos.
stripComponentsu320Remove essa quantidade de componentes iniciais do caminho de cada entrada; entradas que ficam vazias são ignoradas.
maxEntriesu64100000Recusa arquivos com mais entradas.
maxBytesu644 GiBRecusa a extração que gravaria mais bytes, contados à medida que são gravados.
maxRatiou32200Recusa uma entrada ZIP que expande mais que essa quantidade de vezes o tamanho comprimido, e um arquivo TAR.GZ cujos bytes gravados passam dessa quantidade de vezes os bytes comprimidos lidos até ali, depois de gravar mais de 1 MiB.
timeoutMsu64600000 (10 minutos)Desiste com ERR_ARCHIVE_TIMEOUT quando a operação demora mais, removendo o que criou.

Os limites podem ser aumentados, mas nunca desativados: 0 falha com ERR_ARCHIVE_INVALID_OPTION.

Segurança ​

  • Todo nome de entrada é validado antes de qualquer coisa ser criada: caminhos absolutos, componentes .., prefixos de unidade, barras invertidas e nomes que alguma plataforma não consegue criar, como CON ou nomes terminados em ponto, são recusados.
  • As gravações ficam dentro do destino mesmo quando ele já contém um link simbólico: a extração nunca atravessa um link.
  • Links simbólicos, links físicos, dispositivos e outras entradas especiais são recusados em vez de recriados.
  • Duas entradas que resultam no mesmo caminho, inclusive nomes que diferem só na caixa ou na normalização Unicode, são recusadas.
  • Cada arquivo é gravado com um nome temporário e renomeado ao terminar, e em qualquer falha os arquivos e diretórios criados por esta chamada são removidos. O conteúdo que já existia no destino fica intocado.
  • Arquivos extraídos nunca recebem bits de permissão especiais; só a permissão de execução do dono é mantida, para que programas extraídos continuem executáveis.
  • Antes de extrair um arquivo ZIP, os tamanhos que ele declara, limitados a maxBytes, são comparados com o espaço livre no destino, e um arquivo que não cabe é recusado com ERR_ARCHIVE_NO_SPACE antes de qualquer arquivo ser criado. Além disso os tamanhos nunca são confiáveis: os limites contam os bytes gravados de fato, e um disco que enche durante a extração também rejeita com ERR_ARCHIVE_NO_SPACE.
  • Arquivos compactados dentro do arquivo nunca são extraídos: uma entrada .zip ou .tar.gz é gravada como arquivo comum.
  • unpack nunca executa, abre nem interpreta nada do que extrai.

Tratamento de erro ​

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
        }
    }
}