config

type Config struct {
	Global          Global            `yaml:",omitempty"`       // Global contains global/shared exporter configuration settings.
	Log             Log               `yaml:"log"`              // Log holds configuration related to logging for the exporter.
	OpenTelemetry   OpenTelemetry     `yaml:"opentelemetry"`    // OpenTelemetry contains configuration settings for OpenTelemetry integration.
	Server          Server            `yaml:"server"`           // Server holds configuration related to the server settings.
	Gitlab          Gitlab            `yaml:"gitlab"`           // Gitlab contains GitLab-specific configuration settings.
	Redis           Redis             `yaml:"redis"`            // Redis holds configuration parameters for connecting to Redis.
	Pull            Pull              `yaml:"pull"`             // Pull contains configuration related to data pulling behavior.
	GarbageCollect  GarbageCollect    `yaml:"garbage_collect"`  // GarbageCollect contains configuration for garbage collection.
	ProjectDefaults ProjectParameters `yaml:"project_defaults"` // ProjectDefaults defines default project parameters which can be overridden at individual Project or Wildcard levels.

	// Projects is a list of specific projects to pull metrics from.
	// Validation: Must be unique, at least one project or wildcard must be provided, and each element is validated.
	Projects []Project `validate:"unique,at-least-1-project-or-wildcard,dive" yaml:"projects"`

	// Wildcards is a list of wildcard project definitions used to dynamically discover projects.
	// Validation: Must be unique, at least one project or wildcard must be provided, and each element is validated.
	Wildcards []Wildcard `validate:"unique,at-least-1-project-or-wildcard,dive" yaml:"wildcards"`
}

type Format uint8

type GarbageCollect struct {
	// Projects configures cleanup behavior related to projects.
	Projects struct {
		OnInit          bool `default:"false" yaml:"on_init"`                           // OnInit indicates if cleanup should run once at startup.
		Scheduled       bool `default:"true" yaml:"scheduled"`                          // Scheduled indicates if cleanup should run periodically.
		IntervalSeconds int  `default:"14400" validate:"gte=1" yaml:"interval_seconds"` // IntervalSeconds sets the interval in seconds between cleanup runs. 4 hours
	} `yaml:"projects"`

	// Environments configures cleanup behavior related to environments.
	Environments struct {
		OnInit          bool `default:"false" yaml:"on_init"`
		Scheduled       bool `default:"true" yaml:"scheduled"`
		IntervalSeconds int  `default:"14400" validate:"gte=1" yaml:"interval_seconds"` // 4 hours
	} `yaml:"environments"`

	// Runners configures cleanup behavior related to runners.
	Runners struct {
		OnInit          bool `default:"false" yaml:"on_init"`
		Scheduled       bool `default:"true" yaml:"scheduled"`
		IntervalSeconds int  `default:"14400" validate:"gte=1" yaml:"interval_seconds"`
	} `yaml:"runners"`

	// Refs configures cleanup behavior related to Git references (branches, tags, etc).
	Refs struct {
		OnInit          bool `default:"false" yaml:"on_init"`
		Scheduled       bool `default:"true" yaml:"scheduled"`
		IntervalSeconds int  `default:"1800" validate:"gte=1" yaml:"interval_seconds"` // 30 minutes
	} `yaml:"refs"`

	// Metrics configures cleanup behavior related to metrics data.
	Metrics struct {
		OnInit          bool `default:"false" yaml:"on_init"`
		Scheduled       bool `default:"true" yaml:"scheduled"`
		IntervalSeconds int  `default:"600" validate:"gte=1" yaml:"interval_seconds"` // 10 minutes
	} `yaml:"metrics"`
}

