Contributing

Contributing

Contributions are welcome. This page covers everything you need to submit changes.

Before You Start

1. Read the Development Guide to set up your environment
2. Read the Developer Guide to understand the codebase structure
3. Read the Code of Conduct
4. Check existing issues to avoid duplicate work

Quick Checklist

Before submitting a pull request:

• make lint passes (ruff, no warnings)
• make test passes (all 220 pytest tests)
• No existing tests broken
• No existing functionality removed or degraded
• New CLI flags added to parser, builder, help, README, USAGE_GUIDE, CHANGELOG, and tests
• Function documentation headers present (Description, Parameters, Returns)
• Inline comments explain non-obvious logic
• CHANGELOG.md updated under [Unreleased]
• Interactive menu updated if adding new modes or flags

Workflow

1. Fork and Branch

git clone https://github.com/<your-fork>/Socat-Network-Operations-Manager.git
cd Socat-Network-Operations-Manager
git checkout -b feature/your-feature-name

2. Make Changes

Follow the coding standards in the Developer Guide.

3. Test

make test    # Must pass -- the full suite (759 tests)

4. Commit

Use conventional commit format:

Add: --rate-limit flag for listen and forward modes

Implements per-port connection rate limiting using socat's
max-children option. Updates help text and adds 4 pytest tests.

Closes #42

Prefixes: Add:, Fix:, Change:, Remove:, Docs:, Test:, Refactor:

5. Push and Open PR

git push origin feature/your-feature-name

Open a PR on GitHub. The PR template will pre-populate a checklist.

Branch Naming

Prefix	Use
feature/	New functionality
fix/	Bug fixes
docs/	Documentation updates
test/	Test improvements
refactor/	Code reorganization

Coding Standards

Input Validation

All user-supplied inputs must pass through validate_* functions before use. Never interpolate raw input into command strings or file paths.

Error Handling

• ((count++)) || true -- required under set -e
• Never use $() for functions that launch background processes
• Use return, not exit, inside library functions

CLI Flag Checklist

When adding a flag that applies to multiple modes:

Flag: --my-flag
  [ ] listen parser    [ ] listen builder    [ ] listen help
  [ ] batch parser     [ ] batch builder     [ ] batch help
  [ ] forward parser   [ ] forward builder   [ ] forward help
  [ ] tunnel parser    [ ] tunnel builder    [ ] tunnel help
  [ ] redirect parser  [ ] redirect builder  [ ] redirect help
  [ ] Main help
  [ ] README tables
  [ ] USAGE_GUIDE
  [ ] Wiki pages
  [ ] CHANGELOG
  [ ] Tests (at least one per mode)

Reporting Bugs

Use the Bug Report template. Include version, OS, Python 3.12+ version, steps to reproduce, and log output.

Security Vulnerabilities

Do not open a public issue. See Security Policy for private reporting.

Python-Specific Requirements

• All function signatures must have complete type hints
• Google-style docstrings on all public functions (Args, Returns, Raises sections)
• No eval(), exec(), compile(), or shell=True under any circumstances
• All user input through whitelist validators before reaching subprocess
• frozen=True, slots=True on all dataclasses
• File permissions explicitly set (0o600/0o700)

---

Socat Network Operations Manager · MIT License