dagger

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 7, 2023 License: Apache-2.0 Imports: 20 Imported by: 315

README

Dagger Go SDK

A client package for running Dagger pipelines.

NOTE: the canonical version of this module is ./sdk/go in the dagger/dagger repo.

The dagger/dagger-go-sdk repo is a read-only replica; do not edit it.

The canonical import for this package is dagger.io/dagger.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Serve

func Serve(server any)

Types

type BuildArg added in v0.4.3

type BuildArg struct {
	// The build argument name.
	Name string `json:"name"`

	// The build argument value.
	Value string `json:"value"`
}

Key value object that represents a build argument.

type CacheID

type CacheID string

A global cache volume identifier.

type CacheSharingMode added in v0.4.5

type CacheSharingMode string
const (
	Locked  CacheSharingMode = "LOCKED"
	Private CacheSharingMode = "PRIVATE"
	Shared  CacheSharingMode = "SHARED"
)

type CacheVolume

type CacheVolume struct {
	// contains filtered or unexported fields
}

A directory whose contents persist across runs.

func (*CacheVolume) ID

func (r *CacheVolume) ID(ctx context.Context) (CacheID, error)

func (*CacheVolume) XXX_GraphQLID added in v0.4.0

func (r *CacheVolume) XXX_GraphQLID(ctx context.Context) (string, error)

XXX_GraphQLID is an internal function. It returns the underlying type ID

func (*CacheVolume) XXX_GraphQLType added in v0.4.0

func (r *CacheVolume) XXX_GraphQLType() string

XXX_GraphQLType is an internal function. It returns the native GraphQL type name

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Dagger Engine Client

func Connect

func Connect(ctx context.Context, opts ...ClientOpt) (_ *Client, rerr error)

Connect to a Dagger Engine

func (*Client) CacheVolume added in v0.4.4

func (r *Client) CacheVolume(key string) *CacheVolume

Constructs a cache volume for a given cache key.

func (*Client) Close

func (c *Client) Close() error

Close the engine connection

func (*Client) Container added in v0.4.4

func (r *Client) Container(opts ...ContainerOpts) *Container

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.

func (*Client) DefaultPlatform added in v0.4.4

func (r *Client) DefaultPlatform(ctx context.Context) (Platform, error)

The default platform of the builder.

func (*Client) Directory added in v0.4.4

func (r *Client) Directory(opts ...DirectoryOpts) *Directory

Load a directory by ID. No argument produces an empty directory.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *Request, resp *Response) error

Do sends a GraphQL request to the engine

func (*Client) File added in v0.4.4

func (r *Client) File(id FileID) *File

Loads a file by ID.

func (*Client) Git added in v0.4.4

func (r *Client) Git(url string, opts ...GitOpts) *GitRepository

Queries a git repository.

func (*Client) HTTP added in v0.4.4

func (r *Client) HTTP(url string, opts ...HTTPOpts) *File

Returns a file containing an http remote url content.

func (*Client) Host added in v0.4.4

func (r *Client) Host() *Host

Queries the host environment.

func (*Client) Pipeline added in v0.4.4

func (r *Client) Pipeline(name string, opts ...PipelineOpts) *Client

Creates a named sub-pipeline.

func (*Client) Project added in v0.4.4

func (r *Client) Project(name string) *Project

Look up a project by name

func (*Client) Secret added in v0.4.4

func (r *Client) Secret(id SecretID) *Secret

Loads a secret from its ID.

func (*Client) SetSecret added in v0.5.1

func (r *Client) SetSecret(name string, plaintext string) *Secret

Sets a secret given a user defined name to its plaintext and returns the secret.

func (*Client) Socket added in v0.4.4

func (r *Client) Socket(opts ...SocketOpts) *Socket

Loads a socket by its ID.

type ClientOpt

type ClientOpt interface {
	// contains filtered or unexported methods
}

ClientOpt holds a client option

func WithConfigPath

func WithConfigPath(path string) ClientOpt

WithConfigPath sets the engine config path

func WithLogOutput

func WithLogOutput(writer io.Writer) ClientOpt

WithLogOutput sets the progress writer

func WithNoExtensions

func WithNoExtensions() ClientOpt

WithNoExtensions disables installing extensions

func WithWorkdir

func WithWorkdir(path string) ClientOpt

WithWorkdir sets the engine workdir

type Container

type Container struct {
	// contains filtered or unexported fields
}

An OCI-compatible container, also known as a docker container.

Example
package main

