client

package
v1.0.0-beta.28 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 91 Imported by: 2

Documentation

Index

Constants

View Source
const InstrumentationLibrary = "dagger.io/engine.client"
View Source
const StableIDFileName = "stable_client_id"

Variables

View Source
var ErrLiveLogsUnsupported = errors.New("engine does not serve on-demand live log reads")

ErrLiveLogsUnsupported reports that the engine does not serve on-demand live log reads: it predates them, so the log push carries everything.

View Source
var ErrTelemetryBarrierUnsupported = errors.New("engine does not serve a telemetry barrier")

ErrTelemetryBarrierUnsupported reports that the engine predates TelemetryBarrier (enginetel.LiveFeatureFlush).

Functions

func GetHostStableID added in v0.12.3

func GetHostStableID(lg *slog.Logger) string

GetHostStableID returns a random ID that's persisted in the caller's XDG state directory. It's currently used to identify clients that are executing on the same host in order to tell buildkit which filesync cache ref to re-use when syncing dirs+files to the engine.

func NestedSession

func NestedSession() bool

NestedSession reports whether Connect joins the session of the exec or CLI that started this process, as a nested client of it. The engine delivers a nested client's telemetry to its ancestors as well as to the client itself.

func Tracer added in v0.11.0

func Tracer(ctx context.Context) trace.Tracer

Types

type AuthProxy added in v0.19.7

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

func NewAuthProxy added in v0.19.7

func NewAuthProxy(client auth.AuthClient) AuthProxy

func (AuthProxy) Credentials added in v0.19.7

func (AuthProxy) FetchToken added in v0.19.7

func (AuthProxy) GetTokenAuthority added in v0.19.7

func (AuthProxy) Register added in v0.19.7

func (p AuthProxy) Register(server *grpc.Server)

func (AuthProxy) VerifyTokenAuthority added in v0.19.7

type Client

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

func Connect

func Connect(ctx context.Context, params Params) (_ *Client, rerr error)

func ConnectEngineToEngine added in v0.19.7

func ConnectEngineToEngine(ctx context.Context, params EngineToEngineParams) (_ *Client, rerr error)

ConnectEngineToEngine connects a Dagger client to another Dagger engine using an existing session connection. Session attachables are proxied back to the original client.

func (*Client) AppendHTTPRequestHeaders added in v0.11.8

func (c *Client) AppendHTTPRequestHeaders(headers http.Header) http.Header

func (*Client) Close

func (c *Client) Close() error

func (*Client) CloseWithContext

func (c *Client) CloseWithContext(ctx context.Context) (rerr error)

CloseWithContext uses one caller-controlled deadline for graceful shutdown and telemetry draining. Transport cleanup still runs when the deadline expires.

func (*Client) Dagger added in v0.8.8

func (c *Client) Dagger() *dagger.Client

A client to the Dagger API hooked up directly with this engine client.

func (*Client) DialContext

func (c *Client) DialContext(ctx context.Context, _, _ string) (conn net.Conn, err error)

func (*Client) Do

func (c *Client) Do(
	ctx context.Context,
	query string,
	opName string,
	variables map[string]any,
	data any,
) (rerr error)

func (*Client) ExportLogs

func (c *Client) ExportLogs(ctx context.Context, logs []sdklog.Record) error

ExportLogs is ExportSpans for log records.

func (*Client) ExportMetrics

ExportMetrics is ExportSpans for metrics.

func (*Client) ExportSpans

func (c *Client) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans posts spans this client's process emitted to the engine's store for the client. Only call it when IngestsTelemetry is true.

func (*Client) HostPolicyViolation

func (c *Client) HostPolicyViolation() error

HostPolicyViolation returns the first host request that the host policy refused, or nil. A refusal fails the session: Close returns it.

func (*Client) IngestsTelemetry

func (c *Client) IngestsTelemetry() bool

IngestsTelemetry reports whether the engine stores the telemetry this client posts about itself (ExportSpans, ExportLogs and ExportMetrics) in the client's telemetry store, keeping it out of the client's own telemetry streams (engine.ClientTelemetryIngestHeader). It is false for an older engine, and for a nested client, whose process already posts its telemetry to the engine through its exec's OTLP endpoint.

