engine

type ClientMetadata struct {
	// ClientID is unique to each client, randomly generated each time a client initializes.
	// It's also used as the *buildkit* session ID (as opposed to the dagger session ID), which
	// is created for each client.
	ClientID string `json:"client_id"`

	// ClientSecretToken is a secret token that is unique to every client.
	// Every request w/ that client ID must also include the same token.
	ClientSecretToken string `json:"client_secret_token"`

	// SessionID is the id of the dagger session that a client and any of its nested
	// module clients connect to
	SessionID string `json:"session_id"`

	// ClientHostname is the hostname of the client that made the request. It's
	// used to help identify clients in the logs more clearly; nothing functional.
	ClientHostname string `json:"client_hostname"`

	// ClientStableID is an ID that's persisted in a client'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.
	ClientStableID string `json:"client_stable_id"`

	// ClientVersion is the version string of the client that make the request.
	ClientVersion string `json:"client_version"`

	// (Optional) Pipeline labels for e.g. vcs info like branch, commit, etc.
	Labels map[string]string `json:"labels"`

	// Interactive mode
	Interactive bool `json:"interactive"`

	// InteractiveCommand changes the command that is run in interactive mode.
	InteractiveCommand []string `json:"interactive_command"`

	// Import configuration for Buildkit's remote cache
	UpstreamCacheImportConfig []*controlapi.CacheOptionsEntry `json:"upstream_cache_import_config"`

	// Export configuration for Buildkit's remote cache
	UpstreamCacheExportConfig []*controlapi.CacheOptionsEntry `json:"upstream_cache_export_config"`

	// Dagger Cloud Org
	CloudOrg string `json:"cloud_org"`

	// Disable analytics
	DoNotTrack bool `json:"do_not_track"`

	// SSH auth socket path
	SSHAuthSocketPath string `json:"ssh_auth_socket_path"`

	// Modules permitted to access LLM APIs or "all" to bypass restrictions for any loaded module.
	AllowedLLMModules []string `json:"allowed_llm_modules"`

	// Disable lazy loading on module runtime.
	EagerRuntime bool `json:"eager_runtime"`

	// If set, the auth for cloud requests; used for PARC and scale-out
	CloudAuth *auth.Cloud `json:"cloud_auth,omitempty"`

	// If true, this client enables scaling checks out to cloud engines
	EnableCloudScaleOut bool `json:"enable_cloud_scale_out,omitempty"`

	// if set, this client is another engine scaling out to the current one, and the current
	// one has this ID. Should be included in OTEL span sttrs so we can correlate spans to engine.
	// TODO: This is a bit convoluted; it would be nicer if an engine could figure out its own ID
	// rather than being told what it is by the client connecting to it.
	CloudScaleOutEngineID string `json:"cloud_scale_out_engine_id,omitempty"`

	// ExtraModules specifies additional modules to load at connect time.
	// When Entrypoint is true, the module's main-object methods are proxied onto
	// the Query root in addition to its namespaced constructor.
	ExtraModules []ExtraModule `json:"extra_modules,omitempty"`

	// LoadWorkspaceModules opts this client into loading workspace modules.
	// When false, only the core API is exposed by default.
	LoadWorkspaceModules bool `json:"load_workspace_modules,omitempty"`

	// SingleQuery declares that this client will send at most one GraphQL query
	// request before disconnecting. The engine may use the query document to
	// optimize session initialization.
	SingleQuery bool `json:"single_query,omitempty"`

	// SkipWorkspaceModules is a legacy compatibility input. New clients should
	// use LoadWorkspaceModules instead.
	SkipWorkspaceModules bool `json:"skip_workspace_modules,omitempty"`

	// SuppressCompatWorkspaceWarning disables the user-facing warning emitted
	// when a legacy dagger.json is projected into a compat workspace.
	SuppressCompatWorkspaceWarning bool `json:"suppress_compat_workspace_warning,omitempty"`

	// Workspace explicitly declares the workspace binding for this client.
	// When unset, the engine applies default workspace binding behavior.
	Workspace *string `json:"workspace,omitempty"`

	// WorkspaceEnv explicitly selects the workspace environment overlay for
	// this client. When unset, no environment overlay is applied.
	WorkspaceEnv *string `json:"workspace_env,omitempty"`

	// UserConfigPath is the caller-host path to the user-level Dagger config
	// file (~/.config/dagger/config.toml). The engine reads it through the
	// caller host session to apply user-level workspace overrides. When unset,
	// no user-level config is consulted.
	UserConfigPath string `json:"user_config_path,omitempty"`

	// WorkspaceModuleScope hints at the workspace module this client's first
	// schema introspection targets: the leading CLI command token, unresolved
	// (it may name a module, an entrypoint-proxied function, or a typo). The
	// engine may use it to defer loading unrelated workspace modules for the
	// first request whose only full-schema demand is currentTypeDefs. An
	// unrecognized token falls back to the entrypoint module when one is
	// configured, else to loading everything; deferred modules load on demand
	// from later requests.
	WorkspaceModuleScope string `json:"workspace_module_scope,omitempty"`

	// UseRecipeIDsByDefault asks id() to return recipe-form IDs unless the
	// request explicitly passes a recipe argument. This is engine-internal
	// nested-client state and must not be forwarded through client headers.
	UseRecipeIDsByDefault bool `json:"-"`

	// Profile enables engine wall-clock profiling (wcprof) for the duration
	// of this client's work. Experimental; the recorded events are retrieved
	// via the engine debug endpoints.
	Profile bool `json:"profile,omitempty"`
}

