config

type ArrowConfig struct {
	UseArrowBatches         bool
	UseArrowNativeDecimal   bool
	UseArrowNativeTimestamp bool

	// the following are currently not supported
	UseArrowNativeComplexTypes  bool
	UseArrowNativeIntervalTypes bool
}

type CloudFetchConfig struct {
	UseCloudFetch                bool
	MaxDownloadThreads           int
	MaxFilesInMemory             int
	MinTimeToExpiry              time.Duration
	CloudFetchSpeedThresholdMbps float64 // Minimum download speed in MBps before WARN logging (default: 0.1)
	HTTPClient                   *http.Client
}

type Config struct {
	UserConfig
	TLSConfig *tls.Config // nil disables TLS
	ArrowConfig
	PollInterval              time.Duration
	ClientTimeout             time.Duration // max time the http request can last
	PingTimeout               time.Duration // max time allowed for ping
	CanUseMultipleCatalogs    bool
	DriverName                string
	DriverVersion             string
	ThriftProtocol            string
	ThriftTransport           string
	ThriftProtocolVersion     cli_service.TProtocolVersion
	ThriftDebugClientProtocol bool

	// ClientQueryTimeout is the connector-only, kernel execution deadline set by
	// WithClientQueryTimeout. nil means the option was omitted, which preserves
	// the legacy kernel_statement_execute contract. A non-nil zero explicitly
	// selects unlimited execution through the timeout-aware C API.
	ClientQueryTimeout *time.Duration

	// KernelExperimental carries experimental, kernel-backend-only options that
	// have no equivalent on the default (Thrift) path — currently the richer TLS
	// surface (a trusted-CA bundle and an independent hostname-skip) the kernel
	// exposes over its C ABI. It lives here on Config, NOT on UserConfig, so it
	// stays off the stable exported/DSN surface (the same treatment TLSConfig and
	// ArrowConfig get). nil means no experimental option was set. The Thrift
	// backend rejects a non-nil value loudly; the kernel backend forwards it to
	// the kernel C ABI. Mirrors Node's non-exported InternalConnectionOptions /
	// Python's underscore-prefixed kwargs.
	KernelExperimental *KernelExperimentalConfig
}

type ConfigValue[T any] struct {
	// contains filtered or unexported fields
}

type KernelExperimentalConfig struct {
	// TLSTrustedCertsPEM is a PEM CA bundle added to the kernel's trust store on
	// top of the system roots (maps to kernel_session_config_set_tls_trusted_certs).
	// Needed because the kernel's rustls stack ignores SSL_CERT_FILE, so a custom
	// CA must be handed to the kernel explicitly.
	TLSTrustedCertsPEM []byte
	// TLSClientCertPEM / TLSClientKeyPEM are the paired mTLS client identity
	// forwarded through kernel_session_config_set_tls_client_certificate.
	// TLSClientCertConfigured distinguishes an explicit call with empty values
	// from the option never being set, so invalid input cannot fail open.
	TLSClientCertPEM        []byte
	TLSClientKeyPEM         []byte
	TLSClientCertConfigured bool
	// TLSSkipHostnameVerify skips only the certificate hostname check, independent
	// of the blanket InsecureSkipVerify (which relaxes both chain and hostname).
	// Maps to kernel_session_config_set_tls_skip_hostname_verification.
	TLSSkipHostnameVerify bool

	// ProxyURL / ProxyUsername / ProxyPassword / ProxyBypassHosts configure an
	// explicit HTTP proxy on the kernel path (WithKernelProxy), overriding the
	// HTTP(S)_PROXY / NO_PROXY environment the driver otherwise mirrors. The
	// credentials and bypass list are the "advanced" fields the env-var path
	// can't express (a structured no-proxy list, out-of-band basic auth). Empty
	// ProxyURL leaves the environment-derived proxy in effect. Maps to
	// kernel_session_config_set_proxy(url, username, password, bypass_hosts).
	ProxyURL         string
	ProxyUsername    string
	ProxyPassword    string
	ProxyBypassHosts string

	// RetryOverallTimeout is the cumulative retry budget across all attempts on
	// the kernel path (WithKernelRetryOverallTimeout). Zero = keep the kernel
	// default (900s). WithRetries only carries the per-attempt backoff bounds +
	// max attempts (mirroring the Thrift RetryWaitMin/Max/RetryMax surface); the
	// overall budget is a kernel-only knob the Thrift path has no equivalent for,
	// so it lives here and maps to the 4th arg of
	// kernel_session_config_set_retry_config (matching the pyo3/napi
	// retry_overall_timeout knob).
	RetryOverallTimeout time.Duration

	// MaxConnections is the maximum number of idle HTTP connections retained per
	// host by the kernel. Nil keeps the kernel default (100).
	MaxConnections *int

	// MaxChunksInMemory bounds how many decompressed CloudFetch chunks the kernel
	// holds in memory at once (WithKernelMaxChunksInMemory) — the knob that trades
	// throughput for peak RSS on large result sets. Zero = keep the kernel default
	// (16). A positive value is forwarded as the client-only
	// "cloudfetch_max_chunks_in_memory" session conf, which the kernel folds into
	// its result config and strips before the SEA wire; it is kernel-only because
	// the Thrift path has no such in-memory-chunk knob.
	MaxChunksInMemory int

	// DecimalAsFloat scans top-level DECIMAL columns to a lossy float64 instead of
	// the exact string (WithKernelDecimalAsFloat). Kernel-only; off by default.
	DecimalAsFloat bool

	// TokenCacheEnabled controls the kernel's on-disk OAuth U2M token-cache persistence
	// (WithTokenCache). 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 setting. Maps to
	// kernel_session_config_set_u2m_token_cache_config; a nil KernelExperimental or
	// false TokenCacheEnabled calls the setter with enabled=false so the kernel does
	// NOT persist to disk by default.
	TokenCacheEnabled bool

	// EnableGeoSpatialSupport selects the kernel's client-side GEOMETRY /
	// GEOGRAPHY result representation. True requests the canonical
	// struct<srid,wkb> Arrow value; false requests WKT / EWKT strings. A pointer
	// distinguishes the omitted value (default false) from an explicit setting.
	EnableGeoSpatialSupport *bool
}

