goutils

type AsyncQueue[V any] interface {
	/*
		Len get the current queue length

			@return current queue length
	*/
	Len() int

	/*
		Push enqueue data

			@generic V any - the data type being passed through the queue
			@param ctx context.Context - calling context
			@param data V - data to enqueue
	*/
	Push(ctx context.Context, data V) error

	/*
		Pop dequeue data. If caller choices to wait until data is available, the maximum duration
		for the wait is controlled by the context.

		The queue uses "Condition" to signal to any awaiting caller that data is available. To
		support that, the caller needs to supply wake up chan for use with "Condition".

			@generic V any - the data type being passed through the queue
			@param ctx context.Context - calling context
			@param blocking bool - whether to block until data is available
			@param newDataSignalFlag chan bool - wake up chan for use with "Condition"
			@return data from queue
			@error ErrorNoDataAvailable - queue is empty
			@error ErrorTimeout - timed out waiting for data
	*/
	Pop(ctx context.Context, blocking bool, newDataSignalFlag chan bool) (V, error)
}

type ClientCredOAuthTokenManagerParam struct {
	// IDPIssuerURL OpenID provider issuing URL
	IDPIssuerURL string `validate:"required,url"`
	// ClientID OAuth client ID
	ClientID string `validate:"required"`
	// ClientSecret OAuth client secret
	ClientSecret string `validate:"required"`
	// TargetAudience the token's target audience
	TargetAudience *string
	// LogTags metadata fields to include in the logs
	LogTags log.Fields
	// CustomLogModifiers additional log metadata modifiers to use
	CustomLogModifiers []LogMetadataModifier
	// TimeBuffer time buffer before a token expires to perform the token refresh / renew.
	// This helps in situations where there is a time offset between the client and the
	// server.
	TimeBuffer time.Duration

	// SupportTaskMetricsHelper metrics collection helper for the support tasks
	SupportTaskMetricsHelper TaskProcessorMetricHelper
}

type Component struct {
	// LogTags the Apex logging message metadata tags
	LogTags log.Fields
	// LogTagModifiers is the list of log metadata modifier callbacks
	LogTagModifiers []LogMetadataModifier
}

type Condition interface {
	// NotifyOne notify one waiter
	NotifyOne() error

	// NotifyAll notify all waiters
	NotifyAll() error

	/*
		Wait caller will block and wait to be notified. The maximum duration for the wait is
		controlled by the context.

		The signaling channel is provided by the caller, and allows the same channel to be reused
		for subsequent calls.

		IMPORTANT: the signaling channel must be buffered

			@param ctx context.Context - calling context
			@param wakeUp chan bool - signaling channel
			@error ErrorTimeout - timed out waiting for signal
	*/
	Wait(ctx context.Context, wakeUp chan bool) error
}

type ErrorDetail struct {
	// Code is the response code
	Code int `json:"code" validate:"required"`
	// Msg is an optional descriptive message
	Msg string `json:"message,omitempty"`
	// Detail is an optional descriptive message providing additional details on the error
	Detail string `json:"detail,omitempty"`
}

type ErrorNoDataAvailable struct{}

type ErrorTimeout struct{}

type ErrorUnexpectedType struct {
	Expected reflect.Type
	Gotten   reflect.Type
}

type HTTPClientAuthConfig struct {
	// IssuerURL OpenID provider issuer URL
	IssuerURL string `json:"issuer"`
	// ClientID OAuth client ID
	ClientID string `json:"client_id"`
	// ClientSecret OAuth client secret
	ClientSecret string `json:"client_secret"`
	// TargetAudience target audience `aud` to acquire a token for
	TargetAudience *string `json:"target_audience"`
	// LogTags auth middleware log tags
	LogTags log.Fields
}

type HTTPClientRetryConfig struct {
	// MaxAttempts max number of retry attempts
	MaxAttempts int `json:"max_attempts"`
	// InitWaitTime wait time before the first wait retry
	InitWaitTime time.Duration `json:"initialWaitTimeInSec"`
	// MaxWaitTime max wait time
	MaxWaitTime time.Duration `json:"maxWaitTimeInSec"`
}