type Gitlab struct {
	// URL of the GitLab server or API endpoint.
	// Defaults to https://gitlab.com (the public GitLab instance).
	URL string `default:"https://gitlab.com" validate:"required,url" yaml:"url"`

	// HealthURL is the URL used to check if the GitLab server is reachable.
	// Defaults to a publicly accessible endpoint on gitlab.com.
	HealthURL string `default:"https://gitlab.com/explore" validate:"required,url" yaml:"health_url"`

	Token                      string `validate:"required" yaml:"token"`                                  // Token is the authentication token used to access the GitLab API.
	EnableHealthCheck          bool   `default:"true" yaml:"enable_health_check"`                         // EnableHealthCheck toggles periodic health checks by requesting the HealthURL.
	EnableTLSVerify            bool   `default:"true" yaml:"enable_tls_verify"`                           // EnableTLSVerify toggles TLS certificate verification for HTTPS connections to the HealthURL.
	MaximumRequestsPerSecond   int    `default:"5" validate:"gte=1" yaml:"maximum_requests_per_second"`   // MaximumRequestsPerSecond limits the maximum number of GitLab API requests per second.
	BurstableRequestsPerSecond int    `default:"5" validate:"gte=1" yaml:"burstable_requests_per_second"` // BurstableRequestsPerSecond allows short bursts above the normal max request rate.

	// MaximumJobsQueueSize limits the number of jobs queued internally before dropping new ones.
	// Recommended not to change unless you understand the implications.
	// Alternatives to hitting this limit include:
	// - Increasing polling intervals
	// - Increasing API rate limits
	// - Reducing number of monitored projects, refs, environments, or metrics
	// - Using webhooks instead of polling
	MaximumJobsQueueSize int `default:"1000" validate:"gte=10" yaml:"maximum_jobs_queue_size"`
}

type Global struct {
	// InternalMonitoringListenerAddress specifies the URL endpoint where internal
	// metrics and monitoring data of the exporter itself can be accessed.
	InternalMonitoringListenerAddress *url.URL
}

type Log struct {
	// Level sets the logging verbosity level.
	// Valid values: trace, debug, info, warning, error, fatal, panic.
	// Defaults to "info".
	Level string `default:"info" validate:"required,oneof=trace debug info warning error fatal panic"`

	// Format sets the output format of the logs.
	// Valid values: "text" or "json".
	// Defaults to "text".
	Format string `default:"text" validate:"oneof=text json"`
}

type OpenTelemetry struct {
	// GRPCEndpoint is the gRPC address of the OpenTelemetry collector to send traces/metrics to.
	GRPCEndpoint string `yaml:"grpc_endpoint"`
}

type Project struct {
	// ProjectParameters embeds configuration parameters specific to this project.
	ProjectParameters `yaml:",inline"`

	// Name represents the project identifier, commonly known as path_with_namespace in GitLab.
	Name string `yaml:"name"`
}

type ProjectParameters struct {
	// Pull contains detailed settings for what to pull related to projects (pipelines, refs, environments).
	Pull ProjectPull `yaml:"pull"`

	// OutputSparseStatusMetrics controls whether to export all pipeline/job statuses (false)
	// or only the last job's status (true).
	// Defaults to true for less verbose metrics output.
	OutputSparseStatusMetrics bool `default:"true" yaml:"output_sparse_status_metrics"`
}

type ProjectPull struct {
	Environments ProjectPullEnvironments `yaml:"environments"`
	Runners      ProjectPullRunners      `yaml:"runners"`
	Refs         ProjectPullRefs         `yaml:"refs"`
	Pipeline     ProjectPullPipeline     `yaml:"pipeline"`
}

type ProjectPullEnvironments struct {
	// Enabled controls whether environment and deployment metrics are pulled.
	// Defaults to false.
	Enabled bool `default:"false" yaml:"enabled"`

	// Regexp is a regex filter applied to environment names to select which environments to fetch.
	// Defaults to match all (".*").
	Regexp string `default:".*" yaml:"regexp"`

	// ExcludeStopped indicates if environments that are stopped should be excluded from metrics export.
	// Defaults to true.
	ExcludeStopped bool `default:"true" yaml:"exclude_stopped"`
}