func (*Client) LLMConfigured

func (c *Client) LLMConfigured(ctx context.Context) (bool, error)

LLMConfigured reports whether the effective configuration has a provider credential or a local endpoint, including configuration inherited from the session's main client. It does not retrieve or validate credential values.

func (*Client) LLMModelConfig

func (c *Client) LLMModelConfig(ctx context.Context) (*engine.LLMConfig, error)

LLMModelConfig returns effective defaults and model names for the model picker, including inherited providers. A provider's presence in the map means it is configured; credential fields and endpoint addresses are always omitted.

func (*Client) LogsPresence

func (c *Client) LogsPresence() bool

LogsPresence reports whether this client's log push omits display text (see Params.EngineLogsPresence): EngineLogs then sees presence records for it, and the frontend must read it with QueryLogs.

func (*Client) NumCPU added in v0.19.10

func (c *Client) NumCPU() int

NumCPU returns the number of CPUs available on the engine host.

func (*Client) PublishesTelemetryToCloud

func (c *Client) PublishesTelemetryToCloud() bool

PublishesTelemetryToCloud reports whether the engine publishes the session's telemetry to Dagger Cloud on this client's behalf: the client asked it to (Params.EngineCloudTelemetry), and the engine confirmed.

func (*Client) QueryLogs

func (c *Client) QueryLogs(ctx context.Context, q archive.LogQuery, cursor int64, consume func(int64, *collogspb.ExportLogsServiceRequest) error) (int64, error)

QueryLogs reads display text for the spans q names from this client's own store, after cursor (a log row ID; 0 reads from the start). consume receives each batch with the cursor to resume after it; a batch may be empty, and may hold rows beyond the selection, which the caller routes as the frontend does. A one-shot query returns at the store's end as of the request; a follow returns when ctx ends (with ctx's error) or when the session's telemetry drains (nil). The returned cursor is the last one consumed, for resuming after an error.

func (*Client) SearchLogs

func (c *Client) SearchLogs(ctx context.Context, search archive.LogSearch) (archive.LogSearchResult, error)

SearchLogs searches display text in this client's own store.

func (*Client) ServeHTTP

func (c *Client) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Client) SessionLost

func (c *Client) SessionLost() error

SessionLost returns the cause recorded when the engine closed this client's session, or nil while the session is live.

func (*Client) SupportsTelemetryFeature

func (c *Client) SupportsTelemetryFeature(feature string) bool

SupportsTelemetryFeature reports whether the engine named a live telemetry feature (enginetel.LiveFeature*) on this client's trace subscription. It is false for an older engine, or a client without a trace subscription.

func (*Client) TelemetryBarrier

func (c *Client) TelemetryBarrier(ctx context.Context) error

TelemetryBarrier waits until the trace and log subscriptions have delivered everything the engine stored for this client up to now: the engine flushes the session's telemetry and reports its store's high-water marks, which the subscriptions then reach, and EngineTrace and EngineLogs are flushed (when they can be) so it is through their processors too. A frontend reading display text on demand passes it at exit, so the spans of work that just ended are there when it chooses what its final render reads, and the store still serves the reads. It needs enginetel.LiveFeatureFlush; an older engine answers ErrTelemetryBarrierUnsupported, and WaitTelemetryIdle remains.

func (*Client) UpdateLLMConfig

func (c *Client) UpdateLLMConfig(ctx context.Context, cfg *engine.LLMConfig) error

UpdateLLMConfig replaces this client's live routing configuration. Nil clears it. Bootstrap metadata stays unchanged, so concurrent requests and nested clients can continue using their authenticated session without reconnecting. Credentials must be secret URIs served by this client's attachables.

func (*Client) WaitTelemetryIdle

func (c *Client) WaitTelemetryIdle(ctx context.Context, quiet time.Duration)

