gserver

type CORS struct {
	// Enabled specifies if the CORS is enabled.
	Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// MaxAge indicates how long (in seconds) the results of a preflight request can be cached.
	MaxAge int `json:"max_age,omitempty" yaml:"max_age,omitempty"`

	// AllowedOrigins is a list of origins a cross-domain request can be executed from.
	AllowedOrigins []string `json:"allowed_origins,omitempty" yaml:"allowed_origins,omitempty"`

	// AllowedMethods is a list of methods the client is allowed to use with cross-domain requests.
	AllowedMethods []string `json:"allowed_methods,omitempty" yaml:"allowed_methods,omitempty"`

	// AllowedHeaders is list of non simple headers the client is allowed to use with cross-domain requests.
	AllowedHeaders []string `json:"allowed_headers,omitempty" yaml:"allowed_headers,omitempty"`

	// ExposedHeaders indicates which headers are safe to expose to the API of a CORS API specification.
	ExposedHeaders []string `json:"exposed_headers,omitempty" yaml:"exposed_headers,omitempty"`

	// AllowCredentials indicates whether the request can include user credentials.
	// It requires explicit AllowedOrigins or origin patterns; "*" is rejected.
	AllowCredentials *bool `json:"allow_credentials,omitempty" yaml:"allow_credentials,omitempty"`

	// OptionsPassthrough instructs preflight to let other potential next handlers to process the OPTIONS method.
	OptionsPassthrough *bool `json:"options_pass_through,omitempty" yaml:"options_pass_through,omitempty"`

	// Debug flag adds additional output to debug server side CORS issues.
	Debug *bool `json:"debug,omitempty" yaml:"debug,omitempty"`
}

type Config struct {
	// DebugLogs enables verbose per-request debug logging in the gRPC/HTTP mux.
	DebugLogs bool `json:"debug_logs" yaml:"debug_logs"`

	// Description provides description of the server
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Disabled specifies if the service is disabled
	Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty"`

	// ClientURL is the public URL exposed to clients
	ClientURL string `json:"client_url" yaml:"client_url"`

	// ListenURLs is the list of URLs to listen on. Supported schemes are
	// http, https, unix and unixs; a URL without scheme defaults to https when
	// ServerTLS is set. URLs with the same address share one listener.
	ListenURLs []string `json:"listen_urls" yaml:"listen_urls"`

	// ServerTLS provides the TLS config for the server; required for https/unixs URLs.
	ServerTLS *TLSInfo `json:"server_tls,omitempty" yaml:"server_tls,omitempty"`

	// SkipLogPaths if set, specifies a list of paths to not log.
	// this can be used for /v1/status/node or /metrics
	SkipLogPaths []telemetry.LoggerSkipPath `json:"logger_skip_paths,omitempty" yaml:"logger_skip_paths,omitempty"`

	// PromGrpc adds the go-grpc-prometheus unary and stream interceptors.
	PromGrpc bool `json:"prom_grpc" yaml:"prom_grpc"`

	// Services is the list of service names to enable; each must have a
	// ServiceFactory registered in the map passed to Start.
	Services []string `json:"services" yaml:"services"`

	// IdentityMap configures how callers are authenticated and mapped to roles
	// (see gserver/roles). When nil an empty map is used and all callers are guests.
	IdentityMap *roles.IdentityMap `json:"identity_map" yaml:"identity_map"`

	// Authz configures path/role based authorization (see restserver/authz).
	// It is only activated when at least one of Allow, AllowAny or AllowAnyRole is set.
	Authz *authz.Config `json:"authz" yaml:"authz"`

	// CORS contains configuration for CORS.
	CORS *CORS `json:"cors,omitempty" yaml:"cors,omitempty"`

	// RateLimit contains configuration for the rate limiter
	RateLimit *RateLimit `json:"rate_limit,omitempty" yaml:"rate_limit,omitempty"`

	// TrustedProxyCIDRs permits these socket peers to supply forwarding headers.
	// By default, only the socket address is used for client IP and scheme.
	TrustedProxyCIDRs []string `json:"trusted_proxy_cidrs,omitempty" yaml:"trusted_proxy_cidrs,omitempty"`

	// Timeouts bounds HTTP reads, cmux detection and eager TLS handshakes.
	// Zero fields select limits defaults; negative fields disable deadlines.
	// Read does not apply to native gRPC streams, on any listener.
	Timeouts limits.Timeouts `json:"timeouts,omitempty" yaml:"timeouts,omitempty"`

	// MaxRequestBody limits HTTP body bytes, including TLS gRPC/gRPC-Web streams.
	// Zero uses limits.DefaultMaxRequestBody; negative disables the limit.
	// Native gRPC on plain listeners uses MaxRecvMsgSize instead.
	MaxRequestBody int64 `json:"max_request_body,omitempty" yaml:"max_request_body,omitempty"`

	// Timeout settings
	Timeout struct {
		// Request is how long Close waits for in-flight requests to finish
		// before forcing shutdown; default 3s.
		Request time.Duration `json:"request,omitempty" yaml:"request,omitempty"`
	} `json:"timeout" yaml:"timeout"`

	// KeepAlive settings
	KeepAlive KeepAliveCfg `json:"keep_alive" yaml:"keep_alive"`

	// MaxRecvMsgSize sets the maximum gRPC message size a client can send;
	// the MaxRecvMsgSize Option takes precedence when set.
	MaxRecvMsgSize int `json:"max_recv_msg_size,omitempty" yaml:"max_recv_msg_size,omitempty"`

	// MaxSendMsgSize sets the maximum gRPC message size the server can send;
	// the MaxSendMsgSize Option takes precedence when set.
	MaxSendMsgSize int `json:"max_send_msg_size,omitempty" yaml:"max_send_msg_size,omitempty"`

	// HTTPHeaders are static response headers set on every response served
	// by TLS listeners (they are not applied on plain http listeners).
	// While CORS is enabled, Access-Control-* names are rejected (see
	// Validate): the CORS block owns those headers.
	HTTPHeaders map[string]string `json:"http_headers,omitempty" yaml:"http_headers,omitempty"`
}

