@lakutata/docker 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+# @lakutata/docker
+
+The Docker component of the lakutata framework: it drives a Docker daemon over the Docker Engine API, without the
+Docker CLI, to pull, build (with BuildKit), import, export, tag and push images, to create, run and manage containers
+(exec, interactive TTYs, logs, stats, commit, file export) and to manage networks. It connects to a local socket, or to
+a remote daemon over HTTP, HTTPS or SSH. The umbrella package `lakutata` re-exports it as `lakutata/com/docker`.
+
+## Installation
+
+```shell
+npm install lakutata
+```
+
+The component needs a Docker daemon (Docker Engine or Docker Desktop, Engine API 1.41 or newer) reachable from the
+application; no Docker CLI is needed locally. The SSH connections use the optional peer dependency `ssh2`, and the
+Docker CLI on the remote host:
+
+```shell
+npm install ssh2
+```
+
+| Connection | Options | Needs |
+|---|---|---|
+| The Docker of the environment (default) | none: `DOCKER_HOST`, `DOCKER_TLS_VERIFY`, `DOCKER_CERT_PATH`, `DOCKER_CLIENT_TIMEOUT`, else the local socket | nothing |
+| Unix socket / Windows named pipe | `socketPath` (`buildDockerSocketConnectionOptions`) | access to the socket (the `docker` group) |
+| TCP, plain HTTP | `host`, `port` (`buildDockerHttpConnectionOptions`) | a daemon listening on TCP (`-H tcp://0.0.0.0:2375`) |
+| TCP, HTTPS | `host`, `port`, `ca`, `cert`, `key` as PEM contents (`buildDockerHttpsConnectionOptions`) | a daemon with TLS (`--tlsverify`) |
+| SSH | `host`, `port`, `username`, `sshAuthAgent` (`buildDockerSSHConnectionOptions`) | `ssh2` locally; the Docker CLI remotely; a key in the SSH agent |
+
+## Usage
+
+### The component in an application
+
+Register `Docker` in the `components` of the application, then get it with `getObject()` or `@Inject`. When it is
+created, the component pings the daemon and negotiates the API version: an unreachable daemon fails the launch with
+`DockerConnectionException`.
+
+```typescript
+import {Application} from 'lakutata'
+import {Docker, type DockerContainer, type DockerImage} from 'lakutata/com/docker'
+
+Application
+    .run(() => ({
+        id: 'docker.app',
+        name: 'Docker',
+        components: {
+            //The Docker of the environment: DOCKER_HOST, else the local socket
+            docker: {class: Docker}
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const docker: Docker = await app.getObject('docker')
+
+        //Pulled, then looked up as alpine:3.20
+        const image: DockerImage = await docker.pullImage({repo: 'alpine', tag: '3.20'})
+
+        //Created, then started
+        const container: DockerContainer = await image.run({
+            name: 'hello',
+            cmd: ['sh', '-c', 'echo started; sleep 3600'],
+            env: {MODE: 'production'}
+        })
+        console.log(container.id, container.state.status)
+
+        //The exit code, stdout and stderr
+        const {exitCode, stdout} = await container.exec({cmd: ['cat', '/etc/alpine-release']})
+        console.log(exitCode, stdout)
+
+        await container.stop({timeout: 10})
+        await container.remove()
+    })
+```
+
+### Connections
+
+```typescript
+import {readFileSync} from 'node:fs'
+import {Application} from 'lakutata'
+import {
+    buildDockerHttpsConnectionOptions,
+    buildDockerSocketConnectionOptions,
+    buildDockerSSHConnectionOptions,
+    Docker
+} from 'lakutata/com/docker'
+
+Application.run(() => ({
+    id: 'docker.app',
+    name: 'Docker',
+    components: {
+        //A socket, with a request timeout of 60 s
+        local: buildDockerSocketConnectionOptions({socketPath: '/var/run/docker.sock', timeout: 60000}),
+        //TLS: the PEM contents, not the file paths
+        remote: buildDockerHttpsConnectionOptions({
+            host: 'docker.example.com',
+            port: 2376,
+            ca: readFileSync('/etc/docker/certs/ca.pem'),
+            cert: readFileSync('/etc/docker/certs/cert.pem'),
+            key: readFileSync('/etc/docker/certs/key.pem')
+        }),
+        //SSH: authenticated by the SSH agent (SSH_AUTH_SOCK)
+        builder: buildDockerSSHConnectionOptions({host: 'build.example.com', port: 22, username: 'deploy'}),
+        //The options as they are, with a fixed API version
+        pinned: {class: Docker, version: '1.47'}
+    }
+}))
+```
+
+- Without `socketPath` nor `host`, the component connects to the Docker of the environment, with the other options
+  given (`timeout`, `headers`, `version`…) applied over the environment's.
+- `protocol` defaults to `'https'` when `ca`, `cert` and `key` are all given, to `'http'` otherwise.
+- `timeout` (milliseconds) is the time a request may stay idle; it also ends the streams (followed logs) idle for that
+  long.
+
+### Images
+
+```typescript
+import {createReadStream} from 'node:fs'
+import {type Docker, type DockerImage} from 'lakutata/com/docker'
+
+declare const docker: Docker
+
+//Pull, with the registry's credentials and the progress messages
+const node: DockerImage = await docker.pullImage({
+    repo: 'registry.example.com/base/node',
+    tag: '22',
+    platform: 'linux/amd64',
+    auth: {serverAddress: 'registry.example.com', username: 'ci', password: 'secret'},
+    outputCallback: (output: Record<string, any>): void => console.log(output.status, output.progress ?? '')
+})
+
+//Build with BuildKit: the context is the files listed (directories with their content), minus .dockerignore
+const app: DockerImage = await docker.buildImage({
+    workdir: '/srv/app',
+    files: ['Dockerfile', 'package.json', 'src'],
+    repoTag: 'app:1.0.0',
+    buildargs: {NODE_ENV: 'production'},
+    outputCallback: (output: Record<string, any>): void => console.log(output.stream ?? '')
+})
+
+//Tag, push, save to an archive, load it back
+await app.tag({repo: 'registry.example.com/team/app', tag: '1.0.0'})
+await app.push({repo: 'registry.example.com/team/app', tag: '1.0.0', auth: {serverAddress: 'registry.example.com', username: 'ci', password: 'secret'}})
+await app.export({destination: '/tmp/app.tar', repoTag: 'app:1.0.0'})
+const loaded: DockerImage = await docker.importImage({source: createReadStream('/tmp/app.tar')})
+
+//Look up by ID, short ID or name, list, remove (forced by default), prune
+console.log((await docker.getImage('app:1.0.0')).id, loaded.repoTags, node.platform)
+console.log((await docker.listImages()).map((image: DockerImage): string[] => image.repoTags))
+await app.remove()
+await docker.prune({containers: false, images: true, networks: false, volumes: false})
+```
+
+- `getImage()` resolves the names as the daemon does: the full or short ID, `alpine` for `alpine:latest`,
+  `docker.io/library/alpine:3.20`, a digest; `pullImage()` finds the image pulled the same way.
+- `listImages()` inspects every image: one request per image.
+- `prune()` without options prunes the stopped containers and the dangling images; the unused networks and anonymous
+  volumes only when asked (`networks: true`, `volumes: true`).
+- The registry credentials (`auth`) are sent whole, the tokens (`identityToken`, `registryToken`) included, by the
+  pulls, the builds, the pushes and `loginRepository()`.
+
+### Containers
+
+```typescript
+import {createWriteStream} from 'node:fs'
+import {type Docker, type DockerContainer, type DockerContainerTTY, type DockerImage} from 'lakutata/com/docker'
+
+declare const docker: Docker
+
+const image: DockerImage = await docker.getImage('nginx:1.27')
+//Created, not started
+const web: DockerContainer = await docker.createContainer(image.id, {
+    name: 'web',
+    hostname: 'web',
+    ports: [{port: 80, type: 'tcp', hostPorts: [8080]}],
+    binds: [{hostPath: '/srv/www', containerPath: '/usr/share/nginx/html', rw: false}],
+    networks: [{networkName: 'backend', ip: '172.30.0.10'}],
+    memoryLimit: 256 * 1024 * 1024,
+    cpuSet: [0, 1],
+    restartPolicy: 'unless-stopped'
+})
+await web.start()
+
+//The logs so far (follow: true keeps the stream open while the container runs)
+const logs: NodeJS.ReadableStream = await web.logs({follow: false, tail: 100, timestamps: true})
+logs.pipe(process.stdout)
+
+//One sample of CPU, memory, network and block I/O
+console.log(await web.stats())
+
+//A command line (run by /bin/sh -c), and its exit code
+const {exitCode, stdout, stderr} = await web.exec({cmd: 'nginx -t && ls /etc/nginx | wc -l'})
+console.log(exitCode, stdout, stderr)
+
+//An interactive shell with a TTY (/bin/sh by default)
+const tty: DockerContainerTTY = await web.createTTY({consoleSize: {cols: 120, rows: 40}})
+tty.onData((chunk: Buffer): void => {
+    process.stdout.write(chunk)
+})
+tty.write('nginx -v\n')
+await tty.resize({cols: 160, rows: 50})
+tty.write('exit\n')
+
+//A directory of the container as a tar archive; an image of its files
+await web.exportDirectory({path: '/etc/nginx', destination: createWriteStream('/tmp/nginx-conf.tar')})
+const snapshot: DockerImage = await web.commit({repoTag: 'web-snapshot:1'})
+console.log(snapshot.id)
+
+//The limits and the restart policy changed live; the other settings by recreating the container (its ID changes)
+await web.update({memoryLimit: 512 * 1024 * 1024, restartPolicy: 'on-failure:3'})
+await web.update({env: {TZ: 'UTC'}})
+
+await web.restart({timeout: 5})
+await web.kill({signal: 'SIGHUP'})
+await web.pause()
+await web.unpause()
+await web.stop()
+await web.remove({force: true})
+
+//All the containers, the stopped ones included
+console.log((await docker.listContainers()).map((container: DockerContainer): string => `${container.name}: ${container.state.status}`))
+```
+
+- A `DockerContainer` is a snapshot: its operations refresh it, the changes made by others are seen by getting it again
+  (`docker.getContainer(id)`, which also takes a name or a short ID). A container whose image was removed with force is
+  read without it: its `image` is `undefined`.
+- Starting a running container or stopping a stopped one does nothing, as the Docker CLI.
+- `exec()` runs without TTY nor stdin and resolves with `{exitCode, stdout, stderr}`, whatever the exit code (as the
+  containerd component's). An array command runs as it is; a string is a command line, run by `/bin/sh -c`.
+- `createTTY()` runs `/bin/sh` by default; its `cmd` follows the rules of `exec()`. Its write failures are logged by the
+  application's `log` component, else by the console.
+- `kill()` sends `SIGKILL` by default, or the signal given (`'SIGHUP'`, `15`).
+- `update()` changes the memory limit, the CPUs and the restart policy live, and the name by renaming the container.
+  The other settings recreate it from its whole configuration (command, mounts, networks, the anonymous volumes
+  mounted again): created under a temporary name, it replaces the old one only once created (and started, when the
+  old one ran), so a failure leaves the old one as it was. Its ID changes; its files outside the volumes are not kept.
+- `state.startedAt` and `state.finishedAt` are `null` when the container was never started or never exited.
+- Not provided: attaching to the main process, copying files into a container, the volumes (other than by `prune()`)
+  and the daemon's events.
+
+### Networks
+
+```typescript
+import {type Docker, type NetworkInfo} from 'lakutata/com/docker'
+
+declare const docker: Docker
+
+const network: NetworkInfo = await docker.createNetwork({
+    name: 'backend',
+    driver: 'bridge',
+    NetworkIPAMConfigs: [{subnet: '172.30.0.0/16', gateway: '172.30.0.1'}],
+    internal: false
+})
+//The subnet chosen by the daemon
+await docker.createNetwork({name: 'frontend'})
+console.log(network.id, network.IPAMConfigs)
+//The drivers as Docker reports them: bridge, host, null, overlay…
+console.log((await docker.listNetworks()).map((item: NetworkInfo): string => `${item.name}: ${item.driver}`))
+//By ID, short ID or name
+console.log((await docker.getNetwork('frontend')).id)
+await docker.removeNetwork('frontend')
+await docker.removeNetwork(network.id)
+```
+
+## API
+
+| Export | What it is |
+|---|---|
+| `Docker` | The component: `pullImage`, `buildImage`, `importImage`, `getImage`, `listImages`, `createContainer`, `getContainer`, `listContainers`, `createNetwork`, `getNetwork`, `listNetworks`, `removeNetwork`, `prune`, `loginRepository`, `checkRepositoryAuth`; the connection options |
+| `DockerImage` | An image: `id`, `repoTags`, `platform`, `size`, `config`; `tag()`, `export()`, `push()`, `remove()`, `run()` |
+| `DockerContainer` | A container: its settings and `state`; `start()`, `stop()`, `restart()`, `pause()`, `unpause()`, `kill()`, `remove()`, `update()`, `commit()`, `exec()`, `createTTY()`, `logs()`, `stats()`, `exportDirectory()` |
+| `DockerContainerTTY` | An interactive command with a TTY: `raw`, `readable`, `writable`, `onData()`, `write()`, `resize()` |
+| `buildDockerConnectionOptions`, `buildDockerSocketConnectionOptions`, `buildDockerHttpConnectionOptions`, `buildDockerHttpsConnectionOptions`, `buildDockerSSHConnectionOptions` | Build the component options for each kind of connection |
+| `IDockerConnectionOptions`, `IDockerSocketConnectionOptions`, `IDockerHttpConnectionOptions`, `IDockerHttpsConnectionOptions`, `IDockerSSHConnectionOptions`, `IDockerKeyObject` | The connection options |
+| `ImagePullOptions`, `ImageBuildOptions`, `ImageImportOptions`, `ImageExportOptions`, `ImageTagOptions`, `ImagePushOptions`, `ImageRemoveOptions` | The options of the image operations |
+| `ContainerSettingOptions`, `ContainerStopOptions`, `ContainerKillOptions`, `ContainerRemoveOptions`, `ContainerCommitOptions`, `ContainerExecOptions`, `ContainerCreateTTYOptions`, `ContainerTTYConsoleSizeOptions`, `ContainerLogsOptions`, `ContainerExportDirectoryOptions` | The options of the container operations |
+| `NetworkCreateOptions`, `DockerPruneOptions`, `DockerAuthOptions` | The options of the networks, of `prune()`, and the registry credentials |
+| `ContainerState`, `ContainerPort`, `ContainerBind`, `ContainerDevice`, `ContainerNetwork`, `ContainerCapability`, `ContainerRestartPolicy`, `ContainerStats`, `ContainerConfig`, `ContainerExecResult` | The types of the containers, and the result of `exec()` |
+| `ImageConfig`, `ImageExposePort`, `RepositoryTag`, `NetworkInfo`, `DockerOutputCallback` | The types of the images, the networks and the progress messages |
+| `parseRepositoryTag`, `parseEnvToRecord` | Split an image reference into repository and tag; turn `NAME=value` entries into a record |
+| `DockerConnectionException`, `DockerContainerNotFoundException`, `DockerImageNotFoundException`, `DockerImagePullException`, `DockerImageBuildException`, `DockerImageImportException`, `DockerImagePushException`, `DockerImageRepoTagNotFoundException`, `DockerNetworkNotFoundException`, `DockerRequestException` | The exceptions |
+
+All are exported by `lakutata/com/docker` and `@lakutata/docker`. The typings document each declaration with examples.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `DockerConnectionException` (`E_DOCKER_CONNECTION`) | The component's creation: the daemon unreachable or not answering, the TLS handshake failing, SSH without `ssh2` |
+| `DockerContainerNotFoundException` (`E_DOCKER_CONTAINER_NOT_FOUND`) | `getContainer()` finds no container with this ID, short ID or name; an operation of a container removed |
+| `DockerImageNotFoundException` (`E_DOCKER_IMAGE_NOT_FOUND`) | `getImage()` finds no image with this ID or name; `createContainer()` (or the recreation of `update()`) of a missing image; an operation of an image removed |
+| `DockerImagePullException` (`E_DOCKER_IMAGE_PULL`) | `pullImage()` fails, or the component is destroyed during the pull |
+| `DockerImageBuildException` (`E_DOCKER_IMAGE_BUILD`) | `buildImage()` fails: a step, a missing file, a base image which cannot be pulled, the component destroyed during the build |
+| `DockerImageImportException` (`E_DOCKER_IMAGE_IMPORT`) | `importImage()`: the daemon rejects the archive, or the loaded image is unknown |
+| `DockerImagePushException` (`E_DOCKER_IMAGE_PUSH`) | `push()`: the registry refuses the push |
+| `DockerImageRepoTagNotFoundException` (`E_DOCKER_IMAGE_REPO_TAG_NOT_FOUND`) | `export()` of a tag the image does not have, with `createRepoTagIfNotExists: false` |
+| `DockerNetworkNotFoundException` (`E_DOCKER_NETWORK_NOT_FOUND`) | `getNetwork()` or `removeNetwork()` with an ID, short ID or name no network has; a container created or recreated on a missing network |
+| `DockerRequestException` (`E_DOCKER_REQUEST`) | The daemon refuses a request and no exception above fits: its `statusCode` is the HTTP status (409 a name already used or a container not running, 401 credentials refused by `loginRepository()`, 400 an invalid setting, 500…), its message the daemon's |
+| `InvalidMethodAcceptException` (from `lakutata`) | The options of a call are invalid |
+| The errors of Node.js | The daemon becomes unreachable after the component's creation (`ECONNREFUSED`…); the `source` file of `importImage()` cannot be read (`ENOENT`…) |
+
+When the component is destroyed (the application stopping), the pulls and builds in progress are aborted and reject
+with their exception; the listings in progress resolve with an empty list.
+
+## See also
+
+- `doc/en/DockerIntegration.md` of the package `lakutata` (Chinese in `doc/zh`): the guide of the Docker integration.
+- `@lakutata/containerd` (`lakutata/com/containerd`): the same API without a Docker daemon, over containerd.
+- `@lakutata/core` (`lakutata`): the components, `Application` and the dependency injection.
+- `npm run test:docker` (in this package) tests the component against the Docker of the machine.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,299 @@
+# Third-party notices
+
+Parts of `@lakutata/docker` are derived from the third-party projects listed below. They are rewritten in TypeScript
+and modified; the original copyright notices and license terms are reproduced here as required.
+
+## dockerode 4.0.9
+
+Copyright Pedro Dias. Licensed under the Apache License, Version 2.0 (reproduced below).
+
+The operations of the Docker Engine API: `src/client/DockerClient.ts`, and the preparation of the build contexts:
+`src/client/BuildContext.ts`.
+
+Modifications: rewritten in TypeScript with promises only; the query parameters and the bodies are separated; the
+swarm, plugin and volume operations (except the prune of the volumes) are not included; the registry credentials of
+the builds are sent by the `X-Registry-Config` header, without the gRPC session of BuildKit (no protobuf definitions
+are included); the progress of BuildKit is decoded into readable lines (`src/client/BuildKitProgress.ts`).
+
+## docker-modem 5.0.7
+
+Copyright Pedro Dias. Licensed under the Apache License, Version 2.0 (reproduced below).
+
+The connection to the Docker Engine API and its streams: `src/client/DockerConnection.ts`,
+`src/client/DockerStreams.ts`, `src/client/DockerRequestError.ts`.
+
+Modifications: rewritten in TypeScript with promises; the API version is negotiated with the daemon; the requests
+streaming a body close their connection (`Connection: close`) so that the daemon cannot discard a part of a body on a
+kept-alive connection; ssh2 is an optional peer dependency, loaded only for `ssh://` hosts.
+
+## @balena/dockerignore 1.0.2
+
+Copyright 2020 Balena Ltd. under the Apache License, Version 2.0 (reproduced below).
+Copyright 2018 Zeit Inc. under the MIT License (reproduced below).
+
+The rules of the `.dockerignore` files: `src/client/DockerIgnore.ts`.
+
+Modifications: rewritten in TypeScript; only the matching of the paths of a build context is kept.
+
+## tar-fs 2.1.4
+
+The packing of the directories of the build contexts: `src/client/BuildContext.ts`.
+
+Modifications: rewritten on tar-stream; each file is packed once, the files excluded by `.dockerignore` are skipped,
+and an error of the packing fails the archive instead of ending it.
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2014 Mathias Buus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## The MIT License of Zeit Inc.
+
+```
+Copyright 2018 Zeit Inc.
+
+The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+```
+
+## Apache License, Version 2.0
+
+```
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+```

package/dist/cjs/client/BuildContext.d.ts

@@ -0,0 +1,22 @@
+import { type Gzip } from 'node:zlib';
+export type BuildContextOptions = {
+    /**
+     * The directory of the context
+     */
+    directory: string;
+    /**
+     * The files and the directories packed (their paths relative to the directory): the directories are packed with
+     * their content
+     */
+    entries: string[];
+    /**
+     * The files packed even when .dockerignore excludes them (the Dockerfile, as the docker command does)
+     */
+    always?: string[];
+};
+/**
+ * Pack the context of a build: a gzipped tar stream; the files excluded by the .dockerignore of the directory are
+ * skipped. An error of the packing (a file which cannot be read, or changes while it is read) is an error of the stream
+ * @param options
+ */
+export declare function packBuildContext(options: BuildContextOptions): Gzip;