Add connection links via a dedicated #/connect route

[kmcginnes]

Description

Other apps can now send a user into Graph Explorer already pointed at their database with a link like this:

https://<graph-explorer-host>/#/connect?graphDbUrl=https%3A%2F%2Fmy-cluster.us-east-1.neptune.amazonaws.com%3A8182&queryEngine=gremlin&awsRegion=us-east-1&serviceType=neptune-db&name=My%20Database

• A #/connect route handles the link. The params sit after the # like every other route, so integrators build it the same way as any in-app link. The route always redirects with replace, so #/connect never lingers in history.
• The link resolves once into one of four intents.
  • none: it matches the active connection, so nothing changes.
  • activate: it matches another connection, so Graph Explorer switches to it silently, the same as clicking it in the connections list.
  • create: nothing matches, so a prefilled form opens and the user has to save it.
  • invalid: a param failed validation, so a toast names each bad param and the link is ignored.
• The create form is the trust gate. It's the only path that can add a database, so it's fully editable and nothing is saved until the user clicks Add Connection. It renders in the page rather than over a blank one, and outside clicks don't dismiss it. Saving lands on the graph view. Cancel or Escape lands on the connections list.
• Matching treats auth posture as identity. A connection matches when graphDbUrl (normalized, case-insensitive), queryEngine, and IAM on/off plus region and service type all agree. A link asking for IAM never reuses a plaintext connection to the same endpoint. When several match, the active one wins, then the one named by name, then the first. A nameless link uses the hostname as its name.
• Bad values are rejected, not coerced. Silently swapping in a default would connect with settings the link never asked for. A link is invalid when:
  • graphDbUrl is missing, isn't http(s), carries a username or password, or contains a backslash (which parses as a slash, so a link could show one host and connect to another)
  • queryEngine or serviceType is unsupported
  • awsRegion isn't shaped like a region
  • queryEngine is anything but openCypher for Neptune Analytics, which defaults to openCypher since that's all it runs
• Resolution waits for default connections. AppStatusLoader gates the route until they load, so a link matching a default connection activates it instead of prompting for a duplicate. A test pins that ordering.
• Connections from a link always go through the proxy. The proxy URL comes from document.baseURI, so path-hosted deployments such as Neptune notebooks work.

Shared pieces this needed:

• DialogSurface is pulled out of DialogContent so the connect route can render the same panel without the portal.
• CreateConnection.onClose now receives "saved" or "cancelled", so the route can pick the landing page.
• ConnectionLinkError gives createDisplayError one problem per offending param.

The ADR is docs/adr/20260612-connection-links.md, and the user docs are under Connection Links in docs/features/connections.md.

Follow-ups tracked separately:

• Consolidate domain error types behind a shared base class
• Let a connection link choose which page the user lands on
• Resolve command routes with route-level loading instead of mount effects

Validation

I tried every flow in the browser against a local Gremlin Server with air routes:

• create, then save and query
• cancel and Escape
• silently switching back on reopen
• an IAM link falling through to the create form
• each kind of invalid link
• an empty name falling back to the hostname

history.back() skips #/connect.

To try it, open #/connect?graphDbUrl=http%3A%2F%2Flocalhost%3A8182&queryEngine=gremlin&name=Air%20Routes against a local database, then open the same link again after switching connections.

Related Issues

Closes Activate or create a connection via URL parameters.

This should merge after Unify Docker image by removing SageMaker variant. That PR removes the connection's proxy url and proxyConnection. After it lands I'll rebase and delete deriveProxyBaseUrl, and matching on graphDbUrl then always compares the endpoint that is actually queried.

Check List

• I confirm that my contribution is made under the terms of the Apache 2.0 license.
• I have verified pnpm checks passes with no errors.
• I have verified pnpm test passes with no failures.
• I have covered new added functionality with unit tests if necessary.
• I have updated documentation if necessary.

[mjuarros]

Implementation question

When the link does not include a name, this code generates one from the hostname. That generated name is later also used to choose between multiple matching connections.

