session

type Driver interface {
	/*
		Start the driver daemon threads.

		These support threads will read INPUT from REDIS buffers and write output to REDIS buffers.

			@param parentCtx context.Context - driver execution's parent context
			@returns `models.ConsistencyError` driver is already running
			@returns `models.RuntimeError` any starting issues encountered
			@returns `models.PTYError` PTY starting issues
	*/
	Start(parentCtx context.Context) error

	/*
		Stop the daemon threads of the driver

			@param ctx context.Context - execution context
			@returns `models.ConsistencyError` driver is not running
			@returns `models.RuntimeError` any shutdown issues encountered
	*/
	Stop(ctx context.Context) error
}

type Manager interface {
	// Start the session manager
	Start(ctx context.Context) error

	// Stop the session manager
	Stop(ctx context.Context) error

	/*
		StartSession bring up a session runner for an existing session, and start the runner.

			@param ctx context.Context - execution context
			@param sessionName string - session to bring up
			@param blocking bool - whether this is a blocking call
	*/
	StartSession(ctx context.Context, sessionName string, blocking bool) error

	/*
		StopSession bring the session back to IDLE and unload its runner.

			@param ctx context.Context - execution context
			@param sessionName string - session to unload
			@param blocking bool - whether this is a blocking call
	*/
	StopSession(ctx context.Context, sessionName string, blocking bool) error

	/*
		HandleStartSession handler function called by worker task engine to process `StartSession`

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param sessionName string - session to bring up
			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleStartSession(sessionName string, onComplete func(ctx context.Context, err error)) error

	/*
		HandleStopSession handler function called by worker task engine to process `StopSession`

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param sessionName string - session to unload
			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleStopSession(sessionName string, onComplete func(ctx context.Context, err error)) error

	/*
		ChangeOutputBufferCapacity change session output buffer capacity.

		This can only be performed on IDLE sessions.

			@param ctx context.Context - execution context
			@param sessionName string - session to change
			@param newCap int64 - new output buffer capacity
			@param blocking bool - whether this is a blocking call
	*/
	ChangeOutputBufferCapacity(
		ctx context.Context, sessionName string, newCap int64, blocking bool,
	) error

	/*
		HandleChangeOutputBufferCapacity handler function called by worker task engine to process
		`ChangeOutputBufferCapacity`

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param sessionName string - session to change
			@param newCap int64 - new output buffer capacity
			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleChangeOutputBufferCapacity(
		sessionName string, newCap int64, onComplete func(ctx context.Context, err error),
	) error

	/*
		HandleSessionIdleNotify callback function used by session runner to indicate the
		managed session went IDLE before any shutdown command was given.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param sessionName string - the session which stopped
	*/
	HandleSessionIdleNotify(sessionName string)

	/*
		HandleSessionIPCProcessError callback function used by session runner to indicate the
		managed session encountered issues operating the REDIS IPC queue.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param sessionName string - the session which stopped
	*/
	HandleSessionIPCProcessError(sessionName string, sessionErr error)

	/*
		StopAllSessions tear down every currently active session runner.

		This is a bulk shutdown intended only for use while the manager itself is stopping.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param ctx context.Context - execution context
			@param blocking bool - whether this is a blocking call
	*/
	StopAllSessions(ctx context.Context, blocking bool) error

	/*
		HandleStopAllSessions handler function called by worker task engine to process
		`StopAllSessions`.

		Each active runner is simply torn down via its `Stop`; the session is NOT transitioned back
		to IDLE here. On the next manager start, any session left in READY state is reset to IDLE.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleStopAllSessions(onComplete func(ctx context.Context, err error)) error
}

type NewSessionManagerParams struct {
	// InstanceName manager instance name
	InstanceName string `validate:"required"`

	// PersistenceFactory factory function to generate prepare new persistence clients
	PersistenceFactory func() (db.Client, error) `validate:"required"`

	// RedisClient the REDIS client
	RedisClient goutilsRedis.Client `validate:"required"`

	// DriverFactory session driver factory function
	DriverFactory driverFactoryFunc `validate:"required"`

	// WorkerFactory worker task processor factory function
	WorkerFactory taskProcessorFactoryFunc `validate:"required"`

	// RunnerFactory session runner factory function
	RunnerFactory func(parentCtx context.Context, params NewSessionRunnerParams) (Runner, error) `validate:"required"`
}

type NewSessionRunnerParams struct {
	// SessionName name of session to operate
	SessionName string `validate:"required,session_name_type"`

	// PersistenceFactory factory function to generate prepare new persistence clients
	PersistenceFactory func() (db.Client, error) `validate:"required"`

	// RedisClient the REDIS client
	RedisClient goutilsRedis.Client `validate:"required"`

	// DriverFactory session driver factory function
	DriverFactory driverFactoryFunc `validate:"required"`

	// WorkerFactory worker task processor factory function
	WorkerFactory taskProcessorFactoryFunc `validate:"required"`

	// SessionIdleNotify callback function to trigger when the session went back to the IDLE state
	SessionIdleNotify func() `validate:"required"`

	// IPCProcessErrorNotify callback function to trigger when the IPC read process
	// encounters errors
	IPCProcessErrorNotify func(err error) `validate:"required"`
}

type Runner interface {
	// Start the session runner
	Start(ctx context.Context) error

	// Stop the session runner
	Stop(ctx context.Context) error

	/*
		StartSession bring the session to `READY` state

			@param ctx context.Context - execution context
			@param blocking bool - if true, block until the request completes; if false,
			    submit the request and return immediately
	*/
	StartSession(ctx context.Context, blocking bool) error

	/*
		StopSession bring the session back to `IDLE` state

			@param ctx context.Context - execution context
			@param blocking bool - if true, block until the request completes; if false,
			    submit the request and return immediately
	*/
	StopSession(ctx context.Context, blocking bool) error

	/*
		SubmitCommands submit commands to the session driver

			@param ctx context.Context - execution context
			@param commands []models.SessionInputCommand - commands to submit to driver
	*/
	SubmitCommands(ctx context.Context, commands []models.SessionInputCommand) error

	/*
		HandleStartSession handler function called by worker task engine to process `StartSession`.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleStartSession(onComplete func(ctx context.Context, err error)) error

	/*
		HandleStopSession handler function called by worker task engine to process `StopSession`.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleStopSession(onComplete func(ctx context.Context, err error)) error

	/*
		HandleSubmitCommands handler function called by worker task engine to process `SubmitCommands`.

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param commands []models.SessionInputCommand - commands to submit to the driver
			@param onComplete func(ctx context.Context, err error) - callback function triggered
			    upon completion
	*/
	HandleSubmitCommands(
		commands []models.SessionInputCommand, onComplete func(ctx context.Context, err error),
	) error

	/*
		HandleIPCRequestMessage handler function called by IPC receive loop to process
		individual messages

		Only exposed for testing purposes. DO NOT DIRECTLY USE IN PRODUCTION.

			@param newMessage models.IPCMessageEnvelope - message to process
	*/
	HandleIPCRequestMessage(newMessage models.IPCMessageEnvelope) error
}