Skip to content

Commit 241351f

Browse files
justin-layervjustin-layerv
authored
docs: add CONTRIBUTING.md and expand code architecture docs (#1347)
- Create CONTRIBUTING.md with development setup, workflow, and guidelines - Expand docs/code.md from stub to comprehensive architecture overview - Document project structure, modules, and build commands Fixes missing CONTRIBUTING.md referenced in README.md
1 parent 634e3d8 commit 241351f

File tree

2 files changed

+300
-1
lines changed

2 files changed

+300
-1
lines changed

‎CONTRIBUTING.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Contributing to OpenNHP
2+
3+
Thank you for your interest in contributing to OpenNHP! This document provides guidelines and information for contributors.
4+
5+
## Code of Conduct
6+
7+
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to maintain a welcoming and inclusive community.
8+
9+
## Getting Started
10+
11+
### Prerequisites
12+
13+
- **Go 1.24+** - Required for building the project
14+
- **Make** - Build automation
15+
- **Git** - Version control
16+
- **golangci-lint** (optional) - For code linting
17+
18+
### Clone and Build
19+
20+
```bash
21+
# Clone the repository
22+
git clone https://github.com/OpenNHP/opennhp.git
23+
cd opennhp
24+
25+
# Initialize dependencies
26+
make init
27+
28+
# Build all binaries
29+
make
30+
```
31+
32+
### Project Structure
33+
34+
```
35+
opennhp/
36+
├── nhp/ # Core NHP protocol library
37+
│ ├── core/ # Protocol implementation
38+
│ ├── common/ # Shared types and utilities
39+
│ ├── utils/ # Helper functions
40+
│ ├── plugins/ # Plugin system
41+
│ └── test/ # Unit tests
42+
├── endpoints/ # Network daemon implementations
43+
│ ├── agent/ # NHP Agent (client)
44+
│ ├── server/ # NHP Server
45+
│ ├── ac/ # Access Controller
46+
│ ├── db/ # Database component
47+
│ └── kgc/ # Key Generation Center
48+
├── examples/ # Example implementations
49+
│ ├── server_plugin/ # Example server plugin
50+
│ └── client_sdk/ # SDK usage examples
51+
├── docs/ # Documentation
52+
├── docker/ # Docker configurations
53+
└── release/ # Build outputs
54+
```
55+
56+
### Running Tests
57+
58+
```bash
59+
# Run all tests
60+
make test
61+
62+
# Run tests with race detection
63+
make test-race
64+
65+
# Run tests with coverage
66+
make coverage
67+
```
68+
69+
### Code Style
70+
71+
- Use `gofmt` for code formatting: `make fmt`
72+
- Follow [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
73+
- Write clear, descriptive commit messages
74+
- Add tests for new functionality
75+
- Document exported functions and types
76+
77+
## Development Workflow
78+
79+
### Making Changes
80+
81+
1. **Fork** the repository on GitHub
82+
2. **Clone** your fork locally
83+
3. **Create a branch** for your changes:
84+
```bash
85+
git checkout -b feature/your-feature-name
86+
```
87+
4. **Make your changes** and commit them
88+
5. **Test** your changes:
89+
```bash
90+
make test
91+
make fmt
92+
```
93+
6. **Push** to your fork:
94+
```bash
95+
git push origin feature/your-feature-name
96+
```
97+
7. **Open a Pull Request** on GitHub
98+
99+
### Commit Messages
100+
101+
Write clear, concise commit messages that explain the "why" behind your changes:
102+
103+
```
104+
feat(server): add health check endpoint
105+
106+
Add /health and /ready endpoints for Kubernetes liveness
107+
and readiness probes.
108+
```
109+
110+
Use conventional commit prefixes:
111+
- `feat:` - New features
112+
- `fix:` - Bug fixes
113+
- `docs:` - Documentation changes
114+
- `test:` - Test additions or modifications
115+
- `refactor:` - Code refactoring
116+
- `ci:` - CI/CD changes
117+
- `build:` - Build system changes
118+
119+
### Pull Request Guidelines
120+
121+
- Keep PRs focused on a single change
122+
- Update documentation if needed
123+
- Add tests for new functionality
124+
- Ensure all tests pass
125+
- Request review from maintainers
126+
127+
## Reporting Issues
128+
129+
### Bug Reports
130+
131+
When reporting bugs, please include:
132+
133+
- Go version (`go version`)
134+
- Operating system and version
135+
- Steps to reproduce the issue
136+
- Expected vs actual behavior
137+
- Relevant logs or error messages
138+
139+
### Feature Requests
140+
141+
For feature requests, please:
142+
143+
- Check existing issues to avoid duplicates
144+
- Clearly describe the use case
145+
- Explain the proposed solution
146+
147+
## Security Issues
148+
149+
For security vulnerabilities, please see our [Security Policy](SECURITY.md) and report issues privately.
150+
151+
## Getting Help
152+
153+
- **GitHub Issues** - For bugs and feature requests
154+
- **Discussions** - For questions and community support
155+
- **Documentation** - See the [docs/](docs/) directory
156+
157+
## License
158+
159+
By contributing to OpenNHP, you agree that your contributions will be licensed under the [Apache 2.0 License](LICENSE).

‎docs/code.md‎

Lines changed: 141 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,149 @@ permalink: /code/
88
# Understand the Source Code
99
{: .fs-9 }
1010

11-
This article explains how to read the source code of OpenNHP.
11+
This article explains the architecture and structure of the OpenNHP codebase.
1212
{: .fs-6 .fw-300 }
1313

1414
[中文版](/zh-cn/code/){: .label .fs-4 }
1515

1616
---
17+
18+
## Repository Structure
19+
20+
OpenNHP uses a multi-module Go architecture:
21+
22+
```
23+
opennhp/
24+
├── nhp/ # Core protocol library (github.com/OpenNHP/opennhp/nhp)
25+
├── endpoints/ # Network daemons (github.com/OpenNHP/opennhp/endpoints)
26+
├── examples/ # Example implementations
27+
├── docs/ # Documentation (Jekyll)
28+
├── docker/ # Container configurations
29+
└── release/ # Build outputs
30+
```
31+
32+
## Core Library (`nhp/`)
33+
34+
The `nhp` module contains the core NHP protocol implementation:
35+
36+
| Directory | Purpose |
37+
|-----------|---------|
38+
| `core/` | Protocol implementation: packets, encryption, device management |
39+
| `common/` | Shared types, message structures, error definitions |
40+
| `utils/` | Helper functions: IP utilities, iptables, crypto helpers |
41+
| `plugins/` | Server plugin system interfaces |
42+
| `log/` | Async logging framework |
43+
| `etcd/` | etcd integration for distributed configuration |
44+
| `ebpf/` | eBPF programs for XDP and traffic control |
45+
| `test/` | Unit tests |
46+
47+
### Key Files in `core/`
48+
49+
- `device.go` - NHP device lifecycle and connection management
50+
- `packet.go` - Packet structure and header definitions
51+
- `crypto.go` - Cryptographic primitives (ECDH, AEAD)
52+
- `initiator.go` - Client-side message encryption
53+
- `responder.go` - Server-side message decryption
54+
55+
## Network Daemons (`endpoints/`)
56+
57+
The `endpoints` module contains executable daemons:
58+
59+
| Component | Binary | Purpose |
60+
|-----------|--------|---------|
61+
| `agent/` | `nhp-agent` | Client that sends knock requests |
62+
| `server/` | `nhp-server` | Central server handling knock validation |
63+
| `ac/` | `nhp-ac` | Access Controller managing firewall rules |
64+
| `db/` | `nhp-db` | Data broker for DHP (Data Hiding Protocol) |
65+
| `kgc/` | `nhp-kgc` | Key Generation Center for IBC keys |
66+
67+
Each daemon follows a similar structure:
68+
69+
```
70+
agent/
71+
├── main/ # Entry point and CLI
72+
│ ├── main.go # CLI commands
73+
│ ├── export.go # C FFI exports for SDK
74+
│ └── etc/ # Configuration files
75+
├── udpagent.go # UDP transport implementation
76+
├── config.go # Configuration handling
77+
└── msghandler.go # Message processing
78+
```
79+
80+
## Cryptographic Schemes
81+
82+
OpenNHP supports two cipher schemes:
83+
84+
| Scheme | Algorithms | Use Case |
85+
|--------|-----------|----------|
86+
| `CIPHER_SCHEME_CURVE` | Curve25519 + ChaCha20-Poly1305 + BLAKE2s | International |
87+
| `CIPHER_SCHEME_GMSM` | SM2 + SM4-GCM + SM3 | Chinese standards |
88+
89+
See [Cryptography](/cryptography/) for detailed protocol documentation.
90+
91+
## Plugin System
92+
93+
Server plugins extend NHP server functionality:
94+
95+
```go
96+
type PluginHandler interface {
97+
Init(helper *NhpServerPluginHelper) error
98+
Close() error
99+
AuthWithNHP(req *AuthRequest) (*AuthResponse, error)
100+
AuthWithHttp(req *HttpAuthRequest) (*HttpAuthResponse, error)
101+
}
102+
```
103+
104+
See [Server Plugin Development](/server_plugin/) for implementation guide.
105+
106+
## SDK Architecture
107+
108+
The agent provides SDKs for multiple platforms:
109+
110+
| Platform | Output | Build Target |
111+
|----------|--------|--------------|
112+
| Linux | `nhp-agent.so` | `make linuxagentsdk` |
113+
| macOS | `nhp-agent.dylib` | `make macosagentsdk` |
114+
| iOS | `nhpagent.xcframework` | `make iosagentsdk` |
115+
| Android | `libnhpagent.so` | `make androidagentsdk` |
116+
117+
See [Agent SDK](/agent_sdk/) for integration documentation.
118+
119+
## Building from Source
120+
121+
```bash
122+
# Initialize dependencies
123+
make init
124+
125+
# Build all binaries
126+
make
127+
128+
# Build specific components
129+
make agentd # nhp-agent
130+
make serverd # nhp-server
131+
make acd # nhp-ac
132+
133+
# Development commands
134+
make test # Run tests
135+
make fmt # Format code
136+
make clean # Clean build artifacts
137+
```
138+
139+
## Testing
140+
141+
Tests are located in `nhp/test/` and `endpoints/test/`:
142+
143+
```bash
144+
# Run all tests
145+
make test
146+
147+
# Run with race detection
148+
make test-race
149+
150+
# Run with coverage
151+
make coverage
152+
```
153+
154+
## Contributing
155+
156+
See [CONTRIBUTING.md](https://github.com/OpenNHP/opennhp/blob/main/CONTRIBUTING.md) for development guidelines.

0 commit comments

Comments
 (0)