Routing

🧭 Routing & Namespaces

🌍 Overview

MAPS Messaging supports dynamic and static routing of messages between distributed servers or nodes. The routing subsystem allows devices and clients to connect to the closest or most available server automatically and helps ensure horizontal scalability across different geographic regions or tenants.

Routing behavior is configured through the Routing.yaml file, while namespace isolation per user or tenant is handled via the TenantManagement.yaml configuration.

---

🚦 Routing Configuration (Routing.yaml)

Routing:
  enabled: false
  autoDiscovery: true
  predefinedServers:
    - name: commonName
      url: https://host:8080/

    - name: commonName1
      url: https://localhost:8080/

🛠️ Field Reference

Field	Description
enabled	Whether routing is enabled. If false, no remote forwarding occurs.
autoDiscovery	Enables discovery of nearby MAPS servers using multicast or similar tech.
predefinedServers	List of statically defined server endpoints.

Routing is especially useful in distributed deployments where devices may connect to different edge nodes or region-specific servers.

🔎 If autoDiscovery is enabled, devices can find the best MAPS node based on availability or proximity.

---

🗂️ Tenant-Based Namespace Management (TenantManagement.yaml)

This file defines how users are mapped to logical namespaces. Each user or group may have a dedicated prefix (namespace root), isolating their message topics and queues.

Example:

TenantManagement:
  data:
    - name: default
      namespaceRoot: /
      scope: user

    - name: global
      namespaceRoot: /common/
      scope: global

    - name: matthew
      namespaceRoot: /
      scope: user

🔍 Explanation

Field	Description
name	Username, group name, or default. Can use tokens like {user} or {protocol}.
namespaceRoot	Base path used as namespace prefix for all destinations.
scope	Scope of the namespace. Can be user, group, or global.

Example: If user alice has a namespaceRoot of /tenantA/, her published topic sensor/1 will be scoped as /tenantA/sensor/1 internally.

---

🧠 Routing + Namespace Use Case

When combined, routing and namespace scoping allow:

• Seamless routing to the correct regional or tenant-specific server.
• Scoped destinations per user/group/tenant.
• Cleaner multi-tenant separation with shared infrastructure.

---

✅ Best Practices

• Enable autoDiscovery only in trusted or private networks.
• Use predefinedServers in production for full control over routing.
• Define a default namespace fallback to avoid connection failures for unknown users.
• Use scoped namespaceRoots (e.g., /tenant1/, /tenant2/) for secure message isolation.
• Use {user} or {protocol} tokens to dynamically generate namespace paths.

---