docker.dang

"""
A Dagger module for working with Docker and Docker Compose projects.

https://dagger.io
https://docs.docker.com/reference/dockerfile/
"""
type Docker {
  """
  Image used for Dockerfile linting.
  """
  lintImage: String! = "docker.io/hadolint/hadolint:v2.14.0-alpine"

  """
  Extra hadolint arguments, e.g. ["--failure-threshold", "warning"].
  """
  lintArgs: [String!]! = []

  """
  Stage the project build check builds in Dockerfiles that declare it, e.g.
  "production". Empty, or a stage a Dockerfile doesn't declare, builds the
  final stage.
  """
  buildTarget: String! = ""

  """
  Image providing the standalone Compose binary at /docker-compose.
  """
  composeImage: String! = "docker.io/docker/compose-bin:v5.5.0"

  """
  Container that Compose services are attached to by injectServices.
  A blank container by default; override it in dagger.toml, e.g.

    settings.composeBase = ...

  to run the services alongside a container of your choosing.
  """
  composeBase: Container! = container

  """
  Environment variables added to the compose container by injectServices, as
  "key=value" pairs. Set them in dagger.toml, e.g.

    settings.composeEnvs = ["LOG_LEVEL=debug"]

  Only the first "=" separates the name from the value, so values may contain
  "=". An entry with no "=" sets an empty value.
  """
  composeEnvs: [String!]! = []

  """
  Docker projects at or below the working directory, keyed by the directory
  holding their Dockerfile.
  """
  projects(ws: Workspace!): DockerProjects! {
    DockerProjects(paths: roots(ws, ["Dockerfile"]), tool: self)
  }

  """
  Return the Docker project containing a path, relative to the client's cwd.

  By default, path may be a project root or a directory inside a project. Set
  findUp to false when path is already a project root and no lookup is needed.
  """
  project(ws: Workspace!, path: String!, findUp: Boolean! = true): DockerProject! {
    if (findUp) {
      let foundDockerfilePath = ws.findUp("Dockerfile", path)
      if (foundDockerfilePath == null) {
        raise "no Docker project found containing path: " + path
      } else {
        projectAt(directoryOf(foundDockerfilePath ?? ""))
      }
    } else {
      projectAt(rootPath(ws, path))
    }
  }

  """
  The Docker project rooted at a workspace-root-relative path.
  """
  let projectAt(path: String!): DockerProject! {
    DockerProject(path: path, tool: self)
  }

  """
  Workspace-root-relative directories holding one of markers at or below the
  working directory, plus the nearest enclosing one when the working
  directory holds none. Unique and sorted.
  """
  let roots(ws: Workspace!, markers: [String!]!): [String!]! {
    sorted(ws.findRoots(markers: markers).map { dir => rootPath(ws, dir) }.uniq)
  }

  """
  Resolve a path relative to the caller's location, as findRoots returns
  them, into a workspace-root-relative one, collapsing any leading "..".
  """
  let rootPath(ws: Workspace!, cwdRelPath: String!): String! {
    let segments = cwdRelPath.split("/").filter { s => s != "" and s != "." }
    let up = segments.filter { s => s == ".." }.length
    let down = segments.filter { s => s != ".." }
    let resolved = ws.cwd.split("/").filter { s => s != "" and s != "." }.dropLast(up) + down
    if (resolved.length == 0) { "." } else { resolved.join("/") }
  }

  """
  The workspace-root-relative directory of a workspace-root-absolute file
  path: "/a/b/Dockerfile" is "a/b", "/Dockerfile" is ".".
  """
  let directoryOf(filePath: String!): String! {
    let segments = filePath.split("/").filter { s => s != "" and s != "." }.dropLast(1)
    if (segments.length == 0) { "." } else { segments.join("/") }
  }

  """
  A workspace-root-relative path in the form Workspace.file and
  Workspace.directory read from the workspace root.
  """
  let absolutePath(path: String!): String! {
    if (path == ".") { "/" } else { "/" + path }
  }

  """
  items in byte order.
  """
  let sorted(items: [String!]!): [String!]! {
    let empty: [String!]! = []
    items.reduce(empty) { acc, item =>
      acc.takeWhile { x => x <= item } + [item] + acc.dropWhile { x => x <= item }
    }
  }

  """
  Why syncing ctr failed, or null: step and the end of the error.
  """
  let stepFailure(step: String!, ctr: Container!): String {
    {
      ctr.sync
      null
    } rescue {
      err: Error => step + " (" + failureDetail(err.message) + ")"
    }
  }

  """
  What an engine error says about a failed step: the exit code of a RUN
  step when it carries one, else the error without the engine's internal
  object IDs and load chains; either way, a pointer to the trace.
  """
  let failureDetail(message: String!): String! {
    let code = message.matchAll(`exit code: (\d+)`).map { m => m.captures[0] ?? "" }.takeLast(1).join("")
    if (code != "") {
      "exit code " + code + " in a RUN step; see the trace for its output"
    } else {
      cleanError(message) + "; see the trace for details"
    }
  }

  """
  An engine error without the internal object IDs and load chains it wraps
  around the actual cause.
  """
  let cleanError(message: String!): String! {
    message
      .rewriteMatches(`load [A-Za-z]+@[A-Za-z0-9+/=_-]+: `) { m => "" }
      .rewriteMatches(`(?:load xxh3:[0-9a-f]+: (?:inputs: )?)+`) { m => "" }
      .rewriteMatches(`failed to load container from converted ID: `) { m => "" }
      .trimSpace
      .split("\n")
      .takeLast(20)
      .join("\n")
  }

  """
  The failures of a batch, one line per failing item, under a heading; null
  when nothing failed.
  """
  let report(heading: String!, total: Int!, unit: String!, failures: [String!]!): String {
    if (failures.length == 0) {
      null
    } else {
      heading + " in " + toString(failures.length) + " of " + toString(total) + " " + unit + ":\n"
        + failures.map { f => "- " + f }.join("\n")
    }
  }

  """
  Spawn an ephemeral Docker Engine in a container.
  """
  engine(
    """
    Docker Engine version.
    """
    version: String! = "24.0",
    """
    Persist the state of the engine in a cache volume.
    """
    persist: Boolean! = true,
    """
    Namespace for persisting the engine state. Use in combination with persist.
    """
    namespace: String! = "",
  ): Service! {
    let base = container
      .from("index.docker.io/docker:" + version + "-dind")
      .withoutEntrypoint
      .withExposedPort(2375)
    let engineContainer = if (persist) {
      let volumeName = "docker-engine-state-" + version + (
        if (namespace == "") { "" } else { "-" + namespace }
      )
      base.withMountedCache("/var/lib/docker", cacheVolume(volumeName), sharing: LOCKED)
    } else {
      base
    }
    engineContainer.asService(
      args: [
        "dockerd",
        "--host=tcp://0.0.0.0:2375",
        "--host=unix:///var/run/docker.sock",
        "--tls=false",
      ],
      insecureRootCapabilities: true,
    )
  }

  """
  Tools for validating and running Docker Compose projects.
  """
  compose: Compose! {
    Compose(tool: self)
  }

  """
  Attach every service declared by the Compose project detected from the
  client's cwd to the base container as service bindings, then return that
  container. Each service is reachable from the container by its Compose
  service name (the binding's hostname).

  Exactly one project must be visible: enter a project directory to choose it.
  Each service is started from its image when it declares one, or by building
  its build context (with any build args) when it declares a build instead;
  services with neither are skipped. A service that declares a port has that
  container port exposed on its binding.

  The base container is the module's composeBase, blank by default; override
  it in dagger.toml via settings.composeBase. Any composeEnvs entries are set
  on it as environment variables.

  To attach only some services, use injectServices on a subset of a
  project's services collection.
  """
  injectServices(ws: Workspace!): Container! {
    let single = compose.single(ws)
    single.inject(ws, single.serviceSpecs(ws))
  }

  """
  The compose container with composeEnvs applied as environment variables.
  """
  let composeBaseWithEnvs: Container! {
    composeEnvs.reduce(composeBase) { ctr, entry =>
      let parts = entry.split("=", limit: 2)
      let name = parts[0] ?? ""
      if (name == "") {
        raise "invalid composeEnvs entry (expected \"key=value\"): " + entry
      } else {
        ctr.withEnvVariable(name, parts[1] ?? "")
      }
    }
  }

  """
  A Docker CLI ready to query this engine.
  """
  cli(
    """
    Version of the Docker CLI to run.
    """
    version: String! = "24.0",
    """
    Specify the Docker Engine to connect to. By default, run an ephemeral engine.
    """
    engine: Service = null,
  ): CLI! {
    CLI(engine: engine ?? self.engine(version: version))
  }
}

