schema

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2024 License: Apache-2.0 Imports: 62 Imported by: 1

README

Core API proposal

This directory contains a proposal for a complete GraphQL API for Dagger. It is written with the following goals in mind:

  1. Feature parity with Dagger 0.2
  2. Close to feature parity with Buildkit, with an incremental path to reaching full parity in the future
  3. Follow established graphql best practices
  4. Sove as many outstanding DX problems as possible

Reference

DX problems solved

Some problems in the DX that are not yet resolved, and this proposal would help solve, include:

  • Uncertainty as to how to express uploads in a graphql-friendly way (deployment, image push, git push, etc)
  • Chaining of FS operations greatly reduces verbosity, but cannot be applied all the time
  • Transitioning a script to an extension requires non-trivial refactoring, to tease apart the script-specific code from the underlying "API".
  • The API sandbox is amazing for prototyping small queries, but of limited use when multiple queries must reference each other. This is because the native code doing the stitching cannot be run by the playground, so filesystem IDs must be manually copy-pasted between queries.

Design highlights

withX and withoutX

To avoid the use of rpc-style verbs (a graphql best practice) and maximize chaining (a strength of our DX), we use the terminology withX and withoutX.

A field of the form withX returns the same object with content X added or changed.

Example:

"An empty directory with a README copied to it"
query readmeDir($readme: FileID!) {
  directory {
    withFile(source: $readme, path: "README.md") {
      id
    }
}

"An empty container with an app directory mounted into it"
query appContainer($app: DirectoryID!) {
  container {
    withMountedDirectory(source: $app, path: "/app") {
      id
    }
  }
}

A field of the form withoutX returns the same object with content X removed.

"Remove node_modules from a JS project"
query removeNodeModules($dir: DirectoryID!) {
  directory(id: $dir) {
    withoutDirectory(path: "node_modules") {
      id
    }
  }
}
Secrets

Secret handling has been simplified and made more consistent with Directory handling.

  • Secrets have an ID, and can be loaded by ID in the standard graphql manner
  • Secrets can be created in one of two ways:
    1. From an environment variable: type Environment { secret }
    2. From a file: type Directory { secret }
Embrace the llb / Dockerfile model

The Container type proposes an expansive definition of the container, similar to the Buildkit/Dockerfile model. A Container is:

  1. A filesystem state
  2. An OCI artifact which can be pulled from, and pushed to a repository at any time
  3. A persistent configuration to be applied to all commands executed inside it

This is similar to how buildkit models llb state, and how the Dockerfile language models stage state. Note that Dagger extends this model to include even mount configuration (which are scoped to exec in buildkit, but scoped to container in dagger).

Examples:

"""
Download a file over HTTP in a very convoluted way:

1. Download a base linux container
2. Install curl
3. Download the file into the container
4. Load and return the file
"""
query convolutedDownload($url: String!) {
  container {
    from(address: "index.docker.io/alpine:latest") {
      exec(args: ["apk", "add", "curl"]) {
        exec(args: ["curl", "-o", "/tmp/download", $url) {
          file(path: "/tmp/download") {
            id
         }
      }
    }
  }
}

"""
Specialize two containers from a common base
"""
query twoContainers {
  container {
    from(address: "alpine") {
      debug: withVariable(name: "DEBUG", value: "1") {
        id
        exec(args: ["env"]) {
          stdout
        }
      }
      noDebug: withVariable(name: "DEBUG", value: "0") {
        id
        exec(args: ["env"]) {
          stdout
        }
      }
    }
  }
}

Documentation

Index

Constants

View Source 
const InstrumentationLibrary = "dagger.io/engine.schema"

Variables

View Source 
var AllVersion = dagql.AllView{}

AllVersion is a view that contains all versions.

Functions

func SchemaIntrospectionJSON added in v0.11.7 

func SchemaIntrospectionJSON(ctx context.Context, dag *dagql.Server) (json.RawMessage, error)

func Syncer added in v0.9.7 

func Syncer[T Evaluatable]() dagql.Field[T]

Types

type AfterVersion added in v0.12.0 

type AfterVersion string

AfterVersion is a view that checks if a target version is greater than *or* equal to the filtered version.

func (AfterVersion) Contains added in v0.12.0 

func (minVersion AfterVersion) Contains(version string) bool

type BeforeVersion added in v0.12.0 

type BeforeVersion string

BeforeVersion is a view that checks if a target version is less than the filtered version.

func (BeforeVersion) Contains added in v0.12.0 

func (maxVersion BeforeVersion) Contains(version string) bool

type CoreMod added in v0.9.4 

type CoreMod struct {
	Dag *dagql.Server
}

CoreMod is a special implementation of Mod for our core API, which is not *technically* a true module yet but can be treated as one in terms of dependencies. It has no dependencies itself and is currently an implicit dependency of every user module.

func (*CoreMod) Dependencies added in v0.9.4 

func (m *CoreMod) Dependencies() []core.Mod

func (*CoreMod) Install added in v0.9.7 

func (m *CoreMod) Install(ctx context.Context, dag *dagql.Server) error

func (*CoreMod) ModTypeFor added in v0.9.4 

func (m *CoreMod) ModTypeFor(ctx context.Context, typeDef *core.TypeDef, checkDirectDeps bool) (core.ModType, bool, error)

func (*CoreMod) Name added in v0.9.4 

func (m *CoreMod) Name() string

func (*CoreMod) TypeDefs added in v0.9.6 

func (m *CoreMod) TypeDefs(ctx context.Context) ([]*core.TypeDef, error)

func (*CoreMod) View added in v0.12.0 

func (m *CoreMod) View() (string, bool)

type CoreModEnum added in v0.12.0 

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

func (*CoreModEnum) CollectCoreIDs added in v0.12.1 

func (enum *CoreModEnum) CollectCoreIDs(ctx context.Context, value dagql.Typed, ids map[digest.Digest]*resource.ID) error

func (*CoreModEnum) ConvertFromSDKResult added in v0.12.0 

func (enum *CoreModEnum) ConvertFromSDKResult(ctx context.Context, value any) (dagql.Typed, error)

func (*CoreModEnum) ConvertToSDKInput added in v0.12.0 

func (enum *CoreModEnum) ConvertToSDKInput(ctx context.Context, value dagql.Typed) (any, error)

func (*CoreModEnum) SourceMod added in v0.12.0 

func (enum *CoreModEnum) SourceMod() core.Mod

func (*CoreModEnum) TypeDef added in v0.12.0 

func (enum *CoreModEnum) TypeDef() *core.TypeDef

type CoreModObject added in v0.9.4 

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

CoreModObject represents objects from core (Container, Directory, etc.)

func (*CoreModObject) CollectCoreIDs added in v0.12.1 

func (obj *CoreModObject) CollectCoreIDs(ctx context.Context, value dagql.Typed, ids map[digest.Digest]*resource.ID) error

func (*CoreModObject) ConvertFromSDKResult added in v0.9.4 

func (obj *CoreModObject) ConvertFromSDKResult(ctx context.Context, value any) (dagql.Typed, error)

func (*CoreModObject) ConvertToSDKInput added in v0.9.4 

func (obj *CoreModObject) ConvertToSDKInput(ctx context.Context, value dagql.Typed) (any, error)

func (*CoreModObject) SourceMod added in v0.9.4 

func (obj *CoreModObject) SourceMod() core.Mod

func (*CoreModObject) TypeDef added in v0.9.6 

func (obj *CoreModObject) TypeDef() *core.TypeDef

type CoreModScalar added in v0.11.3 

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

CoreModScalar represents scalars from core (Platform, etc)

func (*CoreModScalar) CollectCoreIDs added in v0.12.1 

func (obj *CoreModScalar) CollectCoreIDs(context.Context, dagql.Typed, map[digest.Digest]*resource.ID) error

func (*CoreModScalar) ConvertFromSDKResult added in v0.11.3 

func (obj *CoreModScalar) ConvertFromSDKResult(ctx context.Context, value any) (dagql.Typed, error)

func (*CoreModScalar) ConvertToSDKInput added in v0.11.3 

func (obj *CoreModScalar) ConvertToSDKInput(ctx context.Context, value dagql.Typed) (any, error)

func (*CoreModScalar) SourceMod added in v0.11.3 

func (obj *CoreModScalar) SourceMod() core.Mod

func (*CoreModScalar) TypeDef added in v0.11.3 

func (obj *CoreModScalar) TypeDef() *core.TypeDef

type EnvVariable 

type EnvVariable struct {
	Name  string `field:"true" doc:"The environment variable name."`
	Value string `field:"true" doc:"The environment variable value."`
}

func (EnvVariable) Description added in v0.9.7 

func (EnvVariable) Description() string

func (EnvVariable) Type added in v0.9.7 

func (EnvVariable) Type() *ast.Type

func (EnvVariable) TypeDescription added in v0.9.7 

func (EnvVariable) TypeDescription() string

type Evaluatable added in v0.9.7 

type Evaluatable interface {
	dagql.Typed
	Evaluate(context.Context) (*buildkit.Result, error)
}

type Label added in v0.3.10 

type Label struct {
	Name  string `field:"true" doc:"The label name."`
	Value string `field:"true" doc:"The label value."`
}

func (Label) Type added in v0.9.7 

func (Label) Type() *ast.Type

func (Label) TypeDescription added in v0.9.7 

func (Label) TypeDescription() string

type ModuleSourceWithInitConfigArgs added in v0.12.5 

type ModuleSourceWithInitConfigArgs struct {
	Merge bool `default:"false"`
}

type PipelineLabel added in v0.11.0 

type PipelineLabel struct {
	Name  string `field:"true" doc:"Label name."`
	Value string `field:"true" doc:"Label value."`
}

PipelineLabel is deprecated and has no effect.

func (PipelineLabel) TypeDescription added in v0.11.0 

func (PipelineLabel) TypeDescription() string

func (PipelineLabel) TypeName added in v0.11.0 

func (PipelineLabel) TypeName() string

type SDK added in v0.9.0 

type SDK string
const (
	SDKGo         SDK = "go"
	SDKPython     SDK = "python"
	SDKTypescript SDK = "typescript"
	SDKPHP        SDK = "php"
	SDKElixir     SDK = "elixir"
)

type SchemaResolvers added in v0.9.4 

type SchemaResolvers interface {
	Install()
}

type WithDirectoryArgs added in v0.9.7 

type WithDirectoryArgs struct {
	Path      string
	Directory core.DirectoryID

	core.CopyFilter
}

type WithFileArgs added in v0.9.7 

type WithFileArgs struct {
	Path        string
	Source      core.FileID
	Permissions *int
}

type WithFilesArgs added in v0.9.10 

type WithFilesArgs struct {
	Path        string
	Sources     []core.FileID
	Permissions *int
}

Source Files

View all Source files

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.