====== Константы ======

Значения констант влияют на работу функций и процедур. Если по каким-то причинам значения заданные здесь не подходят, можно после импорта переназначить эти константы.

^ Имя ^ Значение по умолчанию ^ Описание ^
| ''VARIABLE_PREFIX'' | ''ru.a0fs.app''  | Префикс переменных и иных элементов, которые сохраняются во внутренних структурах ''bottle'' |
| ''IP_HEADER''       | ''X-Real-IP''    | Заголовок, в котором реверс-прокси хранит реальный IP клиента.
| ''REQ_ID_HEADER''   | ''X-Request-Id'' | Заголовок запроса, в котором реверс-прокси хранит уникальный ID запроса. Данные ID полезны для мультисерверной инфраструктуры балансировки с единой точкой хранения журналов. Nginx даёт достаточно уникальный ID для трассировки запроса в журналах приложения. Выставляется этот ID через параметр конфигурации <code nginx>proxy_set_header X-Request-Id $request_id;</code> |
| ''CONN_ID_HEADER'' | ''X-Conn-ID'' | Идентификатор текущего соединения. Легковесный способ идентифицировать запрос. Добавляется на стороне nginx через: <code nginx>proxy_set_header X-Conn-ID $connection-$connection_requests;</code> |


====== Функции и процедуры ======

===== get_client_ip() =====

Получение реального адреса клиента.

Пытается получить адрес клиента из специальной переменной реверс-прокси ''X-Real-IP''. В случае неудачи, берёт IP узла, откуда пришёл запрос.

**Проверки на установку IP доверенным источником не производится.** Поскольку приложения не выставляются наружу без прикрытия ''nginx'', который можно соответственно настроить. Это не считается проблемой.

<code>
get_client_ip([request])
</code>

**Возвращает:** Строку с IP клиента.

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, из которого добываются нужные сведения |


===== get_session_fingerprint() =====

Конструируем некий отпечаток пользовательской сессии.

В качестве параметра принимается всё, что должно участвовать в создании отпечатка. Это всё превращается в строку и подмешивается в хэш. То есть функции можно передать всё, что необходимо для идентификации сессии, и что в состоянии дать значимую строку (при преобразовании ''str()'' это должно быть что-то получше чем имя класса и спецсимволы)

<code>
get_session_fingerprint(add_params..., [request])
</code>

