fix: set library-friendly defaults on server Config (#3156)

## Changes

* Add `default:"..."` tags for scalar `Config` fields whose CLI flag
  default in `pkg/cmd/serve.go` is non-zero.

Closes #2502

---------

Co-authored-by: Maria Ines Parnisari <maria.ines.parnisari@authzed.com>

Author: ivanauth

CHANGELOG.md

@@ -21,6 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Tracing: When server is shutting down, flush traces. Also, elide the need for setting `OTEL_EXPORTER_OTLP_ENDPOINT`. (https://github.com/authzed/spicedb/pull/3108)
 - Fixed a LookupSubjects issue in the query planner around the handling of wildcards in compound permissions (https://github.com/authzed/spicedb/pull/3140)
 - MySQL: identifiers (object/subject IDs and relationship counter names) are now stored with a case-sensitive (binary) collation, matching the Postgres, CockroachDB, and Spanner datastores. Previously, identifiers differing only in letter case (e.g. `Foo` and `foo`) incorrectly collided in unique indexes and lookups. ⚠️ The migration rebuilds the `relation_tuple` table in place via `ALTER TABLE`, which can hold a metadata/table lock for a long time on large datasets — run the upgrade in a low-traffic window, or apply it with an online schema-change tool (e.g. gh-ost). (https://github.com/authzed/spicedb/pull/3161)
+- `server.NewConfigWithOptionsAndDefaults` now populates `Config` and its embedded structs with the same defaults as the CLI flags, fixing zero-value behavior when embedding SpiceDB as a library. (https://github.com/authzed/spicedb/pull/3156)
 
 ## [1.53.0] - 2026-05-13
 ### Added

internal/services/integrationtesting/certtest/cert_test.go

@@ -126,7 +126,7 @@ func TestCertRotation(t *testing.T) {
 	require.NoError(t, err)
 
 	ctx, cancel := context.WithCancel(t.Context())
-	srv, err := server.NewConfigWithOptionsAndDefaults(
+	cfg := server.NewConfigWithOptionsAndDefaults(
 		server.WithDatastore(ds),
 		server.WithDispatcher(dispatcher),
 		server.WithDispatchMaxDepth(50),
@@ -183,7 +183,17 @@ func TestCertRotation(t *testing.T) {
 				},
 			},
 		}),
-	).Complete(ctx)
+	)
+	// Disable caches and their metrics to avoid "duplicate metrics" errors
+	cfg.DispatchClusterMetricsEnabled = false
+	cfg.DispatchClientMetricsEnabled = false
+	cfg.DatastoreConfig.EnableDatastoreMetrics = false
+	cfg.NamespaceCacheConfig = server.CacheConfig{}
+	cfg.DispatchCacheConfig = server.CacheConfig{}
+	cfg.ClusterDispatchCacheConfig = server.CacheConfig{}
+	cfg.LR3ResourceChunkCacheConfig = server.CacheConfig{}
+	cfg.StoredSchemaCacheConfig = server.CacheConfig{}
+	srv, err := cfg.Complete(ctx)
 	require.NoError(t, err)
 
 	wait := make(chan error, 1)

internal/services/v1/experimental_test.go

@@ -157,7 +157,7 @@ func TestBulkExportRelationshipsBeyondAllowedLimit(t *testing.T) {
 
 	_, err = resp.Recv()
 	require.Error(err)
-	require.Contains(err.Error(), "provided limit 10000005 is greater than maximum allowed of 100000")
+	require.Contains(err.Error(), "provided limit 10000005 is greater than maximum allowed of 10000")
 }
 
 func TestBulkExportRelationships(t *testing.T) {

internal/services/v1/permissions_test.go

@@ -736,6 +736,9 @@ func TestCheckPermissionWithDebugInfoInError(t *testing.T) {
 }
 
 func TestLookupResources(t *testing.T) {
+	t.Cleanup(func() {
+		goleak.VerifyNone(t, testutil.GoLeakIgnores()...)
+	})
 	testCases := []struct {
 		objectType           string
 		permission           string
@@ -920,9 +923,9 @@ func TestLookupResources(t *testing.T) {
 								tf.StandardDatastoreWithData,
 							)
 							client := v1.NewPermissionsServiceClient(conn)
-							defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
-							defer cleanup()
-
+							t.Cleanup(func() {
+								cleanup()
+							})
 							var trailer metadata.MD
 							lookupClient, err := client.LookupResources(t.Context(), &v1.LookupResourcesRequest{
 								ResourceObjectType: tc.objectType,
@@ -2469,7 +2472,7 @@ func TestExportBulkRelationshipsBeyondAllowedLimit(t *testing.T) {
 
 	_, err = resp.Recv()
 	require.Error(err)
-	require.Contains(err.Error(), "provided limit 10000005 is greater than maximum allowed of 100000")
+	require.Contains(err.Error(), "provided limit 10000005 is greater than maximum allowed of 10000")
 }
 
 func TestExportBulkRelationships(t *testing.T) {

internal/services/v1/relationships.go

@@ -158,7 +158,7 @@ func NewPermissionsServer(
 		MaxReadRelationshipsLimit:          defaultIfZero(config.MaxReadRelationshipsLimit, 1_000),
 		MaxDeleteRelationshipsLimit:        defaultIfZero(config.MaxDeleteRelationshipsLimit, 1_000),
 		MaxLookupResourcesLimit:            defaultIfZero(config.MaxLookupResourcesLimit, 1_000),
-		MaxBulkExportRelationshipsLimit:    defaultIfZero(config.MaxBulkExportRelationshipsLimit, 100_000),
+		MaxBulkExportRelationshipsLimit:    defaultIfZero(config.MaxBulkExportRelationshipsLimit, 10_000),
 		DispatchChunkSize:                  defaultIfZero(config.DispatchChunkSize, 100),
 		MaxCheckBulkConcurrency:            defaultIfZero(config.MaxCheckBulkConcurrency, 50),
 		CaveatTypeSet:                      caveattypes.TypeSetOrDefault(config.CaveatTypeSet),

internal/testserver/cluster.go

@@ -229,6 +229,15 @@ func TestClusterWithDispatch(t testing.TB, size uint, ds datastore.Datastore, ad
 
 		ctx, cancel := context.WithCancel(t.Context())
 		cfg := server.NewConfigWithOptionsAndDefaults(serverOptions...)
+		// Disable caches and their metrics to avoid "duplicate metrics" errors
+		cfg.DispatchClusterMetricsEnabled = false
+		cfg.DispatchClientMetricsEnabled = false
+		cfg.DatastoreConfig.EnableDatastoreMetrics = false
+		cfg.NamespaceCacheConfig = server.CacheConfig{}
+		cfg.DispatchCacheConfig = server.CacheConfig{}
+		cfg.ClusterDispatchCacheConfig = server.CacheConfig{}
+		cfg.LR3ResourceChunkCacheConfig = server.CacheConfig{}
+		cfg.StoredSchemaCacheConfig = server.CacheConfig{}
 		srv, listeners, err := cfg.CompleteForTesting(ctx)
 		require.NoError(t, err)
 

internal/testserver/server.go

@@ -95,7 +95,7 @@ func NewTestServerWithConfigAndDatastore(t testing.TB,
 	dispatcher, err := graph.NewLocalOnlyDispatcher(params)
 	require.NoError(t, err)
 
-	srv, err := server.NewConfigWithOptionsAndDefaults(
+	cfg := server.NewConfigWithOptionsAndDefaults(
 		server.WithDatastore(ds),
 		server.WithDispatcher(dispatcher),
 		server.WithQueryPlanMetadata(queryPlanMetadata),
@@ -163,7 +163,21 @@ func NewTestServerWithConfigAndDatastore(t testing.TB,
 				},
 			},
 		}),
-	).Complete(ctx)
+	)
+	// Disable all caching and metrics so test servers retain their pre-PR
+	// behavior. The new library defaults enable real caches (matching CLI),
+	// which (a) break parallel subtests by registering duplicate metrics
+	// with prometheus.DefaultRegisterer and (b) can affect test semantics
+	// by introducing caching where there was previously a NoopCache.
+	cfg.DispatchClusterMetricsEnabled = false
+	cfg.DispatchClientMetricsEnabled = false
+	cfg.DatastoreConfig.EnableDatastoreMetrics = false
+	cfg.NamespaceCacheConfig = server.CacheConfig{}
+	cfg.DispatchCacheConfig = server.CacheConfig{}
+	cfg.ClusterDispatchCacheConfig = server.CacheConfig{}
+	cfg.LR3ResourceChunkCacheConfig = server.CacheConfig{}
+	cfg.StoredSchemaCacheConfig = server.CacheConfig{}
+	srv, err := cfg.Complete(ctx)
 	require.NoError(t, err)
 
 	go func() {

pkg/cmd/datastore/datastore.go

@@ -52,12 +52,12 @@ var BuilderForEngine = map[string]engineBuilderFunc{
 
 //go:generate go run github.com/ecordell/optgen -output zz_generated.connpool.options.go . ConnPoolConfig
 type ConnPoolConfig struct {
-	MaxIdleTime         time.Duration `debugmap:"visible"`
-	MaxLifetime         time.Duration `debugmap:"visible"`
+	MaxIdleTime         time.Duration `debugmap:"visible" default:"30m"`
+	MaxLifetime         time.Duration `debugmap:"visible" default:"30m"`
 	MaxLifetimeJitter   time.Duration `debugmap:"visible"`
 	MaxOpenConns        int           `debugmap:"visible"`
 	MinOpenConns        int           `debugmap:"visible"`
-	HealthCheckInterval time.Duration `debugmap:"visible"`
+	HealthCheckInterval time.Duration `debugmap:"visible" default:"30s"`
 }
 
 func DefaultReadConnPool() *ConnPoolConfig {
@@ -104,20 +104,20 @@ func deprecateUnifiedConnFlags(flagSet *pflag.FlagSet) {
 
 //go:generate go run github.com/ecordell/optgen -sensitive-field-name-matches uri,secure -output zz_generated.options.go . Config
 type Config struct {
-	Engine                      string        `debugmap:"visible"`
+	Engine                      string        `debugmap:"visible"   default:"memory"`
 	URI                         string        `debugmap:"sensitive"`
-	GCWindow                    time.Duration `debugmap:"visible"`
-	LegacyFuzzing               time.Duration `debugmap:"visible"`
-	RevisionQuantization        time.Duration `debugmap:"visible"`
-	MaxRevisionStalenessPercent float64       `debugmap:"visible"`
+	GCWindow                    time.Duration `debugmap:"visible"   default:"24h"`
+	LegacyFuzzing               time.Duration `debugmap:"visible"   default:"-1ns"`
+	RevisionQuantization        time.Duration `debugmap:"visible"   default:"5s"`
+	MaxRevisionStalenessPercent float64       `debugmap:"visible"   default:"0.1"`
 	CredentialsProviderName     string        `debugmap:"visible"`
 	FilterMaximumIDCount        uint16        `debugmap:"hidden"    default:"100"`
 
 	// Options
 	ReadConnPool                   ConnPoolConfig `debugmap:"visible"`
 	WriteConnPool                  ConnPoolConfig `debugmap:"visible"`
 	ReadOnly                       bool           `debugmap:"visible"`
-	EnableDatastoreMetrics         bool           `debugmap:"visible"`
+	EnableDatastoreMetrics         bool           `debugmap:"visible" default:"true"`
 	DisableStats                   bool           `debugmap:"visible"`
 	IncludeQueryParametersInTraces bool           `debugmap:"visible"`
 
@@ -132,7 +132,7 @@ type Config struct {
 	BootstrapFiles        []string             `debugmap:"visible-format"`
 	BootstrapFileContents map[string][]byte    `debugmap:"visible"`
 	BootstrapOverwrite    bool                 `debugmap:"visible"`
-	BootstrapTimeout      time.Duration        `debugmap:"visible"`
+	BootstrapTimeout      time.Duration        `debugmap:"visible"        default:"10s"`
 	CaveatTypeSet         *caveattypes.TypeSet `debugmap:"hidden"`
 
 	// Hedging
@@ -142,17 +142,17 @@ type Config struct {
 	RequestHedgingQuantile         float64       `debugmap:"visible"`
 
 	// CRDB
-	FollowerReadDelay         time.Duration `debugmap:"visible"`
-	MaxRetries                int           `debugmap:"visible"`
-	OverlapKey                string        `debugmap:"visible"`
-	OverlapStrategy           string        `debugmap:"visible"`
-	EnableConnectionBalancing bool          `debugmap:"visible"`
-	ConnectRate               time.Duration `debugmap:"visible"`
-	WriteAcquisitionTimeout   time.Duration `debugmap:"visible"`
+	FollowerReadDelay         time.Duration `debugmap:"visible" default:"4800ms"`
+	MaxRetries                int           `debugmap:"visible" default:"10"`
+	OverlapKey                string        `debugmap:"visible" default:"key"`
+	OverlapStrategy           string        `debugmap:"visible" default:"static"`
+	EnableConnectionBalancing bool          `debugmap:"visible" default:"true"`
+	ConnectRate               time.Duration `debugmap:"visible" default:"100ms"`
+	WriteAcquisitionTimeout   time.Duration `debugmap:"visible" default:"30ms"`
 
 	// Postgres
-	GCInterval            time.Duration `debugmap:"visible"`
-	GCMaxOperationTime    time.Duration `debugmap:"visible"`
+	GCInterval            time.Duration `debugmap:"visible" default:"3m"`
+	GCMaxOperationTime    time.Duration `debugmap:"visible" default:"1m"`
 	RelaxedIsolationLevel bool          `debugmap:"visible"`
 
 	// Spanner
@@ -168,9 +168,9 @@ type Config struct {
 	// https://docs.cloud.google.com/docs/authentication/client-libraries#adc
 	SpannerCredentialsJSON        []byte `debugmap:"sensitive"`
 	SpannerEmulatorHost           string `debugmap:"visible"`
-	SpannerMinSessions            uint64 `debugmap:"visible"`
-	SpannerMaxSessions            uint64 `debugmap:"visible"`
-	SpannerDatastoreMetricsOption string `debugmap:"visible"`
+	SpannerMinSessions            uint64 `debugmap:"visible"   default:"100"`
+	SpannerMaxSessions            uint64 `debugmap:"visible"   default:"400"`
+	SpannerDatastoreMetricsOption string `debugmap:"visible"   default:"otel"`
 
 	// MySQL
 	TablePrefix string `debugmap:"visible"`
@@ -181,21 +181,56 @@ type Config struct {
 	RelationshipIntegrityExpiredKeys []string        `debugmap:"visible"`
 
 	// Internal
-	WatchBufferLength            uint16        `debugmap:"visible"`
-	WatchChangeBufferMaximumSize string        `debugmap:"visible"`
-	WatchBufferWriteTimeout      time.Duration `debugmap:"visible"`
-	WatchConnectTimeout          time.Duration `debugmap:"visible"`
+	WatchBufferLength            uint16        `debugmap:"visible" default:"1024"`
+	WatchChangeBufferMaximumSize string        `debugmap:"visible" default:"15%"`
+	WatchBufferWriteTimeout      time.Duration `debugmap:"visible" default:"1s"`
+	WatchConnectTimeout          time.Duration `debugmap:"visible" default:"1s"`
 	DisableWatchSupport          bool          `debugmap:"hidden"`
 
 	// Migrations
 	MigrationPhase    string   `debugmap:"visible"`
 	AllowedMigrations []string `debugmap:"visible"`
 
 	// Experimental
-	ExperimentalColumnOptimization bool `debugmap:"visible"`
+	ExperimentalColumnOptimization bool `debugmap:"visible" default:"true"`
 	EnableRevisionHeartbeat        bool `debugmap:"visible"`
 }
 
+// SetDefaults is invoked by github.com/creasty/defaults after struct-tag
+// defaults are applied. It fills the four ConnPoolConfig slots from the
+// canonical DefaultReadConnPool / DefaultWriteConnPool constructors because
+// each slot receives a different default set from RegisterConnPoolFlagsWithPrefix
+// in RegisterDatastoreFlagsWithPrefix (Read pools = 20/20 conns, Write = 10/10).
+// It also pre-allocates slice fields to empty (non-nil) values so the
+// resulting Config matches what RegisterDatastoreFlags writes via
+// StringSliceVar/StringArrayVar.
+func (c *Config) SetDefaults() {
+	c.ReadConnPool = *DefaultReadConnPool()
+	c.WriteConnPool = *DefaultWriteConnPool()
+	c.ReadReplicaConnPool = *DefaultReadConnPool()
+	c.OldReadReplicaConnPool = *DefaultReadConnPool()
+
+	// CaveatTypeSet is hidden from DebugMap but RegisterDatastoreFlags
+	// initializes it from DefaultDatastoreConfig at line 223. Mirror that
+	// here so library users get the same value as CLI users.
+	if c.CaveatTypeSet == nil {
+		c.CaveatTypeSet = caveattypes.Default.TypeSet
+	}
+
+	if c.BootstrapFiles == nil {
+		c.BootstrapFiles = []string{}
+	}
+	if c.ReadReplicaURIs == nil {
+		c.ReadReplicaURIs = []string{}
+	}
+	if c.AllowedMigrations == nil {
+		c.AllowedMigrations = []string{}
+	}
+	if c.RelationshipIntegrityExpiredKeys == nil {
+		c.RelationshipIntegrityExpiredKeys = []string{}
+	}
+}
+
 //go:generate go run github.com/ecordell/optgen -sensitive-field-name-matches uri,secure -output zz_generated.relintegritykey.options.go . RelIntegrityKey
 type RelIntegrityKey struct {
 	KeyID       string `debugmap:"visible"`

pkg/cmd/serve_test.go

@@ -74,6 +74,23 @@ func restoreEnv(prevEnv []string) {
 	}
 }
 
+// TestConfigDefaultsMatchCLIFlags asserts that NewConfigWithOptionsAndDefaults
+// (the library entry point) produces the same Config as RegisterServeFlags
+// (the CLI entry point). Any drift is a bug: a new flag or a new struct field
+// added without a matching default tag/SetDefaults hook will be caught here.
+//
+// pflag writes each flag's default into the bound destination at registration
+// time, so RegisterServeFlags alone (no ParseFlags call) is enough to fully
+// populate cliCfg with the CLI defaults.
+func TestConfigDefaultsMatchCLIFlags(t *testing.T) {
+	cliCfg := &server.Config{}
+	require.NoError(t, RegisterServeFlags(&cobra.Command{}, cliCfg))
+
+	libCfg := server.NewConfigWithOptionsAndDefaults()
+
+	require.Equal(t, cliCfg.DebugMap(), libCfg.DebugMap())
+}
+
 func TestDefaultConfig(t *testing.T) {
 	flags := []string{
 		"--grpc-preshared-key", "some_key",

pkg/cmd/server/otel.go

@@ -30,12 +30,12 @@ type otelShutdowner interface {
 }
 
 type OTelConfig struct {
-	Provider        string  `debugmap:"visible"`
+	Provider        string  `debugmap:"visible" default:"none"`
 	Endpoint        string  `debugmap:"visible"`
-	ServiceName     string  `debugmap:"visible"`
-	TracePropagator string  `debugmap:"visible"`
+	ServiceName     string  `debugmap:"visible" default:"spicedb"`
+	TracePropagator string  `debugmap:"visible" default:"w3c"`
 	UsePlaintext    bool    `debugmap:"visible"`
-	SampleRatio     float64 `debugmap:"visible"`
+	SampleRatio     float64 `debugmap:"visible" default:"0.01"`
 }
 
 // RegisterOTelFlags registers all OpenTelemetry flags on cmd, binding them directly into cfg.