"""
A Docker client.
"""
type CLI {
  """
  The Docker Engine this client is wired to.
  """
  engine: Service!

  """
  Package the Docker CLI into a container, wired to an engine.
  """
  container: Container! {
    Dagger
      .container
      .from("index.docker.io/docker:cli")
      .withoutEntrypoint
      .withServiceBinding("dockerd", engine)
      .withEnvVariable("DOCKER_HOST", "tcp://dockerd:2375")
  }

  """
  Execute 'docker pull'.
  """
  pull(
    """
    The docker repository to pull from. Example: registry.dagger.io/engine
    """
    repository: String!,
    """
    The docker image tag to pull.
    """
    tag: String! = "latest",
  ): Image! {
    load(Dagger.container.from(repository + ":" + tag))
  }

  """
  Execute 'docker push'.
  """
  push(
    """
    The docker repository to push to.
    """
    repository: String!,
    """
    The tag to push to.
    """
    tag: String! = "latest",
  ): String! {
    image(repository: repository, tag: tag).push
  }

  """
  Execute 'docker pull' and return the CLI state, for chaining.
  """
  withPull(repository: String!, tag: String! = "latest"): CLI! {
    pull(repository, tag)
    self
  }

  """
  Execute 'docker push' and return the CLI state, for chaining.
  """
  withPush(repository: String!, tag: String! = "latest"): CLI! {
    push(repository, tag)
    self
  }

  """
  Load a container into the Docker Engine cache (docker load).
  """
  load(
    """
    The container to load.
    """
    ctr: Container!,
  ): Image! {
    let out = self
      .container
      .withMountedFile("/import.tar", ctr.asTarball)
      .withExec(["docker", "load", "-q", "-i", "/import.tar"])
      .stdout
    let m = out.match("Loaded image ID: (sha256:[a-fA-F0-9]{64})")
    if (m == null) {
      raise "docker load failed or went undetected"
    } else {
      let id = m.captures[0]
      if (id == null) {
        raise "docker load failed or went undetected"
      } else {
        Image(client: self, localID: id)
      }
    }
  }

  """
  Look up an image in the local Docker Engine cache.
  If exactly one image matches the filters, return it. Otherwise, raise an error.
  """
  image(
    """
    Filter by image repository.
    """
    repository: String! = "",
    """
    Filter by image tag.
    """
    tag: String! = "latest",
    """
    Filter by image local ID (short IDs are allowed).
    """
    localID: String! = "",
  ): Image! {
    let matches = images(repository: repository, tag: tag, localID: localID)
    let criteria = "repository=" + repository + " tag=" + tag + " id=" + localID
    if (matches.length > 1) {
      raise "more than one image matches the search criteria: " + criteria
    }
    let found = matches[0]
    if (found == null) {
      raise "no image matches the search criteria: " + criteria
    } else {
      found
    }
  }

  """
  List images in the local Docker Engine cache.
  """
  images(
    """
    Filter by image repository.
    """
    repository: String! = "",
    """
    Filter by image tag.
    """
    tag: String! = "",
    """
    Filter by image local ID.
    """
    localID: String! = "",
  ): [Image!]! {
    self
      .container
      .withExec(["docker", "image", "list", "-a", "--no-trunc", "--format", "{{json .}}"])
      .stdout
      .split("\n")
      .filter { line => line != "" }
      .map { line =>
        JSON.decode(line) :: {{ID: String!, Repository: String!, Tag: String!}}!
      }
      .filter { info =>
        (repository == "" or repository == info.Repository)
          and (tag == "" or tag == info.Tag)
          and (localID == "" or info.ID.hasPrefix(localID))
      }
      .map { info =>
        Image(client: self, localID: info.ID, repository: info.Repository, tag: info.Tag)
      }
  }

  """
  Run a container with the docker CLI.
  """
  run(
    """
    Name of the image to run. Example: registry.dagger.io/engine
    """
    name: String!,
    """
    Tag of the image to run.
    """
    tag: String! = "latest",
    """
    Additional arguments.
    """
    args: [String!]! = [],
  ): String! {
    self.container.withExec(["docker", "run", name + ":" + tag] + args).stdout
  }
}

