faucetsdn/udmi/transport-and-target-routing

Transport & Target Specification Navigational Playbook

This playbook guides the agent on where and how to investigate UDMI target specifications, connection transports, and reflector mechanisms in the codebase.

1. Target Specification Syntaxes & Parsing

UDMI tools (sequencer, validator, mantis, udmis, registrar, pubber) dynamically configure target IoT environments, provider semantics, and namespace isolation using project target specifications (project_spec / target_spec).

Authoritative Implementations

• Java: `SiteModel.java` (SPEC_PATTERN, extractSpec, augmentConfig).
• Java Services: `AbstractPollingService.java` (ProjectSpec record).
• Bash: `etc/shell_common.sh` (normalize_conn_spec), `bin/sequencer` (lines 128–153), `bin/pubber` (lines 104–135).
• Python: `mantis/project_spec.py` (parse_project_spec, normalize_project_spec, resolve_target_spec).
• Workbench: `workbench/server/discovery.py` (build_project_spec, the spec suggested for a site model), `workbench/server/testbed.py` (LOCAL_SPEC_PATTERN, the only spec the local testbed accepts).
• Documentation: `docs/tools/project_spec.md`.

The Canonical Specification Expression

Defined in SiteModel.java as:

(//([a-z]+)/)?(([a-z0-9:@.-]+))(/([a-z0-9]+))?(\+([a-z0-9-]+))?

Structural representation:

[//provider/]project[@bridge_host][/namespace][+user]

Capture Groups & Component Semantics

1. Provider (`//provider/`, Group 2, Optional):

• Evaluated to IotAccess.IotProvider: gbos, gref, mqtt, pubsub, jwt, clearblade, local, dynamic, implicit, etcd.
• If omitted:
• Strings with bos-platform- or cloud patterns default to gbos.
• Strings with : (e.g. localhost:18833) or standalone words default to mqtt.

1. Project & Endpoint (`project`, Group 4, Required):

• Supports GCP project IDs (bos-platform-staging, bos-platform-dev), hostnames (localhost, 127.0.0.1, mosquitto).
• Special Value -- or _: Mapped to NO_SITE (null project_id), indicating disconnected or local execution.
• Port Override (`:port`): e.g. //mqtt/localhost:46432. Sets project_id="localhost", bridge_host="localhost:46432".
• Bridge Host Override (`@bridge_host`): e.g. //gbos/bos-platform-dev@mqtt.bos.goog, //jwt/bos-platform-dev@mqtt.bos.goog, //mqtt/_@localhost:18833. Sets project_id to prefix before @ (or null if _), and bridge_host to host after @.

1. Namespace (`/namespace`, Group 6, Optional):

• Multi-tenant isolation qualifier ([a-z0-9]+, e.g. /faucetsdn, /udmis).
• Prefixes cloud resources with delimiter ~ (e.g. <namespace>~UDMI-REFLECT, <namespace>~udmi_reflect).

1. User (`+user`, Group 8, Optional):

• Concurrent execution domain ([a-z0-9-]+, e.g. +dev_user, +runner1).
• Rule: Supported for gref and pubsub. Specifying +user on gbos or mqtt is rejected with an error by Java tools (user name not supported).

Exhaustive Syntax Variants

2. General Transport Diagnostic Methodology

When diagnosing transport timeouts, connection errors, or communication failures:

Communication Path Boundaries

• Parse the target specification using parse_project_spec or inspect the provider syntax (//gbos/, //gref/, //mqtt/, //pubsub/).
• Determine the transport boundaries:
• Direct Local Broker (//mqtt/...): Client connects directly to local MQTT broker (Mosquitto). Verify broker process health, port availability, and credentials.
• Cloud Reflector (//gbos/...): Client connects via cloud bridge (e.g., ClearBlade / IoT Core) through reflector registries (<namespace>~UDMI-REFLECT).
• Direct Cloud Pub/Sub (//gref/... or //pubsub/...): Client interacts directly with GCP Pub/Sub topics and subscriptions (udmi_reflect, udmi_reply).