type GRPCRegistrator interface {
	// RegisterGRPC registers the service implementation on the gRPC server.
	RegisterGRPC(*grpc.Server)
}

type GServer interface {
	// Name returns server name
	Name() string
	// Configuration of the server
	Configuration() *Config
	// AddService to the server
	AddService(svc Service)
	// Service returns service by name
	Service(name string) Service
	// IsReady returns true when the server is ready to serve
	IsReady() bool
	// StartedAt returns Time when the server has started
	StartedAt() time.Time
	// ListenURLs is the list of URLs that the server listens on
	ListenURLs() []string
	// Hostname is the hostname
	Hostname() string
	// LocalIP is the local IP4
	LocalIP() string
	// Discovery returns Discovery interface
	Discovery() discovery.Discovery
	// Err returns error channel
	Err() <-chan error
	// Close gracefully shuts down all servers/listeners and stops the TLS
	// certificate reloader.
	// Client requests will be terminated with request timeout.
	// After timeout, enforce remaining requests be closed immediately.
	// The teardown runs once: later or concurrent calls return after it
	// has finished.
	Close()
}

type KeepAliveCfg struct {
	// MinTime is the minimum interval that a client should wait before pinging server.
	MinTime time.Duration `json:"min_time,omitempty" yaml:"min_time,omitempty"`

	// Interval is the frequency of server-to-client ping to check if a connection is alive.
	Interval time.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`

	// Timeout is the additional duration of wait before closing a non-responsive connection, use 0 to disable.
	Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

type Middleware func(handler http.Handler) http.Handler

type Option interface {
	// contains filtered or unexported methods
}

type RateLimit struct {
	// Enabled specifies if rate limiting is enabled.
	Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	// RequestsPerSecond specifies the maximum number of requests per second
	// per client; it is also the burst size. It must be positive when Enabled:
	// with zero, tollbooth admits one request per client and then rejects
	// every later one.
	RequestsPerSecond int `json:"requests_per_second,omitempty" yaml:"requests_per_second,omitempty"`
	// ExpirationTTL specifies how long a client's token bucket is kept before
	// it is recreated with a full burst; zero selects 10 minutes. Negative
	// values and values below one second are rejected, and the TTL should
	// stay long relative to the refill interval.
	ExpirationTTL time.Duration `json:"expiration_ttl,omitempty" yaml:"expiration_ttl,omitempty"`
	// HeadersIPLookups lists the sources used to identify the client, in
	// order: "RemoteAddr", "X-Forwarded-For" or "X-Real-IP" (as spelled by
	// tollbooth; any other name is rejected because tollbooth would ignore it
	// and leave requests unlimited). The default is the trusted client
	// address derived from the socket peer and TrustedProxyCIDRs; a Unix
	// socket peer has none, so its callers are not limited. Explicit header
	// lookups can be spoofed and should be configured only when the
	// deployment guarantees they are overwritten.
	HeadersIPLookups []string `json:"headers_ip_lookups,omitempty" yaml:"headers_ip_lookups,omitempty"`
	// Metods (sic) restricts limiting to the listed HTTP methods, e.g. "GET",
	// "POST"; empty means all methods. tollbooth compares them exactly, so
	// each entry must be a single upper-case HTTP method token (RFC 9110
	// tchar characters only); any other entry is rejected because it would
	// never match and leave every request unlimited.
	Metods []string `json:"metods,omitempty" yaml:"metods,omitempty"`
	// LogRejections, when true, adds a WARNING line for each rejected
	// request with the limiter key (an IPv6 client's /64 prefix, as
	// tollbooth groups it), the socket peer, the User-Agent and the
	// forwarding headers as received. Its correlation ID (ctx) is the
	// X-Correlation-ID of a 429 and the request ID of a gRPC error. It is
	// off by default. Turn it on to check whether a load balancer's client
	// IP is the limiter key, or whether every caller shares one internal
	// peer such as 10.0.x.x; gRPC log lines show no client address.
	LogRejections *bool `json:"log_rejections,omitempty" yaml:"log_rejections,omitempty"`
}

type RouteRegistrator interface {
	// RegisterRoute adds the service HTTP handlers to the router.
	RegisterRoute(restserver.Router)
}

type Server struct {
	// Listeners are the accepted network listeners, one per unique listen
	// address. They are wrappers (accept backoff, TCP keepalive), not the
	// *net.TCPListener or *net.UnixListener values; use Addr and Close.
	Listeners []net.Listener
	// contains filtered or unexported fields
}

type Service interface {
	// Name returns the unique service name used as the key in GServer.Service.
	Name() string
	// Close releases the service resources; it is called by Server.Close before
	// the listeners are shut down.
	Close()
	// IsReady indicates that service is ready to serve its end-points
	IsReady() bool
}

type ServiceFactory func(GServer) any

type StartSubcriber interface {
	// OnStarted is called when the server started and
	// is ready to serve requests
	OnStarted() error
}

type SwaggerCfg struct {
	// Enabled allows Swagger
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Files is a map of service name to location
	Files map[string]string `json:"files" yaml:"files"`
}

type TLSInfo struct {
	// CertFile specifies location of the cert
	CertFile string `json:"cert,omitempty" yaml:"cert,omitempty"`

	// KeyFile specifies location of the key
	KeyFile string `json:"key,omitempty" yaml:"key,omitempty"`

	// TrustedCAFile specifies location of the trusted root CA bundle
	TrustedCAFile string `json:"trusted_ca,omitempty" yaml:"trusted_ca,omitempty"`

	// ClientCAFile specifies location of the CA bundle used to verify client certificates
	ClientCAFile string `json:"client_ca,omitempty" yaml:"client_ca,omitempty"`

	// CRLFile specifies location of the CRL
	CRLFile string `json:"crl,omitempty" yaml:"crl,omitempty"`

	// OCSPFile specifies location of the OCSP response
	OCSPFile string `json:"ocsp,omitempty" yaml:"ocsp,omitempty"`

	// CipherSuites optionally restricts the enabled TLS 1.2 cipher suites, by
	// crypto/tls name. The order is ignored: Go picks the preferred mutually
	// supported suite itself. Names Go lists as insecure and TLS 1.3 suites
	// (not configurable in Go) are rejected.
	CipherSuites []string `json:"cipher_suites,omitempty" yaml:"cipher_suites,omitempty"`

	// ClientCertAuth, when true, requires and verifies a client certificate;
	// otherwise a client certificate is verified only if presented.
	ClientCertAuth *bool `json:"client_cert_auth,omitempty" yaml:"client_cert_auth,omitempty"`
}

type Validator interface {
	// Validate returns an error (typically a gRPC status) when the request is invalid.
	Validate(ctx context.Context) error
}