presidium 4.8.2 → 4.9.1

package/Docker.js

@@ -16,6 +16,7 @@ const { spawn } = require('child_process')
 const Readable = require('./Readable')
 const HTTP = require('./HTTP')
 const querystring = require('querystring')
+const Archive = require('./internal/Archive')
 const split = require('./internal/split')
 const join = require('./internal/join')
 const isArray = require('./internal/isArray')
@@ -47,9 +48,8 @@ const handleDockerHTTPResponse = require('./internal/handleDockerHTTPResponse')
  *
  * System dependencies:
  *   * `docker`
- *   * `tar`
  *
- * Note: the Presidium Docker client connects to the Docker socket `/var/run/docker.sock`. For security purposes, please avoid exposing any code using the Presidium Docker client to the internet, see [How would an attacker gain access to the host machine from within a Docker container?](https://www.google.com/search?hl=en&q=how+would+an+attacker+gain+access+to+the+host+machine+from+within+a+docker+container&ia=web).
+ * Note: the Presidium Docker client connects to the Docker socket at `/var/run/docker.sock`. For security purposes, please avoid exposing code running the Presidium Docker client to the internet.
  */
 class Docker {
   constructor(options = {}) {
@@ -82,7 +82,7 @@ class Docker {
    * Validates credentials for a Docker container registry. If available, gets an identity token for accessing the registry without password.
    *
    * Arguments:
-   *   * `options` - address used for inter-manager communication that is also advertised to other nodes.
+   *   * `options` - address for inter-manager communication and discovery.
    *     * `username` - authentication credentials.
    *     * `password` - authentication credentials.
    *     * `email` - authentication credentials.
@@ -91,7 +91,7 @@ class Docker {
    * Return:
    *   * `data`
    *     * `Status` - the status message of the authentication
-   *     * `IdentityToken` - a token used to authenticate the user in place of a username and password.
+   *     * `IdentityToken` - a token for authenticating users in place of username and password.
    *
    * ```javascript
    * const docker = new Docker()
@@ -155,7 +155,7 @@ class Docker {
    *     * `Created` - the date and time at which the image was created as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT). 
    *     * `Size` - the total size in bytes of the image including all layers that the image is composed of.
    *     * `SharedSize` - total size of image layers that are shared between the image and other images. `-1` indicates that this value has not been calculated.
-   *     * `Labels` - object of user-defined key/value metadata.
+   *     * `Labels` - object of key-value metadata.
    *     * `Containers` - number of containers using this image. Includes both stopped and running containers. `-1` indicates that this value has not been calculated.
    *     * `Manifests` - list of [image manifests](https://docs.docker.com/reference/cli/docker/manifest/) available in the image. Warning: `Manifests` is experimental and may change at any time without any backward compatibility.
    *     * `Descriptor` - an object containing digest, media type, and size for the image, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md).
@@ -217,20 +217,20 @@ class Docker {
    *   * `data`
    *     * `Id` - the Docker container ID
    *     * `Names` - the names associated with the Docker container.
-   *     * `Image` - the name or ID of the image used to create the Docker container.
-   *     * `ImageID` - the ID of the image used to create the Docker container.
-   *     * `ImageManifestDescriptor` - an object containing digest, media type, and size for the image used to create the Docker container, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md).
+   *     * `Image` - the name or ID of the image of the Docker container.
+   *     * `ImageID` - the ID of the image of the Docker container.
+   *     * `ImageManifestDescriptor` - an object containing digest, media type, and size for the image of the Docker container, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md).
    *     * `Command` - the command to run when starting the Docker container.
    *     * `Created` - the date and time at which the image was created as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT). 
    *     * `Ports` - port-mappings for the Docker container.
    *     * `SizeRw` - the size of files that have been created or changed by the Docker container.
-   *     * `SizeRootFs` - the total size of all files in the read-only layers of the image that are used by the Docker container.
-   *     * `Labels` - object of user-defined key/value metadata.
+   *     * `SizeRootFs` - the total size of all files in the read-only layers of the image of the Docker container.
+   *     * `Labels` - object of key-value metadata.
    *     * `State` - the state of the Docker container.
    *     * `Status` - additional human-readable status of the Docker container, e.g. `'Exit 0'`.
    *     * `HostConfig` - summary of host-specific runtime information of the Docker container.
    *     * `NetworkSettings` - summary of the Docker container's network settings.
-   *     * `Mounts` - list of mounts used by the Docker container.
+   *     * `Mounts` - list of mounts of the Docker container.
    *     * `Health` - summary of the Docker container's health status.
    *
    * ```javascript
@@ -281,7 +281,7 @@ class Docker {
    *     * `password` - authentication credentials.
    *     * `email` - authentication credentials.
    *     * `serveraddress` - domain or IP of the registry server.
-   *     * `identitytoken` - a token used to authenticate the user in place of a username and password.
+   *     * `IdentityToken` - a token for authenticating users in place of username and password.
    *
    * Return:
    *   * `dataStream` - a readable stream of the progress of the Docker `pullImage` operation.
@@ -408,54 +408,12 @@ class Docker {
    *   * [Dockerfile](https://docs.docker.com/engine/reference/builder/)
    */
   async buildImage(path, options = {}) {
-    path = path.endsWith('/') ? path : `${path}/`
-
-    const archiveDir = `presidium-Docker-buildImage-tmp-${uniqid()}`
-
-    await fs.promises.mkdir(archiveDir, { recursive: true })
-
-    const archiveFilename = `${archiveDir}/archive.tar`
-
-    const cmdArgs = []
-
-    cmdArgs.push(`--exclude=${archiveDir}`)
-    if (options.ignore) {
-      for (const pattern of options.ignore) {
-        cmdArgs.push(`--exclude=${pattern}`)
-      }
-    }
-
-    cmdArgs.push('-cf', archiveFilename, '-C', path, '.')
-
-    const cmd = spawn('tar', cmdArgs, { stdio: 'inherit' })
-
-    await new Promise(resolve => {
-      cmd.on('close', resolve)
+    const pack = Archive.tar(path, {
+      base: options.archive,
+      ignore: options.ignore ?? ['node_modules', '.git', '.nyc_output'],
     })
 
-    if (options.archive) {
-      for (const filename in options.archive) {
-        await fs.promises.writeFile(
-          `${archiveDir}/${filename}`, options.archive[filename]
-        )
-
-        const cmdArgs = [
-          '-rf',
-          archiveFilename,
-          `--directory=${archiveDir}`,
-        ]
-
-        cmdArgs.push(filename)
-
-        const cmd = spawn('tar', cmdArgs, { stdio: 'inherit' })
-
-        await new Promise(resolve => {
-          cmd.on('close', resolve)
-        })
-      }
-    }
-
-    const archive = fs.createReadStream(archiveFilename).pipe(zlib.createGzip())
+    const compressed = pack.pipe(zlib.createGzip())
 
     const response = await this.http.post(`/build?${querystring.stringify({
       dockerfile: options.archiveDockerfile ?? 'Dockerfile',
@@ -463,18 +421,13 @@ class Docker {
       forcerm: true,
       platform: options.platform ?? '',
     })}`, {
-      body: archive,
+      body: compressed,
       headers: {
         'Content-Type': 'application/x-tar',
       },
     })
 
     const dataStream = await handleDockerHTTPResponse(response, { stream: true })
-
-    dataStream.on('end', async () => {
-      await fs.promises.rm(archiveDir, { recursive: true })
-    })
-
     return dataStream
   }
 
@@ -508,7 +461,7 @@ class Docker {
    *     * `password` - authentication credentials.
    *     * `email` - authentication credentials.
    *     * `serveraddress` - domain or IP of the registry server.
-   *     * `identitytoken` - a token used to authenticate the user in place of a username and password.
+   *     * `IdentityToken` - a token for authenticating users in place of username and password.
    *
    * Return:
    *   * `dataStream` - a readable stream of the progress of the Docker `pushImage` operation.
@@ -609,13 +562,13 @@ class Docker {
    *     * `Comment` - optional message that was set when committing or importing the image.
    *     * `Created` - the date and time at which the image was created as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT). 
    *     * `Author` - the name of the author that was specified when committing the image.
-   *     * `Config` - the configuration of the image. `Config` fields are used as defaults when starting a container from an image.
+   *     * `Config` - the configuration of the image. `Config` fields are the defaults when starting a container from an image.
    *     * `Architecture` - the CPU architecture that the image runs on.
    *     * `Variant` - a CPU architecture variant.
    *     * `Os` - the operating system that the image is built to run on.
    *     * `OsVersion` - the version of the operating system that the image is built to run on.
    *     * `Size` - the total size in bytes of the image including all layers that the image is composed of.
-   *     * `GraphDriver` - information about the storage driver that stores the filesystem used by the Docker container and the image.
+   *     * `GraphDriver` - information about the storage driver that stores the filesystem of the Docker container and the image.
    *     * `RootFS` - information about the image's RootFS, including the layer IDs.
    *     * `Metadata` - additional metadata of the image in the local cache. This information is not part of the image itself.
    *
@@ -679,12 +632,12 @@ class Docker {
    * }) -> data Promise<Array<{ Untagged: string }|{ Deleted: string }>>
    * ```
    *
-   * Removes a Docker image and any untagged parent images that were referenced by the Docker image from the server. Docker images can't be removed if they have descendant images, are being used by a running container, or are being used by a build.
+   * Removes a Docker image and any untagged parent images that were referenced by the Docker image from the server. Docker images can't be removed if they have descendant images, have a running container, or are being referenced by a build.
    *
    * Arguments:
    *   * `image` - the name or ID of the image to remove.
    *   * `options`
-   *     * `force` - if `true`, removes the image even if it is being used by stopped containers or has other tags. If `false`, the operation will error if the image is being used by stopped containers. Defaults to `false`.
+   *     * `force` - if `true`, removes the image even if it is referenced by stopped containers or has other tags. If `false`, the operation will error if the image is referenced by stopped containers. Defaults to `false`.
    *     * `noprune` - if `true`, the operation will not delete untagged parent images. If `false`, the operation will delete untagged parent images. Defaults to `false`.
    *
    * Return:
@@ -759,7 +712,7 @@ class Docker {
    *     * `image` - the name and tag of the image.
    *     * `rm` - automatically remove the Docker container when it exits.
    *     * `restart` - the restart policy for the Docker container.
-   *     * `logDriver` - the logging driver used for the Docker container.
+   *     * `logDriver` - the logging driver of the Docker container.
    *     * `logDriverOptions` - driver-specific configuration options for the logging driver.
    *     * `publish` - object of mappings of host ports to container ports with optional protocols.
    *     * `healthCmd` - a command that checks the health of the Docker container. The health check fails if the command errors. The command is run inside the Docker container.
@@ -803,7 +756,7 @@ class Docker {
    *   * `image` - mounts a Docker image.
    *   * `npipe` - mounts a named pipe from the host into the Docker container.
    *   * `tmpfs` - create a tmpfs with the given options. The `source` cannot be specified with mount type `tmpfs`.
-   *   * `volume` - creates a volume with the given name and options or uses a pre-existing volume with the same name and options. The volume persists when the Docker container is removed.
+   *   * `volume` - creates or references a volume with the given name and options. The volume persists when the Docker container is removed.
    *
    * ```javascript
    * const docker = new Docker()
@@ -1038,7 +991,7 @@ class Docker {
    *     * `image` - the name and tag of the image.
    *     * `rm` - automatically remove the Docker container when it exits.
    *     * `restart` - the restart policy for the Docker container.
-   *     * `logDriver` - the logging driver used for the Docker container.
+   *     * `logDriver` - the logging driver of the Docker container.
    *     * `logDriverOptions` - driver-specific configuration options for the logging driver.
    *     * `publish` - object of mappings of host ports to container ports with optional protocols.
    *     * `healthCmd` - a command that checks the health of the Docker container. The health check fails if the command errors. The command is run inside the Docker container.
@@ -1080,7 +1033,7 @@ class Docker {
    *   * `image` - mounts a Docker image.
    *   * `npipe` - mounts a named pipe from the host into the Docker container.
    *   * `tmpfs` - create a tmpfs with the given options. The `source` cannot be specified with mount type `tmpfs`.
-   *   * `volume` - creates a volume with the given name and options or uses a pre-existing volume with the same name and options. The volume persists when the Docker container is removed.
+   *   * `volume` - creates or references a volume with the given name and options. The volume persists when the Docker container is removed.
    *
    * ```javascript
    * const docker = new Docker()
@@ -1335,16 +1288,16 @@ class Docker {
    *     * `Id` - the ID of the Docker container.
    *     * `Created` - the date and time at which the Docker container was created as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT). 
    *     * `Path` - the path to the command run by the Docker container.
-   *     * `Args` - the arguments to the command being run by the Docker container.
+   *     * `Args` - the arguments to the command run by the Docker container.
    *     * `State` - `DockerDocs.ContainerState` stores the Docker container's running state.
    *     * `Image` - the ID (digest) of the image that the Docker container was created from.
    *     * `ResolveConfPath` - the location of `/etc/resolve.conf` generated for the Docker container on the host.
    *     * `HostnamePath` - the location of `/etc/hostname` generated for the Docker container on the host.
    *     * `HostsPath` - the location of `/etc/hosts` generated for the Docker container on the host.
-   *     * `LogPath` - the location of the file used to buffer the Docker container's logs.
+   *     * `LogPath` - the location of the file that buffers the Docker container's logs.
    *     * `Name` - the name associated with the Docker container.
    *     * `RestartCount` - the number of times the Docker container was restarted since it was created or since the Docker daemon was started.
-   *     * `Driver` - the storage-driver used for the Docker container's filesystem.
+   *     * `Driver` - the storage-driver of the Docker container's filesystem.
    *     * `Platform` - the platform (operating system) for which the Docker container was created.
    *     * `ImageManifestDescriptor` - an object containing digest, media type, and size for the image from which the Docker container was created, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md).
    *     * `MountLabel` - the SELinux mount label set for the Docker container.
@@ -1352,11 +1305,11 @@ class Docker {
    *     * `AppArmorProfile` - the AppArmor profile set for the Docker container.
    *     * `ExecIDs` - the IDs of exec instances that are running in the Docker container.
    *     * `HostConfig` - host configuration for the Docker container.
-   *     * `GraphDriver` - information about the storage driver that stores the filesystem used by the Docker container and the image.
-   *     * `Storage` - information about the storage used by the Docker container.
+   *     * `GraphDriver` - information about the storage driver that stores the filesystem of the Docker container and the image.
+   *     * `Storage` - information about the storage of the Docker container.
    *     * `SizeRw` - the size of files that have been created or changed by the Docker container.
-   *     * `SizeRootFs` - the total size of all files in the read-only layers of the image that are used by the Docker container.
-   *     * `Mounts` - list of mounts used by the Docker container.
+   *     * `SizeRootFs` - the total size of all files in the read-only layers of the image of the Docker container.
+   *     * `Mounts` - list of mounts of the Docker container.
    *     * `Config` - the configuration of the Docker container.
    *     * `NetworkSettings` - summary of the Docker container's network settings.
    *
@@ -1423,8 +1376,8 @@ class Docker {
    *     * `DefaultAddrPool` - the default subnet pools for global scope networks of the Docker swarm.
    *     * `SubnetSize` - the subnet size of the networks created from the default address pool.
    *     * `JoinTokens` - tokens for worker and manager nodes to join the Docker swarm.
-   *       * `Worker` - the token that worker nodes can use to join the Docker swarm.
-   *       * `Manager` - the token that manager nodes can use to join the Docker swarm.
+   *       * `Worker` - the token for worker nodes to join the Docker swarm.
+   *       * `Manager` - the token for manager nodes to join the Docker swarm.
    *
    * ```javascript
    * const docker = new Docker()
@@ -1451,7 +1404,7 @@ class Docker {
    * Initializes a new Docker swarm.
    *
    * Arguments:
-   *   * `address` - address used for inter-manager communication that is also advertised to other nodes.
+   *   * `address` - address for inter-manager communication and discovery.
    *
    * Return:
    *   * `nodeId` - the ID of the current Docker swarm manager node.
@@ -1492,9 +1445,9 @@ class Docker {
    * Joins the current node (server) to a Docker swarm.
    *
    * Arguments:
-   *   * `address` - address used for inter-manager communication that is also advertised to other nodes.
+   *   * `address` - address for inter-manager communication and discovery.
    *   * `options`
-   *     * `RemoteAddrs` - address or interface for data path traffic. Used to separate data traffic from management traffic.
+   *     * `RemoteAddrs` - address or interface for data path traffic. Separates data traffic from management traffic.
    *     * `JoinToken` - worker or manager token for joining the swarm.
    *
    * Return:
@@ -1624,11 +1577,11 @@ class Docker {
    * Arguments:
    *   * `service` - the Docker service name.
    *   * `options`
-   *     * `image` - the Docker image that will be used by the Docker service.
+   *     * `image` - the Docker image of the Docker service.
    *     * `replicas` - the number of containers that the Docker service will run across all nodes of the Docker swarm. If `replicas` is set to 'global', the Docker service will run containers on each node of the Docker swarm.
    *     * `restart` - the restart policy for the Docker service.
    *     * `restartDelay` - the delay between restarts for the Docker service.
-   *     * `logDriver` - the logging driver used for the Docker service.
+   *     * `logDriver` - the logging driver of the Docker service.
    *     * `logDriverOptions` - driver-specific configuration options for the logging driver.
    *     * `publish` - object of mappings of host ports to Docker service ports with optional protocols.
    *     * `healthCmd` - a command that checks the health of the Docker service. The health check fails if the command errors. The command is run inside each Docker container of the Docker service.
@@ -1659,7 +1612,7 @@ class Docker {
    *     * `password` - authentication credentials.
    *     * `email` - authentication credentials.
    *     * `serveraddress` - domain or IP of the registry server.
-   *     * `identitytoken` - a token used to authenticate the user in place of a username and password.
+   *     * `IdentityToken` - a token for authenticating users in place of username and password.
    *
    * Return:
    *   * `data`
@@ -1906,7 +1859,7 @@ class Docker {
    *     * `replicas` - the number of containers that the Docker service will run across all nodes of the Docker swarm. If `replicas` is set to 'global', the Docker service will run containers on each node of the Docker swarm.
    *     * `restart` - the restart policy for the Docker service.
    *     * `restartDelay` - the delay between restarts for the Docker service.
-   *     * `logDriver` - the logging driver used for the Docker service.
+   *     * `logDriver` - the logging driver of the Docker service.
    *     * `logDriverOptions` - driver-specific configuration options for the logging driver.
    *     * `publish` - object of mappings of host ports to Docker service ports with optional protocols.
    *     * `healthCmd` - a command that checks the health of the Docker service. The health check fails if the command errors. The command is run inside each Docker container of the Docker service.
@@ -2268,12 +2221,12 @@ class Docker {
    *     * `CreatedAt` - the date and time at which the task was created as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT). 
    *     * `UpdatedAt` - the date and time at which the task was updated as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT).
    *     * `Name` - the name of the task.
-   *     * `Labels` - object of user-defined key/value metadata.
+   *     * `Labels` - object of key-value metadata.
    *     * `Spec` - the task configuration.
    *     * `ServiceID` - the ID of the Docker service that the task belongs to.
-   *     * `Slot` - used by the orchestrator for scheduling purposes.
+   *     * `Slot` - for scheduling purposes.
    *     * `NodeID` - the ID of the node that the task is on.
-   *     * `AssignedGenericResources` - user-defined resources.
+   *     * `AssignedGenericResources` - resources.
    *     * `Status` - the status of the task.
    *     * `DesiredState` - the desired status of the task.
    *     * `JobIteration` - the version number of the task.
@@ -2433,7 +2386,7 @@ class Docker {
    * }>
    * ```
    *
-   * Prunes Docker images. Deletes unused Docker images from the server.
+   * Prunes Docker images. Deletes Docker images without containers from the server.
    *
    * Arguments:
    *   * (none)
@@ -2501,7 +2454,7 @@ class Docker {
    * }>
    * ```
    *
-   * Prunes Docker volumes. Deletes unused volumes from the server.
+   * Prunes Docker volumes. Deletes volumes without containers from the server.
    *
    * Arguments:
    *   * (none)
@@ -2578,7 +2531,7 @@ class Docker {
    * Arguments:
    *   * `options`
    *     * `name` - the name of the network to create.
-   *     * `driver` - the name of the network driver plugin to use.
+   *     * `driver` - the name of the network driver plugin.
    *     * `ingress` - if `true`, creates an ingress network. The ingress network is the network that provides the routing-mesh in swarm mode. If `false`, does not create an ingress network.
    *     * `subnet` - the subnet of the network.
    *     * `gateway` - the gateway of the network.
@@ -2668,7 +2621,7 @@ class Docker {
    *     * `Id` - the network ID.
    *     * `Created` - the date and time at which the network was created as seconds since EPOCH (January 1, 1970 at midnight UTC/GMT). 
    *     * `Scope` - the level at which the network exists.
-   *     * `Driver` - the name of the driver used to create the network.
+   *     * `Driver` - the name of the driver of the network.
    *     * `EnableIPv4` - whether the network was created with IPv4 enabled.
    *     * `EnableIPv6` - whether the network was created with IPv6 enabled.
    *     * `IPAM` - the network's IPAM configuration.
@@ -2676,9 +2629,9 @@ class Docker {
    *     * `Attachable` - whether the network is manually attachable by regular containers from worker nodes in a Docker swarm.
    *     * `Ingress` - whether the network is providing the routing-mesh for a Docker swarm.
    *     * `ConfigFrom` - the config-only network source that provides the configuration for the network.
-   *     * `ConfigOnly` - whether the network is a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services.
-   *     * `Options` - network-specific options used when creating the network.
-   *     * `Labels` - object of user-defined key/value metadata.
+   *     * `ConfigOnly` - whether the network is a config-only network. Config-only networks are placeholder networks for network configurations for other networks. Containers and services cannot attach to config-only networks.
+   *     * `Options` - network-specific options for creating the network.
+   *     * `Labels` - object of key-value metadata.
    *     * `Peers` - list of peer nodes for the network. `Peers` is only present if the network is an overlay network.
    *
    * ```javascript

package/HTTP.js

@@ -57,6 +57,10 @@ const httpConfigure = require('./internal/httpConfigure')
  */
 class HTTP {
   constructor(baseUrl, requestOptions = {}) {
+    if (typeof baseUrl == "string" && !baseUrl.startsWith("http")) {
+      baseUrl = `http://${baseUrl}`
+    }
+
     if (
       typeof baseUrl == 'string'
       || typeof baseUrl?.toString == 'function'

package/internal/Archive.js

@@ -0,0 +1,118 @@
+require('rubico/global')
+const tarStream = require('tar-stream')
+const fs = require('fs')
+const walk = require('./walk')
+
+/**
+ * @name Archive
+ */
+const Archive = {
+
+  /**
+   * @name tar
+   *
+   * @docs
+   * ```coffeescript [specscript]
+   * module tar 'https://github.com/mafintosh/tar-stream'
+   *
+   * Archive.tar(path string, options {
+   *   ignore: Array<string>,
+   *   base: Object<string>,
+   * }) -> pack tar.Pack
+   * ```
+   *
+   * Bundle multiple files and directories from a parent directory into a tarball.
+   *
+   * Arguments:
+   *   * `path` - the path to the parent directory which contains the files and directories to bundle.
+   *   * `options`
+   *     * `ignore` - filepaths, filenames, or patterns to ignore.
+   */
+  tar(path, options) {
+    path = path.endsWith('/') ? path : `${path}/`
+    const ignore = get(options, 'ignore')
+    const pack = tarStream.pack()
+
+    pipe(
+      walk(path),
+
+      filter(path => {
+        for (const part of ignore) {
+          if (path.includes(part)) {
+            return false
+          }
+        }
+        return true
+      }),
+
+      reduce(async (pack, filepath) => {
+        const stats = await pipe(filepath, [
+          fs.promises.stat,
+          pick(['size', 'mode', 'mtime', 'uid', 'gid']),
+        ])
+
+        const entry = pack.entry({ ...stats, name: filepath.replace(path, '') })
+
+        const fileStream = fs.createReadStream(filepath)
+
+        fileStream.pipe(entry)
+
+        await new Promise(resolve => {
+          fileStream.on('end', resolve)
+        })
+
+        return pack
+      }, pack),
+
+      tap(pack => {
+        const base = options.base ?? {}
+        for (const filename in base) {
+          pack.entry({ name: filename }, base[filename])
+        }
+        pack.finalize()
+      }),
+    )
+
+    return pack
+  },
+
+  /**
+   * @name untar
+   *
+   * @docs
+   * ```coffeescript [specscript]
+   * module tar 'https://github.com/mafintosh/tar-stream'
+   * module Readable 'https://presidium.services/Readable'
+   *
+   * Archive.untar(pack tar.Pack) ->
+   *   contentMap Promise<Map<(filepath string)=>(content Readable)> >
+   * ```
+   *
+   * Extract a tarball into a map of file paths to content streams.
+   *
+   * Arguments:
+   *   * `pack` - a tarball represented by the `tar.Pack` type. Returned by the [tar](#tar) method.
+   */
+  untar(pack) {
+    const extractStream = tarStream.extract()
+    const extracted = new Map()
+    return new Promise((resolve, reject) => {
+      extractStream.on('entry', (header, stream, next) => {
+        stream.header = header
+        extracted.set(header.name, stream)
+        next()
+      })
+
+      extractStream.on('finish', () => {
+        resolve(extracted)
+      })
+
+      extractStream.on('error', reject)
+
+      pack.pipe(extractStream)
+    })
+  },
+
+}
+
+module.exports = Archive

package/internal/Archive.test.js

@@ -0,0 +1,78 @@
+const assert = require('assert')
+const stream = require('stream')
+const fs = require('fs/promises')
+const Test = require('thunk-test')
+const Archive = require('./Archive')
+const resolvePath = require('./resolvePath')
+const map = require('rubico/map')
+const reduce = require('rubico/reduce')
+const Readable = require('../Readable')
+
+const test = new Test('Archive', async function integration() {
+
+  {
+    const pack = await Archive.tar(__dirname, {
+      ignore: ['Dockerfile', 'node_modules', '.git', '.nyc_output'],
+    })
+    const extracted = await Archive.untar(pack)
+    assert(extracted.size > 0)
+    for (const [path, entry] of extracted) {
+      assert('header' in entry)
+      assert(!path.startsWith('/'))
+      assert.equal(typeof path, 'string')
+      assert.equal(typeof entry[Symbol.asyncIterator], 'function')
+      assert(entry.readable)
+    }
+  }
+
+  {
+    const base = {
+      Dockerfile: 'FROM node:15-alpine'
+    }
+    const ignore = ['fixtures', 'tmp', 'google-chrome-for-testing']
+    const pack = await Archive.tar(__dirname, { ignore, base })
+    const extracted = await Archive.untar(pack)
+    const dir = await fs.readdir(__dirname)
+      .then(filter(filepath => {
+        for (const part of ignore) {
+          if (filepath.includes(part)) {
+            return false
+          }
+        }
+        return true
+      }))
+    const extractedKeys = [...extracted.keys()]
+    assert.equal(extracted.size, dir.length + 1) // extra Dockerfile
+    assert(extracted.has('Dockerfile'))
+    assert.equal(
+      await reduce(extracted.get('Dockerfile'), (a, b) => a + b, ''),
+      'FROM node:15-alpine'
+    )
+  }
+
+  {
+    const base = {
+      Dockerfile: 'FROM busybox:1.32',
+      '.aws/credentials': '[presidium]\naccessKeyId\nsecretAccessKey',
+    }
+    const pack = await Archive.tar(`${__dirname}/`, {
+      ignore: ['hashJSON.js'],
+      base,
+    })
+    const extracted = await Archive.untar(pack)
+    assert(extracted.size > 0)
+    assert(extracted.has('Dockerfile'))
+    assert(extracted.has('.aws/credentials'))
+    assert.equal(
+      await reduce(extracted.get('Dockerfile'), (a, b) => a + b, ''),
+      'FROM busybox:1.32'
+    )
+  }
+
+}).case()
+
+if (process.argv[1] == __filename) {
+  test()
+}
+
+module.exports = test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "presidium",
-  "version": "4.8.2",
+  "version": "4.9.1",
   "description": "The Presidium library.",
   "author": "Richard Tong",
   "license": "CFOSS",
@@ -71,6 +71,7 @@
     "presidium-db-client-server": ">=0.6.6",
     "presidium-websocket": ">=4.2.2",
     "rubico": "^2.21.0",
+    "tar-stream": "^3.2.2",
     "uniqid": "^5.4.0"
   },
   "scripts": {