server

package
v1.0.0-beta.24 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: Apache-2.0 Imports: 165 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// UsageScopeEngineProcess is the engine process itself: its CPU, page
	// faults, and Go runtime counters.
	UsageScopeEngineProcess = "engine_process"
	// UsageScopeEngineChildren is the engine's child processes (runc, and
	// the processes it runs), counted only once the engine reaped them: their
	// CPU and page faults.
	UsageScopeEngineChildren = "engine_children"
	// UsageScopeEngineCgroup is the engine process's cgroup (as the engine's
	// cgroup metrics find it) and everything in it: its CPU, and the bytes it
	// read from and wrote to block devices (left out when io.stat can't be
	// read).
	UsageScopeEngineCgroup = "engine_cgroup"
	// UsageScopeMachine is the whole machine the engine runs on, from
	// /proc/stat, which a container shares with its host: user (with nice),
	// system (with interrupts), iowait, steal and idle, summed over its cores.
	UsageScopeMachine = "machine"
	// UsageScopeMachineSample is the machine, as UsageScopeMachine, over one
	// stretch of the phase: read every machineSampleInterval while it runs,
	// each reading covers the time since the phase's previous one (or its
	// start), and its time is the stretch's end. The last stretch ends with
	// the phase.
	UsageScopeMachineSample = "machine_sample"
	// UsageScopeEngineCgroupSample is the engine's cgroup's memory at one
	// moment of the phase, read every machineSampleInterval while it runs:
	// anonymous memory, file pages, and the part of both in transparent huge
	// pages.
	UsageScopeEngineCgroupSample = "engine_cgroup_sample"
	// UsageScopeGoRuntimeSample is the engine process's Go garbage collector
	// over one stretch of the phase, read every machineSampleInterval while
	// it runs: the CPU its GC took, by class, since the previous reading (the
	// runtime's estimates, which it updates at GC events, so a stretch can
	// carry an earlier one's CPU); and at the reading's time, the live heap as
	// of the last GC, the heap goal, the scannable heap and globals, and the
	// stack the last GC scanned (see wcprof.Usage).
	UsageScopeGoRuntimeSample = "go_runtime_sample"
	// UsageScopeEngineProcessSample is the engine process's CPU over one
	// stretch of the phase, read every machineSampleInterval while it runs:
	// user and system time since the previous reading (or the phase's
	// start). A window of the phase is the sum of the readings whose stretch
	// ends inside it, accurate to within one stretch at each end.
	UsageScopeEngineProcessSample = "engine_process_sample"
)

Usage scopes of a phase: the resources the engine used while it ran. They are activity during the phase, not resources the phase owned: phases that overlap (two sessions) see each other's work.

View Source 
const InstrumentationLibrary = "dagger.io/engine.server"
View Source 
const PhaseSession = "session"

PhaseSession is a session's life, from its initialization to the end of its removal.

Variables

View Source 
var ErrRemoteCacheAdapterClosed = errors.New("remote cache adapter closed")

Functions

func DetectDefaultGCCap added in v0.13.7 

func DetectDefaultGCCap(dstat disk.DiskStat) config.GCSpace

func FormatPlatforms added in v0.11.8 

func FormatPlatforms(p []ocispecs.Platform) []string

Types

type Capture 

type Capture struct {
	At time.Time `json:"at"`
	// Session is the session that ran past the threshold, and Sessions every
	// watched session running then, with how long each had run.
	Session  string           `json:"session"`
	Sessions []CaptureSession `json:"sessions"`
	// GoroutinesBefore and GoroutinesAfter are every goroutine's stack, as
	// /debug/pprof/goroutine?debug=2 writes them, before and after the CPU
	// profile.
	GoroutinesBefore string `json:"goroutines_before"`
	GoroutinesAfter  string `json:"goroutines_after"`
	// CPUProfile is a pprof CPU profile over captureCPUDuration. When Go's CPU
	// profiler was already in use, it's empty and CPUProfileSkipped says why.
	CPUProfile        []byte `json:"cpu_profile,omitempty"`
	CPUProfileSkipped string `json:"cpu_profile_skipped,omitempty"`
}

Capture is what the engine was doing when Session ran past the watch's threshold.

type CaptureSession 

