rpc

Overview ¶

Package rpc provides protocol-agnostic RPC client/server abstractions. Applications use these interfaces without caring about the underlying transport (ZAP, gRPC, JSON-RPC, etc.).

ZAP is the default transport. Use build tags to enable alternatives:

go build -tags grpc  # Enable gRPC transport
go build -tags json  # Enable JSON-RPC transport

Package rpc provides protocol-agnostic RPC abstractions for the Lux ecosystem.

Transport Selection ¶

ZAP is the default transport, optimized for high-frequency trading and VM communication. Use build tags to enable alternative transports:

go build              # ZAP only (default, fastest)
go build -tags grpc   # Enable gRPC transport
go build -tags json   # Enable JSON-RPC transport

Usage ¶

Client usage:

client, err := rpc.Dial(ctx, "localhost:9000")
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Structured call (auto JSON encoding)
var result MyResponse
err = client.Call(ctx, "Service.Method", &MyRequest{...}, &result)

// Raw call (zero-copy, for HFT)
resp, err := client.CallRaw(ctx, "trade", orderBytes)

Server usage:

server, err := rpc.Listen(":9000")
if err != nil {
    log.Fatal(err)
}

// Register raw handler for low-latency
server.RegisterRaw("trade", func(ctx context.Context, payload []byte) ([]byte, error) {
    // Process order with zero-copy
    return processOrder(payload)
})

server.Serve(ctx)

Performance ¶

ZAP transport benchmarks (Apple M1 Max):

BenchmarkRoundTrip/1KB    46ns encode, 19ns decode, 0 allocs
BenchmarkRoundTrip/100KB  1.6μs encode, 19ns decode, 0 allocs
BenchmarkRoundTrip/1MB    20μs encode, 19ns decode, 0 allocs

ZAP vs Protobuf comparison:

1KB:   7.9x faster encode, 19.8x faster decode
100KB: 8.5x faster encode, 658x faster decode
1MB:   7x faster encode, 2866x faster decode

Architecture ¶

The package separates concerns:

• client.go: Protocol-agnostic Client and Server interfaces
• codec.go: Codec interface for message encoding
• transport.go: Transport registry for build-tag extensibility
• dial.go: Dial and Listen factory functions
• zap.go: ZAP transport implementation (default)
• dial_grpc.go: gRPC transport (requires -tags grpc)

Application code should only depend on the Client/Server interfaces, making transport selection a deployment decision rather than a code change.