"""
An image stored in the local Docker Engine cache.
"""
type Image {
  let client: CLI!

  """
  The local identifier of the docker image.
  """
  localID: String!

  """
  The image repository.
  """
  repository: String! = ""

  """
  The image tag.
  """
  tag: String! = ""

  """
  Export this image from the docker engine into Dagger.
  """
  export: Container! {
    let archive = client
      .container
      .withExec(["docker", "image", "save", "-o", "/export.tar", localID])
      .file("/export.tar")
    Dagger.container.import(archive)
  }

  """
  Push this image to a registry.
  """
  push: String! {
    export.publish(ref)
  }

  """
  Return the image's ref (remote address).
  """
  ref: String! {
    let refTag = if (tag == "") { "latest" } else { tag }
    let address = repository + ":" + refTag
    if (localID == "") { address } else { address + "@" + localID }
  }
}

"""
Docker projects in a workspace, keyed by the directory holding their
Dockerfile.
"""
type DockerProjects @collection {
  """
  Project root paths, relative to the workspace root.
  """
  paths: [String!]! @keys

  let tool: Docker!

  """
  The Docker project rooted at path.
  """
  project(path: String!): DockerProject! @get {
    tool.projectAt(path)
  }

  """
  Lint the Dockerfiles of the selected projects with hadolint.
  """
  lint(ws: Workspace!): Void @check {
    # A selection over a list evaluates its elements concurrently, so every
    # project is linted in parallel and every failure is reported.
    let failures = paths.map { p => project(p) }.{{path, failure: lintFailure(ws)}}
      .filter { r => r.failure != null }
      .map { r => r.path + ": " + (r.failure ?? "") }
    let failed = tool.report("hadolint failed", paths.length, "projects", failures)
    if (failed != null) {
      raise failed ?? ""
    }
    null
  }

  """
  Build the Dockerfiles of the selected projects.
  """
  build(ws: Workspace!): Void @check {
    let failures = paths.map { p => project(p) }.{{path, failure: buildFailure(ws)}}
      .filter { r => r.failure != null }
      .map { r => r.path + ": " + (r.failure ?? "") }
    let failed = tool.report("docker build failed", paths.length, "projects", failures)
    if (failed != null) {
      raise failed ?? ""
    }
    null
  }
}