import (
	"context"
	"fmt"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	alpine := client.Container().From("alpine:3.16.2")

	out, err := alpine.Exec(dagger.ContainerExecOpts{
		Args: []string{"cat", "/etc/alpine-release"},
	}).Stdout(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Println(out)

}
Output:

3.16.2

func (*Container) Build

func (r *Container) Build(context *Directory, opts ...ContainerBuildOpts) *Container

Initializes this container from a Dockerfile build.

Example
package main

import (
	"context"
	"fmt"
	"strings"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	repo := client.Git("https://github.com/dagger/dagger").
		Tag("v0.3.0").
		Tree()

	daggerImg := client.Container().Build(repo)

	out, err := daggerImg.Exec(dagger.ContainerExecOpts{
		Args: []string{"version"},
	}).Stdout(ctx)
	if err != nil {
		panic(err)
	}

	words := strings.Split(strings.TrimSpace(out), " ")
	fmt.Println(words[0])

}
Output:

dagger

func (*Container) DefaultArgs

func (r *Container) DefaultArgs(ctx context.Context) ([]string, error)

Retrieves default arguments for future commands.

func (*Container) Directory

func (r *Container) Directory(path string) *Directory

Retrieves a directory at the given path.

Mounts are included.

func (*Container) Endpoint added in v0.4.6

func (r *Container) Endpoint(ctx context.Context, opts ...ContainerEndpointOpts) (string, error)

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.

func (*Container) Entrypoint

func (r *Container) Entrypoint(ctx context.Context) ([]string, error)

Retrieves entrypoint to be prepended to the arguments of all commands.

func (*Container) EnvVariable

func (r *Container) EnvVariable(ctx context.Context, name string) (string, error)

Retrieves the value of the specified environment variable.

func (*Container) EnvVariables

func (r *Container) EnvVariables(ctx context.Context) ([]EnvVariable, error)

Retrieves the list of environment variables passed to commands.

func (*Container) Exec deprecated

func (r *Container) Exec(opts ...ContainerExecOpts) *Container

Retrieves this container after executing the specified command inside it.

Deprecated: Replaced by WithExec.

func (*Container) ExitCode

func (r *Container) ExitCode(ctx context.Context) (int, error)

Exit code of the last executed command. Zero means success. Errors if no command has been executed.

func (*Container) Export added in v0.4.0

func (r *Container) Export(ctx context.Context, path string, opts ...ContainerExportOpts) (bool, error)

Writes the container as an OCI tarball to the destination file path on the host for the specified platform variants.

Return true on success. It can also publishes platform variants.

func (*Container) ExposedPorts added in v0.4.6

func (r *Container) ExposedPorts(ctx context.Context) ([]Port, error)

Retrieves the list of exposed ports.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

func (*Container) FS deprecated

func (r *Container) FS() *Directory

Retrieves this container's root filesystem. Mounts are not included.

Deprecated: Replaced by Rootfs.

func (*Container) File

func (r *Container) File(path string) *File

Retrieves a file at the given path.

Mounts are included.

func (*Container) From

func (r *Container) From(address string) *Container

Initializes this container from a pulled base image.

func (*Container) Hostname added in v0.4.6

func (r *Container) Hostname(ctx context.Context) (string, error)

Retrieves a hostname which can be used by clients to reach this container.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

func (*Container) ID

func (r *Container) ID(ctx context.Context) (ContainerID, error)

A unique identifier for this container.

func (*Container) ImageRef added in v0.4.6

func (r *Container) ImageRef(ctx context.Context) (string, error)

The unique image reference which can only be retrieved immediately after the 'Container.From' call.

func (*Container) Import added in v0.6.0

func (r *Container) Import(source *File, opts ...ContainerImportOpts) *Container

Reads the container from an OCI tarball.

NOTE: this involves unpacking the tarball to an OCI store on the host at $XDG_CACHE_DIR/dagger/oci. This directory can be removed whenever you like.

func (*Container) Label added in v0.4.4

func (r *Container) Label(ctx context.Context, name string) (string, error)

Retrieves the value of the specified label.

func (*Container) Labels added in v0.4.4

func (r *Container) Labels(ctx context.Context) ([]Label, error)

Retrieves the list of labels passed to container.

func (*Container) Mounts

func (r *Container) Mounts(ctx context.Context) ([]string, error)

Retrieves the list of paths where a directory is mounted.

func (*Container) Pipeline added in v0.4.4

func (r *Container) Pipeline(name string, opts ...ContainerPipelineOpts) *Container

Creates a named sub-pipeline

func (*Container) Platform added in v0.4.0

func (r *Container) Platform(ctx context.Context) (Platform, error)

The platform this container executes and publishes as.

func (*Container) Publish

func (r *Container) Publish(ctx context.Context, address string, opts ...ContainerPublishOpts) (string, error)

Publishes this container as a new image to the specified address.

Publish returns a fully qualified ref. It can also publish platform variants.

func (*Container) Rootfs added in v0.4.1

func (r *Container) Rootfs() *Directory

Retrieves this container's root filesystem. Mounts are not included.

func (*Container) Stderr

func (r *Container) Stderr(ctx context.Context) (string, error)

The error stream of the last executed command. Errors if no command has been executed.

func (*Container) Stdout

func (r *Container) Stdout(ctx context.Context) (string, error)

The output stream of the last executed command. Errors if no command has been executed.

func (*Container) User

func (r *Container) User(ctx context.Context) (string, error)

Retrieves the user to be set for all commands.

func (*Container) WithDefaultArgs

func (r *Container) WithDefaultArgs(opts ...ContainerWithDefaultArgsOpts) *Container

Configures default arguments for future commands.

func (*Container) WithDirectory added in v0.4.2

func (r *Container) WithDirectory(path string, directory *Directory, opts ...ContainerWithDirectoryOpts) *Container

Retrieves this container plus a directory written at the given path.

func (*Container) WithEntrypoint

func (r *Container) WithEntrypoint(args []string) *Container

Retrieves this container but with a different command entrypoint.

func (*Container) WithEnvVariable

func (r *Container) WithEnvVariable(name string, value string) *Container

Retrieves this container plus the given environment variable.

Example
package main

import (
	"context"
	"fmt"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	container := client.Container().From("alpine:3.16.2")

	container = container.WithEnvVariable("FOO", "bar")

	out, err := container.Exec(dagger.ContainerExecOpts{
		Args: []string{"sh", "-c", "echo $FOO"},
	}).Stdout(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Println(out)

}
Output:

bar

func (*Container) WithExec added in v0.4.1

func (r *Container) WithExec(args []string, opts ...ContainerWithExecOpts) *Container

Retrieves this container after executing the specified command inside it.

func (*Container) WithExposedPort added in v0.4.6

func (r *Container) WithExposedPort(port int, opts ...ContainerWithExposedPortOpts) *Container

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.

func (*Container) WithFS deprecated

func (r *Container) WithFS(id *Directory) *Container

Initializes this container from this DirectoryID.

Deprecated: Replaced by WithRootfs.

func (*Container) WithFile added in v0.4.2

func (r *Container) WithFile(path string, source *File, opts ...ContainerWithFileOpts) *Container

Retrieves this container plus the contents of the given file copied to the given path.

func (*Container) WithLabel added in v0.4.4

func (r *Container) WithLabel(name string, value string) *Container

Retrieves this container plus the given label.

func (*Container) WithMountedCache

func (r *Container) WithMountedCache(path string, cache *CacheVolume, opts ...ContainerWithMountedCacheOpts) *Container

Retrieves this container plus a cache volume mounted at the given path.

Example
package main

import (
	"context"
	"fmt"
	"strconv"
	"time"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	cacheKey := "example-cache"

	cache := client.CacheVolume(cacheKey)

	container := client.Container().From("alpine:3.16.2")

	container = container.WithMountedCache("/cache", cache)

	filename := time.Now().Format("2006-01-02-15-04-05")
	echoCmd := fmt.Sprintf("echo $0 >> /cache/%[1]v.txt; cat /cache/%[1]v.txt", filename)

	var out string
	for i := 0; i < 5; i++ {
		out, err = container.Exec(dagger.ContainerExecOpts{
			Args: []string{"sh", "-c", echoCmd, strconv.Itoa(i)},
		}).Stdout(ctx)
		if err != nil {
			panic(err)
		}
	}

	fmt.Printf("%q", out)

}
Output:

"0\n1\n2\n3\n4\n"

func (*Container) WithMountedDirectory

func (r *Container) WithMountedDirectory(path string, source *Directory) *Container

Retrieves this container plus a directory mounted at the given path.

Example
package main

import (
	"context"
	"fmt"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	dir := client.Directory().
		WithNewFile("hello.txt", "Hello, world!").
		WithNewFile("goodbye.txt", "Goodbye, world!")

	container := client.Container().From("alpine:3.16.2")

	container = container.WithMountedDirectory("/mnt", dir)

	out, err := container.Exec(dagger.ContainerExecOpts{
		Args: []string{"ls", "/mnt"},
	}).Stdout(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%q", out)

}
Output:

"goodbye.txt\nhello.txt\n"

func (*Container) WithMountedFile

func (r *Container) WithMountedFile(path string, source *File) *Container

Retrieves this container plus a file mounted at the given path.

func (*Container) WithMountedSecret

func (r *Container) WithMountedSecret(path string, source *Secret) *Container

Retrieves this container plus a secret mounted into a file at the given path.

func (*Container) WithMountedTemp

func (r *Container) WithMountedTemp(path string) *Container

Retrieves this container plus a temporary directory mounted at the given path.

func (*Container) WithNewFile added in v0.4.2

func (r *Container) WithNewFile(path string, opts ...ContainerWithNewFileOpts) *Container

Retrieves this container plus a new file written at the given path.

func (*Container) WithRegistryAuth added in v0.4.5

func (r *Container) WithRegistryAuth(address string, username string, secret *Secret) *Container

Retrieves this container with a registry authentication for a given address.

func (*Container) WithRootfs added in v0.4.1

func (r *Container) WithRootfs(id *Directory) *Container

Initializes this container from this DirectoryID.

func (*Container) WithSecretVariable

func (r *Container) WithSecretVariable(name string, secret *Secret) *Container

Retrieves this container plus an env variable containing the given secret.

func (*Container) WithServiceBinding added in v0.4.6

func (r *Container) WithServiceBinding(alias string, service *Container) *Container

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.

func (*Container) WithUnixSocket added in v0.4.2

func (r *Container) WithUnixSocket(path string, source *Socket) *Container

Retrieves this container plus a socket forwarded to the given Unix socket path.

func (*Container) WithUser

func (r *Container) WithUser(name string) *Container

Retrieves this container with a different command user.

func (*Container) WithWorkdir

func (r *Container) WithWorkdir(path string) *Container

Retrieves this container with a different working directory.

func (*Container) WithoutEnvVariable

func (r *Container) WithoutEnvVariable(name string) *Container

Retrieves this container minus the given environment variable.

func (*Container) WithoutExposedPort added in v0.4.6

func (r *Container) WithoutExposedPort(port int, opts ...ContainerWithoutExposedPortOpts) *Container

Unexpose a previously exposed port.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

func (*Container) WithoutLabel added in v0.4.4

func (r *Container) WithoutLabel(name string) *Container

Retrieves this container minus the given environment label.

func (*Container) WithoutMount

func (r *Container) WithoutMount(path string) *Container

Retrieves this container after unmounting everything at the given path.

func (*Container) WithoutRegistryAuth added in v0.4.5

func (r *Container) WithoutRegistryAuth(address string) *Container

Retrieves this container without the registry authentication of a given address.

func (*Container) WithoutUnixSocket added in v0.4.2

func (r *Container) WithoutUnixSocket(path string) *Container

Retrieves this container with a previously added Unix socket removed.

func (*Container) Workdir

func (r *Container) Workdir(ctx context.Context) (string, error)

Retrieves the working directory for all commands.

func (*Container) XXX_GraphQLID added in v0.4.0

func (r *Container) XXX_GraphQLID(ctx context.Context) (string, error)

XXX_GraphQLID is an internal function. It returns the underlying type ID

func (*Container) XXX_GraphQLType added in v0.4.0

func (r *Container) XXX_GraphQLType() string

XXX_GraphQLType is an internal function. It returns the native GraphQL type name

type ContainerBuildOpts

type ContainerBuildOpts struct {
	// Path to the Dockerfile to use.
	//
	// Default: './Dockerfile'.
	Dockerfile string
	// Additional build arguments.
	BuildArgs []BuildArg
	// Target build stage to build.
	Target string
}

ContainerBuildOpts contains options for Container.Build

type ContainerEndpointOpts added in v0.4.6

type ContainerEndpointOpts struct {
	// The exposed port number for the endpoint
	Port int
	// Return a URL with the given scheme, eg. http for http://
	Scheme string
}

ContainerEndpointOpts contains options for Container.Endpoint

type ContainerExecOpts

type ContainerExecOpts struct {
	// Command to run instead of the container's default command (e.g., ["run", "main.go"]).
	Args []string
	// Content to write to the command's standard input before closing (e.g., "Hello world").
	Stdin string
	// Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
	RedirectStdout string
	// Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
	RedirectStderr string
	// 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.
	ExperimentalPrivilegedNesting bool
}

ContainerExecOpts contains options for Container.Exec

type ContainerExportOpts added in v0.4.0

type ContainerExportOpts struct {
	// Identifiers for other platform specific containers.
	// Used for multi-platform image.
	PlatformVariants []*Container
}

ContainerExportOpts contains options for Container.Export

type ContainerID

type ContainerID string

A unique container identifier. Null designates an empty container (scratch).

type ContainerImportOpts added in v0.6.0

type ContainerImportOpts struct {
	// Identifies the tag to import from the archive, if the archive bundles
	// multiple tags.
	Tag string
}

ContainerImportOpts contains options for Container.Import

type ContainerOpts

type ContainerOpts struct {
	ID ContainerID

	Platform Platform
}

ContainerOpts contains options for Query.Container

type ContainerPipelineOpts added in v0.4.4

type ContainerPipelineOpts struct {
	// Pipeline description.
	Description string
	// Pipeline labels.
	Labels []PipelineLabel
}

ContainerPipelineOpts contains options for Container.Pipeline

type ContainerPublishOpts added in v0.4.0

type ContainerPublishOpts struct {
	// Identifiers for other platform specific containers.
	// Used for multi-platform image.
	PlatformVariants []*Container
}

ContainerPublishOpts contains options for Container.Publish

type ContainerWithDefaultArgsOpts

type ContainerWithDefaultArgsOpts struct {
	// Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).
	Args []string
}

ContainerWithDefaultArgsOpts contains options for Container.WithDefaultArgs

type ContainerWithDirectoryOpts added in v0.4.2

type ContainerWithDirectoryOpts struct {
	// Patterns to exclude in the written directory (e.g., ["node_modules/**", ".gitignore", ".git/"]).
	Exclude []string
	// Patterns to include in the written directory (e.g., ["*.go", "go.mod", "go.sum"]).
	Include []string
}

ContainerWithDirectoryOpts contains options for Container.WithDirectory

type ContainerWithExecOpts added in v0.4.1

type ContainerWithExecOpts struct {
	// Content to write to the command's standard input before closing (e.g., "Hello world").
	Stdin string
	// Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
	RedirectStdout string
	// Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
	RedirectStderr string
	// 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.
	ExperimentalPrivilegedNesting bool
	// 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.
	InsecureRootCapabilities bool
}

ContainerWithExecOpts contains options for Container.WithExec

type ContainerWithExposedPortOpts added in v0.4.6

type ContainerWithExposedPortOpts struct {
	// Transport layer network protocol
	Protocol NetworkProtocol
	// Optional port description
	Description string
}

ContainerWithExposedPortOpts contains options for Container.WithExposedPort

type ContainerWithFileOpts added in v0.4.3

type ContainerWithFileOpts struct {
	// Permission given to the copied file (e.g., 0600).
	//
	// Default: 0644.
	Permissions int
}

ContainerWithFileOpts contains options for Container.WithFile

type ContainerWithMountedCacheOpts

type ContainerWithMountedCacheOpts struct {
	// Identifier of the directory to use as the cache volume's root.
	Source *Directory
	// Sharing mode of the cache volume.
	Sharing CacheSharingMode
}

ContainerWithMountedCacheOpts contains options for Container.WithMountedCache

type ContainerWithNewFileOpts added in v0.4.2

type ContainerWithNewFileOpts struct {
	// Content of the file to write (e.g., "Hello world!").
	Contents string
	// Permission given to the written file (e.g., 0600).
	//
	// Default: 0644.
	Permissions int
}

ContainerWithNewFileOpts contains options for Container.WithNewFile

type ContainerWithoutExposedPortOpts added in v0.4.6

type ContainerWithoutExposedPortOpts struct {
	// Port protocol to unexpose
	Protocol NetworkProtocol
}

ContainerWithoutExposedPortOpts contains options for Container.WithoutExposedPort

type Directory

type Directory struct {
	// contains filtered or unexported fields
}

A directory.

Example
package main

import (
	"context"
	"fmt"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	dir := client.Directory().
		WithNewFile("hello.txt", "Hello, world!").
		WithNewFile("goodbye.txt", "Goodbye, world!")

	entries, err := dir.Entries(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Println(entries)

}
Output:

[goodbye.txt hello.txt]

func (*Directory) Diff

func (r *Directory) Diff(other *Directory) *Directory

Gets the difference between this directory and an another directory.

func (*Directory) Directory

func (r *Directory) Directory(path string) *Directory

Retrieves a directory at the given path.

func (*Directory) DockerBuild added in v0.4.2

func (r *Directory) DockerBuild(opts ...DirectoryDockerBuildOpts) *Container

Builds a new Docker container from this directory.

func (*Directory) Entries

func (r *Directory) Entries(ctx context.Context, opts ...DirectoryEntriesOpts) ([]string, error)

Returns a list of files and directories at the given path.

func (*Directory) Export added in v0.4.0

func (r *Directory) Export(ctx context.Context, path string) (bool, error)

Writes the contents of the directory to a path on the host.

func (*Directory) File

func (r *Directory) File(path string) *File

Retrieves a file at the given path.

func (*Directory) ID

func (r *Directory) ID(ctx context.Context) (DirectoryID, error)

The content-addressed identifier of the directory.

func (*Directory) LoadProject

func (r *Directory) LoadProject(configPath string) *Project

load a project's metadata

func (*Directory) Pipeline added in v0.4.4

func (r *Directory) Pipeline(name string, opts ...DirectoryPipelineOpts) *Directory

Creates a named sub-pipeline

func (*Directory) WithDirectory

func (r *Directory) WithDirectory(path string, directory *Directory, opts ...DirectoryWithDirectoryOpts) *Directory

Retrieves this directory plus a directory written at the given path.

func (*Directory) WithFile added in v0.4.0

func (r *Directory) WithFile(path string, source *File, opts ...DirectoryWithFileOpts) *Directory

Retrieves this directory plus the contents of the given file copied to the given path.

func (*Directory) WithNewDirectory added in v0.4.0

func (r *Directory) WithNewDirectory(path string, opts ...DirectoryWithNewDirectoryOpts) *Directory

Retrieves this directory plus a new directory created at the given path.

func (*Directory) WithNewFile

func (r *Directory) WithNewFile(path string, contents string, opts ...DirectoryWithNewFileOpts) *Directory

Retrieves this directory plus a new file written at the given path.

func (*Directory) WithTimestamps added in v0.4.3

func (r *Directory) WithTimestamps(timestamp int) *Directory

Retrieves this directory with all file/dir timestamps set to the given time.

func (*Directory) WithoutDirectory

func (r *Directory) WithoutDirectory(path string) *Directory

Retrieves this directory with the directory at the given path removed.

func (*Directory) WithoutFile

func (r *Directory) WithoutFile(path string) *Directory

Retrieves this directory with the file at the given path removed.

func (*Directory) XXX_GraphQLID added in v0.4.0

func (r *Directory) XXX_GraphQLID(ctx context.Context) (string, error)

XXX_GraphQLID is an internal function. It returns the underlying type ID

func (*Directory) XXX_GraphQLType added in v0.4.0

func (r *Directory) XXX_GraphQLType() string

XXX_GraphQLType is an internal function. It returns the native GraphQL type name

type DirectoryDockerBuildOpts added in v0.4.2

type DirectoryDockerBuildOpts struct {
	// Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
	//
	// Defaults: './Dockerfile'.
	Dockerfile string
	// The platform to build.
	Platform Platform
	// Build arguments to use in the build.
	BuildArgs []BuildArg
	// Target build stage to build.
	Target string
}

DirectoryDockerBuildOpts contains options for Directory.DockerBuild

type DirectoryEntriesOpts

type DirectoryEntriesOpts struct {
	// Location of the directory to look at (e.g., "/src").
	Path string
}

DirectoryEntriesOpts contains options for Directory.Entries

type DirectoryID

type DirectoryID string

A content-addressed directory identifier.

type DirectoryOpts

type DirectoryOpts struct {
	ID DirectoryID
}

DirectoryOpts contains options for Query.Directory

type DirectoryPipelineOpts added in v0.4.4

type DirectoryPipelineOpts struct {
	// Pipeline description.
	Description string
	// Pipeline labels.
	Labels []PipelineLabel
}

DirectoryPipelineOpts contains options for Directory.Pipeline

type DirectoryWithDirectoryOpts added in v0.4.0

type DirectoryWithDirectoryOpts struct {
	// Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
	Exclude []string
	// Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
	Include []string
}

DirectoryWithDirectoryOpts contains options for Directory.WithDirectory

type DirectoryWithFileOpts added in v0.4.3

type DirectoryWithFileOpts struct {
	// Permission given to the copied file (e.g., 0600).
	//
	// Default: 0644.
	Permissions int
}

DirectoryWithFileOpts contains options for Directory.WithFile

type DirectoryWithNewDirectoryOpts added in v0.4.3

type DirectoryWithNewDirectoryOpts struct {
	// Permission granted to the created directory (e.g., 0777).
	//
	// Default: 0755.
	Permissions int
}

DirectoryWithNewDirectoryOpts contains options for Directory.WithNewDirectory

type DirectoryWithNewFileOpts

type DirectoryWithNewFileOpts struct {
	// Permission given to the copied file (e.g., 0600).
	//
	// Default: 0644.
	Permissions int
}

DirectoryWithNewFileOpts contains options for Directory.WithNewFile

type EnvVariable

type EnvVariable struct {
	// contains filtered or unexported fields
}

A simple key value object that represents an environment variable.

func (*EnvVariable) Name

func (r *EnvVariable) Name(ctx context.Context) (string, error)

The environment variable name.

func (*EnvVariable) Value

func (r *EnvVariable) Value(ctx context.Context) (string, error)

The environment variable value.

type File

type File struct {
	// contains filtered or unexported fields
}

A file.

func (*File) Contents

func (r *File) Contents(ctx context.Context) (string, error)

Retrieves the contents of the file.

func (*File) Export added in v0.4.0

func (r *File) Export(ctx context.Context, path string) (bool, error)

Writes the file to a file path on the host.

func (*File) ID

func (r *File) ID(ctx context.Context) (FileID, error)

Retrieves the content-addressed identifier of the file.

func (*File) Secret deprecated

func (r *File) Secret() *Secret

Retrieves a secret referencing the contents of this file.

Deprecated: insecure, leaves secret in cache. Superseded by SetSecret

func (*File) Size

func (r *File) Size(ctx context.Context) (int, error)

Gets the size of the file, in bytes.

func (*File) WithTimestamps added in v0.4.3

func (r *File) WithTimestamps(timestamp int) *File

Retrieves this file with its created/modified timestamps set to the given time.

func (*File) XXX_GraphQLID added in v0.4.0

func (r *File) XXX_GraphQLID(ctx context.Context) (string, error)

XXX_GraphQLID is an internal function. It returns the underlying type ID

func (*File) XXX_GraphQLType added in v0.4.0

func (r *File) XXX_GraphQLType() string

XXX_GraphQLType is an internal function. It returns the native GraphQL type name

type FileID

type FileID string

A file identifier.

type GitOpts added in v0.4.1

type GitOpts struct {
	// Set to true to keep .git directory.
	KeepGitDir bool
	// A service which must be started before the repo is fetched.
	ExperimentalServiceHost *Container
}

GitOpts contains options for Query.Git

type GitRef

type GitRef struct {
	// contains filtered or unexported fields
}

A git ref (tag, branch or commit).

func (*GitRef) Digest

func (r *GitRef) Digest(ctx context.Context) (string, error)

The digest of the current value of this ref.

func (*GitRef) Tree

func (r *GitRef) Tree(opts ...GitRefTreeOpts) *Directory

The filesystem tree at this ref.

type GitRefTreeOpts added in v0.4.2

type GitRefTreeOpts struct {
	SSHKnownHosts string

	SSHAuthSocket *Socket
}

GitRefTreeOpts contains options for GitRef.Tree

type GitRepository

type GitRepository struct {
	// contains filtered or unexported fields
}

A git repository.

Example
package main

import (
	"context"
	"fmt"
	"strings"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	readme, err := client.Git("https://github.com/dagger/dagger").
		Tag("v0.3.0").
		Tree().File("README.md").Contents(ctx)
	if err != nil {
		panic(err)
	}

	lines := strings.Split(strings.TrimSpace(readme), "\n")
	fmt.Println(lines[0])

}
Output:

## What is Dagger?

func (*GitRepository) Branch

func (r *GitRepository) Branch(name string) *GitRef

Returns details on one branch.

func (*GitRepository) Branches

func (r *GitRepository) Branches(ctx context.Context) ([]string, error)

Lists of branches on the repository.

func (*GitRepository) Commit added in v0.4.1

func (r *GitRepository) Commit(id string) *GitRef

Returns details on one commit.

func (*GitRepository) Tag

func (r *GitRepository) Tag(name string) *GitRef

Returns details on one tag.

func (*GitRepository) Tags

func (r *GitRepository) Tags(ctx context.Context) ([]string, error)

Lists of tags on the repository.

type HTTPOpts added in v0.4.6

type HTTPOpts struct {
	// A service which must be started before the URL is fetched.
	ExperimentalServiceHost *Container
}

HTTPOpts contains options for Query.HTTP

type Host

type Host struct {
	// contains filtered or unexported fields
}

Information about the host execution environment.

func (*Host) Directory

func (r *Host) Directory(path string, opts ...HostDirectoryOpts) *Directory

Accesses a directory on the host.

Example
package main

import (
	"context"
	"fmt"
	"strings"

	"dagger.io/dagger"
)

func main() {
	ctx := context.Background()
	client, err := dagger.Connect(ctx, dagger.WithWorkdir("."))
	if err != nil {
		panic(err)
	}
	defer client.Close()

	readme, err := client.Host().Directory(".").File("README.md").Contents(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%v\n", strings.Contains(readme, "Dagger"))

}
Output:

true

func (*Host) EnvVariable

func (r *Host) EnvVariable(name string) *HostVariable

Accesses an environment variable on the host.

func (*Host) UnixSocket added in v0.4.2

func (r *Host) UnixSocket(path string) *Socket

Accesses a Unix socket on the host.

func (*Host) Workdir deprecated

func (r *Host) Workdir(opts ...HostWorkdirOpts) *Directory

Retrieves the current working directory on the host.

Deprecated: Use Directory with path set to '.' instead.

type HostDirectoryOpts added in v0.4.0

type HostDirectoryOpts struct {
	// Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
	Exclude []string
	// Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
	Include []string
}

HostDirectoryOpts contains options for Host.Directory

type HostVariable

type HostVariable struct {
	// contains filtered or unexported fields
}

An environment variable on the host environment.

func (*HostVariable) Secret deprecated

func (r *HostVariable) Secret() *Secret

A secret referencing the value of this variable.

Deprecated: been superseded by SetSecret

func (*HostVariable) Value

func (r *HostVariable) Value(ctx context.Context) (string, error)

The value of this variable.

type HostWorkdirOpts added in v0.4.0

type HostWorkdirOpts struct {
	// Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
	Exclude []string
	// Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
	Include []string
}

HostWorkdirOpts contains options for Host.Workdir

type Label added in v0.4.4

type Label struct {
	// contains filtered or unexported fields
}

A simple key value object that represents a label.

func (*Label) Name added in v0.4.4

func (r *Label) Name(ctx context.Context) (string, error)

The label name.

func (*Label) Value added in v0.4.4

func (r *Label) Value(ctx context.Context) (string, error)

The label value.

type NetworkProtocol added in v0.4.6

type NetworkProtocol string
const (
	Tcp NetworkProtocol = "TCP"
	Udp NetworkProtocol = "UDP"
)

type PipelineLabel added in v0.5.0

type PipelineLabel struct {
	// Label name.
	Name string `json:"name"`

	// Label value.
	Value string `json:"value"`
}

Key value object that represents a Pipeline label.

type PipelineOpts added in v0.4.4

type PipelineOpts struct {
	// Pipeline description.
	Description string
	// Pipeline labels.
	Labels []PipelineLabel
}

PipelineOpts contains options for Query.Pipeline

type Platform added in v0.4.0

type Platform string

The platform config OS and architecture in a Container.

The format is os/[platform]/[version] (e.g., "darwin/arm64/v7", "windows/amd64", "linux/arm64").

type Port added in v0.4.6

type Port struct {
	// contains filtered or unexported fields
}

A port exposed by a container.

func (*Port) Description added in v0.4.6

func (r *Port) Description(ctx context.Context) (string, error)

The port description.

func (*Port) Port added in v0.4.6

func (r *Port) Port(ctx context.Context) (int, error)

The port number.

func (*Port) Protocol added in v0.4.6

func (r *Port) Protocol(ctx context.Context) (NetworkProtocol, error)

The transport layer network protocol.

type Project

type Project struct {
	// contains filtered or unexported fields
}

A set of scripts and/or extensions

func (*Project) Extensions

func (r *Project) Extensions(ctx context.Context) ([]Project, error)

extensions in this project

func (*Project) GeneratedCode

func (r *Project) GeneratedCode() *Directory

Code files generated by the SDKs in the project

func (*Project) Install

func (r *Project) Install(ctx context.Context) (bool, error)

install the project's schema

func (*Project) Name

func (r *Project) Name(ctx context.Context) (string, error)

name of the project

func (*Project) SDK

func (r *Project) SDK(ctx context.Context) (string, error)

sdk used to generate code for and/or execute this project

func (*Project) Schema

func (r *Project) Schema(ctx context.Context) (string, error)

schema provided by the project

type Request

type Request struct {
	// The literal string representing the GraphQL query, e.g.
	// `query myQuery { myField }`.
	Query string `json:"query"`
	// A JSON-marshalable value containing the variables to be sent
	// along with the query, or nil if there are none.
	Variables interface{} `json:"variables,omitempty"`
	// The GraphQL operation name. The server typically doesn't
	// require this unless there are multiple queries in the
	// document, but genqlient sets it unconditionally anyway.
	OpName string `json:"operationName"`
}

Request contains all the values required to build queries executed by the graphql.Client.

Typically, GraphQL APIs will accept a JSON payload of the form

{"query": "query myQuery { ... }", "variables": {...}}`

and Request marshals to this format. However, MakeRequest may marshal the data in some other way desired by the backend.

type Response

type Response struct {
	Data       interface{}            `json:"data"`
	Extensions map[string]interface{} `json:"extensions,omitempty"`
	Errors     gqlerror.List          `json:"errors,omitempty"`
}

Response that contains data returned by the GraphQL API.

Typically, GraphQL APIs will return a JSON payload of the form

{"data": {...}, "errors": {...}}

It may additionally contain a key named "extensions", that might hold GraphQL protocol extensions. Extensions and Errors are optional, depending on the values returned by the server.

type Secret

type Secret struct {
	// contains filtered or unexported fields
}

A reference to a secret value, which can be handled more safely than the value itself.

func (*Secret) ID

func (r *Secret) ID(ctx context.Context) (SecretID, error)

The identifier for this secret.

func (*Secret) Plaintext

func (r *Secret) Plaintext(ctx context.Context) (string, error)

The value of this secret.

func (*Secret) XXX_GraphQLID added in v0.4.0

func (r *Secret) XXX_GraphQLID(ctx context.Context) (string, error)

XXX_GraphQLID is an internal function. It returns the underlying type ID

func (*Secret) XXX_GraphQLType added in v0.4.0

func (r *Secret) XXX_GraphQLType() string

XXX_GraphQLType is an internal function. It returns the native GraphQL type name

type SecretID

type SecretID string

A unique identifier for a secret.

type Socket added in v0.4.2

type Socket struct {
	// contains filtered or unexported fields
}

func (*Socket) ID added in v0.4.2

func (r *Socket) ID(ctx context.Context) (SocketID, error)

The content-addressed identifier of the socket.

func (*Socket) XXX_GraphQLID added in v0.4.2

func (r *Socket) XXX_GraphQLID(ctx context.Context) (string, error)

XXX_GraphQLID is an internal function. It returns the underlying type ID

func (*Socket) XXX_GraphQLType added in v0.4.2

func (r *Socket) XXX_GraphQLType() string

XXX_GraphQLType is an internal function. It returns the native GraphQL type name

type SocketID added in v0.4.2

type SocketID string

A content-addressed socket identifier.

type SocketOpts added in v0.4.2

type SocketOpts struct {
	ID SocketID
}

SocketOpts contains options for Query.Socket

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL