dagger

package module
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 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.

Will execute default command if none is set, or error if there's no default.

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.

Will execute default command if none is set, or error if there's no default.

func (*Container) Stdout 

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

The output stream of the last executed command.

Will execute default command if none is set, or error if there's no default.

func (*Container) User 

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

Retrieves the user to be set for all commands.

func (*Container) With added in v0.6.1 

func (r *Container) With(f WithContainerFunc) *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").
		With(func(c *dagger.Container) *dagger.Container {
			return c.WithEnvVariable("FOO", "bar")
		})

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

	fmt.Println(out)
}

Output:

bar

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, opts ...ContainerWithMountedDirectoryOpts) *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, opts ...ContainerWithMountedFileOpts) *Container

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

func (*Container) WithMountedSecret 

func (r *Container) WithMountedSecret(path string, source *Secret, opts ...ContainerWithMountedSecretOpts) *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, executing the default command if none is set.

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, opts ...ContainerWithUnixSocketOpts) *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
	// Secrets to pass to the build.
	//
	// They will be mounted at /run/secrets/[secret-name].
	Secrets []*Secret
}

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
	// A user:group to set for the directory and its contents.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithDirectoryOpts contains options for Container.WithDirectory

type ContainerWithExecOpts added in v0.4.1 

type ContainerWithExecOpts struct {
	// If the container has an entrypoint, ignore it for args rather than using it to wrap them.
	SkipEntrypoint bool
	// 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
	// A user:group to set for the file.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

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
	// A user:group to set for the mounted cache directory.
	//
	// Note that this changes the ownership of the specified mount along with the
	// initial filesystem provided by source (if any). It does not have any effect
	// if/when the cache has already been created.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithMountedCacheOpts contains options for Container.WithMountedCache

type ContainerWithMountedDirectoryOpts added in v0.6.1 

type ContainerWithMountedDirectoryOpts struct {
	// A user:group to set for the mounted directory and its contents.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithMountedDirectoryOpts contains options for Container.WithMountedDirectory

type ContainerWithMountedFileOpts added in v0.6.1 

type ContainerWithMountedFileOpts struct {
	// A user or user:group to set for the mounted file.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithMountedFileOpts contains options for Container.WithMountedFile

type ContainerWithMountedSecretOpts added in v0.6.1 

type ContainerWithMountedSecretOpts struct {
	// A user:group to set for the mounted secret.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithMountedSecretOpts contains options for Container.WithMountedSecret

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
	// A user:group to set for the file.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithNewFileOpts contains options for Container.WithNewFile

type ContainerWithUnixSocketOpts added in v0.6.1 

type ContainerWithUnixSocketOpts struct {
	// A user:group to set for the mounted socket.
	//
	// The user and group can either be an ID (1000:1000) or a name (foo:bar).
	//
	// If the group is omitted, it defaults to the same as the user.
	Owner string
}

ContainerWithUnixSocketOpts contains options for Container.WithUnixSocket

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) With added in v0.6.1 

func (r *Directory) With(f WithDirectoryFunc) *Directory

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
	// Secrets to pass to the build.
	//
	// They will be mounted at /run/secrets/[secret-name].
	Secrets []*Secret
}

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

type WithContainerFunc added in v0.6.1 

type WithContainerFunc func(r *Container) *Container

type WithDirectoryFunc added in v0.6.1 

type WithDirectoryFunc func(r *Directory) *Directory

Source Files

View all Source files

Directories

Path Synopsis
internal
engineconn
querybuilder

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.