WaitTelemetryIdle waits until the trace and log subscriptions have delivered nothing for quiet, or ctx ends. The engine batches what it records and the subscriptions poll for it, so a span (or presence) for work that just ended reaches EngineTrace/EngineLogs a little later. A frontend reading display text on demand waits for them at exit, before choosing what its final render reads, while the session can still serve the reads.

type DirectConn added in v0.8.8

type DirectConn func(*http.Request) (*http.Response, error)

func EngineConn added in v0.8.8

func EngineConn(engineClient *Client) DirectConn

func (DirectConn) Close added in v0.8.8

func (f DirectConn) Close() error

func (DirectConn) Do added in v0.8.8

func (f DirectConn) Do(r *http.Request) (*http.Response, error)

func (DirectConn) Host added in v0.8.8

func (f DirectConn) Host() string

type EngineToEngineParams added in v0.19.7

type EngineToEngineParams struct {
	Params

	// The caller's session grpc conn, which will be proxied back to
	CallerSessionConn *grpc.ClientConn

	// important we forward the original client's stable id so that filesync
	// caching can work as expected
	StableClientID string

	Labels enginetel.Labels
}

type FilesyncSource added in v0.11.5

type FilesyncSource Filesyncer

func (FilesyncSource) DiffCopy added in v0.11.5

func (FilesyncSource) FindUp

FindUp looks for each requested name in the start directory and then in each parent up to the root, answering in one call what would otherwise take one stat per name and level. A name found is reported with the absolute path of its directory, the same path a stat of it returns.

func (FilesyncSource) Register added in v0.11.5

func (s FilesyncSource) Register(server *grpc.Server)

func (FilesyncSource) TarStream added in v0.11.5

type FilesyncSourceProxy added in v0.19.7

type FilesyncSourceProxy struct {
	Client filesync.FileSyncClient
}

func (FilesyncSourceProxy) DiffCopy added in v0.19.7

func (FilesyncSourceProxy) FindUp

func (FilesyncSourceProxy) Register added in v0.19.7

func (s FilesyncSourceProxy) Register(server *grpc.Server)

func (FilesyncSourceProxy) TarStream added in v0.19.7

type FilesyncTarget added in v0.11.5

type FilesyncTarget Filesyncer

func (FilesyncTarget) DiffCopy added in v0.11.5

func (t FilesyncTarget) DiffCopy(stream filesync.FileSend_DiffCopyServer) (rerr error)

func (FilesyncTarget) Register added in v0.11.5

func (t FilesyncTarget) Register(server *grpc.Server)

type FilesyncTargetProxy added in v0.19.7

type FilesyncTargetProxy struct {
	Client filesync.FileSendClient
}

func (FilesyncTargetProxy) DiffCopy added in v0.19.7

func (FilesyncTargetProxy) Register added in v0.19.7

func (s FilesyncTargetProxy) Register(server *grpc.Server)

type Filesyncer added in v0.11.5

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

func NewFilesyncer added in v0.11.5

func NewFilesyncer() (Filesyncer, error)

func (Filesyncer) AsSource added in v0.11.5

func (f Filesyncer) AsSource() FilesyncSource

func (Filesyncer) AsTarget added in v0.11.5

func (f Filesyncer) AsTarget() FilesyncTarget

type HostPolicy

type HostPolicy struct {
	// Version must be 1.
	Version int `toml:"version"`
	// Reason names who set the policy. Refusal messages include it.
	Reason string `toml:"reason"`

	Secrets HostPolicySecrets `toml:"secrets"`
	Files   HostPolicyFiles   `toml:"files"`
	Git     HostPolicyGit     `toml:"git"`

	// RegistryAuth allows registry credentials from the host's Docker
	// configuration.
	RegistryAuth bool `toml:"registry_auth"`
}

HostPolicy limits what a client does on its host when the engine asks it to. A client without a policy serves every host request. A client with a policy serves only what the policy allows:

  • secrets from the listed provider schemes,
  • reads of files and directories under the listed absolute paths,
  • Git credentials and configuration for remote repositories,
  • registry credentials.

