@dagger.io/dagger 0.3.3 → 0.3.5

package/dist/api/client.gen.js

@@ -53,6 +53,20 @@ export var CacheSharingMode;
      */
     CacheSharingMode[CacheSharingMode["Shared"] = 2] = "Shared";
 })(CacheSharingMode || (CacheSharingMode = {}));
+/**
+ * Transport layer network protocol associated to a port.
+ */
+export var NetworkProtocol;
+(function (NetworkProtocol) {
+    /**
+     * TCP (Transmission Control Protocol)
+     */
+    NetworkProtocol[NetworkProtocol["Tcp"] = 0] = "Tcp";
+    /**
+     * UDP (User Datagram Protocol)
+     */
+    NetworkProtocol[NetworkProtocol["Udp"] = 1] = "Udp";
+})(NetworkProtocol || (NetworkProtocol = {}));
 /**
  * A directory whose contents persist across runs.
  */
@@ -68,16 +82,41 @@ export class CacheVolume extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * An OCI-compatible container, also known as a docker container.
  */
 export class Container extends BaseClient {
     /**
-     * Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs.
+     * Initializes this container from a Dockerfile build.
      * @param context Directory context used by the Dockerfile.
      * @param opts.dockerfile Path to the Dockerfile to use.
-  Defaults to './Dockerfile'.
+     *
+     * Default: './Dockerfile'.
      * @param opts.buildArgs Additional build arguments.
      * @param opts.target Target build stage to build.
      */
@@ -109,7 +148,10 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Retrieves a directory at the given path. Mounts are included.
+     * Retrieves a directory at the given path.
+     *
+     * Mounts are included.
+     * @param path The path of the directory to retrieve (e.g., "./src").
      */
     directory(path) {
         return new Directory({
@@ -124,6 +166,27 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Retrieves an endpoint that clients can use to reach this container.
+     *
+     * If no port is specified, the first exposed port is used. If none exist an error is returned.
+     *
+     * If a scheme is specified, a URL is returned. Otherwise, a host:port pair is returned.
+     * @param opts.port The exposed port number for the endpoint
+     * @param opts.scheme Return a URL with the given scheme, eg. http for http://
+     */
+    endpoint(opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "endpoint",
+                    args: Object.assign({}, opts),
+                },
+            ], this.client);
+            return response;
+        });
+    }
     /**
      * Retrieves entrypoint to be prepended to the arguments of all commands.
      */
@@ -140,6 +203,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves the value of the specified environment variable.
+     * @param name The name of the environment variable to retrieve (e.g., "PATH").
      */
     envVariable(name) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -169,13 +233,13 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container after executing the specified command inside it.
-     * @param opts.args Command to run instead of the container's default command.
-     * @param opts.stdin Content to write to the command's standard input before closing.
-     * @param opts.redirectStdout Redirect the command's standard output to a file in the container.
-     * @param opts.redirectStderr Redirect the command's standard error to a file in the container.
+     * @param opts.args Command to run instead of the container's default command (e.g., ["run", "main.go"]).
+     * @param opts.stdin Content to write to the command's standard input before closing (e.g., "Hello world").
+     * @param opts.redirectStdout Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
+     * @param opts.redirectStderr Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
      * @param opts.experimentalPrivilegedNesting Provide dagger access to the executed command.
-  Do not use this option unless you trust the command being executed.
-  The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
+     * Do not use this option unless you trust the command being executed.
+     * The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      * @deprecated Replaced by withExec.
      */
     exec(opts) {
@@ -207,12 +271,14 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Writes the container as an OCI tarball to the destination file path on the host for the specified platformVariants.
+     * Writes the container as an OCI tarball to the destination file path on the host for the specified platform variants.
+     *
      * Return true on success.
-     * @param path Host's destination path.
-  Path can be relative to the engine's workdir or absolute.
+     * It can also publishes platform variants.
+     * @param path Host's destination path (e.g., "./tarball").
+     * Path can be relative to the engine's workdir or absolute.
      * @param opts.platformVariants Identifiers for other platform specific containers.
-  Used for multi-platform image.
+     * Used for multi-platform image.
      */
     export(path, opts) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -227,7 +293,24 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Retrieves a file at the given path. Mounts are included.
+     * Retrieves the list of exposed ports
+     */
+    exposedPorts() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "exposedPorts",
+                },
+            ], this.client);
+            return response;
+        });
+    }
+    /**
+     * Retrieves a file at the given path.
+     *
+     * Mounts are included.
+     * @param path The path of the file to retrieve (e.g., "./README.md").
      */
     file(path) {
         return new File({
@@ -243,9 +326,10 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Initializes this container from the base image published at the given address.
+     * Initializes this container from a pulled base image.
      * @param address Image's address from its registry.
-  Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+     *
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").
      */
     from(address) {
         return new Container({
@@ -276,6 +360,20 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Retrieves a hostname which can be used by clients to reach this container.
+     */
+    hostname() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "hostname",
+                },
+            ], this.client);
+            return response;
+        });
+    }
     /**
      * A unique identifier for this container.
      */
