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 localPath's bytes to remotePath (both absolute),
	// creating or truncating the destination. No SHA-256 verification
	// happens here: callers hash before and after for a pure bytes-copy
	// that lets each backend pick its own transport. ctx cancellation
	// interrupts the stream, leaving a partial file at remotePath.
	StreamFile(ctx context.Context, localPath, remotePath string) error
}

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

	// Auth priority: PrivateKey (raw contents, wins over PrivateKeyPath)
	// beats PrivateKeyPath (read at Open time) beats Password (fallback).
	// Passphrase decrypts the key. All three use []byte so Close() can
	// zero the provider's copy; golang.org/x/crypto/ssh makes its own.
	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 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 once exceeded; the default of 4 stays under typical
	// caps. 0 uses the default; negative disables the cap (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 fields, meaningful only when Auth=="kerberos" (the
	// provider-config layer catches a misconfigured Auth at plan time).
	// KrbRealm is required; KrbSpn defaults to "HTTP/<Host>";
	// KrbConfigPath defaults to the first existing of $KRB5_CONFIG,
	// ~/.config/krb5.conf, /etc/krb5.conf. Setting KrbCCachePath
	// switches from password-mode (inline AS-REQ) to ccache-mode
	// (reuse an existing TGT) and Password is then 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

	// MaxShells caps the number of concurrent WinRM shells this backend
	// will open. Windows' default MaxShellsPerUser is 5; with Terraform's
	// default -parallelism=10 the provider can easily exceed that and
	// receive HTTP 400. Default: 3.
	MaxShells int
}