type ProjectPullPipeline struct {
	// Jobs contains configuration related to pipeline jobs.
	Jobs ProjectPullPipelineJobs `yaml:"jobs"`

	// Variables controls pipeline variable fetching settings.
	Variables ProjectPullPipelineVariables `yaml:"variables"`

	// TestReports configures the collection of pipeline test reports.
	TestReports ProjectPullPipelineTestReports `yaml:"test_reports"`

	// PerRef Add multiple refs per pipelines
	PerRef uint `default:"1" yaml:"PerRef"`
}

type ProjectPullPipelineJobs struct {
	// Enabled toggles pulling metrics related to pipeline jobs.
	// Defaults to false.
	Enabled bool `default:"false" yaml:"enabled"`

	// FromChildPipelines configures pulling jobs from child or downstream pipelines.
	FromChildPipelines ProjectPullPipelineJobsFromChildPipelines `yaml:"from_child_pipelines"`

	// RunnerDescription configures whether to export the description of the runner
	// that executed the job.
	RunnerDescription ProjectPullPipelineJobsRunnerDescription `yaml:"runner_description"`
}

type ProjectPullPipelineJobsFromChildPipelines struct {
	// Enabled toggles whether to pull pipeline jobs from child or downstream pipelines.
	// Defaults to true.
	Enabled bool `default:"true" yaml:"enabled"`
}

type ProjectPullPipelineJobsRunnerDescription struct {
	// Enabled toggles whether to export the description of the runner that executed the job.
	// Defaults to true.
	Enabled bool `default:"true" yaml:"enabled"`

	// AggregationRegexp is a regex to reduce cardinality by aggregating runner descriptions.
	// For example, it can extract a numeric identifier from a hostname pattern.
	// Defaults to "shared-runners-manager-(\d*)\.gitlab\.com"
	AggregationRegexp string `default:"shared-runners-manager-(\\d*)\\.gitlab\\.com" yaml:"aggregation_regexp"`
}

type ProjectPullPipelineTestReports struct {
	// Enabled toggles whether to attempt retrieving test reports included in the pipeline.
	// Defaults to false.
	Enabled bool `default:"false" yaml:"enabled"`

	// FromChildPipelines configures whether to pull test reports from child/downstream pipelines.
	FromChildPipelines ProjectPullPipelineTestReportsFromChildPipelines `yaml:"from_child_pipelines"`

	// TestCases configures fetching details about individual test cases within the test reports.
	TestCases ProjectPullPipelineTestReportsTestCases `yaml:"test_cases"`
}

type ProjectPullPipelineTestReportsFromChildPipelines struct {
	// Enabled toggles whether to pull test reports from child/downstream pipelines.
	// Defaults to false.
	Enabled bool `default:"false" yaml:"enabled"`
}

type ProjectPullPipelineTestReportsTestCases struct {
	// Enabled toggles whether to attempt retrieving individual test case information
	// from the pipeline test report.
	// Defaults to false.
	Enabled bool `default:"false" yaml:"enabled"`
}

type ProjectPullPipelineVariables struct {
	// Enabled toggles whether to fetch variables included in the pipeline.
	// Defaults to false.
	Enabled bool `default:"false" yaml:"enabled"`

	// Regexp filters pipeline variable values by regex to control which variables are fetched.
	// Defaults to match all (".*").
	Regexp string `default:".*" yaml:"regexp"`
}

type ProjectPullRefs struct {
	Branches      ProjectPullRefsBranches      `yaml:"branches"`
	Tags          ProjectPullRefsTags          `yaml:"tags"`
	MergeRequests ProjectPullRefsMergeRequests `yaml:"merge_requests"`
}

type ProjectPullRefsBranches struct {
	// Enabled toggles whether branch pipelines are monitored.
	// Defaults to true.
	Enabled bool `default:"true" yaml:"enabled"`

	// Regexp filters branches to include by name using regex.
	// Default includes only "main" or "master" branches.
	Regexp string `default:"^(?:main|master)$" yaml:"regexp"`

	// MostRecent limits exported branches to the N most recently updated.
	// If zero, no limit is applied.
	MostRecent uint `default:"0" yaml:"most_recent"`

	// MaxAgeSeconds prevents exporting metrics for branches whose latest pipeline
	// update is older than this age in seconds. Zero means no age limit.
	MaxAgeSeconds uint `default:"0" yaml:"max_age_seconds"`

	// ExcludeDeleted indicates whether to skip branches marked as deleted.
	// Defaults to true.
	ExcludeDeleted bool `default:"true" yaml:"exclude_deleted"`
}