Could we keep the URL-provided name optional for matching, and only derive a name when the user needs to create a new connection? This would ensure a generated display name does not accidentally influence which existing connection is selected.

A test with two connections pointing to the same database, no name in the link, and one connection named after the hostname would help confirm the expected behavior.

[kmcginnes]

Deliberate, though the rationale wasn't written down anywhere — fixed now.

The derived name is the link's identity, not just a display fallback: a nameless link identifies the connection it would have created, and what it would have created is named after the hostname. So if you open a nameless link (creating a connection named my-cluster.example.com), then later add a second connection to the same endpoint under a name of your own, reopening that original link returns to the original connection rather than picking arbitrarily.

Dropping the name from matching would fall through to matches[0], i.e. Map insertion order — which happens to give the right answer in that scenario only by accident.

I added the test you suggested (a nameless link prefers the connection its own derived name created), with the hand-named connection placed first in the map so a first-match fallthrough fails it, and recorded the reasoning on deriveNameFromUrl.

[mjuarros]

Spec/design decision, not an implementation defect

This dedicated #/connect?... route differs from #1788, which currently documents top-level search parameters while preserving the hash as the requested landing page. The route-based contract is coherent, but it changes the external URL API.

Can we confirm this intentionally supersedes the issue contract and update #1788 so integrators have one authoritative link format?

[kmcginnes]

Agreed it diverged from the spec. I kept the dedicated route and updated Activate or create a connection via URL parameters to match. Putting the params after the # means integrators build the link like any other in-app route, and nothing in the app shell has to read window.location.search or strip params.

[mjuarros]

Spec/design decision, not an implementation defect

Every outcome is hard-coded to /graph-explorer. In #1788, the caller can choose the landing page, and cancelling should strip the parameters while leaving the user on the requested/current page. With the dedicated route, that destination is no longer represented.

Is always landing on the graph canvas the intended replacement behavior? If so, the affected user stories should be updated explicitly. Otherwise, the connect route needs a validated return destination.

[kmcginnes]

Choosing the landing page is split out into Let a connection link choose which page the user lands on. For now, saving and invalid links land on the graph view and cancelling lands on the connections list, so a declined link leaves you where you can pick a connection yourself.

[mjuarros]

Spec/design decision, not an implementation defect

This silently switches to an existing matching connection. That aligns with the PR rationale and normal connection-list behavior, but #1788 also says switching to a different connection should be confirmed before its Session is reset.

Can we confirm silent activation is the final product decision and update the issue accordingly? The current implementation looks internally consistent once that contract is settled.

[kmcginnes]

Confirmed as the final product decision. Two reasons, both now recorded in the ADR:

First, there is no session to lose. Sessions are stored per connection (allGraphSessionsAtom, keyed by connection id) and useResetState only clears the in-memory view atoms — it never touches allGraphSessionsAtom. So switching swaps which session is displayed rather than destroying the previous one: return to that connection and it restores.

Second, a link cannot change an already-open window's state. Following one opens a new tab, or the user pastes it deliberately. Either way the intent to start somewhere new is explicit.

Together that makes this identical to clicking a connection in the connections list, which has never prompted. The create path keeps its friction, since it is the only one that can introduce a new database.

Worth noting the issue contradicts itself here, which is probably what prompted the question: #1788's Modules section item 3 says "prompts to switch (resetting the Session on confirm)", while that same issue's Implementation Decisions say activation is "identical to a manual connection switch". The implementation follows the latter, and I'm correcting the issue text.

[mjuarros]

Could we default queryEngine and serviceType only when they are absent, and reject explicitly invalid values? With .catch(), queryEngine=sql silently becomes Gremlin, while an invalid serviceType can later become neptune-db when a region is present. The resulting connection may differ from what the caller requested instead of following the existing invalid-link path.

Using optional schemas with defaults for missing values would preserve the convenience while allowing malformed explicit values to produce the invalid intent. The current coercion tests should then become rejection tests.

