redis

type Client interface {
	/*
		GetRingBuffer prepare data stream ring buffer client.

		The ring buffer maintains the most recent N bytes of data written to it, based on the
		predefined capacity.

			@param ctx context.Context - execution context
			@param bufferName string - buffer name
			@param capacity int64 - buffer max capacity
			@returns the
	*/
	GetRingBuffer(
		ctx context.Context, bufferName string, capacity int64,
	) (RingBuffer, error)

	/*
		DeleteRingBuffer delete a data stream ring buffer

			@param ctx context.Context - execution context
			@param bufferName string - buffer name
			@returns `REDISError` in case of failure
	*/
	DeleteRingBuffer(ctx context.Context, bufferName string) error

	/*
		GetQueueHandle get handle to a REDIS queue

			@param ctx context.Context - execution context
			@returns the queue
	*/
	GetQueueHandle(ctx context.Context, queueName string) (Queue, error)

	/*
		DeleteQueue delete a queue from REDIS

			@param ctx context.Context - execution context
			@param queueName string - queue name
			@returns `REDISError` in case of failure
	*/
	DeleteQueue(ctx context.Context, queueName string) error

	/*
		Publish a message a onto a REDIS PubSub topic

			@param ctx context.Context - execution context
			@param topic string - topic to publish on
			@param msg QueueMessageEnvelope - the message to publish
			@returns `BadInputError` in case message is not serializing
			@returns `REDISError` in case of failure
	*/
	Publish(ctx context.Context, msg PubSubMessage) error

	/*
		Subscribe for messages on a set of REDIS PubSub topics

			@param ctx context.Context - execution context
			@param subName string - subscriber name
			@param topics []string - the PubSub topics to subscribe on
			@return the subscription runner
	*/
	Subscribe(ctx context.Context, subName string, topics []string) (Subscriber, error)
}

type ConnectionConfig struct {
	// Host of the server
	Host string `json:"host" validate:"required,hostname"`
	// Port of the server
	Port uint16 `json:"port"`
	// DBNumber number of the REDIS database
	DBNumber uint32 `json:"dbNumber"`
}

type PubSubMessage struct {
	// Topic the PubSub topic
	Topic string
	// Message to send or received
	Message QueueMessageEnvelope
}

type PubSubMessageHandler func(ctx context.Context, msg PubSubMessage)

type Queue interface {
	// QueueName get the REDIS queue name
	QueueName() string

	/*
		PushRight push message into queue right

			@param ctx context.Context - execution context
			@param message IPCMessageEnvelope - message to insert
			@param ttl time.Duration - if > 0, optionally set a TTL for the message.
			@return length of queue after insert
	*/
	PushRight(
		ctx context.Context, message QueueMessageEnvelope, ttl *time.Duration,
	) (uint64, error)

	/*
		PushLeft push message into queue left

			@param ctx context.Context - execution context
			@param message IPCMessageEnvelope - message to insert
			@param ttl time.Duration - if > 0, optionally set a TTL for the message.
			@return length of queue after insert
	*/
	PushLeft(
		ctx context.Context, message QueueMessageEnvelope, ttl *time.Duration,
	) (uint64, error)

	/*
		PopRight pop message from queue right

			@param ctx context.Context - execution context
			@param blocking bool - whether this is a blocking operation
			@param maxWait *time.Duration - if blocking, the max duration. Default 5 sec.
			@return message or nil if empty
	*/
	PopRight(
		ctx context.Context, blocking bool, maxWait *time.Duration,
	) (QueueMessageEnvelope, error)

	/*
		PopLeft pop message from queue left

			@param ctx context.Context - execution context
			@param blocking bool - whether this is a blocking operation
			@param maxWait *time.Duration - if blocking, the max duration. Default 5 sec.
			@return message or nil if empty
	*/
	PopLeft(
		ctx context.Context, blocking bool, maxWait *time.Duration,
	) (QueueMessageEnvelope, error)

	/*
		PopLeftAndMove pop message from queue left and move that message to another queue.

		On completion, return the popped message.

			@param ctx context.Context - execution context
			@param destination string - destination queue
			@param insertOnLeft bool - whether to insert on left of destination queue. Default is right.
			@param blocking bool - whether this is a blocking operation
			@param maxWait *time.Duration - if blocking, the max duration. Default 5 sec.
			@return message or nil if empty
	*/
	PopLeftAndMove(
		ctx context.Context,
		destination string,
		insertOnLeft bool,
		blocking bool,
		maxWait *time.Duration,
	) (QueueMessageEnvelope, error)

	/*
		PopRightAndMove pop message from queue right and move that message to another queue.

		On completion, return the popped message.

			@param ctx context.Context - execution context
			@param destination string - destination queue
			@param insertOnLeft bool - whether to insert on left of destination queue. Default is right.
			@param blocking bool - whether this is a blocking operation
			@param maxWait *time.Duration - if blocking, the max duration. Default 5 sec.
			@return message or nil if empty
	*/
	PopRightAndMove(
		ctx context.Context,
		destination string,
		insertOnLeft bool,
		blocking bool,
		maxWait *time.Duration,
	) (QueueMessageEnvelope, error)

	/*
		RemoveAndMove atomically remove a single occurrence of a specific message from this
		queue and, only if it was present, push it onto the destination queue.

		Unlike PopLeftAndMove / PopRightAndMove, the message is targeted by value rather than
		by position, so this is safe to use when this queue holds several unrelated messages.
		The remove and push happen in one atomic step, so the message can never be lost from
		both queues nor duplicated onto the destination if the caller crashes mid-operation.

		If the message is not present in this queue nothing is moved and an error is returned;
		this prevents a caller from injecting a message that did not originate from this queue.

			@param ctx context.Context - execution context
			@param destination string - destination queue
			@param message QueueMessageEnvelope - the specific message to move
			@param insertOnLeft bool - whether to insert on left of destination queue. Default is right.
	*/
	RemoveAndMove(
		ctx context.Context,
		destination string,
		message QueueMessageEnvelope,
		insertOnLeft bool,
	) error

	/*
		PeakLeft read the left most value of the queue without removing it

			@param ctx context.Context - execution context
			@return message or nil if empty
	*/
	PeakLeft(ctx context.Context) (QueueMessageEnvelope, error)

	/*
		PeakRight read the right most (tail) value of the queue without removing it

			@param ctx context.Context - execution context
			@return message or nil if empty
	*/
	PeakRight(ctx context.Context) (QueueMessageEnvelope, error)

	/*
		Length fetch the length of the queue

			@param ctx context.Context - execution context
			@return length of queue
	*/
	Length(ctx context.Context) (uint64, error)

	/*
		Remove delete a message from the queue

			@param ctx context.Context - execution context
			@param message IPCMessageEnvelope - the message to delete
	*/
	Remove(ctx context.Context, message QueueMessageEnvelope) error
}

