145 lines
6.0 KiB
Markdown
145 lines
6.0 KiB
Markdown
---
|
|
phase: 01-data-pipeline
|
|
plan: 01
|
|
subsystem: infra
|
|
tags: [rust, aya, ebpf, workspace, repr-c, ringbuf]
|
|
|
|
# Dependency graph
|
|
requires: []
|
|
provides:
|
|
- Aya eBPF workspace with three crates (tcptop, tcptop-common, tcptop-ebpf)
|
|
- Shared types (TcptopEvent, DataEvent, StateEvent) with repr(C) union layout
|
|
- NetworkCollector platform abstraction trait with mpsc channel pattern
|
|
- Privilege check (root or CAP_BPF+CAP_PERFMON, exit code 77)
|
|
- ConnectionRecord and ConnectionKey model types
|
|
- eBPF build pipeline via aya-build in build.rs
|
|
affects: [01-02, 01-03, 02-tui, 04-macos]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: [aya, aya-build, aya-ebpf, tokio, clap, anyhow, thiserror, nix, async-trait, signal-hook]
|
|
patterns: [aya-build in build.rs (not xtask), platform-conditional deps, repr(C) union for kernel-userspace shared types]
|
|
|
|
key-files:
|
|
created:
|
|
- Cargo.toml
|
|
- rust-toolchain.toml
|
|
- .cargo/config.toml
|
|
- tcptop/Cargo.toml
|
|
- tcptop/build.rs
|
|
- tcptop/src/main.rs
|
|
- tcptop/src/privilege.rs
|
|
- tcptop/src/collector/mod.rs
|
|
- tcptop/src/collector/linux.rs
|
|
- tcptop/src/model.rs
|
|
- tcptop-common/Cargo.toml
|
|
- tcptop-common/src/lib.rs
|
|
- tcptop-ebpf/Cargo.toml
|
|
- tcptop-ebpf/src/main.rs
|
|
modified: []
|
|
|
|
key-decisions:
|
|
- "aya-build API takes Package structs and Toolchain enum, not string slices -- adapted build.rs accordingly"
|
|
- "procfs, aya, aya-log are Linux-only target deps to allow macOS development"
|
|
- "build.rs ignores eBPF compilation failure (let _ =) to allow development without bpf-linker"
|
|
|
|
patterns-established:
|
|
- "Platform-conditional dependencies: cfg(target_os = linux) for kernel-specific crates"
|
|
- "Shared types use #[repr(C)] with only primitive fields, union for tagged event data"
|
|
- "NetworkCollector trait uses async-trait + mpsc::Sender<CollectorEvent> pattern"
|
|
|
|
requirements-completed: [PLAT-01, PLAT-03, OPS-01, OPS-02]
|
|
|
|
# Metrics
|
|
duration: 3min
|
|
completed: 2026-03-21
|
|
---
|
|
|
|
# Phase 01 Plan 01: Workspace Scaffold Summary
|
|
|
|
**Aya eBPF three-crate workspace with repr(C) union shared types, privilege check (exit 77), and NetworkCollector platform trait**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 3 min
|
|
- **Started:** 2026-03-21T23:08:54Z
|
|
- **Completed:** 2026-03-21T23:12:13Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 14
|
|
|
|
## Accomplishments
|
|
- Three-crate Aya workspace compiles (userspace + common crates verified, eBPF crate skeleton ready)
|
|
- All shared types defined with #[repr(C)] union layout and IPv6-ready [u8; 16] address fields
|
|
- Privilege check exits with code 77 and exact error message per D-09/D-10/D-11
|
|
- NetworkCollector trait defined with async start/stop and mpsc channel pattern per PLAT-03
|
|
- ConnectionRecord model has all required fields for DATA-01 through DATA-07
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Create Aya workspace with shared types and eBPF build pipeline** - `554aadb` (feat)
|
|
2. **Task 2: Implement privilege check and platform abstraction trait** - `006abca` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `Cargo.toml` - Workspace root with three members and shared dependencies
|
|
- `rust-toolchain.toml` - Pinned nightly-2026-01-15 with bpfel-unknown-none target
|
|
- `.cargo/config.toml` - Minimal build config (aya-build handles eBPF target)
|
|
- `tcptop/Cargo.toml` - Userspace crate with platform-conditional Linux deps
|
|
- `tcptop/build.rs` - aya-build integration for eBPF compilation
|
|
- `tcptop/src/main.rs` - Entry point with privilege check
|
|
- `tcptop/src/privilege.rs` - Root/CAP_BPF+CAP_PERFMON check, exit code 77
|
|
- `tcptop/src/collector/mod.rs` - NetworkCollector trait and CollectorEvent enum
|
|
- `tcptop/src/collector/linux.rs` - Placeholder for Linux eBPF collector (Plan 02)
|
|
- `tcptop/src/model.rs` - ConnectionRecord, ConnectionKey, Protocol, TcpState types
|
|
- `tcptop-common/Cargo.toml` - no_std compatible shared types crate
|
|
- `tcptop-common/src/lib.rs` - TcptopEvent, DataEvent, StateEvent, TcptopEventData union
|
|
- `tcptop-ebpf/Cargo.toml` - eBPF kernel program crate
|
|
- `tcptop-ebpf/src/main.rs` - eBPF skeleton with RingBuf map declaration
|
|
|
|
## Decisions Made
|
|
- aya-build 0.1.3 API takes `Package` structs and `Toolchain` enum, not string slices as the plan assumed -- adapted build.rs to match actual API
|
|
- Made `procfs`, `aya`, and `aya-log` Linux-only target dependencies (`cfg(target_os = "linux")`) since procfs fails to compile on macOS
|
|
- build.rs uses `let _ =` to ignore eBPF build failures, allowing development without bpf-linker installed
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 3 - Blocking] Fixed aya-build API mismatch**
|
|
- **Found during:** Task 1 (workspace creation)
|
|
- **Issue:** Plan specified `aya_build::build_ebpf(&["tcptop-ebpf"])` but actual API requires `Package` structs and a `Toolchain` argument
|
|
- **Fix:** Updated build.rs to use `Package { name, root_dir, ..Default::default() }` and `Toolchain::default()`
|
|
- **Files modified:** tcptop/build.rs
|
|
- **Verification:** `cargo check -p tcptop` succeeds
|
|
- **Committed in:** 554aadb (Task 1 commit)
|
|
|
|
**2. [Rule 3 - Blocking] Made procfs/aya Linux-only dependencies**
|
|
- **Found during:** Task 1 (workspace creation)
|
|
- **Issue:** procfs crate fails to compile on macOS with "unsupported platform" build script error
|
|
- **Fix:** Moved procfs, aya, and aya-log to `[target.'cfg(target_os = "linux")'.dependencies]`
|
|
- **Files modified:** tcptop/Cargo.toml
|
|
- **Verification:** `cargo check -p tcptop` succeeds on macOS
|
|
- **Committed in:** 554aadb (Task 1 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 2 auto-fixed (2 blocking issues)
|
|
**Impact on plan:** Both fixes necessary for compilation. No scope creep.
|
|
|
|
## Issues Encountered
|
|
None beyond the auto-fixed deviations above.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Workspace structure ready for Plan 02 (Linux eBPF collector implementation)
|
|
- NetworkCollector trait defined and ready for implementation
|
|
- Shared types locked and ready for use in eBPF kprobe programs
|
|
- bpf-linker will be needed on Linux for eBPF crate compilation in Plan 02
|
|
|
|
---
|
|
*Phase: 01-data-pipeline*
|
|
*Completed: 2026-03-21*
|