mirror of https://github.com/ospab/ostp.git
docs: add CONTRIBUTING guide in English and Russian, link in README
This commit is contained in:
ospab
parent
0ef43bb823
commit
8cfb7e9c17
|
|
@ -0,0 +1,115 @@
|
|||
# Contributing to OSTP
|
||||
|
||||
Thank you for your interest in contributing to **OSTP (Ospab Stealth Transport Protocol)**! We welcome contributions from developers, security researchers, testers, and documentation writers of all skill levels.
|
||||
|
||||
By contributing to this project, you agree to abide by our code of conduct and license terms.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Development Setup](#development-setup)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Development Workflow](#development-workflow)
|
||||
4. [Coding Guidelines](#coding-guidelines)
|
||||
5. [Submitting Pull Requests](#submitting-pull-requests)
|
||||
6. [Security Vulnerabilities](#security-vulnerabilities)
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
To build and test OSTP locally, you will need:
|
||||
|
||||
* **Rust Toolchain (1.75+)**: Install via [rustup](https://rustup.rs/).
|
||||
* **Node.js (18+) & npm**: Required to build the frontend control panel (`ostp-control`) and compile Tauri GUI resources.
|
||||
* **Git**: For version control.
|
||||
|
||||
### Building the Project
|
||||
|
||||
1. **Clone the repository**:
|
||||
```bash
|
||||
git clone https://github.com/ospab/ostp.git
|
||||
cd ostp
|
||||
```
|
||||
|
||||
2. **Build the control panel frontend**:
|
||||
```bash
|
||||
cd ostp-control
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
```
|
||||
|
||||
3. **Build the entire Cargo workspace**:
|
||||
```bash
|
||||
cargo build
|
||||
```
|
||||
|
||||
4. **Run tests**:
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
The repository is organized as a Cargo workspace containing the following crates:
|
||||
|
||||
* [`ostp-core/`](file:///d:/ospab-projects/ostp/ostp-core): Core protocol logic, including packet formatting, serialization, selective ACK/NACK (ARQ) state machine, and the Noise protocol (`Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s`) handshake.
|
||||
* [`ostp-client/`](file:///d:/ospab-projects/ostp/ostp-client): Client implementations, including SOCKS5/HTTP local proxies, `tun2socks` integration, native TUN interface routing, and split-tunneling bypass mechanisms.
|
||||
* [`ostp-server/`](file:///d:/ospab-projects/ostp/ostp-server): Server logic, session dispatcher, anti-probing fallback server proxying, access key database, and the REST API for control panel communication.
|
||||
* [`ostp-control/`](file:///d:/ospab-projects/ostp/ostp-control): A modern web dashboard for server administration (user management, real-time metrics, bandwidth limits).
|
||||
* [`ostp-gui/`](file:///d:/ospab-projects/ostp/ostp-gui): Tauri-based desktop GUI application for Windows and Linux.
|
||||
* [`ostp-flutter/`](file:///d:/ospab-projects/ostp/ostp-flutter): Mobile client code for Android platforms.
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Check for existing issues** or open a new one to discuss proposed changes before starting work.
|
||||
2. **Fork the repository** and create a new branch from `master`:
|
||||
```bash
|
||||
git checkout -b feat/your-feature-name
|
||||
```
|
||||
3. **Implement your changes**, ensuring you write appropriate unit or integration tests.
|
||||
4. **Format your code**:
|
||||
```bash
|
||||
cargo fmt --all
|
||||
```
|
||||
5. **Run linter checks**:
|
||||
```bash
|
||||
cargo clippy --workspace --all-targets -- -D warnings
|
||||
```
|
||||
6. **Ensure all tests pass**:
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Coding Guidelines
|
||||
|
||||
* **Safety**: Avoid using `unsafe` blocks unless absolutely necessary for low-level system bindings (e.g., FFI configurations like `setsockopt`). When using `unsafe`, add safety doc comments explaining why it is safe.
|
||||
* **Documentation**: Document public modules, structs, and functions. Maintain comment integrity across codebase changes.
|
||||
* **Logging**: Use the `tracing` framework for structured logging. Avoid `println!` for production logs.
|
||||
* **Aesthetics**: When editing GUI or Web components, adhere to premium, modern web design aesthetics (vibrant color palettes, glassmorphism, responsive grids).
|
||||
|
||||
---
|
||||
|
||||
## Submitting Pull Requests
|
||||
|
||||
1. Push your branch to your GitHub fork:
|
||||
```bash
|
||||
git push origin feat/your-feature-name
|
||||
```
|
||||
2. Open a Pull Request (PR) targeting the `master` branch.
|
||||
3. In your PR description, explain the rationale behind your changes, what was fixed/added, and how it was tested.
|
||||
4. Verify that GitHub Actions CI runs successfully on your PR.
|
||||
|
||||
---
|
||||
|
||||
## Security Vulnerabilities
|
||||
|
||||
If you discover a security-related vulnerability, please do **not** open a public issue. Instead, report it privately by emailing the core maintainers at [gvoprgrg@gmail.com](mailto:gvoprgrg@gmail.com). We will coordinate a swift disclosure and fix.
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
# Участие в разработке OSTP
|
||||
|
||||
Спасибо за интерес к участию в разработке **OSTP (Ospab Stealth Transport Protocol)**! Мы рады любой помощи: от написания кода и тестирования до работы над документацией и проведения аудита безопасности.
|
||||
|
||||
Присылая изменения в проект, вы соглашаетесь соблюдать правила нашего сообщества и условия лицензии.
|
||||
|
||||
---
|
||||
|
||||
## Содержание
|
||||
|
||||
1. [Подготовка окружения](#подготовка-окружения)
|
||||
2. [Структура проекта](#структура-проекта)
|
||||
3. [Процесс разработки](#процесс-разработки)
|
||||
4. [Правила оформления кода](#правила-оформления-кода)
|
||||
5. [Создание Pull Request](#создание-pull-request)
|
||||
6. [Уязвимости безопасности](#уязвимости-безопасности)
|
||||
|
||||
---
|
||||
|
||||
## Подготовка окружения
|
||||
|
||||
Для локальной сборки и тестирования OSTP вам понадобятся:
|
||||
|
||||
* **Rust Toolchain (1.75+)**: Рекомендуется установить через [rustup](https://rustup.rs/).
|
||||
* **Node.js (18+) и npm**: Необходимы для сборки веб-панели управления (`ostp-control`) и сборки интерфейса Tauri.
|
||||
* **Git**: Для контроля версий.
|
||||
|
||||
### Сборка проекта
|
||||
|
||||
1. **Клонируйте репозиторий**:
|
||||
```bash
|
||||
git clone https://github.com/ospab/ostp.git
|
||||
cd ostp
|
||||
```
|
||||
|
||||
2. **Соберите веб-интерфейс панели управления**:
|
||||
```bash
|
||||
cd ostp-control
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
```
|
||||
|
||||
3. **Соберите весь Cargo-workspace**:
|
||||
```bash
|
||||
cargo build
|
||||
```
|
||||
|
||||
4. **Запустите тесты**:
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Структура проекта
|
||||
|
||||
Репозиторий представляет собой единый Cargo-workspace со следующими компонентами:
|
||||
|
||||
* [`ostp-core/`](file:///d:/ospab-projects/ostp/ostp-core): Базовая логика протокола: форматирование пакетов, сериализация, конечный автомат выборочного подтверждения (ARQ/ACK/NACK) и рукопожатие Noise (`Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s`).
|
||||
* [`ostp-client/`](file:///d:/ospab-projects/ostp/ostp-client): Клиентская часть: локальные SOCKS5/HTTP прокси-серверы, интеграция с драйвером `wintun` / `tun2socks` и реализация раздельного туннелирования для прямого обхода трафика.
|
||||
* [`ostp-server/`](file:///d:/ospab-projects/ostp/ostp-server): Серверная часть: диспетчеризация сессий, маскировка под классические веб-серверы при активном сканировании, база данных ключей доступа и REST API панели управления.
|
||||
* [`ostp-control/`](file:///d:/ospab-projects/ostp/ostp-control): Панель администратора (пользователи, статистика трафика в реальном времени, лимиты скорости и объема данных).
|
||||
* [`ostp-gui/`](file:///d:/ospab-projects/ostp/ostp-gui): Настольное приложение-клиент для Windows и Linux на платформе Tauri.
|
||||
* [`ostp-flutter/`](file:///d:/ospab-projects/ostp/ostp-flutter): Мобильный клиент для платформы Android.
|
||||
|
||||
---
|
||||
|
||||
## Процесс разработки
|
||||
|
||||
1. **Проверьте существующие задачи** или откройте новую тему (Issue) для обсуждения предлагаемых изменений.
|
||||
2. **Сделайте fork репозитория** и создайте новую ветку от `master`:
|
||||
```bash
|
||||
git checkout -b feat/имя-вашей-фичи
|
||||
```
|
||||
3. **Внесите необходимые изменения** и добавьте соответствующие модульные или интеграционные тесты.
|
||||
4. **Выровняйте форматирование кода**:
|
||||
```bash
|
||||
cargo fmt --all
|
||||
```
|
||||
5. **Запустите статический анализатор**:
|
||||
```bash
|
||||
cargo clippy --workspace --all-targets -- -D warnings
|
||||
```
|
||||
6. **Убедитесь, что все тесты проходят**:
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Правила оформления кода
|
||||
|
||||
* **Безопасность (Safety)**: Избегайте использования блоков `unsafe` везде, где это возможно. Допускается их использование только для низкоуровневых системных вызовов (например, FFI-настройки сокетов `setsockopt`). Любой блок `unsafe` должен сопровождаться комментарием `// SAFETY: ...`.
|
||||
* **Документация**: Пишите документацию для публичных модулей, структур и методов. Сохраняйте целостность комментариев при рефакторинге.
|
||||
* **Логирование**: Используйте фреймворк `tracing` для структурированного логирования. Не используйте `println!` в рабочем коде.
|
||||
* **Дизайн**: При изменении веб-интерфейсов или GUI следуйте современным визуальным трендам (плавные анимации, сбалансированная цветовая гамма, адаптивная верстка).
|
||||
|
||||
---
|
||||
|
||||
## Создание Pull Request
|
||||
|
||||
1. Отправьте ветку в ваш fork-репозиторий:
|
||||
```bash
|
||||
git push origin feat/имя-вашей-фичи
|
||||
```
|
||||
2. Создайте Pull Request (PR) в ветку `master` основного репозитория.
|
||||
3. Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка.
|
||||
4. Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно.
|
||||
|
||||
---
|
||||
|
||||
## Уязвимости безопасности
|
||||
|
||||
Если вы обнаружили уязвимость, пожалуйста, **не** публикуйте её в открытых Issue. Вместо этого отправьте отчёт разработчикам на почту [gvoprgrg@gmail.com](mailto:gvoprgrg@gmail.com) для координации закрытого исправления.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# OSTP — Ospab Stealth Transport Protocol
|
||||
|
||||
[Русский язык](README.ru.md) · [Wiki](https://github.com/ospab/ostp/wiki) · [Releases](https://github.com/ospab/ostp/releases)
|
||||
[Русский язык](README.ru.md) · [Wiki](https://github.com/ospab/ostp/wiki) · [Contributing](CONTRIBUTING.md) · [Releases](https://github.com/ospab/ostp/releases)
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# OSTP — Ospab Stealth Transport Protocol
|
||||
|
||||
[English](README.md)
|
||||
[English](README.md) · [Contributing](CONTRIBUTING.ru.md)
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2632,7 +2632,7 @@ dependencies = [
|
|||
|
||||
[[package]]
|
||||
name = "ostp-client"
|
||||
version = "0.2.66"
|
||||
version = "0.2.67"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"base64 0.22.1",
|
||||
|
|
@ -2662,7 +2662,7 @@ dependencies = [
|
|||
|
||||
[[package]]
|
||||
name = "ostp-core"
|
||||
version = "0.2.66"
|
||||
version = "0.2.67"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"bytes",
|
||||
|
|
|
|||
Loading…
Reference in New Issue