The client does not serve anything else: file writes, host sockets and network, host port tunnels, local Git repositories, terminals, prompts, standard input and output, and image loading. The client does not register the services that the engine may probe, so the engine sees a client without them. Outside the read paths, the host looks empty: a stat finds nothing, except the directories that contain a read path. The client refuses requests for secrets, file contents, Git configuration, sockets and tunnels that the policy does not allow. A refusal fails the session: Close returns the first refusal, also when the caller handled the error of the request.

The client checks a read path and then opens it, so nothing untrusted must be able to change the read paths while a session runs.

func LoadHostPolicy

func LoadHostPolicy() (*HostPolicy, error)

LoadHostPolicy reads the [host_policy] table of the user config file (userconfig.Path). It returns nil when the file or the table does not exist. See ParseHostPolicy.

func ParseHostPolicy

func ParseHostPolicy(data []byte) (*HostPolicy, error)

ParseHostPolicy parses the [host_policy] table of a user config file. It returns nil when the table does not exist.

Other settings of the file are read leniently, but a policy fails closed. A file that does not parse and contains "host_policy", unknown fields, an unsupported version, unknown secret providers and relative paths are errors, so that a client never runs with a policy that it does not fully understand.

func (*HostPolicy) AllowsRead

func (p *HostPolicy) AllowsRead(path string) bool

AllowsRead reports whether an absolute path is under a read path of the policy, with symlinks resolved.

type HostPolicyFiles

type HostPolicyFiles struct {
	// Read lists absolute paths. The client serves reads of these paths and
	// of everything under them, after it resolves symlinks.
	Read []string `toml:"read"`
}

type HostPolicyGit

type HostPolicyGit struct {
	// Credentials allows Git credentials and the host's Git configuration for
	// remote repositories.
	Credentials bool `toml:"credentials"`
}

type HostPolicySecrets

type HostPolicySecrets struct {
	// Providers lists the secret provider schemes that the client resolves,
	// such as "op" or "vault". A provider runs on the host with the client's
	// access, and the read paths do not limit it: "env", "file", "cmd" and
	// "llmconfig" give access to the host environment, files and commands.
	Providers []string `toml:"providers"`
}

type Params

