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.
	PrivateKey     []byte
	PrivateKeyPath string
	Passphrase     []byte
	Password       string

	// 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
}

type WinRMOptions struct {
	Host     string // required
	Port     int    // default 5986 (HTTPS) or 5985 (HTTP)
	Username string // required
	Password string // required for ntlm/basic

	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 bounds an individual WinRM operation (dial, auth, request).
	// Default 30s. Distinct from CommandTimeout, which bounds the remote
	// PowerShell call.
	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
}