config

type Config struct {
	GitLabURL string
	// GitLabURLs is the full set of instances an HTTP deployment publishes,
	// in the order they were configured; GitLabURL is its first entry.
	//
	// More than one turns the per-request GITLAB-URL header from a free
	// choice into a selection among published instances, which is what makes
	// it safe in oauth mode: the server validates the bearer token against
	// the instance it is about to use, so a caller naming a host of their own
	// would be handed the token. Empty or single-valued behaves exactly as
	// GitLabURL alone always has.
	GitLabURLs        []string
	GitLabToken       string
	SkipTLSVerify     bool
	DisableRetries    bool // Disable GitLab client retries for unit tests.
	ToolSurface       string
	CapabilitySurface string

	// Tier is the resolved GitLab licensing tier for this configuration.
	// When TierExplicit is false it holds the conservative default
	// (edition.Free); callers detect the real tier from the instance license.
	Tier edition.Tier
	// TierExplicit reports whether the tier was set explicitly via GITLAB_MCP_TIER
	// (stdio) or --tier (HTTP). When true, no instance license check is
	// performed and Tier is used verbatim. When false, the tier is detected
	// per instance, falling back to edition.Free.
	TierExplicit bool

	ReadOnly bool
	SafeMode bool

	EmbeddedResources bool // Append EmbeddedResource content blocks to get_* tool results (default true)

	UploadMaxFileSize int64

	MaxHTTPClients     int           // Maximum unique tokens in the server pool (HTTP mode only)
	SessionTimeout     time.Duration // Idle MCP session timeout (HTTP mode only)
	RevalidateInterval time.Duration // Token re-validation interval (HTTP mode only)
	// ActionTimeout bounds one action's handler in both transports: a call
	// still running after this long is cancelled and answered with the
	// deadline error. 0 disables the bound.
	ActionTimeout time.Duration
	// DrainDelay is how long, after SIGTERM, the HTTP listener stays open
	// answering /health with 503 draining before it closes, so a balancer
	// takes the instance out of rotation first. 0 closes at once.
	DrainDelay time.Duration
	// PoolIdleTimeout is how long a pooled per-token-and-URL server entry may go unused
	// before it is reclaimed; 0 keeps entries until the pool's size bound
	// evicts them (HTTP mode only).
	PoolIdleTimeout time.Duration

	// Stateless enables sessionless streamable HTTP (SEP-2567, protocol
	// 2026-07-28): the server neither reads nor sets Mcp-Session-Id, every
	// POST is self-contained, and GET/DELETE return 405 (HTTP mode only).
	Stateless bool
	// JSONResponse returns application/json bodies instead of
	// text/event-stream (SSE) for streamable responses (HTTP mode only).
	JSONResponse bool
	// MaxRequestBodyBytes caps the size of incoming streamable HTTP request
	// bodies. 0 uses the SDK default (4 MiB); negatives are rejected at
	// validation (HTTP mode only).
	//
	// The default stays at the SDK's 4 MiB rather than being cut to 256 KiB or
	// 1 MiB, which a hardening review proposed against the cost of parsing a
	// deeply nested body. That defense now lives where the shape of the attack
	// is, in the inbound JSON depth cap: a smaller byte budget only narrows the
	// window, since a quarter of a megabyte still spells a hundred thousand
	// levels of nesting, and a wide-but-shallow body of the full size
	// unmarshals in tens of milliseconds either way. Cutting it would break the
	// documented inline-upload path, where content_base64 is the only way a
	// remote caller can send a file at all, for every deployment that never
	// configured the flag. An operator who wants a smaller ceiling still has
	// the flag.
	MaxRequestBodyBytes int64

	// TLSCertFile and TLSKeyFile enable TLS on the listener itself, for a
	// deployment where the proxy does not share a machine with the server
	// and the hop between them crosses a network. They are set together or
	// not at all (HTTP mode only).
	TLSCertFile string
	TLSKeyFile  string
	// SocketMode is the permission bits applied to a unix socket named by
	// the listen address. 0 means the default, [DefaultSocketMode].
	SocketMode os.FileMode

	AuthMode      string        // Auth mode for HTTP: "legacy" (default) or "oauth"
	OAuthCacheTTL time.Duration // OAuth token cache TTL (HTTP mode, oauth auth mode)
	// OAuthClientUIDs pins the OAuth applications whose tokens this
	// deployment admits, by GitLab application uid. Empty — the default —
	// admits any credential the instance accepts.
	//
	// It is the only recipient check available: GitLab's authorization server
	// publishes no resource_indicators_supported, so RFC 8707 audience
	// restriction cannot be used, and the specification's "or otherwise verify
	// that they are the intended recipient" is met by comparing the
	// application a token was minted for. It is a set because --gitlab-url is
	// repeatable and every published instance has its own application.
	//
	// Off by default because turning it on refuses personal access tokens
	// outright: a PAT belongs to no application, and it is a supported
	// credential here.
	OAuthClientUIDs []string
	// PublicURL is the externally reachable origin of this deployment
	// (scheme://host[:port][/path], no trailing slash). Required in oauth
	// mode: RFC 9728 defines the protected-resource identifier as an https
	// URL, and deriving it from the bind address produces host-less or
	// wrong-origin identifiers behind any TLS-terminating proxy.
	PublicURL string

	// ResourceDocumentation is the RFC 9728 resource_documentation URL the
	// protected-resource metadata advertises. Empty means this project's
	// own OAuth setup guide. An operator running their own deployment
	// points it at a page describing their own OAuth application, which is
	// the only sanctioned way to lead a client to a client ID: RFC 9728
	// defines no field for one.
	ResourceDocumentation string

	// ResourcePolicyURI and ResourceTermsURI are the RFC 9728
	// resource_policy_uri and resource_tos_uri fields. Both are omitted from
	// the metadata document when empty, which is the default: they describe a
	// specific deployment's undertakings about the data reached with the
	// tokens it accepts, and publishing a link to a page that does not exist
	// would put a dead link on a consent screen.
	ResourcePolicyURI string
	ResourceTermsURI  string

	TrustedProxyHeader string   // HTTP header with real client IP (e.g. X-Forwarded-For, X-Real-IP)
	TrustedProxies     []string // Addresses or CIDR ranges of the proxies TrustedProxyHeader is believed from; required with it
	// TrustedOrigins are absolute origins (scheme://host[:port]) allowed to
	// make cross-origin browser requests. Empty by default: the server
	// refuses every cross-origin browser POST, and only a listed origin (or
	// the PublicURL origin, seeded automatically) is exempted. A trusted
	// origin is validation, not a bypass — the DNS-rebinding MUST is still
	// met for every origin not on the list.
	TrustedOrigins []string
	ExcludeTools   []string // Tool names to exclude from registration (comma-separated via EXCLUDE_TOOLS)
	IgnoreScopes   bool     // When true, skip PAT scope detection and register all tools

	RateLimitRPS   float64 // Per-server tools/call rate limit in requests/second (0 = disabled)
	RateLimitBurst int     // Token-bucket burst size when RateLimitRPS > 0

	// MetaParamSchema controls how meta-tool input schemas advertise the
	// shape of the `params` object. Allowed values: "opaque" (default),
	// "compact", "full". See [DefaultMetaParamSchema] and constants.
	MetaParamSchema string
}

