kernel

type Auth struct {
	Mode         AuthMode
	Token        string   // PAT
	ClientID     string   // M2M + U2M (U2M: fixed in-house client, cloud-agnostic); federated PAT uses the optional SP-wide client id
	ClientSecret string   // M2M
	Scopes       []string // U2M — fixed offline_access + sql (cloud-agnostic); nil → kernel default
	RedirectPort uint16   // U2M — no user option today; 0 → kernel default port (8030)
}

type AuthMode int

type Config struct {
	Host        string // workspace hostname, no scheme
	HTTPPath    string // e.g. /sql/1.0/warehouses/abc123 (carries ?o= org routing)
	WarehouseID string // bare warehouse id; preferred over HTTPPath when set
	Auth        Auth   // PAT / OAuth M2M / OAuth U2M

	// UserAgent is forwarded as the User-Agent header so the kernel path is
	// attributed to this driver (not the kernel's built-in UA). Empty leaves it unset.
	UserAgent string

	// RequestTimeout is the total HTTP request deadline, from connect through
	// response-body completion. Zero selects the kernel's 120s default; it is
	// neither unlimited nor an immediate timeout.
	RequestTimeout time.Duration

	// SessionConf carries server-bound session confs verbatim — the same map the
	// Thrift backend forwards (STATEMENT_TIMEOUT, QUERY_TAGS, TIMEZONE, …).
	SessionConf map[string]string

	// TLSSkipVerify accepts any server cert (maps the driver's
	// WithSkipTLSHostVerify / TLSConfig.InsecureSkipVerify). crypto/tls's
	// InsecureSkipVerify disables both chain validation and the hostname check,
	// so the kernel path relaxes both to match.
	TLSSkipVerify bool

	// Experimental kernel-only TLS knobs (from the WithKernel* options). These
	// have no Thrift-path equivalent and are set via config.KernelExperimental.
	// Empty/false fields are simply not applied. TLSTrustedCertsPEM is a custom CA
	// bundle added on top of the system roots; TLSClientCertPEM/TLSClientKeyPEM
	// are the paired mTLS client identity; TLSSkipHostnameVerify skips only the
	// hostname check (finer-grained than the blanket TLSSkipVerify above).
	TLSTrustedCertsPEM    []byte
	TLSClientCertPEM      []byte
	TLSClientKeyPEM       []byte
	TLSSkipHostnameVerify bool

	// ProxyURL configures an HTTP proxy. It is either resolved for this endpoint
	// from the same HTTP(S)_PROXY / NO_PROXY environment the Thrift path uses
	// (NO_PROXY applied during resolution), or set explicitly via WithKernelProxy.
	// Empty leaves the kernel on a direct connection.
	//
	// ProxyUsername / ProxyPassword are out-of-band basic-auth credentials (an
	// alternative to embedding them in ProxyURL's userinfo). ProxyBypassHosts is
	// a comma-separated no-proxy list honored kernel-side. All three are only
	// meaningful with an explicit WithKernelProxy — the env-var path folds
	// credentials into the URL and consumes NO_PROXY during resolution, so it
	// leaves these empty. Empty fields are passed as NULL (kernel default).
	ProxyURL         string
	ProxyUsername    string
	ProxyPassword    string
	ProxyBypassHosts string

	// Retry carries the driver's WithRetries backoff/attempt policy (RetryWaitMin
	// / RetryWaitMax / RetryMax) plus the kernel-only overall retry budget. nil
	// leaves the kernel on its own default retry policy; non-nil forwards to
	// set_retry_config so the caller's policy is authoritative. A pointer so
	// "unset" is distinct from an explicit zero-retry (disable) request.
	Retry *RetryConfig

	// Location is the session time zone used to render DATE / TIMESTAMP values,
	// matching the Thrift path which returns them in this location. nil means UTC.
	Location *time.Location

	// Catalog / Schema select the initial namespace. The kernel C ABI has no
	// catalog/schema config setter, so OpenSession applies them post-connect by
	// running USE CATALOG / USE SCHEMA. Empty leaves the session in the server
	// default namespace.
	Catalog string
	Schema  string

	// DecimalAsFloat scans top-level DECIMAL columns to a lossy float64 instead of
	// the exact string (from WithKernelDecimalAsFloat). Kernel still sends Decimal128.
	DecimalAsFloat bool

	// TokenCacheEnabled controls the kernel's on-disk OAuth U2M token-cache persistence
	// (WithTokenCache / tokenCache DSN param). When false (the default), tokens are held
	// in memory only; when true, the refresh token is persisted encrypted to
	// ~/.config/databricks-sql-kernel/oauth/. U2M-only: PAT and M2M ignore this.
	// Note the zero value is not "unapplied": on the U2M path false is still
	// forwarded to the setter to explicitly disable on-disk persistence by default.
	// Maps to kernel_session_config_set_u2m_token_cache_config.
	TokenCacheEnabled bool

	// Telemetry carries the kernel-owned telemetry collection settings. The Go
	// wrapper telemetry interceptor is disabled on the kernel path; these fields
	// are the configuration the kernel must use for its own telemetry runtime.
	Telemetry *TelemetryConfig

	// DriverSystemConfiguration is the driver/runtime identity stamped onto
	// kernel-owned telemetry. Nil lets the kernel use its built-in defaults.
	DriverSystemConfiguration *DriverSystemConfiguration
}

type DriverSystemConfiguration struct {
	DriverVersion   string
	RuntimeName     string
	RuntimeVersion  string
	RuntimeVendor   string
	OSName          string
	OSVersion       string
	OSArch          string
	DriverName      string
	ClientAppName   string
	LocaleName      string
	CharSetEncoding string
	ProcessName     string
}

type KernelError struct {
	Code       int
	Message    string
	SQLState   string
	VendorCode int32
	HTTPStatus uint16
	Retryable  bool
	QueryID    string
}

type M2MCredentialsProvider interface {
	// M2MCredentials returns the client id and client secret.
	M2MCredentials() (clientID, clientSecret string)
	// M2MScopes returns the configured OAuth scopes. The kernel's C-ABI M2M setter
	// takes no scopes (it applies its own default set), so resolveKernelAuth rejects
	// a custom set via M2MScopesSupported rather than silently dropping it.
	M2MScopes() []string
}

type RetryConfig struct {
	MinWait    time.Duration
	MaxWait    time.Duration
	MaxRetries uint32
	// OverallTimeout is the cumulative retry budget; zero => keep the kernel
	// default (900s). Mirrors the pyo3/napi retry_overall_timeout knob.
	OverallTimeout time.Duration
}

type TelemetryConfig struct {
	Enabled           bool
	BatchSize         int
	FlushInterval     time.Duration
	MaxRetries        uint32
	RetryDelay        time.Duration
	CloseFlushTimeout time.Duration
}

type U2MCredentialsProvider interface {
	// U2MClientID returns the OAuth client id for the U2M browser flow. Used by the
	// kernel path only as a presence marker (see the interface doc above).
	U2MClientID() string
}