type Params struct {
	// The id to connect to the API server with. If blank, will be set to a
	// new random value.
	ID string

	// The id of the session to connect to, or if blank a new one should be started.
	SessionID string

	Version string

	SecretToken string

	RunnerHost string // host of dagger engine runner serving buildkit apis

	CloudURLCallback func(context.Context, string, string, bool)

	EngineTrace   sdktrace.SpanExporter
	EngineLogs    sdklog.Exporter
	EngineMetrics []sdkmetric.Exporter

	// EngineTraceWithoutCloud, EngineLogsWithoutCloud and
	// EngineMetricsWithoutCloud replace EngineTrace, EngineLogs and
	// EngineMetrics when the engine publishes the session's telemetry to Dagger
	// Cloud itself (EngineCloudTelemetry): the same destinations, without this
	// client's Cloud exporters.
	EngineTraceWithoutCloud   sdktrace.SpanExporter
	EngineLogsWithoutCloud    sdklog.Exporter
	EngineMetricsWithoutCloud []sdkmetric.Exporter

	// Log level (0 = INFO)
	LogLevel slog.Level

	Interactive        bool
	InteractiveCommand []string

	WithTerminal terminal.WithTerminalFunc

	AllowedLLMModules []string

	PromptHandler prompt.PromptHandler
	// CLI helper for client-local SSH key unlocking; not a general command hook.
	SSHAskpassExecutable string

	Stdin  io.Reader
	Stdout io.Writer

	ImageLoaderBackend imageload.Backend

	Module       string
	ExtraModules []engine.ExtraModule
	Function     string
	ExecCmd      []string
	// GitRemote and WorkspacePath tell Dagger Cloud the repository and the
	// workspace in it that the client runs in, when it requests an engine.
	GitRemote     string
	WorkspacePath string

	EagerRuntime bool

	LoadWorkspaceModules bool
	SingleQuery          bool

	SkipWorkspaceModules bool

	SuppressCompatWorkspaceWarning bool

	// Workspace explicitly declares workspace binding for this client.
	Workspace *string

	// WorkspaceEnv explicitly selects the workspace environment overlay for this client.
	WorkspaceEnv *string

	// UserConfigPath is the caller-host path to the user-level Dagger config
	// file, read by the engine for user-level workspace overrides.
	UserConfigPath string

	// LLMConfig is this client's LLM routing configuration; credentials in
	// it are secret URIs the engine resolves against this client.
	LLMConfig *engine.LLMConfig

	// WorkspaceModuleScope hints at the workspace module this client's first
	// schema introspection targets (the leading CLI command token, unresolved).
	WorkspaceModuleScope string

	CloudAuth           *auth.Cloud
	EnableCloudScaleOut bool

	// EngineCloudTelemetry asks the engine to publish the session's telemetry
	// to Dagger Cloud itself, with CloudAuth, at CloudURL, instead of this
	// client forwarding it. The engine refreshes an expiring OAuth token from
	// CloudCredentialsPath on this client's host and writes it back there.
	EngineCloudTelemetry bool
	CloudURL             string
	CloudCredentialsPath string

	// EngineLogsPresence asks the engine's log push to omit display text
	// (GET /v1/logs?display=presence): EngineLogs then receives every other
	// record plus one body-less presence record per span with logs, and the
	// frontend reads display text on demand with QueryLogs. Set it only when
	// nothing receiving EngineLogs needs display text but a frontend that
	// reads it on demand. The client still asks only an engine that serves
	// the mode and stores the client's own telemetry (IngestsTelemetry: the
	// frontend reads the client's own display text from the store too), and,
	// with EngineCloudTelemetry, only one that confirmed it publishes to
	// Cloud itself; LogsPresence reports the outcome.
	EngineLogsPresence bool

	// Profile enables engine wall-clock profiling (wcprof) for this session.
	Profile bool
	// ProfileEBPF names the eBPF programs to profile the session with.
	ProfileEBPF []string

	// HostPolicy limits what this client does on its host for the engine.
	// Nil serves every host request. See HostPolicy.
	HostPolicy *HostPolicy
}

type SessionAttachable added in v0.21.0

type SessionAttachable interface {
	Register(*grpc.Server)
}

type SessionAttachablesServer added in v0.21.0

type SessionAttachablesServer struct {
	*grpc.Server
	MethodURLs  []string
	Conn        net.Conn
	Attachables []SessionAttachable
	// contains filtered or unexported fields
}

func ConnectSessionAttachables added in v0.21.0

func ConnectSessionAttachables(
	ctx context.Context,
	conn net.Conn,
	headers http.Header,
	attachables ...SessionAttachable,
) (_ *SessionAttachablesServer, rerr error)

func NewSessionAttachablesServer added in v0.21.0

func NewSessionAttachablesServer(ctx context.Context, conn net.Conn, attachables ...SessionAttachable) *SessionAttachablesServer

func (*SessionAttachablesServer) Run added in v0.21.0

type SocketProvider

type SocketProvider struct {
	EnableHostNetworkAccess bool
}

func (SocketProvider) CheckAgent

func (SocketProvider) ForwardAgent

func (p SocketProvider) ForwardAgent(stream sshforward.SSH_ForwardAgentServer) error

func (SocketProvider) Register

func (p SocketProvider) Register(server *grpc.Server)

type SocketSessionProxy added in v0.19.7

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

SocketSessionProxy is a proxy of a the grpc session attachable (as opposed to the above socketProxy which proxies to arbitrary net.Conns). It's used for engine scale-out.

func NewSocketSessionProxy added in v0.19.7

func NewSocketSessionProxy(client sshforward.SSHClient) *SocketSessionProxy

func (*SocketSessionProxy) CheckAgent added in v0.19.7

func (*SocketSessionProxy) ForwardAgent added in v0.19.7

func (*SocketSessionProxy) Register added in v0.19.7

func (p *SocketSessionProxy) Register(server *grpc.Server)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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