**Возвращает:** Строку с значением SHA512 от соединённых элементов, данных в параметрах, и некоторых значимых элементов самого запроса (идентификатор браузера и IP источника запроса.

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''add_params'' | ''Any'' |  --  | Параметры (можно добавлять сколько угодно), подмешиваемые в вычисляемый идентификатор клиента. |
| ''request''    | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, относительно которого берутся параметры для вычисления |


===== get_env() =====

Возвращает значения из хранилища контекста запроса ''bottle''. Данный контекст уникален для каждого запроса и в нём могут хранится различные объекты Python, сохранённые обрабатывающим приложением.

<code>
get_env(name, [default], [request])
</code>

**Возвращает:** Имеющееся в контексте значение, или ''default'', если его сохранили. Тип объекта контролируется разработчиком.

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''name''    | ''str''                |  --                | Имя переменной |
| ''default'' | ''Any''                | ''None''           | Значение по умолчанию, которое возвращается, если в контексте отсутствует соответствующая переменная |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, из которого добываются нужные сведения |


===== set_env() =====

Добавляет в контекст переменную, которую затем можно запрашивать через [[#get_env]].

<code>
set_env(name, value, [request])
</code>

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''name''    | ''str''                |  --                | Имя переменной |
| ''value''   | ''Any''                |  --                | Значение, сохраняемое в контекст запроса |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, из которого добываются нужные сведения |


===== make_response() =====

Формирование JSON ответа.

Полезно при программировании JSON REST-API. Даёт больший контроль над ответом.

<code>
make_response([data], [status], [cookies], [remove_cookies])
</code>

**Возвращает:** ''bottle.HTTPResponse'', включающий все заданные функции параметры, который можно отдавать в качестве ответа обработчика URL в ''bottle''

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''data'' | ''Any'' | ''None'' | Любой объект, которые может быть преобразован в JSON. |
| ''status'' | ''int'' | ''200'' | HTTP-код ответа. |
| ''cookies'' | ''List[Cookie]'' | ''None'' | Устанавливаемые cookie |
| ''remove_cookies'' | ''List[Union[Cookie, str]]'' | ''None'' | Удаляемые cookie, заданные как самими объектами ''Cookie'', так и именами |

В качестве значения ''data'' может быть задана любая осмысленная конструкция. Функция способна к преобразованию в json-вид всех базовых конструкций языка (числа, строки, словари, списки, кортежи). Остальное она приводит к строке и возвращает строку. Конструкции могут быть вложены друг в друга.


===== get_request_json() =====

Если запрос имеет тело JSON, и фреймворк это распознал, то функция вернёт этот JSON.

<code>
get_request_json()
</code>

**Возвращает:** Словарь, содержащий данный JSON


===== get_cookie() =====

Получить значение ''cookie'' с заданным именем из текущего запроса.

<code>
get_cookie(name, [request])
</code>

**Возвращает:** Строку со значением cookie или ''None''

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''name'' | ''str'' |  --  | Имя cookie в запросе |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, из которого добываются нужные сведения |


===== get_param() =====

Получить из запроса переданный пользователем параметр.

<code>
get_param(name, [param_type], [default], [postprocess], [param_source], [request])
</code>

**Возвращает:** Переданное пользователем значение

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''name'' | ''str'' |  --  | Имя параметра |
| ''param_type'' | ''type'' или строка ''json'' | ''str''  | Тип параметра, к которому его следует привести перед возвращением. Если задано '''json' '', будет выполнена попытка декодировать поле как JSON строку. |
| ''default''    | ''Any''  | ''None'' | Если не задан параметр, возвращается это |
| ''postprocess'' | ''bool'' | ''True'' | Выполнять ли попытку обработки результата |
| ''param_source'' | ''None'', '''get' '', '''post' '' | ''None'' | Источник параметра, если не задано, то [[https://bottlepy.org/docs/dev/api.html#bottle.BaseRequest.params|используется все параметры]] |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, из которого добываются нужные сведения |

Приведение параметров к типу - очень базовая функциональность. Функция не пытается догадываться. Если целевой тип ''bool'' то применяется следующее соответствие:
^ Результат ^ Значение параметра ^
| ''True'' | ''on'', ''yes'', ''1'', ''true'' |
| ''False'' | ''off'', ''no'', ''0'', ''false'' |

Если будет что-то ещё, будет возбуждено исключение.

Обработка результата одна: если целевой тип - строка, то удаляются лидирующие и завершающие пробелы. Чего не ожидается, скажем, в полях паролей.


===== make_log_topic() =====

Сгенерировать подходящий префикс журналирования для данного запроса.

Помогает в журналировании событий, связанных с запросом.

<code>
make_log_topic([user], [request])
</code>

**Возвращает:** Строку, которую можно использовать для инициализации [[lib.py:aw_log:api|объекта лога]]. Строка представляет собой:
<code bash>
${USER}[${IP} | ${REQ_ID} | ${CONN_ID}] - ${URL}
</code>
Где:
  * ''${USER}'' - Переданное имя пользователя или ''_NOUID_'' если ничего передано не было.
  * ''${IP}'' - Результат работы функции [[#get_client_ip|get_client_ip()]].
  * ''${REQ_ID}'' - Значение заголовка ''REQ_ID_HEADER'', если он имеется. В противном случае ничего не подставляется и не выводится разделитель.
  * ''${CONN_ID}'' - Значение заголовка ''CONN_ID_HEADER'', если он имеется. В противном случае ничего не подставляется и не выводится разделитель.
  * ''${URL}'' - Путь переданный в запросе.



^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''user''    | ''str''                | ''None''           | Имя пользователя. Если ''None'', то данная компонента в префиксе не используется |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Объект запроса, из которого добываются нужные сведения |


===== make_error_response() =====

Создание сообщения об ошибке для JSON REST API сервисов.

<code>
make_error_response(code, err, [msg], [remove_cookies], [cookies])
</code>

**Возвращает:** ''bottle.HTTPResponse'', включающий все заданные функции параметры, который можно отдавать в качестве ответа обработчика URL в ''bottle''

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''code'' | ''int'' |  --  | HTTP-код ответа |
| ''err''  | ''Exception'' или ''str'' |  --  | Либо объект исключения, либо название ошибки для обозначения произошедшего пользователю |
| ''msg''  | ''str'' | ''None'' | Сообщение об ошибке, которым можно уточнить произошедшее. Для объекта ''Exception'' данное поле будет получено приведением этого объекта к ''str()'' |
| ''data'' | ''Any'' | ''None'' | Любой объект, которые может быть преобразован в JSON. |
| ''remove_cookies'' | ''List[Union[Cookie, str]]'' | ''None'' | Удаляемые cookie, заданные как самими объектами ''Cookie'', так и именами |
| ''cookies'' | ''List[Cookie]'' | ''None'' | Устанавливаемые cookie |