fusefile

type Cache struct {
	Enabled bool `yaml:"enabled,omitempty"`
}

type Command struct {
	// Shell is the shell-form command; set when `run` was a yaml scalar.
	Shell string
	// Argv is the exec-form argv; set when `run` was a yaml sequence.
	Argv []string
}

type Compiled struct {
	Spec            ResourceSpec
	ManifestJSON    []byte
	StartupScript   string
	RequiredSecrets []string
	Expose          []ExposeSpec

	// Healthcheck is the environment-level readiness probe, or nil when the
	// author declared none. It does not travel in the manifest: the manifest
	// describes services, and this probe is about the environment.
	Healthcheck *HealthcheckSpec

	// Desktop is the graphical session's geometry, or nil when the author
	// declared none. Like Healthcheck it rides beside the manifest, not in
	// it: the manifest describes services, and the desktop is about the
	// environment.
	Desktop *DesktopSpec

	// Copy is the compiled `copy` block: one entry per authored entry, with
	// its guest path resolved against the workspace. The sources are named,
	// never read. Expanding a directory into files is the CLI's job
	// (cli/copy.go), so that this compiler stays a pure function of the
	// Fusefile and `fuse compile` keeps working with no filesystem behind it.
	Copy []CopySpec

	// BuildScript is the setup phase alone, for `fuse build` to run through
	// the exec path (600s) rather than the startup-script path (30s).
	// StartupScript still carries setup+run, so `fuse up` is unchanged.
	BuildScript string

	// RunScript is the run command alone, for a boot whose setup phase is
	// already baked into a seed rootfs (`fuse up --from-build`). Replaying
	// setup there would redo the work the artifact exists to skip.
	RunScript string

	// StartupTimeoutSeconds carries Fusefile.StartupTimeout to the wire.
	// Zero means the author did not ask for one and the orchestrator's
	// default applies.
	StartupTimeoutSeconds int64
}

type CopyEntry struct {
	// From is a file or directory on the authoring machine, resolved
	// relative to the Fusefile's directory rather than the process working
	// directory, so `fuse up ./repro/Fusefile` copies the same sources it
	// would from inside that directory. A directory is expanded
	// client-side into one entry per regular file; a symlink is an error
	// rather than something silently followed out of the tree.
	From string `yaml:"from"`

	// To is where it lands in the guest. An absolute path is taken as
	// written; a relative one resolves against the workspace, the same
	// directory setup and run already start in. For a directory source this
	// is the directory the tree lands under.
	To string `yaml:"to"`
}

type CopySpec struct {
	// From is the authored source path, carried through unchanged. It is
	// still relative to the Fusefile's directory, because only the client
	// that reads the Fusefile knows where that is.
	From string

	// To is the resolved absolute guest path. A file source lands exactly
	// here; a directory source lands its tree under here.
	To string
}

type Desktop struct {
	// Width is the display width in pixels.
	Width int `yaml:"width"`
	// Height is the display height in pixels.
	Height int `yaml:"height"`
}

type DesktopSpec struct {
	Width  int
	Height int
}

type EnvValue struct {
	Value  string `yaml:"value,omitempty"`
	Secret string `yaml:"secret,omitempty"`
}

type Expose struct {
	Port int    `yaml:"port"`
	As   string `yaml:"as,omitempty"`
}

type ExposeSpec struct {
	Port int
	As   string
}

type File struct {
	// Path is where the file lands in the guest. A relative path resolves
	// against the workspace.
	Path string `yaml:"path"`
	// Source is a path on the authoring machine, relative to the Fusefile.
	Source string `yaml:"source,omitempty"`
	// Content is a literal file body.
	Content string `yaml:"content,omitempty"`
	// Mode is an octal permission string, e.g. "0755". Empty leaves the
	// mode to the guest's umask.
	Mode string `yaml:"mode,omitempty"`
}

