connection

type Connection interface {
	Runner

	// Open establishes any persistent state the backend needs (an SSH
	// client, a pooled HTTP transport, etc.). Local is stateless and
	// returns nil.
	Open(ctx context.Context) error

	// Close releases the backend's persistent state. Idempotent. Local
	// is a no-op.
	Close() error

	// Healthcheck returns nil if the backend can reach the host and run
	// a trivial command. Used at provider Configure time to fail fast on
	// misconfiguration.
	Healthcheck(ctx context.Context) error

	// Backend returns the lowercase identifier of the implementation —
	// "local" | "ssh" | "winrm". Used for tflog field decoration; the
	// schema's `backend` attribute is the user-facing form.
	Backend() string
}

type LocalOptions struct {
	// PwshPath, if non-empty, is used as-is. Set via the provider's
	// `local.pwsh_path` attribute or the HYPERV_PWSH_PATH env var.
	PwshPath string
}

type Result struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
	Duration time.Duration
}

type Runner interface {
	RunScript(ctx context.Context, script string, stdinJSON []byte) (Result, error)

	// StreamFile copies the bytes at localPath on the runner to
	// remotePath on the host. Both paths are absolute. Backends create
	// (or truncate) the destination file and write streamed bytes —
	// nothing is buffered in memory beyond the backend's transport
	// chunk size.
	//
	// No SHA-256 verification is performed at this layer: the typed
	// client (internal/hyperv) computes the local hash before calling
	// StreamFile and verifies the remote hash via the existing
	// image_file/get.ps1 path after the destination rename. Keeping
	// the primitive a pure bytes-copy lets each backend pick its own
	// optimal transport without dragging hashing into the protocol.
	//
	// Cancellation through ctx interrupts the stream; partial files at
	// the remote path are the caller's problem to clean up. Resources
	// that need atomicity stage to a `.part` sibling and rename, the
	// same pattern image_file's url-mode uses.
	StreamFile(ctx context.Context, localPath, remotePath string) error
}

type SSHOptions struct {
	Host     string // required
	Port     int    // default 22
	Username string // required

	// Auth methods, in priority order:
	//
	//   1. PrivateKey       (raw key contents -- wins if both PrivateKey and PrivateKeyPath are set)
	//   2. PrivateKeyPath   (path read at Open time)
	//   3. Password         (fallback only -- key auth is preferred)
	//
	// Passphrase decrypts the key when set.
	//
	// All three sensitive fields use []byte so Close() can zero the
	// long-lived copy held by the backend. Libraries we hand the value
	// to (golang.org/x/crypto/ssh) make their own copies; zeroing here
	// covers the provider's own state, not theirs.
	PrivateKey     []byte
	PrivateKeyPath string
	Passphrase     []byte
	Password       []byte

	// KnownHostsPath is the file used for host key verification. Default:
	// ~/.ssh/known_hosts. Empty path falls back to the default. A missing
	// file is a hard error -- silently disabling host-key checking would be
	// a security regression.
	KnownHostsPath string

	// Timeout is the dial timeout. Default 30s.
	Timeout time.Duration

	// CommandTimeout bounds an individual RunScript call. Default
	// 5m. A wedged remote cmdlet surfaces as ErrTimeout instead of
	// blocking the whole apply. Set to 0 to disable.
	CommandTimeout time.Duration

	// KeepaliveInterval is how often the backend sends an SSH
	// keepalive request while the persistent client is open.
	// Default 30s. Prevents NAT/firewall mid-apply drops. Set to
	// 0 to disable.
	KeepaliveInterval time.Duration

	// PwshPath is the binary the remote shell invokes per call. Default:
	// "powershell.exe" -- universally available on Windows. Set to "pwsh"
	// or "pwsh.exe" to prefer PS 7+ if installed.
	PwshPath string

	// MaxConcurrentSessions caps the number of in-flight RunScript calls
	// against the persistent ssh.Client. OpenSSH's per-connection
	// MaxSessions limit (default 10, often 4-6 on hardened Windows
	// builds) rejects late session opens with "rejected: connect failed
	// (open failed)" once exceeded. Default 4 stays well under typical
	// Windows OpenSSH caps; raise it on hosts with sshd_config tuned
	// upward, lower it if the bench surfaces the error under heavier
	// fanout. Set to 0 to use the default; negative values disable the
	// cap entirely (not recommended).
	MaxConcurrentSessions int
}

type WinRMOptions struct {
	Host     string // required
	Port     int    // default 5986 (HTTPS) or 5985 (HTTP)
	Username string // required
	// Password is []byte so Close() can zero the long-lived copy held
	// by the backend. masterzen/winrm copies the value into its own
	// EndpointParams when we construct the client; that copy is outside
	// our reach, but our state stays clean across the connection's life.
	Password []byte // required for ntlm/basic; for kerberos, mutually exclusive with KrbCCachePath

	UseHTTPS bool   // default true; flip to false only for diagnosing TLS-only failures
	Insecure bool   // skip TLS certificate verification (default false)
	Auth     string // "ntlm" | "basic" | "kerberos"; default "ntlm"
	CACert   string // path to a CA bundle PEM; empty = system roots

	// Kerberos auth fields. Only meaningful when Auth=="kerberos"; ignored
	// otherwise. The provider-config layer is responsible for catching the
	// "kerberos fields set without auth=kerberos" misconfig at plan time;
	// this struct just transports the values.
	//
	// KrbRealm is required (NewWinRM rejects empty when Auth=="kerberos").
	// KrbSpn defaults to "HTTP/<Host>" when empty.
	// KrbConfigPath defaults to first-existing of $KRB5_CONFIG,
	// ~/.config/krb5.conf, /etc/krb5.conf when empty.
	// KrbCCachePath, when set, switches from password-mode (inline AS-REQ)
	// to ccache-mode (re-use a pre-existing TGT). When set, Password is
	// ignored.
	KrbRealm      string
	KrbSpn        string
	KrbConfigPath string
	KrbCCachePath string

	// Timeout sets `http.Client.Timeout` for every WSMan request.
	// Default 0 (no wall-clock cap) -- file transfers can run for
	// arbitrarily long. The initial TCP dial is bounded by the OS;
	// a connection that stalls mid-transfer (host freezes, packets
	// silently dropped) holds the apply until ctx cancellation
	// (operator Ctrl+C).
	Timeout time.Duration

	// CommandTimeout bounds a single RunScript call. Default 5m. A wedged
	// remote cmdlet surfaces as ErrTimeout instead of blocking the whole
	// apply. Set to 0 to disable.
	CommandTimeout time.Duration

	// PwshPath is the binary the remote shell invokes per call. Default:
	// "powershell.exe" -- universally available on Windows. Set to "pwsh"
	// or "pwsh.exe" to prefer PS 7+ if installed.
	PwshPath string
}