type ProjectPullRefsMergeRequests struct {
	// Enabled toggles whether pipeline metrics for merge requests are monitored.
	// No default is specified, so it must be explicitly set.
	Enabled bool `yaml:"enabled"`

	// Filter for MRs to include (by title).
	Regexp string `default:".*" yaml:"regexp"`

	// MostRecent limits export to only the N most recently updated merge requests.
	// If zero, no limit is applied.
	MostRecent uint `default:"0" yaml:"most_recent"`

	// MaxAgeSeconds prevents exporting metrics for merge requests whose most recent pipeline
	// update is older than this number of seconds. Zero means no age limit.
	MaxAgeSeconds uint `default:"0" yaml:"max_age_seconds"`

	// Prevent exporting metrics for MRs that are not opened.
	ExcludeNonOpened bool `default:"false" yaml:"exclude_non_opened"`
}

type ProjectPullRefsTags struct {
	// Enabled toggles whether pipeline metrics for tags are monitored.
	// Defaults to true.
	Enabled bool `default:"true" yaml:"enabled"`

	// Regexp filters tags by name using a regex pattern.
	// Defaults to match all tags (".*").
	Regexp string `default:".*" yaml:"regexp"`

	// MostRecent limits export to only the N most recently updated tags.
	// If zero, no limit is applied.
	MostRecent uint `default:"0" yaml:"most_recent"`

	// MaxAgeSeconds prevents exporting metrics for tags whose most recent pipeline
	// update is older than this number of seconds. Zero means no age limit.
	MaxAgeSeconds uint `default:"0" yaml:"max_age_seconds"`

	// ExcludeDeleted controls whether to exclude tags marked as deleted.
	// Defaults to true.
	ExcludeDeleted bool `default:"true" yaml:"exclude_deleted"`
}

type ProjectPullRunners struct {
	Enabled        bool   `default:"true" yaml:"enabled"`
	Regexp         string `default:".*" yaml:"regexp"`
	ExcludeStopped bool   `default:"false" yaml:"exclude_stopped"`
}

type Projects []Project

type Pull struct {
	// ProjectsFromWildcards configures the fetching of projects discovered through wildcard searches.
	ProjectsFromWildcards struct {
		OnInit          bool `default:"true" yaml:"on_init"`                           // OnInit determines whether projects should be fetched once at startup.
		Scheduled       bool `default:"true" yaml:"scheduled"`                         // Scheduled enables periodic fetching of projects.
		IntervalSeconds int  `default:"1800" validate:"gte=1" yaml:"interval_seconds"` // IntervalSeconds defines the interval in seconds between scheduled fetches.
	} `yaml:"projects_from_wildcards"`

	// EnvironmentsFromProjects configures the fetching of environments associated with projects.
	EnvironmentsFromProjects struct {
		OnInit          bool `default:"true" yaml:"on_init"`                           // OnInit determines whether environments should be fetched once at startup.
		Scheduled       bool `default:"true" yaml:"scheduled"`                         // Scheduled enables periodic fetching of environments.
		IntervalSeconds int  `default:"1800" validate:"gte=1" yaml:"interval_seconds"` // IntervalSeconds defines the interval in seconds between scheduled fetches.
	} `yaml:"environments_from_projects"`

	// RunnersFromProjects configures the fetching of runners associated with projects.
	RunnersFromProjects struct {
		OnInit          bool `default:"true" yaml:"on_init"`
		Scheduled       bool `default:"true" yaml:"scheduled"`
		IntervalSeconds int  `default:"1800" validate:"gte=1" yaml:"interval_seconds"`
	} `yaml:"runners_from_projects"`

	// RefsFromProjects configures the fetching of refs (branches, tags, MRs) for projects.
	RefsFromProjects struct {
		OnInit          bool `default:"true" yaml:"on_init"`                          // OnInit determines whether refs should be fetched once at startup.
		Scheduled       bool `default:"true" yaml:"scheduled"`                        // Scheduled enables periodic fetching of refs.
		IntervalSeconds int  `default:"300" validate:"gte=1" yaml:"interval_seconds"` // IntervalSeconds defines the interval in seconds between scheduled fetches.
	} `yaml:"refs_from_projects"`

	// Metrics configures how metrics data is fetched.
	Metrics struct {
		OnInit          bool `default:"true" yaml:"on_init"`                         // OnInit determines whether metrics should be fetched once at startup.
		Scheduled       bool `default:"true" yaml:"scheduled"`                       // Scheduled enables periodic fetching of metrics.
		IntervalSeconds int  `default:"30" validate:"gte=1" yaml:"interval_seconds"` // IntervalSeconds defines the interval in seconds between scheduled fetches.
	} `yaml:"metrics"`
}

