gocapnweb Examples#

This directory contains complete examples demonstrating the Go implementation of Cap'n Web RPC.

Examples#

1. Hello World (`helloworld/`)#

A simple WebSocket RPC example that demonstrates:

Basic method registration and dispatch
WebSocket connection handling
Real-time bidirectional communication
Interactive web client

Running:

cd helloworld
go run main.go

Demo: http://localhost:8000/static/helloworld/

2. Batch Pipelining (`batch-pipelining/`)#

An advanced HTTP batch RPC example that demonstrates:

Pipeline references (chaining dependent calls)
HTTP batch processing for optimal performance
Simulated network latency comparison
Performance metrics and visualization

Running:

cd batch-pipelining
go run main.go

Demo: http://localhost:8000/static/batch-pipelining/

JavaScript Client#

Both examples use the official capnweb JavaScript client library loaded from CDN:

import { newWebSocketRpcSession, newHttpBatchRpcSession } from 'https://unpkg.com/capnweb@latest/dist/index.js';

For production use, install the package:

npm install capnweb

File Structure#

examples/
├── README.md                    # This file
├── static/                      # Static web assets
│   ├── helloworld/
│   │   ├── index.html          # Hello World demo page
│   │   └── client.mjs          # WebSocket client
│   └── batch-pipelining/
│       ├── index.html          # Batch pipelining demo page
│       └── client.mjs          # HTTP batch client
├── helloworld/
│   ├── go.mod                  # Go module
│   └── main.go                 # Hello World server
└── batch-pipelining/
    ├── go.mod                  # Go module
    └── main.go                 # Batch pipelining server

Protocol Compatibility#

These examples are fully compatible with the original C++ implementation:

Same JSON message format
Same WebSocket and HTTP endpoints
Same pipeline reference syntax
Same client-side JavaScript

Testing the Examples#

Hello World Test#

# Terminal 1: Start server
cd helloworld && go run main.go

# Terminal 2: Test with curl
curl -X POST http://localhost:8000/api \
  -d '["push",["pipeline",1,["hello"],["World"]]]'

curl -X POST http://localhost:8000/api \
  -d '["pull",1]'

Batch Pipelining Test#

# Terminal 1: Start server
cd batch-pipelining && go run main.go

# Terminal 2: Test authentication
curl -X POST http://localhost:8000/rpc \
  -d '["push",["pipeline",1,["authenticate"],["cookie-123"]]]'

curl -X POST http://localhost:8000/rpc \
  -d '["pull",1]'

Performance Notes#

The Go implementation provides:

Concurrent handling: Each connection runs in its own goroutine
Memory safety: No memory leaks or segfaults
Built-in JSON: Fast, safe JSON processing
Standard HTTP: Uses Go's battle-tested net/http package

Performance characteristics:

Latency: Similar to C++ for most use cases
Throughput: Excellent for typical RPC workloads
Memory: Automatic garbage collection
Scalability: Goroutines scale better than event loops for blocking operations

Development#

To modify the examples:

Server changes: Edit the main.go files
Client changes: Edit the .mjs files in static/
UI changes: Edit the .html files in static/

The servers automatically serve static files, so you can edit the client code and refresh the browser to see changes.

Troubleshooting#

CORS Issues#

The servers include CORS headers for browser compatibility. If you encounter CORS issues, check that:

The server is running on the expected port
The client is connecting to the correct URL
No proxy is interfering with headers

WebSocket Connection Issues#

For WebSocket problems:

Check browser developer tools for connection errors
Verify the WebSocket URL (ws:// not https://)
Ensure no firewall is blocking the connection

Module Issues#

If you see Go module errors:

go mod tidy
go mod download

JavaScript Import Issues#

The examples use ES modules with CDN imports. For older browsers or different setups, you may need to:

Use a bundler like webpack or vite
Install capnweb locally with npm
Use a different import strategy