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.
Firma
unpack(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ón | Tipo | Por defecto | Efecto |
|---|---|---|---|
overwrite | boolean | false | Reemplaza archivos que ya existen en el destino. Los directorios y enlaces nunca se reemplazan. |
stripComponents | u32 | 0 | Elimina esa cantidad de componentes iniciales de la ruta de cada entrada; las entradas que quedan vacías se omiten. |
maxEntries | u64 | 100000 | Rechaza archivos con más entradas. |
maxBytes | u64 | 4 GiB | Rechaza la extracción que escribiría más bytes, contados a medida que se escriben. |
maxRatio | u32 | 200 | Rechaza 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. |
timeoutMs | u64 | 600000 (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, comoCONo 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 conERR_ARCHIVE_NO_SPACEantes 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 conERR_ARCHIVE_NO_SPACE. - Los archivos comprimidos dentro del archivo nunca se extraen: una entrada
.zipo.tar.gzse escribe como un archivo común. unpacknunca 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
}
}
}