impl: prefer agent name over agent id in URI handler (#585)

* impl: prefer agent name over agent id in URI handler

Agent name is easier to resolve in jetbrains gateway module

* impl: prefer agent name over agent id in URI handler (2)

Error reporting should also prefer agent name over the agent id.

* chore: update and fix UTs

Test cases related to agent matching have to be updated
now that agent name is preferred over agent id.

* chore: refactor UTs related to agent matching in URI handling

Rewrote the entire test to be easier to read and debug.

Author: fioan89

src/main/kotlin/com/coder/gateway/util/LinkHandler.kt

@@ -327,25 +327,24 @@ internal fun getMatchingAgent(
     }
 
     // If the agent is missing and the workspace has only one, use that.
-    // Prefer the ID over the name if both are set.
-    val agent =
-        if (!parameters.agentID().isNullOrBlank()) {
-            agents.firstOrNull { it.id.toString() == parameters.agentID() }
-        } else if (!parameters.agentName().isNullOrBlank()) {
-            agents.firstOrNull { it.name == parameters.agentName() }
-        } else if (agents.size == 1) {
-            agents.first()
-        } else {
-            null
-        }
+    // Prefer the name over the id if both are set.
+    val agent = if (!parameters.agentName().isNullOrBlank()) {
+        agents.firstOrNull { it.name == parameters.agentName() }
+    } else if (!parameters.agentID().isNullOrBlank()) {
+        agents.firstOrNull { it.id.toString() == parameters.agentID() }
+    } else if (agents.size == 1) {
+        agents.first()
+    } else {
+        null
+    }
 
     if (agent == null) {
-        if (!parameters.agentID().isNullOrBlank()) {
-            throw IllegalArgumentException("The workspace \"${workspace.name}\" does not have an agent with ID \"${parameters.agentID()}\"")
-        } else if (!parameters.agentName().isNullOrBlank()) {
+        if (!parameters.agentName().isNullOrBlank()) {
             throw IllegalArgumentException(
-                "The workspace \"${workspace.name}\"does not have an agent named \"${parameters.agentName()}\"",
+                "The workspace \"${workspace.name}\" does not have an agent named \"${parameters.agentName()}\"",
             )
+        } else if (!parameters.agentID().isNullOrBlank()) {
+            throw IllegalArgumentException("The workspace \"${workspace.name}\" does not have an agent with ID \"${parameters.agentID()}\"")
         } else {
             throw MissingArgumentException(
                 "Unable to determine which agent to connect to; one of \"$AGENT_NAME\" or \"$AGENT_ID\" must be set because the workspace \"${workspace.name}\" has more than one agent",

src/main/kotlin/com/coder/gateway/util/LinkMap.kt

@@ -29,6 +29,7 @@ fun Map<String, String>.owner() = this[OWNER]
 
 fun Map<String, String?>.agentName() = this[AGENT_NAME]
 
+@Deprecated("Use the agent name instead")
 fun Map<String, String?>.agentID() = this[AGENT_ID]
 
 fun Map<String, String>.folder() = this[FOLDER]