The behaviour a responder backend implements.

Madness publishes by delegating to whatever responder the host already runs, and only acts as a responder itself when there is none. Each such delegate is a Madness.Responder backend. Application code does not call these callbacks; it calls Madness.publish/2, which selects a backend and drives it.

The callbacks

connect/0, disconnect/1, and optional handle_info/2 maintain a presence connection used to detect daemon availability. Publications use separate registration connections. Failed presence connections are retried with backoff.

capabilities/0 declares what the backend can honour. See "Capabilities".

publish/3 registers a service and returns an opaque handle plus the name the responder actually accepted. unpublish/1 withdraws it.

Its options carry the deadline from Madness.publish/2; a backend must stop waiting by that deadline.

Process ownership is the revocation mechanism

publish/3 is called from the process that will own the registration, and that process exists for exactly as long as the registration should. Any socket or connection the callback opens therefore belongs to that process, and dies with it.

Daemon-backed implementations must open the registration connection in this process and must not pool it. The daemon can then withdraw only this service when the owning process exits.

unpublish/1 is the orderly path, called from the same process during termination. It should be idempotent: it can race with the owner exiting.

It must also return promptly because shutdown has a bounded window.

Empty TXT records

A service with no metadata arrives as txt: []. DNS-SD requires the TXT record to exist and forbids one containing zero strings, so a backend must publish a TXT record holding a single empty string — not no record at all. Both delegated daemons do this for you when handed an empty TXT.

Capabilities

A backend declares the scopes it supports. Madness.publish/2 refuses a scope the selected backend cannot honour:

• :interface_scope - can restrict a publication to one interface.
• :family_scope - can restrict a publication to IPv4 or IPv6 alone.

Apple's IPC protocol has no per-address-family control, so its backend declares :interface_scope only, and family: :inet is rejected there rather than quietly ignored. family: :any is the portable choice.

Asynchronous events

A responder can rename a service long after it was registered, when a new conflicting host appears. A backend that learns of such an event sends a message to its owning process — the one that called publish/3:

send(owner, {:madness_responder, handle, {:renamed, "My Printer (2)"}})
send(owner, {:madness_responder, handle, {:error, reason}})

Madness forwards these to the caller of Madness.publish/2 when it asked for notify: true. {:error, {:connection_lost, reason}} has lifecycle meaning: when it names a handle the publication still holds, Madness terminates that publication with reason {:shutdown, {:connection_lost, reason}}. Monitor the returned publication pid to observe this regardless of notification settings, then publish again if the service should return. Other backend errors are notifications and do not end the publication. A backend with nothing asynchronous to report never sends any.

Interface-scoped publications have the same terminal-handle rule. Losing the concrete interface that existed at registration time exits the owning process with {:shutdown, {:interface_lost, interface}}; losing the interface event stream exits it with {:shutdown, :interface_events_unavailable}. Madness does not move an existing backend handle to an interface that arrives later.

Example

defmodule MyBackend do
  @behaviour Madness.Responder

  @impl true
  def connect do
    # ... reach the daemon, and keep the connection so its closure is
    # noticed. Publications never use this one.
    {:ok, connection}
  end

  @impl true
  def disconnect(connection), do: close(connection)

  @impl true
  def handle_info({:tcp_closed, socket}, %{socket: socket}), do: :disconnected
  def handle_info(_message, connection), do: {:ok, connection}

  @impl true
  def capabilities, do: [:interface_scope]

  @impl true
  def publish(service, scope, opts) do
    # ... open a connection *here*, in this process, register on it, and
    # read back the accepted name, waiting no later than
    # Keyword.get(opts, :deadline, :infinity)
    {:ok, connection, accepted_name}
  end

  @impl true
  def unpublish(connection), do: :ok = close(connection)
end

Madness.Responder.MDNSResponder is a complete worked example.