Documentation
¶
Index ¶
- Constants
- Variables
- func GetHostStableID(lg *slog.Logger) string
- func NestedSession() bool
- func Tracer(ctx context.Context) trace.Tracer
- type AuthProxy
- func (p AuthProxy) Credentials(ctx context.Context, req *auth.CredentialsRequest) (*auth.CredentialsResponse, error)
- func (p AuthProxy) FetchToken(ctx context.Context, req *auth.FetchTokenRequest) (*auth.FetchTokenResponse, error)
- func (p AuthProxy) GetTokenAuthority(ctx context.Context, req *auth.GetTokenAuthorityRequest) (*auth.GetTokenAuthorityResponse, error)
- func (p AuthProxy) Register(server *grpc.Server)
- func (p AuthProxy) VerifyTokenAuthority(ctx context.Context, req *auth.VerifyTokenAuthorityRequest) (*auth.VerifyTokenAuthorityResponse, error)
- type Client
- func (c *Client) AppendHTTPRequestHeaders(headers http.Header) http.Header
- func (c *Client) Close() error
- func (c *Client) CloseWithContext(ctx context.Context) (rerr error)
- func (c *Client) Dagger() *dagger.Client
- func (c *Client) DialContext(ctx context.Context, _, _ string) (conn net.Conn, err error)
- func (c *Client) Do(ctx context.Context, query string, opName string, variables map[string]any, ...) (rerr error)
- func (c *Client) ExportLogs(ctx context.Context, logs []sdklog.Record) error
- func (c *Client) ExportMetrics(ctx context.Context, req *colmetricspb.ExportMetricsServiceRequest) error
- func (c *Client) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error
- func (c *Client) HostPolicyViolation() error
- func (c *Client) IngestsTelemetry() bool
- func (c *Client) LLMConfigured(ctx context.Context) (bool, error)
- func (c *Client) LLMModelConfig(ctx context.Context) (*engine.LLMConfig, error)
- func (c *Client) LogsPresence() bool
- func (c *Client) NumCPU() int
- func (c *Client) PublishesTelemetryToCloud() bool
- func (c *Client) QueryLogs(ctx context.Context, q archive.LogQuery, cursor int64, ...) (int64, error)
- func (c *Client) SearchLogs(ctx context.Context, search archive.LogSearch) (archive.LogSearchResult, error)
- func (c *Client) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (c *Client) SessionLost() error
- func (c *Client) SupportsTelemetryFeature(feature string) bool
- func (c *Client) TelemetryBarrier(ctx context.Context) error
- func (c *Client) UpdateLLMConfig(ctx context.Context, cfg *engine.LLMConfig) error
- func (c *Client) WaitTelemetryIdle(ctx context.Context, quiet time.Duration)
- type DirectConn
- type EngineToEngineParams
- type FilesyncSource
- func (s FilesyncSource) DiffCopy(stream filesync.FileSync_DiffCopyServer) error
- func (s FilesyncSource) FindUp(ctx context.Context, req *filesync.FindUpRequest) (*filesync.FindUpResponse, error)
- func (s FilesyncSource) Register(server *grpc.Server)
- func (s FilesyncSource) TarStream(stream filesync.FileSync_TarStreamServer) error
- type FilesyncSourceProxy
- func (s FilesyncSourceProxy) DiffCopy(stream filesync.FileSync_DiffCopyServer) error
- func (s FilesyncSourceProxy) FindUp(ctx context.Context, req *filesync.FindUpRequest) (*filesync.FindUpResponse, error)
- func (s FilesyncSourceProxy) Register(server *grpc.Server)
- func (s FilesyncSourceProxy) TarStream(stream filesync.FileSync_TarStreamServer) error
- type FilesyncTarget
- type FilesyncTargetProxy
- type Filesyncer
- type HostPolicy
- type HostPolicyFiles
- type HostPolicyGit
- type HostPolicySecrets
- type Params
- type SessionAttachable
- type SessionAttachablesServer
- type SocketProvider
- type SocketSessionProxy
Constants ¶
const InstrumentationLibrary = "dagger.io/engine.client"
const StableIDFileName = "stable_client_id"
Variables ¶
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.
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
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.
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 (p AuthProxy) Credentials(ctx context.Context, req *auth.CredentialsRequest) (*auth.CredentialsResponse, error)
func (AuthProxy) FetchToken ¶ added in v0.19.7
func (p AuthProxy) FetchToken(ctx context.Context, req *auth.FetchTokenRequest) (*auth.FetchTokenResponse, error)
func (AuthProxy) GetTokenAuthority ¶ added in v0.19.7
func (p AuthProxy) GetTokenAuthority(ctx context.Context, req *auth.GetTokenAuthorityRequest) (*auth.GetTokenAuthorityResponse, error)
func (AuthProxy) VerifyTokenAuthority ¶ added in v0.19.7
func (p AuthProxy) VerifyTokenAuthority(ctx context.Context, req *auth.VerifyTokenAuthorityRequest) (*auth.VerifyTokenAuthorityResponse, error)
type Client ¶
type Client struct {
Params
// contains filtered or unexported fields
}
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 (*Client) CloseWithContext ¶
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
A client to the Dagger API hooked up directly with this engine client.
func (*Client) DialContext ¶
func (*Client) ExportLogs ¶
ExportLogs is ExportSpans for log records.
func (*Client) ExportMetrics ¶
func (c *Client) ExportMetrics(ctx context.Context, req *colmetricspb.ExportMetricsServiceRequest) error
ExportMetrics is ExportSpans for metrics.
func (*Client) ExportSpans ¶
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 ¶
HostPolicyViolation returns the first host request that the host policy refused, or nil. A refusal fails the session: Close returns it.
func (*Client) IngestsTelemetry ¶
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 ¶
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 ¶
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 ¶
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
NumCPU returns the number of CPUs available on the engine host.
func (*Client) PublishesTelemetryToCloud ¶
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) SessionLost ¶
SessionLost returns the cause recorded when the engine closed this client's session, or nil while the session is live.
func (*Client) SupportsTelemetryFeature ¶
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 ¶
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 ¶
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 ¶
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
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) Host ¶ added in v0.8.8
func (f DirectConn) Host() string
type EngineToEngineParams ¶ added in v0.19.7
type FilesyncSource ¶ added in v0.11.5
type FilesyncSource Filesyncer
func (FilesyncSource) DiffCopy ¶ added in v0.11.5
func (s FilesyncSource) DiffCopy(stream filesync.FileSync_DiffCopyServer) error
func (FilesyncSource) FindUp ¶
func (s FilesyncSource) FindUp(ctx context.Context, req *filesync.FindUpRequest) (*filesync.FindUpResponse, error)
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
func (s FilesyncSource) TarStream(stream filesync.FileSync_TarStreamServer) error
type FilesyncSourceProxy ¶ added in v0.19.7
type FilesyncSourceProxy struct {
Client filesync.FileSyncClient
}
func (FilesyncSourceProxy) DiffCopy ¶ added in v0.19.7
func (s FilesyncSourceProxy) DiffCopy(stream filesync.FileSync_DiffCopyServer) error
func (FilesyncSourceProxy) FindUp ¶
func (s FilesyncSourceProxy) FindUp(ctx context.Context, req *filesync.FindUpRequest) (*filesync.FindUpResponse, error)
func (FilesyncSourceProxy) Register ¶ added in v0.19.7
func (s FilesyncSourceProxy) Register(server *grpc.Server)
func (FilesyncSourceProxy) TarStream ¶ added in v0.19.7
func (s FilesyncSourceProxy) TarStream(stream filesync.FileSync_TarStreamServer) error
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 (s FilesyncTargetProxy) DiffCopy(stream filesync.FileSend_DiffCopyServer) error
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 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
func (srv *SessionAttachablesServer) Run(ctx context.Context)
type SocketProvider ¶
type SocketProvider struct {
EnableHostNetworkAccess bool
}
func (SocketProvider) CheckAgent ¶
func (p SocketProvider) CheckAgent(ctx context.Context, req *sshforward.CheckAgentRequest) (*sshforward.CheckAgentResponse, error)
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 (p *SocketSessionProxy) CheckAgent(ctx context.Context, req *sshforward.CheckAgentRequest) (*sshforward.CheckAgentResponse, error)
func (*SocketSessionProxy) ForwardAgent ¶ added in v0.19.7
func (p *SocketSessionProxy) ForwardAgent(stream sshforward.SSH_ForwardAgentServer) error
func (*SocketSessionProxy) Register ¶ added in v0.19.7
func (p *SocketSessionProxy) Register(server *grpc.Server)