Add TAR_* error codes

This adds error codes to all of the warnings emitted by tar operations,
tests for several error conditions, and handling for errors raised by
close(2).

BREAKING CHANGES:
- The `warn` event now emits with 3 arguments (code, message, data)
  rather than 2 (message, data).
- The `data` argument to the warn event handler is always an object,
  (either an Error or a plain old JavaScript object) rather than
  sometimes being a string or undefined.
- Failures from `fs.close()` are tracked and emitted.

Author: isaacs

README.md

@@ -63,23 +63,93 @@ that all of the data is immediately available by calling
 `stream.read()`.  For writable streams, it will be acted upon as soon
 as it is provided, but this can be at any time.
 
-### Warnings
-
-Some things cause tar to emit a warning, but should usually not cause
-the entire operation to fail.  There are three ways to handle
-warnings:
-
-1. **Ignore them** (default) Invalid entries won't be put in the
-   archive, and invalid entries won't be unpacked.  This is usually
-   fine, but can hide failures that you might care about.
-2. **Notice them**  Add an `onwarn` function to the options, or listen
-   to the `'warn'` event on any tar stream.  The function will get
-   called as `onwarn(message, data)`.  Handle as appropriate.
-3. **Explode them.**  Set `strict: true` in the options object, and
-   `warn` messages will be emitted as `'error'` events instead.  If
-   there's no `error` handler, this causes the program to crash.  If
-   used with a promise-returning/callback-taking method, then it'll
-   send the error to the promise/callback.
+### Warnings and Errors
+
+Tar emits warnings and errors for recoverable and unrecoverable situations,
+respectively.  In many cases, a warning only affects a single entry in an
+archive, or is simply informing you that it's modifying an entry to comply
+with the settings provided.
+
+Unrecoverable warnings will always raise an error (ie, emit `'error'` on
+streaming actions, throw for non-streaming sync actions, reject the
+returned Promise for non-streaming async operations, or call a provided
+callback with an `Error` as the first argument).  Recoverable errors will
+raise an error only if `strict: true` is set in the options.
+
+Respond to (recoverable) warnings by listening to the `warn` event.
+Handlers receive 3 arguments:
+
+- `code` String.  One of the error codes below.  This may not match
+  `data.code`, which preserves the original error code from fs and zlib.
+- `message` String.  More details about the error.
+- `data` Metadata about the error.  An `Error` object for errors raised by
+  fs and zlib.  All fields are attached to errors raisd by tar.  Typically
+  contains the following fields, as relevant:
+  - `tarCode` The tar error code.
+  - `code` Either the tar error code, or the error code set by the
+    underlying system.
+  - `file` The archive file being read or written.
+  - `cwd` Working directory for creation and extraction operations.
+  - `entry` The entry object (if it could be created) for `TAR_ENTRY_INFO`,
+    `TAR_ENTRY_INVALID`, and `TAR_ENTRY_ERROR` warnings.
+  - `header` The header object (if it could be created, and the entry could
+    not be created) for `TAR_ENTRY_INFO` and `TAR_ENTRY_INVALID` warnings.
+  - `recoverable` Boolean.  If `false`, then the warning will emit an
+    `error`, even in non-strict mode.
+
+#### Error Codes
+
+* `TAR_ENTRY_INFO`  An informative error indicating that an entry is being
+  modified, but otherwise processed normally.  For example, removing `/` or
+  `C:\` from absolute paths if `preservePaths` is not set.
+
+* `TAR_ENTRY_INVALID` An indication that a given entry is not a valid tar
+  archive entry, and will be skipped.  This occurs when:
+  - a checksum fails,
+  - a `linkpath` is missing for a link type, or
+  - a `linkpath` is provided for a non-link type.
+
+  If every entry in a parsed archive raises an `TAR_ENTRY_INVALID` error,
+  then the archive is presumed to be unrecoverably broken, and
+  `TAR_BAD_ARCHIVE` will be raised.
+
+* `TAR_ENTRY_ERROR` The entry appears to be a valid tar archive entry, but
+  encountered an error which prevented it from being unpacked.  This occurs
+  when:
+  - an unrecoverable fs error happens during unpacking,
+  - an entry has `..` in the path and `preservePaths` is not set, or
+  - an entry is extracting through a symbolic link, when `preservePaths` is
+    not set.
+
+* `TAR_ENTRY_UNSUPPORTED`  An indication that a given entry is
+  a valid archive entry, but of a type that is unsupported, and so will be
+  skipped in archive creation or extracting.
+
+* `TAR_ABORT`  When parsing gzipped-encoded archives, the parser will
+  abort the parse process raise a warning for any zlib errors encountered.
+  Aborts are considered unrecoverable for both parsing and unpacking.
+
+* `TAR_BAD_ARCHIVE`  The archive file is totally hosed.  This can happen for
+  a number of reasons, and always occurs at the end of a parse or extract:
+
+  - An entry body was truncated before seeing the full number of bytes.
+  - The archive contained only invalid entries, indicating that it is
+    likely not an archive, or at least, not an archive this library can
+    parse.
+
+  `TAR_BAD_ARCHIVE` is considered informative for parse operations, but
+  unrecoverable for extraction.  Note that, if encountered at the end of an
+  extraction, tar WILL still have extracted as much it could from the
+  archive, so there may be some garbage files to clean up.
+
+Errors that occur deeper in the system (ie, either the filesystem or zlib)
+will have their error codes left intact, and a `tarCode` matching one of
+the above will be added to the warning metadata or the raised error object.
+
+Errors generated by tar will have one of the above codes set as the
+`error.code` field as well, but since errors originating in zlib or fs will
+have their original codes, it's better to read `error.tarCode` if you wish
+to see how tar is handling the issue.
 
 ### Examples
 
@@ -201,8 +271,8 @@ The following options are supported:
   and a file is not provided, then the resulting stream will already
   have the data ready to `read` or `emit('data')` as soon as you
   request it.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `strict` Treat warnings as crash-worthy errors.  Default false.
 - `cwd` The current working directory for creating the archive.
   Defaults to `process.cwd()`.  [Alias: `C`]
@@ -297,8 +367,8 @@ The following options are supported:
   Pathnames with fewer elements will be silently skipped.  Note that
   the pathname is edited after applying the filter, but before
   security checks. [Alias: `strip-components`, `stripComponents`]
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `preserveOwner` If true, tar will set the `uid` and `gid` of
   extracted entries to the `uid` and `gid` fields in the archive.
   This defaults to true when run as root, and false otherwise.  If
@@ -401,8 +471,8 @@ The following options are supported:
   filename. [Alias: `f`]
 - `sync` Act synchronously.  If this is set, then any provided file
   will be fully written after the call to `tar.c`.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `strict` Treat warnings as crash-worthy errors.  Default false.
 - `cwd` The current working directory for adding entries to the
   archive.  Defaults to `process.cwd()`.  [Alias: `C`]
@@ -452,8 +522,8 @@ The following options are supported:
   filename. [Alias: `f`]
 - `sync` Act synchronously.  If this is set, then any provided file
   will be fully written after the call to `tar.c`.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `strict` Treat warnings as crash-worthy errors.  Default false.
 - `cwd` The current working directory for adding entries to the
   archive.  Defaults to `process.cwd()`.  [Alias: `C`]
@@ -499,8 +569,8 @@ Has all the standard readable stream interface stuff.  `'data'` and
 
 The following options are supported:
 
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `strict` Treat warnings as crash-worthy errors.  Default false.
 - `cwd` The current working directory for creating the archive.
   Defaults to `process.cwd()`.
@@ -595,8 +665,8 @@ Most unpack errors will cause a `warn` event to be emitted.  If the
   Pathnames with fewer elements will be silently skipped.  Note that
   the pathname is edited after applying the filter, but before
   security checks.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `umask` Filter the modes of entries like `process.umask()`.
 - `dmode` Default mode for directories
 - `fmode` Default mode for files
@@ -634,8 +704,8 @@ Most unpack errors will cause a `warn` event to be emitted.  If the
 - `strict` Treat warnings as crash-worthy errors.  Default false.
 - `onentry` A function that gets called with `(entry)` for each entry
   that passes the filter.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 
 ### class tar.Unpack.Sync
 
@@ -674,13 +744,13 @@ The following options are supported:
   archive, or `false` to skip it.
 - `onentry` A function that gets called with `(entry)` for each entry
   that passes the filter.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 
-#### abort(message, error)
+#### abort(error)
 
 Stop all parsing activities.  This is called when there are zlib
-errors.  It also emits a warning with the message and error provided.
+errors.  It also emits an unrecoverable warning with the error provided.
 
 ### class tar.ReadEntry extends [MiniPass](http://npm.im/minipass)
 
@@ -781,8 +851,8 @@ The following options are supported:
 - `strict` Treat warnings as crash-worthy errors.  Default false.
 - `win32` True if on a windows platform.  Causes behavior where paths
   replace `\` with `/`.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `noMtime` Set to true to omit writing `mtime` values for entries.
   Note that this prevents using other mtime-based features like
   `tar.update` or the `keepNewer` option with the resulting tar archive.
@@ -818,8 +888,8 @@ The following options are supported:
 - `preservePaths` Allow absolute paths.  By default, `/` is stripped
   from absolute paths.
 - `strict` Treat warnings as crash-worthy errors.  Default false.
-- `onwarn` A function that will get called with `(message, data)` for
-  any warnings encountered.
+- `onwarn` A function that will get called with `(code, message, data)` for
+  any warnings encountered.  (See "Warnings and Errors")
 - `noMtime` Set to true to omit writing `mtime` values for entries.
   Note that this prevents using other mtime-based features like
   `tar.update` or the `keepNewer` option with the resulting tar archive.

lib/pack.js

@@ -62,6 +62,7 @@ const Pack = warner(class Pack extends MiniPass {
     super(opt)
     opt = opt || Object.create(null)
     this.opt = opt
+    this.file = opt.file || ''
     this.cwd = opt.cwd || process.cwd()
     this.maxReadSize = opt.maxReadSize
     this.preservePaths = !!opt.preservePaths
@@ -285,9 +286,7 @@ const Pack = warner(class Pack extends MiniPass {
 
   [ENTRYOPT] (job) {
     return {
-      onwarn: (msg, data) => {
-        this.warn(msg, data)
-      },
+      onwarn: (code, msg, data) => this.warn(code, msg, data),
       noPax: this.noPax,
       cwd: this.cwd,
       absolute: job.absolute,