{"_id":"@affectively/dash-webtransport-server","_rev":"2-ef5d60f8c0df552234752b040f64a676","name":"@affectively/dash-webtransport-server","dist-tags":{"latest":"5.0.0"},"versions":{"5.0.0":{"name":"@affectively/dash-webtransport-server","version":"5.0.0","_id":"@affectively/dash-webtransport-server@5.0.0","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"dist":{"shasum":"e6bfd368b9f9db1599c863935823d067a1815481","tarball":"https://registry.npmjs.org/@affectively/dash-webtransport-server/-/dash-webtransport-server-5.0.0.tgz","fileCount":32,"integrity":"sha512-yEurQv5zAiPCL5NoiKbjVvriqvP+dOiJzUcXRgNQ1pM6TFdyDC+FGk0ek2xFRuWyjGQEmqOBe2e750XvtSnf2w==","signatures":[{"sig":"MEUCIEMsq4mchgAuAVN2RUdEqbIE1fq7Pb/fa8tQMN93OuCXAiEA5MZquHekTZJxh0/XyRkj3hUGUbWxVNgxo/5acU0z3pY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":142819},"main":"src/index.ts","type":"module","gitHead":"ae54b0df6ac98ed86b037accafa16cf218dda541","scripts":{"dev":"bunx wrangler dev","tail":"bunx wrangler tail","test":"bun test","build":"bunx wrangler deploy --dry-run","start":"bun run src/index.ts","deploy":"bunx wrangler deploy","tail:dev":"bunx wrangler tail --env development","tail:prod":"bunx wrangler tail --env production","deploy:dev":"bunx wrangler deploy --env development","type-check":"tsc --noEmit","deploy:prod":"bunx wrangler deploy --env production","forge:deploy":"bun ../../apps/aeon-forge/src/cli/cli.tsx deploy . --oneshot","tail:staging":"bunx wrangler tail --env staging","deploy:staging":"bunx wrangler deploy --env staging"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"_npmVersion":"11.8.0","description":"Dash WebTransport Relay Server for real-time P2P-style synchronization","directories":{},"_nodeVersion":"25.5.0","dependencies":{"yjs":"^13.6.20","@affectively/shared-ui":"workspace:*","@affectively/shared-utils":"workspace:*"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.3","@types/node":"^20.14.0","@cloudflare/workers-types":"^4.20241106.0"},"_npmOperationalInternal":{"tmp":"tmp/dash-webtransport-server_5.0.0_1773155903893_0.8973568561314671","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."}},"time":{"created":"2026-03-10T15:18:23.793Z","modified":"2026-03-27T20:03:27.678Z","5.0.0":"2026-03-10T15:18:24.051Z"},"description":"Dash WebTransport Relay Server for real-time P2P-style synchronization","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"readme":"# Dash WebTransport Relay Server (Cloudflare Workers)\n\n> Deprecated for DashRelay room sync/relay traffic. Relay responsibilities moved to `apps/dashrelay-app` (`/relay/sync` and `/relay`).\n\nCentral hub (Star Topology) for Dash clients to connect in \"Rooms\" for real-time P2P-style synchronization using WebTransport (HTTP/3 over QUIC) on Cloudflare Workers.\n\n## Overview\n\nThis Cloudflare Worker implements the Dash WebTransport Relay protocol:\n- **Transport**: WebTransport (HTTP/3 over QUIC) - native Cloudflare support\n- **State Management**: Durable Objects for persistent, low-latency room state\n- **Connection**: One WebTransport session per Client\n- **Multiplexing**: One Bidirectional Stream per \"Document/Room\"\n- **Protocol**: Stream-based Echo Relay\n\n## Architecture\n\n```text\nDash Client A ──┐\n               │\nDash Client B ──┼──> Cloudflare Worker (handles WebTransport streams)\n               │              │\nDash Client C ──┘              │\n                               │ (coordinates via Durable Objects)\n                               ▼\n                        Durable Object (Room state)\n```text\n\n**Note**: Durable Objects are fully implemented for stateful room management. The Worker handles WebTransport stream I/O (streams are tied to Worker execution context), while Durable Objects coordinate room state and membership. See [DURABLE_OBJECTS.md](./DURABLE_OBJECTS.md) for details.\n\n### Handshake Protocol\n\n1. Client creates a BidirectionalStream from WebTransport session\n2. Client writes Room Name to stream (VarString encoded)\n3. Worker reads Room Name and routes to Durable Object for that room\n4. Durable Object adds stream to room and sets up relay\n5. When data received from Client A, Durable Object broadcasts to Clients B, C, ... (not back to A)\n\n## Deployment\n\n### Prerequisites\n\n1. Cloudflare account with Workers enabled\n2. Wrangler CLI installed: `bunx wrangler --version`\n\n### Deploy to Cloudflare\n\n```bash\n# Install dependencies\nbun install\n\n# Login to Cloudflare (if not already)\nbunx wrangler login\n\n# Deploy to development\nbunx wrangler deploy --env development\n\n# Deploy to staging\nbunx wrangler deploy --env staging\n\n# Deploy to production\nbunx wrangler deploy --env production\n```text\n\n### Local Development\n\n```bash\n# Run locally with Wrangler\nbunx wrangler dev\n\n# Or use Bun directly (for testing, but WebTransport won't work locally)\nbun run dev\n```text\n\n**Note**: WebTransport requires HTTP/3/QUIC which is only available in Cloudflare's production environment, not in local development. Use `wrangler dev` for testing the worker logic, but full WebTransport testing requires deployment.\n\n## Configuration\n\n### Environment Variables\n\nSet in `wrangler.toml` or via Cloudflare dashboard:\n\n```toml\n[env.production]\nvars = { \n  ENVIRONMENT = \"production\"\n}\n```text\n\n### Durable Objects\n\nDurable Objects are automatically configured in `wrangler.toml`:\n\n```toml\n[[durable_objects.bindings]]\nname = \"ROOM\"\nclass_name = \"RoomDurableObject\"\nscript_name = \"dash-webtransport-relay\"\n```text\n\n## Usage\n\n### Client Connection\n\n```typescript\n// Connect to WebTransport relay\nconst transport = new WebTransport('https://dash-relay.yourdomain.com/relay');\n\n// Wait for connection\nawait transport.ready;\n\n// Create bidirectional stream\nconst stream = await transport.createBidirectionalStream();\n\n// Write room name (VarString encoded)\nconst roomName = 'user-123';\nconst encoded = encodeVarString(roomName);\nconst writer = stream.writable.getWriter();\nawait writer.write(encoded);\nwriter.releaseLock();\n\n// Now you can read/write CRDT updates\nconst reader = stream.readable.getReader();\n// ... handle incoming updates\n```text\n\n### Room Name in URL (Optional)\n\nYou can also specify the room name in the URL:\n\n```typescript\nconst transport = new WebTransport('https://dash-relay.yourdomain.com/relay/user-123');\n```text\n\nThis is optional - the room name can still be sent in the stream handshake.\n\n## Endpoints\n\n### Health Check\n\n```bash\nGET /health\n```text\n\nReturns:\n```json\n{\n  \"status\": \"ok\",\n  \"service\": \"Dash WebTransport Relay Server\",\n  \"environment\": \"production\",\n  \"timestamp\": \"2024-01-01T12:00:00Z\"\n}\n```text\n\n### WebTransport Relay\n\n```text\nWebTransport /relay\nWebTransport /relay/{roomName}\n```text\n\nAccepts WebTransport connections and routes to appropriate Durable Object room.\n\n## Durable Objects\n\nEach room is managed by a separate Durable Object instance:\n- **Consistent State**: All clients in a room connect to the same Durable Object\n- **Low Latency**: Durable Objects run close to clients (Cloudflare edge)\n- **Automatic Scaling**: Cloudflare handles scaling and distribution\n- **Persistence**: Durable Objects maintain state across requests\n\n### Room Lifecycle\n\n1. **Creation**: First client connects → Durable Object created\n2. **Active**: Clients join/leave → Durable Object manages streams\n3. **Cleanup**: Last client leaves → Durable Object can be garbage collected (after timeout)\n\n## Monitoring\n\n### Cloudflare Dashboard\n\n- View Worker metrics: Requests, errors, CPU time\n- View Durable Object metrics: Active objects, requests, errors\n- Set up alerts for high error rates or latency\n\n### Logs\n\n```bash\n# View real-time logs\nbunx wrangler tail\n\n# View logs for specific environment\nbunx wrangler tail --env production\n```\n\n## Performance\n\n### Advantages of Cloudflare Workers\n\n- **Global Edge Network**: Low latency worldwide\n- **Automatic Scaling**: Handles traffic spikes automatically\n- **Durable Objects**: Stateful connections with low latency\n- **Native WebTransport**: No additional infrastructure needed\n- **Pay-as-you-go**: Only pay for what you use\n\n### Limitations\n\n- **CPU Time**: 50ms CPU time per request (can be increased with paid plans)\n- **Memory**: 128MB per Durable Object\n- **Connections**: WebTransport connections count toward Worker limits\n\n## Cost Estimation\n\n- **Free Tier**: 100,000 requests/day, 10ms CPU time per request\n- **Paid Plans**: $5/month + usage-based pricing\n- **Durable Objects**: $0.15 per million requests + storage costs\n\nFor a typical Dash sync use case:\n- ~1,000 active users\n- ~10 sync operations per user per day\n- ~10,000 requests/day\n- **Estimated cost**: Free tier or < $5/month\n\n## Troubleshooting\n\n### Connection Failures\n\n1. **Check URL**: Ensure WebTransport URL is correct\n2. **Check browser support**: WebTransport requires Chrome 97+, Edge 97+, or Firefox 114+\n3. **Check Cloudflare status**: Verify Worker is deployed and running\n4. **Check logs**: Use `wrangler tail` to see connection errors\n\n### High Latency\n\n1. **Check Durable Object location**: Cloudflare automatically places them close to clients\n2. **Check room size**: Large rooms may have higher broadcast latency\n3. **Check network conditions**: QUIC performs better on stable networks\n\n### Room Isolation Issues\n\n1. **Verify room names**: Ensure room names are unique per user/document\n2. **Check encoding**: Room names must be properly VarString encoded\n3. **Monitor logs**: Check for room name parsing errors\n\n## Security Considerations\n\n1. **Room name validation**: Ensure room names can't be guessed or enumerated\n2. **Rate limiting**: Consider adding rate limiting per client\n3. **Authentication**: Consider adding room-level authentication\n4. **HTTPS only**: WebTransport requires HTTPS (enforced by Cloudflare)\n\n## Related Documentation\n\n- [Dash WebTransport Integration Guide](./WEBTRANSPORT_INTEGRATION.md)\n- [Architecture Decision](./ARCHITECTURE_DECISION.md)\n- [Durable Objects Implementation](./DURABLE_OBJECTS.md) - How Durable Objects coordinate room state\n- [Cloudflare Workers WebTransport Docs](https://developers.cloudflare.com/workers/runtime-apis/webtransport/)\n- [Cloudflare Durable Objects Docs](https://developers.cloudflare.com/durable-objects/)\n\nLast Updated: 2026-01-31\n\n## Sub-Directories\n\n- **[Go](./go)**\n- **[Src](./src)**\n","readmeFilename":"README.md"}