# Глава 13: Zig в реальном мире

Поздравляю! Если вы добрались до этого момента, значит, вы смогли преодолеть все трудности, связанные с основами языка Zig — управление памятью, обработка ошибок, системы сборки кода, а также все те особенности языка, которые делают его мощным инструментом для программирования, но иногда и сложным для использования. Однако изучение синтаксиса и различных концепций по отдельности подобно изучению приемов фехтования без реального противника. Пришло время объединить все эти знания воедино и создать что-то действительно полезное.

В этой главе мы подробно рассмотрим FileGuard – реальную систему мониторинга файлов, созданную полностью на языке программирования Zig. Это не просто ещё одна программа вроде «Hello, World!», выполненная с использованием языка Zig, это полноценный инструмент командной строки, который отслеживает изменения в каталогах, фиксирует изменения файлов и сообщает о всех обнаруженных событиях. При этом вы увидите, как функции языка Zig, связанные с безопасностью использования памяти, обработкой ошибок и совместимостью с языком C, вместе способствуют созданию надежного программного обеспечения.

К концу этой главы вы узнаете:

• Как использовать инструменты командной строки и автоматизировать свою работу (и немного разозлить коллег)
• Другие идеи для проектов: Горизонтов нет (или, по крайней мере, ограничены только возможности памяти компьютера)
• Какие есть ресурсы сообщества: форумы, чат-румы и прочие места для обмена знаниями
• Каковы планы на будущее: как Зиг намерен завоевать мир (вероятно).
• Каково влияние Zig: примеры успешного применения этого языка (от скромных начал до статуса ведущего технологического решения) — Кто на самом деле использует этот язык в своей практике? Стали ли пользователи этого языка более умными или же, наоборот, потеряли разум?

Независимо от того, являетесь ли вы человеком, который впервые сталкивается с концепциями, связанными с управлением памятью, и не понимает, в чем суть всего этого, или же вы опытный программист на языке C++, стремящийся избавиться от проблем, связанных с использованием шаблонов и метапрограммирования, примеры, приведенные в этой главе, покажут вам, почему стоит обратить внимание на язык Zig. Этот язык быстр в использовании, его синтаксис понятен. Самое главное — при использовании Zig вы можете спать спокойно, зная, что ваш код не будет тайком расходовать память.

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

Весь код, приведенный в этой главе, можно найти в директории Chapter13 нашего git-репозитория: https://github.com/PacktPublishing/Learning-Zig/tree/main/Chapter13.

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

Инструменты командной строки являются основным инструментарием системных программистов. Именно с их помощью можно автоматизировать монотонные и утомительные процессы, производить работу более эффективно, чем это возможно вручную. Кроме того, инструменты командной строки позволяют сбить с толку тех, кто считает, что компьютеры должны иметь «кнопки» и «простой интерфейс». Хорошо спроектированный инструмент командной строки похож на цифровую копию швейцарского армейского ножа: компактный, точный в использовании и приносящий удовлетворение от использования в нужный момент.

И что самое приятное? Инструменты командной строки, написанные на языке Zig, работают намного быстрее, чем те громоздкие скрипты на Python, которые используют все остальные. Нет ничего лучше, чем видеть, как проекты коллег, полные сложных зависимостей, выполняются за 30 секунд, в то время как ваш проект, написанный на Zig, готов мгновенно. «О, а ваш проект все еще выполняется? У меня он уже давно завершился, у меня даже хватило времени, чтобы переписать его дважды.»

Познакомьтесь с FileGuard – нашей будущей системой мониторинга файлов. Нет, это не какой-то готовый инструмент, о котором вы никогда не слышали. Это наш собственный проект, который мы будем создавать вместе, шаг за шагом. Сможет ли это полностью изменить индустрию программного обеспечения? Вряд ли. Но, безусловно, использование FileGuard заставит вас чувствовать себя почти богом в мире цифровых технологий по сравнению с теми, кто продолжает использовать стандартные инструменты для отслеживания изменений в файлах.

FileGuard обнаруживает моменты создания, изменения, удаления файлов, а также их тайного перемещения. Его можно использовать для мониторинга каталогов с исходным кодом, отслеживания изменений в настройках системы, а также для контроля за сотрудниками, которые без разрешения используют ваши скрипты. В профессиональной среде FileGuard отлично справляется с такими задачами, как выявление изменений в настройках системы, контроль за важными системными файлами на наличие несанкционированных изменений, а также отслеживание изменений в исходном коде в рамках процессов CI/CD. Способность инструмента различать перемещения файлов и операции удаления-создания делает его особенно ценным для понимания истинной природы изменений в сложных сценариях развертывания. Хотя похожие инструменты уже существуют в реальности, создание собственных инструментов дает нам отличную возможность проявить свои таланты, без необходимости создавать очередной стартап стоимостью в миллиарды долларов.

Давайте запустим любой из наших эмуляторов терминала, слегка потрясем костяшками пальцев (хотя никто и не смотрит), и создадим нечто, что могли бы гордиться философы UNIX: инструмент, который выполняет одну функцию прекрасно и может быть использован в сочетании с другими инструментами для управления нашей «крошечной частью вычислительной вселенной».

Прежде чем мы начнем написание кода, давайте на мгновение задумаемся о том, как должна быть структурирована программа, отвечающая за защиту файлов. В конце концов, разница между «новичком-программистом» и «опытным системным программистом» заключается прежде всего в степени подготовки, которая проводится перед написанием первой строки кода. А поскольку вы читаете книгу с названием, содержащим слово «Обучение», предполагаю, что именно этого вы и стремитесь достичь.

Давайте рассмотрим, как сделать FileGuard модульным, эффективным и, позвольте мне так сказать, элегантным в своей структуре. Хорошая архитектура — это не просто способ сделать программу более эффективной в работе, это также способ избежать ситуаций, когда человеку приходится жаловаться на прошлые решения каждый раз, когда необходимо добавить новые функции в программу (стоимость поддержки жизненного цикла приложения, ага).

Давайте попробуем понять, какую именно проблему решает FileGuard. По сути, мониторинг файлов кажется довольно простым процессом. Нужно лишь узнавать моменты, когда файлы меняются, не так ли? Но, как и в случае со многими «простыми» проблемами в информатике, на самом деле все гораздо сложнее.

Сложность связана с фундаментальными различиями в способах обработки событий, связанных с файлами, в разных операционных системах. Linux использует механизм inotify для эффективной обработки уведомлений на уровне ядра. macOS использует механизм kqueue, а Windows – функцию ReadDirectoryChangesW. У каждой системы свои возможности, ограничения и особенности работы. Некоторые системы позволяют точно определять типы событий, другим приходится использовать дополнительные методы обработки данных. Кроме того, каждая система по-разному справляется с особыми ситуациями, связанными с сетевыми файловыми системами или частыми изменениями в структуре файлов.

Вместо того чтобы иметь дело с специфическими для каждой платформы API, FileGuard использует иной подход: периодический сканирование с функцией распознавания изменений. Этот подход эффективно работает на всех платформах, при этом его легко понять и настроить.

Надлежащая система мониторинга файлов должна выполнять следующие функции:

• Выявлять различные виды изменений: файлы могут быть созданы, удалены, изменены или перемещены. Могут меняться их права доступа. Иногда также обновляются только временные метки файлов, без изменения их содержимого.
• Эффективно сканирование больших структур каталогов: Мы не можем позволить себе читать каждый байт каждого файла при каждом сканировании. Если мы хотим, чтобы процесс сканирования происходил достаточно быстро, чтобы пользователи не теряли терпения во время ожидания результатов.
• Фильтрация шума: Пользователям редко нужно просматривать каждый отдельный файл. Необходимо иметь способы для отбора только важных файлов и исключения ненужных.
• Разумно распознавать действия по изменению названий файлов: является ли это новым файлом или же это просто тот же самый файл с другим названием? Это имеет важное значение.
• Отчеты должны содержать значимую информацию: необработанные данные бесполезны без контекста и такой формы представления, которую могут понять люди.

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

Как нам эффективно преодолеть эти проблемы? Вот ключевые архитектурные решения, которые будут служить ориентиром при реализации.

1. Обнаружение двухфазных изменений
   Вместо постоянной повторной обработки всей информации мы будем использовать двухэтапный подход:
   • Создайте базовый индекс метаданных файлов (пути к файлам, их размеры, временные метки и т. д.).
   • При последующих сканированиях необходимо создавать новый индекс и сравнивать его с исходными значениями.
   • Записывайте все различия в виде изменений.
   • Необходимо обновить исходные данные для следующего сканирования. Это означает, что нам достаточно считывать и сохранять только метаданные, а не весь содержимое файла. Благодаря этому процесс становится намного быстрее.
2. Отслеживание inode для выявления перемещений
   На системах типа UNIX (Linux, macOS) у каждого файла есть номер индекса файла – уникальный идентификатор, присваиваемый файловой системой. Этот номер остается неизменным даже при переименовании или перемещении файла. В Windows используется похожая концепция: номера файлов или идентификаторы файлов, выполняющие ту же функцию. Благодаря использованию этих уникальных идентификаторов…
   • Если файл исчезает с местоположения А, но на местоположении Б появляется другой файл с тем же идентификатором inode, значит, файл был просто перемещен, а не удален и затем снова создан.
   • Это позволяет нам избежать необходимости проведения дорогостоящих сравнений различного вида контента для определения характера действий над файлом.
   • Стандартная библиотека Zig устраняет эти различия между платформами. Благодаря этому наш код будет работать одинаково независимо от используемой системы.
3. Необязательное хэширование контента
   Для обеспечения максимальной точности (в ущерб производительности, конечно) мы добавим возможность вычисления хэш-значений контента.
   • По причинам, связанным с производительностью, по умолчанию параметр установлен в значение «off».
   • При включении этой функции программа обнаруживает даже незначительные изменения в содержимом файла, которые не влияют на его размер.
   • Позволяет пользователям самостоятельно управлять балансом между скоростью выполнения операций и степенью их тщательности.
4. Настройка правил сопоставления шаблонов
   Не все файлы заслуживают постоянного наблюдения. Для этого мы будем использовать схемы сопоставления по шаблонам.
   • Включать только те файлы, которые соответствуют определенным шаблонам (например, «.zig», «config/»).
   • Исключить файлы, соответствующие другим шаблонам (например, «.tmp», «node_modules/»).
   • Предоставьте пользователям возможность тонкой настройки процесса мониторинга.

fileGuard/
├── build.zig         # Build configuration
├── build.zig.zon     # Dependencies
└── src/
    ├── main.zig              # Program entry point
    ├── file_metadata.zig     # File information tracking
    ├── file_index.zig        # Collection of file metadata
    ├── traversal.zig         # Directory walking
    ├── pattern.zig           # Glob pattern matching
    ├── change_detection.zig  # Identifying changes
    ├── config.zig            # Configuration structures
    └── cli.zig               # Command-line interface

Каждый модуль выполняет свои конкретные функции:

• Файл metadata.zig определяет способ представления и управления отдельными файлами.
• Файл index.zig предназначен для хранения метаданных файлов, что обеспечивает более эффективный поиск информации о файлах.
• Файл traversal.zig обеспечивает просмотр структуры каталогов в соответствии с настроенными правилами.
• Файл pattern.zig реализует механизм сопоставления путей к файлам.
• Файл change_detection.zig сравнивает индексы файлов с целью определения того, что изменилось.
• Файл config.zig содержит структуры конфигурации, необходимые для выполнения процедур просмотра и обнаружения.
• Файл cli.zig обрабатывает аргументы, вводимые в командной строке, и отображает результаты обработки.
• Файл main.zig объединяет все элементы воедино и служит точкой входа для выполнения программы.

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

После того, как мы создадим структуру нашего приложения, мы будем создавать функционал FileGuard, двигаясь по следующим логическим шагам:

• Определим основные структуры данных, необходимые для хранения метаданных файлов и их индексации.
• Реализуем перебор элементов каталога с использованием схем сопоставления шаблонов
• Создадим логику обнаружения изменений.
• Создадим интерфейс командной строки.
• Свяжем всё вместе в главной программе.
• Проверим полученные результаты и оптимизируем их.

Начнем с основы – с тех структур, которые представляют информацию о файлах. В следующем разделе мы подробно рассмотрим процесс реализации модуля file_metadata.zig. В этом модуле определяется способ сбора и хранения информации о отдельных файлах. Этот модуль является основой всей нашей системы, правильная его реализация будет ключевым фактором успеха всего проекта.

Прежде чем мы сможем обнаруживать какие-либо изменения, нам необходим способ представления файлов и их характеристик. Это оказывается сложнее, чем кажется на первый взгляд. Что же такое «файл» в контексте мониторинга? Разве это просто путь к файлу и его содержимое? А как насчет прав доступа, времени создания файла, а также различных дополнительных характеристик, которые могут быть важны для некоторых приложений?

Ответ таков: все зависит от того, какие именно изменения важны для пользователя. Поскольку у разных пользователей разные потребности, структура FileMetadata должна быть достаточно гибкой, чтобы поддерживать различные стратегии мониторинга. В то же время структуру не следует чрезмерно усложнять из-за наличия полей, которые используются крайне редко.

Давайте определим способ представления метаданных в файле file_metadata.zig:

const std = @import("std");
const fs = std.fs;

pub const FileMetadata = struct {
    md: fs.File.Metadata,     // File system metadata
    path: []const u8,         // File path
    inode: u64,               // Unique file identifier
    checksum: ?[]const u8,    // Optional content hash
    allocator: std.mem.Allocator, // Memory allocator
    // Methods will go here...
};

Каждое поле выполняет свою конкретную функцию:

• md: Встроенная структура File.Metadata в Zig позволяет хранить информацию об атрибутах файлов, специфичных для данной платформы. Благодаря этому наша реализация не зависит от конкретной платформы.
• path: Местоположение файла в файловой системе.
• inode: уникальный идентификатор, который помогает нам отслеживать перемещение файлов (подробнее об этом позже).
• checksum: необязательный хэш-суммарный отчет о содержимом файла, используемый для выявления изменений в его содержимом.
• allocator: аллокатор, отвечающий за распределение памяти, выделяемой динамически.

Преимущество использования класса fs.File.Metadata по сравнению с необходимостью самостоятельной реализации всех функций заключается в том, что этот класс автоматически учитывает особенности разных платформ. Независимо от того, используется ли Linux, macOS или Windows, стандартная библиотека скрывает от пользователя все детали, связанные с конкретной платформой: способ представления разрешений, формат хранения временных меток и т. д.

Можно рассматривать это как передачу обязанностей по решению всех этих хлопотных проблем, связанных с работой различных платформ, разработчикам стандартной библиотеки Zig. Они уже столкнулись с необходимостью разбираться в том, почему в Windows временные метки рассчитываются исходя из 1601 года, а не, как это логично, из 1970 года. Мы же просто пользуемся результатами их усилий.

Теперь давайте реализуем метод инициализации:

pub fn init(allocator: std.mem.Allocator, path: []const u8, hash_content: bool) !FileMetadata {
    const abs_path = try fs.realpathAlloc(allocator, path);
    errdefer allocator.free(abs_path);

    const file = try fs.openFileAbsolute(abs_path, .{});
    defer file.close();

    const md = try fs.File.metadata(file);
	const stat = try file.stat();
    var metadata = FileMetadata{
        .path = abs_path,
        .md = md,
        .inode = stat.inode,
        .checksum = null,
        .allocator = allocator,
    };

    if (hash_content) {
        metadata.checksum = try computeFileHash(file, allocator);
    }

    return metadata;
}

Здесь происходит много всего:

• Мы преобразуем указанный путь в абсолютный путь. Это помогает избежать путаницы при смене рабочего каталога.
• Мы открываем файл и считываем, как его стандартные метаданные, так и статистическую информацию (включая номер индексного файла).
• Мы инициализируем структуру FileMetadata с использованием этой информации.
• По запросу мы вычисляем хэш содержимого файла.

Обратите внимание на инструкцию errdefer, которая выполняется после присвоения абсолютного пути. Это способ, предусмотренный языком Zig, для предотвращения утечки памяти в случае возникновения ошибки. Путь будет освобожден, если какая-либо из последующих операций потерпит неудачу. Это своего рода «система безопасности» для памяти, которая активируется только в случае возникновения проблем.

Поскольку мы выделяем память для хранения информации о пути и, возможно, также контрольной суммы, нам необходим способ освободить эту память по окончании работы. Вот наш метод очистки памяти:

pub fn deinit(self: *const FileMetadata) void {
    self.allocator.free(self.path);
    if (self.checksum) |checksum| {
        self.allocator.free(checksum);
    }
}

Этот метод позволяет освободить всю динамически выделенную память, которой мы располагаем. Это простой, но важный механизм: без него при каждом удалении метаданных файлов происходила бы утечка памяти.

Обратите внимание: мы не освобождаем память, занимаемую объектом типа md. Это связано с тем, что md представляет собой простой тип данных, который не занимает место в динамической памяти. Стандартная библиотека Zig сама заботится обо всех этих деталях. Это ещё одно преимущество использования конструкции fs.File.Metadata .

При сравнении файлов в течение времени необходимо сохранять старые метаданные при создании новых. Именно для этого и используется процедура клонирования метаданных.

pub fn clone(fmd: FileMetadata) !FileMetadata {
    var new_metadata = FileMetadata{
        .path = try fmd.allocator.dupe(u8, fmd.path),
        .md = fmd.md,
        .inode = fmd.inode,
        .checksum = null,
        .allocator = fmd.allocator,
    };
    if (fmd.checksum) |cs| {
        new_metadata.checksum = try fmd.allocator.dupe(u8, cs);
    }
    return new_metadata;
}

Этот метод создает полную копию объекта типа FileMetadata. При этом копируются все данные, связанные с файлом (путь к файлу, контрольная сумма и т. д.), чтобы избежать ситуаций, когда один и тот же файл используется несколькими процессами. По сути, это создание «генетической копии» файла, имеющей собственную память для хранения информации о файле.

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

fn computeFileHash(file: fs.File, allocator: std.mem.Allocator) ![]const u8 {
    var hasher = std.crypto.hash.sha2.Sha256.init(.{});

    // Use a 4KB buffer for reading
    var buffer: [4096]u8 = undefined;

    try file.seekTo(0);
    while (true) {
        const bytes_read = try file.read(&buffer);
        if (bytes_read == 0) break;
        hasher.update(buffer[0..bytes_read]);
    }

    var hash: [32]u8 = undefined;
    hasher.final(&hash);
    const hex_hash = try allocator.alloc(u8, 64);
    _ = try std.fmt.bufPrint(hex_hash, "{s}", .{std.fmt.fmtSliceHexLower(&hash)});

    return hex_hash;
}

Эта функция:

• Инициализирует алгоритм хэширования SHA-256.
• Файл считывается пакетами, чтобы избежать необходимости загрузки всего содержимого файла в память одновременно.
• Обновляется хэш с каждым блоком данных.
• Завершает процедуру генерации хэш-значения и преобразует его в шестнадцатеричную строку.

Подход, основанный на обработке блоков данных, имеет решающее значение для обеспечения высокой производительности и эффективного использования памяти. Представьте себе попытку хэширования 10-гигабайтного видеофайла путем его полной загрузки в оперативную память. В таком случае работа системы будет существенно замедлена. Это похоже на ситуацию, когда разработчику приходится сталкиваться с неожиданными сложностями в процессе реализации проекта.

Одной из наиболее привлекательных особенностей нашей реализации является то, что некоторые аспекты работы с данными вообще не требуют ручного управления. Мы не занимаемся обработкой различных форматов временных меток на разных операционных системах. Нам также не нужно переписывать механизмы обработки информации, связанной с правами доступа к файлам, для каждой платформы. Кроме того, нам не приходится иметь дело с различными интерфейсами для работы с атрибутами файлов.

Благодаря использованию функций класса Zig fs.File.Metadata мы получаем возможность работы приложения на разных платформах. Стандартная библиотека скрывает все различия между разными платформами:

• В Windows временные метки измеряются с интервалом в 100 наносекунд, начиная с 1 января 1601 года.
• Системы типа Unix, в которых для отсчета времени используются секунды и наносекунды, начало отсчета – 1 января 1970 года.
• Разные модели разрешений в разных операционных системах
• Различные системы атрибутов файлов: атрибуты файлов в Windows NTFS по сравнению с режимами файлов в Unix.

Есть одна область, в которой платформы существенно отличаются друг от друга – это количество идентификаторов файлов. В системах типа Unix эти идентификаторы являются надежными и уникальными, они сохраняются даже при перемещении или переименовании файлов. В Windows ситуация несколько иная: эквивалентные идентификаторы файлов работают по-другому. Поэтому при работе с файлами в Windows необходимо быть более осторожным.

Использование стандарта MD для хранения всех метаданных, связанных с конкретной платформой, позволяет сохранять код простым и понятным, сосредоточив внимание исключительно на самой задаче – мониторинге файлов. Это похоже на ситуацию, когда квалифицированный переводчик занимается всеми нюансами языка, а вы можете сосредоточиться на самом смысле сообщения.

Благодаря всем этим элементам, наш полноценный модуль file_metadata.zig позволяет эффективно собирать, хранить и сравнивать информацию о файлах на разных операционных системах. Этот модуль безопасен в использовании, эффективен и справляется со всеми особенностями работы с файлами на разных платформах благодаря стандартной библиотеке Zig.

Эта основа в виде метаданных является ключевым элементом всей нашей системы мониторинга. Без надежной информации о файлах попытки выявления различий между ними будут бесполезными, подобно попыткам детально различить фотографии сделанными с помощью фотокамеры старого кнопочного телефона из начала нулевых.

Теперь, когда мы реализовали структуру метаданных файлов, мы можем перейти к их организации. В следующем разделе мы создадим структуру FileIndex, которая будет хранить и упорядочивать метаданные файлов для удобства поиска и сравнения информации. Эта структура станет основой нашей системы обнаружения изменений, позволяя нам быстро определять, что изменилось в каталоге между двумя сканированиями.

Теперь, когда мы можем собирать метаданные по отдельным файлам, нам необходим способ их организации. Представьте себе попытку отслеживать тысячи файлов, храня информацию о каждом из них в беспорядочной куче данных. На поиск необходимой информации уйдет гораздо больше времени, чем на само обнаружение изменений в файлах. Именно здесь и пригождается наш инструмент FileIndex.

Представьте себе FileIndex как цифровой аналог шкафа для хранения документов, в котором работает очень энергичный и профессиональный библиотекарь.

Метаданные хранятся таким образом, который позволяет быстро находить информацию по пути к файлу или по его идентификатору inode. Это также позволяет определять, существуют ли файлы на диске, а также сравнивать их состояние в разные временные периоды. Без такой структуры хранения данных процесс мониторинга файлов становился бы крайне затруднительным.

Давайте определим структуру индекса в файле file_index.zig:

pub const FileIndex = struct {
    // Map from file paths to their metadata
    files: std.StringHashMap(FileMetadata),

    // Map from inodes to file paths (for detecting file moves)
    inodes: std.AutoHashMap(u64, []const u8),

    // Allocator for managing memory
    allocator: std.mem.Allocator,

    // Track path allocations separately
    path_storage: std.StringHashMap(void),

    // Methods will go here...
};

В FileIndex содержатся две основные структуры данных:

• files: хэш-карта, позволяющий получать информацию о метаданных файлов по их пути.
• inodes: хеш-карта, которая позволяет находить пути к файлам по их идентификаторам (inode).

Двойная индексация имеет решающее значение для работы более сложных функций нашего программного обеспечения. Индекс путей к файлам понятен: нам необходимо знать, какие файлы существуют и каковы их метаданные. Но индекс inodes представляет наибольший интерес с точки зрения функциональности программы.

Путем сопоставления inode с путями к файлам мы можем определить, когда файл был перемещен или переименован. Таким образом можно избежать ошибочных сообщений о том, что файл удален в одном месте и создан в другом.

Похоже, что хранение информации о путях является излишним — зачем вообще сохранять информацию о путях в отдельной структуре данных? Ответ кроется в принципах управления памятью. Поскольку пути используются в качестве ключей в основной хеш-структуре, необходимо отслеживать, какие пути уже были выделены под хранение данных. Это позволяет правильно освободить эти ресурсы при уничтожении структуры данных.

Это похоже на ведение списка всех ярлыков, которые вы создали для отделений своего шкафа для хранения документов. Таким образом, вы сможете легко уничтожать эти ярлыки при выбрасывании шкафа.

Начнем с метода инициализации:

pub fn init(allocator: std.mem.Allocator) FileIndex {
    return FileIndex{
        .files = std.StringHashMap(FileMetadata).init(allocator),
        .inodes = std.AutoHashMap(u64, []const u8).init(allocator),
        .allocator = allocator,
        .path_storage = std.StringHashMap(void).init(allocator),
    };
}

Это довольно просто. Мы инициализируем наши хеш-карты с помощью предоставленного механизма выделения памяти. Следует отметить, что, в отличие от многих других наших функций, эта функция не может выполняться с ошибкой по памяти. Это связано с тем, что при инициализации хеш-карты память выделяется только тогда, когда в нее фактически добавляются элементы.

По окончании работы с индексом необходимо освободить всю память, которая им была занята:

pub fn deinit(self: *FileIndex) void {
    // First free all metadata objects
    var it = self.files.iterator();
    while (it.next()) |entry| {
        entry.value_ptr.deinit();
    }

    // Free all path strings we've tracked
    var path_it = self.path_storage.keyIterator();
    while (path_it.next()) |path_ptr| {
        self.allocator.free(path_ptr.*);
    }

    // Free the hashmaps themselves
    self.files.deinit();
    self.inodes.deinit();
    self.path_storage.deinit();
}

Эта процедура уборки оказывается сложнее, чем можно было бы ожидать. Нам необходимо сделать следующее:

1. Освободите все объекты типа FileMetadata, находящиеся в нашем индексе.
2. Освободите все строковые пути, которые мы выделили.
3. Освободите сами структуры типа хэш-карт.

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

Теперь давайте реализуем метод добавления файлов в наш индекс:

pub fn addFile(self: *FileIndex, metadata: FileMetadata) !void {
    const cloned = try metadata.clone();
    errdefer cloned.deinit();
    const path_copy = try self.allocator.dupe(u8, cloned.path);
    errdefer self.allocator.free(path_copy);
    try self.path_storage.put(path_copy, {});
    try self.files.put(path_copy, cloned);
    if (cloned.inode != 0) {
        try self.inodes.put(cloned.inode, path_copy);
    }
}

Вот что происходит:

• Мы клонируем метаданные, чтобы создать независимую копию.
• Мы создаем копию строки путём к файлу для использования в качестве ключа в хеш-карте.
• Мы отслеживаем распределение путей для последующей очистки.
• Мы добавляем метаданные в индекс наших файлов.
• Если у файла существует действительный inode, мы добавляем его в наш индекс.

Операторы типа errdefer служат своего рода «системами безопасности»: если происходит сбой при выделении ресурсов после того, как они уже были выделены, эти операторы обеспечивают очистку уже выделенных ресурсов. Это похоже на наличие автоматической системы по устранению ошибок, которая активируется только в случае возникновения проблем.

Нам необходимо несколько способов для получения информации из нашего индекса:

pub fn contains(self: *const FileIndex, path: []const u8) bool {
    return self.files.contains(path);
}

pub fn get(self: *const FileIndex, path: []const u8) ?*const FileMetadata
{
    return self.files.getPtr(path);
}

pub fn findByInode(self: *const FileIndex, inode: u64) ?[]const u8 {
    return self.inodes.get(inode);
}

Эти методы обеспечивают необходимую функциональность для выявления изменений:

• Функция contains позволяет узнать, существует ли файл в нашем индексе.
• Функция get позволяет получить метаданные файла по его пути.
• Метод findByInode позволяет найти путь к файлу по его inode.

Метод findByInode имеет особое значение для выявления случаев перемещения файлов. Если файл исчезает с местоположения A, но на местоположении B находится другой файл с тем же inode, это означает, что файл был перемещен, а не удален и затем снова создан.

При постоянном мониторинге файлов необходимо сохранять базовый индекс во время создания нового индекса.

После обнаружения изменений мы заменяем исходный индекс на новый. Для этого необходим способ копирования всего индекса целиком.

pub fn clone(self: *const FileIndex) !FileIndex {
    var cloned = FileIndex.init(self.allocator);
    errdefer cloned.deinit();

    var it = self.files.iterator();
    while (it.next()) |entry| {
        const original_metadata = entry.value_ptr.*;
        const metadata_clone = FileMetadata{
            .allocator = original_metadata.allocator,
            .path = try self.allocator.dupe(u8, original_metadata.path),
            .inode = original_metadata.inode,
            .md = original_metadata.md,
            .checksum = if (original_metadata.checksum) |cs|
                try self.allocator.dupe(u8, cs)
            else
                null,
        };

        errdefer {
            if (metadata_clone.checksum) |cs| {
                self.allocator.free(cs);
            }
            self.allocator.free(metadata_clone.path);
        }

        const path_copy = try cloned.allocator.dupe(u8, metadata_clone.path);
        errdefer cloned.allocator.free(path_copy);

        try cloned.path_storage.put(path_copy, {});
        try cloned.files.put(path_copy, metadata_clone);
        if (metadata_clone.inode != 0) {
            try cloned.inodes.put(metadata_clone.inode, path_copy);
        }
    }
    return cloned;
}

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

Тщательное управление памятью здесь имеет решающее значение. Для каждого пути и контрольной суммы создаются отдельные области памяти. Необходимо следить за тем, чтобы все эти области памяти правильно отслеживались и в конечном итоге освобождались. Это похоже на процесс создания копий каждого документа, хранящегося в вашем архиве, включая все ярлыки и папки, связанные с этими документами.

Нам также необходим способ удаления файлов из нашего индекса:

pub fn removeFile(self: *FileIndex, path: []const u8) void {
    if (self.files.fetchRemove(path)) |removed| {
        if (removed.value.inode != 0) {
            _ = self.inodes.remove(removed.value.inode);
        }
        removed.value.deinit();
        _ = self.path_storage.remove(removed.key);
        self.allocator.free(removed.key);
    }
}

В этом методе:

• Удаляет запись о файле из нашего индекса файлов.
• Если у файла существует действительный индекс inode, его также необходимо удалить из нашего индекса.
• Освобождает объект метаданных
• Удаляет данный путь из списка путей, которые отслеживаются, и освобождает его для дальнейшего использования.

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

Для целей отчетности и отладки полезно знать, сколько файлов находится в нашем индексе.

pub fn count(self: *const FileIndex) usize {
    return self.files.count();
}

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

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

Этот двойной подход позволяет нам добиться следующего:

• Эффективный поиск путей: Мы можем быстро проверить, существует ли файл, и получить его метаданные.
• Обнаружение перемещения файлов: Путем поиска файлов по идентификатору inode можно определить, когда файлы были перемещены или переименованы.
• Комплексное обнаружение изменений: Мы можем эффективно выявлять файлы, которые были созданы, удалены, изменены или перемещены.

Именно благодаря этой двойной системе индексации возможно реализовать одну из самых важных функций FileGuard: правильное различение между действиями по перемещению файлов и действиями по их удалению/созданию. Менее совершенные инструменты не всегда способны правильно определить эти действия.

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

При использовании отдельной структуры данных, в которой ключами являются пути, а значениями — пустые структуры (которые не занимают никакой памяти), мы можем легко просмотреть все пути, которые были выделены для использования. Это незначительная нагрузка на память, но при этом значительно упрощает процедуру очистки данных.

Этот подход отражает типичную особенность программирования на языке Zig — иногда небольшие дополнительные усилия по организации процесса управления памятью могут существенно улучшить эффективность и надежность работы программы.

Именно такой организованный подход делает FileGuard быстрым и эффективным в работе. Вместо того, чтобы при каждой проверке заново сканировать и просматривать всё содержимое папок, мы можем создавать индексы и сравнивать их между собой. Это похоже на то, как библиотекарь использует каталог, чтобы быстро найти необходимую информацию среди огромного количества книг, вместо того чтобы методом проб и ошибок искать нужные книги на полках.

Теперь, когда наши файлы индексированы, нам необходим способ заполнения этого индекса путем просмотра содержимого директорий и сбора информации о файлах. В следующем разделе мы реализуем механизм просмотра директорий с использованием фильтров на основе определенных шаблонов. Это позволит пользователям отслеживать именно те файлы, которые их интересуют.

Теперь, когда у нас есть метаданные файлов и структуры их индексации, нам необходим способ для поиска файлов, которые необходимо отслеживать. Именно здесь и пригождается процедура просмотра содержимого директорий – это своего рода исследование файловой системы, позволяющее определить все документы и исполняемые файлы, которые мы встречаем по пути.

Но не все исследователи хотят исследовать каждый темный уголок. Некоторые предпочитают избегать опасных областей, таких как папка «node_modules», а также сложных структур, связанных с символическими ссылками. Другие же могут интересоваться только определенными типами файлов: например, редкими исходными файлами формата .zig или обычными текстовыми документами в формате .txt.

Наш модуль traversal.zig обеспечивает удобство в настройках процесса исследования окружающей среды, такие возможности могли бы позавидовать даже системы GPS.

Прежде чем приступить к написанию кода для обработки данных, давайте определим, какие возможности имеют наши «исследователи». В файле config.zig мы определим структуру конфигурации.

pub const TraversalConfig = struct {
    max_depth: ?usize = null,
    include_patterns: []const []const u8 = &.{"*"},
    exclude_patterns: []const []const u8 = &.{},
    hash_content: bool = false,
    follow_symlinks: bool = false,
    current_depth: usize = 0,
};

Эти опции позволяют нам точно контролировать процесс просмотра контента:

• max_depth: Насколько глубоко мы готовы проникнуть в структуру каталогов.
• include_patterns: Какие типы файлов нас интересуют (например, «.zig», «.txt»).
• exclude_patterns: Файловые типы или директории, которые необходимо исключить из процесса обработки (например, «.tmp», «node_modules/»).
• hash_content: Необходимо ли вычислять хэш-значения содержимого файла (процесс занимает больше времени, но результаты более точные).
• follow_symlinks: Необходимо ли следовать за символическими ссылками (это может быть опасно, но иногда такой подход необходим).
• current_depth: Внутренняя информация о том, на какой глубине мы находимся в данный момент.

Считайте это своим снаряжением для путешествий: мачете для пробивания себе путь сквозь заросли (функция сопоставления шаблонов), прибор для измерения глубины при исследовании пещер (параметр max_depth), а также надежную карту, которая предупреждает о опасных «символических ловушках», из-за которых можно бесконечно ходить по кругу, пока не иссякнет объем памяти и человек не умрет.

Одним из важных шагов перед тем, как мы сможем просматривать содержимое директорий, является определение того, какие файлы соответствуют заданным условиям. Давайте реализуем механизм сопоставления файлов с заданными шаблонами в файле pattern.zig:

const c = @cImport({
    @cInclude("stdlib.h");
    @cInclude("fnmatch.h");
});

pub fn matches(pattern: []const u8, name: []const u8) bool {
    const patternC: [*c]const u8 = @ptrCast(pattern.ptr);
    const nameC: [*c]const u8 = @ptrCast(name.ptr);
    const rc: c_int = c.fnmatch(patternC, nameC, 0);
    return rc == 0;
}

pub fn matchesAnyPattern(patterns: []const []const u8, path: []const u8) bool {
    for (patterns) |pattern| {
        if (matches(pattern, path)) {
            return true;
        }
    }
    return false;
}

Здесь мы используем функцию fnmatch из языка C для обработки шаблонов. Это прекрасный пример того, насколько хорошо Zig совместим с языком C. Зачем изобретать велосипед заново, когда существует уже отлаженный код для обработки шаблонов, доступный через простую инструкцию @cImport?

Функция matches проверяет, соответствует ли определенный путь файлу какому-либо шаблону. Функция matchesAnyPattern же проверяет, соответствует ли путь хотя бы одному из шаблонов в списке. Просто, но эффективно.

С использованием механизма сопоставления шаблонов мы можем определить, какие файлы необходимо включить в процесс мониторинга:

fn shouldIncludeFile(path: []const u8, config: *const TraversalConfig) bool {
    // Exclusion patterns take precedence over inclusion patterns
    if (pattern.matchesAnyPattern(config.exclude_patterns, path)) {
        return false;
    }
    // Check if the file matches any inclusion pattern
    return pattern.matchesAnyPattern(config.include_patterns, path);
}

Эта функция следует простому правилу: если файл соответствует какому-либо из правил исключения, его игнорируют. В противном случае, файл включается в список разрешенных к использованию, если он соответствует какому-либо из правил включения. Правила исключения всегда имеют приоритет. Можно представить себе это как ситуацию, когда охранник в клубе проверяет список запрещенных к входу лиц ещё до того, как посмотреть общий список приглашенных гостей.

Теперь перейдем к главному элементу – функции просмотра содержимого каталогов:

pub fn traverseDirectory(
    index: *FileIndex,
    dir_path: []const u8,
    config: *const TraversalConfig,
) !void {
    // Open the directory
    var dir = try std.fs.cwd().openDir(dir_path, .{ .iterate = true });
    defer dir.close();

    // Iterate through directory entries
    var iter = dir.iterate();
    while (try iter.next()) |entry| {
        // Construct the full path
        const full_path = try std.fs.path.join(
            index.allocator,
            &[_][]const u8{ dir_path, entry.name }
        );
        defer index.allocator.free(full_path);

        // Handle different entry types
        switch (entry.kind) {
            .file => {
                // Check if the file should be included
                if (shouldIncludeFile(full_path, config)) {
                    // Get metadata and add to index
                    const metadata = try FileMetadata.init(
                        index.allocator,
                        full_path,
                        config.hash_content
                    );
                    try index.addFile(metadata);
                }
            },
            .directory => {
                // Check depth limit before recursing
                if (config.max_depth == null or config.current_depth < config.max_depth.?) {
                    // Create a new config with incremented depth
                    var next_config = config.*;
                    next_config.current_depth += 1;
                    // Recursively process subdirectory
                    try traverseDirectory(index, full_path, &next_config);
                }
            },
            .sym_link => {
                if (config.follow_symlinks) {
                    // Handle symlinks (implementation omitted for brevity)
                    // This would resolve the symlink and either process the target file
                    // or recursively traverse the target directory
                }
            },
            else => {}, // Skip other types (pipes, devices, etc.)
        }
    }
}

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

• Мы открываем каталог и просматриваем все его элементы по очереди.
• Для каждой записи мы определяем её полный путь.
• В зависимости от типа входных данных мы действуем следующим образом:
  • Что касается файлов: необходимо проверить, соответствуют ли они нашим критериям. Если да, их следует добавить в индекс.
  • Что касается каталогов: необходимо рекурсивно просматривать их, если мы ещё не достигли предела глубины просмотра.
  • Что касается символических ссылок: следуйте им, если это предусмотрено настройками.
  • Что касается остальных типов: игнорируйте их.

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

Символьные ссылки заслуживают особого внимания, поскольку они могут создавать циклы в файловой системе, которая обычно имеет древовидную структуру. Если ссылка А указывает на каталог Б, а в каталоге Б находится ссылка В, которая, в свою очередь, указывает на родительский каталог ссылки А, то возникает бесконечный цикл. Это может привести к серьезным проблемам при использовании рекурсивных алгоритмов.

Вот как мы обрабатываем символические ссылки (в упрощенном виде):

.sym_link => {
    if (config.follow_symlinks) {
        const target_path = try dir.readLink(entry.name, &[_]u8{});
        const resolved_path = try std.fs.path.resolve(
            index.allocator,
            &[_][]const u8{ dir_path, target_path }
        );
        defer index.allocator.free(resolved_path);
        const target_stat = try std.fs.cwd().statFile(resolved_path);
        if (target_stat.kind == .directory) {
            if (config.max_depth == null or config.current_depth < config.max_depth.?) {
                var next_config = config.*;
                next_config.current_depth += 1;
                try traverseDirectory(index, resolved_path, &next_config);
            }
        } else if (target_stat.kind == .file) {
            // Process target file (if it matches patterns)
            if (shouldIncludeFile(resolved_path, config)) {
                const metadata = try FileMetadata.init(
                    index.allocator,
                    resolved_path,
                    config.hash_content
                );
                try index.addFile(metadata);
            }
        }
    }
}

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

Опасность, связанная с символическими ссылками, заключается не только в возможности возникновения бесконечных циклов обработки данных. Символические ссылки также могут привести к необходимости многократной обработки одного и того же файла по разным путям. Более сложные реализации могут учитывать те индексы файлов, которые уже были обработаны, чтобы избежать этой проблемы. Но ради простоты мы готовы пойти на такое дублирование действий при обработке файлов.

Давайте отступим на шаг назад и посмотрим, как все эти элементы взаимодействуют между собой.

• Пользователь сам определяет, какие файлы необходимо отслеживать, с помощью правил включения и исключения.
• Наша функция просмотра элементов директории проходит по всей структуре директорий, с соблюдением ограничений по глубине проникновения в структуру директорий.
• Для каждого найденного файла мы проверяем, соответствует ли он нашим шаблонам.
• Если это происходит, мы создаем для таких элементов метаданные и добавляем их в наш индекс.
• В итоге получается удобный для использования указатель всех файлов, которые нас интересуют.

Такой избирательный подход к обработке данных крайне важен для эффективной работы системы. Представьте себе ситуацию, когда необходимо отслеживать директорию, содержащую тысячи файлов, но при этом важны лишь несколько десятков конфигурационных файлов. Благодаря фильтрации в процессе обработки данных мы избегаем пустой траты времени и памяти на обработку файлов, которые нам вообще не нужны.

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

• Селективное хэширование: Хэширование контента по умолчанию отключено и выполняется только по прямой просьбе пользователя.
• Ограничение глубины просмотра: Параметр max_depth предотвращает ненужное проникновение в глубокие уровни структуры каталогов.
• Фильтрация по шаблонам: Мы обрабатываем только те файлы, которые соответствуют нашим шаблонам включения и не соответствуют шаблонам исключения.
• Отложенная очистка: Мы используем механизм отложенной обработки для очистки используемых ресурсов. Это позволяет освободить память даже в случае возникновения ошибок.

Эти меры оптимизации позволяют программе FileGuard сохранять свою эффективность даже при мониторинге крупных структур каталогов.

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

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

Теперь, когда у нас уже готовы системы обработки метаданных файлов, их индексации и поиска, мы можем приступить к решению последней проблемы – выявлению изменений, происходящих между процедурами индексации. В следующем разделе мы реализуем логику обнаружения изменений, которая позволит выявлять файлы, которые были созданы, удалены, изменены или перемещены. Таким образом, наш инструмент FileGuard станет полноценно функциональным.

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

Что касается файлов, то с ними может происходить несколько видов изменений:

• Создание: Файл, которого раньше не существовало, вдруг появляется.
• Удаление: Файл, который раньше существовал, исчезает в цифровом пространстве.
• Изменение: содержимое файла изменилось.
• Перемещение: Файл перемещается на другой путь.
• Изменения в правах доступа: Права доступа к файлу были изменены.
• Обновления временных меток: Временные метки файла меняются без изменения самого содержимого файла.

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

Давайте сначала определим типы изменений, которые мы можем обнаружить в файле change_detection.zig:

pub const ChangeType = enum {
    created,    // File is new
    deleted,    // File no longer exists
    modified,   // File content has changed
    moved,      // File was moved or renamed
    permissions, // Permissions have changed
    timestamp,  // Timestamp has changed without content changes
};

Этот перечень охватывает все типы изменений, которые может обнаружить FileGuard. Это своего рода «словарь» языка, используемого для описания изменений. Разница между фразами вроде «Файл изменился каким-то образом» и более конкретным описанием, например «Файл был перемещен с места А в место Б», и заключается именно в использовании этого перечня.

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

pub const FileChange = struct {
    // Type of change that was detected
    change_type: ChangeType,
    // Original path of the file (null for created files)
    old_path: ?[]const u8,
    // Current path of the file (null for deleted files)
    new_path: ?[]const u8,
    // Original metadata (null for created files)
    old_metadata: ?FileMetadata,
    // Current metadata (null for deleted files)
    new_metadata: ?FileMetadata,
    // When the change was detected
    timestamp: i64,
    // Allocator for memory management
    allocator: std.mem.Allocator,

    // Methods for initialization and cleanup
    // ...
};

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

Для хранения нескольких изменений мы создадим специальный журнал изменений:

pub const ChangeJournal = struct {
    // List of detected changes
    changes: std.ArrayList(FileChange),

    // Allocator for memory management
    allocator: std.mem.Allocator,

    // Methods for initialization, cleanup, and recording changes
    // ...
};

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

Разные пользователи придают разное значение разным типам изменений. Поэтому нам необходима структура для настройки этих параметров.

pub const DetectionConfig = struct {
    // Enable timestamp monitoring
    monitor_timestamps: bool = true,

    // Enable size change detection
    monitor_size: bool = true,

    // Enable content hash comparison
    monitor_content: bool = false,

    // Enable permission change detection
    monitor_permissions: bool = false,

    // Enable move detection using inodes
    detect_moves: bool = true,
};

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

Теперь перейдем к главному элементу – алгоритму обнаружения изменений. Давайте разберем его на более простые составляющие.

Сначала мы настроим необходимую функцию и начнем поиск удаленных файлов:

pub fn detectChanges(
    old_index: *const FileIndex,
    new_index: *const FileIndex,
    config: *const DetectionConfig,
    journal: *ChangeJournal,
) !void {
    // Step 1: Find deleted files (in old but not in new)
    var old_iterator = old_index.files.iterator();
    while (old_iterator.next()) |entry| {
        const path = entry.key_ptr.*;
        const old_metadata = entry.value_ptr.*;
        if (!new_index.contains(path)) {
            // This file is in the old index but not the new one
            // It might be deleted or moved...

Если файл отсутствует в новом индексе, мы проверяем, возможно, его просто переместили, а не удалили.

           if (config.detect_moves) {
                // Check if the file was moved (same inode appears elsewhere)
                if (old_metadata.inode != 0) {
                    if (new_index.findByInode(old_metadata.inode)) |new_path| {
                        // File was moved/renamed
                        const new_metadata_opt = new_index.get(new_path);
                        if (new_metadata_opt) |new_metadata_ptr|
                        try journal.recordChange(
                            .moved,
                            path,
                            new_path,
                            old_metadata,
                            new_metadata_ptr.*,
                        );
                        continue; // Skip recording as deleted
                    }
                }
            }
            // If we got here, the file was truly deleted
            try journal.recordChange(
                .deleted,
                path,
                null,
                old_metadata,
                null,
            );
        }
    }

Далее мы ищем созданные и измененные файлы:

   // Step 2: Find created and modified files (in new but maybe not in old)
    var new_iterator = new_index.files.iterator();
    while (new_iterator.next()) |entry| {
        const path = entry.key_ptr.*;
        const new_metadata = entry.value_ptr.*;
        if (old_index.get(path)) |old_metadata| {
            // File exists in both - check for modifications
            try detectFileModifications(
                path,
                old_metadata.*,
                new_metadata,
                config,
                journal,
            );
        } else {
            // This file is in the new index but not the old one
            // It might be new or the destination of a move...

Когда файл находится в новом индексе, но не в старом, мы проверяем, не является ли он целью перемещения.

            // Skip files already detected as moved
            var was_move = false;
            if (config.detect_moves and new_metadata.inode != 0) {
                // Check if this is the destination of a move operation
                if (old_index.findByInode(new_metadata.inode)) |_| {
                    was_move = true;
                }
            }
            if (!was_move) {
                // New file (not detected as moved)
                try journal.recordChange(
                    .created,
                    null,
                    path,
                    null,
                    new_metadata,
                );
            }
        }
    }
}

Секрет данного решения заключается в способе обнаружения изменений с местоположением файлов. С помощью inode файлов мы можем определить, был ли файл просто переименован или перемещен, а не удален и заново создан. Это похоже на ситуацию, когда человек остается тем же человеком, даже если меняет имя или переезжает в другой дом.

Когда файл присутствует как в старом, так и в новом индексах, необходимо проверить, что именно изменилось в нем (если вообще что-то изменилось). Давайте рассмотрим это по типам изменений.

Во-первых, мы определяем структуру функции и проверяем наличие изменений в её содержимом:

fn detectFileModifications(
    path: []const u8,
    old_metadata: FileMetadata,
    new_metadata: FileMetadata,
    config: *const DetectionConfig,
    journal: *ChangeJournal,
) !void {
    // Check content changes first (highest priority)
    if (config.monitor_content) {
        // If both have checksums and they don't match, content changed
        if (old_metadata.checksum != null and new_metadata.checksum != null) {
            if (!std.mem.eql(u8, old_metadata.checksum.?, new_metadata.checksum.?)) {
                try journal.recordChange(
                    .modified,
                    path,
                    path,
                    old_metadata,
                    new_metadata,
                );
                return; // No need to check other modifications
            }
        }
    }

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

Далее мы проверяем изменения в размерах:

    // Check size changes
    if (config.monitor_size) {
        if (old_metadata.md.size() != new_metadata.md.size()) {
            try journal.recordChange(
                .modified,
                path,
                path,
                old_metadata,
                new_metadata,
            );

            return; // No need to check other modifications
        }
    }

Изменения в размерах также являются значимыми изменениями. Поэтому, если мы обнаруживаем такие изменения, мы записываем их, не занимаясь проверкой разрешений или временных меток.

Затем мы проверяем наличие изменений в правах доступа:

    // Check permission changes
    if (config.monitor_permissions) {
        if (!std.meta.eql(old_metadata.md.permissions(), new_metadata.md.permissions())) {
            try journal.recordChange(
                .permissions,
                path,
                path,
                old_metadata,
                new_metadata,
            );
        }
    }

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

Наконец, мы проверяем наличие изменений в временных метках.

    // Check timestamp changes
    if (config.monitor_timestamps) {
        // Focus on modification time
        const old_mtime = old_metadata.md.modified();
        const new_mtime = new_metadata.md.modified();
        if (old_mtime != new_mtime) {
            try journal.recordChange(
                .timestamp,
                path,
                path,
                old_metadata,
                new_metadata,
            );
        }
    }
}

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

Одной из самых примечательных особенностей FileGuard является его способность выявлять файлы, которые были перемещены или переименованы. Именно здесь проявляется всё преимущество двойной системы индексации FileGuard: индексация по пути хранения файла и по его идентификатору inode.

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

Это важное различие. Представьте себе, что вы отслеживаете файлы с исходным кодом. Знание о том, что файл был перемещен, гораздо полезнее информации о том, что он был удален в одном месте и создан в другом, особенно если содержимое файлов идентично.

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

Благодаря этим компонентам – типам изменений, записям об изменениях, журналу записей изменений, настройкам и алгоритмам их обнаружения – у нас получается полноценная система для определения того, что изменилось в каталоге между двумя процедурами сканирования.

Это и есть суть функции FileGuard – системы, которая выявляет все изменения, произошедшие во время отсутствия пользователя. Будь то изменение содержимого файлов, их перемещение из одного места в другое или просто исчезновение из числа доступных файлов, наша система обнаружения изменений обязательно зафиксирует все эти действия.

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

У нас есть прочная основа для дальнейшего развития, но в настоящее время эта основа скрыта за механизмами обработки данных и структурами хранения информации. Что нам сейчас необходимо, так это своего рода «мост» между этими техническими возможностями и людьми, которые хотят ими пользоваться.

В следующем разделе мы создадим интерфейс командной строки, который превратит наши алгоритмы мониторинга в практический инструмент. Благодаря этому пользователи смогут настраивать параметры мониторинга, подбирать формат выводимой информации и взаимодействовать с программой FileGuard с помощью стандартных командной строки команд.

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

Создание хорошего интерфейса командной линии оказывается сложнее, чем кажется на первый взгляд. Необходимо учитывать множество параметров, проверять вводимые пользователем данные, отображать полезные сообщения об ошибках, а также форматировать результаты обработки так, чтобы их было легко понять как для людей, так и для программ. Это вопрос того, станет ли инструмент полезным для пользователей или же заставит их сомневаться в правильности своего выбора. Давайте рассмотрим процесс создания интерфейса командной линии для FileGuard. Мы преобразуем мощный механизм обнаружения ошибок в инструмент, который смогут использовать обычные люди, без необходимости специальных навыков программирования.

Сначала давайте определим, какие опции будет поддерживать наша командная строка в файле cli.zig:

pub const CliOptions = struct {
    // Global options
    help: bool = false,
    verbose: bool = false,

    // Monitoring options
    include_patterns: []const u8 = "*",
    exclude_patterns: []const u8 = "",
    max_depth: ?usize = null,
    hash_content: bool = false,
    follow_symlinks: bool = false,
    monitor_timestamps: bool = true,
    monitor_size: bool = true,
    monitor_content: bool = false,
    monitor_permissions: bool = false,
    detect_moves: bool = true,
    continuous: bool = false,
    interval: u64 = 60,

    // More fields and methods...
};

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

Чтобы сделать интерфейс командной строки более удобным в использовании, мы также определили сокращения для наиболее часто используемых параметров.

// Shorthands for command-line options
pub const shorthands = .{
    .h = "help",
    .v = "verbose",
    .i = "include_patterns",
    .x = "exclude_patterns",
    .d = "max_depth",
    .c = "hash_content",
    .s = "follow_symlinks",
    .t = "monitor_timestamps",
    .z = "monitor_size",
    .C = "monitor_content",
    .p = "monitor_permissions",
    .m = "detect_moves",
    .w = "continuous",
    .n = "interval",
};

Эти сокращения позволяют пользователям вводить команду -v вместо --verbose. Это экономит время, которое можно было бы потратить на жалобы на то, насколько медленно работает код других людей (и это перечисление потом больше нигде не упоминается, т.ч. как оно помогает – вопрос открытый, если не посмотреть в исходный код, – прим. переводчика).

Для обработки аргументов командной строки мы будем использовать внешнюю библиотеку. Это позволяет нам избежать необходимости самостоятельной реализации сложных механизмов обработки аргументов и сосредоточиться на собственно функциях мониторинга.

Вот как мы обрабатываем аргументы в нашей функции run:

pub fn run() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Parse command-line arguments
    const args = try argsParser.parseForCurrentProcess(
        CliOptions,
        allocator,
        .print,
    );
    defer args.deinit();

    // Show help if requested
    if (args.options.help) {
        return showHelp(args.executable_name orelse "fileguard");
    }

    // Get the path to monitor (first positional argument, or default to ".")
    const path = if (args.positionals.len > 0) args.positionals[0] else ".";

    // More code...
}

Этот код:

• Предоставляет универсальный механизм распределения памяти для ее управления.
• Преобразует аргументы командной строки в структуру типа CliOptions.
• Показывает информацию по помощи, если используется флаг --help.
• Определяет путь, по которому будет осуществляться мониторинг (по умолчанию используется текущий каталог, если путь не указан).

Обратите внимание на то, как мы используем оператор defer в языке Zig для обеспечения того, чтобы ресурсы были корректно очищены даже в случае возникновения ошибок во время выполнения программы или завершении функции. Это один из самых полезных операторов языка Zig для создания надежного кода. Это похоже на ситуацию, когда фигурки в игре автоматически падают друг за другом и убирают за собой беспорядок после того, как человек покидает комнату.

Когда пользователи используют параметр --help, мы хотим показать им подробную документацию. Вот наша функция showHelp:

fn showHelp(program_name: []const u8) !void {
    const stdout = std.io.getStdOut().writer();
    try stdout.print("Usage: {s} [OPTIONS] [PATH]\n\n", .{program_name});
    try stdout.writeAll("A file monitoring system that detects and reports changes to the console.\n\n");
    try stdout.writeAll("If PATH is not specified, the current directory will be monitored.\n\n");
    try stdout.writeAll("Options:\n");
    try stdout.writeAll("  -h, --help               Show this help message\n");
    try stdout.writeAll("  -v, --verbose            Enable verbose output\n\n");
    // More options omitted for brevity...
}

Хороший текст с описанием функций инструмента имеет решающее значение для качества пользовательского опыта. Именно он определяет, сможет ли пользователь за несколько секунд понять, как использовать инструмент, или же ему придется отказаться от использования данного инструмента и создать свою собственную, гораздо худшую версию инструмента.

После того, как конфигурация была обработана и проверена, мы можем приступить к самому процессу мониторинга:

fn runMonitor(
    allocator: std.mem.Allocator,
    path: []const u8,
    options: CliOptions,
) !void {
    // First validate the path
    try validatePath(path);
    if (options.verbose) {
        std.debug.print("Monitoring {s} for changes\n", .{path});
    }

    // Resolve the real path
    const real_path = try std.fs.realpathAlloc(allocator, path);
    defer allocator.free(real_path);

    // Split the pattern strings into arrays
    const include_patterns = try splitPatterns(allocator, options.include_patterns);
    defer {
        for (include_patterns) |pattern| {
            allocator.free(pattern);
        }
        allocator.free(include_patterns);
    }
    const exclude_patterns = try splitPatterns(allocator, options.exclude_patterns);
    defer {
        for (exclude_patterns) |pattern| {
            allocator.free(pattern);
        }
        allocator.free(exclude_patterns);
    }

    // Set up configurations and baseline index
    // ...
}

Эта часть функции:

• Проверяется, существует ли указанный путь и является ли он доступным для использования.
• Преобразует путь в абсолютный путь.
• Разделяет шаблоны включения и исключения.
• Обеспечивается эффективное управление памятью с помощью операторов defer.

Далее мы настраиваем параметры обработки данных и выявления необходимых элементов, а также создаем исходный индекс.

   // Create traversal configuration
    const traverse_config = TraversalConfig{
        .include_patterns = include_patterns,
        .exclude_patterns = exclude_patterns,
        .max_depth = options.max_depth,
        .hash_content = options.hash_content,
        .follow_symlinks = options.follow_symlinks,
    };

    // Create detection configuration
    const detect_config = DetectionConfig{
        .monitor_timestamps = options.monitor_timestamps,
        .monitor_size = options.monitor_size,
        .monitor_content = options.monitor_content,
        .monitor_permissions = options.monitor_permissions,
        .detect_moves = options.detect_moves,
    };

    // Create baseline index
    std.debug.print("Creating initial baseline index...\n", .{});
    var baseline_index = FileIndex.init(allocator);
    defer baseline_index.deinit();

    // Traverse directory for baseline
    try traverseDirectory(&baseline_index, real_path, &traverse_config);
    if (options.verbose) {
        std.debug.print("Baseline index created with {d} files\n", .{baseline_index.count()});
    }

Здесь:

• Создаётся объект TraversalConfig на основе параметров, введенных через командную строку.
• Создаётся объект типа DetectionConfig на основе параметров, заданных через командную строку.
• Создаётся исходный индекс файлов для сравнения.
• Производится анализ содержимого директории для формирования исходного индекса.

Наконец, мы переходим к этапу мониторинга:

    // Determine if we're doing continuous monitoring or a single check
    const is_continuous = options.continuous;
    const interval_ns = options.interval * std.time.ns_per_s;
    var last_change_time: i64 = 0;
    std.debug.print("Monitoring started. ", .{});

    if (is_continuous) {
        std.debug.print("Will check every {d} seconds. Press Ctrl+C to stop.\n", .{options.interval});
    } else {
        std.debug.print("Will perform a single check.\n", .{});
    }

    // Monitor loop
    while (!should_exit) {
        var current_index = FileIndex.init(allocator);
        defer current_index.deinit();

        // Traverse directory
        traverseDirectory(&current_index, real_path, &traverse_config) catch |err| {
            std.debug.print("Error during directory traversal: {}\n", .{err});
            std.debug.print("Will retry on next cycle\n", .{});
            if (!is_continuous) {
                return err;
            } else {
                std.time.sleep(interval_ns);
                continue;
            }
        };

        // Detect and report changes
        // ...
        // If not continuous monitoring, break
        if (!is_continuous) {
            break;
        }

        // Sleep for the interval
        std.time.sleep(interval_ns);
    }

Эта часть:

• Определяет, будет ли осуществляться непрерывный мониторинг или же будет проведена лишь одна проверка.
• Программа входит в цикл, который продолжается до момента её завершения.
• На каждой итерации создается новый индекс.
• Проходит по всем элементам каталога для заполнения текущего индекса.
• Умеет грамотно справляться с ошибками.
• При включенном режиме непрерывного мониторинга процесс выполнения задачи приостанавливается между отдельными итерациями.

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

// Create a change journal
var change_journal = ChangeJournal.init(allocator);
defer change_journal.deinit();

// Detect changes
try detectChanges(&baseline_index, &current_index, &detect_config, &change_journal);

// If changes were detected
if (change_journal.count() > 0) {
    const timestamp = std.time.timestamp();
    std.debug.print("\n=== Changes detected at {d} ({d} changes) ===\n\n", .{
        timestamp,
        change_journal.count(),
    });

    // Print each change
    for (change_journal.changes.items) |change| {
        printChange(change, allocator) catch |err| {
            std.debug.print("Error printing change: {}\n", .{err});
        };
    }
    std.debug.print("\n", .{});
    last_change_time = timestamp;

    // Update baseline by creating a fresh copy of current_index
    const new_baseline = try current_index.clone();
    baseline_index.deinit();
    baseline_index = new_baseline;
} else {
    if (options.verbose) {
        std.debug.print("No changes detected at {}\n", .{std.time.timestamp()});
    }
}

Этот код:

• Создает журнал изменений для хранения информации о всех обнаруженных изменениях.
• Запускает алгоритм обнаружения изменений
• Отчитывается обо всех обнаруженных изменениях в удобочитаемом формате.
• Обновляет базовый индекс до текущего значения для следующей итерации.

Фактическая обработка изменений осуществляется с помощью отдельной функции:

fn printChange(change: FileChange, allocator: std.mem.Allocator) !void {
    const stdout = std.io.getStdOut().writer();
    const old_path = change.old_path orelse "unknown";
    const new_path = change.new_path orelse "unknown";
    switch (change.change_type) {
        .created => {
            try stdout.print("[{d}] CREATED: {s}\n", .{
                change.timestamp,
                new_path,
            });
        },
        .deleted => {
            try stdout.print("[{d}] DELETED: {s}\n", .{
                change.timestamp,
                old_path,
            });
        },
        // Other change types...
    }

    // Show additional details for certain change types
    // ...
}