type Redis struct {
	// URL is the connection string used to connect to the Redis server.
	// Format example: redis[s]://[:password@]host[:port][/db-number][?option=value]
	URL string `yaml:"url"`

	ProjectTTL time.Duration `default:"336h" yaml:"project_ttl"` // ProjectTTL defines TTL for projects by default 2 weeks
	RefTTL     time.Duration `default:"1h" yaml:"ref_ttl"`       // RefTTL defines TTL for references by default 1h
	RunnerTTL  time.Duration `default:"1h" yaml:"runner_ttl"`    // RunnerTTL defines TTL for runners by default 1h
	EnvTTL     time.Duration `default:"1h" yaml:"env_ttl"`       // EnvTTL defines TTL for Environments by default 1h
	MetricTTL  time.Duration `default:"1h" yaml:"metric_ttl"`    // MetricTTL defines TTL for Metrics by default 1h
}

type SchedulerConfig struct {
	OnInit          bool // OnInit determines whether the task should run immediately at startup.
	Scheduled       bool // Scheduled determines whether the task should run on a recurring schedule.
	IntervalSeconds int  // IntervalSeconds specifies how often (in seconds) the task should run when scheduled.
}

type Server struct {
	// ListenAddress specifies the address and port the server will bind to and listen on.
	// Default is ":8080" (all interfaces on port 8080).
	ListenAddress string        `default:":8080" yaml:"listen_address"`
	EnablePprof   bool          `default:"false" yaml:"enable_pprof"` // EnablePprof enables profiling endpoints for debugging performance issues.
	Metrics       ServerMetrics `yaml:"metrics"`                      // Metrics contains configuration related to exposing Prometheus metrics.
	Webhook       ServerWebhook `yaml:"webhook"`                      // Webhook holds configuration for webhook-related HTTP endpoints.
}

type ServerMetrics struct {
	// EnableOpenmetricsEncoding enables OpenMetrics content encoding in the Prometheus HTTP handler.
	// This can be useful for compatibility with Prometheus 2.0+.
	EnableOpenmetricsEncoding bool `default:"false" yaml:"enable_openmetrics_encoding"`
	Enabled                   bool `default:"true" yaml:"enabled"` // Enabled controls whether the /metrics endpoint is exposed.
}

type ServerWebhook struct {
	// Enabled enables the /webhook endpoint to receive GitLab webhook requests.
	Enabled bool `default:"false" yaml:"enabled"`

	// SecretToken is used to authenticate incoming webhook requests to ensure they come from a legitimate GitLab server.
	// This token is required if the webhook endpoint is enabled.
	SecretToken string `validate:"required_if=Enabled true" yaml:"secret_token"`
}

type Wildcard struct {
	ProjectParameters `yaml:",inline"`

	Search   string        `yaml:"search"`
	Owner    WildcardOwner `yaml:"owner"`
	Archived bool          `yaml:"archived"`
}

type WildcardOwner struct {
	Name             string `yaml:"name"`
	Kind             string `yaml:"kind"`
	IncludeSubgroups bool   `yaml:"include_subgroups"`
}

type Wildcards []Wildcard