type QueueMessageEnvelope interface {
	// StringPayload return its payload as a string
	StringPayload() (string, error)
}

type RingBuffer interface {
	/*
		Write a byte slice into the buffer.

		When the data currently in the buffer plus the new slice exceed the buffer capacity,
		the write will wrap around.

		If the byte slice is longer than the capacity of the ring buffer, N, then only the last N
		bytes of the slice is stored.

			@param ctx context.Context - execution context
			@param data []byte - data to write into the buffer
	*/
	Write(ctx context.Context, data []byte) (int64, error)

	/*
		ReadAt read data from the buffer starting at an offset.

		If the offset is older than the currently oldest byte in the buffer,  the offset
		is moved to the oldest byte currently in the buffer.

		If the offset is greater than all data written, nothing is returned.

			@param ctx context.Context - execution context
			@param buf []byte - the receive buffer
			@returns the actual offset
			@returns the number of bytes read
			@returns the total number of bytes written to the buffer
			@returns `REDISError` in case of failure
	*/
	ReadAt(ctx context.Context, buf []byte, offset int64) (int64, int, int64, error)

	/*
		ReadNewest read the newest bytes from the buffer, filling at most `len(buf)` bytes.

		If fewer than `len(buf)` bytes have been written, all available bytes are returned. If
		more than the buffer capacity is requested, only the bytes currently in the buffer are
		returned.

			@param ctx context.Context - execution context
			@param buf []byte - the receive buffer
			@returns the actual offset of the first byte read
			@returns the number of bytes read
			@returns the total number of bytes written to the buffer
			@returns `REDISError` in case of failure
	*/
	ReadNewest(ctx context.Context, buf []byte) (int64, int, int64, error)

	/*
		Total fetch the total bytes written to the buffer

			@param ctx context.Context - execution context
			@returns the total number of bytes written to the buffer
			@returns `REDISError` in case of failure
	*/
	Total(ctx context.Context) (int64, error)

	/*
		AsReadWriteCloser create a wrapper around this buffer so it presents an `io.ReadWriteCloser`
		interface, allowing this buffer to be used other standard IO helper functions.

			@param parentCtx context.Context - the parent execution context for this buffer
			    which allows for clean execution control of the buffer while maintaining
			    standard interface.
			@param initReadOffset int64 - define the starting read index offset on the buffer
			@param dataCheckInt time.Duration - as the buffer `ReadAt` API is non-blocking,
			    this set the interval of the internal polling loop for available data. Minimum
			    value is 1ms.
			@returns interface complaint with `io.ReadWriteCloser`
	*/
	AsReadWriteCloser(
		parentCtx context.Context, initReadOffset int64, dataCheckInt time.Duration,
	) io.ReadWriteCloser
}

type Subscriber interface {
	/*
		Start the subscription message processing support task.

		The caller must provide a handler callback. It is invoked, serially, for each
		received message from the subscriber's single reader goroutine.

			@param parentCtx context.Context - parent execution context for the support process
			@param handler PubSubMessageHandler - callback invoked for each received message
	*/
	Start(parentCtx context.Context, handler PubSubMessageHandler) error

	/*
		Stop the subscription message processing support task

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