type ExtraModule struct {
	Ref        string `json:"ref"`
	Name       string `json:"name,omitempty"`
	Entrypoint bool   `json:"entrypoint,omitempty"`
}

type LocalExportOpts struct {
	Path               string      `json:"path"`
	IsFileStream       bool        `json:"is_file_stream"`
	FileOriginalName   string      `json:"file_original_name"`
	AllowParentDirPath bool        `json:"allow_parent_dir_path"`
	FileMode           os.FileMode `json:"file_mode"`
	// whether to just merge in contents of a directory to the target on the host
	// or to replace the target entirely such that it matches the source directory,
	// which includes deleting any files that are not in the source directory
	Merge       bool
	RemovePaths []string `json:"remove_paths"`
}

type LocalImportOpts struct {
	Path               string           `json:"path"`
	UseGitIgnore       bool             `json:"use_gitignore"`
	IncludePatterns    []string         `json:"include_patterns"`
	ExcludePatterns    []string         `json:"exclude_patterns"`
	FollowPaths        []string         `json:"follow_paths"`
	ReadSingleFileOnly bool             `json:"read_single_file_only"`
	MaxFileSize        int64            `json:"max_file_size"`
	StatPathOnly       bool             `json:"stat_path_only"`
	StatReturnAbsPath  bool             `json:"stat_return_abs_path"`
	StatResolvePath    bool             `json:"stat_resolve_path"`
	GetAbsPathOnly     bool             `json:"get_abs_path_only"`
	GlobPattern        string           `json:"glob_pattern"`
	SearchOpts         *LocalSearchOpts `json:"search_opts,omitempty"`
}

type LocalSearchOpts struct {
	Pattern     string   `json:"pattern"`
	Literal     bool     `json:"literal,omitempty"`
	Multiline   bool     `json:"multiline,omitempty"`
	Dotall      bool     `json:"dotall,omitempty"`
	Insensitive bool     `json:"insensitive,omitempty"`
	SkipIgnored bool     `json:"skip_ignored,omitempty"`
	SkipHidden  bool     `json:"skip_hidden,omitempty"`
	FilesOnly   bool     `json:"files_only,omitempty"`
	Limit       *int     `json:"limit,omitempty"`
	Paths       []string `json:"paths,omitempty"`
	Globs       []string `json:"globs,omitempty"`
}

type LocalSearchResult struct {
	FilePath       string                `json:"file_path"`
	LineNumber     int                   `json:"line_number"`
	AbsoluteOffset int                   `json:"absolute_offset"`
	MatchedLines   string                `json:"matched_lines"`
	Submatches     []LocalSearchSubmatch `json:"submatches,omitempty"`
}

type LocalSearchSubmatch struct {
	Text  string `json:"text"`
	Start int    `json:"start"`
	End   int    `json:"end"`
}