"""
A Docker project rooted at a directory containing a Dockerfile.
"""
type DockerProject {
  """
  Project root, relative to the workspace root.
  """
  path: String!

  let tool: Docker!

  """
  Workspace-root-relative path of this project's Dockerfile.
  """
  dockerfilePath: String! {
    if (path == ".") { "Dockerfile" } else { path + "/Dockerfile" }
  }

  """
  Build context mounted for this project's Docker commands.
  """
  buildContext(ws: Workspace!): Directory! {
    ws.directory(tool.absolutePath(path))
  }

  """
  The container built from this project's Dockerfile.
  """
  container(
    ws: Workspace!,
    """
    Target build stage to build. Empty builds the final stage.
    """
    target: String! = "",
    """
    Platform to build for, e.g. "linux/amd64". Defaults to the host platform.
    """
    platform: String = null,
  ): Container! {
    if (platform == null) {
      buildContext(ws).dockerBuild(target: target)
    } else {
      buildContext(ws).dockerBuild(target: target, platform: platform :: Platform!)
    }
  }

  """
  Lint this project's Dockerfile with hadolint.
  """
  lint(ws: Workspace!): Void @check {
    let failure = lintFailure(ws)
    if (failure != null) {
      raise path + ": " + (failure ?? "")
    }
    null
  }

  """
  Build this project's Dockerfile.
  """
  build(ws: Workspace!): Void @check {
    let failure = buildFailure(ws)
    if (failure != null) {
      raise path + ": " + (failure ?? "")
    }
    null
  }

  """
  The stage the build check builds: the buildTarget setting when this
  Dockerfile declares it, else "" for the final stage.
  """
  let defaultTarget(ws: Workspace!): String! {
    let wanted = tool.buildTarget.toLower
    if (wanted != "" and allStages(ws).any { s => (s.name ?? "").toLower == wanted }) {
      tool.buildTarget
    } else {
      ""
    }
  }

  """
  Named stages of this project's Dockerfile that its build never reaches: no
  other stage references them, and they are neither the final stage nor the
  buildTarget setting. Keyed by stage name.
  """
  stages(ws: Workspace!): DockerStages! {
    let all = allStages(ws)
    let last = all.length - 1
    let target = tool.buildTarget.toLower
    let names = all
      .filter { s =>
        s.name != null and s.referenced == false and s.index != last and (s.name ?? "").toLower != target
      }
      .map { s => s.name ?? "" }
    DockerStages(names: tool.sorted(names.uniq), all: all, project: self)
  }

  """
  Build stages declared in this project's Dockerfile, in declaration order.

  Stages are parsed from FROM instructions as described in the Dockerfile
  reference (https://docs.docker.com/reference/dockerfile/). Parsing is
  line-based: a FROM inside a heredoc or after a line continuation is not
  distinguished from a real instruction.
  """
  allStages(ws: Workspace!): [DockerStage!]! {
    let empty: [DockerStage!]! = []
    {
      parseStages(ws.file(tool.absolutePath(dockerfilePath)).contents)
    } rescue {
      err: Error => empty
    }
  }

  """
  Return the named build stage of this project's Dockerfile.
  """
  stage(ws: Workspace!, name: String!): DockerStage! {
    let found = allStages(ws).filter { candidate => candidate.name == name }[0]
    if (found == null) {
      raise "no stage named \"" + name + "\" in " + dockerfilePath
    } else {
      found
    }
  }

  """
  The stages declared by a Dockerfile's contents.
  """
  let parseStages(text: String!): [DockerStage!]! {
    # A leading byte order mark would hide the first FROM.
    let contents = text.rewriteMatches(`^\x{FEFF}`) { m => "" }
    let fromMatches = contents.matchAll("(?im)^\\s*FROM\\s+(?:--\\S+\\s+)*(\\S+)(?:\\s+AS\\s+(\\S+))?")
    # Stage references, lowercased since stage names are case-insensitive:
    # FROM bases, COPY/ADD --from=<ref>, and RUN --mount=...,from=<ref>.
    let references = fromMatches.map { m => (m.captures[0] ?? "").toLower }
      + contents.matchAll("(?i)--from=(\\S+)").map { m => (m.captures[0] ?? "").toLower }
      + contents.matchAll("(?i)[=,]from=([^,\\s]+)").map { m => (m.captures[0] ?? "").toLower }
    fromMatches.map { m, i =>
      let stageName = m.captures[1]
      let name = if (stageName == "" or stageName == null) { null } else { stageName }
      DockerStage(
        project: self,
        index: i,
        base: m.captures[0] ?? "",
        name: name,
        referenced: references.contains((name ?? "").toLower)
          or references.contains(toString(i)),
      )
    }
  }

  """
  Why hadolint failed on this project's Dockerfile, or null.
  """
  let lintFailure(ws: Workspace!): String {
    let config = hadolintConfig(ws)
    let base = Dagger
      .container
      .from(tool.lintImage)
      .withWorkdir("/src")
      .withDirectory(".", buildContext(ws), include: ["Dockerfile"])
    let empty: [String!]! = []
    let configured = if (config == null) {
      base
    } else {
      base.withFile("/config/hadolint.yaml", ws.file(config ?? ""))
    }
    let configArgs = if (config == null) { empty } else { ["--config", "/config/hadolint.yaml"] }
    let ran = configured.withExec(
      ["hadolint", "--no-color"] + configArgs + tool.lintArgs + ["Dockerfile"],
      expect: ReturnType.ANY,
    )
    let code = ran.exitCode
    if (code == 0) {
      null
    } else {
      let output = (ran.stdout + "\n" + ran.stderr).trimSpace.split("\n").takeLast(40).join("\n")
      "hadolint failed (exit " + toString(code) + ")" + (if (output == "") { "" } else { ":\n" + output })
    }
  }

  """
  The nearest .hadolint.yaml or .hadolint.yml from this project's directory
  up to the workspace root, as a workspace-root-absolute path, or null.
  """
  let hadolintConfig(ws: Workspace!): String {
    let start = tool.absolutePath(path)
    let found = [ws.findUp(".hadolint.yaml", start), ws.findUp(".hadolint.yml", start)]
      .map { f => f ?? "" }
      .filter { f => f != "" }
    # The deeper file is the nearer one.
    found.reduce(null) { best, f =>
      if (best == null or f.split("/").length > (best ?? "").split("/").length) { f } else { best }
    }
  }

  """
  Why building this project's Dockerfile failed, or null.
  """
  let buildFailure(ws: Workspace!): String {
    tool.stepFailure("docker build failed", container(ws, target: defaultTarget(ws)))
  }
}

