goutils

type AlreadyExistsError struct{ BaseError }

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 BadInputError struct{ BaseError }

type BaseError struct {
	// Name identifies the concrete error type in the rendered message.
	Name string
	// Message is the human-readable description of the error.
	Message string
	// Core is the wrapped underlying error, if any.
	Core error
	// Stack holds the program counters captured at construction, if requested.
	Stack []uintptr
}

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 ConsistencyError struct{ BaseError }

type ContainerStopSignalENUMType string

type ContainerTimeoutPolicyENUMType string

type DockerError struct{ BaseError }

type Enum[T ~string] interface {
	~string
	// Values returns the complete set of permitted members for the ENUM type.
	Values() []T
}

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 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 HTTPRequestError struct {
	BaseError
	// StatusCode is the HTTP status code returned by the upstream request.
	StatusCode int
}

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 MCPHandler struct {
	Component

	// LogLevel configure the request logging level
	LogLevel HTTPRequestLogLevel

	// EnumTypeSchemas the per-Go-type enumerated JSON schemas handed to jsonschema-go so ENUM
	// fields in a tool's input emit a proper enumeration rather than a bare string. Must be
	// allocated before use (e.g. by the struct embedding this handler); populate it via
	// MCPInstallEnumSchema and treat it as read-only thereafter.
	EnumTypeSchemas map[reflect.Type]*jsonschema.Schema
}

type MCPRequestParam struct {
	// ID is the request session ID
	ID string `json:"id"`
	// IsToolCall whether the request is tool call
	IsToolCall bool `json:"is_tool_call"`
	// Method is the request method
	Method string `json:"method"`
	// ToolName tool being called
	ToolName string `json:"tool_name,omitempty"`
	// ToolArgs tool call arguments
	ToolArgs json.RawMessage `json:"tool_args,omitempty"`
	// Timestamp is when the request is first received
	Timestamp time.Time
}

type MCPRequestParamKey struct{}

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 NoDataAvailableError struct{}

type NotFoundError struct{ BaseError }

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 ObjectStoreError struct{ BaseError }

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 PubSubError struct {
	BaseError
	// Operation is the PubSub API call that failed (e.g. "CreateTopic").
	Operation string
}

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 RedisError struct{ BaseError }

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
	// LogRequestPayload when true, enables dumping of the request payload to STDOUT.
	// This is a debug-only facility; see RequestPayloadDumpMiddleware for the caveats.
	LogRequestPayload bool
	// 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 RuntimeError struct{ BaseError }

