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

examples/README.md

@@ -18,6 +18,8 @@ This directory contains example scripts demonstrating common ways to use the Age
 | [using-domains-file.sh](using-domains-file.sh) | Using a file to specify allowed domains |
 | [blocked-domains.sh](blocked-domains.sh) | Blocking specific domains with allowlist/blocklist |
 | [debugging.sh](debugging.sh) | Debug mode with log inspection |
+| [server-inside-firewall.sh](server-inside-firewall.sh) | Run HTTP server inside firewall, connect from host |
+| [client-inside-firewall.sh](client-inside-firewall.sh) | Run server on host, connect from inside firewall |
 | [domains.txt](domains.txt) | Example domain allowlist file |
 
 ## Running Examples

examples/client-inside-firewall.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+set -e
+
+# Example: Run an HTTP server on the host and connect to it
+# from inside the firewall container
+
+echo "====================================="
+echo "Client Inside Firewall Example"
+echo "====================================="
+echo ""
+echo "This example demonstrates connecting to a host server"
+echo "from inside the firewall container."
+echo ""
+
+# Find available port
+PORT=9000
+
+# Create a simple HTTP server on the host
+echo "Starting HTTP server on host at port $PORT..."
+
+# Start Python HTTP server in background
+python3 -m http.server $PORT --bind 0.0.0.0 > /tmp/host-server.log 2>&1 &
+SERVER_PID=$!
+
+# Wait for server to start
+sleep 2
+
+# Check if server started successfully
+if ! kill -0 $SERVER_PID 2>/dev/null; then
+  echo "Error: Failed to start HTTP server"
+  exit 1
+fi
+
+echo "Host server started (PID: $SERVER_PID)"
+echo ""
+
+# Get the Docker network gateway IP
+GATEWAY_IP=$(docker network inspect awf-net --format='{{range .IPAM.Config}}{{.Gateway}}{{end}}' 2>/dev/null || echo "172.30.0.1")
+
+echo "====================================="
+echo "Testing connection from firewall"
+echo "====================================="
+echo ""
+echo "Host gateway IP: $GATEWAY_IP"
+echo "Server URL: http://${GATEWAY_IP}:${PORT}"
+echo ""
+
+# Test connection from inside the firewall
+echo "Running curl inside firewall to connect to host server..."
+echo ""
+
+sudo awf \
+  --allow-domains example.com \
+  -- curl -v "http://${GATEWAY_IP}:${PORT}" 2>&1 | head -20
+
+echo ""
+echo ""
+echo "====================================="
+echo "Connection test completed!"
+echo "====================================="
+echo ""
+echo "Note: Connections to IP addresses bypass domain filtering."
+echo "This is expected behavior for accessing host services."
+echo ""
+
+# Cleanup
+echo "Cleaning up..."
+kill $SERVER_PID 2>/dev/null || true
+rm -f /tmp/host-server.log
+
+echo "Done!"

examples/server-inside-firewall.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+set -e
+
+# Example: Run a Node.js HTTP server inside the firewall
+# and connect to it from the host machine
+
+echo "====================================="
+echo "Server Inside Firewall Example"
+echo "====================================="
+echo ""
+echo "This example demonstrates running an HTTP server"
+echo "inside the firewall and connecting from the host."
+echo ""
+
+# Create a simple HTTP server script
+SERVER_SCRIPT=$(mktemp --suffix=.js)
+cat > "$SERVER_SCRIPT" << 'EOF'
+const http = require('http');
+
+const server = http.createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    message: 'Hello from inside the firewall!',
+    url: req.url,
+    timestamp: new Date().toISOString(),
+    container: 'awf-agent'
+  }));
+});
+
+const PORT = 8080;
+server.listen(PORT, '0.0.0.0', () => {
+  console.log(`Server running at http://0.0.0.0:${PORT}/`);
+  console.log('Press Ctrl+C to stop the server');
+});
+
+// Keep the server running
+process.on('SIGINT', () => {
+  console.log('\nShutting down server...');
+  server.close(() => {
+    console.log('Server stopped');
+    process.exit(0);
+  });
+});
+EOF
+
+echo "Starting HTTP server inside firewall..."
+echo "Server script: $SERVER_SCRIPT"
+echo ""
+
+# Start the server inside the firewall (background process)
+sudo awf \
+  --allow-domains registry.npmjs.org \
+  --keep-containers \
+  -- node "$SERVER_SCRIPT" &
+
+AWF_PID=$!
+
+# Wait for the server to start
+echo "Waiting for server to start..."
+sleep 5
+
+# Get the container IP
+CONTAINER_IP=$(docker inspect awf-agent --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' 2>/dev/null || echo "172.30.0.20")
+
+echo ""
+echo "====================================="
+echo "Server is running!"
+echo "====================================="
+echo ""
+echo "Container IP: $CONTAINER_IP"
+echo "Server URL: http://${CONTAINER_IP}:8080"
+echo ""
+echo "Testing connection from host..."
+echo ""
+
+# Test the connection
+curl -s "http://${CONTAINER_IP}:8080" | jq '.' || curl -s "http://${CONTAINER_IP}:8080"
+
+echo ""
+echo ""
+echo "====================================="
+echo "You can also test manually:"
+echo "  curl http://${CONTAINER_IP}:8080"
+echo "  curl http://${CONTAINER_IP}:8080/api/test"
+echo ""
+echo "Press Ctrl+C to stop the server and clean up"
+echo "====================================="
+
+# Wait for the AWF process
+wait $AWF_PID
+
+# Cleanup
+rm -f "$SERVER_SCRIPT"
+echo "Cleaned up temporary files"