disguise developers

Discovery

Designer instances after r30.8 support DNS-SD discovery. This allows you to discover Designer instances on your network and connect to them, without prior knowledge of the hostname or port number. There are two services published by Designer - the host and the director services.

The services are published with unique names and other metadata which help understand what is available on the local network.

All services are currently only supported on the .local domain.

The host service

The host service is named _d3host._tcp within DNS-SD. The service instance name is the hostname of the machine. The full name for a machine with hostname vx4-44158 would therefore be vx4-44158._d3host._tcp.local..

The host service is available at all times when the machine is turned on, and all machines running d3service publish this service.

Host services publish the following TXT records (properties)

PropertyDescription
gatewayWhether the machine is likely to serve as a session host given past usage. i.e. is it a machine which recently hosted a session, even if one is not running currently
recentProjectThe relative path to the most recently run project on the machine.
recentRoleWhich session role the machine has most recently filled
versionNumberThe version of the Designer software currently running on the machine
branchThe branch of the Designer software

The director service

The director service is named _d3director._tcp. The service instance name is the name of the session which the director is currently hosting, with special characters replaced with _. An example full name for a director service might be folder_projectname_d3session._d3director._tcp.local.

Director services are only published when the Designer software is running and the software is in control of a session.

Director services publish the following TXT records (properties)

PropertyDescription
sessionNameThe unmangled name of the session e.g. "folder/projectname.d3session"

Discovery script

Disguise has provided a Python 3 discovery script which can be used to discover systems on the network and functions as a debug/diagnostics tool as well as a reference for how to discover servers on a local network. To use the script, the zeroconf library needs to be installed (pip install zeroconf)

Python Example

In the below example, we use the zeroconf library to discover Designer instances on the local network. We then make an HTTP GET request to the /api/session/status/health health endpoint to check the health of the Designer instance. This allows us to check the health of the Designer instance and get the current FPS and system states, without prior knowledge of the Designer instance’s hostname or port.

from zeroconf import ServiceBrowser, Zeroconf # Use the zeroconf library to discover Designer instances
import requests # Use the requests library to make HTTP requests
import json # Use the json library to parse JSON

class Listener:
    def check_health(self, hostname, port):
        """Check the health of a d3 instance and print the results."""
        try:
            url = f"http://{hostname}:{port}/api/session/status/health" # Create the URL for the health check
            response = requests.get(url, timeout=5) # Make the HTTP GET request to the health check URL
            if response.status_code == 200: # Check if the response status code is 200 (OK)
                health = response.json() # Parse the response as JSON
                # Extract and display relevant health info
                for result in health['result']:
                    machine = result['machine']
                    status = result['status']
                    print(f"\nHealth Status for {machine['name']}:")
                    print(f"  FPS: {status['averageFPS']:.2f}")
                    print("\nSystem States:")
                    for state in status['states']:
                        print(f"  {state['name']}: {state['detail']} ({state['severity']})")
            else:
                print(f"Health check failed with status code: {response.status_code}") # Print the status code if the health check fails
        except Exception as e:
            print(f"Failed to get health status: {str(e)}") # Print the error message if the health check fails

    def add_service(self, zc, type_, name):
        if "d3api" in name.lower():  # Check if the service name contains "d3api"
            info = zc.get_service_info(type_, name) # Get the service info from the zeroconf instance
            if info:
                hostname = info.server.rstrip('.local.') # Get the hostname from the service info
                print(f"Found d3 instance - {name} {hostname}:{info.port}") # Print the service name, hostname and port
                self.check_health(hostname, info.port) # Perform health check

    def update_service(self, zc, type_, name):
        if "d3api" in name.lower():
            info = zc.get_service_info(type_, name) # Get the service info from the zeroconf instance
            if info:
                hostname = info.server.rstrip('.local.') # Get the hostname from the service info
                print(f"\nUpdated d3 instance - {name} {hostname}:{info.port}") # Print the service name, hostname and port
                self.check_health(hostname, info.port) # Perform health check

zc = Zeroconf()
browser = ServiceBrowser(zc, "_d3director._tcp.local.", Listener())
input("Press Enter to exit...\n")
zc.close()

Legacy api service

It is not recommended, but if versions < 30.8 are required, another service is published on the _http._tcp service called d3api. Because the service name is the same, it is not very compatible with multiple Disguise servers on the network. Depending on network conditions, the service instances can be overlaid and overwrite one another, or the OS may rename the service (e.g. append a number in some form) to disambiguate the different instances. This doesn’t give enough information to select machines effectively, and is not as reliable. The d3api service is still available in later versions of Designer, and shares the same lifecycle as the host service.