Сжатие и двоичные данные

Здесь решаются три разные задачи: перевод текста в байты, сжатие текста и создание двоичного сообщения Protobuf. Не смешивайте их: массив чисел, Base64 и Protobuf могут описывать одни и те же байты, но принимаются разными функциями. Все вызовы используют общую запись функций in-Line.

Что выбрать

Текст, байты и их запись

Функции сначала получают строку программы, а затем сами выбирают, как представить её байты. На примере слова Привет цепочка выглядит так:

ZLIB и GZIP также начинают с байтов UTF-8, но после сжатия записывают двоичный результат в Base64. PROTOBUF строит байты по номерам и типам полей, поэтому одного исходного текста для него недостаточно.

STRTOBYTES и BYTESTOSTR

Эти функции образуют обратимую пару, если массив не менялся и содержит допустимый текст UTF-8.

#beginScript
|DV|[Utf8Bytes]=(|STRTOBYTES|Привет|STRTOBYTES|)
|DV|[Utf8Text]=(|BYTESTOSTR||DV|[Utf8Bytes]|BYTESTOSTR|)
#endScript

После выполнения:

|DV|[Utf8Bytes] = [208,159,209,128,208,184,208,178,208,181,209,130]
|DV|[Utf8Text]  = Привет

(|STRTOBYTES|hello|STRTOBYTES|)

[104,101,108,108,111]

Некорректный JSON, значение вместо массива или нечисловой элемент вызывают ошибку выполнения. Не передавайте дроби и числа вне диапазона байта: это не входит в договор функции.

ZLIB и GZIP

Обе пары выполняют одну цепочку: текст → UTF-8 → сжатые байты → Base64. При восстановлении шаги идут в обратном порядке. Входом функций распаковки служит Base64, а результатом — текст UTF-8.

Обратимая пара ZLIB

#beginScript
|DV|[Source]={"event":"heartbeat"}
|DV|[ZlibPacked]=(|ZLIBCOMPRESS||DV|[Source]|ZLIBCOMPRESS|)
|DV|[ZlibRestored]=(|ZLIBDECOMPRESS||DV|[ZlibPacked]|ZLIBDECOMPRESS|)
#endScript

|DV|[ZlibRestored] будет равно {"event":"heartbeat"}. При текущей реализации |DV|[ZlibPacked] имеет вид eJyrVkotS80rUbJSykhNLCpJSk0sUaoFAFHbB40=, но проверяйте восстановленный текст, а не точное совпадение сжатой строки: допустимый поток может отличаться после смены средства сжатия или его настроек.

Устройство потока определено в описании ZLIB.

Обратимая пара GZIP

#beginScript
|DV|[Source]={"event":"sync"}
|DV|[GzipPacked]=(|GZIPCOMPRESS||DV|[Source]|GZIPCOMPRESS|)
|DV|[GzipRestored]=(|GZIPDECOMPRESS||DV|[GzipPacked]|GZIPDECOMPRESS|)
#endScript

|DV|[GzipRestored] будет равно {"event":"sync"}. Один из допустимых результатов сжатия — H4sIAAAAAAAAAKtWSi1LzStRslIqrsxLVqoFADsT6ZcQAAAA; заголовок GZIP допускает служебные поля, поэтому точная строка также не является устойчивой проверкой.

Устройство потока определено в описании GZIP.

Пустой ввод и ошибки

• Пустая строка на входе любой из четырёх функций сразу даёт пустую строку. Это особое поведение, а не Base64 сжатого пустого потока.
• Функции сжатия принимают текст, а не произвольный массив байтов. Для файла или уже готового двоичного тела отдельного входа здесь нет.
• Неверный Base64, чужая обёртка или повреждённый поток не останавливают исполнение исключением: функция возвращает текст вида Error: <описание>. Такой результат нельзя передавать дальше как успешно восстановленные данные.

PROTOBUF

