configclient

type Client struct {
	// contains filtered or unexported fields
}

type FlagPayload struct {
	Enabled   bool   `json:"enabled"`
	Value     string `json:"value"`
	UpdatedAt string `json:"updatedAt"`
}

type HTTPFallback struct {
	// BaseURL of central-config's HTTP API, e.g. http://central-config:8080.
	BaseURL string

	// Token is the bearer credential sent on every fallback request. It must be
	// scoped to the client's environment: the API answers a read outside a
	// token's scope with 404, the same as a row that does not exist.
	//
	// It is a secret and is treated as one — it is never logged, never put in
	// an error message and never reported by Status.
	Token string

	// AllowUnauthenticated sends the fallback requests with no Authorization
	// header. It is for a deployment running with auth switched off, which is a
	// dev-only mode the control plane warns about at startup. Setting it
	// anywhere else converts a boot-time configuration error into a 401
	// discovered on the day JetStream is already down.
	AllowUnauthenticated bool

	// Timeout for the whole hydration pass. Defaults to 5s.
	Timeout time.Duration

	// HTTPClient overrides the default client (tests, custom transports).
	HTTPClient *http.Client

	// ConfigValueID is the /configs/values/{id} row id holding this service's
	// appsettings. Required to fall back for SERVICESETTINGS.
	ConfigValueID int64

	// FlagValueIDs maps flag key -> /flags/values/{id} row id, for the flags
	// this service actually reads. Required to fall back for FLAGS.
	FlagValueIDs map[string]int64

	// Locales this service serves, e.g. []string{"en-US", "pt-BR"}. Required
	// to fall back for LOCALIZATION, and only usable on a client scoped with
	// Options.MicroserviceID (the endpoint is keyed by microservice).
	Locales []string
}

type Options struct {
	NATSURL       string // required, e.g. nats://nats:4222
	NATSCreds     string // optional path to a .creds file
	EnvironmentID int64  // required, the environment this service runs in

	// MicroserviceID is the service this client runs inside. When set, the
	// client watches only "{env}.{id}" on SERVICESETTINGS and "{env}.{id}.>" on
	// LOCALIZATION, so its memory grows with its own config rather than with
	// the size of the fleet. FLAGS is still watched env-wide because flags are
	// shared across services.
	//
	// Leaving it at 0 selects a fleet-wide watch: every service's appsettings
	// and every locale bundle in the environment. That is a deliberate escape
	// hatch for diagnostic consumers (the test console, admin views) that
	// genuinely want to observe the whole environment — it is the wrong setting
	// for a normal service, and Status().FleetWide reports it so the choice is
	// visible rather than silent. It is the zero value because the field is
	// optional, not because it is the setting to reach for.
	//
	// When it is set, ServiceSettings and Translate for any *other* microservice
	// return false (that data is not watched) and increment
	// Status().OutOfScopeReads, so an out-of-scope read shows up as a reported
	// mistake instead of an empty result that looks like "no config yet".
	MicroserviceID int64

	// HTTPFallback, if set, hydrates the cache from central-config's HTTP API
	// when JetStream is unreachable at boot or a scoped key is missing from KV.
	// Optional and boot-only; see HTTPFallback for its limits. It carries its
	// own credential and New rejects one that cannot work, whether or not the
	// fallback ends up being needed.
	HTTPFallback *HTTPFallback

	// Logger, if set, receives the client's diagnostics: watch failures, the
	// fallback being used, a malformed payload. It is optional on purpose —
	// this is a library, and a library that logs by default is a library that
	// prints into somebody else's log stream. Unset means silent, with the same
	// information still available through Status().
	Logger *slog.Logger

	// OnChange, if set, is called after each applied KV update: during the
	// initial snapshot and for every later push. bucket is FLAGS, SERVICESETTINGS
	// or LOCALIZATION; key is the full KV key; value is nil for a delete.
	// It runs on the watcher goroutine, so it must not block.
	//
	// Delivery is at-least-once, and a delivery does not mean the value
	// changed. The same value arrives again whenever the watcher reconnects
	// (the ordered consumer replays the current value of every watched key) and
	// whenever the control plane genuinely republishes it. Handlers must
	// therefore be idempotent: doing real work per call — rebuilding an HTTP
	// client, resetting a log level, invalidating a cache — must be safe to
	// repeat with an unchanged value. Compare against what you already hold if
	// the work is expensive.
	OnChange func(bucket, key string, value []byte)
}

type Snapshot struct {
	EnvironmentID   int64                                `json:"environmentId"`
	Flags           map[string]FlagPayload               `json:"flags"`
	ServiceSettings map[int64]json.RawMessage            `json:"serviceSettings"`
	Localization    map[int64]map[string]json.RawMessage `json:"localization"`
}

type Status struct {
	EnvironmentID    int64  `json:"environmentId"`
	MicroserviceID   int64  `json:"microserviceId"` // 0 when fleet-wide
	FleetWide        bool   `json:"fleetWide"`      // watching every service's config
	Connected        bool   `json:"connected"`      // NATS connection is up right now
	Watching         bool   `json:"watching"`       // KV watchers are running
	UsedHTTPFallback bool   `json:"usedHttpFallback"`
	LastUpdate       string `json:"lastUpdate,omitempty"` // RFC3339 of the last applied KV entry
	StaleFor         string `json:"staleFor,omitempty"`   // time since that update
	LastError        string `json:"lastError,omitempty"`
	OutOfScopeReads  int64  `json:"outOfScopeReads"`
	Counts           struct {
		Flags           int `json:"flags"`
		ServiceSettings int `json:"serviceSettings"`
		Localization    int `json:"localization"`
	} `json:"counts"`
}