type HTTPClientTransportConfig struct {
	// CustomCA if provided, is the custom CA to use for the TLS session.
	CustomCA *string `json:"http_tls_ca,omitempty"`
}

type HTTPRequestLogLevel string

type HTTPRequestMetricHelper interface {
	/*
		RecordRequest record parameters regarding a request to the metrics

			@param method string - HTTP request method
			@param status int - HTTP response status
			@param latency time.Duration - delay between request received, and response sent
			@param respSize int64 - HTTP response size in bytes
	*/
	RecordRequest(method string, status int, latency time.Duration, respSize int64)
}

type HTTPRequestRetryParam struct {
	// MaxRetires maximum number of retries
	MaxRetires int
	// InitialWaitTime the initial retry wait time
	InitialWaitTime time.Duration
	// MaxWaitTime the max retry wait time
	MaxWaitTime time.Duration
}

type IntervalTimer interface {
	/*
		Start starts timer with a specific timeout interval, and the callback to trigger on timeout.

		If oneShort, cancel after first timeout.

		 @param interval time.Duration - timeout interval
		 @param handler TimeoutHandler - handler to trigger on timeout
		 @param oneShort bool - if true, timer stop after first activation
	*/
	Start(interval time.Duration, handler TimeoutHandler, oneShort bool) error

	/*
		Stop stops the timer
	*/
	Stop() error
}

type JWTCheckMiddleware struct {
	Component
	// contains filtered or unexported fields
}

type LogMetadataModifier func(context.Context, log.Fields)

type MessageBus interface {
	/*
		CreateTopic create new message topic

			@param ctxt context.Context - execution context
			@param topicName string - topic name
			@param topicLogTags log.Fields - metadata fields to include in the logs of the topic entity
			@return new MessageTopic instance
	*/
	CreateTopic(
		ctxt context.Context, topicName string, topicLogTags log.Fields,
	) (MessageTopic, error)

	/*
		GetTopic fetch a message topic

			@param ctxt context.Context - execution context
			@param topicName string - topic name
			@returns MessageTopic instance
	*/
	GetTopic(ctxt context.Context, topicName string) (MessageTopic, error)

	/*
		DeleteTopic delete a message topic

			@param ctxt context.Context - execution context
			@param topicName string - topic name
	*/
	DeleteTopic(ctxt context.Context, topicName string) error
}

type MessageTopic interface {
	/*
		Publish publish a message on the topic in parallel.

			@param ctxt context.Context - execution context
			@param message interface{} - the message to send
			@param blockFor time.Duration - how long to block for the publish to complete. If >0,
			    this is a non-blocking call; blocking call otherwise.
	*/
	Publish(ctxt context.Context, message interface{}, blockFor time.Duration) error

	/*
		CreateSubscription create a new topic subscription

			@param ctxt context.Context - execution context
			@param subscriber string - name of the subscription
			@param bufferLen int - length of message buffer
			@returns the channel to receive messages on
	*/
	CreateSubscription(
		ctxt context.Context, subscriber string, bufferLen int,
	) (chan interface{}, error)

	/*
		DeleteSubscription delete an existing topic subscription

			@param ctxt context.Context - execution context
			@param subscriber string - subscription to delete
	*/
	DeleteSubscription(ctxt context.Context, subscriber string) error
}

type MetricsCollector interface {
	/*
		InstallApplicationMetrics install trackers for Golang application execution metrics
	*/
	InstallApplicationMetrics()

	/*
		InstallHTTPMetrics install trackers for HTTP request metrics collection. This will return
		a helper agent to record the metrics.

			@returns request metrics logging agent
	*/
	InstallHTTPMetrics() HTTPRequestMetricHelper

	/*
		InstallPubSubMetrics install trackers for PubSub messaging collection. This will return
		a helper agent to record the metrics.

			@return PubSub metrics logging agent
	*/
	InstallPubSubMetrics() PubSubMetricHelper

	/*
		InstallTaskProcessorMetrics install tracker for Task processor operations. This will return
		a helper agent to record the metrics

			@return Task process logging agent
	*/
	InstallTaskProcessorMetrics() TaskProcessorMetricHelper

	/*
		InstallCustomCounterVecMetrics install new custom `CounterVec` metrics

			@param ctxt context.Context - execution context
			@param metricsName string - metrics name
			@param metricsHelpMessage string - metrics help message
			@param metricsLabels []string - labels to support
			@returns new `CounterVec` handle
	*/
	InstallCustomCounterVecMetrics(
		ctxt context.Context, metricsName string, metricsHelpMessage string, metricsLabels []string,
	) (*prometheus.CounterVec, error)

	/*
		InstallCustomGaugeVecMetrics install new custom `GaugeVec` metrics

			@param ctxt context.Context - execution context
			@param metricsName string - metrics name
			@param metricsHelpMessage string - metrics help message
			@param metricsLabels []string - labels to support
			@returns new `GaugeVec` handle
	*/
	InstallCustomGaugeVecMetrics(
		ctxt context.Context, metricsName string, metricsHelpMessage string, metricsLabels []string,
	) (*prometheus.GaugeVec, error)

	/*
		ExposeCollectionEndpoint expose the Prometheus metric collection endpoint

			@param outer *mux.Router - HTTP router to install endpoint on
			@param metricsPath string - metrics endpoint path relative to the router provided
			@param maxSupportedRequest int - max number of request the endpoint will support
	*/
	ExposeCollectionEndpoint(router *mux.Router, metricsPath string, maxSupportedRequest int)
}

type OAuthTokenManager interface {
	/*
		GetToken fetch the current valid OAuth token

		 @param ctxt context.Context - the execution context
		 @param timestamp time.Time - the current timestamp
		 @returns the token
	*/
	GetToken(ctxt context.Context, timestamp time.Time) (string, error)

	/*
		Stop stop any support background tasks which were started

		 @param ctxt context.Context - execution context
	*/
	Stop(ctxt context.Context) error
}

type OIDPClientParam struct {
	// Issuer is the URL of the OpenID provider issuer URL
	Issuer string `json:"issuer" validate:"required,url"`
	// ClientID is the client ID to use during token introspection
	ClientID *string `json:"client_id" validate:"omitempty"`
	// ClientCred is the client credential to use during token introspection
	ClientCred *string `json:"client_cred" validate:"omitempty"`
	// RequestHostOverride if specified, use this as "Host" header when communicating with provider
	RequestHostOverride *string `json:"host_override" validate:"omitempty"`
	// TargetAudiences a set of audiences which are accepted
	TargetAudiences []string `json:"target_audiences"`
	// LogTags metadata fields to include in the logs
	LogTags log.Fields
}

type OpenIDProviderClient interface {
	/*
		AssociatedPublicKey fetches the associated public based on "kid" value of a JWT token

		 @param token *jwt.Token - the JWT token to find the public key for
		 @return public key material
	*/
	AssociatedPublicKey(token *jwt.Token) (interface{}, error)

	/*
		ParseJWT parses a string into a JWT token object.

		 @param raw string - the original JWT string
		 @param claimStore jwt.Claims - the object to store the claims in
		 @return the parsed JWT token object
	*/
	ParseJWT(raw string, claimStore jwt.Claims) (*jwt.Token, error)

	/*
		CanIntrospect whether the client can perform introspection

		 @return whether the client can perform introspection
	*/
	CanIntrospect() bool

	/*
		IntrospectToken perform introspection for a token

		 @param ctxt context.Context - the operating context
		 @param token string - the token to introspect
		 @return whether token is still valid
	*/
	IntrospectToken(ctxt context.Context, token string) (bool, error)
}

type PriorityQueueEntry interface {
	/*
		HigherPriorityThan check whether priority of this object is higher than "right"

			@param right PriorityQueueEntry - object to compare against
			@returns whether this element has higher priority than "right"
	*/
	HigherPriorityThan(right PriorityQueueEntry) bool
}

