docs: add server-client communication guide for HTTP/HTTPS/gRPC

[Copilot]

Added documentation for bidirectional server/client communication through the firewall—running servers inside containers accessible from the host, and connecting to host services from inside containers.

Documentation

Created: docs-site/src/content/docs/guides/server-client-communication.md (733 lines)

Server Inside Firewall → Client on Host

• Container accessible at fixed IP 172.30.0.20
• HTTP/HTTPS/gRPC server examples (Node.js, Python)
• TLS certificate generation for HTTPS
• Bind requirement: 0.0.0.0, not localhost

// server.js - accessible from host at http://172.30.0.20:8080
const server = http.createServer((req, res) => { /* ... */ });
server.listen(8080, '0.0.0.0');  // Critical: bind to all interfaces

sudo awf --allow-domains registry.npmjs.org --keep-containers -- node server.js
curl http://172.30.0.20:8080  # From host

Server on Host → Client Inside Firewall

• Host accessible via Docker bridge gateway at 172.30.0.1
• Database/API server integration patterns
• IP-based connections bypass domain filtering (expected)

# Host: python3 -m http.server 9000 --bind 0.0.0.0
sudo awf --allow-domains example.com -- curl http://172.30.0.1:9000

Protocol Behavior

• Ports 80/443: Proxied through Squid, domain filtering applied
• Custom ports: Direct connection, no domain filtering
• gRPC: HTTP/2 over 443 filtered, custom ports bypass
• WebSockets: ws:// (80) and wss:// (443) filtered

Troubleshooting

21 common issues documented:

• Server binding (0.0.0.0 vs localhost)
• Container/host reachability
• Certificate verification
• gRPC connection failures

Examples

Added executable scripts:

• examples/server-inside-firewall.sh - HTTP server demo
• examples/client-inside-firewall.sh - Host connection demo

Both demonstrate the network topology and binding requirements concretely.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /usr/local/bin/node node /home/REDACTED/work/gh-aw-firewall/gh-aw-firewall/docs-site/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Describe in docs how to run server inside the awf and client connects to it, and vice versa. It should cover both http grpc and https servers

Custom agent used: technical-doc-writer
AI technical documentation writer for awf library using Astro Starlight

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

Ready?

[github-actions]

Test Coverage Report

Metric	Coverage	Covered/Total
Lines	81.02%	1230/1518
Statements	80.98%	1261/1557
Functions	78.16%	136/174
Branches	72.56%	410/565

Coverage Thresholds

The project has the following coverage thresholds configured:

• Lines: 38%
• Statements: 38%
• Functions: 35%
• Branches: 30%

---

Coverage report generated by `npm run test:coverage`