Макросы в tentacli. Часть один
Со времени публикации первых двух статей мой проект сменил имя и концепцию. Теперь он называется TentaCLI и это название, являющееся игрой слов tentacle и cli, полностью отражает новую суть проекта. Хотя tentacli по прежнему может быть скачан с github и использоваться, как отдельное клиентское приложение, он и его части так же доступны в виде крэйтов. Внедряемость, а так же возможность добавлять собственные модули в tentacli делает его подходящим для создания собственных приложений. В частности, у меня таких два: мини wow сервер для тестирования tine и скрытый проект binary army, в котором tentacli полностью раскрывает свой потенциал как щупальца-исполнителя - и для управления которыми я пишу сердце.
А сердце tentacli - это чтение и обработка TCP пакетов и для облегчения работы с ними я использую макросы.
Мотивация
Давным-давно, в далекой-предалекой первой версии парсинг и создание пакетов представляли собой весьма муторную задачу:
// чтение пакета с опкодом SMSG_MESSAGECHAT
let mut reader = Cursor::new(input.data.as_ref().unwrap()[4..].to_vec());
let message_type = reader.read_u8()?;
let language = reader.read_u32::<LittleEndian>()?;
let sender_guid = reader.read_u64::<LittleEndian>()?;
// skip
reader.read_u32::<LittleEndian>()?;
// условное поле раз
let mut channel_name = Vec::new();
if message_type == MessageType::CHANNEL {
reader.read_until(0, &mut channel_name)?;
}
let channel_name = match channel_name.is_empty() {
true => String::new(),
false => {
String::from_utf8(
channel_name[..(channel_name.len() - 1) as usize].to_owned()
).unwrap()
},
};
let target_guid = reader.read_u64::<LittleEndian>()?;
let size = reader.read_u32::<LittleEndian>()?;
// условное поле два
let mut message = vec![0u8; (size - 1) as usize];
reader.read_exact(&mut message)?;
let message = String::from_utf8_lossy(&message);Возможно, вы подумали, что это специальный код для наказаний и, вобщем-то, так оно и было - масштабировать подобный код было тем еще испытанием. Как итог, были реализованы обработчики только для самых базовых пакетов. Но этой ситуации суждено было измениться.
Начало великого перехода
В процессе исследований я нашел крэйты serde и bincode. Однако, концепция, которую я задумал, не могла быть реализована с помощью данных крэйтов - мне нужна была условная десериализация. Пример кода выше - идеальный для отражения проблемы, поскольку в нем представлены сразу два случая условной десериализации: когда поле (channel_name) может быть прочитано только в случае, если совпало некое условие и когда чтение поля (message) зависит от ранее прочитанного поля (size). Я размышлял над максимально лаконичной формой описания таких полей.
Итогом моих экспериментов и исследований, а так же значительной помощи со стороны официального Rust комьюнити стал вот такой макрос - который заменил код выше:
#[derive(WorldPacket, Serialize)]
struct Incoming {
message_type: u8,
language: u32,
sender_guid: u64,
skip: u32,
#[conditional]
channel_name: String,
target_guid: u64,
message_length: u32,
#[depends_on(message_length)]
message: String,
}
impl Incoming {
fn channel_name(instance: &mut Self) -> bool {
instance.message_type == MessageType::CHANNEL
}
}Устройство макроса
Теперь по порядку разберем, как он устроен. Фундаментом для чтения/записи данных служит трейт BinaryConverter :
pub trait BinaryConverter {
fn write_into(&mut self, buffer: &mut Vec<u8>) -> AnyResult<()>;
fn read_from<R: BufRead>(
reader: &mut R,
dependencies: &mut Vec<u8>
) -> AnyResult<Self> where Self: Sized;
}Этот трейт я имплеменчу на каждый тип, который хочу использовать в полях сериалайзера:
impl BinaryConverter for u8 {
fn write_into(&mut self, buffer: &mut Vec<u8>) -> AnyResult<()> {
buffer.write_u8(*self).map_err(|e| FieldError::CannotWrite(e, "u8".to_string()).into())
}
fn read_from<R: BufRead>(reader: &mut R, _: &mut Vec<u8>) -> AnyResult<Self> {
reader.read_u8().map_err(|e| FieldError::CannotRead(e, "u8".to_string()).into())
}
}В некоторых случаях требуется чуть больше кода, к примеру, для строк:
impl BinaryConverter for String {
fn write_into(&mut self, buffer: &mut Vec<u8>) -> AnyResult<()> {
buffer.write_all(self.as_bytes())
.map_err(|e| FieldError::CannotWrite(e, "String".to_string()))?;
Ok(())
}
fn read_from<R: BufRead>(
reader: &mut R,
dependencies: &mut Vec<u8>
) -> AnyResult<Self> {
let mut cursor = Cursor::new(dependencies.to_vec());
let size = match dependencies.len() {
1 => ReadBytesExt::read_u8(&mut cursor)
.map_err(|e| FieldError::CannotRead(e, "String u8 size".to_string()))? as usize,
2 => ReadBytesExt::read_u16::<LittleEndian>(&mut cursor)
.map_err(|e| FieldError::CannotRead(e, "String u16 size".to_string()))? as usize,
4 => ReadBytesExt::read_u32::<LittleEndian>(&mut cursor)
.map_err(|e| FieldError::CannotRead(e, "String u32 size".to_string()))? as usize,
_ => 0,
};
let buffer = if size > 0 {
let mut buffer = vec![0u8; size];
reader.read_exact(&mut buffer)
.map_err(|e| FieldError::CannotRead(e, "String".to_string()))?;
buffer
} else {
let mut buffer = vec![];
reader.read_until(0, &mut buffer)
.map_err(|e| FieldError::CannotRead(e, "String".to_string()))?;
buffer
};
let string = String::from_utf8(buffer)
.map_err(|e| FieldError::InvalidString(e, "String".to_string()))?;
Ok(string.trim_end_matches(char::from(0)).to_string())
}
}То же самое справедливо и для пользовательских типов. Благодаря этому при объявлении сериалайзера можно использовать тип Player напрямую в качестве типа для поля:
// пакет с опкодом SMSG_CHAR_ENUM
#[derive(WorldPacket, Serialize, Debug)]
struct Incoming {
characters_count: u8,
#[depends_on(characters_count)]
characters: Vec<Player>,
}Теперь, при получении пакета с сервера, с помощью сериалайзера из примера выше мы можем прочитать список персонажей - в переменную characters:
let (Incoming { characters, .. }, json) = Incoming::from_binary(&input.data)?;Метод from_binary возвращает tuple из двух элементов - инстанс текущего struct и json представление его полей.
Рассмотрим, откуда взялся этот метод и при чем же здесь trait BinaryConverter.
Изнанка сериалайзера
Есть два макроса: один для Login сервера, второй - для World сервера. Но выбирать из них мы не будем и рассмотрим только один, поскольку они сильно похожи.
#[proc_macro_derive(WorldPacket, attributes(depends_on, conditional))]
pub fn world_packet(input: TokenStream) -> TokenStream {
let ItemStruct { ident, fields, .. } = parse_macro_input!(input);
// формируем список полей
// формируем список зависимостей для полей
// формируем список значений
// формируем то, что вернет макрос
TokenStream::from(output)
}Любой proc-macro скорее всего будет выглядеть как-то так.
Начать я хотел бы с конца, а именно - с объяснения, что такое output. Если вкратце, то это - переменная, которая содержит код, обернутый с помощью макроса quote!. Т.е. для того, чтобы struct, к которому я применяю мой макрос, получал некий метод, назовем его from_binary, понадобится добавить следующие строки в эту переменную:
#[proc_macro_derive(WorldPacket, attributes(depends_on, conditional))]
pub fn world_packet(input: TokenStream) -> TokenStream {
let ItemStruct { ident, fields, .. } = parse_macro_input!(input);
// формируем список полей
// формируем список зависимостей для полей
// формируем список значений
let output = quote! {
impl #ident {
pub fn from_binary(buffer: &[u8]) -> #result<(Self, String)> {
println!("It works !");
// а здесь нужно вернуть результат
}
}
};
TokenStream::from(output)
}В коде выше ident - это идентификатор того struct, к которому применен макрос. Знак решетки служит для интерполяции выражений - таким образом, в контексте текущей серии примеров, ident означает Incoming, как если бы я написал:
impl Incoming {
pub fn from_binary(buffer: &[u8]) -> AnyResult<(Self, String)> {
println!("It works !");
// а здесь нужно вернуть результат
}
}Помимо переменных, интерполировать можно так же и импорты, к примеру, переменнаяresult - это не что иное, как quote!(anyhow::Result).
Теперь добавим формирование списка полей и списка значений. Поскольку задача метода from_binary - сформировать struct из пакета байт (ну, а так же json), нужно, чтобы внутри метода было что-то вроде:
let binary_converter = quote!(tentacli_traits::BinaryConverter);
let cursor = quote!(std::io::Cursor);
let output = quote! {
impl #ident {
pub fn from_binary(buffer: &[u8]) -> #result<(Self, String)> {
println!("It works !");
let mut reader = #cursor::new(buffer);
let json = String::new();
let instance = Self {
characters_count: #binary_converter::read_from(&mut reader, &mut vec![]),
characters: #binary_converter::read_from(&mut reader, &mut vec![]),
};
Ok((instance, json))
}
}
};Благодаря этому коду получился одноразовый макрос.
Теперь нужно сделать, чтобы он обрабатывал любой набор полей:
// эту строку я уже указывал в примерах выше, но просто добавлю ее
// для ясности - откуда взялся fields
let ItemStruct { ident, fields, .. } = parse_macro_input!(input);
let field_names = fields.iter().map(|f| {
// в этом случае ident - это уже идентификатор поля !
f.ident.clone()
}).collect::<Vec<Option<Ident>>>();
let initializers = fields.iter()
.map(|f| {
let field_name = f.ident.clone();
let field_type = f.ty.clone();
quote! {
{
let value: #field_type = #binary_converter::read_from(&mut reader, &mut vec![])?;
value
}
}
});
let binary_converter = quote!(tentacli_traits::BinaryConverter);
let cursor = quote!(std::io::Cursor);
let output = quote! {
impl #ident {
pub fn from_binary(buffer: &[u8]) -> #result<(Self, String)> {
println!("It works !");
let mut reader = #cursor::new(buffer);
let json = String::new();
// а теперь магия развертывания
let mut instance = Self {
#(#field_names: #initializers),*
};
Ok((instance, json))
}
}
};Вот этот код (развертывание):
let mut instance = Self {
#(#field_names: #initializers),*
};Будет компилятором преображен примерно в такой:
let mut instance = Self {
field1: {
let value: i32 = binary_converter::read_from(&mut reader, &mut vec![])?;
value
},
field2: {
let value: String = binary_converter::read_from(&mut reader, &mut vec![])?;
value
},
// ...
};Т.е. иными словами, благодаря развертыванию происходит сопоставление каждого элемента из field_names элементу с тем же порядковым номером из initializers , затем каждая пара подставляется в Self - и разделяется запятой.
Атрибуты depends_on и conditional
Чтобы сформировать список полей, которые содержат заданные атрибуты, можно использовать обычный вектор или какой-нибудь hashmap/btreemap:
// этот struct объявлен вне макроса
struct DependsOnAttribute {
pub name: Ident,
}
impl Parse for DependsOnAttribute {
fn parse(input: ParseStream) -> syn::Result<Self> {
let name: Ident = input.parse()?;
Ok(Self { name })
}
}
// дальнейший код уже внутри макроса
let mut depends_on: BTreeMap<Option<Ident>, Vec<Ident>> = BTreeMap::new();
let mut conditional: Vec<Option<Ident>> = vec![];
for field in fields.iter() {
let ident = field.ident.clone();
if field.attrs.iter().any(|attr| attr.path().is_ident("depends_on")) {
let mut dependencies: Vec<Ident> = vec![];
field.attrs.iter().for_each(|attr| {
if attr.path().is_ident("depends_on") {
let parsed_attrs = attr.parse_args_with(
Punctuated::<DependsOnAttribute, Token![,]>::parse_terminated
).unwrap();
for a in parsed_attrs {
dependencies.push(a.name);
}
}
});
depends_on.insert(ident.clone(), dependencies);
}
if field.attrs.iter().any(|attr| attr.path().is_ident("conditional")) {
conditional.push(ident);
}
}С помощью переменных depends_on и conditional мы просто формируем списки идентификаторов, которые будут использованы в дальнейшем (см. в конце статьи).
Но перед тем, как мы перейдем к завершающей фазе, хочу рассмотреть еще одну вещь.
В свое время parse_terminated и парсинг атрибутов в целом вызвал у меня много вопросов и непоняток, поэтому рассмотрим его подробнее с примерами.
Как вообще парсить атрибуты
Метод parse_terminated принимает два generic параметра: то, что мы ищем и то, чем это разделяется (separator).
Для начала сделаем макрос, атрибут которого будет принимать список чисел, которые затем можно будет вывести в консоль:
#[derive(Simple)]
#[numbers(1, 2, 3, 4)]
struct MyStruct;
fn main() {
MyStruct::output()
}
// и код макроса:
#[proc_macro_derive(Simple, attributes(numbers))]
pub fn simple(input: TokenStream) -> TokenStream {
let DeriveInput { ident, attrs, .. } = parse_macro_input!(input);
let mut numbers = vec![];
for attr in attrs {
if attr.path().is_ident("numbers") {
let number_list = attr.parse_args_with(
Punctuated::<LitInt, Token![,]>::parse_terminated
).unwrap();
for number in number_list {
numbers.push(number.base10_parse::<i32>().unwrap());
}
}
}
// поскольку на вектор при интерполяции накладываются некоторые ограничения
// для вывода мы можем предварительно привести его к строке
let numbers_str = format!("{:?}", numbers);
let output = quote! {
impl #ident {
pub fn output() {
println!("{:?}", #numbers_str);
// либо можно вывести вектор вот так:
println!("{:?}", [ #( #numbers ),* ]);
}
}
};
TokenStream::from(output)
}Каждый атрибут мы парсим с помощью attr.parse_args_with, который принимает парсер в качестве параметра. Собственно, парсером в нашем случае выступает вышеупомянутый parse_terminated .
Можно немного облагородить процесс парсинга и создать кастомный struct:
struct NumberList {
numbers: Punctuated<LitInt, Token![,]>,
}
impl syn::parse::Parse for NumberList {
fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
Ok(NumberList {
numbers: Punctuated::parse_terminated(input)?
})
}
}
// и в самом макросе number_list будет читаться как-то так:
let number_list = attr.parse_args::<NumberList>().unwrap().numbers;В таком случае использование parse_terminated можно вынести из общего кода. Концепция кастомного struct нам понадобится далее.
Теперь усложним задачу. Будем парсить список параметров, где есть пары ключ и значение:
#[derive(Middle)]
#[values(tentacli=works, join=us, on=discord)]
struct BetterStruct;
// для этого я применю уже рассмотренный выше подход с кастомным struct
struct ValuesList {
pub items: Vec<(String, String)>,
}
impl syn::parse::Parse for ValuesList {
fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
let mut items = vec![];
while !input.is_empty() {
let key: Ident = input.parse()?;
input.parse::<Token![=]>()?;
let value: Ident = input.parse()?;
items.push((key.to_string(), value.to_string()));
if input.peek(Token![,]) {
input.parse::<Token![,]>().expect(",");
}
}
Ok(Self { items })
}
}
#[proc_macro_derive(Middle, attributes(values))]
pub fn middle(input: TokenStream) -> TokenStream {
// ...
for attr in attrs {
if attr.path().is_ident("values") {
let items_list = attr.parse_args::<ValuesList>().unwrap();
// ...
}
}
// ...
TokenStream::from(output)
}То, что мы парсим - это по сути просто набор токенов, поэтому можно воспринимать процесс парсинга как их последовательный перебор - и если какой-то элемент в последовательности будет пропущен (скажем, в нашем случае - пропущен знак "=") - произойдет ошибка на этапе компиляции.
Поскольку параметры, указанные в скобках атрибута, передаются без кавычек, они воспринимаются парсером, как идентификаторы, в противном случае каждый key/value нужно было бы парсить как строку с помощью LitStr вместо Ident.
Это все были атрибуты для struct. Для полноты картины рассмотрим так же атрибуты полей. С ними все то же самое, единственное отличие - эти атрибуты парсятся из fields.
#[derive(Hard)]
#[values(tentacli=works, join=us, on=discord)]
struct TopStruct {
#[value("Tentacli")]
name: String,
#[value("https://github.com/idewave/tentacli")]
github_link: String,
#[value("https://crates.io/crates/tentacli")]
crates_link: String,
}
#[proc_macro_derive(Hard, attributes(values, value))]
pub fn hard(input: TokenStream) -> TokenStream {
// чтобы получить fields вместо DeriveInput используем ItemStruct
let ItemStruct { ident, fields, attrs, .. } = parse_macro_input!(input);
for field in fields.iter() {
field.attrs.iter().for_each(|attr| {
if attr.path().is_ident("value") {
let value = attr.parse_args::<LitStr>().unwrap();
values.push(value.value());
}
});
}
TokenStream::from(output)
}Я создал репу на гитхабе, в которой содержатся все три примера.
Заключение
Теперь с полным (я надеюсь) пониманием, как функционирует макрос - предлагаю дописать код для переменной initializers и для метода from_binary:
let initializers = fields
.iter()
.map(|f| {
let field_name = f.ident.clone();
let field_type = f.ty.clone();
let output = if let Some(dep_fields) = depends_on.get(&field_name) {
quote! {
{
let mut data: Vec<u8> = vec![];
#(
#binary_converter::write_into(
&mut cache.#dep_fields,
&mut data,
)?;
)*
#binary_converter::read_from(&mut reader, &mut data)?
}
}
} else {
quote! {
{
let value: #field_type = #binary_converter::read_from(
&mut reader, &mut vec![]
)?;
cache.#field_name = value.clone();
value
}
}
};
if conditional.contains(&field_name) {
quote! {
{
if Self::#field_name(&mut cache) {
#output
} else {
Default::default()
}
}
}
} else {
output
}
});
let output = quote! {
impl #ident {
pub fn from_binary(buffer: &[u8]) -> #result<(Self, String)> {
println!("It works !");
let mut cache = Self {
#(#field_names: Default::default()),*
};
let mut reader = #cursor::new(buffer);
let mut instance = Self {
#(#field_names: #initializers),*
};
let details = instance.get_json_details()?;
Ok((instance, details))
}
}
};Первый вопрос, который может у вас появиться: что это за reader, cache и прочие разные переменные, которые не объявлены перед initializers, но почему-то используются внутри этой переменной. Ответ достаточно прост: содержимое переменной initializers будет подставлено в том месте переменной output, где мы ее указали. А все, что мы передали внутрь TokenStream::from(output) - будет скомпилировано одним куском. Таким образом, в коде выше, - переменная cache объявлена на 52 строке, переменная reader - на 56 и все они - объявлены ДО того, как initializers попал в код.
Второй вопрос: что есть cache. Это реплика инстанса текущего struct за исключением того, что запись туда ведется до первого поля с атрибутом depends_on. Благодаря этому подходу можно сделать запрос к ранее прочитанным полям, не дожидаясь окончания чтения всех полей. И на этапе билда решить, как правильно читать следующее поле. К примеру, возьмем самый первый код, где описан пакет SMSG_MESSAGECHAT. Есть там условное поле channel_name, если на этапе чтения мы его прочтем тогда, когда этого делать было не нужно, то следующее поле (и все дальнейшие) уже будет прочитано неправильно, что приведет к ошибке.
А третий вопрос задавайте в комментариях.