搜尋套件、儲存庫與 APP 分類

套件詳情v2.1.0

tar

記憶體效率高的串流式 tar 檔案格式實作

AndroidiOSWebmacOSWindowsLinux
近 30 天下載
33.5萬
喜歡數
42
Pub 分數
160

安裝套件

flutter pub add tar

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

tar 套件提供了一種記憶體效率高、串流式的實作,可用於在 Dart 中讀取和寫入 tar 檔案格式。此套件專為處理大型歸檔檔案而設計,無需將整個檔案載入記憶體,支援逐次處理歸檔項目。非常適合需要高效檔案壓縮與解壓的應用程式,特別是在資源有限的情況下。該套件相容於所有主要平台,包含行動裝置、網頁與桌面端。它能與需要強大歸檔處理功能的 Flutter 應用程式無縫整合。

適用情境

  • 大型 tar 檔案的串流提取
  • 在資源受限環境中的高效歸檔建立
  • 在跨平台應用中整合基於 tar 的資料儲存
  • 處理歸檔日誌或備份
  • 在Flutter應用程式中處理壓縮資源

主要特色

  • 用於低記憶體使用的串流 I/O
  • 支援讀取和寫入 tar 檔案
  • 跨平台相容性(Android、iOS、Web、macOS、Windows、Linux)
  • 歸檔項目之增量處理
  • 輕量且快速的效能

適合對象

  • 開發檔案管理工具的開發者
  • 需要高效歸檔處理的應用程式
  • 記憶體資源有限的專案
  • 使用 Flutter 的跨平台應用程式
  • 處理大型資料集的歸檔格式工具

使用建議

  • 不支援加密或壓縮的 tar 檔案(例如 .tar.gz)
  • 需要手動處理檔案權限和元資料
  • 僅限基本的 tar 格式,不包含進階功能
  • 不適用於複雜的歸檔操作
  • 最佳搭配已知且格式良好的 tar 輸入使用

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

tar

Build status

This package provides stream-based readers and writers for tar files.

When working with large tar files, this library consumes considerably less memory than package:archive, although it is slightly slower due to the async overhead.

Reading

To read entries from a tar file, use a TarReader with a Stream emitting bytes (as List<int>):

import 'dart:convert';
import 'dart:io';
import 'package:tar/tar.dart';

Future<void> main() async {
  final reader = TarReader(File('file.tar').openRead());

  while (await reader.moveNext()) {
    final entry = reader.current;
    // Use reader.header to see the header of the current tar entry
    print(entry.header.name);
    // And reader.contents to read the content of the current entry as a stream
    print(await entry.contents.transform(utf8.decoder).first);
  }
  // Note that the reader will automatically close if moveNext() returns false or
  // throws. If you want to close a tar stream before that happens, use
  // reader.cancel();
}

To read .tar.gz files, transform the stream with gzip.decoder before passing it to the TarReader.

To easily go through all entries in a tar file, use TarReader.forEach:

Future<void> main() async {
  final inputStream = File('file.tar').openRead();

  await TarReader.forEach(inputStream, (entry) {
    print(header.name);
    print(await entry.contents.transform(utf8.decoder).first);
  });
}

Warning: Since the reader is backed by a single stream, concurrent calls to read are not allowed! Similarly, if you're reading from an entry's contents, make sure to fully drain the stream before calling read() again. Not subscribing to contents before calling moveNext() is acceptable too. In this case, the reader will implicitly drain the stream. The reader detects concurrency misuses and will throw an error when they occur, there's no risk of reading faulty data.

Writing

When writing archives, package:tar expects a Stream of tar entries to include in the archive. This stream can then be converted into a stream of byte-array chunks forming the encoded tar archive.

To write a tar stream into a StreamSink<List<int>>, such as an IOSink returned by File.openWrite, use tarWritingSink:

import 'dart:convert';
import 'dart:io';
import 'package:tar/tar.dart';

