tasq/node_modules/agentic-flow/docs/plans/QUIC/QUIC-README.md

# QUIC Transport for Agentic Flow

High-performance QUIC/HTTP3 transport layer for faster and more reliable agent communication.

## Features

- 🚀 **2-3x Faster Connections** - 0-RTT and 1-RTT handshakes vs TCP's 2-RTT
- 🔄 **Stream Multiplexing** - True independence without head-of-line blocking
- 📦 **Connection Pooling** - Efficient connection reuse
- 🔌 **Auto Fallback** - Graceful HTTP/2 fallback when needed
- 🏥 **Health Monitoring** - Built-in health checks and metrics
- 🔐 **TLS 1.3 Built-in** - Encryption integrated into protocol

## Quick Start

```bash
# Enable QUIC transport
export AGENTIC_FLOW_ENABLE_QUIC=true

# Generate certificates (development)
mkdir -p certs
openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout certs/key.pem \
  -out certs/cert.pem \
  -days 365 \
  -subj "/CN=localhost"

# Start proxy with QUIC
npm run proxy:quic
```

## Configuration

### Environment Variables

```bash
export AGENTIC_FLOW_ENABLE_QUIC=true
export QUIC_PORT=4433
export QUIC_HOST=0.0.0.0
export QUIC_CERT_PATH=./certs/cert.pem
export QUIC_KEY_PATH=./certs/key.pem
export QUIC_MAX_CONNECTIONS=100
export QUIC_MAX_STREAMS=100
```

### Programmatic

```typescript
import { createQuicProxy } from 'agentic-flow/proxy/quic-proxy';

const proxy = createQuicProxy({
  openrouterApiKey: process.env.OPENROUTER_API_KEY,
  transport: 'auto', // 'quic' | 'http2' | 'auto'
  enableQuic: true,
  quic: {
    port: 4433,
    maxConnections: 100,
    maxConcurrentStreams: 100
  },
  fallbackToHttp2: true
});

proxy.start(3000);
```

## Usage Examples

### Client

```typescript
import { QuicClient } from 'agentic-flow/transport/quic';

const client = new QuicClient({
  serverHost: 'api.example.com',
  serverPort: 4433
});

await client.initialize();

const connection = await client.connect();
const stream = await client.createStream(connection.id);

await stream.send(new TextEncoder().encode('Hello'));
const response = await stream.receive();

await stream.close();
await client.shutdown();
```

### Server

```typescript
import { QuicServer } from 'agentic-flow/transport/quic';

const server = new QuicServer({
  host: '0.0.0.0',
  port: 4433,
  certPath: './certs/cert.pem',
  keyPath: './certs/key.pem'
});

await server.initialize();
await server.listen();
```

### Connection Pool

```typescript
import { QuicClient, QuicConnectionPool } from 'agentic-flow/transport/quic';

const client = new QuicClient();
await client.initialize();

const pool = new QuicConnectionPool(client, 20);
const conn = await pool.getConnection('api.example.com', 4433);

// Automatically reuses existing connections
const conn2 = await pool.getConnection('api.example.com', 4433);
console.log(conn.id === conn2.id); // true
```

## Health Checks

```bash
# Check overall health (includes QUIC)
curl http://localhost:8080/health

# QUIC-specific health
curl http://localhost:8080/health/quic
```

## Performance

| Metric | HTTP/2 | QUIC | Improvement |
|--------|--------|------|-------------|
| Connection Time | 50-100ms | 0-30ms | 2-3x |
| First Byte | 100-200ms | 50-100ms | 2x |
| Latency | 200-400ms | 100-250ms | 1.5-2x |

## Testing

```bash
# Run QUIC integration tests
npm run test:quic

# Test with development proxy
npm run proxy:quic:dev
```

## Troubleshooting

### QUIC Not Available

Check availability:
```typescript
import { checkQuicAvailability } from 'agentic-flow/config/quic';

const status = await checkQuicAvailability();
console.log(status);
```

### Connection Timeouts

1. Verify UDP port 4433 is open:
   ```bash
   sudo netstat -tulpn | grep 4433
   ```

2. Check firewall:
   ```bash
   sudo ufw allow 4433/udp
   ```

### Certificate Issues

For development:
```bash
export QUIC_VERIFY_PEER=false
```

For production, use proper certificates from Let's Encrypt.

## Documentation

- [Full Integration Guide](./QUIC-INTEGRATION.md)
- [API Reference](./API.md)
- [Configuration Schema](./CONFIG.md)

## Architecture

```
┌─────────────────┐
│  QUIC Client    │
│  - Connection   │
│    Pool         │
│  - Stream Mux   │
└────────┬────────┘
         │
         │ UDP/QUIC
         │
┌────────▼────────┐
│  QUIC Server    │
│  - TLS 1.3      │
│  - HTTP/3       │
└─────────────────┘
```

## Requirements

- Node.js >= 18.0.0
- UDP port 4433 accessible
- TLS 1.3 certificates

## Roadmap

- [ ] WASM module integration
- [ ] HTTP/3 QPACK compression
- [ ] 0-RTT resumption
- [ ] Connection migration
- [ ] BBR congestion control

## References

- [QUIC RFC 9000](https://www.rfc-editor.org/rfc/rfc9000.html)
- [HTTP/3 RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html)
- [TLS 1.3 RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)