PROTOBUF строит или разбирает одно сообщение по описанию полей в JSON. Функция не читает .proto, не получает схему из сообщения и не угадывает типы: номер и тип каждого нужного поля задаются при каждом вызове.

Договор входного объекта

{
  "action": "encode | decode | update",
  "message_type": "AuthRequest",
  "field_mapping": {
    "AuthRequest": {
      "login": { "number": 1, "type": "string" },
      "password": { "number": 2, "type": "string" }
    }
  },
  "field_values": {
    "login": "Arthas",
    "password": "Scourge"
  },
  "protobuf_base64": "CgZBcnRoYXMSB1Njb3VyZ2U="
}

Свойство name внутри описания поля не используется: именем служит ключ login, password и так далее. Лишнее name не заменяет правильный ключ и не исправляет неверный number.

Поддерживаемые типы

Полная пара: создать и разобрать

#beginScript
|DV|[AuthPacket]=(|PROTOBUF|{
  "action":"encode",
  "message_type":"AuthRequest",
  "field_mapping":{
    "AuthRequest":{
      "login":{"number":1,"type":"string"},
      "password":{"number":2,"type":"string"}
    }
  },
  "field_values":{
    "login":"Arthas",
    "password":"Scourge"
  }
}|PROTOBUF|)

|DV|[AuthData]=(|PROTOBUF|{
  "action":"decode",
  "message_type":"AuthRequest",
  "field_mapping":{
    "AuthRequest":{
      "login":{"number":1,"type":"string"},
      "password":{"number":2,"type":"string"}
    }
  },
  "protobuf_base64":"|DV|[AuthPacket]"
}|PROTOBUF|)
#endScript

Результаты:

|DV|[AuthPacket] = CgZBcnRoYXMSB1Njb3VyZ2U=
|DV|[AuthData]   = {"login":"Arthas","password":"Scourge"}

Имена login и password в двоичном сообщении не хранятся. При разборе они восстанавливаются только из field_mapping; если поменять номера местами, значения будут подписаны неверными именами.

Что в действительности делает update

Следующий вызов получает созданный выше пакет и добавляет ещё одну запись поля login:

(|PROTOBUF|{
  "action":"update",
  "message_type":"AuthRequest",
  "field_mapping":{
    "AuthRequest":{
      "login":{"number":1,"type":"string"},
      "password":{"number":2,"type":"string"}
    }
  },
  "field_values":{"login":"Jaina"},
  "protobuf_base64":"CgZBcnRoYXMSB1Njb3VyZ2U="
}|PROTOBUF|)

Результат — CgZBcnRoYXMSB1Njb3VyZ2UKBUphaW5h. При последующем decode эта реализация покажет два вхождения login как массив ["Arthas","Jaina"]; порядок свойств самого объекта JSON не определён.

Повторяющиеся известные поля при decode собираются в массив. При encode массив поддержан только для вложенных полей типа message; массив простых строк, чисел или bytes не принимается. Упакованные повторяющиеся числа также не входят в поддерживаемый договор.

Границы и ошибки

• Номер поля должен совпадать со схемой другой стороны. Допустимы номера от 1 до 536870911, кроме зарезервированного промежутка 19000–19999; исполнитель сам полностью это правило не проверяет.
• Публичный договор ограничен одиннадцатью типами выше. Частично присутствующие во внутреннем исполнителе названия sint32, sint64, fixed32, fixed64, sfixed32 и sfixed64 записываются несовместимо либо разбираются неполно, поэтому использовать их нельзя.
• Неизвестное поле при decode пропускается. Отсутствующее известное поле не дополняется значением по умолчанию.
• Некорректный JSON, отсутствующее обязательное свойство, неизвестное действие, неверный тип значения или повреждённый Base64 вызывают ошибку выполнения; PROTOBUF не возвращает строку Error: ..., как функции сжатия.

Почему номер и вид записи поля определяют смысл двоичных данных, показано в официальном описании Protobuf.