type CaptureSession struct {
	ID        string `json:"id"`
	RunningMS int64  `json:"running_ms"`
}

CaptureSession is a session running at a capture.

type ClientInitOpts added in v0.11.8 

type ClientInitOpts struct {
	*engine.ClientMetadata

	// NestedTransport proves that a nested proxy was explicitly registered
	// before serving. It is nil only for intentional root transports.
	NestedTransport *engine.NestedClientTransport

	// ParentClientID names the client that delegated reachability to this nested
	// client. It is required for nested clients and forbidden for explicit roots.
	ParentClientID string

	// RootClient explicitly marks a session/root transport. Empty parent IDs do
	// not implicitly create roots.
	RootClient bool

	// BootstrapOnly allows registration-adjacent attachable, /init, and shutdown
	// requests to reconcile metadata without constructing the executable runtime.
	// The first non-bootstrap request seals metadata before initialization.
	BootstrapOnly bool

	// InertAttachables marks an in-engine SDK client that must not access any
	// caller-host session attachables.
	InertAttachables bool

	// If set, host-backed services for this client may proxy through this
	// ancestor when this client has no session attachables of its own.
	HostServiceProxyClientID string

	// If the client is running from a function in a module, this is that module.
	ModuleContext dagql.ObjectResult[*core.Module]

	// If the client is running from a function in a module, this is that function call.
	FunctionCall *core.FunctionCall
	// contains filtered or unexported fields
}

type ClientLifecycleDebugSnapshot 

type ClientLifecycleDebugSnapshot struct {
	ClientID         string                     `json:"client_id"`
	ParentIDs        []string                   `json:"parent_ids,omitempty"`
	RecordState      string                     `json:"record_state"`
	RuntimeState     string                     `json:"runtime_state"`
	MetadataSealed   bool                       `json:"metadata_sealed"`
	ActiveRequests   int                        `json:"active_requests"`
	ClosedAt         *time.Time                 `json:"closed_at,omitempty"`
	QuiescentAt      *time.Time                 `json:"quiescent_at,omitempty"`
	ShutdownAt       *time.Time                 `json:"shutdown_at,omitempty"`
	RetentionReasons []LifecycleRetentionReason `json:"retention_reasons,omitempty"`
	// Telemetry reports runtime-owned metric resources. Trace/log topology lives
	// on the owning session snapshot.
	Telemetry LifecycleTelemetryCounts `json:"telemetry"`
}

type EngineEventExport 

type EngineEventExport interface {
	Logger() log.Logger
	Shutdown(context.Context) error
}

EngineEventExport is where the engine's cache events go: a logger that delivers every record it accepts, and a bounded shutdown that flushes them.

type LifecycleDebugSnapshot 

type LifecycleDebugSnapshot struct {
	GeneratedAt         time.Time                       `json:"generated_at"`
	Records             int                             `json:"records"`
	Runtimes            int                             `json:"runtimes"`
	ClosedRuntimes      int                             `json:"closed_runtimes"`
	OldestClosedRuntime *time.Time                      `json:"oldest_closed_runtime,omitempty"`
	ActiveRequests      int                             `json:"active_requests"`
	LeaseCounts         []LifecycleRetentionReason      `json:"lease_counts,omitempty"`
	OpenClientDBs       int                             `json:"open_client_dbs"`
	OpenClientDBStreams int                             `json:"open_client_db_streams"`
	OpenClientDBRefs    int                             `json:"open_client_db_refs"`
	Providers           LifecycleTelemetryCounts        `json:"providers"`
	Sessions            []SessionLifecycleDebugSnapshot `json:"sessions"`
}

LifecycleDebugSnapshot is a point-in-time view of session-long client records and the execution runtimes that remain published by typed leases.

type LifecycleRetentionReason 