type PubSubClient interface {
	/*
		UpdateLocalTopicCache sync local topic cache with existing topics in project

		 @param ctxt context.Context - execution context
	*/
	UpdateLocalTopicCache(ctxt context.Context) error

	/*
		UpdateLocalSubscriptionCache sync local subscription cache with existing subscriptions in project

		 @param ctxt context.Context - execution context
	*/
	UpdateLocalSubscriptionCache(ctxt context.Context) error

	/*
		CreateTopic create PubSub topic

		 @param ctxt context.Context - execution context
		 @param topic string - topic name
		 @param config *pubsub.TopicConfig - optionally, provide config on the topic
	*/
	CreateTopic(ctxt context.Context, topic string, config *pubsub.TopicConfig) error

	/*
		DeleteTopic delete PubSub topic

		 @param ctxt context.Context - execution context
		 @param topic string - topic name
	*/
	DeleteTopic(ctxt context.Context, topic string) error

	/*
		GetTopic get the topic config for a topic

		 @param ctxt context.Context - execution context
		 @param topic string - topic name
		 @returns if topic is known, the topic config
	*/
	GetTopic(ctxt context.Context, topic string) (pubsub.TopicConfig, error)

	/*
		UpdateTopic update the topic config

		 @param ctxt context.Context - execution context
		 @param topic string - topic name
		 @param newConfig pubsub.TopicConfigToUpdate - the new config
	*/
	UpdateTopic(ctxt context.Context, topic string, newConfig pubsub.TopicConfigToUpdate) error

	/*
		CreateSubscription create PubSub subscription to attach to topic

		 @param ctxt context.Context - execution context
		 @param targetTopic string - target topic
		 @param subscription string - subscription name
		 @param config pubsub.SubscriptionConfig - subscription config
	*/
	CreateSubscription(
		ctxt context.Context, targetTopic, subscription string, config pubsub.SubscriptionConfig,
	) error

	/*
		DeleteSubscription delete PubSub subscription

		 @param ctxt context.Context - execution context
		 @param subscription string - subscription name
	*/
	DeleteSubscription(ctxt context.Context, subscription string) error

	/*
		GetSubscription get the subscription config for a subscription

		 @param ctxt context.Context - execution context
		 @param subscription string - subscription name
		 @returns if subscription is known, the subscription config
	*/
	GetSubscription(ctxt context.Context, subscription string) (pubsub.SubscriptionConfig, error)

	/*
		UpdateSubscription update the subscription config

		 @param ctxt context.Context - execution context
		 @param subscription string - subscription name
		 @param newConfig pubsub.SubscriptionConfigToUpdate - the new config
	*/
	UpdateSubscription(
		ctxt context.Context, subscription string, newConfig pubsub.SubscriptionConfigToUpdate,
	) error

	/*
		Publish publish a message to a topic

		 @param ctxt context.Context - execution context
		 @param topic string - topic name
		 @param message []byte - message content
		 @param metadata map[string]string - message metadata, which will be sent using attributes
		 @param blocking bool - whether the call is blocking until publish is complete
		 @returns when non-blocking, the async result object to check on publish status
	*/
	Publish(
		ctxt context.Context, topic string, message []byte, metadata map[string]string, blocking bool,
	) (*pubsub.PublishResult, error)

	/*
		Subscribe subscribe for message on a subscription

		THIS CALL IS BLOCKING!!

		 @param ctxt context.Context - execution context
		 @param subscription string - subscription name
		 @param handler PubSubMessageHandler - RX message callback
	*/
	Subscribe(ctxt context.Context, subscription string, handler PubSubMessageHandler) error

	/*
		Close close and clean up the client

		 @param ctxt context.Context - execution context
	*/
	Close(ctxt context.Context) error
}

type PubSubMessageHandler func(
	ctxt context.Context, pubTimestamp time.Time, msg []byte, metadata map[string]string,
) error

type PubSubMetricHelper interface {
	/*
		RecordPublish record PubSub publish message

			@param topic string - PubSub topic
			@param successful bool - whether the operation was successful
			@param payloadLen int64 - publish payload length
	*/
	RecordPublish(topic string, successful bool, payloadLen int64)

	/*
		RecordReceive record PubSub receive message

			@param topic string - PubSub topic
			@param successful bool - whether the operation was successful
			@param payloadLen int64 - receive payload length
	*/
	RecordReceive(topic string, successful bool, payloadLen int64)
}