type Fusefile struct {
	Version int `yaml:"version"`

	// Name is the task id this Fusefile boots under, and through it the
	// environment's identity: the orchestrator names the vm by prefixing the
	// task id, so `name: sandbox` is the environment `fuse-sandbox`.
	//
	// It is optional and `fuse up --task-id` still wins, but declaring it is
	// what makes the name a property of the project rather than of whatever
	// directory the file happens to sit in. Without it the CLI falls back to
	// the parent directory's name, so two checkouts of the same repo derive
	// the same id and the second `up` collides.
	//
	// Held to a DNS label for the same reason expose[].as is: it becomes part
	// of a vm name rather than free text.
	Name string `yaml:"name,omitempty"`

	Image     string      `yaml:"image,omitempty"`
	Resources Resources   `yaml:"resources,omitempty"`
	Placement Placement   `yaml:"placement,omitempty"`
	Cache     Cache       `yaml:"cache,omitempty"`
	Files     []File      `yaml:"files,omitempty"`
	Copy      []CopyEntry `yaml:"copy,omitempty"`

	// Env is set for every build step and for Run. it reuses the same
	// value-or-secret grammar as services.<name>.env, so there is one env
	// shape in the file. services do not inherit it: a service runs in its
	// own container and takes its environment from its own env map.
	//
	// a value never reaches the generated script. the compiler carries the
	// block in the manifest instead; the orchestrator resolves any secret
	// reference and renders the result to a file under /fuse, and the script
	// sources that path. the script is handed to the guest as a single
	// `sh -lc` argument, so anything interpolated into its text is readable
	// in the host's process table for the length of the boot.
	//
	// a key is written into that file unquoted, as a shell identifier, so
	// validate holds it to ^[A-Za-z_][A-Za-z0-9_]*$.
	Env map[string]EnvValue `yaml:"env,omitempty"`

	// Build is the work that prepares the environment: it runs to completion
	// before Run, in the same workspace, and a failure in it is reported as a
	// build failure rather than as a failure of the task itself. It is the
	// first-class spelling of the phase.
	Build []Step `yaml:"build,omitempty"`

	// Setup is a deprecated alias for Build, kept accepted so every Fusefile
	// written before the rename keeps compiling byte for byte. Setting both is
	// a validation error rather than a concatenation: which half runs first
	// would be a guess, and running steps in an order the author did not write
	// is worse than making them pick a spelling.
	//
	// Nothing downstream reads either field directly. BuildSteps resolves the
	// alias in one place so the compiler, the layer keys, and the CLI cannot
	// disagree about which one won.
	Setup []Step `yaml:"setup,omitempty"`

	Services  map[string]Service `yaml:"services,omitempty"`
	Run       Command            `yaml:"run,omitempty"`
	Workspace string             `yaml:"workspace,omitempty"`
	Expose    []Expose           `yaml:"expose,omitempty"`
	Secrets   []string           `yaml:"secrets,omitempty"`

	// Healthcheck is the environment-level readiness probe. It is optional
	// and there is at most one: the point of the block is that the whole
	// sandbox has a single verdict.
	Healthcheck *HealthProbe `yaml:"healthcheck,omitempty"`

	// Desktop declares that the environment boots a graphical session and at
	// what geometry. It requires an image that carries the desktop stack
	// (see fc-bake-desktop-rootfs.sh); on any other image the declaration is
	// inert and the computer surface answers 503. Nil means no desktop, and
	// stays nil all the way down, the same contract Healthcheck has.
	Desktop *Desktop `yaml:"desktop,omitempty"`

	// StartupTimeout bounds the generated startup script (build + run) as a
	// go duration, e.g. "45s". Empty means the orchestrator's default. The
	// orchestrator rejects a value above its configured ceiling rather than
	// clamping it, so an author always knows what bound they got.
	//
	// This is not the knob for a genuinely long setup phase: the ceiling is
	// bounded by the control plane's HTTP write timeout because create is
	// synchronous. Bake long work into an image with `fuse build` instead.
	StartupTimeout string `yaml:"startup_timeout,omitempty"`
}

