Networking Layer
Speed is nothing without a frictionless delivery mechanism. LoomCache handles inter-node communication and client-server traffic through a highly optimized TCP layer built on Java NIO2 and Virtual Threads.
The Binary Protocol
Section titled “The Binary Protocol”Rather than communicating via HTTP or REST JSON, LoomCache utilizes a hyper-efficient, custom binary protocol with 108 distinct message types.
Wire Protocol Pipelining
Zero-copy serialization with batched pipelining over persistent TCP connections.
- Header Structure: Every packet has a fixed-length header declaring the payload size, operation code (OP-Code), and a strict format. This enables zero-parse-ahead framing.
- Kryo 5.6.2 Serialization: Map entries and keys are serialized via Kryo’s high-performance binary format with object pooling to minimize GC pressure.
- Pipelining: Multiple commands can be flushed rapidly on the same connection (batch size configurable, default 100), significantly reducing round-trip latency.
Message categories
Section titled “Message categories”Counts from MessageType.java:
| Category | Examples |
|---|---|
| Data operations | MAP_PUT, MAP_GET, QUEUE_OFFER, SET_ADD, TOPIC_PUBLISH |
| Raft consensus | RAFT_APPEND_ENTRIES, RAFT_VOTE_REQUEST, RAFT_PRE_VOTE_REQUEST, RAFT_INSTALL_SNAPSHOT, RAFT_TIMEOUT_NOW |
| Cluster management | CLUSTER_JOIN, CLUSTER_LEAVE, CLUSTER_PING, PARTITION_TABLE, PARTITION_MIGRATE_START |
| Consistency subsystem | CP_ATOMIC_GET, CP_ATOMIC_CAS (lock / semaphore opcodes exist but are currently rejected server-side) |
| Client control | AUTH, NEAR_CACHE_SUBSCRIBE, BATCH_EXECUTE, SQL_QUERY_EXECUTE |
| WAN / executor | WAN_*, EXECUTOR_* (server-side scaffolding) |
| Responses | RESPONSE_OK, RESPONSE_ERROR, RESPONSE_REDIRECT, RESPONSE_SERVER_BUSY, RESPONSE_SEQUENCE_LOST |
Thread-Pool Isolation
Section titled “Thread-Pool Isolation”Networking logic is separated via specialized execution arenas:
- TcpServer — Virtual thread per connection. Blocks freely on I/O; JVM unmounts carrier thread automatically.
- CommandExecutorPool — Dedicated pool for state machine operations. Prevents slow clients from backing up consensus.
- BackpressureController — Watermark-based flow control. When the command queue fills, new connections are back-pressured rather than dropped.
Connection Lifecycle
Section titled “Connection Lifecycle”Each connection is tracked by a ConnectionContext holding the negotiated TLS identity, resolved permission set, and
per-connection request counters. ConnectionHealthMonitor closes connections that exceed the per-IP limit with
TOO_MANY_CONNECTIONS.
Backpressure
Section titled “Backpressure”LoomCache implements watermark-based backpressure via the BackpressureController:
| Watermark | Behavior |
|---|---|
| Below low mark | Normal processing |
| Between marks | New connections throttled |
| Above high mark | New connections rejected with BackpressureException |
This prevents a thundering herd of clients from overwhelming the command queue and starving Raft replication.
Security (mTLS)
Section titled “Security (mTLS)”Production deployments demand zero-trust encryption. LoomCache natively supports Mutual TLS (mTLS) for cluster inner-node communication. Each node validates the identity of adjoining nodes before participating in Raft elections or accepting writes.
- TLSv1.3 by default with TLSv1.2 fallback
- PKCS12 keystores for identity and trust
- Per-connection TLS handshake via
SslContextFactory - Client connections support optional mTLS (
requireClientAuthtoggle)