Add SetDefaultHostMetadataResolverFactory (#1636)

## Changes

[PR #1572](#1572)
added `Config.HostMetadataResolver` so callers could override the SDK's
`/.well-known/databricks-config` fetch on a per-Config basis. That
covers "I have one Config and I want to wrap it."

The gap: programs that construct many Configs across their command
surface (e.g. the Databricks CLI) end up copying the same
`cfg.HostMetadataResolver = ...` assignment at every construction site,
in the CLI roughly 10 sites across 7 files plus a guardrail test to
catch drift.

This PR adds a package-level default consulted when a Config has no
explicit resolver set. Callers set a factory once during startup; every
subsequent Config gets the same resolver without per-site wiring. The
Config-level field still takes precedence, so PR #1572's contract is
unchanged.

### API

```go
// config/host_metadata.go
var DefaultHostMetadataResolverFactory func(*Config) HostMetadataResolver
```

Plain public variable, set once at init. Matches the stdlib pattern for
single-default hooks: `http.DefaultClient`, `http.DefaultTransport`,
`log.Default`. Callers needing per-Config or dynamic behaviour should
use `Config.HostMetadataResolver` instead.

### Resolution order inside `Config.EnsureResolved`

1. If `Config.HostMetadataResolver` is set, use it.
2. Else, if `DefaultHostMetadataResolverFactory` is non-nil, invoke it
with the resolving Config and use its return value. If it returns nil,
fall through.
3. Else, SDK's default HTTP fetch (unchanged behavior for all existing
callers).

## How the Databricks CLI will use this

The canonical Go idiom for "library A registers itself with library B"
is a blank import that triggers an `init()` in A. This is how
`database/sql` drivers (`_ "github.com/lib/pq"`), image codecs (`_
"image/png"`), and encoding formats register themselves.

After this PR lands and is bumped into the CLI, [CLI PR
#5011](databricks/cli#5011) will collapse from
~10 wired-in `hostmetadata.Attach(cfg)` calls + a guardrail test down to
two small pieces:

**`repos/cli/libs/hostmetadata/resolver.go`** — set the caching factory
at package init:

```go
func init() {
    config.DefaultHostMetadataResolverFactory = func(cfg *config.Config) config.HostMetadataResolver {
        return NewResolver(cfg.DefaultHostMetadataResolver())
    }
}
```

**`repos/cli/cmd/databricks/main.go`** — one blank import to pull the
package in at startup:

```go
import (
    // Registers a disk-cached HostMetadataResolver with the SDK so every
    // Config the CLI constructs reuses the cached /.well-known lookup.
    _ "github.com/databricks/cli/libs/hostmetadata"
)
```

That's the full integration. Every Config the CLI creates, now and in
the future from any new command a developer adds, automatically gets
caching. No per-site `Attach` call to remember, no guardrail test to
maintain, no new developer ever has to learn this mechanism exists to
benefit from it.

### Experimental

Marked experimental to match the existing `HostMetadataResolver` field.
No default behavior change for callers that never set
`DefaultHostMetadataResolverFactory`.

## Tests

Three new tests in `config/config_test.go`, each using a small
`withDefaultHostMetadataResolverFactory(t, factory)` helper that
captures and restores the prior value, so tests never clobber each other
via the package-level default:

- Factory is invoked when Config has no resolver; back-fill works
end-to-end.
- Config-level resolver takes precedence (factory not consulted).
- Factory returning nil falls through to the SDK's HTTP fetch.

- `make fmt test lint` clean
- `go test ./config/... -count=1 -race` clean

Signed-off-by: simon <simon.faltum@databricks.com>

---------

Signed-off-by: simon <simon.faltum@databricks.com>
Co-authored-by: Renaud Hartert <renaud.hartert@databricks.com>

Author: simonfaltum

NEXT_CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### New Features and Improvements
 
+ * Add `config.DefaultHostMetadataResolverFactory`: a package-level variable consulted when `Config.HostMetadataResolver` is unset. Lets programs install a shared resolver (e.g. a caching one) once from an `init()` block (typically in a blank-imported package) instead of wiring per-Config. Experimental.
+
 ### Bug Fixes
 
  * Add `X-Databricks-Org-Id` header to `Workspace.Download()` and `Workspace.Upload()` for SPOG host compatibility.

config/config.go

@@ -701,10 +701,17 @@ func (c *Config) resolveHostMetadata(ctx context.Context) {
 		return
 	}
 
+	resolver := c.HostMetadataResolver
+	if resolver == nil {
+		if factory := DefaultHostMetadataResolverFactory; factory != nil {
+			resolver = factory(c)
+		}
+	}
+
 	var meta *HostMetadata
 	var err error
-	if c.HostMetadataResolver != nil {
-		meta, err = c.HostMetadataResolver(ctx, c.CanonicalHostName())
+	if resolver != nil {
+		meta, err = resolver(ctx, c.CanonicalHostName())
 	} else {
 		meta, err = getHostMetadata(ctx, c.CanonicalHostName(), c.refreshClient)
 	}

config/config_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/http"
 	"sync"
+	"sync/atomic"
 	"testing"
 
 	"github.com/databricks/databricks-sdk-go/common/environment"
@@ -1169,3 +1170,79 @@ func TestConfig_ResolveHostMetadata_HostTypes(t *testing.T) {
 		})
 	}
 }
