From 2bf4d0be00b40261f83ed731f85fa2f42502d8e3 Mon Sep 17 00:00:00 2001
From: ginuerzh <ginuerzh@gmail.com>
Date: Sat, 5 Sep 2026 20:59:43 +0800
Subject: [PATCH] add .gitignore, document p2p plugin

- .gitignore excludes .codegraph/.claude/.remember and test artifacts
- CLAUDE.md: service catalog now 13 types; p2p row plus its deliberate
  deviations (opaque peer/endpoint, no example/, gRPC-only)
- README.md: p2p row and usage section with p2ps: config snippet
---
 .gitignore | 10 ++++++++++
 CLAUDE.md  |  5 +++--
 README.md  | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 48 insertions(+), 2 deletions(-)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f593922
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,10 @@
+# Index / IDE / agent state
+.codegraph/
+.claude/
+.remember/
+
+# Build & test artifacts
+*.test
+coverage.out
+coverage*.out
+coverage*.tmp
diff --git a/CLAUDE.md b/CLAUDE.md
index 9372128..3b43105 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ Generated code was produced with `protoc-gen-go v1.28.1`, `protoc-gen-go-grpc v1
 
 This module defines the **gRPC plugin protocol** for [GOST](https://github.com/go-gost/gost). External plugin processes implement these gRPC services to extend GOST's behavior (authentication, rate limiting, DNS resolution, etc.). The core GOST binary communicates with plugins either via **gRPC** or **HTTP/JSON** — examples for both transports are provided.
 
-### Service catalog (12 plugin types)
+### Service catalog (13 plugin types)
 
 Each subdirectory follows the same structure: `proto/<name>.proto` + generated `.pb.go`/`_grpc.pb.go`, and `example/` with reference implementations (gRPC and optionally HTTP).
 
@@ -34,12 +34,13 @@ Each subdirectory follows the same structure: `proto/<name>.proto` + generated `
 | `ingress/` | `Ingress` | `GetRule(req) → (endpoint)`, `SetRule(req) → (ok)` | `type: ingress` |
 | `limiter/traffic/` | `Limiter` | `Limit(req) → (in, out)` | `type: limiter` |
 | `observer/` | `Observer` | `Observe(events[]) → (ok)` | `type: observer` |
+| `p2p/` | `P2P` | `OpenTunnel(req) → (ok, id, endpoint)`, `CloseTunnel(id) → (ok)`, `Status` | top-level `p2ps:` section (`plugin.type: grpc`) |
 | `recorder/` | `Recorder` | `Record(data, metadata) → (ok)` | `type: recorder` |
 | `resolver/` | `Resolver` | `Resolve(req) → (ips[], ok)` | `type: resolver` |
 | `router/` | `Router` | `GetRoute(req) → (dst, gateway)` | `type: router` |
 | `sd/` | `SD` | `Register`, `Deregister`, `Renew`, `Get` | `type: sd` |
 
-All RPCs are **unary** (no streaming). Every request carries proxy context fields (`network`, `addr`, `host`, `client`, `service`) relevant to the intercepted connection.
+All RPCs are **unary** (no streaming). Every request carries proxy context fields (`network`, `addr`, `host`, `client`, `service`) relevant to the intercepted connection. The p2p service deviates deliberately: `peer` and `endpoint` are opaque strings (the plugin defines their semantics), there is no `example/` in this module (the standalone `p2p/` host repo is the reference implementation), and only the gRPC transport exists.
 
 ### Dual transport: gRPC + HTTP
 
diff --git a/README.md b/README.md
index f65484b..ec9b977 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ gRPC-based plugin protocol definitions for [GOST](https://github.com/go-gost/gos
 | [ingress](ingress/) | `Ingress` | Ingress rule management |
 | [limiter/traffic](limiter/traffic/) | `Limiter` | Per-connection bandwidth limits |
 | [observer](observer/) | `Observer` | Receive connection and traffic events |
+| [p2p](p2p/) | `P2P` | Establish tunnels to peers for P2P connectivity |
 | [recorder](recorder/) | `Recorder` | Record proxied traffic |
 | [resolver](resolver/) | `Resolver` | Custom DNS resolution |
 | [router](router/) | `Router` | Custom route selection |
@@ -112,6 +113,40 @@ services:
       addr: 127.0.0.1:8000
 ```
 
+### P2P plugin
+
+The `P2P` service lets GOST establish the network path to a chain node through
+a tunnel opened by an external plugin (NAT traversal, relay, hole punching —
+the strategy is entirely up to the plugin). The client sends an opaque `peer`
+identifier; the plugin replies with an opaque `endpoint` handle (v1: a locally
+dialable TCP `host:port`). P2P plugins are declared in a top-level `p2ps:`
+section and referenced by chain node metadata:
+
+```yaml
+p2ps:
+  - name: p2p-1
+    plugin:
+      type: grpc
+      addr: 127.0.0.1:8003
+
+chains:
+  - name: chain-0
+    hops:
+      - name: hop-0
+        nodes:
+          - name: node-0
+            addr: 192.168.1.10:8080
+            connector:
+              type: http
+            dialer:
+              type: tcp
+            metadata:
+              p2p: p2p-1
+```
+
+A reference implementation of the plugin host (stub: local TCP bridge) lives in
+the standalone [p2p](https://github.com/go-gost/p2p) repo.
+
 ## Code generation
 
 Generated protobuf code was produced with `protoc-gen-go v1.28.1` and `protoc-gen-go-grpc v1.2.0`. To regenerate: