Skip to content

Ubiquitous Language for Dioad Connect

Introduction

This document defines a consistent vocabulary for discussing Dioad Connect components, concepts, and architecture. A ubiquitous language ensures that discussions between developers, operators, and documentation are unambiguous and precise.

Problem Addressed: The Connect system uses terms like "tunnel," "server," "agent," "endpoint," "target," "forward," and "reverse" in overlapping contexts, creating ambiguity. This document establishes precise definitions for each concept.


Core Concepts

1. Deployment Tier (Top-level Components)

Agent Instance (or simply "Agent")

The local command-line tool (connect agent) that runs on a user's machine or server.

  • Establishes connections to a Connect Server
  • Manages local services that will be exposed
  • Provides a management API for viewing tunnel status

Usage:

  • "The agent connects to the server"
  • "Configure the agent with agent.yaml"
  • "The agent is running on port 4444"

NOT "tunnel" or "client"


Connect Server (or simply "Server")

The central command-line service (connect server) that receives connections from Agents and routes traffic.

  • Accepts inbound Agent connections
  • Manages tunnel registrations
  • Routes internet traffic to appropriate Agents
  • Provides management and control APIs

Usage:

  • "Deploy the Connect Server in your data center"
  • "The agent connects to the Connect Server on port 8119"
  • "Server listens on port 8443 for traffic"

NOT "the tunnel server" or "reverse tunnel server"


2. Traffic Direction (How services are exposed)

Reverse Tunnel (or "Reverse Traffic Path")

A service running locally (behind NAT/firewall) that is exposed to external traffic.

  • Agent initiates connection to Server
  • External clients connect to Server
  • Server routes traffic back through Agent to local service
  • Example: Expose a local web server to the internet

Diagram:

Internet Client → Server → Agent → Local Service
(inbound)

Usage:

  • "Configure a reverse tunnel to expose your web server"
  • "The reverse tunnel allows external access to internal services"
  • "Port 443 on the server routes to the reverse tunnel"

Forward Tunnel (or "Forward Traffic Path")

A service running on an external/remote system that is accessed from the local network.

  • Agent initiates connection to Server
  • Agent listens locally for connections
  • Local clients connect to Agent
  • Agent forwards traffic through Server to remote service

Diagram:

Local Client → Agent → Server → Remote Service
(outbound)

Usage:

  • "Use a forward tunnel to access databases in the cloud"
  • "Configure a forward tunnel for SOCKS5 proxy to remote network"
  • "The forward tunnel makes remote services accessible locally"

3. Tunnel Configuration and Lifecycle

Tunnel Definition (or "Tunnel Configuration")

The configuration that specifies what service to expose and how.

  • Defined in the agent.yaml file
  • Each definition has a name, type, endpoint, and optional tags
  • Defines whether traffic is reverse or forward
  • Specifies TLS configuration, authentication, etc.

Usage:

  • "Create a tunnel definition for your web server"
  • "The tunnel definition specifies the endpoint URL"
  • "Tags are stored in the tunnel definition for filtering"

NOT "tunnel" alone (too vague)


Active Tunnel (or "Established Tunnel")

A tunnel that has been successfully instantiated and is actively carrying traffic or ready to carry traffic.

  • Agent has a tunnel definition
  • Connection to server is established
  • Service is accessible through the tunnel

Lifecycle:

Tunnel Definition → (agent starts) → Connection Negotiation → Active Tunnel

Usage:

  • "The active tunnel is carrying traffic"
  • "List all active tunnels with connect agent status"
  • "When the agent reconnects, the active tunnel is reestablished"

4. Local Services (What Runs in the Agent)

Exposed Service (or "External Local Service")

A service running on the same machine/network as the Agent, but external to the connect process, that is being exposed through tunnels.

  • Examples: A separate Flask web server, local PostgreSQL database, or an SSH server.
  • Defined by its target-address or target-url in configuration.

Managed Exec Service (or "Exec Service")

A service that is actually managed and executed by the Agent itself.

  • Configured in the services/exec section of agent.yaml.
  • The Agent handles starting, stopping, and restarting the process (e.g., maddy mail server).
  • Often works in conjunction with a tunnel to expose its capabilities.

Usage:

  • "The maddy mail server is a managed exec service"
  • "The agent starts the exec service after establishing control connections"

Tunnel Server (or "Tunnel Handler")

The component that handles a specific service type. Implements the protocol/connection logic for a tunnel.

  • Examples: HTTPReverseProxyServer, FileTunnelServer, TCPTunnelServer
  • Implements the tunnel.Server interface
  • Handles the exposed service and traffic to/from it
  • Could be built-in or registered via SDK

Usage:

  • "The tunnel server for HTTP reverse proxy handles SNI routing"
  • "Register a custom tunnel server for your protocol"
  • "The file tunnel server handles both listing and serving files"

NOT "reverse tunnel server" or "forward tunnel server" (the server is neither, it's the tunnel definition that specifies direction)


5. Extensions and Features (Optional Capabilities)

Extension (or "Tunnel Extension")

Optional UI and API capabilities provided by a tunnel server.

  • Agent exposes at /extensions/{tunnelID}/ui/ and /extensions/{tunnelID}/api/
  • Provides management UI or programmatic API for the tunnel
  • Example: Custom message API endpoint in hello tunnel

Usage:

  • "The tunnel provides an extension for managing configuration"
  • "Access the tunnel extension UI to view statistics"
  • "Call the extension API to update settings"

NOT "management UI" (that's the Agent's main UI)


Tunnel Type (or "Service Type")

The classification of what kind of tunnel it is. Determines which tunnel server handles it.

  • Examples: hello, file, tcp, httpreverseproxy, socks5
  • Declared in tunnel definition with type: tcp
  • Must have a registered tunnel server implementation

Usage:

  • "Use tunnel type 'tcp' to forward arbitrary TCP traffic"
  • "The 'file' tunnel type serves a local directory"
  • "Register a new tunnel type with the SDK"

6. Connection and Protocol (Network Communication)

Control Connection (or "Control Channel")

The WebSocket/Connect Protocol connection between Agent and Server.

  • Bidirectional communication
  • Used for control plane messages (registration, routing info, etc.)
  • Separate from data/traffic plane

Usage:

  • "The control connection is established on port 8119"
  • "Control connection messages are compressed and encrypted"
  • "When the control connection drops, all tunnels become inactive"

Traffic Connection (or "Data Connection" or "Traffic Path")

The actual data flowing through an active tunnel.

  • Reverse tunnels: Internet → Server → Agent → Local Service
  • Forward tunnels: Local Client → Agent → Server → Remote Service
  • May be multiplexed over control connection or separate

Usage:

  • "Traffic connections use TLS encryption"
  • "The traffic connection is established through the control connection"
  • "Metrics track bytes transmitted on traffic connections"

Connect Server Address (or "Server Endpoint")

The address of the Connect Server that the Agent connects to.

  • Specified in the endpoint field of agent.yaml (either globally in tunnel-defaults or per tunnel).
  • Usually points to the control plane path on the server (e.g., https://connect.example.com/connect/https).

Access URL (or "Public URL" or "External URL")

The URL where the tunnel is actually accessed by clients.

  • For reverse tunnels: The public hostname/path on the Connect Server (e.g., https://my-service.example.com).
  • For forward tunnels: The local address on the Agent (e.g., localhost:8080).

Endpoint (Ambiguous Term)

Warning: This term is used inconsistently across the system and should be qualified when possible.

  • In Configuration: endpoint refers to the Connect Server Address.
  • In Documentation/UI: endpoint often refers to the Access URL.
  • In Routing: It may refer to the SNI hostname or target destination.

Usage:

  • "The agent connects to the server endpoint" (Connect Server Address)
  • "The tunnel endpoint is accessible at my-service.com" (Access URL)

Remote Target (or "Target Service")

For forward tunnels: The external service being accessed.

  • Specified by hostname and port in the tunnel configuration.
  • Can be Static (fixed address in cloud/data center) or Dynamic (determined by the protocol, e.g., with SOCKS5).
  • Example: database.aws.region.rds.amazonaws.com:5432.

Usage:

  • "The forward tunnel connects to the remote target in AWS"
  • "Configure TLS when connecting to the remote target"
  • "The target service is only accessible through the tunnel"

7. Routing and Traffic Management

Tunnel Route (or "Routing Rule" or "Hostname Mapping")

The rule that determines which tunnel handles a particular request.

  • For reverse tunnels: SNI hostname → tunnel mapping
  • For forward tunnels: Local listener port → tunnel mapping
  • Managed by server's route manager

Usage:

  • "Add a tunnel route for 'api.example.com' to tunnel 'api-service'"
  • "The tunnel route uses SNI for routing decisions"
  • "Multiple tunnel routes can point to the same tunnel"

Traffic Forwarder (or "Proxy" or "Traffic Handler")

The component that handles actual traffic forwarding/proxying.

  • Different implementations for different tunnel types
  • Part of the tunnel server implementation
  • Moves bytes between two sides of a connection

Usage:

  • "The traffic forwarder handles HTTPS connections"
  • "The traffic forwarder closes connections on timeout"
  • "Metrics show bytes handled by the traffic forwarder"

8. Management and Visibility

Agent Management API (or "Agent API" or "Status API")

The REST API exposed by the Agent.

  • Listens on management.listen-address; no struct-level default, but a fresh install with no config file at all self-bootstraps one set to 127.0.0.1:4444
  • Endpoints: /api/tunnels, /api/tunnel/{id}, /api/extensions/{id}/ui/, etc.
  • Provides query-only access (no mutation in core)

Usage:

  • "Query the agent management API for tunnel status"
  • "The agent management API exposes prometheus metrics"
  • "Authentication to agent management API is optional (local use)"

Server Management API (or "Server API" or "Management Server")

The REST API exposed by the Connect Server.

  • Listens on management-listen-address — required, with no default (:5555 is just the convention used in examples)
  • Endpoints for querying tunnel state, metrics, etc.
  • Separate from the control listener

Usage:

  • "The server management API lists all connected agents"
  • "Query the server management API for traffic metrics"
  • "The server management API requires authentication"

Tunnel Status (or "Tunnel State")

The current operational state of a tunnel.

  • States:
    • registered: The tunnel configuration has been loaded but connection hasn't started.
    • connecting: The agent is attempting to establish the control connection.
    • connected: The tunnel is active and ready for traffic.
    • failed: An error occurred during connection or operation.
    • closing: The tunnel is in the process of shutting down.
    • closed: The tunnel has been successfully terminated.
  • Visible in agent management API.
  • Changes are published as events.

Usage:

  • "The tunnel status is 'connected' and healthy"
  • "Check tunnel status before sending traffic"
  • "Tunnel status events are published for monitoring"

9. Authentication and Authorization

Agent Authentication (or "Agent Identity")

Credentials used to authenticate the Agent to the Server.

  • Could be OIDC (GitHub, etc.), HMAC key, mTLS certificate.
  • Configured in the identity section of agent.yaml.
  • Applied to all tunnels to prove agent ownership and permission.

Usage:

  • "Configure agent identity with OIDC/GitHub credentials"
  • "The agent authentication token is refreshed automatically"
  • "Agent identity is validated on the control connection"

Tunnel Authorization (or "Access Control" or "Tunnel ACL")

Rules that determine who can access a tunnel.

  • Applied at the server to restrict traffic to the Access URL.
  • Could be based on hostname, client certificate, IP, etc.
  • Separate from agent authentication/identity.

Usage:

  • "Apply tunnel authorization to restrict access to internal IPs"
  • "Tunnel authorization is checked before forwarding traffic"
  • "Use tags for tunnel authorization grouping"

10. Deployment and Configuration

Agent Configuration (or "Agent Config")

The YAML configuration file for the agent (agent.yaml).

  • Defines all tunnel definitions for this agent.
  • Specifies identity, logging, management server settings.
  • Primary sections: management, identity, tunnel-defaults, traffic, services.

Usage:

  • "Edit the agent configuration to add a new tunnel"
  • "The agent configuration is loaded at startup"
  • "Override agent configuration with command-line flags"

Server Configuration (or "Server Config")

The YAML configuration file for the server (server.yaml).

  • Defines listening addresses, TLS, authentication, logging
  • Sections: log, identity, control, management, connect, events (see doc/SERVER_CONFIGURATION.md)

Usage:

  • "The server configuration specifies TLS certificates"
  • "Configure multiple authentication providers in server configuration"
  • "Load balancers should point to the address in server configuration"

Tunnel Definition Metadata (or "Tunnel Metadata" or "Tunnel Tags")

Structured information about a tunnel.

  • Name, Type, ID, Creation timestamp, TLS settings.
  • User-defined tags for categorization.
  • Exposed through management APIs.
  • Protocol Mapping: Metadata is communicated between Agent and Server via HTTP headers (e.g., X-Tunnel-Connection-ID maps to TunnelMetadata.ConnectionID).

Usage:

  • "Add tags to tunnel definitions for categorization"
  • "Query tunnels by metadata in the management API"
  • "Tunnel metadata is immutable once created"

Tunnel ID vs Tunnel Connection ID

  • Tunnel ID: The unique logical identifier of the tunnel configuration (persists across reconnects).
  • Tunnel Connection ID: The unique identifier of a specific active network session (changes on every reconnect).

Usage:

  • "Filter logs by Tunnel ID to see all attempts for that service"
  • "The Tunnel Connection ID changed after the agent restarted"

11. Observability and Monitoring

Tunnel Metrics (or "Tunnel Statistics")

Quantitative data about tunnel operation.

  • Bytes transmitted/received
  • Connection count
  • Error rates
  • Exposed via Prometheus endpoint

Usage:

  • "Monitor tunnel metrics for performance"
  • "Alert on elevated error rates in tunnel metrics"
  • "Tunnel metrics are reset on agent restart"

Event (or "Tunnel Event")

Notification of significant state changes.

  • Examples: Tunnel connected, disconnected, traffic spike
  • Published to event sink (if configured)
  • Useful for alerting and audit logging

Usage:

  • "Subscribe to tunnel events for monitoring"
  • "Events are published when tunnel status changes"
  • "Use events to trigger auto-scaling or failover"

Terminology Summary Table

Concept Correct Term Avoid Definition
Local tool Agent Client, Agent client The CLI tool running locally
Central service Connect Server Tunnel server, Backend The central hub service
Service exposure Reverse Tunnel Inbound tunnel Local service to internet
Remote access Forward Tunnel Outbound tunnel Access remote from local
Protocol-specific handler Tunnel Server Service Adapter Component implementing tunnel type
Configuration Tunnel Definition Tunnel config, tunnel YAML configuration entry
Live instance Active Tunnel Connected tunnel, live tunnel Running, traffic-carrying tunnel
External local service Exposed Service Tunnel service, backend Service behind Agent (e.g. Flask)
Managed process Managed Exec Service Local service Service started by Agent (e.g. maddy)
Optional capability Extension Management UI, custom API Tunnel UI/API features
Service classification Tunnel Type Tunnel protocol, tunnel kind Type field in config
Agent-Server connection Control Connection Management connection WebSocket/protocol channel
Data flow Traffic Connection Data stream, tunnel stream Actual traffic path
Control Plane Address Connect Server Address Endpoint Address in agent.yaml endpoint field
Public URL Access URL Endpoint Where tunnel is accessed
External service Remote Target Target, remote service Service accessed via forward tunnel
Request routing Tunnel Route Route rule, routing entry Mapping of request to tunnel
Traffic movement Traffic Forwarder Proxy, forwarding logic Component moving bytes
Agent REST API Agent Management API Agent API, status API REST endpoints on Agent
Server REST API Server Management API Server API, management API REST endpoints on Server
Current condition Tunnel Status Tunnel state, tunnel health Current operational state
Logical Identity Tunnel ID ID Permanent ID for a tunnel definition
Session Identity Tunnel Connection ID ID Temporary ID for an active session
Credential system Agent Identity Agent credentials, agent auth How Agent proves identity
Access rules Tunnel Authorization Tunnel ACL, access control Who can use tunnel
Agent YAML file Agent Configuration Agent config, agent.yaml Config file content concept
Server YAML file Server Configuration Server config, server.yaml Config file content concept
Structured info Tunnel Metadata Tunnel attributes, tunnel info Name, tags, creation info
Measurements Tunnel Metrics Tunnel statistics, tunnel stats Bytes, connections, errors
State changes Event Tunnel event, notification Something significant happened

Context-Specific Usage Examples

Scenario 1: User Exposing Web Server

Correct:

"Create a reverse tunnel definition for your web server. Once the agent connects, the active tunnel will forward external traffic to your local web service."

Avoid:

"Set up a tunnel server for your web server. Once the agent client connects, the reverse server will handle traffic from the remote server to your tunnel service."


Scenario 2: Administrator Viewing Health

Correct:

"Check the Agent Management API to view tunnel status. If the control connection is down, all active tunnels are inactive. Check the tunnel metrics in the Server Management API for overall traffic."

Avoid:

"Check the tunnel status in the API. If the tunnel client connection is down, all tunnels are offline. Check the tunnel stats in the server API for overall tunnel throughput."


Scenario 3: Developer Implementing Custom Service

Correct:

"Create a new Tunnel Type by implementing the tunnel.Server interface. Your tunnel server will receive connections from the Agent and forward them to the exposed service based on the tunnel definition."

Avoid:

"Create a new tunnel by implementing the tunnel server interface. Your reverse tunnel server will receive calls from the agent client and send them to the tunnel service based on the tunnel config."


Scenario 4: Network Admin Configuring Authorization

Correct:

"Configure tunnel authorization in the Server to restrict which clients can access each tunnel route. Use tags in tunnel definitions to group tunnels for authorization policies."

Avoid:

"Configure tunnel ACL in the server to restrict tunnel access. Use tags in tunnel configs to group tunnels for access control."


Implementation Notes

For Documentation Writers

  • Refer to this glossary when writing docs
  • Use consistent terms across all documents
  • When introducing a new concept, provide a brief definition with reference to this glossary

For Code Comments

  • Use these terms in code comments and docstrings
  • Example: "Return the active tunnel's current status" not "Return tunnel's state"
  • Example: "Register a new tunnel type" not "Register a new tunnel protocol"

For Error Messages

  • Use terms from this glossary in error messages
  • Example: "Failed to establish control connection to server" not "Failed to connect to tunnel server"

For API Documentation

  • Document endpoints using glossary terms
  • Example: "GET /api/tunnel/{tunnelID}" returns Tunnel Status, not "tunnel state"

For Logs and Metrics

  • Log messages should use glossary terms
  • Metric names should be clear
  • Example: tunnel_control_connection_up not tunnel_client_connected

Common Confusion Points and Clarifications

"Tunnel" Alone Is Ambiguous

Problem: "Configure the tunnel"

Better:

  • "Configure the tunnel definition" (the config)
  • "Activate the tunnel" (start using it)
  • "Monitor the active tunnel" (the running instance)
  • "What's the tunnel type?" (classification)

"Server" Can Mean Different Things

Problem: "The tunnel server is not responding"

Clearer:

  • "The Connect Server is not responding" (the central service)
  • "The tunnel server implementation crashed" (the handler for a type)
  • "The exposed service is not responding" (the local service)

"Forward" and "Reverse" Are Directions, Not Components

Problem: "Deploy the reverse tunnel server"

Better:

  • "Configure a reverse tunnel to expose the service" (describes traffic direction)
  • "The tunnel server handles reverse tunnel definitions" (the service type)
  • "In reverse tunnels, external clients connect to the server first" (clarifies direction)

"Endpoint" Specificity

Problem: "The endpoint is failing" (ambiguous - which endpoint?)

Better:

  • "The Access URL 'api.example.com' is not resolving" (the public URL)
  • "The Connect Server Address configuration is invalid" (the endpoint: config entry)
  • "Traffic to the Access URL is timing out" (connections to the public endpoint)

Glossary (Alphabetical Quick Reference)

  • Active Tunnel: Running tunnel carrying traffic or ready to carry traffic
  • Agent: Local CLI tool that connects to Connect Server
  • Agent Configuration: The agent.yaml file and its settings
  • Agent Identity: Credentials for Agent to authenticate to Server
  • Agent Management API: REST API exposed by the Agent
  • Connect Server: Central hub that receives Agent connections and routes traffic
  • Connect Server Address: The address of the Server in agent.yaml
  • Control Connection: WebSocket channel between Agent and Server
  • Event: Notification of significant state changes
  • Access URL: URL where a tunnel is accessed by clients
  • Exposed Service: External local service being exposed through tunnels
  • Managed Exec Service: Process started and managed by the Agent
  • Extension: Optional UI/API capabilities from tunnel server
  • Forward Tunnel: Tunnel that accesses external services from local network
  • Remote Target: External service accessed via forward tunnel
  • Reverse Tunnel: Tunnel that exposes local services to external traffic
  • Server Configuration: The server.yaml file and its settings
  • Server Management API: REST API exposed by the Connect Server
  • Traffic Connection: Actual data flow through a tunnel
  • Traffic Forwarder: Component that moves bytes in tunnels
  • Tunnel Authorization: Rules controlling tunnel access
  • Tunnel Definition: Configuration entry for a tunnel (in agent.yaml)
  • Tunnel ID: Unique logical identifier of the tunnel configuration
  • Tunnel Connection ID: Unique identifier of a specific active network session
  • Tunnel Metadata: Structured info about a tunnel (name, tags, etc.)
  • Tunnel Metrics: Performance measurements (bytes, connections, errors)
  • Tunnel Route: Rule mapping requests to tunnels
  • Tunnel Server: Component handling specific tunnel type
  • Tunnel Status: Current operational state of a tunnel
  • Tunnel Type: Classification of tunnel (tcp, file, httpreverseproxy, etc.)