"""
Named stages of a Dockerfile that a default build never reaches, keyed by
stage name.
"""
type DockerStages @collection {
  """
  Stage names.
  """
  names: [String!]! @keys

  """
  Every stage of the Dockerfile, for looking up a key.
  """
  let all: [DockerStage!]!

  let project: DockerProject!

  """
  The Dockerfile stage with this name.
  """
  stage(name: String!): DockerStage! @get {
    let found = all.filter { s => s.name == name }[0]
    if (found == null) {
      raise "no stage named \"" + name + "\""
    } else {
      found
    }
  }

  """
  Build the selected stages.
  """
  buildStage(ws: Workspace!): Void @check {
    let failures = names.map { n => stage(n) }.{{label, failure: buildFailure(ws)}}
      .filter { r => r.failure != null }
      .map { r => r.label + ": " + (r.failure ?? "") }
    let failed = project.tool.report(
      "docker build failed",
      names.length,
      "stages",
      failures,
    )
    if (failed != null) {
      raise failed ?? ""
    }
    null
  }
}

"""
A build stage of a Docker project's Dockerfile.
"""
type DockerStage {
  """
  The Docker project whose Dockerfile declares this stage.
  """
  let project: DockerProject!

  """
  Zero-based position of this stage in the Dockerfile.
  """
  index: Int!

  """
  Image or prior stage this stage builds from.
  """
  base: String!

  """
  Stage name declared with AS. Null for unnamed stages.
  """
  name: String

  """
  Whether another stage in the Dockerfile references this stage, as a FROM
  base, a COPY/ADD --from source, or a RUN --mount from source. References by
  name (case-insensitive) and by stage index are both counted.
  """
  referenced: Boolean!

  """
  The project path and stage, as failures name them.
  """
  let label: String! {
    project.path + " (stage " + (name ?? toString(index)) + ")"
  }

  """
  The container built from this stage of the project's Dockerfile.
  """
  container(
    ws: Workspace!,
    """
    Platform to build for, e.g. "linux/amd64". Defaults to the host platform.
    """
    platform: String = null,
  ): Container! {
    let target = name
    if (target == null) {
      raise "cannot build stage " + toString(index) + " of " + project.dockerfilePath
        + " by target: it has no name"
    } else {
      project.container(ws, target: target ?? "", platform: platform)
    }
  }

  """
  Build this Dockerfile stage.
  """
  buildStage(ws: Workspace!): Void @check {
    let failure = buildFailure(ws)
    if (failure != null) {
      raise label + ": " + (failure ?? "")
    }
    null
  }

  """
  Why building this stage failed, or null.
  """
  let buildFailure(ws: Workspace!): String {
    project.tool.stepFailure("docker build failed", container(ws))
  }
}