docker-engine-ruby 0.2.2 → 0.4.0

data/rbi/docker_engine_ruby/resources/containers.rbi

@@ -6,7 +6,7 @@ module DockerEngineRuby
       # Create a container
       sig do
         params(
-          config: DockerEngineRuby::ContainerCreateParams::Config::OrHash,
+          config: DockerEngineRuby::Config::OrHash,
           name: String,
           platform: String,
           request_options: DockerEngineRuby::RequestOptions::OrHash
@@ -15,31 +15,15 @@ module DockerEngineRuby
       def create(
         # Body param: Configuration for a container that is portable between hosts.
         config:,
-        # Query param: Assign the specified name to the container. Must match
-        # `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
+        # Query param
         name: nil,
-        # Query param: Platform in the format `os[/arch[/variant]]` used for image lookup.
-        #
-        # When specified, the daemon checks if the requested image is present in the local
-        # image cache with the given OS and Architecture, and otherwise returns a `404`
-        # status.
-        #
-        # If the option is not set, the host's native OS and Architecture are used to look
-        # up the image in the image cache. However, if no platform is passed and the given
-        # image does exist in the local image cache, but its OS or architecture does not
-        # match, the container is created with the available image, and a warning is added
-        # to the `Warnings` field in the response, for example;
-        #
-        #     WARNING: The requested image's platform (linux/arm64/v8) does not
-        #              match the detected host platform (linux/amd64) and no
-        #              specific platform was requested
+        # Query param
         platform: nil,
         request_options: {}
       )
       end
 
-      # Change various configuration options of a container without having to recreate
-      # it.
+      # Update a container
       sig do
         params(
           id: String,
@@ -91,15 +75,12 @@ module DockerEngineRuby
           nano_cpus: Integer,
           oom_kill_disable: T::Boolean,
           pids_limit: T.nilable(Integer),
-          restart_policy:
-            DockerEngineRuby::ContainerUpdateParams::RestartPolicy::OrHash,
           ulimits:
             T::Array[DockerEngineRuby::ContainerUpdateParams::Ulimit::OrHash],
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::UpdateResponse)
       end
       def update(
-        # ID or name of the container
         id,
         # Limit read rate (bytes per second) from a device, in the form:
         #
@@ -197,11 +178,6 @@ module DockerEngineRuby
         # Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not
         # change.
         pids_limit: nil,
-        # The behavior to apply when the container exits. The default is not to restart.
-        #
-        # An ever increasing delay (double the previous delay, starting at 100ms) is added
-        # before each restart to prevent flooding the server.
-        restart_policy: nil,
         # A list of resource limits to set in the container. For example:
         #
         # ```
@@ -212,12 +188,7 @@ module DockerEngineRuby
       )
       end
 
-      # Returns a list of containers. For details on the format, see the
-      # [inspect endpoint](#operation/ContainerInspect).
-      #
-      # Note that it uses a different, smaller representation of a container than
-      # inspecting a single container. For example, the list of linked containers is not
-      # propagated .
+      # List containers
       sig do
         params(
           all: T::Boolean,
@@ -228,34 +199,9 @@ module DockerEngineRuby
         ).returns(T::Array[DockerEngineRuby::Summary])
       end
       def list(
-        # Return all containers. By default, only running containers are shown.
         all: nil,
-        # Filters to process on the container list, encoded as JSON (a
-        # `map[string][]string`). For example, `{"status": ["paused"]}` will only return
-        # paused containers.
-        #
-        # Available filters:
-        #
-        # - `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)
-        # - `before`=(`<container id>` or `<container name>`)
-        # - `expose`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`)
-        # - `exited=<int>` containers with exit code of `<int>`
-        # - `health`=(`starting`|`healthy`|`unhealthy`|`none`)
-        # - `id=<ID>` a container's ID
-        # - `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only)
-        # - `is-task=`(`true`|`false`)
-        # - `label=key` or `label="key=value"` of a container label
-        # - `name=<name>` a container's name
-        # - `network`=(`<network id>` or `<network name>`)
-        # - `publish`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`)
-        # - `since`=(`<container id>` or `<container name>`)
-        # - `status=`(`created`|`restarting`|`running`|`removing`|`paused`|`exited`|`dead`)
-        # - `volume`=(`<volume name>` or `<mount point destination>`)
         filters: nil,
-        # Return this number of most recently created containers, including non-running
-        # ones.
         limit: nil,
-        # Return the size of container as fields `SizeRw` and `SizeRootFs`.
         size: nil,
         request_options: {}
       )
@@ -271,20 +217,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def delete(
-        # ID or name of the container
-        id,
-        # If the container is running, kill it before removing it.
-        force: nil,
-        # Remove the specified link associated with the container.
-        link: nil,
-        # Remove anonymous volumes associated with the container.
-        v: nil,
-        request_options: {}
-      )
+      def delete(id, force: nil, link: nil, v: nil, request_options: {})
       end
 
-      # Get a tar archive of a resource in the filesystem of container id.
+      # Get an archive of a filesystem resource in a container
       sig do
         params(
           id: String,
@@ -292,110 +228,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def archive(
-        # ID or name of the container
-        id,
-        # Resource in the container’s filesystem to archive.
-        path:,
-        request_options: {}
-      )
+      def archive(id, path:, request_options: {})
       end
 
-      # Attach to a container to read its output or send it input. You can attach to the
-      # same container multiple times and you can reattach to containers that have been
-      # detached.
-      #
-      # Either the `stream` or `logs` parameter must be `true` for this endpoint to do
-      # anything.
-      #
-      # See the
-      # [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/)
-      # for more details.
-      #
-      # ### Hijacking
-      #
-      # This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and
-      # `stderr` on the same socket.
-      #
-      # This is the response from the daemon for an attach request:
-      #
-      # ```
-      # HTTP/1.1 200 OK
-      # Content-Type: application/vnd.docker.raw-stream
-      #
-      # [STREAM]
-      # ```
-      #
-      # After the headers and two new lines, the TCP connection can now be used for raw,
-      # bidirectional communication between the client and server.
-      #
-      # To hint potential proxies about connection hijacking, the Docker client can also
-      # optionally send connection upgrade headers.
-      #
-      # For example, the client sends this request to upgrade the connection:
-      #
-      # ```
-      # POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
-      # Upgrade: tcp
-      # Connection: Upgrade
-      # ```
-      #
-      # The Docker daemon will respond with a `101 UPGRADED` response, and will
-      # similarly follow with the raw stream:
-      #
-      # ```
-      # HTTP/1.1 101 UPGRADED
-      # Content-Type: application/vnd.docker.raw-stream
-      # Connection: Upgrade
-      # Upgrade: tcp
-      #
-      # [STREAM]
-      # ```
-      #
-      # ### Stream format
-      #
-      # When the TTY setting is disabled in
-      # [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type
-      # header is set to application/vnd.docker.multiplexed-stream and the stream over
-      # the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The
-      # stream consists of a series of frames, each containing a header and a payload.
-      #
-      # The header contains the information which the stream writes (`stdout` or
-      # `stderr`). It also contains the size of the associated frame encoded in the last
-      # four bytes (`uint32`).
-      #
-      # It is encoded on the first eight bytes like this:
-      #
-      # ```go
-      # header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
-      # ```
-      #
-      # `STREAM_TYPE` can be:
-      #
-      # - 0: `stdin` (is written on `stdout`)
-      # - 1: `stdout`
-      # - 2: `stderr`
-      #
-      # `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as
-      # big endian.
-      #
-      # Following the header is the payload, which is the specified number of bytes of
-      # `STREAM_TYPE`.
-      #
-      # The simplest way to implement this protocol is the following:
-      #
-      # 1. Read 8 bytes.
-      # 2. Choose `stdout` or `stderr` depending on the first byte.
-      # 3. Extract the frame size from the last four bytes.
-      # 4. Read the extracted size and output it on the correct output.
-      # 5. Goto 1.
-      #
-      # ### Stream format when using a TTY
-      #
-      # When the TTY setting is enabled in
-      # [`POST /containers/create`](#operation/ContainerCreate), the stream is not
-      # multiplexed. The data exchanged over the hijacked connection is simply the raw
-      # data from the process PTY and client's `stdin`.
+      # Attach to a container
       sig do
         params(
           id: String,
@@ -409,52 +245,28 @@ module DockerEngineRuby
         ).void
       end
       def attach(
-        # ID or name of the container
         id,
-        # Override the key sequence for detaching a container.Format is a single character
-        # `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`
-        # or `_`.
         detach_keys: nil,
-        # Replay previous logs from the container.
-        #
-        # This is useful for attaching to a container that has started and you want to
-        # output everything since the container started.
-        #
-        # If `stream` is also enabled, once all the previous output has been returned, it
-        # will seamlessly transition into streaming current output.
         logs: nil,
-        # Attach to `stderr`
         stderr: nil,
-        # Attach to `stdin`
         stdin: nil,
-        # Attach to `stdout`
         stdout: nil,
-        # Stream attached streams from the time the request was made onwards.
         stream: nil,
         request_options: {}
       )
       end
 
-      # Returns which files in a container's filesystem have been added, deleted, or
-      # modified. The `Kind` of modification can be one of:
-      #
-      # - `0`: Modified ("C")
-      # - `1`: Added ("A")
-      # - `2`: Deleted ("D")
+      # Get changes on a container’s filesystem
       sig do
         params(
           id: String,
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(T::Array[DockerEngineRuby::FilesystemChange])
       end
-      def changes(
-        # ID or name of the container
-        id,
-        request_options: {}
-      )
+      def changes(id, request_options: {})
       end
 
-      # Run a command inside a running container.
+      # Create an exec instance
       sig do
         params(
           id: String,
@@ -473,52 +285,33 @@ module DockerEngineRuby
         ).returns(DockerEngineRuby::Models::ContainerExecResponse)
       end
       def exec_(
-        # ID or name of container
         id,
-        # Attach to `stderr` of the exec command.
         attach_stderr: nil,
-        # Attach to `stdin` of the exec command.
         attach_stdin: nil,
-        # Attach to `stdout` of the exec command.
         attach_stdout: nil,
-        # Command to run, as a string or array of strings.
         cmd: nil,
-        # Initial console size, as an `[height, width]` array.
         console_size: nil,
-        # Override the key sequence for detaching a container. Format is a single
-        # character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`,
-        # `[`, `,` or `_`.
         detach_keys: nil,
-        # A list of environment variables in the form `["VAR=value", ...]`.
         env: nil,
-        # Runs the exec process with extended privileges.
         privileged: nil,
-        # Allocate a pseudo-TTY.
         tty: nil,
-        # The user, and optionally, group to run the exec process inside the container.
-        # Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.
         user: nil,
-        # The working directory for the exec process inside the container.
         working_dir: nil,
         request_options: {}
       )
       end
 
-      # Export the contents of a container as a tarball.
+      # Export a container
       sig do
         params(
           id: String,
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def export(
-        # ID or name of the container
-        id,
-        request_options: {}
-      )
+      def export(id, request_options: {})
       end
 
-      # Return low-level information about a container.
+      # Inspect a container
       sig do
         params(
           id: String,
@@ -526,16 +319,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::Container)
       end
-      def inspect_(
-        # ID or name of the container
-        id,
-        # Return the size of container as fields `SizeRw` and `SizeRootFs`
-        size: nil,
-        request_options: {}
-      )
+      def inspect_(id, size: nil, request_options: {})
       end
 
-      # Send a POSIX signal to a container, defaulting to killing to the container.
+      # Kill a container
       sig do
         params(
           id: String,
@@ -543,19 +330,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def kill(
-        # ID or name of the container
-        id,
-        # Signal to send to the container as an integer or string (e.g. `SIGINT`).
-        signal: nil,
-        request_options: {}
-      )
+      def kill(id, signal: nil, request_options: {})
       end
 
-      # Get `stdout` and `stderr` logs from a container.
-      #
-      # Note: This endpoint works only for containers with the `json-file` or `journald`
-      # logging driver.
+      # Get container logs
       sig do
         params(
           id: String,
@@ -570,44 +348,26 @@ module DockerEngineRuby
         ).returns(StringIO)
       end
       def logs(
-        # ID or name of the container
         id,
-        # Keep connection after returning logs.
         follow: nil,
-        # Only return logs since this time, as a UNIX timestamp
         since: nil,
-        # Return logs from `stderr`
         stderr: nil,
-        # Return logs from `stdout`
         stdout: nil,
-        # Only return this number of log lines from the end of the logs. Specify as an
-        # integer or `all` to output all log lines.
         tail: nil,
-        # Add timestamps to every log line
         timestamps: nil,
-        # Only return logs before this time, as a UNIX timestamp
         until_: nil,
         request_options: {}
       )
       end
 
-      # Use the freezer cgroup to suspend all processes in a container.
-      #
-      # Traditionally, when suspending a process the `SIGSTOP` signal is used, which is
-      # observable by the process being suspended. With the freezer cgroup the process
-      # is unaware, and unable to capture, that it is being suspended, and subsequently
-      # resumed.
+      # Pause a container
       sig do
         params(
           id: String,
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def pause(
-        # ID or name of the container
-        id,
-        request_options: {}
-      )
+      def pause(id, request_options: {})
       end
 
       # Delete stopped containers
@@ -617,21 +377,7 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::Models::ContainerPruneResponse)
       end
-      def prune(
-        # Filters to process on the prune list, encoded as JSON (a `map[string][]string`).
-        #
-        # Available filters:
-        #
-        # - `until=<timestamp>` Prune containers created before this timestamp. The
-        #   `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go
-        #   duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon
-        #   machine’s time.
-        # - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or
-        #   `label!=<key>=<value>`) Prune containers with (or without, in case
-        #   `label!=...` is used) the specified labels.
-        filters: nil,
-        request_options: {}
-      )
+      def prune(filters: nil, request_options: {})
       end
 
       # Rename a container
@@ -642,16 +388,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def rename(
-        # ID or name of the container
-        id,
-        # New name for the container
-        name:,
-        request_options: {}
-      )
+      def rename(id, name:, request_options: {})
       end
 
-      # Resize the TTY for a container.
+      # Resize a container TTY
       sig do
         params(
           id: String,
@@ -660,15 +400,7 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def resize(
-        # ID or name of the container
-        id,
-        # Height of the TTY session in characters
-        h:,
-        # Width of the TTY session in characters
-        w:,
-        request_options: {}
-      )
+      def resize(id, h:, w:, request_options: {})
       end
 
       # Restart a container
@@ -680,15 +412,7 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def restart(
-        # ID or name of the container
-        id,
-        # Signal to send to the container as an integer or string (e.g. `SIGINT`).
-        signal: nil,
-        # Number of seconds to wait before killing the container
-        t: nil,
-        request_options: {}
-      )
+      def restart(id, signal: nil, t: nil, request_options: {})
       end
 
       # Start a container
@@ -699,49 +423,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def start(
-        # ID or name of the container
-        id,
-        # Override the key sequence for detaching a container. Format is a single
-        # character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`,
-        # `[`, `,` or `_`.
-        detach_keys: nil,
-        request_options: {}
-      )
+      def start(id, detach_keys: nil, request_options: {})
       end
 
-      # This endpoint returns a live stream of a container’s resource usage statistics.
-      #
-      # The `precpu_stats` is the CPU statistic of the _previous_ read, and is used to
-      # calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats`
-      # field.
-      #
-      # If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for
-      # compatibility with older daemons the length of the corresponding
-      # `cpu_usage.percpu_usage` array should be used.
-      #
-      # On a cgroup v2 host, the following fields are not set
-      #
-      # - `blkio_stats`: all fields other than `io_service_bytes_recursive`
-      # - `cpu_stats`: `cpu_usage.percpu_usage`
-      # - `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields
-      #   are incompatible with cgroup v1.
-      #
-      # To calculate the values shown by the `stats` command of the docker cli tool the
-      # following formulas can be used:
-      #
-      # - used_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
-      # - used_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups
-      #   v2)
-      # - available_memory = `memory_stats.limit`
-      # - Memory usage % = `(used_memory / available_memory) * 100.0`
-      # - cpu_delta =
-      #   `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
-      # - system_cpu_delta =
-      #   `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
-      # - number_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or
-      #   `cpu_stats.online_cpus`
-      # - CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`
+      # Get container stats based on resource usage
       sig do
         params(
           id: String,
@@ -750,17 +435,7 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::StatsResponse)
       end
-      def stats(
-        # ID or name of the container
-        id,
-        # Only get a single stat instead of waiting for 2 cycles. Must be used with
-        # `stream=false`.
-        one_shot: nil,
-        # Stream the output. If false, the stats will be output once and then it will
-        # disconnect.
-        stream: nil,
-        request_options: {}
-      )
+      def stats(id, one_shot: nil, stream: nil, request_options: {})
       end
 
       # Stop a container
@@ -772,19 +447,10 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def stop(
-        # ID or name of the container
-        id,
-        # Signal to send to the container as an integer or string (e.g. `SIGINT`).
-        signal: nil,
-        # Number of seconds to wait before killing the container
-        t: nil,
-        request_options: {}
-      )
+      def stop(id, signal: nil, t: nil, request_options: {})
       end
 
-      # On Unix systems, this is done by running the `ps` command. This endpoint is not
-      # supported on Windows.
+      # List processes running inside a container
       sig do
         params(
           id: String,
@@ -792,30 +458,20 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::TopResponse)
       end
-      def top(
-        # ID or name of the container
-        id,
-        # The arguments to pass to `ps`. For example, `aux`
-        ps_args: nil,
-        request_options: {}
-      )
+      def top(id, ps_args: nil, request_options: {})
       end
 
-      # Resume a container which has been paused.
+      # Unpause a container
       sig do
         params(
           id: String,
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).void
       end
-      def unpause(
-        # ID or name of the container
-        id,
-        request_options: {}
-      )
+      def unpause(id, request_options: {})
       end
 
-      # Block until a container stops, then returns the exit code.
+      # Wait for a container
       sig do
         params(
           id: String,
@@ -823,15 +479,7 @@ module DockerEngineRuby
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::WaitResponse)
       end
-      def wait(
-        # ID or name of the container
-        id,
-        # Wait until a container state reaches the given condition.
-        #
-        # Defaults to `not-running` if omitted or empty.
-        condition: nil,
-        request_options: {}
-      )
+      def wait(id, condition: nil, request_options: {})
       end
 
       # @api private

data/rbi/docker_engine_ruby/resources/distribution.rbi

@@ -3,18 +3,14 @@
 module DockerEngineRuby
   module Resources
     class Distribution
-      # Return image digest and platform information by contacting the registry.
+      # Get image information from the registry
       sig do
         params(
           name: String,
           request_options: DockerEngineRuby::RequestOptions::OrHash
         ).returns(DockerEngineRuby::Inspect)
       end
-      def inspect_(
-        # Image name or id
-        name,
-        request_options: {}
-      )
+      def inspect_(name, request_options: {})
       end
 
       # @api private