Module: Docker::API::Platform

Defined in:
lib/docker/api/platform.rb,
sig/docker/api/core.rbs

Overview

Platform selectors, in the two encodings the Engine API uses for them.

The API is not consistent here, and the inconsistency is silent. Some endpoints want the familiar string:

POST /containers/create?platform=linux/arm64
POST /build?platform=linux/arm64
POST /images/create?platform=linux/arm64

while others want a JSON-encoded OCI platform object:

GET  /images/{name}/json?platform={"os":"linux","architecture":"arm64"}
POST /images/{name}/push?platform={"os":"linux","architecture":"arm64"}
GET  /images/{name}/history?platform={...}

Sending the string where the object is expected fails with 400 failed to parse platform: invalid character 'l', which does not obviously mean "wrong encoding" to anyone reading it for the first time.

Callers of this gem write "linux/arm64" everywhere and the ergonomic layer encodes whichever form the endpoint in question wants.

Class Method Summary collapse

Class Method Details

.oci(value) ⇒ Hash?

Parse a platform into its OCI object form.

Examples:

Platform.oci("linux/arm64")   #=> {"os"=>"linux", "architecture"=>"arm64"}
Platform.oci("linux/arm/v7")  #=> {"os"=>"linux", "architecture"=>"arm", "variant"=>"v7"}

Parameters:

  • value (String, Hash, nil) —

    "os/arch", "os/arch/variant", an already-built OCI hash, or nil

Returns:

  • (Hash, nil) —

    with "os", "architecture" and optionally "variant"



41
42
43
44
45
46
47
48
49
 
# File 'lib/docker/api/platform.rb', line 41

def oci(value)
  return nil if value.nil?
  return value if value.is_a?(Hash)

  os, architecture, variant = value.to_s.split("/", 3)
  return nil if os.nil? || os.empty?

  { "os" => os, "architecture" => architecture, "variant" => variant }.compact
end

.string(value) ⇒ String?

Render a platform in the os[/arch[/variant]] string form.

Examples:

Platform.string("os" => "linux", "architecture" => "arm64") #=> "linux/arm64"

Parameters:

  • value (String, Hash, nil)

Returns:

  • (String, nil) 


58
59
60
61
62
63
64
65
 
# File 'lib/docker/api/platform.rb', line 58

def string(value)
  return nil if value.nil?
  return value if value.is_a?(String)

  [value["os"] || value[:os],
   value["architecture"] || value[:architecture],
   value["variant"] || value[:variant]].compact.join("/")
end