Future<void> main() async {
  final output = File('test.tar').openWrite();
  final tarEntries = Stream<TarEntry>.value(
    TarEntry.data(
      TarHeader(
        name: 'hello.txt',
        mode: int.parse('644', radix: 8),
      ),
      utf8.encode('Hello world'),
    ),
  );

  await tarEntries.pipe(tarWritingSink(output));
}

For more complex stream transformations, tarWriter can be used as a stream transformer converting a stream of tar entries into archive bytes.

Together with the gzip.encoder transformer from dart:io, this can be used to write a .tar.gz file:

import 'dart:io';
import 'package:tar/tar.dart';

Future<void> write(Stream<TarEntry> entries) {
  return entries
      .transform(tarWriter) // convert entries into a .tar stream
      .transform(gzip.encoder) // convert the .tar stream into a .tar.gz stream
      .pipe(File('output.tar.gz').openWrite());
}

A more complex example for writing files can be found in example/archive_self.dart.

Encoding options

By default, tar files are written in the pax format defined by the POSIX.1-2001 specification (--format=posix in GNU tar). When all entries have file names shorter than 100 chars and a size smaller than 8 GB, this is equivalent to the ustar format. This library won't write PAX headers when there is no reason to do so. If you prefer writing GNU-style long filenames instead, you can use the format option:

Future<void> write(Stream<TarEntry> entries) {
  return entries
      .pipe(
        tarWritingSink(
          File('output.tar').openWrite(),
          format: OutputFormat.gnuLongName,
      ));
}

To change the output format on the tarWriter transformer, use tarWriterWith.

Synchronous writing

As the content of tar entries is defined as an asynchronous stream, the tar encoder is asynchronous too. The more specific SynchronousTarEntry class stores tar content as a list of bytes, meaning that it can be written synchronously.

To synchronously write tar files, use tarConverter (or tarConverterWith for options):

List<int> createTarArchive(Iterable<SynchronousTarEntry> entries) {
  late List<int> result;
  final sink = ByteConversionSink.withCallback((data) => result = data);

  final output = tarConverter.startChunkedConversion(sink);
  entries.forEach(output.add);
  output.close();

  return result;
}

Features

  • Supports v7, ustar, pax, gnu and star archives
  • Supports extended pax headers for long file or link names
  • Supports long file and link names generated by GNU-tar
  • Hardened against denial-of-service attacks with invalid tar files
  • Supports being compiled to JavaScript, tested on Node.js

Security considerations

Internally, this package contains checks to guard against some invalid tar files. In particular,

  • The reader doesn't allocate memory based on values in a tar file (so there's a guard against DoS attacks with tar files containing huge headers).
  • When encountering malformed tar files, the reader will throw a TarException. Any other exception thrown indicates a bug in package:tar or how it's used. The reader should never crash.
  • Reading a tar file can be cancelled mid-stream without leaking resources.

However, the tar reader does not throw exceptions for well-formed archives with suspicious contents, such as

  • File names beginning with ../, / or names pointing out of the archive by other means.
  • Link references to files outside of the archive.
  • Paths not using forward slashes.
  • Gzip + tar bombs.
  • Invalid permission bits in entries.
  • ...

When reading or extracting untrusted tar files, it is your responsibility to detect and handle these cases. For instance, this naive extraction function is susceptible to invalid tar files containing paths outside of the target directory:

Future<void> extractTarGz(File tarGz, Directory target) async {
  final input = tarGz.openRead().transform(gzip.decoder);

  await TarReader.forEach(input, (entry) async {
    final destination =
        // DON'T DO THIS! If `entry.name` contained `../`, this may escape the
        // target directory.
        path.joinAll([target.path, ...path.posix.split(entry.name)]);

    final f = File(destination);
    await f.create(recursive: true);
    await entry.contents.pipe(f.openWrite());
  });
}

For an idea on how to guard against this, see the extraction logic used by the pub client.


Big thanks to Garett Tok Ern Liang for writing the initial Dart tar reader that this library is based on.

所屬分類

依賴

依賴清單 3 項

原始碼儲存庫

使用此套件的專案

所在榜單