type PubSubRequestResponseClientParam struct {
	// TargetID the ID to target to send a request (or response) to this client
	TargetID string
	// Name client instance name
	Name string
	// PSClient base pubsub client
	PSClient PubSubClient
	// MsgRetentionTTL PubSub message TTL, after which the message is purged.
	MsgRetentionTTL time.Duration
	// LogTags metadata fields to include in the logs
	LogTags log.Fields
	// CustomLogModifiers additional log metadata modifiers to use
	CustomLogModifiers []LogMetadataModifier
	// SupportWorkerCount number of support workers to spawn to process incoming messages
	SupportWorkerCount int
	// TimeoutEnforceInt interval between request timeout checks
	TimeoutEnforceInt time.Duration

	// SupportTaskMetricsHelper metrics collection helper for the support tasks
	SupportTaskMetricsHelper TaskProcessorMetricHelper
}

type Queue[V any] interface {
	/*
		Len get the current queue length

			@return current queue length
	*/
	Len() int

	/*
		Push enqueue data

			@param data V - data to enqueue
	*/
	Push(data V) error

	/*
		Pop dequeue data

			@return data from queue
			@error ErrorNoDataAvailable - queue is empty
	*/
	Pop() (V, error)
}

type RRInboundRequestHandler func(
	ctxt context.Context, request interface{}, origMsg ReqRespMessage,
) (interface{}, error)

type RRMessageParser func(rawMsg []byte) (interface{}, error)

type ReqRespMessage struct {
	// RequestID request ID associated with this message
	RequestID string `json:"request" validate:"required"`
	// SenderID message sender ID
	SenderID string `json:"sender" validate:"required"`
	// TargetID message target ID
	TargetID string `json:"target" validate:"required"`
	// IsRequest whether the message is a request message
	IsRequest bool `json:"is_request"`
	// Timestamp message timestamp
	Timestamp time.Time `json:"timestamp"`
	// Metadata message metadata
	Metadata map[string]string `json:"meta,omitempty"`
	// Payload message payload
	Payload []byte `json:"payload,omitempty"`
}

type ReqRespMessageHandler func(ctxt context.Context, msg ReqRespMessage) error

type ReqRespTimeoutHandler func(ctxt context.Context) error

type RequestCallParam struct {
	// RespHandler response message handler callback
	RespHandler ReqRespMessageHandler
	// ExpectedResponsesCount the expected number of responses to receive. Once this many responses
	// are received, the request is considered to be complete.
	ExpectedResponsesCount int
	// Blocking whether the request call is blocking
	Blocking bool
	// Timeout the request timeout if it has not received all responses after this duration
	Timeout time.Duration
	// TimeoutHandler request timeout handler callback
	// TODO FIXME: implement request timeout handling
	TimeoutHandler ReqRespTimeoutHandler
}

type RequestResponseClient interface {
	/*
		SetInboundRequestHandler set the inbound request handler

		 @param ctxt context.Context - execution context
		 @param handler ReqRespMessageHandler - the handler to use
	*/
	SetInboundRequestHandler(ctxt context.Context, handler ReqRespMessageHandler) error

	/*
		Request make a new request

		 @param ctxt context.Context - execution context
		 @param targetID string - target ID this request is destined for
		 @param message []byte - request message payload
		 @param metadata map[string]string - request metadata
		 @param callParam RequestCallParam - request call parameters
		 @return request ID
	*/
	Request(
		ctxt context.Context,
		targetID string,
		message []byte,
		metadata map[string]string,
		callParam RequestCallParam,
	) (string, error)

	/*
		Respond respond to an inbound request

		 @param ctxt context.Context - execution context
		 @param originalReq ReqRespMessage - original request
		 @param message []byte - response message payload
		 @param metadata map[string]string - request metadata
		 @param blocking bool - whether the call is blocking
	*/
	Respond(
		ctxt context.Context,
		originalReq ReqRespMessage,
		message []byte,
		metadata map[string]string,
		blocking bool,
	) error

	/*
		Stop stop any support background tasks which were started

		 @param ctxt context.Context - execution context
	*/
	Stop(ctxt context.Context) error
}

