Relay Portals

A non-blocking, message-oriented relay layer for scalable microservice communication — optimized for real-time workloads.

Relay Portals

Relay portals in our framework provide a simple and efficient way to forward messages from one service to another. They are similar to regular portals, but with added functionality that allows you to route messages through a relay, mitigating the load on other services while keeping your main service as the gateway.

🚦 Creating a Relay Portal

Relay Portals are used to forward specific events or requests to downstream services without overloading your main gateway service. They work similarly to regular portals but are tailored for service-to-service communication, especially over WebSockets.

Note:

Relay Portal is NOT:

  • ❌ A load balancer — it doesn't distribute traffic across multiple instances.
  • ❌ A request-response handler — it does not await or expect responses in a blocking manner.
  • ❌ A message queue — it does not persist, retry, or store messages.
  • ❌ A guaranteed delivery mechanism — delivery is best-effort over the used transport client (e.g. WebSockets).

Note:

✔️ Relay Portals are best used for fire-and-forget forwarding of client messages to downstream services via WebSocket, where the downstream service is responsible for returning a response when ready.

🔧 How to Implement

To create a relay portal, extend the RelayPortal abstract class and define your relay handling logic:

public class MyRelayPortal : RelayPortal {
    ...
    [Gate("relay-event")]
    public void ReceiveResponse(ResponsePacket packet, string clientId) {
        // Forward the message to the client
        Router.Client.SendAsync(ResponsePacket.Header.Receiver, packet);
    }
}

Note:

The clientId parameter here refers to the ID of the downstream service that sent the response. To correctly forward the message, the ResponsePacket.Header.Receiver must be set to the original client’s ID — this tells the relay portal which connected client should receive the response.

This method will be triggered when the underlying service sends a response back via the "relay-event" channel.

📡 Registering the Relay Portal

After implementing your relay portal, register it in your gateway:

.MapRelayPortal<Portal>(host, port, "relay-event")
  • host: The IP or hostname of the downstream service.
  • port: The port on which the downstream service is listening.
  • relay-event: The event name used to route messages between the gateway and the downstream service.

🧠 How It Works

  • When the gateway receives a message targeting relay-event, it forwards it to the configured downstream service host:port via WebSocket.
  • The downstream service processes the message and sends a response back to relay-event.
  • Your RelayPortal instance captures this response and can then forward it to the intended client.

Note:

Currently, Altruist only supports WebSocket relay clients for downstream communication.

When Should You Use Relay Portals?

Relay portals are particularly useful when you have a high-traffic service that is responsible for handling multiple types of requests, but you want to offload specific operations to other specialized services.

For example, if you're working with a game server, you may want to handle authentication, room management, and other basic services on the main server. However, more resource-intensive tasks—like player movement—could be offloaded to a separate service to reduce the load on the main server.

Relay portals help you forward those requests to the right service efficiently, without overwhelming your primary gateway.

Benefits of Using Relay Portals:

  1. Offloading: Offload heavy processing tasks to specialized services without impacting the main service.

  2. Modularity: Keep services decoupled and manageable. Each service can handle its own domain, such as movement, chat, or user authentication.

  3. Efficiency: Forward only the relevant messages to services that are optimized to handle them.

  4. Simplified Communication: Use the same API to route requests to different services, making the system easier to extend and maintain.

When Not to Use Relay Portals

While relay portals offer a lot of flexibility, they are not always the right tool for every situation. Avoid using relay portals when:

  • Immediate Response Is Critical: If you need a response immediately from the same service (i.e., synchronous operations), using a relay might introduce unnecessary latency.

  • Too Much Complexity: If your service dependencies are tightly coupled, adding a relay layer might complicate things further. It's better to use direct communication in such cases.

  • Lack of Network Stability: If your network connection between services is unreliable, forwarding messages through a relay portal may result in higher failure rates. For such scenarios, look into implementing retry or error handling mechanisms.