[kmcginnes]

Done. .catch() is gone. An absent queryEngine still defaults, but an explicit unsupported value for either param now rejects the link, and the toast names the param.

[mjuarros]

Dialog composition

CreateConnection already renders its own DialogBody and DialogFooter, so this outer DialogBody nests two body containers and places the footer inside the outer scrolling region. That can duplicate spacing and make the actions scroll with the form instead of remaining in the dialog footer position.

Could we render CreateConnection directly after the header, or extract form content so one component clearly owns the body and footer?

[kmcginnes]

Fixed. CreateConnection owns its body and footer. The connect route also renders the form in the page with DialogSurface now, instead of a modal over a blank page.

[mjuarros]

Security hardening

This accepts HTTP(S) URLs containing embedded credentials, such as https://user:password@host. Because the value comes from an external link and can be persisted as the database endpoint after confirmation, credentials could end up stored and forwarded as part of the URL.

Could the schema reject URLs whose parsed username or password is non-empty? That also avoids userinfo being used to make an unintended host look trustworthy at a glance.

[kmcginnes]

Fixed. A graphDbUrl with a username or password is rejected. I also reject backslashes, since https://evil.tld\@prod.neptune.amazonaws.com parses to evil.tld while the form shows a Neptune host.

[mjuarros]

Security documentation

This guarantee is broader than the current behavior. The allowlist permits any origin when PROXY_SERVER_ALLOWED_DB_ORIGINS is unset, and matching does not require an existing connection to be proxy-backed. A matching direct connection can therefore activate without proxy allowlist enforcement.

Could we either enforce proxy-backed matching for connection links, or qualify this note to say the allowlist applies only when configured and only to requests routed through the proxy?

[kmcginnes]

Agreed, that overstated it. I dropped the note from security.md, and the ADR now says the allowlist only bounds a link when PROXY_SERVER_ALLOWED_DB_ORIGINS is set.

[mjuarros]

Documentation accuracy

The notification currently reports a generic invalid-link message rather than explaining which value or rule failed. The creation flow also has two outcomes worth stating explicitly: saving creates the connection, while closing or cancelling creates nothing; both then navigate to the graph view.

Could we describe the error as generic and document those two dialog outcomes, or enhance the UI if specific validation feedback is intended?

[kmcginnes]

Fixed both. The toast now names each bad param and what it requires, for example "graphDbUrl must be a valid http or https URL", and the docs cover the save and cancel outcomes separately.

[mjuarros]

Architecture documentation

The implementation does not snapshot the intent once on entry. useUrlConnectionIntent() reads live Jotai state and resolves again on each render, including while the creation dialog is open.

Could we describe this as reactive resolution, or snapshot the initial intent if one-shot processing is an architectural invariant? CONTEXT.md uses the same “resolved once” wording and should stay aligned.

[kmcginnes]

Fixed in the code, not just the doc. The route now resolves the link once in a useState initializer and acts on that. The AppStatusLoader gate makes that safe, and a test pins the ordering.

[mjuarros]

Manual testing found that the invalid-link warning is not visible.

Reproduction:

1. Open /#/connect?graphDbUrl=not-a-url.
2. The app redirects to the graph explorer and does not open the create form, as expected.
3. No Invalid connection link toast is displayed.

The PR contract specifies invalid as “warn with a toast and ignore,” and Connect.tsx calls toast.error(...), so the redirect behavior is correct but the user-facing warning appears to be missing. The current route test verifies the mocked toast.error call, but does not mount the real Toaster or assert that the notification is rendered and remains visible after navigation.

[kmcginnes]

Thanks for catching this. sonner dropped toasts raised before the Toaster subscribed, and the connect route raises its toast on mount. sonner 2.0.8, which came in with Bump the minor-and-patch group, replays those early toasts, so it shows now. I checked /#/connect?graphDbUrl=not-a-url in the browser: the toast reads "graphDbUrl must be a valid http or https URL. The link was ignored, so nothing changed." and then it redirects.