datasource

type CacheFetchProbe interface {
	CacheHit()
	CacheMiss()
	CacheExpired()
	FetchFailed(err error)
	End()
}

type CacheObserver interface {
	// CacheFetchStarted is called when a cache fetch begins.
	// Returns a potentially modified context and a probe to track the operation.
	CacheFetchStarted(ctx context.Context, dataSourceName string) (context.Context, CacheFetchProbe)
}

type CacheableLuaDataSource struct {
	*LuaDataSource
}

type CacheableLuaDataSourceConfig struct {
	// Name identifies this data source
	Name string

	// Script is the Lua script to execute
	//
	// The script should define a function called 'fetch' that takes an input table
	// and returns a result table with 'data' and 'content_type' fields
	//
	// The script must define fetch_cache_key(input), which returns a modified input
	// table with only the fields relevant for caching. Return nil to skip the cache
	// (no read, no write) for that request.
	//
	// Example:
	//   function fetch_cache_key(input)
	//     return {subject = {subject = input.subject.subject}}
	//   end
	Script string

	// ConfigSource provides configuration values available to the script via config.get()
	// If nil, an empty MapConfigSource will be used
	ConfigSource luaservices.ConfigSource

	// HTTP bundles the client and optional base URL for relative Lua URLs.
	HTTP httpclient.LuaClient

	// RequestOptions is a programmatic hook that augments outgoing HTTP requests. Optional.
	RequestOptions luaservices.RequestOptions

	// Observer for Lua-specific execution events on the inner Lua data source.
	// If nil, NewLuaDataSource substitutes NoOpDataSourceObserver{}.
	Observer LuaObserver
}

type DataSourceObserver interface {
	CacheObserver
	LuaObserver
}

type DistributedCachingConfig struct {
	// GroupName is the name for this groupcache group
	// Should be unique per data source type
	GroupName string

	// CacheSizeBytes is the maximum size of the cache in bytes
	// Default: 64MB
	CacheSizeBytes int64

	// Clock provides the current time for TTL bucketing.
	// Default: system clock.
	Clock clock.Clock

	// CacheTTL is the time-to-live for cached entries.
	// 0 means no TTL-based expiration (cache indefinitely).
	CacheTTL time.Duration
}

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

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

type InMemoryCachingDataSourceOption func(*InMemoryCachingDataSource)

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

type LuaDataSourceConfig struct {
	// Name identifies this data source
	Name string

	// Script is the Lua script to execute
	// The script should define a function called 'fetch' that takes an input table
	// and returns a result table with 'data' and 'content_type' fields
	//
	// Example:
	//   function fetch(input)
	//     local response = http.get("https://api.example.com/user/" .. input.subject.subject)
	//     if response.status == 200 then
	//       return {data = response.body, content_type = "application/json"}
	//     end
	//     return nil
	//   end
	Script string

	// ConfigSource provides configuration values available to the script via config.get()
	// If nil, an empty MapConfigSource will be used
	ConfigSource luaservices.ConfigSource

	// HTTP bundles the client and optional base URL for relative Lua URLs.
	// Zero value uses [http.DefaultClient] with absolute URLs only.
	HTTP httpclient.LuaClient

	// RequestOptions is a programmatic hook that augments outgoing HTTP requests
	// (e.g. injecting headers or query params from Go context). Optional.
	RequestOptions luaservices.RequestOptions

	// Observer for Lua-specific execution events. If nil, defaults to NoOpObserver.
	Observer LuaObserver
}

type LuaFetchProbe interface {
	ScriptLoadFailed(err error)
	ScriptExecutionFailed(err error)
	InvalidReturnType(got string)
	FetchCompleted()
	FetchCompletedNil()
	// FetchAudit is called when a script attaches optional audit metadata.
	FetchAudit(fields map[string]string)
	ResultConversionFailed(err error)
	End()
}

type LuaObserver interface {
	// LuaFetchStarted is called when a Lua fetch begins.
	// Returns a potentially modified context and a probe to track the operation.
	LuaFetchStarted(ctx context.Context, dataSourceName string) (context.Context, LuaFetchProbe)
}

type NoOpCacheFetchProbe struct{}

type NoOpCacheObserver struct{}

type NoOpDataSourceObserver struct {
	NoOpCacheObserver
	NoOpLuaObserver
}

type NoOpLuaFetchProbe struct{}

type NoOpLuaObserver struct{}

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