Configuration

Configuration & builder reference

You can configure Vyra using the fluent builder obtained via Vyra.builder() or transport-specific factory helpers (such as RedisVyra.redis(...) or InMemoryVyra.inMemory(...)).

---

Complete builder reference

Vyra vyra = Vyra.builder()
        .transport(new RedisTransport(redisClient)) // Required (or use factory)
        .serializer(JacksonSerializer.jackson())    // Required
        .nodeId("billing-service-1")                // Optional (Default: auto-generated UUID)
        .registry(new CustomMessageRegistry())      // Optional (Default: internal registry)
        .handlerExecutor(customThreadPool)          // Optional (Default: internal daemon pool)
        .build();

Builder option	Required?	Default value	Purpose
transport(Transport)	Yes	—	Specifies the byte-delivery transport (e.g. RedisTransport, InMemoryTransport).
serializer(Serializer)	Yes	—	Specifies the serializer for encoding envelopes and domain payloads.
nodeId(String)	No	Auto-generated UUID string	Unique identity for this instance. Used to route responses back to this node.
registry(MessageRegistry)	No	Internal DefaultMessageRegistry	Maps stable wire identifiers ("player.get") to Java classes.
handlerExecutor(ExecutorService)	No	Fixed-size daemon thread pool	The executor where deserialization and user handlers execute.

---

Lifecycle rule: supplied = yours, created = ours

To prevent resource leaks and premature shutdowns in shared environments, Vyra follows one ownership rule:

flowchart TD
    CloseCall["vyra.close() called"] --> TransportClose["Close transport connections<br/>Cancel pending request timeouts"]
    TransportClose --> CheckExec{"Was the handler executor supplied by you?"}
    CheckExec -- "Yes (supplied)" --> LeaveExec["Do NOT shut it down.<br/>You manage its lifecycle."]
    CheckExec -- "No (created by Vyra)" --> KillExec["Shut down the internal executor pool."]
    TransportClose --> CheckClient{"Was the transport client supplied by you?<br/>(e.g. RedisClient, InMemoryBus)"}
    CheckClient -- "Yes (supplied)" --> LeaveClient["Do NOT shut it down.<br/>You own the client."]
    CheckClient -- "No (created by Vyra)" --> KillClient["Shut down the internal client."]

Loading

One rule, two resources: whatever you supplied stays alive after close(); whatever Vyra created is shut down.

1. Handler executor ownership

// Scenario A: you supply an existing application thread pool
ExecutorService sharedPool = Executors.newFixedThreadPool(16);
Vyra vyra = Vyra.builder()
        .transport(transport)
        .serializer(serializer)
        .handlerExecutor(sharedPool) // Supplied = yours
        .build();

vyra.close();
// sharedPool is STILL RUNNING! You must shut it down yourself when your app stops.
sharedPool.shutdown();

// Scenario B: you rely on Vyra's default executor
Vyra vyraDefault = Vyra.builder()
        .transport(transport)
        .serializer(serializer) // Created = Ours
        .build();

vyraDefault.close();
// Vyra automatically shuts down its internal daemon worker pool.

2. RedisClient ownership

The Lettuce RedisClient represents your connection pool and event loops:

RedisClient redisClient = RedisClient.create("redis://localhost:6379");
Vyra vyra = RedisVyra.redis(redisClient).serializer(serializer).build();

vyra.close(); 
// Closes only the internal connections opened by this Vyra instance.
// redisClient remains open and can be reused by other Vyra instances or DAOs.

---

Setting node IDs in production

By default, Vyra assigns each instance a random UUID string (e.g., 550e8400-e29b-41d4-a716-446655440000).

In production, set a human-readable, stable identifier:

Vyra vyra = RedisVyra.redis(client)
        .serializer(JacksonSerializer.jackson())
        .nodeId("billing-service-prod-pod-4")
        .build();

Important

The nodeId must be unique among all live, connected instances. If two active nodes share the same nodeId, responses meant for one node may be consumed by the other.

---

Custom message registries

The MessageRegistry interface decouples network identifiers from internal Java class paths:

public interface MessageRegistry {
    void register(String messageType, Class<?> type);
    String getMessageType(Class<?> type);
    Class<?> getClass(String messageType);
}

The default registry is thread-safe and configured via vyra.register(...). If your organization uses an automated annotation scanner or external schema registry, you can provide a custom implementation via .registry(...).

---

Next steps

• The threading architecture in Concurrency.
• Learn about error recovery and status codes in Timeouts & errors.
• Explore best practices for production reliability in Best practices.