@dagger.io/dagger 0.3.4 → 0.4.0

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.
  */
@@ -98,10 +112,11 @@ export class CacheVolume extends BaseClient {
  */
 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.
      */
@@ -133,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({
@@ -148,6 +166,29 @@ 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.
+     *
+     * Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.
+     * @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.
      */
@@ -164,6 +205,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* () {
@@ -193,13 +235,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) {
@@ -217,7 +259,7 @@ export class Container extends BaseClient {
     }
     /**
      * Exit code of the last executed command. Zero means success.
-     * Null if no command has been executed.
+     * Errors if no command has been executed.
      */
     exitCode() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -231,12 +273,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* () {
@@ -251,7 +295,26 @@ export class Container extends BaseClient {
         });
     }
     /**
-     * Retrieves a file at the given path. Mounts are included.
+     * Retrieves the list of exposed ports.
+     *
+     * Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.
+     */
+    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({
@@ -267,9 +330,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({
@@ -300,6 +364,22 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Retrieves a hostname which can be used by clients to reach this container.
+     *
+     * Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.
+     */
+    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.
      */
@@ -314,6 +394,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.
      */
@@ -359,6 +453,9 @@ export class Container extends BaseClient {
     }
     /**
      * Creates a named sub-pipeline
+     * @param name Pipeline name.
+     * @param opts.description Pipeline description.
+     * @param opts.labels Pipeline labels.
      */
     pipeline(name, opts) {
         return new Container({
@@ -388,11 +485,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* () {
@@ -423,7 +524,7 @@ export class Container extends BaseClient {
     }
     /**
      * The error stream of the last executed command.
-     * Null if no command has been executed.
+     * Errors if no command has been executed.
      */
     stderr() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -438,7 +539,7 @@ export class Container extends BaseClient {
     }
     /**
      * The output stream of the last executed command.
-     * Null if no command has been executed.
+     * Errors if no command has been executed.
      */
     stdout() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -467,6 +568,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({
@@ -483,6 +585,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({
@@ -499,6 +605,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({
@@ -515,6 +622,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({
@@ -531,13 +640,18 @@ 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.
+     * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command
+     * with "sudo" or executing `docker run` with the `--privileged` flag. Containerization
+     * does not provide any security guarantees when using this option. It should only be used
+     * when absolutely necessary and only with trusted commands.
      */
     withExec(args, opts) {
         return new Container({
@@ -552,6 +666,31 @@ 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
+     *
+     * Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.
+     * @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.
@@ -571,6 +710,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({
@@ -587,6 +731,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({
@@ -603,9 +749,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) {
@@ -623,6 +769,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({
@@ -639,6 +787,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({
@@ -655,6 +805,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({
@@ -671,6 +823,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({
@@ -687,6 +840,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({
@@ -704,7 +862,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.
      */
@@ -739,6 +897,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({
@@ -753,8 +913,34 @@ 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.
+     *
+     * Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.
+     * @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({
@@ -770,7 +956,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({
@@ -787,6 +974,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({
@@ -803,6 +991,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({
@@ -817,8 +1006,29 @@ export class Container extends BaseClient {
             sessionToken: this.sessionToken,
         });
     }
+    /**
+     * Unexpose a previously exposed port.
+     *
+     * Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.
+     * @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({
@@ -835,6 +1045,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({
@@ -852,7 +1063,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({
@@ -869,6 +1080,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({
@@ -928,6 +1140,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({
@@ -944,6 +1157,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({
@@ -960,10 +1174,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) {
@@ -981,6 +1196,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* () {
@@ -996,6 +1212,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* () {
@@ -1011,6 +1228,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({
@@ -1056,7 +1274,10 @@ export class Directory extends BaseClient {
         });
     }
     /**
-     * Creates a named sub-pipeline.
+     * Creates a named sub-pipeline
+     * @param name Pipeline name.
+     * @param opts.description Pipeline description.
+     * @param opts.labels Pipeline labels.
      */
     pipeline(name, opts) {
         return new Directory({
@@ -1073,10 +1294,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({
@@ -1093,6 +1314,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({
@@ -1109,6 +1335,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({
@@ -1125,6 +1355,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({
@@ -1140,7 +1375,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({
@@ -1157,6 +1395,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({
@@ -1173,6 +1412,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({
@@ -1289,6 +1529,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* () {
@@ -1346,7 +1587,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({
@@ -1451,6 +1695,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({
@@ -1481,6 +1726,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({
@@ -1497,6 +1743,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({
@@ -1556,6 +1803,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({
@@ -1572,6 +1822,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({
@@ -1588,6 +1839,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({
@@ -1604,6 +1856,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) {
@@ -1759,6 +2013,77 @@ export class Label extends BaseClient {
         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
  */
@@ -1876,7 +2201,7 @@ export class Project extends BaseClient {
 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({
@@ -1893,8 +2218,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({
@@ -1957,6 +2284,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({
@@ -1988,14 +2320,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,
@@ -2003,7 +2337,10 @@ export default class Client extends BaseClient {
         });
     }
     /**
-     * Creates a named sub-pipeline
+     * Creates a named sub-pipeline.
+     * @param name Pipeline name.
+     * @param opts.description Pipeline description.
+     * @param opts.labels Pipeline labels.
      */
     pipeline(name, opts) {
         return new Client({