type ServerResolver[T any] interface {
	// Resolve fetches the configuration value from the server.
	// Returns the value and any error encountered.
	// On error, the config overlay will fall back to the default value.
	Resolve(ctx context.Context, host string, httpClient *http.Client) (T, error)
}

type UserConfig struct {
	Protocol       string
	Host           string // from databricks UI
	Port           int    // from databricks UI
	HTTPPath       string // from databricks UI
	Catalog        string
	Schema         string
	Authenticator  auth.Authenticator
	AccessToken    string        // from databricks UI
	MaxRows        int           // max rows per page
	QueryTimeout   time.Duration // Timeout passed to server for query processing
	UserAgentEntry string
	Location       *time.Location
	SessionParams  map[string]string
	RetryWaitMin   time.Duration
	RetryWaitMax   time.Duration
	RetryMax       int
	// Telemetry configuration
	// Uses config overlay pattern: client > server > default.
	// Unset = check server feature flag; explicitly true/false overrides the server.
	EnableTelemetry          ConfigValue[bool]
	TelemetryBatchSize       int           // 0 = use default (200)
	TelemetryFlushInterval   time.Duration // 0 = use default (30s)
	Transport                http.RoundTripper
	UseLz4Compression        bool
	EnableMetricViewMetadata bool
	// UseArrowNativeDecimalDSN is a DSN-only carrier for the useArrowNativeDecimal
	// parameter. The authoritative setting lives on ArrowConfig; ParseDSN records
	// the DSN value here (because it can only return a UserConfig) and the
	// connector copies it into Config.ArrowConfig.UseArrowNativeDecimal when it is
	// assembled. The name intentionally differs from ArrowConfig's field so the
	// promoted selector Config.UseArrowNativeDecimal stays unambiguous.
	UseArrowNativeDecimalDSN bool
	CloudFetchConfig
	// UseKernel selects the SEA-via-kernel backend instead of Thrift. See the
	// WithUseKernel connector option for the build requirements. DSN: useKernel=true.
	UseKernel bool
	// WarehouseID is the bare SQL warehouse id, used by the kernel backend (which
	// addresses a warehouse by id) in preference to HTTPPath. The Thrift backend
	// ignores it and routes by HTTPPath. DSN: warehouseId=<id>.
	WarehouseID string
	// TokenCacheEnabledDSN is a DSN-only carrier for the tokenCache parameter (U2M-only).
	// The authoritative setting lives on KernelExperimentalConfig; ParseDSN records the
	// DSN value here (because it can only return a UserConfig) and the connector copies
	// it into Config.KernelExperimental.TokenCacheEnabled when it is assembled. The name
	// intentionally differs from KernelExperimentalConfig's field so the setting stays
	// unambiguous. False by default; when true, enables on-disk token-cache persistence
	// for U2M OAuth. DSN: tokenCache=true.
	TokenCacheEnabledDSN bool
	// EnableGeoSpatialSupportDSN is a DSN-only carrier for
	// enableGeoSpatialSupport=true|false. Nil means omitted (the default is
	// false); the connector copies a present value into KernelExperimental.
	EnableGeoSpatialSupportDSN *bool
}