From e0ee94f60ef3dc5a73417465ddf89a3ba35d6a70 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Wed, 10 Sep 2025 03:30:23 +0000 Subject: [PATCH] chore: add basic context about Firezone for AI agents (#10284) When using an AI-enabled editor (like Zed), it is useful to have a "rules" file to give it basic context about the project so we don't have to re-explain it every time. We can also extend this file with a list of code review instructions / coding guidelines for Copilot. See https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#asking-copilot-coding-agent-to-generate-a-githubcopilot-instructionsmd-file. I expect this file to grow as we learn which info the agents need about the product to be helpful. In order to use it, people are encouraged to create locally-ignored symlinks to the `docs/AGENT.md` file. --------- Signed-off-by: Thomas Eizinger Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 1 + docs/AGENT.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 120000 .github/copilot-instructions.md create mode 100644 docs/AGENT.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 120000 index 000000000..8378fd7d8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +docs/AGENT.md \ No newline at end of file diff --git a/docs/AGENT.md b/docs/AGENT.md new file mode 100644 index 000000000..ce6faa758 --- /dev/null +++ b/docs/AGENT.md @@ -0,0 +1,33 @@ +# AI agent rules for Firezone + +## Summary + +Firezone is a zero-trust access platform built on top of WireGuard. +The data plane components are built in Rust and reside in `rust/`. +The control plane components are built in Elixir and reside in `elixir/`. + +## Data plane architecture + +At the core of the data plane resides a shared library called [`connlib`](../rust/connlib). +It combines ICE (using the `str0m` library) and WireGuard (using the `boringtun` library) to establish on-the-fly tunnels between Clients and Gateways. +The entry-point for the data plane is [`Tunnel`](../rust/connlib/tunnel) which acts as a big event-loop combining three components: + +- A platform-specific TUN device +- A sans-IO state component representing either the Client or the Gateway +- A platform-specific UDP socket + +Packets from IO sources (TUN device and UDP socket) are passed to the state component, resulting in a UDP or IP packet. +The state component also manages ICE through the [`snownet`](../rust/connlib/snownet) library, so some UDP traffic is handled internally and does not yield an IP packet. + +These three components are split into multiple threads and connected via bounded channels: + +- 1 thread for reading from the TUN device +- 1 thread for writing to the TUN device +- 1 thread for handling IPv4 UDP traffic with 1 task each for sending / receiving +- 1 thread for handling IPv6 UDP traffic with 1 task each for sending / receiving +- 1 task on the "main" thread that holds the state and reads / writes from and to the channels connecting to the IO threads + +## Code review guidelines + +- Assume that code compiles and is syntactically correct. +- Focus on consistency and correctness.