server

package
v1.0.0-beta.15 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2026 License: Apache-2.0 Imports: 147 Imported by: 0

Documentation

Index

Constants

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

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 CacheFactExport 

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

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

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 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
	// CacheFactExport, when set, makes the dagql cache emit its bookkeeping
	// facts as OTel log records through its logger.
	CacheFactExport CacheFactExport
}

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) Spans added in v0.12.5 

func (ps *PubSub) Spans(clientID string) sdktrace.SpanExporter

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) OfferParts 

func (a *RemoteCacheAdapter) OfferParts(ctx context.Context, receiver dagql.AnyResult, offers []dagql.PersistedPartOffer) ([]dagql.OfferDisposition, error)

OfferParts is an engine control operation, not a user's GraphQL call. Its receiver is already registered and held by the caller.

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) 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) 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 client connected to a cloud engine. If bool return is false, the local engine should be used. Session attachables for the returned client will be proxied back 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) 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) 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 attempts to close all boltdbs and do a final syncfs since all the DBs run with NoSync=true (plus NoFreelistSync/NoGrowSync) for performance reasons.

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) 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) 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) 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,
) (*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.

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) ServeModule added in v0.11.8 

func (srv *Server) ServeModule(ctx context.Context, mod dagql.ObjectResult[*core.Module], includeDependencies bool, entrypoint 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 entrypoint 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) 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) 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) 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.