fix: simplify URI handling when the same deployment URL is already opened (#227)

Netflix reported that only seems to reproduce on Linux (we've only
tested Ubuntu so far).
I can’t reproduce it on macOS. First, here’s some context:
1. Polling workspaces:
Coder Toolbox polls the deployment every 5 seconds for workspace
updates.
These updates (new workspaces, deletions,status changes) are stored in a
cached “environments” list (an oversimplified explanation). When a URI
is executed,
we reset the content of the list and run the login sequence, which
re-initializes
the HTTP poller and CLI using the new deployment URL and token. A new
polling loop
then begins populating the environments list again.

2. Cache monitoring:
Toolbox watches this cached list for changes—especially status changes,
which determine
when an SSH connection can be established.

In Netflix’s case, they launched Toolbox, created a workspace from the
Dashboard, and the
poller added it to the environments list. When the workspace switched
from starting to ready,
they used a URI to connect to it. The URI reset the list, then the
poller repopulated it. But
because the list had the same IDs (but new object references), Toolbox
didn’t detect any changes.
As a result, it never triggered the SSH connection. This issue only
reproduces on Linux, but it
might explain some of the sporadic macOS failures Atif mentioned in the
past.

I need to dig deeper into the Toolbox bytecode to determine whether this
is a Toolbox bug, but
it does seem like Toolbox wasn’t designed to switch cleanly between
multiple deployments and/or users.
The current Coder plugin behavior—always performing a full login
sequence on every URI—is also ...sub-optimal.
It only really makes sense in these scenarios:

1. Toolbox started with deployment A, but the URI targets deployment B.
2. Toolbox started with deployment A/user X, but the URI targets
deployment A/user Y.

But this design is inefficient for the most common case: connecting via
URI to a workspace on the
same deployment and same user. While working on the fix, I realized that
scenario (2) is not realistic.
On the same host machine, why would multiple users log into the same
deployment via Toolbox? The whole
fix revolves around the idea of just recreating the http client and
updating the CLI with the new token
instead of going through the full authentication steps when the URI
deployment URL is the same as the
currently opened URL

The fix focuses on simply recreating the HTTP client and updating the
CLI token when the URI URL matches the existing deployment URL, instead
of running a full login.

This PR splits responsibilities more cleanly:

- CoderProtocolHandler now only finds the workspace and agent and
handles IDE installation and launch.
- the logic for creating a new HTTP client, updating the CLI, cleaning
up old resources (polling loop, environment cache), and handling
deployment URL changes is separated out.

The benefits would be:

- shared logic for cleanup and re-initialization, with less coupling and
clearer, more maintainable code.
- a clean way to check whether the URI’s deployment URL matches the
current one and react appropriately when they differ.

Author: fioan89

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Changed
+
+- streamlined URI handling with a faster workflow, clearer progress, and an overall smoother experience
+
+### Fixed
+
+- URI handling on Linux can now launch IDEs on newly started workspaces
+
 ## 0.8.0 - 2025-12-03
 
 ### Added

gradle.properties

@@ -1,3 +1,3 @@
-version=0.8.0
+version=0.8.1
 group=com.coder.toolbox
 name=coder-toolbox

src/main/kotlin/com/coder/toolbox/CoderRemoteEnvironment.kt

@@ -276,10 +276,8 @@ class CoderRemoteEnvironment(
 
     private fun updateStatus(status: WorkspaceAndAgentStatus) {
         environmentStatus = status
-        context.cs.launch(CoroutineName("Workspace Status Updater")) {
-            state.update {
-                environmentStatus.toRemoteEnvironmentState(context)
-            }
+        state.update {
+            environmentStatus.toRemoteEnvironmentState(context)
         }
         context.logger.debug("Overall status for workspace $id is $environmentStatus. Workspace status: ${workspace.latestBuild.status}, agent status: ${agent.status}, agent lifecycle state: ${agent.lifecycleState}, login before ready: ${agent.loginBeforeReady}")
     }
@@ -312,10 +310,8 @@ class CoderRemoteEnvironment(
      */
     fun startSshConnection(): Boolean {
         if (environmentStatus.ready() && !isConnected.value) {
-            context.cs.launch(CoroutineName("SSH Connection Trigger")) {
-                connectionRequest.update {
-                    true
-                }
+            connectionRequest.update {
+                true
             }
             return true
         }

src/main/kotlin/com/coder/toolbox/CoderRemoteProvider.kt

@@ -2,11 +2,20 @@ package com.coder.toolbox
 
 import com.coder.toolbox.browser.browse
 import com.coder.toolbox.cli.CoderCLIManager
+import com.coder.toolbox.plugin.PluginManager
 import com.coder.toolbox.sdk.CoderRestClient
 import com.coder.toolbox.sdk.ex.APIResponseException
 import com.coder.toolbox.sdk.v2.models.WorkspaceStatus
 import com.coder.toolbox.util.CoderProtocolHandler
 import com.coder.toolbox.util.DialogUi
+import com.coder.toolbox.util.TOKEN
+import com.coder.toolbox.util.URL
+import com.coder.toolbox.util.WebUrlValidationResult.Invalid
+import com.coder.toolbox.util.toQueryParameters
+import com.coder.toolbox.util.toURL
+import com.coder.toolbox.util.token
+import com.coder.toolbox.util.url
+import com.coder.toolbox.util.validateStrictWebUrl
 import com.coder.toolbox.util.waitForTrue
 import com.coder.toolbox.util.withPath
 import com.coder.toolbox.views.Action
@@ -37,13 +46,16 @@ import kotlinx.coroutines.launch
 import kotlinx.coroutines.selects.onTimeout
 import kotlinx.coroutines.selects.select
 import java.net.URI
+import java.net.URL
+import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.coroutines.cancellation.CancellationException
 import kotlin.time.Duration.Companion.seconds
 import kotlin.time.TimeSource
 import com.jetbrains.toolbox.api.ui.components.AccountDropdownField as DropDownMenu
 import com.jetbrains.toolbox.api.ui.components.AccountDropdownField as dropDownFactory
 
 private val POLL_INTERVAL = 5.seconds
+private const val CAN_T_HANDLE_URI_TITLE = "Can't handle URI"
 
 @OptIn(ExperimentalCoroutinesApi::class)
 class CoderRemoteProvider(
@@ -61,11 +73,13 @@ class CoderRemoteProvider(
 
     // The REST client, if we are signed in
     private var client: CoderRestClient? = null
+    private var cli: CoderCLIManager? = null
 
     // On the first load, automatically log in if we can.
     private var firstRun = true
 
     private val isInitialized: MutableStateFlow<Boolean> = MutableStateFlow(false)
+    private val isHandlingUri: AtomicBoolean = AtomicBoolean(false)
     private val coderHeaderPage = NewEnvironmentPage(context.i18n.pnotr(context.deploymentUrl.toString()))
     private val settingsPage: CoderSettingsPage = CoderSettingsPage(context, triggerSshConfig) {
         client?.let { restClient ->
@@ -82,7 +96,7 @@ class CoderRemoteProvider(
             providerVisible = false
         )
     )
-    private val linkHandler = CoderProtocolHandler(context, dialogUi, settingsPage, visibilityState, isInitialized)
+    private val linkHandler = CoderProtocolHandler(context)
 
     override val loadingEnvironmentsDescription: LocalizableString = context.i18n.ptrl("Loading workspaces...")
     override val environments: MutableStateFlow<LoadableState<List<CoderRemoteEnvironment>>> = MutableStateFlow(
@@ -254,6 +268,17 @@ class CoderRemoteProvider(
      * Also called as part of our own logout.
      */
     override fun close() {
+        softClose()
+        client = null
+        cli = null
+        lastEnvironments.clear()
+        environments.value = LoadableState.Value(emptyList())
+        isInitialized.update { false }
+        CoderCliSetupWizardState.goToFirstStep()
+        context.logger.info("Coder plugin is now closed")
+    }
+
+    private fun softClose() {
         pollJob?.let {
             it.cancel()
             context.logger.info("Cancelled workspace poll job ${pollJob.toString()}")
@@ -262,12 +287,6 @@ class CoderRemoteProvider(
             it.close()
             context.logger.info("REST API client closed and resources released")
         }
-        client = null
-        lastEnvironments.clear()
-        environments.value = LoadableState.Value(emptyList())
-        isInitialized.update { false }
-        CoderCliSetupWizardState.goToFirstStep()
-        context.logger.info("Coder plugin is now closed")
     }
 
     override val svgIcon: SvgIcon =
@@ -331,27 +350,49 @@ class CoderRemoteProvider(
      */
     override suspend fun handleUri(uri: URI) {
         try {
-            linkHandler.handle(
-                uri,
-                shouldDoAutoSetup()
-            ) { restClient, cli ->
-                context.logger.info("Stopping workspace polling and de-initializing resources")
-                close()
-                isInitialized.update {
-                    false
+            val params = uri.toQueryParameters()
+            if (params.isEmpty()) {
+                // probably a plugin installation scenario
+                context.logAndShowInfo("URI will not be handled", "No query parameters were provided")
+                return
+            }
+            isHandlingUri.set(true)
+            // this switches to the main plugin screen, even
+            // if last opened provider was not Coder
+            context.envPageManager.showPluginEnvironmentsPage()
+            coderHeaderPage.isBusy.update { true }
+            context.logger.info("Handling $uri...")
+            val newUrl = resolveDeploymentUrl(params)?.toURL() ?: return
+            val newToken = if (context.settingsStore.requiresMTlsAuth) null else resolveToken(params) ?: return
+            if (sameUrl(newUrl, client?.url)) {
+                if (context.settingsStore.requiresTokenAuth) {
+                    newToken?.let {
+                        refreshSession(newUrl, it)
+                    }
+                }
+            } else {
+                CoderCliSetupContext.apply {
+                    url = newUrl
+                    token = newToken
                 }
-                context.logger.info("Starting initialization with the new settings")
-                this@CoderRemoteProvider.client = restClient
-                if (context.settingsStore.useAppNameAsTitle) {
-                    coderHeaderPage.setTitle(context.i18n.pnotr(restClient.appName))
-                } else {
-                    coderHeaderPage.setTitle(context.i18n.pnotr(restClient.url.toString()))
+                CoderCliSetupWizardState.goToStep(WizardStep.CONNECT)
+                CoderCliSetupWizardPage(
+                    context, settingsPage, visibilityState,
+                    initialAutoSetup = true,
+                    jumpToMainPageOnError = true,
+                    connectSynchronously = true,
+                    onConnect = ::onConnect
+                ).apply {
+                    beforeShow()
                 }
-                environments.showLoadingMessage()
-                pollJob = poll(restClient, cli)
-                context.logger.info("Workspace poll job with name ${pollJob.toString()} was created while handling URI $uri")
-                isInitialized.waitForTrue()
             }
+            // force the poll loop to run
+            triggerProviderVisible.send(true)
+            // wait for environments to be populated
+            isInitialized.waitForTrue()
+
+            linkHandler.handle(params, newUrl, this.client!!, this.cli!!)
+            coderHeaderPage.isBusy.update { false }
         } catch (ex: Exception) {
             val textError = if (ex is APIResponseException) {
                 if (!ex.reason.isNullOrBlank()) {
@@ -363,7 +404,63 @@ class CoderRemoteProvider(
                 textError ?: ""
             )
             context.envPageManager.showPluginEnvironmentsPage()
+        } finally {
+            coderHeaderPage.isBusy.update { false }
+            isHandlingUri.set(false)
+            firstRun = false
+        }
+    }
+
+    private suspend fun resolveDeploymentUrl(params: Map<String, String>): String? {
+        val deploymentURL = params.url() ?: askUrl()
+        if (deploymentURL.isNullOrBlank()) {
+            context.logAndShowError(CAN_T_HANDLE_URI_TITLE, "Query parameter \"${URL}\" is missing from URI")
+            return null
+        }
+        val validationResult = deploymentURL.validateStrictWebUrl()
+        if (validationResult is Invalid) {
+            context.logAndShowError(CAN_T_HANDLE_URI_TITLE, "\"$URL\" is invalid: ${validationResult.reason}")
+            return null
         }
+        return deploymentURL
+    }
+
+    private suspend fun resolveToken(params: Map<String, String>): String? {
+        val token = params.token()
+        if (token.isNullOrBlank()) {
+            context.logAndShowError(CAN_T_HANDLE_URI_TITLE, "Query parameter \"$TOKEN\" is missing from URI")
+            return null
+        }
+        return token
+    }
+
+    private fun sameUrl(first: URL, second: URL?): Boolean = first.toURI().normalize() == second?.toURI()?.normalize()
+
+    private suspend fun refreshSession(url: URL, token: String): Pair<CoderRestClient, CoderCLIManager> {
+        context.logger.info("Stopping workspace polling and re-initializing the http client and cli with a new token")
+        softClose()
+        val newRestClient = CoderRestClient(
+            context,
+            url,
+            token,
+            PluginManager.pluginInfo.version,
+        ).apply { initializeSession() }
+        val newCli = CoderCLIManager(context, url).apply {
+            login(token)
+        }
+        this.client = newRestClient
+        this.cli = newCli
+        pollJob = poll(newRestClient, newCli)
+        context.logger.info("Workspace poll job with name ${pollJob.toString()} was created while handling URI")
+        return newRestClient to newCli
+    }
+
+    private suspend fun askUrl(): String? {
+        context.popupPluginMainPage()
+        return dialogUi.ask(
+            context.i18n.ptrl("Deployment URL"),
+            context.i18n.ptrl("Enter the full URL of your Coder deployment")
+        )
     }
 
     /**
@@ -373,6 +470,9 @@ class CoderRemoteProvider(
      * list.
      */
     override fun getOverrideUiPage(): UiPage? {
+        if (isHandlingUri.get()) {
+            return null
+        }
         // Show the setup page if we have not configured the client yet.
         if (client == null) {
             // When coming back to the application, initializeSession immediately.
@@ -420,6 +520,7 @@ class CoderRemoteProvider(
 
     private fun onConnect(client: CoderRestClient, cli: CoderCLIManager) {
         // Store the URL and token for use next time.
+        close()
         context.settingsStore.updateLastUsedUrl(client.url)
         if (context.settingsStore.requiresTokenAuth) {
             context.secrets.storeTokenFor(client.url, client.token ?: "")
@@ -428,10 +529,7 @@ class CoderRemoteProvider(
             context.logger.info("Deployment URL was stored and will be available for automatic connection")
         }
         this.client = client
-        pollJob?.let {
-            it.cancel()
-            context.logger.info("Cancelled workspace poll job ${pollJob.toString()} in order to start a new one")
-        }
+        this.cli = cli
         environments.showLoadingMessage()
         if (context.settingsStore.useAppNameAsTitle) {
             coderHeaderPage.setTitle(context.i18n.pnotr(client.appName))