type HealthCheck struct {
	Test     []string `yaml:"test,omitempty"`
	Interval string   `yaml:"interval,omitempty"`
	Timeout  string   `yaml:"timeout,omitempty"`
	Retries  int      `yaml:"retries,omitempty"`
}

type HealthProbe struct {
	// HTTP probes a port inside the guest. Successful means a response with
	// a 2xx or 3xx status.
	HTTP *HealthProbeHTTP `yaml:"http,omitempty"`

	// Exec is an argv run inside the guest. Successful means exit status 0.
	// It is an argv rather than a shell string so an argument can never be
	// reinterpreted by a shell, matching the exec form of `run`.
	Exec []string `yaml:"exec,omitempty"`

	// Interval is how long the guest agent waits between attempts, as a go
	// duration ("5s"). Empty means the guest agent's default.
	Interval string `yaml:"interval,omitempty"`

	// Timeout bounds one attempt, as a go duration ("2s"). Empty means the
	// guest agent's default. It may not exceed Interval: attempts are run one
	// at a time, so a timeout longer than the interval would silently stretch
	// the interval instead of overlapping attempts.
	Timeout string `yaml:"timeout,omitempty"`

	// Retries is how many consecutive failed attempts flip the verdict from
	// passing to failing. Zero means the guest agent's default. A single
	// failed attempt is not a verdict: a probe that is retried is the only
	// kind worth reporting on.
	Retries int `yaml:"retries,omitempty"`

	// StartPeriod is a grace window measured from the first attempt during
	// which failures do not count against Retries, as a go duration ("10s").
	// It covers the gap between "the process was started" and "the process
	// is serving", which is exactly the gap this probe exists to close. Once
	// the probe passes once, the window is over for good: a service that came
	// up and then fell over is failing, not still starting.
	StartPeriod string `yaml:"start_period,omitempty"`
}

type HealthProbeHTTP struct {
	// Port is the guest-side port to dial, 1 to 65535.
	Port int `yaml:"port"`
	// Path is the request path, which must start with "/". Empty means "/".
	Path string `yaml:"path,omitempty"`
}

type HealthcheckHTTP struct {
	Port int
	Path string
}

type HealthcheckSpec struct {
	HTTP *HealthcheckHTTP
	Exec []string

	IntervalSeconds    int64
	TimeoutSeconds     int64
	Retries            int
	StartPeriodSeconds int64
}

type InputDigester func(patterns []string) (string, error)

type LayerKey struct {
	// Index is the step's position in the build phase (Fusefile.BuildSteps).
	Index int
	// Script is the shell fragment this step emits, hashed byte for byte.
	Script string
	// Key is the step's content-addressed layer key, hex sha256. Empty when
	// the step is not cacheable.
	Key string
	// ParentKey is the key this step was chained onto: the previous step's
	// key, or the base key for the first step. Empty when not cacheable.
	ParentKey string
	// InputsDigest is the digest of the step's declared inputs, "" when the
	// step declares none.
	InputsDigest string
	// Cacheable reports whether this step can produce or restore a layer.
	Cacheable bool
	// Reason explains why Cacheable is false; empty when it is true.
	Reason string
}

type LayerOptions struct {
	// BaseKey identifies the base rootfs the first step builds on. Empty
	// means derive it from Fusefile.Image via BaseKey.
	//
	// Ideally this is a digest of the resolved rootfs bytes; the host agent
	// does not expose one yet (it resolves `image` to a file by name with no
	// content hash), so today it is a digest of the image reference. That is
	// a weaker binding: republishing the same tag with new contents does not
	// invalidate. Wiring a real rootfs digest is backend work.
	BaseKey string
}

type Placement struct {
	// Host pins the environment to an exact host id. A pin is not an
	// override: the pinned host still has to be active, run the right
	// backend, and fit the request.
	Host string `yaml:"host,omitempty"`

	// Labels must all match the host's operator-declared labels (AND).
	Labels map[string]string `yaml:"labels,omitempty"`
}