type LifecycleRetentionReason struct {
	Kind    string `json:"kind"`
	OwnerID string `json:"owner_id,omitempty"`
	Count   int    `json:"count,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

type LifecycleTelemetryCounts 

type LifecycleTelemetryCounts struct {
	TracerProviders          int `json:"tracer_providers"`
	LoggerProviders          int `json:"logger_providers"`
	MeterProviders           int `json:"meter_providers"`
	ConfiguredSpanProcessors int `json:"configured_span_processors"`
	ConfiguredLogProcessors  int `json:"configured_log_processors"`
	ConfiguredMetricReaders  int `json:"configured_metric_readers"`
	ConfiguredSpanQueueSlots int `json:"configured_span_queue_slots"`
	ConfiguredLogQueueSlots  int `json:"configured_log_queue_slots"`
	// The OTel batch processors do not expose queue occupancy. Keep this
	// explicit so configured capacity is never mistaken for measured backlog.
	QueueOccupancyMeasured bool `json:"queue_occupancy_measured"`
}

LifecycleTelemetryCounts reports configured provider, processor, reader, and queue cardinality. Trace/log resources are session-owned; metric resources belong to live client runtimes. Slots count bounded capacity; lossless unbounded queues contribute no finite slot count. This is configured fact, never measured occupancy.

type NewServerOpts added in v0.11.8 

type NewServerOpts struct {
	Name           string
	Config         *config.Config
	BuildkitConfig *bkconfig.Config
	// RemoteCacheIntegration is nil, and remote cache renewal off, by default.
	RemoteCacheIntegration *RemoteCacheIntegrationConfig
	// EngineInstanceID names this engine process. NewServer creates a random
	// one when it is empty.
	EngineInstanceID string
	// EngineEvents, when set, receives the engine's cache events as OTel log
	// records through its logger.
	EngineEvents EngineEventExport
	// WorkloadExport is engine-owned and independent of session Cloud export.
	WorkloadExport *enginetel.WorkloadExport
}

type PubSub added in v0.12.5 

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

func NewPubSub added in v0.12.5 

func NewPubSub(srv *Server) *PubSub

func (*PubSub) Logs added in v0.12.5 

func (ps *PubSub) Logs(clientID string) sdklog.Exporter

func (*PubSub) LogsHandler added in v0.12.5 

func (ps *PubSub) LogsHandler(rw http.ResponseWriter, r *http.Request)

func (*PubSub) LogsSubscribeHandler added in v0.12.5 

func (ps *PubSub) LogsSubscribeHandler(w http.ResponseWriter, r *http.Request, record *clientRecord) error

func (*PubSub) Metrics added in v0.13.6 

func (ps *PubSub) Metrics(clientID string) sdkmetric.Exporter

func (*PubSub) MetricsHandler added in v0.12.5 

func (ps *PubSub) MetricsHandler(rw http.ResponseWriter, r *http.Request)

func (*PubSub) MetricsSubscribeHandler added in v0.13.6 

func (ps *PubSub) MetricsSubscribeHandler(w http.ResponseWriter, r *http.Request, record *clientRecord) error

func (*PubSub) ServeHTTP added in v0.12.5 

func (ps *PubSub) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*PubSub) TracesHandler added in v0.12.5 

func (ps *PubSub) TracesHandler(rw http.ResponseWriter, r *http.Request)

func (*PubSub) TracesSubscribeHandler added in v0.12.5 

func (ps *PubSub) TracesSubscribeHandler(w http.ResponseWriter, r *http.Request, record *clientRecord) error

type RemoteCacheAdapter 

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

RemoteCacheAdapter forwards control calls to its cache and renewal calls to the one bridge attached for it, never to a later attachment.

func (*RemoteCacheAdapter) CacheIdentity 

func (a *RemoteCacheAdapter) CacheIdentity() (string, uint64)

CacheIdentity returns the engine cache's identity and generation, which the remote cache integration says in hello.

func (*RemoteCacheAdapter) Export 

func (a *RemoteCacheAdapter) Export(ctx context.Context, req protocol.Export, consume func(context.Context, remotecache.Export) error) (rerr error)

Export holds the requested entries by number and captures the held roots with the selected outputs, leaving out those outside the captured closure. A missing root is skipped as gone. When the capture fails, other than by the request's own cancellation or the cache closing, each root is probed alone: one whose probe is busy is skipped as busy, one whose probe fails otherwise is skipped as refused, each with its error as the message, and the others are captured together; if that capture is busy, they are all busy with its error, and if it fails otherwise, so does the request. consume is called once, with the bundle while its chains stay open, or with no bundle when no root survived.

func (*RemoteCacheAdapter) Merge 

func (a *RemoteCacheAdapter) Merge(ctx context.Context, req protocol.Merge) (protocol.Merged, error)

Merge merges a bundle of the Cloud's values into the cache and answers with what the commit left. A merge that committed is answered even when a release after the commit failed: the cache changed, and the service must learn how. The release's error is logged instead.

func (*RemoteCacheAdapter) OfferParts 

func (a *RemoteCacheAdapter) OfferParts(ctx context.Context, req protocol.Offer) (protocol.Offered, error)

OfferParts places the Cloud's parts on the cache's entries by number. Each item's entry is held while its parts are offered; a missing one is gone. An item's replacement count and dependencies are those its outcomes were decided at.

func (*RemoteCacheAdapter) ReplyRenewal 

func (a *RemoteCacheAdapter) ReplyRenewal(reply dagql.RenewalReply) dagql.RenewalReplyDisposition

func (*RemoteCacheAdapter) Stop 

func (a *RemoteCacheAdapter) Stop(ctx context.Context) error

Stop closes the adapter and joins Run within ctx, the deadline engine shutdown already passes. It is idempotent and keeps the first result. A Run that ignores cancellation is reported, not terminated.

func (*RemoteCacheAdapter) TakeRenewalRequest 

func (a *RemoteCacheAdapter) TakeRenewalRequest(ctx context.Context) (*dagql.RenewalRequest, error)

type RemoteCacheIntegrationConfig 

type RemoteCacheIntegrationConfig struct {
	// Run is called once, after local cache initialization, under the server
	// lifetime context. It must return once that context is canceled, including
	// for delivered requests' Done signals, and must not hold a cache operation
	// while waiting for future requests.
	Run func(context.Context, *RemoteCacheAdapter) error
}

RemoteCacheIntegrationConfig injects an in-process remote cache integration. Ordinary engines leave it nil. This is not a schema field, listener or service; Run owns the integration's channel consumer and transport.

type Server added in v0.11.8 

type Server struct {
	controlapi.UnimplementedControlServer
	// contains filtered or unexported fields
}

func NewServer added in v0.11.8 

func NewServer(ctx context.Context, opts *NewServerOpts) (*Server, error)

func (*Server) Agents 

func (srv *Server) Agents(ctx context.Context) (*core.AgentRuntimes, error)

The agent runtimes for the current client's session

func (*Server) Auth added in v0.12.0 

func (srv *Server) Auth(ctx context.Context) (*auth.RegistryAuthProvider, error)

The auth provider for the current client

func (*Server) AuthorizeGitPush 

func (srv *Server) AuthorizeGitPush(ctx context.Context, remote, ref string, force, resolveURL bool) (*core.GitPushAuthorization, error)

func (*Server) AuthorizeGitRead 

func (srv *Server) AuthorizeGitRead(ctx context.Context, remote string) (*engine.ClientMetadata, error)

AuthorizeGitRead returns the client whose Git credentials may authenticate a read of remote, an address an agent's model supplied as a tool argument.

The owner is the trusted caller before the first module boundary, as for push. When the caller is that owner itself (the user's own conversation), its credentials apply as they would to any of its reads. When a module drives the agent (e.g. a worker spawned by a module), the module chose the conversation, so the owner approves each remote for that module first; a grant lasts for the session, a denial only for that attempt. Otherwise any module could read whatever the user can, by prompting a model.

func (*Server) BeginGracefulStop added in v0.21.0 

func (srv *Server) BeginGracefulStop()

func (*Server) BuiltinOCIStore added in v0.21.0 

func (srv *Server) BuiltinOCIStore() content.Store

func (*Server) CacheAccessor added in v0.19.11 

func (srv *Server) CacheAccessor() bkcache.Accessor

func (*Server) CallPayloadSeenKeyStore 

func (srv *Server) CallPayloadSeenKeyStore(ctx context.Context) (dagql.CallPayloadSeenKeyStore, error)

CallPayloadSeenKeyStore returns the claim store for call-payload telemetry (core/dag_call_telemetry.go), scoped to the current client's delivery route — the client and its ancestors, exactly the DBs PubSub fans its telemetry out to — rather than the whole session. Claims are per (digest, target), so a client attaching later still receives every frame on its own first walk.

func (*Server) Captures 

func (srv *Server) Captures() []Capture

Captures returns the captures the engine kept, oldest first.

func (*Server) CleanMountNS added in v0.19.9 

func (srv *Server) CleanMountNS() *os.File

A mount namespace guaranteed to not have any mounts created by engine operations. Should be used when creating goroutines/processes that unshare a mount namespace, otherwise those unshared mnt namespaces may inherit mounts from engine operations and leak them.

func (*Server) ClientLifecycleDebugSnapshot 

func (srv *Server) ClientLifecycleDebugSnapshot() LifecycleDebugSnapshot

ClientLifecycleDebugSnapshot reports why current clients remain retained. It is lock-safe for use from the engine debug server while sessions initialize or tear down and does not acquire a session lifecycleMu.

func (*Server) ClientTelemetry added in v0.19.0 

func (srv *Server) ClientTelemetry(ctx context.Context, sessID, clientID string) (*clientdb.DB, error)

func (*Server) Clients added in v0.19.4 

func (srv *Server) Clients() []string

func (*Server) CloudEngineClient added in v0.19.7 

func (srv *Server) CloudEngineClient(
	ctx context.Context,
	module string,
	function string,
	execCmd []string,
) (*engineclient.Client, bool, error)

Return a cloud client whose session attachables proxy to the calling client.

func (*Server) ConnectedClients added in v0.18.11 

func (srv *Server) ConnectedClients() int

ConnectedClients returns the number of currently connected clients

func (*Server) CorruptDBReset added in v0.19.5 

func (srv *Server) CorruptDBReset() bool

func (*Server) CurrentClientModules 

func (srv *Server) CurrentClientModules(ctx context.Context) ([]core.WorkspaceClientModule, error)

Return the modules the current client served beside its workspace's own, with -m or through the API, sorted by name. A module served only for its types, such as a dependency of a main module, isn't listed by artifact discovery and isn't returned.

func (*Server) CurrentFunctionCall added in v0.11.8 

func (srv *Server) CurrentFunctionCall(ctx context.Context) (*core.FunctionCall, error)

If the current client is coming from a function, return the function call metadata

func (*Server) CurrentModule added in v0.11.8 

func (srv *Server) CurrentModule(ctx context.Context) (dagql.ObjectResult[*core.Module], error)

If the current client is coming from a function, return the module that function is from

func (*Server) CurrentServedDeps added in v0.11.8 

func (srv *Server) CurrentServedDeps(ctx context.Context) (*core.SchemaBuilder, error)

Return the modules being served to the current client

func (*Server) CurrentWorkspace added in v0.20.4 

func (srv *Server) CurrentWorkspace(ctx context.Context) (*core.Workspace, error)

CurrentWorkspace returns the cached workspace for the current client.

func (*Server) CurrentWorkspaceLock added in v0.21.0 

func (srv *Server) CurrentWorkspaceLock(ctx context.Context, requireWritable bool) (*workspace.Lock, bool, error)

func (*Server) DNS added in v0.18.5 

func (srv *Server) DNS() *oci.DNSConfig

The dns configuration for the engine as a whole

func (*Server) DagqlCacheEntries added in v0.20.0 

func (srv *Server) DagqlCacheEntries() int

func (*Server) DagqlCacheEntryStats added in v0.20.0 

func (srv *Server) DagqlCacheEntryStats() dagql.CacheEntryStats

func (*Server) DagqlCacheMetadataEstimatedBytes added in v0.21.9 

func (srv *Server) DagqlCacheMetadataEstimatedBytes() int64

func (*Server) DagqlDebugSnapshot added in v0.21.0 

func (srv *Server) DagqlDebugSnapshot() *dagql.EGraphDebugSnapshot

func (*Server) DefaultDeps added in v0.12.0 

func (srv *Server) DefaultDeps(ctx context.Context) (*core.SchemaBuilder, error)

The default deps of every user module (currently just core)

func (*Server) Engine added in v0.21.0 

func (srv *Server) Engine(ctx context.Context) (*engineutil.Client, error)

The session-owned engine utility gateway for the current executable scope.

func (*Server) EngineInstanceID 

func (srv *Server) EngineInstanceID() string

EngineInstanceID returns the random ID naming this engine process.

func (*Server) EngineLocalCacheEntries added in v0.12.0 

func (srv *Server) EngineLocalCacheEntries(ctx context.Context) (*core.EngineCacheEntrySet, error)

Return all the cache entries in the local cache. No support for filtering yet.

func (*Server) EngineLocalCachePolicy added in v0.13.7 

func (srv *Server) EngineLocalCachePolicy() *dagqlCachePrunePolicy

func (*Server) EngineName added in v0.19.3 

func (srv *Server) EngineName() string

func (*Server) EngineVolumeState 

func (srv *Server) EngineVolumeState() core.EngineVolumeState

func (*Server) EnsureWorkspaceModules 

func (srv *Server) EnsureWorkspaceModules(ctx context.Context, include []string, mode core.ModuleLoadMode) ([]core.ModuleLoadFailure, error)

EnsureWorkspaceModules loads the pending workspace modules a selector resolver (checks/generators/services) demands. Those fields validate against the core schema, so loading waits until resolution where include is native. In a best-effort mode, modules that fail to load are skipped with a warning instead of failing the operation, and their failure messages are returned for the caller to surface (see ensureModulesLoadedMode).

func (*Server) ExpectNestedExecAttachables 

func (srv *Server) ExpectNestedExecAttachables(sessionID, attachablesClientID string) (fail func(error), done func(), _ error)

ExpectNestedExecAttachables records that a nested exec's session helper will register attachablesClientID's attachables, starting alongside the exec's command. Queries then wait for them as long as the exec runs instead of a fixed timeout. fail reports that the helper will not register them, and done that the exec has ended. The exec's clients must be registered with fromExecHelper set, which keeps their waits failing at once after done.

func (*Server) FlushSessionTelemetry added in v0.20.4 

func (srv *Server) FlushSessionTelemetry(ctx context.Context) error

Provides access to the client's telemetry database.

func (*Server) GracefulStop added in v0.19.5 

func (srv *Server) GracefulStop(ctx context.Context) error

GracefulStop stops sessions, persists the dagql cache and closes the engine's DBs. The DBs run without syncing (bolt NoSync=true plus NoFreelistSync/NoGrowSync, SQLite synchronous=OFF) for performance, and the stop does not sync them either; see the comment at the end.

func (*Server) Info added in v0.11.8 

func (srv *Server) Info(context.Context, *controlapi.InfoRequest) (*controlapi.InfoResponse, error)

func (*Server) LeaseManager added in v0.12.0 

func (srv *Server) LeaseManager() *bkcache.LeaseManager

The lease manager for the engine as a whole

func (*Server) ListWorkers added in v0.11.8 

func (srv *Server) ListWorkers(context.Context, *controlapi.ListWorkersRequest) (*controlapi.ListWorkersResponse, error)

func (*Server) Locker added in v0.18.5 

func (srv *Server) Locker() *locker.Locker

func (*Server) LogMetrics added in v0.11.8 

func (srv *Server) LogMetrics(l *logrus.Entry) *logrus.Entry

func (*Server) MCPSessions 

func (srv *Server) MCPSessions(ctx context.Context) (*core.MCPSessions, error)

The live MCP sessions for the current client's session

func (*Server) MainClientCallerMetadata added in v0.17.0 

func (srv *Server) MainClientCallerMetadata(ctx context.Context) (*engine.ClientMetadata, error)

The Client metadata of the main client caller (i.e. the one who created the session, typically the CLI invoked by the user)

func (*Server) ModuleParent added in v0.19.8 

func (srv *Server) ModuleParent(ctx context.Context) (dagql.ObjectResult[*core.Module], error)

If the current client is a module client or a client created by a module function, returns that module.

func (*Server) ModuleParentHostClientMetadata 

func (srv *Server) ModuleParentHostClientMetadata(ctx context.Context) (*engine.ClientMetadata, error)

The nearest non-module client above the module ModuleParent returns: the client whose host that module was loaded from. Unlike NonModuleParentClientMetadata, a nested exec under the module is skipped.

func (*Server) MuxEndpoint added in v0.11.8 

func (srv *Server) MuxEndpoint(ctx context.Context, path string, handler http.Handler) error

Mix in this http endpoint+handler to the current client's session

func (*Server) NonModuleParentClientMetadata added in v0.12.6 

func (srv *Server) NonModuleParentClientMetadata(ctx context.Context) (*engine.ClientMetadata, error)

The nearest ancestor client that is not a module (either a caller from the host like the CLI or a nested exec). Useful for figuring out where local sources should be resolved from through chains of dependency modules.

func (*Server) OCIStore added in v0.12.0 

func (srv *Server) OCIStore() content.Store

The content store for the engine as a whole

func (*Server) Platform added in v0.12.0 

func (srv *Server) Platform() core.Platform

The default platform for the engine as a whole

func (*Server) ProfilePhase 

func (srv *Server) ProfilePhase(ctx context.Context, phase string) ([]byte, error)

ProfilePhase arms a CPU profile of the next run of the named phase and returns it in pprof's format once the run ends. It disarms if ctx ends before the run starts; once started, the profile runs to the run's end. One profile can be armed at a time.

func (*Server) PruneEngineLocalCacheEntries added in v0.12.0 

func (srv *Server) PruneEngineLocalCacheEntries(ctx context.Context, opts core.EngineCachePruneOptions) (*core.EngineCacheEntrySet, error)

Prune the local cache of releaseable entries. With no options, preserve the legacy behavior of pruning all releasable disk cache entries. Explicit disk and structural controls run only their respective stages; UseDefaultPolicy runs both configured stages when automatic GC is enabled.

func (*Server) Register added in v0.11.8 

func (srv *Server) Register(server *grpc.Server)

func (*Server) RegisterNestedClientTransport 

func (srv *Server) RegisterNestedClientTransport(
	ctx context.Context,
	metadata *engine.ClientMetadata,
	parentClientID string,
) (*engine.NestedClientTransport, error)

RegisterNestedClientTransport delegates one unique nested transport from the creating request's held scope. The descriptor and both lifecycle leases are published together before the proxy can serve its first request.

func (*Server) RegisterNestedClientTransportForExec 

func (srv *Server) RegisterNestedClientTransportForExec(
	ctx context.Context,
	metadata *engine.ClientMetadata,
	parentClientID string,
	attachablesClientID string,
	fromExecHelper bool,
) (*engine.NestedClientTransport, error)

RegisterNestedClientTransportForExec additionally binds a logical nested client to the exact bootstrap attachables channel created by the same exec. The binding is internal proxy state and cannot come from request metadata. fromExecHelper says that the exec's session helper registers the attachables (see ExpectNestedExecAttachables).

func (*Server) RegistryResolver added in v0.21.0 

func (srv *Server) RegistryResolver(ctx context.Context) (*serverresolver.Resolver, error)

func (*Server) SchemaBuilderMemo 

func (srv *Server) SchemaBuilderMemo(ctx context.Context) (*core.SchemaBuilderMemo, error)

SchemaBuilderMemo returns the current client's memo of schema builders by module set. Builders derived from DefaultDeps do not carry it, so a builder stored in a long-lived value (a decoded Module's Deps) cannot pin it.

func (*Server) SecretSalt added in v0.18.6 

func (srv *Server) SecretSalt() []byte

A shared engine-wide salt used when creating cache keys for secrets based on their plaintext

func (*Server) ServeHTTP added in v0.11.8 

func (srv *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves clients directly hitting the engine API (i.e. main client callers, not nested execs like module functions)

func (*Server) ServeHTTPToNestedClient added in v0.11.8 

func (srv *Server) ServeHTTPToNestedClient(
	w http.ResponseWriter,
	r *http.Request,
	transport *engine.NestedClientTransport,
	nestedClientMetadata *engine.ClientMetadata,
	callerClientID string,
	inertAttachables bool,
	moduleCtx dagql.AnyObjectResult,
	functionCall dagql.Typed,
)

ServeHTTPToNestedClient serves nested clients, including module function calls.

func (*Server) ServeHTTPToNewSession 

func (srv *Server) ServeHTTPToNewSession(w http.ResponseWriter, r *http.Request)

ServeHTTPToNewSession serves an exec's new session endpoint the same way the engine's main listener serves clients: gRPC requests go to the control API the client handshake uses, and every other request is a root client, so each client that connects starts its own session.

func (*Server) ServeModule added in v0.11.8 

func (srv *Server) ServeModule(ctx context.Context, mod dagql.ObjectResult[*core.Module], includeDependencies bool, main bool) error

Stitch in the given module to the list being served to the current client. When includeDependencies is true, dependency modules are also served with their constructors on the Query root. When main is true, the module's main-object methods are promoted onto the Query root.

func (*Server) Server added in v0.17.0 

func (srv *Server) Server(ctx context.Context) (*dagql.Server, error)

The DagQL server for the current client's session

func (*Server) Services added in v0.12.0 

func (srv *Server) Services(ctx context.Context) (*core.Services, error)

The services for the current client's session

func (*Server) SessionSchemaBuilderMemo added in v0.21.11 

func (srv *Server) SessionSchemaBuilderMemo(ctx context.Context) (*core.SchemaBuilderMemo, error)

SessionSchemaBuilderMemo returns the current session's memo of module dependency schemas, or nil once the session is tearing down.

func (*Server) SessionScopedContext 

func (srv *Server) SessionScopedContext(ctx context.Context) (context.Context, error)

SessionScopedContext returns a context that lives for the remainder of the current client's session: it is detached from the given context's cancellation and is canceled when the session begins closing.

func (*Server) SetCurrentWorkspaceLookup added in v0.21.0 

func (srv *Server) SetCurrentWorkspaceLookup(
	ctx context.Context,
	namespace string,
	operation string,
	inputs []any,
	value string,
) error

func (*Server) SetSessionTitle 

func (srv *Server) SetSessionTitle(ctx context.Context, title string) error

SetSessionTitle implements Query.setSessionTitle. It names the calling session's archive and publishes the title into the session's telemetry as a span-name record on the main client's primary span, so every consumer of the trace -- the CLI's frontend via its live stream, Cloud, the archive's own history -- renames the session from this one call. Only the session's main client may name it; module clients and nested CLIs (including ones in a container the main client started) are separate clients and are refused.

func (*Server) SharedCloudArtifactClient 

func (srv *Server) SharedCloudArtifactClient(ctx context.Context, scope string) (*engineclient.Client, error)

Related artifacts share a cloud session and its module call cache.

func (*Server) SnapshotManager added in v0.21.0 

func (srv *Server) SnapshotManager() bkcache.SnapshotManager

func (*Server) SpecificClientAttachableConn added in v0.21.0 

func (srv *Server) SpecificClientAttachableConn(ctx context.Context, clientID string, opts core.SpecificClientAttachableConnOpts) (*grpc.ClientConn, bool, error)

func (*Server) SpecificClientMetadata added in v0.20.0 

func (srv *Server) SpecificClientMetadata(ctx context.Context, clientID string) (*engine.ClientMetadata, error)

The Client metadata of a specific client ID within the same session as the current client.

func (*Server) TelemetrySeenKeyStore added in v0.21.0 

func (srv *Server) TelemetrySeenKeyStore(ctx context.Context) (dagql.TelemetrySeenKeyStore, error)

func (*Server) Watch 

func (srv *Server) Watch(threshold time.Duration)

Watch switches the session watch on with threshold, or off when threshold is 0. Sessions already running keep their threshold, or stay unwatched.

func (*Server) WatchThreshold 

func (srv *Server) WatchThreshold() time.Duration

WatchThreshold is the session watch's threshold, 0 when it's off.

func (*Server) WriteDagqlCacheDebugSnapshot added in v0.21.0 

func (srv *Server) WriteDagqlCacheDebugSnapshot(w io.Writer) error

type SessionLifecycleDebugSnapshot 

type SessionLifecycleDebugSnapshot struct {
	SessionID   string                         `json:"session_id"`
	State       string                         `json:"state"`
	Records     int                            `json:"records"`
	Runtimes    int                            `json:"runtimes"`
	LeaseCounts []LifecycleRetentionReason     `json:"lease_counts,omitempty"`
	Telemetry   LifecycleTelemetryCounts       `json:"telemetry"`
	Clients     []ClientLifecycleDebugSnapshot `json:"clients"`
}

type Topic added in v0.12.5 

type Topic struct {
	TraceID  trace.TraceID
	ClientID string
}

func (Topic) String added in v0.12.5 

func (t Topic) String() string

Source Files

View all Source files

Directories

Path Synopsis

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.