stackforge 0.3.0__tar.gz → 0.4.0__tar.gz

stackforge-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,238 @@
+# Contributing to Stackforge
+
+Thank you for your interest in contributing! We welcome bug reports, feature requests, and pull requests.
+
+## Prerequisites
+
+- **Rust:** Stable toolchain — install via [rustup](https://rustup.rs/)
+- **Python:** 3.13 or higher
+- **uv:** Fast Python package manager — install via [astral.sh/uv](https://docs.astral.sh/uv/)
+- **cog:** Conventional commit tool — install via `cargo install cocogitto`
+
+## Setting Up the Environment
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/LaBackDoor/stackforge.git
+cd stackforge
+
+# 2. Sync Python dependencies
+uv sync
+
+# 3. Compile the Rust extension and install in editable mode
+uv run maturin develop
+```
+
+> Re-run `uv run maturin develop` any time you change Rust code.
+
+## Project Structure
+
+```
+stackforge/
+├── crates/
+│   ├── stackforge-core/        # Core Rust library (published to crates.io)
+│   │   └── src/
+│   │       ├── layer/          # Protocol implementations
+│   │       │   ├── mod.rs      # LayerKind enum, Layer trait, LayerEnum dispatch
+│   │       │   ├── bindings.rs # Protocol detection rules (ethertype, port → layer)
+│   │       │   ├── field.rs    # Field abstractions (MacAddress, BytesField, etc.)
+│   │       │   ├── ethernet.rs
+│   │       │   ├── arp.rs
+│   │       │   ├── ipv4/
+│   │       │   ├── ipv6/
+│   │       │   ├── tcp/
+│   │       │   ├── udp/
+│   │       │   ├── icmp/
+│   │       │   ├── icmpv6/
+│   │       │   ├── dns/
+│   │       │   ├── http/
+│   │       │   ├── http2/
+│   │       │   ├── quic/
+│   │       │   ├── l2tp/
+│   │       │   ├── ssh/
+│   │       │   ├── tls/
+│   │       │   ├── dot11/      # 802.11 Wi-Fi
+│   │       │   ├── dot15d4/    # 802.15.4 Zigbee
+│   │       │   └── generic/    # Runtime custom protocols
+│   │       ├── packet.rs
+│   │       └── lib.rs
+│   └── stackforge-automata/    # Async state machine framework (planned)
+├── src/
+│   └── lib.rs                  # PyO3 bindings
+├── python/
+│   └── stackforge/
+│       ├── __init__.py         # Python re-exports
+│       └── custom.py           # CustomLayer + typed fields
+└── tests/
+    ├── integration/            # Rust integration tests
+    ├── python/                 # Python tests (pytest)
+    │   └── scapy_compat/       # Scapy behavioural compatibility tests
+    ├── uts/                    # UTS regression test suites (Scapy-format)
+    └── sample_pcap/            # PCAP fixtures
+```
+
+## Running Tests
+
+### Rust tests
+
+```bash
+# All unit + integration tests
+cargo test
+
+# Single test by name
+cargo test test_name
+
+# Single integration file
+cargo test --test integration dns
+```
+
+### Python tests
+
+```bash
+# All Python tests
+uv run pytest tests/python
+
+# Single file
+uv run pytest tests/python/test_dns.py
+
+# Single test
+uv run pytest tests/python/test_dns.py::test_dns_query_build
+
+# Scapy compatibility tests only
+uv run pytest tests/python/scapy_compat
+
+# Verbose output
+uv run pytest -v tests/python
+```
+
+### UTS regression tests
+
+UTS files in `tests/uts/` are Scapy-format regression suites run via the Python test suite:
+
+```bash
+uv run pytest tests/python/scapy_compat/test_uts_integration.py
+```
+
+## Linting and Formatting
+
+All of the following must pass before submitting a PR:
+
+```bash
+# Rust
+cargo fmt
+cargo clippy
+
+# Python
+uv run ruff check .
+```
+
+## Adding a New Protocol Layer
+
+Follow the existing pattern used by layers like `dns`, `http`, or `quic`.
+
+### 1. Create the layer module
+
+```
+crates/stackforge-core/src/layer/<proto>/
+├── mod.rs        # Layer struct, parse(), fields, Layer trait impl
+└── builder.rs    # (optional) Builder for constructing packets
+```
+
+The layer struct holds `start`/`end` offsets into a shared `Bytes` buffer — it does **not** copy field values on parse. Fields are read on demand:
+
+```rust
+pub struct MyProtoLayer {
+    start: usize,
+    end: usize,
+}
+
+impl MyProtoLayer {
+    pub fn my_field<'a>(&self, buf: &'a [u8]) -> u16 {
+        u16::from_be_bytes(buf[self.start..self.start + 2].try_into().unwrap())
+    }
+}
+```
+
+### 2. Register the `LayerKind` variant
+
+In `crates/stackforge-core/src/layer/mod.rs`, add a variant to the `LayerKind` enum and handle it in `LayerEnum`.
+
+### 3. Add detection rules
+
+In `crates/stackforge-core/src/layer/bindings.rs`, register how the new layer is detected (e.g., from an ethertype, IP protocol number, or TCP/UDP port).
+
+### 4. Expose via PyO3
+
+If the layer needs Python-accessible fields, add them to the `PyO3` bindings in `src/lib.rs`.
+
+### 5. Write tests
+
+- **Rust:** Add `tests/integration/<proto>.rs` with parse and build tests.
+- **Python:** Add `tests/python/test_<proto>.py` covering field access, builders, and edge cases.
+- **UTS (optional):** Add `tests/uts/<proto>.uts` for Scapy-format regression tests.
+
+## Architecture Notes
+
+- **Lazy Zero-Copy View** — `Packet::parse()` only records layer boundaries (offsets). Field values are read directly from the buffer when accessed, with no upfront copying.
+- **Copy-on-Write Mutation** — The underlying `Bytes` buffer is only cloned when a mutation occurs on a shared packet.
+- **`Packet(raw)` is unparsed** — always call `.parse()` before accessing layers or fields.
+- **`Packet::parse()` assumes Ethernet first** — Dot11 and Dot15d4 frames require a dedicated parse entry point.
+
+## Commit Messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by [cocogitto](https://docs.cocogitto.io/) (`cog`). All commits must follow the format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+```
+
+Common types:
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or protocol |
+| `fix` | Bug fix |
+| `chore` | Maintenance, dependency updates, CI |
+| `docs` | Documentation only |
+| `test` | Adding or fixing tests |
+| `refactor` | Code restructuring with no behaviour change |
+| `perf` | Performance improvement |
+
+Use `cog commit` instead of `git commit` to get an interactive prompt that validates the format:
+
+```bash
+cog commit feat "add OSPF layer"
+cog commit fix  "correct DNS name compression offset"
+```
+
+Breaking changes must include a `!` after the type or a `BREAKING CHANGE:` footer:
+
+```bash
+cog commit feat! "redesign Layer trait interface"
+```
+
+## Versioning and Changelog
+
+Versions and the changelog are managed by `cog`. Maintainers cut releases with:
+
+```bash
+# Bump version automatically based on commit history (patch / minor / major)
+cog bump --auto
+
+# Or bump explicitly
+cog bump --patch
+cog bump --minor
+cog bump --major
+```
+
+`cog bump` runs `pre_bump_hooks` (updates `Cargo.toml` version), tags the commit, and regenerates `CHANGELOG.md` from the commit history. Contributors do not need to edit `CHANGELOG.md` manually.
+
+## Pull Request Process
+
+1. Fork the repo and create your branch from `main`.
+2. Add tests for any new behaviour — both Rust and Python.
+3. Ensure all tests pass: `cargo test` and `uv run pytest tests/python`.
+4. Ensure linting passes: `cargo fmt && cargo clippy && uv run ruff check .`
+5. Open a pull request with a clear description of what changed and why.

{stackforge-0.3.0 → stackforge-0.4.0}/Cargo.lock

@@ -67,6 +67,12 @@ version = "1.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
+[[package]]
+name = "bitflags"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -187,6 +193,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
 [[package]]
 name = "crypto-bigint"
 version = "0.5.5"
@@ -245,6 +257,20 @@ dependencies = [
  "syn 2.0.112",
 ]
 
+[[package]]
+name = "dashmap"
+version = "6.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5041cc499144891f3790297212f32a74fb938e5136a14943f338ef9e0ae276cf"
+dependencies = [
+ "cfg-if",
+ "crossbeam-utils",
+ "hashbrown",
+ "lock_api",
+ "once_cell",
+ "parking_lot_core",
+]
+
 [[package]]
 name = "default-net"
 version = "0.22.0"
@@ -422,6 +448,12 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.14.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -480,6 +512,15 @@ version = "0.2.178"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37c93d8daa9d8a012fd8ab92f088405fb202ea0b6ab73ee2482ae66af4f42091"
 
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
 [[package]]
 name = "log"
 version = "0.4.29"
@@ -529,7 +570,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "053998cea5a306971f88580d0829e90f270f940befd7cf928da179d4187a5a66"
 dependencies = [
  "anyhow",
- "bitflags",
+ "bitflags 1.3.2",
  "byteorder",
  "libc",
  "netlink-packet-core",
@@ -589,6 +630,19 @@ dependencies = [
  "sha2",
 ]
 
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
 [[package]]
 name = "paste"
 version = "1.0.15"
@@ -836,6 +890,15 @@ dependencies = [
  "cipher",
 ]
 
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags 2.11.0",
+]
+
 [[package]]
 name = "rfc6979"
 version = "0.4.0"
@@ -861,6 +924,12 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
 [[package]]
 name = "sec1"
 version = "0.7.3"
@@ -961,7 +1030,7 @@ dependencies = [
 
 [[package]]
 name = "stackforge"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "pyo3",
  "stackforge-automata",
@@ -970,7 +1039,7 @@ dependencies = [
 
 [[package]]
 name = "stackforge-automata"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "bytes",
  "stackforge-core",
@@ -978,13 +1047,14 @@ dependencies = [
 
 [[package]]
 name = "stackforge-core"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "aes",
  "aes-gcm",
  "bytes",
  "cbc",
  "chacha20poly1305",
+ "dashmap",
  "default-net",
  "des",
  "digest",
@@ -1037,7 +1107,7 @@ version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba3a3adc5c275d719af8cb4272ea1c4a6d668a777f37e115f6d11ddbc1c8e0e7"
 dependencies = [
- "bitflags",
+ "bitflags 1.3.2",
  "core-foundation",
  "system-configuration-sys",
 ]
@@ -1178,6 +1248,12 @@ dependencies = [
  "windows-targets",
 ]
 
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
 [[package]]
 name = "windows-targets"
 version = "0.48.5"

{stackforge-0.3.0 → stackforge-0.4.0}/Cargo.toml

@@ -21,7 +21,7 @@ shared-version = true
 tag-name = "v{{version}}"
 
 [workspace.package]
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 license = "GPL-3.0-only"
 authors = ["Stackforge Contributors"]
@@ -31,6 +31,7 @@ repository = "https://github.com/LaBackDoor/stackforge"
 bytes = "1.11.0"
 smallvec = "1.15.1"
 thiserror = "2.0.17"
+dashmap = "6.1"
 stackforge-core = { path = "crates/stackforge-core" }
 stackforge-automata = { path = "crates/stackforge-automata" }