Skip to content

Client API #1597

@shykes

Description

@shykes

Overview

I propose a new API for securely accessing the client machine from a Dagger plan. This is informed by:

Proposed design

This is a work in progress. Fire at will.

package dagger

#Plan: {

  // Access client machine
  client: {

    // Access client filesystem
    // Path may be absolute, or relative to client working directory
    filesystem: [path=string]: {
      // Read data from that path
      // CUE type defines expected content:
      //     string: contents of a regular file
      //     #FS: contents of a directory
      //     #Secret: secure reference to the file contents
      //     #Service: unix socket
      read?: string | #FS | #Secret | #Service

      // If set, Write to that path
      write?: string | #FS | #Secret | #Service | {
          contents: string | #FS | #Secret | #Service
          {
              create: true
              permissions?: int
          } | *{
             create: false
          }
      }
    }

    // Access client environment variables
    env: [string]: *string | #Secret

    // Execute commands in the client
    commands: [id=string]: {
      name: string
      args: [...string]
      flags: [string]: bool | string
      env: [string]: string
      // Capture standard output (as a string or secret)
      stdout?: *string | #Secret
      // Capture standard error (as a string or secret)
      stderr?: *string | #Secret
      // Inject standard input (from a string or secret)
      stdin?: string | #Secret
    }

    // Informatiom about the client machine running `dagger`
    platform: {
      // Hardware architecture
      arch: "x86_64" | "arm64"

      // Operating system
      os: "linux" | "darwin" | "windows"
  }
}

Example usage:

package main

import (
  "dagger.io/dagger"
)

dagger.#Plan & {
  client: {
    platform: string
    arch: string
    filesystem: {
      "/home/shykes/dagger": read: dagger.#FS
      "/home/shykes/dagger/README.md": read: string
      "/tmp/message": "Hello, wowrld!"
      "output_dir": write: actions.build.output
    }
    env: GITHUB_API_TOKEN: dagger.#Secret
    command: {
      whoami: name: "whoami"
    }
  }

  actions: build: {
    output: container.export.directories."/src/cmd/dagger"
    container: docker.#Run & {
      mount: src: {
        contents: client.filesystem."/home/shykes/dagger".read
        dest: "/src"
      }
      command: {
        name: "make"
        args: ["dagger"]
      }
      export: directories: "/src/cmd/dagger": _
      env: client.env
    }
}

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions