gkweb/.desc.md

GKWeb - Rust веб-сервер

Обзор проекта

GKWeb — это современный веб-сервер, написанный на языке программирования Rust с использованием фреймворка Axum. Проект представляет собой простой, но функциональный веб-сервер, способный обслуживать статические файлы и HTML-страницы с поддержкой автоматической маршрутизации.

Архитектура и особенности

Основные компоненты

1. Главный модуль (src/main.rs)

   • Точка входа в приложение
   • Создание и запуск сервера на порту 3000
   • Инициализация маршрутизации

2. Система маршрутизации (src/routing.rs)

   • Автоматическая маршрутизация с помощью Axum
   • Поддержка статических файлов и HTML страниц
   • Обработка 404 ошибок
   • Поддержка переменной BASE_URL для настройки базового пути

3. Управление ресурсами (src/assets.rs)

   • Встраивание статических файлов в исполняемый файл с помощью rust-embed
   • Компиляция всех файлов из директории assets/ в бинарник
   • Поддержка любых типов файлов

4. Система логирования (src/logger.rs)

   • Цветной терминальный логгер с временными метками
   • 4 уровня логирования: INFO, WARN, ERROR, DEBUG
   • Адаптивный вывод с учетом ширины терминала

5. Отладочные функции (src/debug/)

   • Вывод списка всех встроенных ресурсов
   • Помощь в разработке и отладке

6. Система сборки (src/builder.rs)

   • Модуль для будущих функций сборки шаблонов (пока не реализован)

Технологический стек

• Язык: Rust (edition 2024)
• Веб-фреймворк: Axum 0.8.7
• Асинхронность: Tokio (полная поддержка)
• HTTP: http 1.3.1
• Типы файлов: mime_guess для определения MIME-типов
• Ресурсы: rust-embed для встраивания файлов
• Время: chrono для временных меток
• Терминал: term_size для определения размеров окна

Функциональность

Маршрутизация

• / — главная страница (index.html)
• /{path} — общий маршрут для статических файлов и HTML страниц
• Автоматический поиск файлов с добавлением .html для путей
• Поддержка статических файлов (CSS, JS, изображения, медиа)

Особенности HTML страниц

• Автоматическая замена плейсхолдера {{BASE_URL}} на значение из переменной окружения
• Поддержка базового href для корректной работы ссылок
• Fallback на 404 для несуществующих страниц

Логирование

log(0, "Server started successfully on port 3000", true); // INFO уровень, жирный шрифт
log(3, "Debug information", false); // DEBUG уровень, обычный шрифт

Структура проекта

├── src/
│   ├── main.rs              # Главный файл
│   ├── routing.rs           # Система маршрутизации
│   ├── assets.rs           # Управление ресурсами
│   ├── builder.rs          # Сборщик (заготовка)
│   ├── logger.rs           # Система логирования
│   └── debug/
│       ├── mod.rs
│       └── static_content.rs # Отладочные функции
├── assets/                  # Статические ресурсы
│   ├── pages/
│   │   ├── index.html      # Главная страница
│   │   ├── about.html      # Страница "О нас"
│   │   └── test.hbs        # Handlebars шаблон (не используется)
│   ├── template.html       # Шаблон страницы
│   ├── styles/
│   │   └── main.css        # Основные стили
│   ├── scripts/
│   │   └── hello.js        # JavaScript файлы
│   ├── media/
│   │   └── uzi.gif         # Медиа файлы
│   └── content/
│       └── about.md        # Markdown контент
├── Cargo.toml              # Конфигурация проекта
├── TECHDOC.md             # Техническая документация
└── .desc.md               # Данное описание проекта

Использование

Запуск сервера

cargo run

Переменные окружения

• BASE_URL — базовый URL для замены в HTML страницах (по умолчанию "/")

Пример работы

1. Сервер запускается на http://0.0.0.0:3000
2. При старте выводится список всех встроенных ресурсов
3. Главная страница доступна по адресу /
4. Статические файлы обслуживаются напрямую
5. HTML страницы обрабатываются с заменой BASE_URL

Преимущества

1. Производительность: Rust обеспечивает высокую скорость и низкое потребление памяти
2. Безопасность: Встроенная безопасность памяти Rust
3. Простота развертывания: Все ресурсы встроены в один исполняемый файл
4. Гибкость: Поддержка переменных окружения для конфигурации
5. Отладка: Встроенные инструменты логирования и отладки
6. Современность: Использует последние версии Rust и фреймворков

Возможности для развития

1. Поддержка шаблонов: Завершение реализации системы сборки шаблонов
2. Динамические страницы: Добавление обработки шаблонов Handlebars
3. API эндпоинты: Расширение функциональности для REST API
4. Конфигурация: Поддержка файлов конфигурации
5. Мониторинг: Добавление метрик и мониторинга
6. Кэширование: Реализация системы кэширования
7. HTTPS: Поддержка SSL/TLS соединений

Заключение

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

---

Проект разработан с использованием Rust 2024 edition и Axum framework