rest

type API interface {
	// Получение информации о методе
	Info() *Info

	// Вызывается в самом начале обработки rest, используется, например, первичной настройки или проверок
	Prepare(proc *ProcOptions) (result any, code int, err error)

	// Вызывается перед обращением к базе, используется, например, для добавления дополнительных параметров или проверок
	Before(proc *ProcOptions) (result any, code int, err error)

	// Вызывается после обращения к базе, используется, например, для обогащения результата
	After(proc *ProcOptions) (result any, code int, err error)
}

type ByRow struct {
	Begin []byte // Пишется один раз в начале
	End   []byte // Пишется один раз в конце

	Data []RowData

	RowNum  int  // Количество выданных строк (увеличивается в конце обработки строки)
	IsFinal bool // Финал, Tuner еще раз вызывается после завершения выборки, в первом параметре опять последнее значение
	// contains filtered or unexported fields
}

type ByRowTuner func(br *ByRow, row any) (err error)

type Enumerator func(path string, info *Info) (err error)

type ExecResult struct {
	Method      string           `json:"-" comment:"Method"`
	TotalRows   uint64           `json:"totalRows" comment:"Number of records affected"`
	SuccessRows uint64           `json:"successRows" comment:"Number of records affected (success)"`
	FailedRows  uint64           `json:"failedRows" comment:"Number of records affected (failed)"`
	Rows        []*ExecResultRow `json:"rows,omitempty" comment:"Created records" ref:"execResultRow"`
}

type ExecResultRow struct {
	Code int    `json:"code" comment:"Result code"`
	ID   uint64 `json:"id,omitempty" comment:"ID of the created record"`
	GUID string `json:"guid,omitempty" comment:"GUID of the created record"`
	MessagesBlock
}

type ExternalDocs struct {
	Description string
	URL         string
}

type FieldDef struct {
	JSONname string
	DBname   string
	Type     reflect.Kind
}

type FindModule func(path string) (module *Module, basePath string, extraPath []string, found bool)

type FuncHandler func(proc *ProcOptions) (result any, code int, err error)

type FuncInit func(info *Info) (err error)

type FuncResultTuner func(proc *ProcOptions, result0 any, code0 int, err0 error) (result any, code int, err error)

type Info struct {
	Path             string      // Относительный (от базового) путь в URL
	Name             string      // Имя, желательно  чтобы по правилам имен переменных
	Summary          string      // Краткое описание
	Description      string      // Описание, по умолчанию сформированное из Summary и query параметров
	Tags             []string    // Имена тегов для группировки
	Flags            path.Flags  // Флаги
	Methods          *path.Set   // Цепочки обработки
	Config           any         // Кастомные параметры в конфиг файле
	DBtype           string      // Тип базы. Если пусто, то по умолчанию из конфига
	WithTransactions bool        // Разрешить транзакции
	QueryPrefix      string      // Префикс имени запроса в базу
	Init             FuncInit    // User defined Init
	Prepare          FuncHandler // User defined Prepare function
	Before           FuncHandler // User defined Before function
	After            FuncHandler // User defined After function

	ResultTuner FuncResultTuner // The last step result tuner
	// contains filtered or unexported fields
}

type MessagesBlock struct {
	Messages []string `json:"message,omitempty" comment:"Messages"`
	// contains filtered or unexported fields
}

type Module struct {
	RawURL      string
	RelativeURL string        // URL без учета базовой части
	Handler     API           // Интерфейс метода
	Info        *Info         // Информация о методе
	LogFacility *log.Facility // Log facility
}

type ProcOptions struct {
	LogFacility      *log.Facility       // Предпочтительная facility для логирования
	H                *stdhttp.HTTP       // HTTP листенер
	LogSrc           string              // Строка с ID запроса для MessageWithSource
	Info             *Info               // Информация о методе
	ID               uint64              // ID запроса
	Prefix           string              // Префикс пути запроса (при работе через прокси)
	Path             string              // Путь запроса
	Tail             []string            // Остаток пути
	R                *http.Request       // Запрос
	W                http.ResponseWriter // Интерфейс для ответа
	AuthIdentity     *auth.Identity      // Результаты аутентификации
	Chain            *path.Chain         // Обрабатываемая цепочка
	ChainLocal       path.Chain          // Копия Chain для возможности ее модификации для работы с динамическими объектами. Рекомендуется использовать её, а не Chain.Parent
	Scope            string              // Обрабатываемый Scope
	RawBody          []byte              // Тело запроса. В R.Body уже nil!
	PathParams       any                 // Path параметры
	QueryParams      any                 // Query параметры
	QueryParamsFound misc.BoolMap        // Query параметры, присутствующие в запросе в явном виде
	RequestParams    any                 // Request параметры
	DBtype           string              // Тип базы, если надо изменить на время запроса. Если пусто, то из info

	DBqueryName        string              // Имя запроса к базе данных
	DBqueryVars        []any               // Переменные для формирования запроса
	ResultAsRows       bool                // Возвращать для GET не готовый результат, а *sqlx.Rows, чтобы производить разбор самостоятельно. Актуально для больших результатов.
	DBqueryResult      any                 // Результат выполненения запроса (указатель на слайс) при ResultAsRows==false
	DBqueryRows        *sqlx.Rows          // Результат при ResultAsRows==true
	Fields             []misc.InterfaceMap // Поля (имя из sql запроса) для insert или update. Для select - список полей для выборки из базы, если нужны не все из объекта
	ExcludedFields     misc.StringMap      // Поля ([name]db_name), которые надо исключить из запроса
	InternalExecResult *ExecResult         // Внутренний промежуточный результат выполнения
	ExecResult         *ExecResult         // Результат выполнения Exec
	ExtraHeaders       misc.StringMap      // Дополнительные возвращаемые HTTP заголовки
	Extra              any                 // Произвольные данные от вызывающего
	Custom             any                 // Произвольные пользовательские данные
	// contains filtered or unexported fields
}

type RowData struct {
	Prefix    []byte // Дополнительный блок цикла, который может возвращаться из ByRowTuner и пишется перед основными данными
	Suffix    []byte // Дополнительный блок цикла, который может возвращаться из ByRowTuner и пишется после основных данных
	Separator []byte // Разделитель строк
	Data      any    // Основные данные цикла
}

type Tag struct {
	Name         string
	Aliases      []string
	Description  string
	ExternalDocs ExternalDocs
}

type Tags []*Tag