Эта функция форматирует информацию о каждой изменении таким образом, чтобы её было легко понять человеку. При этом указываются временные моменты, когда происходили изменения, а также подробная информация о том, что именно изменилось. В случае сложных изменений, например, при модификации содержимого файла, функция указывает, какие именно элементы файла изменились (размер, содержимое и т. д.).

Надежная командная оболочка должна уметь грамотно справляться с ошибками. Давайте рассмотрим, как можно проверить правильность пути, по которому будет осуществляться мониторинг.

fn validatePath(path: []const u8) !void {
    var dir = std.fs.cwd().openDir(path, .{}) catch |err| {
        switch (err) {
            error.FileNotFound => {
                std.debug.print("Error: Path '{s}' does not exist\n", .{path});
                return error.PathNotFound;
            },
            error.AccessDenied => {
                std.debug.print("Error: Access denied to path '{s}'\n", .{path});
                return error.AccessDenied;
            },
            else => {
                std.debug.print("Error: Unable to access path '{s}': {}\n", .{ path, err });
                return err;
            },
        }
    };
    dir.close();
}

Эта функция пытается открыть указанный каталог. В зависимости от причины возникшей ошибки программа выдает соответствующие сообщения об ошибках. Это гораздо удобнее для пользователя, чем ситуация, когда программа просто выходит из строя с общим сообщением об ошибке.

Аналогичным образом, механизм обработки ошибок в процессе просмотра структуры каталогов в цикле мониторинга гарантирует, что временные сбои (например, блокировка файла) не приведут к сбою всего процесса мониторинга в режиме непрерывной работы.

Благодаря всем этим элементам наша командная строка предоставляет полноценный и удобный в использовании интерфейс для работы с функциями FileGuard. Пользователи могут:

• Наличие/отсутствие определенных файлов в списке контроля можно настроить с помощью правил включения и исключения.
• Управляйте степенью глубины просмотра структуры каталогов.
• Выберите, какие именно типы изменений необходимо обнаруживать.
• Проводите либо однократную проверку, либо постоянный мониторинг.
• Получайте четкие и понятные отчеты о выявленных изменениях.

С помощью CLI инструмент FileGuard превращается из набора алгоритмов в полезный инструмент, который могут использовать реальные люди для решения конкретных проблем.

Итак, допустим, вы перешли от «Привет, я изучаю Zig!» к «Этот инструмент мониторинга файлов будет внедрен в наш критически важный производственный процесс!» быстрее, чем вы можете сказать «разработка на основе резюме». Но прежде чем размещать этот инструмент на серверах cвоей компании и обновлять свой профиль на LinkedIn до состояния «Ищу новые возможности», подумайте о добавлении следующих функций:

• Форматы выходных данных: Поддерживаются форматы, понятные для обработки компьютером, такие как JSON или CSV. Ведь Дэйв из отдела DevOps точно разозлится, если ему снова придется обрабатывать данные в формате stdout с помощью регулярных выражений.
• Логирование: Изменения записываются непосредственно в лог-файлы, а не в стандартный вывод. Это способствует тому, что при необходимости доказать, что именно не ваше приложение удалило презентацию генерального директора, лог-файлы будут доступны для анализа.
• Уведомления: Предупреждения отправляются по электронной почте, через службу Slack или с помощью голубей-посыльных. Таким образом, вы сможете получить уведомление в 3 часа ночи, если кто-то внесет изменения в временный файл.
• Фильтры: Более сложная обработка информации о произошедших изменениях. Ведь никому не нужно 500 уведомлений о том, что изменились файлы с расширением .DS_Store.
• Интеграционные хуки: Выполнение пользовательских команд при обнаружении изменений. Например, автоматический запуск скрипта для редактирования резюме при исчезновении важных файлов.

Помните: существует тонкая грань между проектом, который можно назвать «потрясающим решением для выходных», и проектом, который становится причиной срочного собрания всего персонала в понедельник. Именно эти улучшения могут определить то, будут ли ваши коллеги считать данный проект полезным инструментом для работы, или же будут считать его причиной серьезных проблем.

Теперь, когда мы реализовали интерфейс командной строки, мы завершили создание всех основных компонентов нашего инструмента FileGuard. В следующем разделе мы объединим все эти компоненты в единое целое в рамках нашей основной программы. Также мы рассмотрим более общие аспекты создания инструментов с интерфейсом командной строки на языке Zig.

Мы разработали все составляющие нашей системы FileGuard: механизмы отслеживания метаданных файлов, их индексирования, обработки запросов к каталогам, сопоставления файлов с определенными шаблонами, обнаружения изменений в файлах, а также интерфейс командной строки.

Теперь пришло время объединить все эти компоненты в одном файле main.zig. Именно этот файл служит своего рода «оркестратором», который превращает все эти элементы в целостное приложение.

По сравнению с сложностью других наших модулей, файл main.zig кажется по-настоящему простым в использовании.

// imports ommitted for brevity
pub fn main() !void {
    // Run the CLI
    try cli.run();
}

Простота структуры файла main.zig является свидетельством качественного модульного проектирования. Каждый компонент выполняет свои функции четко определенным образом, при этом они взаимодействуют друг с другом через четко определенные интерфейсы. Такой подход облегчает понимание, тестирование и обслуживание кода.

Хотя файл main.zig отвечает за организацию работы приложения во время его выполнения, настоящими «героями» нашего проекта являются файлы build.zig и build.zig.zon. Именно эти файлы определяют, как наш код превращается в исполняемый файл. Эти файлы отражают подход языка Zig к управлению процессом сборки и зависимостями между компонентами программы. Их стоит понимать так же тщательно, как и сам код, который они компилируют.

Начнем с файла build.zig – этот файл указывает языку Zig, как собирать нашу программу.

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe_mod = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    const exe = b.addExecutable(.{
        .name = "fg",
        .root_module = exe_mod,
    });

    exe.linkLibC();
    exe.root_module.addImport("args", b.dependency("args", .{
        .target = target,
        .optimize = optimize,
    }).module("args"));

    b.installArtifact(exe);
    // Additional build steps for testing and running...
}

Посмотрите, что делает наш файл конфигурации:

• Определяет целевую платформу для сборки программы из параметров компиляции.
• Определяет уровни оптимизации из параметров компиляции.
• Создает модуль на основе нашего исходного кода.
• Определяет исполняемый файл, в котором наш модуль является корневым элементом.
• Добавляет связь с библиотекой libc (для реализации алгоритма сопоставления шаблонов fnmatch)
• Добавляется в зависимости внешнюю библиотеку для парсинга аргументов.
• Инсталлирует полученный результат.

Несмотря на все это, он по-прежнему более удобочитаем, чем обычный файл package.json, который каким-то образом накопил 8742 зависимостей ещё до обеда.

Теперь давайте посмотрим на файл build.zig.zon – это файл, который отвечает за управление нашими внешними зависимостями.

{
    .name = .zig_file_guard,
    .version = "0.0.1",
    .fingerprint = 0x3112a747329a3960, // Changing this has security and trust implications.
    .minimum_zig_version = "0.14.0",
    .dependencies = .{
        .args = .{
            .url = "git+https://github.com/ikskuh/zig-args?ref=master#9425b94c103a031777fdd272c555ce93a7dea581",
            .hash = "args-0.0.0-CiLiqv_NAAC97fGpk9hS2K681jkiqPsWP6w3ucb_ctGH",
        },
    },
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "README.md",
    },
}

Это формат представления данных Zig Object Notation (ZON) – аналог JSON, но с меньшим количеством кавычек и более логичной структурой данных.

В нашем файле build.zig.zon указано следующее:

• Основные метаданные проекта (название, версия)
• Минимальная версия программы Zig, необходимая для использования.
• Внешние зависимости с точным указанием версий
• Пути к проектам, которые необходимо включить в пакеты для распространения

Система определения зависимостей заслуживает особого внимания. Обратите внимание, мы не просто просим предоставить «самую последнюю версию zig-args» или «любую версию, которая хотя бы отчасти совместима с другими компонентами». Вместо этого мы указываем конкретный хэш коммита. Это и есть подход Zig к обеспечению стабильности приложений: если что-то сработало один раз, то должно сработать и в будущем, без странных ситуаций вроде «вчера всё работало нормально, а сегодня — нет», что часто приводит разработчиков в тупик.

Хэш-значение гарантирует, что загруженный код полностью соответствует тому, что мы ожидаем. Это похоже на ситуацию, когда у двери стоит охранник, проверяющий удостоверения личности. Только у этого «охранника» идеальная память: он способен распознать поддельные документы даже на расстоянии, даже с завязанными глазами.

В отличие от некоторых языков, где система сборки рассматривается как нечто второстепенное (имею в виду языки, которые используют сторонние инструменты для управления пакетами), система сборки в Zig является неотъемлемой частью самого языка. Это ещё один пример того, что те же принципы ясности и понятности, которые делают код на Zig качественным, также способствуют надежности процесса сборки.

Так что в следующий раз, когда кто-то покажет вам свой файл webpack.config.js объемом 500 строк или свой скрипт Gradle, для понимания которого необходимо знание дифференциальных уравнений, вы сможете с самодовольной улыбкой показать им свой простой и понятный в использовании файл build.zig. Только постарайтесь не вести себя слишком надменно.

Теперь, когда наш код готов, мы можем собрать FileGuard с использованием встроенной системы сборки Zig.

zig build

Эта команда собирает весь наш код в один исполняемый файл, который затем можно запустить.

./zig-out/bin/fileguard </path/to/monitor>

Чтобы включить непрерывный мониторинг с использованием пользовательских настроек:

./zig-out/bin/fileguard --continuous --interval=5 --include-patterns="*.zig,*.md" </path/to/monitor>

Для наших друзей, страдающих СДВГ, не обязательно запоминать всё. Вместо этого можно воспользоваться командой «Помощь».

./zig-out/bin/fileguard --help

Процессы сборки и выполнения проходят без каких-либо проблем благодаря файлу build.zig. Этот файл определяет, как все компоненты программы должны взаимодействовать между собой, а также какие внешние зависимости необходимы для корректной работы программы (например, библиотека zig-args).

Хотя нынешняя реализация функциональна, существует несколько способов ее улучшения для использования в более профессиональных целях:

• Бэкенд базы данных: Метаданные файлов и информация об изменениях хранятся в базе данных для дальнейшего анализа.
• Веб-интерфейс: Можно добавить веб-панель управления для визуализации и анализа изменений в файлах.
• Система плагинов: Позволит пользователям создавать собственные плагины для специализированной обработки обнаруженных изменений.
• Распределенный мониторинг: Предусмотреть возможность мониторинга файлов на нескольких устройствах с последующей централизованной обработкой полученной информации.
• Улучшения в области безопасности: Можно вводить проверки на наличие подозрительных изменений, которые могут свидетельствовать о нарушениях безопасности.