type ResourceSpec struct {
	CPUs      int32
	RamMB     int32
	StorageGB int32
	Region    string
	// Arch restricts scheduling to hosts of this CPU architecture ("amd64",
	// "arm64"). Not yet authorable in a Fusefile; carried for wire parity
	// so compile output mirrors the orchestrator's spec shape.
	Arch              string
	MaxRuntimeSeconds int64
	// IdleTimeoutSeconds destroys the environment after this many seconds
	// with no exec and no attach session. Zero means no idle expiry.
	IdleTimeoutSeconds int64
	Image              string
	GPUs               int32
	GPUKind            string
	GPUProfile         string
	// HostID pins the environment to an exact host id (placement.host).
	HostID string
	// Labels are the placement label selectors (placement.labels); every
	// pair must match the host's declared labels.
	Labels map[string]string
}

type Resources struct {
	CPUs    VCPUs  `yaml:"cpus,omitempty"`
	GPU     int    `yaml:"gpu,omitempty"`      // device count: whole GPUs, or MIG instances when gpu_profile is set
	GPUKind string `yaml:"gpu_kind,omitempty"` // optional match, e.g. "a100"
	// GPUProfile requests fractional GPU allocation: a MIG profile in
	// nvidia mig-parted vocabulary (e.g. "1g.10gb", "2g.20gb"). When set,
	// `gpu` counts MIG instances of this profile rather than whole
	// devices (decision D5). Empty means whole-device allocation.
	GPUProfile string `yaml:"gpu_profile,omitempty"`
	Memory     string `yaml:"memory,omitempty"` // e.g. "2GB", "2G", "2GiB", "512MB"
	// Disk sizes the guest root disk, e.g. "10GB". It is the preferred
	// spelling; Storage is a permanent alias kept for files written before
	// the rename. Setting both is allowed only if they mean the same size.
	Disk       string `yaml:"disk,omitempty"`
	Storage    string `yaml:"storage,omitempty"`     // alias for Disk, never removed
	Region     string `yaml:"region,omitempty"`      // schedules only onto a host registered in this region; empty matches any
	MaxRuntime string `yaml:"max_runtime,omitempty"` // go duration
	// IdleTimeout destroys the environment after this long with no exec
	// and no attach session. Go duration. "idle" means exactly that: no
	// control-plane activity. In-guest CPU or network traffic is not
	// observed. Empty means no idle expiry.
	IdleTimeout string `yaml:"idle_timeout,omitempty"` // go duration
}

type Service struct {
	Image string              `yaml:"image"`
	Ports []int               `yaml:"ports,omitempty"`
	Env   map[string]EnvValue `yaml:"env,omitempty"`

	// Command, Restart, HealthCheck, and DependsOn map one-to-one onto their
	// compose-native counterparts; the guest's `docker compose up` (decision
	// D1) is what interprets them, so no new runtime semantics are
	// introduced here. They govern the compose container, not the VM: a
	// failing healthcheck marks the service unhealthy inside the guest, it
	// does not signal the orchestrator that the environment is dead.
	Command []string `yaml:"command,omitempty"`
	// Restart must be one of the compose-native policies: "no", "always",
	// "on-failure", "unless-stopped".
	Restart     string       `yaml:"restart,omitempty"`
	HealthCheck *HealthCheck `yaml:"healthcheck,omitempty"`
	DependsOn   []string     `yaml:"depends_on,omitempty"`
}

type Step struct {
	Run    string   `yaml:"run"`
	Inputs []string `yaml:"inputs,omitempty"`
	Cache  *bool    `yaml:"cache,omitempty"`

	// Workdir scopes this one step to a directory. a relative path resolves
	// against Fusefile.Workspace, since every step starts there. the step is
	// emitted as a subshell, so the directory change does not leak into the
	// next step; only the directory is scoped, not the shell (see the note on
	// setupScripts). empty means the step runs in the workspace, unchanged.
	Workdir string `yaml:"workdir,omitempty"`
}

type VCPUs int32