type EnvFileReport struct {
	// ExplicitPath is the absolute path of the file EnvFileVar named, whether
	// or not it could be read. Empty when the variable is unset.
	ExplicitPath string
	// ExplicitErr is why the file EnvFileVar named could not be read.
	ExplicitErr error
	// ExplicitRelative records that EnvFileVar named a relative path, so the
	// file that was loaded is whichever one sits in the working directory the
	// client chose. Meaningless when ExplicitPath is empty.
	ExplicitRelative bool
	// HomePath is the home file that was loaded. Empty when there is none.
	HomePath string
	// IgnoredPath is the absolute path of a working-directory .env that was
	// found and deliberately not loaded. Empty when there is none.
	IgnoredPath string
	// IgnoredKeys are the variable names that file would have set, sorted.
	IgnoredKeys []string
}

type HTTPEnvOverlay struct {
	GitLabURL         *string
	SkipTLSVerify     *bool
	ToolSurface       *string
	CapabilitySurface *string
	MetaParamSchema   *string

	Tier         *edition.Tier
	TierExplicit bool

	ReadOnly          *bool
	SafeMode          *bool
	EmbeddedResources *bool
	IgnoreScopes      *bool
	ExcludeTools      *string

	MaxHTTPClients     *int
	SessionTimeout     *time.Duration
	PoolIdleTimeout    *time.Duration
	RevalidateInterval *time.Duration
	ActionTimeout      *time.Duration
	DrainDelay         *time.Duration

	AuthMode       *string
	PublicURL      *string
	TrustedOrigins *string
	OAuthCacheTTL  *time.Duration
	OAuthClientUID *string

	RateLimitRPS   *float64
	RateLimitBurst *int
}

type ServerConfig struct {
	GitLabURL         string
	ToolSurface       string
	CapabilitySurface string
	// Tier is the resolved GitLab licensing tier for this pool entry. When the
	// owning Config did not set the tier explicitly, the pool detects it per
	// instance before building the server.
	Tier edition.Tier
	// TierExplicit mirrors Config.TierExplicit: when true the tier is used
	// verbatim and the pool performs no per-instance license detection.
	TierExplicit bool
	ReadOnly     bool
	// ReadOnlyFromTokenScope records that ReadOnly was not asked for by the
	// operator but derived from the credential: this token cannot write, so a
	// read-only surface was built for it. The two causes need different words
	// when a withheld action is asked for — "reauthorize with a wider scope"
	// versus "this deployment does not write" — and only the first is
	// something the caller can act on.
	ReadOnlyFromTokenScope bool
	SafeMode               bool
	ExcludeTools           []string
	TokenScopes            []string
	RateLimitRPS           float64
	RateLimitBurst         int
	MetaParamSchema        string
	// Stateless mirrors Config.Stateless. It reaches the server because a
	// sessionless transport cannot carry a server-initiated notification
	// outside an open request, which decides whether the legacy
	// resources/subscribe path can be honored at all.
	Stateless bool
}