Эти дополнения превратят FileGuard из инструмента, предназначенного лишь для целей обучения, в по-настоящему полезный инструмент для системных администраторов, разработчиков и специалистов по вопросам безопасности.

Теперь, когда вы уже создали FileGuard, вам, наверное, интересно, какие ещё практические проекты можно реализовать на языке Zig. Вместо того чтобы советовать вам создавать следующую операционную систему или симулятор для квантовых вычислений (ведь у вас же есть настоящая работа, которую нужно выполнить между периодами перегрузки), предлагаем несколько более практичных идей для проектов, которые действительно помогут вам в повседневной работе разработчика:

• Инструмент поиска в командной строке: Можно создать более быстрый и удобный в использовании вариант утилит grep (например: https://github.com/ktarasov/zigrep) или find, который не требовал бы постоянного обращения к руководствам по использованию. Следует сосредоточиться на наиболее часто используемых шаблонах поиска и сделать их максимально простыми в использовании.
• Log Parser/Analyzer: Можно создать инструмент, который будет обрабатывать эти 10 ГБ лог-файлов, которые обычно игнорируются всеми до момента возникновения проблем в работе системы. Инструмент должен уметь обрабатывать лог-файлы в различных форматах (Nginx, Apache, логи пользовательских приложений) и извлекать из них полезную информацию.
• Сервер для отслеживания изменений в исходных файлах: Создайте сервер, который автоматически перекомпилирует или перезапускает ваше приложение при изменении исходных файлов. При этом сервер не должен занимать все процессорные ядра, как это происходит при добыче криптовалют в фоновом режиме.
• Средство для проверки конфигурации: Создайте инструмент, который будет анализировать и проверять ваши конфигурационные файлы в форматах JSON, YAML и TOML. Это поможет избежать ситуаций, когда неисправная конфигурация приводит к сбоям в работе системы в 2 часа ночи по субботам.
• Инструмент синхронизации каталогов: Можно создать программу, которая автоматически синхронизирует каталоги, избегая сложностей, связанных с использованием 500 опций командной строки утилиты rsync, которые почти никто не может полностью понять. Идеально подходит для поддержания синхронизации сред разработки.
• Преобразователь Markdown в HTML: Создайте максимально быстрый преобразователь формата Markdown в HTML, который не требует скачивания огромного количества файлов из репозитория npm. Отлично подходит для создания документации или наполнения статических веб-сайтов контентом.
• Обработчик данных в формате JSON/XML: Создайте инструмент для командной строки, позволяющий выполнять запросы к данным в формате JSON или XML, а также их преобразование. Это избавит пользователя от необходимости запоминать сложную синтаксис языка jq или писать временные скрипты на языке Python.
• Инструментарий для обработки текста: Создайте универсальный инструмент, который будет полезен при выполнении различных операций с текстом в повседневной практике – подсчет слов, замена определенных фрагментов текста, извлечение информации из таблиц, нормализация формата пробелов и т. д.
• Простой HTTP-клиент: Создайте удобный HTTP-клиент, предназначенный для работы с теми API, с которыми вы часто имеете дело. Клиент должен обеспечивать встроенную обработку данных и выполнение распространенных операций. Таким образом вам не придется постоянно вводить одни и те же команды в формате curl.
• Создайте инструмент для очистки временных файлов, связанных с процессом разработки: Можно разработать программу, которая будет эффективно освобождать ценное пространство на диске путем удаления старых временных файлов, каталогов типа node_modules, пакетов формата nix и прочих элементов, связанных с процессом разработки. Все эти элементы могут занимать целых 200 ГБ дискового пространства.

Эти проекты идеально подходят для реализации средствами Zig. Они реализуют преимущества высокой скорости работы (более быстрые инструменты означают меньше времени ожидания), минимальной зависимостью от внешних библиотек (избегается возникновения непредвиденных ситуаций), а также эффективной системой обработки ошибок (инструменты должны сообщать о причинах возникновения ошибок, а не просто переставать работать без каких-либо пояснений).

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

В отличие от учебных материалов по созданию собственных движков баз данных, в результате использования которых у вас остается код, который вы больше никогда не будете использовать, эти проекты создают инструменты, которые действительно пригодятся в процессе разработки. К тому же, когда бинарный файл, созданный с помощью инструмента Go вашего коллеги, все еще запускается, а инструмент Zig уже выполнил свою работу, вы почувствуете удовлетворение от того, что для выполнения задачи требуется вдвое меньше памяти и в четыре раза меньше времени.

Разработка реальных проектов неизбежно сопряжена с появлением вопросов, сложностей и моментов, когда кажется, что нужно разбираться с какой-то ошибкой, написанной на древнешумерском языке. Именно здесь сообщество Zig оказывается незаменимым.

Сообщество пользователей Zig, хотя и меньше по размеру по сравнению с сообществами более известных языков программирования, тем не менее очень гостеприимно и полно знаний. Вот некоторые полезные ресурсы, которые пригодятся вам, если вам понадобится помощь или если вы захотите узнать больше:

• Zig Showtime: Серия видео, созданная Лорисом Кро, вице-президентом по вопросам взаимодействия с сообществом в фонде Zig Software Foundation, а также другими участниками. В сериале показываются проекты и особенности Zig.
• Сервер Zig на платформе Discord: самый активный центр общения для пользователей сообщества Zig. На этом сервере есть каналы, предназначенные для начинающих, а также каналы для обсуждений вопросов, связанных с проектированием языков программирования, и для презентации различных проектов.
• Форум Ziggit: специализированный форум для обсуждений, связанных с проектом Zig. Идеально подходит для обсуждения более сложных вопросов и ведения дискуссий.
• Zig на Codeberg: Основной репозиторий, в котором происходит разработка Zig. В нем также имеется множество обсуждений по поводу возникающих проблем, а также подробная документация.
• r/Zig: Сабреддит Zig – место, где пользователи делятся своими проектами, статьями и вопросами.
• zig-lang.ru: русскоязычный сайт Zig с учебником языка и блогом. На нем есть информация о языке, документация, примеры кода и многое другое.
• Канал Zig-lang.ru в мессенджере MAX: Русское сообщество пользователей Zig на платформе MAX.
• Канал Zig-lang.ru в Telegram: Русское сообщество пользователей Zig на платформе Telegram.
• Сообщество в VK: Русское сообщество пользователей Zig на платформе VK.com.

Эти ресурсы помогут вам преодолеть трудности, связанные с реализацией проектов на языке Zig, а также позволят связаться с другими разработчиками, которые разделяют ваш интерес к этому языку.

После того, как вы разработаете собственные проекты, вас, возможно, заинтересует возможность внести свой вклад в саму платформу Zig или в экосистему библиотек и инструментов, связанных с ней. Это отличный способ углубить свои знания языка и внести положительный вклад в развитие сообщества.

Возможности для внесения вклада включают:

• Разработка языка программирования: работа над компилятором Zig, стандартной библиотекой и другими функциями языка.
• Улучшения в документации: Повышение качества документации к продукту Zig, чтобы сделать её более понятной для новых пользователей.
• Разработка пакетов: Создание и сопровождение библиотек, расширяющих возможности языка Zig.
• Разработка инструментов: Создание инструментов, которые способствуют улучшению процесса разработки приложений на языке Zig.
• Образование и пропаганда: Написание статей, создание учебных материалов, выступления с лекциями о продукте Zig с целью помощи другим людям в изучении языка и его популяризации в сообществе разработчиков ПО.

Даже небольшой вклад может иметь значение, особенно в таком быстро развивающемся языке, как Zig. Кроме того, упоминание вкладов в проекты с открытым исходным кодом положительно сказывается на резюме: это свидетельствует как о технических навыках, так и о способности к сотрудничеству в рамках дистрибутированных команд.

Язык Zig по-прежнему находится в стадии развития, планируются значимые улучшения в будущих версиях языка. Понимание этого плана развития поможет вам согласовать свои усилия по изучению языка и созданию проектов с направлением его развития.

Основные направления текущей деятельности по развитию включают:

• Автономный компилятор: Переход от текущего компилятора на основе C++ и LLVM к компилятору, полностью написанному на Zig.
• Менеджер пакетов: Разработка надежного решения для управления зависимостями между компонентами программы.
• Улучшенное управление памятью: Расширенный набор возможностей для управления памятью в различных условиях ее использования.
• Повышенная совместимость: Дальнейшее упрощение интеграции с кодом, написанным на других языках программирования.
• Оптимизация производительности: Продолжается совершенствование компилятора с целью ускорения процессов компиляции и выполнения программ.
• Асинхронность: Новая реализация механизма асинхронного ввода-вывода.
• Развитие LSP сервера, предназначенный для помощи разработчикам в процессе разработки приложений на языке Zig.

Эти улучшения сделают Zig ещё более мощным и удобным в использовании. Благодаря этому число проектов, для которых Zig является оптимальным решением, будет увеличиваться.

Несмотря на свой молодой возраст, Zig уже добился значительных успехов в различных областях – от встраиваемых систем до веб-сервисов. Изучение примеров таких успехов может стать источником вдохновения и подтверждением целесообразности реализации собственных проектов с использованием технологий Zig.

Примечательные примеры использования технологии Zig в реальных условиях включают:

• Bun: Среда выполнения кода на языке JavaScript и набор инструментов (на смену node.js), созданные с использованием фреймворка Zig. Основное внимание уделяется производительности и удобству использования для разработчиков.
• MachEngine: Игровой движок, созданный с использованием языка Zig. Он полностью использует преимущества этого языка с точки зрения производительности и удобства использования.
• TigerBeetle: Распределенная база данных для финансового учета, написанная на языке программирования Zig. Предназначена для обеспечения высокой производительности и надежности в работе.
• Zig во встраиваемых системах: Различные проекты, в которых Zig используется для разработки встраиваемых систем, благодаря небольшому времени выполнения и точному управлению (например, Microzig).
• Zig в WebAssembly: Проекты, написанные на языке Zig и компилируемые в WebAssembly для высокопроизводительных веб-приложений.

Эти примеры демонстрируют универсальность Zig и его потенциал преуспевать в областях, где важны производительность, контроль и надежность.

Создание этой программы - только первый шаг в вашем путешествии с Zig. Вы видели, как структурировать реальное приложение, управлять памятью явно, взаимодействовать с файловой системой и создавать дружественный CLI интерфейс пользователя. Эти навыки составят основу для более амбициозных проектов.

Ваше путешествие по мире Zig только начинается. Удачи на этом пути!