type S3Client interface {
	/*
		ListBuckets get a list of available buckets at the server

			@param ctx context.Context - execution context
			@returns list of bucket names
	*/
	ListBuckets(ctx context.Context) ([]string, error)

	/*
		ListObjects get a list of objects in a bucket

			@param ctx context.Context - execution context
			@param bucket string - the bucket name
			@param prefix *string - optionally, specify the object prefix to filter on
			@param startingKey *string - optionally, list keys lexically after this one
			       (exclusive: the given key itself is not returned). S3 paginates by
			       key, not offset, so pass the last key of a previous page to continue.
			@param maxKeys *int - optionally, cap the total number of keys returned. If
			       nil, all matching keys are returned.
			@return list of bucket objects
	*/
	ListObjects(
		ctx context.Context,
		bucket string,
		prefix *string,
		startingKey *string,
		maxKeys *int,
	) ([]string, error)

	/*
		CreateBucket create a bucket

			@param ctx context.Context - execution context
			@param bucket string - new bucket name
	*/
	CreateBucket(ctx context.Context, bucket string) error

	/*
		DeleteBucket delete a bucket

			@param ctx context.Context - execution context
			@param bucket string - new bucket name
	*/
	DeleteBucket(ctx context.Context, bucket string) error

	/*
		PutObject put a new object into a bucket

		A SHA-256 checksum is always computed and stored with the object, so it is
		available later via GetObjectStat.

			@param ctx context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKey string - target object name within the bucket
			@param data io.Reader - data reader to the content
			@param expectedSize int64 - expected object size, or -1, if unknown
			@param contentType *string - if specified, the object MIME type; otherwise
			       the object store defaults to "application/octet-stream".
	*/
	PutObject(
		ctx context.Context,
		bucket string,
		objectKey string,
		data io.Reader,
		expectedSize int64,
		contentType *string,
	) error

	/*
		CopyObject copy an object from one bucket/key to another. The source and
		destination buckets may be the same or different. The copy is performed
		server-side and this call blocks until it completes.

		When newMIMEType is set, the destination's Content-Type is rewritten to
		that value. NOTE: this uses a single-part server-side copy, which S3 caps
		at 5GiB; larger objects will fail.

			@param ctx context.Context - execution context
			@param srcBucket string - the source bucket
			@param srcKey string - the source object key
			@param dstBucket string - the destination bucket
			@param dstKey string - the destination object key
			@param newMIMEType *string - if specified, change the destination object MIME type.
	*/
	CopyObject(
		ctx context.Context,
		srcBucket string,
		srcKey string,
		dstBucket string,
		dstKey string,
		newMIMEType *string,
	) error

	/*
		GetObject get an object from a bucket

		The function performs a object stat read first before returning the object reader. However,
		because the object is not read here, it is not guaranteed that object reader will not
		encounter errors later on.

			@param ctx context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKey string - target object name within the bucket
			@returns basic object stat and associated content reader
	*/
	GetObject(
		ctx context.Context, bucket string, objectKey string,
	) (S3ObjectStat, S3ObjectReader, error)

	/*
		GetObjectStat get object file stats

		The returned CheckSum may be empty; see S3ObjectStat.CheckSum.

			@param ctx context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKey string - target object name within the bucket
			@returns object file stats
	*/
	GetObjectStat(
		ctx context.Context, bucket string, objectKey string,
	) (S3ObjectStat, error)

	/*
		DeleteObject delete an object from a bucket

			@param ctxt context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKey string - target object name within the bucket
	*/
	DeleteObject(ctx context.Context, bucket, objectKey string) error

	/*
		DeleteObjects delete a group of objects from a bucket

			@param ctxt context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKeys []string - target object names within the bucket
			@returns map of per-object-key deletion errors (empty if all succeeded)
			@returns error a function-level error, e.g. if the context is cancelled
			         before the bulk delete completes

		On cancellation both returns may be non-nil: the map holds the per-object
		failures reported before the delete stopped, and the error signals the
		cancellation. When the error is non-nil the map is not exhaustive, so a
		key's absence does not confirm it was deleted.
	*/
	DeleteObjects(
		ctx context.Context, bucketName string, objectKeys []string,
	) (map[string]error, error)

	/*
		GeneratePresignedGetURL generate presigned GET URL from S3 server for a particular
		bucket and object key.

			@param ctx context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKey string - target object key
			@param ttl time.Duration - TTL for the pre-signed URL
			@returns presigned URL
	*/
	GeneratePresignedGetURL(
		ctx context.Context, bucketName string, objectKey string, ttl time.Duration,
	) (*url.URL, error)

	/*
		GeneratePresignedPutURL generate presigned PUT URL from S3 server for a particular
		bucket and object key.

		The returned URL binds the upload to an exact `Content-Length` and a base64-encoded
		SHA-256 of the body (sent as the `x-amz-checksum-sha256` header). The HTTP client
		using this URL must send both headers with these exact values, or the object store
		will reject the request with a signature or checksum error.

			@param ctx context.Context - execution context
			@param bucketName string - target bucket name
			@param objectKey string - target object key
			@param objectSize int64 - exact size in bytes of the object the caller will upload
			@param sha256Sum string - base64-encoded SHA-256 of the object content
			@param ttl time.Duration - TTL for the pre-signed URL
			@returns presigned URL
	*/
	GeneratePresignedPutURL(
		ctx context.Context,
		bucketName string,
		objectKey string,
		objectSize int64,
		sha256Sum string,
		ttl time.Duration,
	) (*url.URL, error)
}

type S3Config struct {
	// ServerEndpoint S3 server endpoint
	ServerEndpoint string `json:"endpoint" validate:"required"`
	// UseTLS whether to TLS when connecting
	UseTLS bool `json:"useTLS"`
	// Region optional S3 region. When set, it is used as the client region (which,
	// among other things, is the region newly created buckets are placed in). When
	// nil, the region is left for the server / minio to resolve automatically.
	Region *string `json:"region,omitempty" validate:"omitempty"`
	// Creds S3 credentials
	Creds S3Credentials `json:"creds,omitempty" validate:"omitempty"`
}

type S3Credentials struct {
	// AccessKey object store access key
	AccessKey string `json:"access_id" validate:"required"`
	// SecretAccessKey object store secret access key
	SecretAccessKey string `json:"secret_id" validate:"required"`
}

type S3ObjectReader interface {
	io.Reader
	io.ReaderAt
	io.Seeker
	io.Closer
}

type S3ObjectStat struct {
	// MIMEType object MIME type
	MIMEType string
	// Size object file size
	Size int64
	// CheckSum object SHA-256 checksum, base64-encoded. May be empty for objects
	// that were not uploaded with a SHA-256 checksum (e.g. by other tools, or via
	// multipart uploads that store a composite checksum). Objects uploaded through
	// PutObject always carry one.
	CheckSum string
}

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

type ShutdownError struct{ BaseError }

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 TimeoutError struct{ BaseError }

type TimeoutHandler func() error

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

type ValidationError struct{ BaseError }