+
+// withDefaultHostMetadataResolverFactory installs factory for the duration of
+// the current test, restoring whatever was previously set on cleanup.
+// Capture/set/restore are not atomic — do not use with t.Parallel across
+// multiple tests that touch the package-level default.
+func withDefaultHostMetadataResolverFactory(t *testing.T, factory func(*Config) HostMetadataResolver) {
+	t.Helper()
+	prev := DefaultHostMetadataResolverFactory
+	DefaultHostMetadataResolverFactory = factory
+	t.Cleanup(func() { DefaultHostMetadataResolverFactory = prev })
+}
+
+func TestDefaultHostMetadataResolverFactory_UsedWhenConfigHasNoResolver(t *testing.T) {
+	var factoryCalls atomic.Int32
+	withDefaultHostMetadataResolverFactory(t, func(c *Config) HostMetadataResolver {
+		factoryCalls.Add(1)
+		return func(ctx context.Context, host string) (*HostMetadata, error) {
+			return &HostMetadata{AccountID: testHMAccountID, WorkspaceID: testHMWorkspaceID}, nil
+		}
+	})
+
+	noopLoader := mockLoader(func(cfg *Config) error { return nil })
+	cfg := &Config{Host: testHMHost, Loaders: []Loader{noopLoader}}
+	require.NoError(t, cfg.EnsureResolved())
+
+	assert.Equal(t, int32(1), factoryCalls.Load(), "factory must be invoked exactly once per resolve")
+	assert.Equal(t, testHMAccountID, cfg.AccountID)
+	assert.Equal(t, testHMWorkspaceID, cfg.WorkspaceID)
+}
+
+func TestDefaultHostMetadataResolverFactory_PerConfigResolverTakesPrecedence(t *testing.T) {
+	var factoryCalls atomic.Int32
+	withDefaultHostMetadataResolverFactory(t, func(c *Config) HostMetadataResolver {
+		factoryCalls.Add(1)
+		return func(ctx context.Context, host string) (*HostMetadata, error) {
+			return &HostMetadata{AccountID: "factory-account"}, nil
+		}
+	})
+
+	noopLoader := mockLoader(func(cfg *Config) error { return nil })
+	cfg := &Config{
+		Host:    testHMHost,
+		Loaders: []Loader{noopLoader},
+		HostMetadataResolver: func(ctx context.Context, host string) (*HostMetadata, error) {
+			return &HostMetadata{AccountID: testHMAccountID}, nil
+		},
+	}
+	require.NoError(t, cfg.EnsureResolved())
+
+	assert.Equal(t, int32(0), factoryCalls.Load(), "factory must not be consulted when Config has its own resolver")
+	assert.Equal(t, testHMAccountID, cfg.AccountID)
+}
+
+func TestDefaultHostMetadataResolverFactory_NilResolverFromFactoryFallsThroughToHTTP(t *testing.T) {
+	withDefaultHostMetadataResolverFactory(t, func(c *Config) HostMetadataResolver {
+		return nil
+	})
+
+	noopLoader := mockLoader(func(cfg *Config) error { return nil })
+	cfg := &Config{
+		Host:    testHMHost,
+		Loaders: []Loader{noopLoader},
+		HTTPTransport: fixtures.SliceTransport{
+			{
+				Method:       "GET",
+				Resource:     "/.well-known/databricks-config",
+				ReuseRequest: true,
+				Status:       200,
+				Response:     `{"oidc_endpoint": "` + testHMHost + `/oidc", "account_id": "` + testHMAccountID + `"}`,
+			},
+		},
+	}
+	require.NoError(t, cfg.EnsureResolved())
+
+	assert.Equal(t, testHMAccountID, cfg.AccountID)
+}

config/host_metadata.go

@@ -38,6 +38,20 @@ type HostMetadata struct {
 // This allows callers to provide cached metadata without the SDK making an HTTP call.
 type HostMetadataResolver func(ctx context.Context, host string) (*HostMetadata, error)
 
+// DefaultHostMetadataResolverFactory is consulted by [Config.EnsureResolved]
+// when [Config.HostMetadataResolver] is nil. When set, the factory is invoked
+// with the resolving Config and must return the resolver to use for that
+// Config (or nil to fall through to the SDK's default HTTP fetch).
+//
+// Intended for programs that want a single hook to install a caching or
+// otherwise-customised resolver across every Config they construct, without
+// per-site wiring. Set once from an init() block in a package that is
+// blank-imported by the main binary. Callers needing a per-Config resolver
+// should use [Config.HostMetadataResolver] instead.
+//
+// Experimental: subject to change.
+var DefaultHostMetadataResolverFactory func(*Config) HostMetadataResolver
+
 // getHostMetadata fetches the raw Databricks well-known configuration from
 // {host}/.well-known/databricks-config. The returned HostMetadata contains
 // raw values with no substitution (e.g., {account_id} placeholders are left