type RequestResponseDriver struct {
	Component
	Client        RequestResponseClient
	PayloadParser RRMessageParser
	// contains filtered or unexported fields
}

type RestAPIBaseResponse struct {
	// Success indicates whether the request was successful
	Success bool `json:"success" validate:"required"`
	// RequestID gives the request ID to match against logs
	RequestID string `json:"request_id" validate:"required"`
	// Error are details in case of errors
	Error *ErrorDetail `json:"error,omitempty"`
}

type RestAPIHandler struct {
	Component
	// CallRequestIDHeaderField the HTTP header containing the request ID provided by the caller
	CallRequestIDHeaderField *string
	// DoNotLogHeaders marks the set of HTTP headers to not log
	DoNotLogHeaders map[string]bool
	// LogLevel configure the request logging level
	LogLevel HTTPRequestLogLevel
	// MetricsHelper HTTP request metric collection agent
	MetricsHelper HTTPRequestMetricHelper
}

type RestRequestOAuthTokenKey struct{}

type RestRequestParam struct {
	// ID is the request ID
	ID string `json:"id"`
	// Host is the request host
	Host string `json:"host" validate:"required,fqdn"`
	// URI is the request URI
	URI string `json:"uri" validate:"required,uri"`
	// Method is the request method
	Method string `json:"method" validate:"required,oneof=GET HEAD PUT POST PATCH DELETE OPTIONS"`
	// Referer is the request referer string
	Referer string `json:"referer"`
	// RemoteAddr is the request
	RemoteAddr string `json:"remote_address"`
	// Proto is the request HTTP proto string
	Proto string `json:"http_proto"`
	// ProtoMajor is the request HTTP proto major version
	ProtoMajor int `json:"http_version_major"`
	// ProtoMinor is the request HTTP proto minor version
	ProtoMinor int `json:"http_version_minor"`
	// RequestHeaders additional request headers
	RequestHeaders http.Header
	// Timestamp is when the request is first received
	Timestamp time.Time
}

type RestRequestParamKey struct{}

type Sequencer interface {
	/*
		NextValue returns the next value in the sequence
	*/
	NextValue() float64
}

type TaskProcessor interface {
	/*
		Submit submits a new task parameter to be processed by a handler

		 @param ctx context.Context - calling context
		 @param newTaskParam interface{} - task-parameter
		 @return whether successful
	*/
	Submit(ctx context.Context, newTaskParam interface{}) error

	/*
		SetTaskExecutionMap update the mapping between task-parameter object and its associated
		handler function.

		The task-parameter object contains information need to execute a particular task. When
		a user wants to execute a task, the user is submitting a task-parameter object via Submit.
		The module finds the associated handler function and calls it with the task-parameter object.

		 @param newMap map[reflect.Type]TaskHandler - map of task handlers to various task-parameter
		 object types
		 @return whether successful
	*/
	SetTaskExecutionMap(newMap map[reflect.Type]TaskProcessorSupportHandler) error

	/*
		AddToTaskExecutionMap add new (task-parameter, handler function) mapping to the existing set.

		 @param parameterType reflect.Type - task-parameter object type
		 @param handler TaskHandler - task handler
		 @return whether successful
	*/
	AddToTaskExecutionMap(parameterType reflect.Type, handler TaskProcessorSupportHandler) error

	/*
		StartEventLoop starts one daemon thread for processing the submitted task-parameters

		 @param wg *sync.WaitGroup - wait group
		 @return whether successful
	*/
	StartEventLoop(wg *sync.WaitGroup) error

	/*
		StopEventLoop stops the daemon threads

		 @return whether successful
	*/
	StopEventLoop() error
}

type TaskProcessorMetricHelper interface {
	/*
		RecordSubmit record task submission

			@param instance string - task processor instance name
			@param successful bool - whether the operation was successful
	*/
	RecordSubmit(instance string, successful bool)

	/*
		RecordSubmit record task processed

			@param instance string - task processor instance name
	*/
	RecordProcessed(instance string)
}

type TaskProcessorSupportHandler func(taskParam interface{}) error

type TimeoutHandler func() error