Routing Model

Routing Model

AISMixer routing maps internal source IDs to named egress target IDs through logical source zones and ordered route declarations.

Identities

Term	Meaning
source_id	Internal opaque identity for one ingress source.
target_id	Internal opaque identity for one named egress target.
Named forwarder	A forwarders entry with an id; currently implemented for UDP egress.
Logical zone	A named set expression that resolves to source IDs.
Route	An ordered declaration from one logical zone to one or more target IDs.

Canonical source ID examples:

• udp:roof_receiver
• udp:mapped_alias
• udp:192.0.2.10
• udpsec:rPiAIS002

Canonical UDP target ID example:

• udp:aishub

source_id and emitted TAG s are separate concepts. Routing uses source_id; TAG output uses the TAG selection logic.

For trust boundaries around source IDs and TAG metadata, see Security Model.

Source IDs

Plain UDP source identity is selected in this order:

1. configured udp_inputs[].id;
2. mapped alias from udp_alias_map_file;
3. remote IP address.

UDPSEC source identity is based on the authenticated station identity and uses the udpsec: namespace.

Target IDs

Named UDP forwarders use udp:<forwarder-id>. For example:

forwarders:
  - id: aishub
    host: 192.0.2.20
    port: 10110

This creates the route target ID udp:aishub.

Route targets must reference currently available named egress adapters. Only UDP egress targets are currently implemented, so route targets must be existing udp:<id> forwarders.

Logical Zones

Zones are logical sets of source IDs. They are not map areas and do not inspect coordinates, MMSI, vessel type, or AIS payload contents.

Each zone defines exactly one operation:

Operation	Meaning
include	Defines a zone directly from listed source IDs.
union	Combines all source IDs from named operand zones.
intersection	Keeps only source IDs present in every named operand zone.
difference	Starts with the first operand zone and removes source IDs from later operand zones.

routing:
  zones:
    fixed_udp:
      include:
        - udp:roof_receiver
        - udp:dock_gate

    secure_stations:
      include:
        - udpsec:rPiAIS002

    trusted_sources:
      union:
        - fixed_udp
        - secure_stations

    trusted_fixed_sources:
      intersection:
        - trusted_sources
        - fixed_udp

    public_without_secure:
      difference:
        - trusted_sources
        - secure_stations

Operands for union, intersection, and difference are zone names, not source IDs.

Routes

Routes are evaluated in declaration order. A matching route contributes its route name and target IDs.

When multiple matching routes include the same target, target IDs are deduplicated by first occurrence. This preserves route order while avoiding duplicate sends to the same target during one routed output decision.

routing:
  routes:
    - name: trusted_to_debug
      from_zone: trusted_sources
      to:
        - udp:local_debug

    - name: public_platforms
      from_zone: public_without_secure
      to:
        - udp:aishub

Validation and Snapshots

Static routing is compiled during startup. Invalid zones, unknown route zones, unknown fields, or route targets that do not match available named egress adapters fail validation.

RoutingTable snapshots are immutable. Runtime replacement builds and validates a candidate table first, then atomically installs the whole new snapshot through RoutingState.

See the main repository example: examples/config-routing.yaml.