db

type Client interface {
	/*
		RunSQLInTransaction execute SQL calls within a transaction

			@param ctx context.Context - execution context
			@param coreLogic func(ctx context.Context, tx *gorm.DB) error - the callback to execute
	*/
	RunSQLInTransaction(
		ctx context.Context, coreLogic func(ctx context.Context, tx *gorm.DB) error,
	) error

	/*
		RunSQLInTransaction utilize a `Database` instance in a transaction

			@param ctx context.Context - execution context
			@param coreLogic func(ctx context.Context, dbClient Database) error - the callback to execute
	*/
	UseDatabaseInTransaction(
		ctx context.Context, coreLogic func(ctx context.Context, dbClient Database) error,
	) error
}

type CommonListEntryQueryFilter struct {
	// Limit max number of entries to return
	Limit *int `json:"limit,omitempty" validate:"omitempty,gte=1" jsonschema:"max number of entries to return"`
	// Offset number of leading entries to skip
	Offset *int `json:"offset,omitempty" validate:"omitempty,gte=0" jsonschema:"number of leading entries to skip"`
}

type Database interface {
	// Ready check whether the DB connection is working
	Ready() error

	/*
		DefineNewSession define a new session

			@param ctx context.Context - execution context
			@param name string - session name, can only contain alphanumeric characters and -
			@param description *string - session description
			@param command models.SessionCommand - the command to execute
			@param outputBufferCapacity int64 - buffering capacity for holding command output history
			@param driverParams interface{} - session driver parameters, allowed types are:
			    * SessionDriverPTYParams
			@returns new session entry
			@returns `models.ValidationError` bad data
			@returns `models.PersistenceError` persistence layer failure
	*/
	DefineNewSession(
		ctx context.Context,
		name string,
		description *string,
		command models.SessionCommand,
		outputBufferCapacity int64,
		driverParams interface{},
	) (models.Session, error)

	/*
		GetSession fetch a session by name

			@param ctx context.Context - execution context
			@param name string - session name
			@returns session entry
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.PersistenceError` persistence layer failure
	*/
	GetSessionByName(ctx context.Context, name string) (models.Session, error)

	/*
		MarkSessionIdle mark a session is IDLE

			@param ctx context.Context - execution context
			@param name string - session name
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.ConsistencyError` state transition is not acceptable
			@returns `models.PersistenceError` persistence layer failure
	*/
	MarkSessionIdle(ctx context.Context, name string) error

	/*
		MarkSessionReady mark a session is Ready

			@param ctx context.Context - execution context
			@param name string - session name
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.ConsistencyError` state transition is not acceptable
			@returns `models.PersistenceError` persistence layer failure
	*/
	MarkSessionReady(ctx context.Context, name string) error

	/*
		UpdateSessionOutputBufCapacity change the output buffer capacity of a session.

		This can only be performed on IDLE sessions.

			@param ctx context.Context - execution context
			@param name string - session name
			@param newCap int64 - new output buffer capacity
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.ConsistencyError` session in wrong state
			@returns `models.PersistenceError` persistence layer failure
	*/
	UpdateSessionOutputBufCapacity(ctx context.Context, name string, newCap int64) error

	/*
		UpdateSessionRunMode change the runner mode of a session

		This can only be performed on IDLE sessions.

			@param ctx context.Context - execution context
			@param name string - session name
			@param newMode models.SessionRunnerModeTypeENUMType - new runner mode
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.ConsistencyError` session in wrong state
			@returns `models.PersistenceError` persistence layer failure
	*/
	UpdateSessionRunMode(
		ctx context.Context, name string, newMode models.SessionRunnerModeTypeENUMType,
	) error

	/*
		UpdateSessionCommand change the session command

		This can only be performed on IDLE sessions.

			@param ctx context.Context - execution context
			@param name string - session name
			@param newCommand models.SessionCommand - new session command
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.ConsistencyError` session in wrong state
			@returns `models.PersistenceError` persistence layer failure
	*/
	UpdateSessionCommand(ctx context.Context, name string, newCommand models.SessionCommand) error

	/*
		UpdateSessionDriver change the session driver parameters

		This can only be performed on IDLE sessions.

			@param ctx context.Context - execution context
			@param name string - session name
			@param driverParams interface{} - new session driver parameters
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.ConsistencyError` session in wrong state
			@returns `models.ValidationError` new driver parameters are not valid
			@returns `models.PersistenceError` persistence layer failure
	*/
	UpdateSessionDriver(ctx context.Context, name string, driverParams interface{}) error

	/*
		UpdateSessionName change session name

			@param ctx context.Context - execution context
			@param name string - session name
			@param newName string - new session name
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.PersistenceError` persistence layer failure
	*/
	UpdateSessionName(ctx context.Context, name string, newName string) error

	/*
		UpdateSessionDescription change session description

			@param ctx context.Context - execution context
			@param name string - session name
			@param newDescription *string - new session description
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.PersistenceError` persistence layer failure
	*/
	UpdateSessionDescription(ctx context.Context, name string, newDescription *string) error

	/*
		DeleteSession delete a session

		This can only be performed on IDLE sessions.

			@param ctx context.Context - execution context
			@param name string - session name
			@returns `models.UnknownSessionError` if session is unknown
			@returns `models.PersistenceError` persistence layer failure
	*/
	DeleteSession(ctx context.Context, name string) error

	/*
		ListSessions list sessions

			@param ctx context.Context - execution context
			@param filter SessionQueryFilter - query filter
			@returns list of session according to the query filter
			@returns `models.PersistenceError` persistence layer failure
	*/
	ListSessions(ctx context.Context, filters SessionQueryFilter) ([]models.Session, error)
}

type SessionQueryFilter struct {
	CommonListEntryQueryFilter
	// SimilarName filter for session whose name is similar to this, case insensitive.
	SimilarName *string `json:"name,omitempty" jsonschema:"filter for session whose name is similar to this, case insensitive"`
	// TargetDriverType fetch session using this driver type
	TargetDriverType []models.SessionDriverTypeENUMType `json:"driver,omitempty" validate:"omitempty,dive,session_driver_type" jsonschema:"fetch session using this driver type"`
	// TargetStates fetch session in this state
	TargetStates []models.SessionStateENUMType `json:"state,omitempty" validate:"omitempty,dive,session_state_type" jsonschema:"fetch session in this state"`
	// OrderByName whether to order the returns by name
	OrderByName bool `json:"order_by_name,omitempty" jsonschema:"whether to order the returns by name"`
	// OrderDirection ordering direction `asc` or `desc`
	OrderDirection *string `json:"order_dir,omitempty" validate:"omitempty,oneof=asc desc ASC DESC" jsonschema:"ordering direction asc or desc"`
}