@@ -290,6 +388,20 @@ export class Container extends BaseClient {
             return response;
         });
     }
+    /**
+     * The unique image reference which can only be retrieved immediately after the 'Container.From' call.
+     */
+    imageRef() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "imageRef",
+                },
+            ], this.client);
+            return response;
+        });
+    }
     /**
      * Retrieves the value of the specified label.
      */
@@ -364,11 +476,15 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Publishes this container as a new image to the specified address, for the platformVariants, returning a fully qualified ref.
+     * Publishes this container as a new image to the specified address.
+     *
+     * Publish returns a fully qualified ref.
+     * It can also publish platform variants.
      * @param address Registry's address to publish the image to.
-  Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+     *
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g. "docker.io/dagger/dagger:main").
      * @param opts.platformVariants Identifiers for other platform specific containers.
-  Used for multi-platform image.
+     * Used for multi-platform image.
      */
     publish(address, opts) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -443,6 +559,7 @@ export class Container extends BaseClient {
     }
     /**
      * Configures default arguments for future commands.
+     * @param opts.args Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).
      */
     withDefaultArgs(opts) {
         return new Container({
@@ -459,6 +576,10 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a directory written at the given path.
+     * @param path Location of the written directory (e.g., "/tmp/directory").
+     * @param directory Identifier of the directory to write
+     * @param opts.exclude Patterns to exclude in the written directory (e.g., ["node_modules/**", ".gitignore", ".git/"]).
+     * @param opts.include Patterns to include in the written directory (e.g., ["*.go", "go.mod", "go.sum"]).
      */
     withDirectory(path, directory, opts) {
         return new Container({
@@ -475,6 +596,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container but with a different command entrypoint.
+     * @param args Entrypoint to use for future executions (e.g., ["go", "run"]).
      */
     withEntrypoint(args) {
         return new Container({
@@ -491,6 +613,8 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus the given environment variable.
+     * @param name The name of the environment variable (e.g., "HOST").
+     * @param value The value of the environment variable. (e.g., "localhost").
      */
     withEnvVariable(name, value) {
         return new Container({
@@ -507,13 +631,14 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container after executing the specified command inside it.
-     * @param args Command to run instead of the container's default command.
-     * @param opts.stdin Content to write to the command's standard input before closing.
-     * @param opts.redirectStdout Redirect the command's standard output to a file in the container.
-     * @param opts.redirectStderr Redirect the command's standard error to a file in the container.
-     * @param opts.experimentalPrivilegedNesting Provide dagger access to the executed command.
-  Do not use this option unless you trust the command being executed.
-  The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
+     * @param args Command to run instead of the container's default command (e.g., ["run", "main.go"]).
+     * @param opts.stdin Content to write to the command's standard input before closing (e.g., "Hello world").
+     * @param opts.redirectStdout Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
+     * @param opts.redirectStderr Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
+     * @param opts.experimentalPrivilegedNesting Provides dagger access to the executed command.
+     *
+     * Do not use this option unless you trust the command being executed.
+     * The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      */
     withExec(args, opts) {
         return new Container({
@@ -528,6 +653,28 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Expose a network port.
+     * Exposed ports serve two purposes:
+     *   - For health checks and introspection, when running services
+     *   - For setting the EXPOSE OCI field when publishing the container
+     * @param port Port number to expose
+     * @param opts.protocol Transport layer network protocol
+     * @param opts.description Optional port description
+     */
+    withExposedPort(port, opts) {
+        return new Container({
+            queryTree: [
+                ...this._queryTree,
+                {
+                    operation: "withExposedPort",
+                    args: Object.assign({ port }, opts),
+                },
+            ],
+            host: this.clientHost,
+            sessionToken: this.sessionToken,
+        });
+    }
     /**
      * Initializes this container from this DirectoryID.
      * @deprecated Replaced by withRootfs.
@@ -547,6 +694,11 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus the contents of the given file copied to the given path.
+     * @param path Location of the copied file (e.g., "/tmp/file.txt").
+     * @param source Identifier of the file to copy.
+     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
      */
     withFile(path, source, opts) {
         return new Container({
@@ -563,6 +715,8 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus the given label.
+     * @param name The name of the label (e.g., "org.opencontainers.artifact.created").
+     * @param value The value of the label (e.g., "2023-01-01T00:00:00Z").
      */
     withLabel(name, value) {
         return new Container({
@@ -579,9 +733,9 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a cache volume mounted at the given path.
-     * @param path Path to mount the cache volume at.
-     * @param cache ID of the cache to mount.
-     * @param opts.source Directory to use as the cache volume's root.
+     * @param path Location of the cache directory (e.g., "/cache/node_modules").
+     * @param cache Identifier of the cache volume to mount.
+     * @param opts.source Identifier of the directory to use as the cache volume's root.
      * @param opts.sharing Sharing mode of the cache volume.
      */
     withMountedCache(path, cache, opts) {
@@ -599,6 +753,8 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a directory mounted at the given path.
+     * @param path Location of the mounted directory (e.g., "/mnt/directory").
+     * @param source Identifier of the mounted directory.
      */
     withMountedDirectory(path, source) {
         return new Container({
@@ -615,6 +771,8 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a file mounted at the given path.
+     * @param path Location of the mounted file (e.g., "/tmp/file.txt").
+     * @param source Identifier of the mounted file.
      */
     withMountedFile(path, source) {
         return new Container({
@@ -631,6 +789,8 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a secret mounted into a file at the given path.
+     * @param path Location of the secret file (e.g., "/tmp/secret.txt").
+     * @param source Identifier of the secret to mount.
      */
     withMountedSecret(path, source) {
         return new Container({
@@ -647,6 +807,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a temporary directory mounted at the given path.
+     * @param path Location of the temporary directory (e.g., "/tmp/temp_dir").
      */
     withMountedTemp(path) {
         return new Container({
@@ -663,6 +824,11 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus a new file written at the given path.
+     * @param path Location of the written file (e.g., "/tmp/file.txt").
+     * @param opts.contents Content of the file to write (e.g., "Hello world!").
+     * @param opts.permissions Permission given to the written file (e.g., 0600).
+     *
+     * Default: 0644.
      */
     withNewFile(path, opts) {
         return new Container({
@@ -680,7 +846,7 @@ export class Container extends BaseClient {
     /**
      * Retrieves this container with a registry authentication for a given address.
      * @param address Registry's address to bind the authentication to.
-  Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
      * @param username The username of the registry's account (e.g., "Dagger").
      * @param secret The API key, password or token to authenticate to this registry.
      */
@@ -715,6 +881,8 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container plus an env variable containing the given secret.
+     * @param name The name of the secret variable (e.g., "API_SECRET").
+     * @param secret The identifier of the secret value.
      */
     withSecretVariable(name, secret) {
         return new Container({
@@ -729,8 +897,32 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Establish a runtime dependency on a service. The service will be started automatically when needed and detached when it is no longer needed.
+     *
+     * The service will be reachable from the container via the provided hostname alias.
+     *
+     * The service dependency will also convey to any files or directories produced by the container.
+     * @param alias A name that can be used to reach the service from the container
+     * @param service Identifier of the service container
+     */
+    withServiceBinding(alias, service) {
+        return new Container({
+            queryTree: [
+                ...this._queryTree,
+                {
+                    operation: "withServiceBinding",
+                    args: { alias, service },
+                },
+            ],
+            host: this.clientHost,
+            sessionToken: this.sessionToken,
+        });
+    }
     /**
      * Retrieves this container plus a socket forwarded to the given Unix socket path.
+     * @param path Location of the forwarded Unix socket (e.g., "/tmp/socket").
+     * @param source Identifier of the socket to forward.
      */
     withUnixSocket(path, source) {
         return new Container({
@@ -746,7 +938,8 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Retrieves this containers with a different command user.
+     * Retrieves this container with a different command user.
+     * @param name The user to set (e.g., "root").
      */
     withUser(name) {
         return new Container({
@@ -763,6 +956,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container with a different working directory.
+     * @param path The path to set as the working directory (e.g., "/app").
      */
     withWorkdir(path) {
         return new Container({
@@ -779,6 +973,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container minus the given environment variable.
+     * @param name The name of the environment variable (e.g., "HOST").
      */
     withoutEnvVariable(name) {
         return new Container({
@@ -793,8 +988,27 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Unexpose a previously exposed port.
+     * @param port Port number to unexpose
+     * @param opts.protocol Port protocol to unexpose
+     */
+    withoutExposedPort(port, opts) {
+        return new Container({
+            queryTree: [
+                ...this._queryTree,
+                {
+                    operation: "withoutExposedPort",
+                    args: Object.assign({ port }, opts),
+                },
+            ],
+            host: this.clientHost,
+            sessionToken: this.sessionToken,
+        });
+    }
     /**
      * Retrieves this container minus the given environment label.
+     * @param name The name of the label to remove (e.g., "org.opencontainers.artifact.created").
      */
     withoutLabel(name) {
         return new Container({
@@ -811,6 +1025,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container after unmounting everything at the given path.
+     * @param path Location of the cache directory (e.g., "/cache/node_modules").
      */
     withoutMount(path) {
         return new Container({
@@ -828,7 +1043,7 @@ export class Container extends BaseClient {
     /**
      * Retrieves this container without the registry authentication of a given address.
      * @param address Registry's address to remove the authentication from.
-  Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+     * Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
      */
     withoutRegistryAuth(address) {
         return new Container({
@@ -845,6 +1060,7 @@ export class Container extends BaseClient {
     }
     /**
      * Retrieves this container with a previously added Unix socket removed.
+     * @param path Location of the socket to remove (e.g., "/tmp/socket").
      */
     withoutUnixSocket(path) {
         return new Container({
@@ -873,6 +1089,30 @@ export class Container extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A directory.
@@ -880,6 +1120,7 @@ export class Container extends BaseClient {
 export class Directory extends BaseClient {
     /**
      * Gets the difference between this directory and an another directory.
+     * @param other Identifier of the directory to compare.
      */
     diff(other) {
         return new Directory({
@@ -896,6 +1137,7 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves a directory at the given path.
+     * @param path Location of the directory to retrieve (e.g., "/src").
      */
     directory(path) {
         return new Directory({
@@ -912,10 +1154,11 @@ export class Directory extends BaseClient {
     }
     /**
      * Builds a new Docker container from this directory.
-     * @param opts.dockerfile Path to the Dockerfile to use.
-  Defaults to './Dockerfile'.
+     * @param opts.dockerfile Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
+     *
+     * Defaults: './Dockerfile'.
      * @param opts.platform The platform to build.
-     * @param opts.buildArgs Additional build arguments.
+     * @param opts.buildArgs Build arguments to use in the build.
      * @param opts.target Target build stage to build.
      */
     dockerBuild(opts) {
@@ -933,6 +1176,7 @@ export class Directory extends BaseClient {
     }
     /**
      * Returns a list of files and directories at the given path.
+     * @param opts.path Location of the directory to look at (e.g., "/src").
      */
     entries(opts) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -948,6 +1192,7 @@ export class Directory extends BaseClient {
     }
     /**
      * Writes the contents of the directory to a path on the host.
+     * @param path Location of the copied directory (e.g., "logs/").
      */
     export(path) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -963,6 +1208,7 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves a file at the given path.
+     * @param path Location of the file to retrieve (e.g., "README.md").
      */
     file(path) {
         return new File({
@@ -1025,10 +1271,10 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves this directory plus a directory written at the given path.
-     * @param opts.exclude Exclude artifacts that match the given pattern.
-  (e.g. ["node_modules/", ".git*"]).
-     * @param opts.include Include only artifacts that match the given pattern.
-  (e.g. ["app/", "package.*"]).
+     * @param path Location of the written directory (e.g., "/src/").
+     * @param directory Identifier of the directory to copy.
+     * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
+     * @param opts.include Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
      */
     withDirectory(path, directory, opts) {
         return new Directory({
@@ -1045,6 +1291,11 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves this directory plus the contents of the given file copied to the given path.
+     * @param path Location of the copied file (e.g., "/file.txt").
+     * @param source Identifier of the file to copy.
+     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
      */
     withFile(path, source, opts) {
         return new Directory({
@@ -1061,6 +1312,10 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves this directory plus a new directory created at the given path.
+     * @param path Location of the directory created (e.g., "/logs").
+     * @param opts.permissions Permission granted to the created directory (e.g., 0777).
+     *
+     * Default: 0755.
      */
     withNewDirectory(path, opts) {
         return new Directory({
@@ -1077,6 +1332,11 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves this directory plus a new file written at the given path.
+     * @param path Location of the written file (e.g., "/file.txt").
+     * @param contents Content of the written file (e.g., "Hello world!").
+     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     *
+     * Default: 0644.
      */
     withNewFile(path, contents, opts) {
         return new Directory({
@@ -1092,7 +1352,10 @@ export class Directory extends BaseClient {
         });
     }
     /**
-     * Retrieves this directory with all file/dir timestamps set to the given time, in seconds from the Unix epoch.
+     * Retrieves this directory with all file/dir timestamps set to the given time.
+     * @param timestamp Timestamp to set dir/files in.
+     *
+     * Formatted in seconds following Unix epoch (e.g., 1672531199).
      */
     withTimestamps(timestamp) {
         return new Directory({
@@ -1109,6 +1372,7 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves this directory with the directory at the given path removed.
+     * @param path Location of the directory to remove (e.g., ".github/").
      */
     withoutDirectory(path) {
         return new Directory({
@@ -1125,6 +1389,7 @@ export class Directory extends BaseClient {
     }
     /**
      * Retrieves this directory with the file at the given path removed.
+     * @param path Location of the file to remove (e.g., "/file.txt").
      */
     withoutFile(path) {
         return new Directory({
@@ -1139,6 +1404,30 @@ export class Directory extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A simple key value object that represents an environment variable.
@@ -1172,6 +1461,30 @@ export class EnvVariable extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A file.
@@ -1193,6 +1506,7 @@ export class File extends BaseClient {
     }
     /**
      * Writes the file to a file path on the host.
+     * @param path Location of the written directory (e.g., "output.txt").
      */
     export(path) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1250,7 +1564,10 @@ export class File extends BaseClient {
         });
     }
     /**
-     * Retrieves this file with its created/modified timestamps set to the given time, in seconds from the Unix epoch.
+     * Retrieves this file with its created/modified timestamps set to the given time.
+     * @param timestamp Timestamp to set dir/files in.
+     *
+     * Formatted in seconds following Unix epoch (e.g., 1672531199).
      */
     withTimestamps(timestamp) {
         return new File({
@@ -1265,6 +1582,30 @@ export class File extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A git ref (tag, branch or commit).
@@ -1300,6 +1641,30 @@ export class GitRef extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A git repository.
@@ -1307,6 +1672,7 @@ export class GitRef extends BaseClient {
 export class GitRepository extends BaseClient {
     /**
      * Returns details on one branch.
+     * @param name Branch's name (e.g., "main").
      */
     branch(name) {
         return new GitRef({
@@ -1337,6 +1703,7 @@ export class GitRepository extends BaseClient {
     }
     /**
      * Returns details on one commit.
+     * @param id Identifier of the commit (e.g., "b6315d8f2810962c601af73f86831f6866ea798b").
      */
     commit(id) {
         return new GitRef({
@@ -1353,6 +1720,7 @@ export class GitRepository extends BaseClient {
     }
     /**
      * Returns details on one tag.
+     * @param name Tag's name (e.g., "v0.3.9").
      */
     tag(name) {
         return new GitRef({
@@ -1381,6 +1749,30 @@ export class GitRepository extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * Information about the host execution environment.
@@ -1388,6 +1780,9 @@ export class GitRepository extends BaseClient {
 export class Host extends BaseClient {
     /**
      * Accesses a directory on the host.
+     * @param path Location of the directory to access (e.g., ".").
+     * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
+     * @param opts.include Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
      */
     directory(path, opts) {
         return new Directory({
@@ -1404,6 +1799,7 @@ export class Host extends BaseClient {
     }
     /**
      * Accesses an environment variable on the host.
+     * @param name Name of the environment variable (e.g., "PATH").
      */
     envVariable(name) {
         return new HostVariable({
@@ -1420,6 +1816,7 @@ export class Host extends BaseClient {
     }
     /**
      * Accesses a Unix socket on the host.
+     * @param path Location of the Unix socket (e.g., "/var/run/docker.sock").
      */
     unixSocket(path) {
         return new Socket({
@@ -1436,6 +1833,8 @@ export class Host extends BaseClient {
     }
     /**
      * Retrieves the current working directory on the host.
+     * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
+     * @param opts.include Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
      * @deprecated Use directory with path set to '.' instead.
      */
     workdir(opts) {
@@ -1451,6 +1850,30 @@ export class Host extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * An environment variable on the host environment.
@@ -1485,6 +1908,30 @@ export class HostVariable extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A simple key value object that represents a label.
@@ -1518,6 +1965,101 @@ export class Label extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
+}
+/**
+ * A port exposed by a container.
+ */
+export class Port extends BaseClient {
+    /**
+     * The port description.
+     */
+    description() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "description",
+                },
+            ], this.client);
+            return response;
+        });
+    }
+    /**
+     * The port number.
+     */
+    port() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "port",
+                },
+            ], this.client);
+            return response;
+        });
+    }
+    /**
+     * The transport layer network protocol.
+     */
+    protocol() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield computeQuery([
+                ...this._queryTree,
+                {
+                    operation: "protocol",
+                },
+            ], this.client);
+            return response;
+        });
+    }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 /**
  * A set of scripts and/or extensions
@@ -1608,11 +2150,35 @@ export class Project extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 export default class Client extends BaseClient {
     /**
      * Constructs a cache volume for a given cache key.
-     * @param key A string identifier to target this cache volume (e.g. "myapp-cache").
+     * @param key A string identifier to target this cache volume (e.g., "modules-cache").
      */
     cacheVolume(key) {
         return new CacheVolume({
@@ -1629,8 +2195,10 @@ export default class Client extends BaseClient {
     }
     /**
      * Loads a container from ID.
+     *
      * Null ID returns an empty container (scratch).
-     * Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.
+     * Optional platform argument initializes new containers to execute and publish as that platform.
+     * Platform defaults to that of the builder's host.
      */
     container(opts) {
         return new Container({
@@ -1693,6 +2261,11 @@ export default class Client extends BaseClient {
     }
     /**
      * Queries a git repository.
+     * @param url Url of the git repository.
+     * Can be formatted as https://{host}/{owner}/{repo}, git@{host}/{owner}/{repo}
+     * Suffix ".git" is optional.
+     * @param opts.keepGitDir Set to true to keep .git directory.
+     * @param opts.experimentalServiceHost A service which must be started before the repo is fetched.
      */
     git(url, opts) {
         return new GitRepository({
@@ -1724,14 +2297,16 @@ export default class Client extends BaseClient {
     }
     /**
      * Returns a file containing an http remote url content.
+     * @param url HTTP url to get the content from (e.g., "https://docs.dagger.io").
+     * @param opts.experimentalServiceHost A service which must be started before the URL is fetched.
      */
-    http(url) {
+    http(url, opts) {
         return new File({
             queryTree: [
                 ...this._queryTree,
                 {
                     operation: "http",
-                    args: { url },
+                    args: Object.assign({ url }, opts),
                 },
             ],
             host: this.clientHost,
@@ -1835,6 +2410,30 @@ export class Secret extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }
 export class Socket extends BaseClient {
     /**
@@ -1851,4 +2450,28 @@ export class Socket extends BaseClient {
             return response;
         });
     }
+    /**
+     * Chain objects together
+     * @example
+     * ```ts
+     *	function AddAFewMounts(c) {
+     *			return c
+     *			.withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
+     *			.withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
+     *	}
+     *
+     * connect(async (client) => {
+     *		const tree = await client
+     *			.container()
+     *			.from("alpine")
+     *			.withWorkdir("/foo")
+     *			.with(AddAFewMounts)
+     *			.withExec(["ls", "-lh"])
+     *			.stdout()
+     * })
+     *```
+     */
+    with(arg) {
+        return arg(this);
+    }
 }