guard/docs/README.md
loki5512344 918e561a61
feat(xdp): IPv6 UDP rate limit, working loader; English JavaDoc comments
XDP behaviour:
- udp_rate_limit6 (LRU, 128-bit source key) + throttle_hit6, so
  udp_policy = "rate-limit" now applies to native IPv6 as well.
- scripts/xdp_ipv6_smoke.sh: phase 4 patches .rodata before load and
  verifies policy=2 on a real kernel (3 pass / 3 rate-limited).

XDP loader (was completely broken, never reached the verifier):
- .rodata is now one struct rampart_config with frozen offsets enforced by
  _Static_assert; XdpGlobals is #[repr(C)] and the image is built with
  offset_of!. Previously a 96-byte image was written into a 76-byte map at
  offsets clang had reordered, so load() failed with EINVAL.
- patch_rodata fails loudly when the map size and the image size diverge.
- build.rs tracks xdp/core and xdp/hooks, not just universal_filter.c.
- build_ringbuf looked for "events_map"; the map is "events_ringbuf".
- tests/xdp_object_maps.rs: verifies map names and .rodata size without root;
  the real binary was confirmed to attach in a netns.

Docs and style:
- Code comments are English, JavaDoc/Rustdoc style, without emoji or
  decorative banners (new project rule, TODO §0.8).
- README rewritten bilingual: Russian first, English below, TOC and
  copy-paste quick start.
- docs/README.md: documentation index and maintenance rules;
  configuration.md documents the whole [xdp] section and IPv4/IPv6 coverage;
  testing.md describes the real-kernel smoke; stale research links removed.
2026-11-15 23:44:07 +01:00

66 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Документация Rampart
> Индекс всей документации проекта и правила её ведения.
> Точка входа — [README.md](../README.md); текущий статус и планы — [TODO.md](../TODO.md).
---
## 1. С чего начать
| Документ | Когда читать |
|----------|--------------|
| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
| [configuration.md](configuration.md) | Настройка `config.toml`, секция `[xdp]`, переменные manager'а |
| [runbook.md](runbook.md) | Ежедневная эксплуатация и типовые операции |
## 2. Эксплуатация (how-to)
| Документ | О чём |
|----------|-------|
| [runbook.md](runbook.md) | Метрики, рестарты, снятие банов, аварийные процедуры |
| [troubleshooting.md](troubleshooting.md) | Диагностика типовых проблем |
| [disaster_recovery.md](disaster_recovery.md) | Восстановление после отказа Redis/ноды |
| [testing.md](testing.md) | Гейты, тесты, XDP-smoke на реальном ядре |
## 3. Справочник (reference)
| Документ | О чём |
|----------|-------|
| [configuration.md](configuration.md) | Все поля конфига и значения по умолчанию |
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты |
| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
## 4. Протоколы
| Документ | О чём |
|----------|-------|
| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
## 5. Теория и исследования
| Раздел | О чём |
|--------|-------|
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на вопрос
«какое решение выбрать и почему». Статус проекта не живёт ни там, ни там — только в
[TODO.md](../TODO.md).
---
## 6. Как вести документацию
1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский (TODO §0.8).
2. **Один документ = одна задача.** How-to начинается с цели («что получится в конце»),
содержит копируемые команды и заканчивается проверкой результата.
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг CLI
или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение = баг.
4. **Новый документ** кладётся в подходящую категорию (2–4) и сразу добавляется в эту
таблицу; если он является точкой входа — ссылка добавляется и в корневой README.
5. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна только
для серии документов (`kb/`, `research/`).
6. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри документа.
7. **Никаких битых ссылок.** Перед коммитом: `grep -o '](\.\?[^)]*)' docs/*.md` и проверь,
что цели существуют.