Activate or create a connection via URL parameters

[kmcginnes]

Problem Statement

Applications that use graph databases have no way to launch Graph Explorer pre-connected to their database. Users must manually open Graph Explorer, create a connection, and configure it — friction that discourages cross-app integration.

Solution

Graph Explorer accepts a dedicated #/connect route whose query parameters specify a database connection. On entry it either activates a matching existing Connection or prompts the user to create a new one, then redirects to the graph view ready to explore.

Example link from an external app:

https://my-ge-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

Note: The parameters belong to the #/connect route, so they go after the #. Graph Explorer uses hash-based routing, so integrators build the link the same way they would any in-app link. The graphDbUrl value must be URL-encoded (e.g., https://host:8182 becomes https%3A%2F%2Fhost%3A8182). Most languages provide this via encodeURIComponent() (JavaScript), urllib.parse.quote() (Python), URLEncoder.encode() (Java), etc.

User Stories

1. As an external app developer, I want to link users to Graph Explorer with a database connection pre-activated, so that users can explore their graph data without manual configuration.
2. As an external app developer, I want to specify the database URL, query language, AWS region, service type, and display name in the link, so that the connection is configured correctly for my database.
3. As a Graph Explorer user, I want to be prompted before a new connection is created from a link, so that arbitrary links cannot silently modify my saved connections.
4. As a Graph Explorer user, I want to edit the connection name in the creation prompt, so that I can personalize how the connection appears in my list.
5. As a Graph Explorer user, I want my existing graph Session to be preserved when a link targets the connection I am already connected to, so that my exploration work is not lost when nothing actually changes.
6. As a Graph Explorer user, I want the connect URL to leave no trace in my history, so that refreshing the page or pressing back behaves normally.
7. As a Graph Explorer user, I want only graphDbUrl to be required in the link, so that simple integrations need minimal configuration (query language defaults to Gremlin, IAM auth assumed off when region is absent).
8. As a Graph Explorer user, I want duplicate connections to not be created when I click the same external link multiple times, so that my connection list stays clean.
9. As a Graph Explorer user, I want the link processed after default connections load, so that a link matching a default connection does not prompt me to create a duplicate.
10. As an external app developer, I want the matching logic to find my connection even if the user has renamed it in Graph Explorer, so that name changes don't break integration links.
11. As a Graph Explorer user with multiple connections to the same database, I want the name parameter to disambiguate which connection activates, so that the correct one is chosen.
12. As a Graph Explorer user, I want a link requesting IAM auth to never silently reuse a plaintext connection to the same endpoint (or the reverse), so that I always know how a connection authenticates.
13. As a Graph Explorer user, I want a link carrying values Graph Explorer cannot honor to be rejected outright rather than corrected for me, so that a link never quietly connects me with settings it did not ask for.
14. As a Graph Explorer user, I want to be told which part of a bad link was wrong, so that I can correct it or report it to whoever sent it.

Implementation Decisions

• URL parameter location: Query parameters on a dedicated #/connect route, so they sit after the # like every other route. This keeps the parameters inside the router (no window.location reads, no manual param stripping) and makes the link format the same shape integrators already use for in-app links. This replaces an earlier decision to put the parameters before the #; see the ADR for the reasoning and the trade it makes.
• Accepted parameters: graphDbUrl (required, must be URL-encoded, must be http/https, must not carry a username or password), queryEngine (optional, default "gremlin"), awsRegion (optional), serviceType (optional), name (optional). Providing awsRegion enables IAM auth; without it IAM auth is off.
• Invalid values are rejected, not coerced: An unsupported queryEngine or serviceType invalidates the link rather than falling back to a default. Answering queryEngine=sql with Gremlin would build a connection that queries the database in a language the caller never asked for. A rejected link is ignored and the user is shown which parameter was at fault and what it requires.
• Credentials in the URL are rejected: fetch itself refuses a URL carrying userinfo (the Request constructor throws), so such a link could only ever produce a connection that fails every query, after persisting the password to IndexedDB and into any exported connection file. Graph Explorer authenticates with IAM, never userinfo.
• Processing location: The #/connect route resolves the link once on entry and acts on the result. It still runs after default connections have loaded, because AppStatusLoader gates the route behind a loading state while the connection store is empty. Order: preload IndexedDB → fetch default connections → resolve the link → redirect.
• Matching logic: Filter connections by graphDbUrl (case-insensitive) + queryEngine + auth posture. Auth posture is identity-bearing: whether IAM is on, and when on, the region and service type. If multiple match, prefer the already-active connection, then tiebreak by name, then fall back to first found. If zero match, prompt for creation.
• Activation behavior: A link matching a different connection switches to it silently, with no prompt. This is the same operation as clicking that connection in the connections list, which has never asked for confirmation, and the link only ever activates a connection the user already created. There is also no session data at risk: Sessions are stored per connection, so switching swaps which Session is displayed rather than destroying the previous one. A link cannot change an already-open window's state either, since following one opens a new tab or the user pastes it deliberately.
• Creation requires user consent: When no match is found, the create-connection form opens pre-filled and fully editable. Saving creates the connection and activates it; closing or cancelling creates nothing. Either way the user ends on the graph view. This is the trust gate for the untrusted endpoint details a link can carry, and the only path that can introduce a new database.
• Connection naming: Use the name parameter when given, otherwise derive one from the graphDbUrl hostname. The derived name is part of the link's identity, not just a display fallback: a nameless link identifies the connection it would have created, so reopening it returns to that connection even after the user adds a second connection to the same endpoint under a name of their own. The name is editable in the create form.
• No parameter stripping: The route redirects with replace, so the #/connect entry never enters history. This replaces the earlier window.history.replaceState approach.
• Landing page: Every outcome redirects to the graph view. Naming the landing page is deferred to Let a connection link choose which page the user lands on #2164, along with the cancel-returns-you-where-you-were behavior that depended on it.
• Scope: New tab/window navigation only. No iframe/postMessage support.
• Subsequent navigations: Opening another link with different parameters is a hash change, which the router handles as a normal navigation rather than a full page reload.

Modules

1. Connection link reader — Pure function that reads a route's search string and returns one of three outcomes: no link present, an invalid link carrying a problem per offending parameter, or a valid link with typed parameters. Handles URL decoding, required vs optional fields, and defaults.
2. Connection matcher — Pure function over the parsed parameters, the existing connections, and the active connection id, returning the matched connection or null. Encapsulates the full priority logic (filter by graphDbUrl + queryEngine + auth posture → prefer active → tiebreak by name → first found).
3. Intent resolver — Pure function that folds a link plus the current connections into one of four intents: do nothing (no link, or it targets the active connection), activate a matching connection, create a new one seeded from the link, or reject an invalid link. Callers dispatch on the intent rather than juggling match and pending flags.
4. Connect route — Resolves the link once on entry via the resolver, then acts: activates silently, notifies and ignores an invalid link, or renders the create form. Every outcome except the create form redirects immediately.
5. Create form prefill — The existing create-connection form gains the ability to open pre-filled with fully editable values, without entering its "edit an existing connection" mode.

Testing Decisions

Good tests for this feature verify external behavior (given this link and this connection state, what connection is activated, what is shown) rather than implementation details (which atoms were set, which internal functions were called).

Modules to test

1. Connection link reader — Valid parameter combinations, missing required parameters, defaults applied, URL decoding, and each rejection rule with the problem it reports. Prior art: defaultConnection.test.ts (schema validation pattern with DefaultConnectionDataSchema).
2. Connection matcher — Single match, multiple-match disambiguation (active preferred, then name tiebreak, then first), auth posture mismatch falling through to no match, zero matches returning null, case-insensitive URL comparison. Prior art: exportedGraph.test.ts (isMatchingConnection tests).
3. Intent resolver — Each of the four intents, including a link matching the active connection resolving to a no-op and an auth-posture mismatch resolving to create.
4. Connect route — Integration tests for each intent: silent activation with redirect, create form pre-filled, no-op redirect, and an invalid link that notifies and redirects without prompting. Also the ordering case: a link matching a default connection that is still loading must not prompt to create a duplicate.
5. Create form prefill — Renders with the given values, stays in "add" mode, and creates the connection on submit.

Out of Scope

• Naming the landing page, and returning the user to where they were on cancel (moved to Let a connection link choose which page the user lands on #2164)
• Iframe embedding or postMessage-based communication with parent applications
• Proxy server configuration parameters (removed per PR Unify Docker image by removing SageMaker variant #1773)
• Sharing or encoding graph Session state (vertices/edges) in URL parameters
• Authentication token passing via URL, including credentials in graphDbUrl (security risk)
• Bidirectional communication (GE notifying the external app of user actions)
• Multi-connection activation (only one connection at a time)
• fetchTimeoutMs or nodeExpansionLimit as URL parameters (too implementation-specific for external callers)

Further Notes

• This feature depends on PR Unify Docker image by removing SageMaker variant #1773 landing first, which simplifies the Connection model to use graphDbUrl as the single required field.
• The isMatchingConnection function in exportedGraph.ts is prior art for matching logic, but the new matcher module should be independent since post-Unify Docker image by removing SageMaker variant #1773 the connection model changes.
• Link-driven activation reuses today's manual connection-switching behavior. There is no special "activate without reset" path: the in-memory graph is cleared on switch exactly as it is when switching by hand, and the previous connection's Session remains persisted under its own key.
• External apps must URL-encode parameter values. The graphDbUrl in particular contains characters (:, /) that are invalid in query string values without encoding.
• Design decisions and the reasoning behind them live in docs/adr/20260612-connection-links.md.

Related Issues

• Implemented by Add connection links via a dedicated #/connect route #1828
• Replaces Feat: Activate or create connection via URL parameters #1811
• Landing page deferred to Let a connection link choose which page the user lands on #2164

[andy-k-improving]

1. What defines a "connection" for matching purposes? Is it the tuple of (graphDbUrl, queryEngine), or does it also include name/ID? The matching logic in the spec filters by graphDbUrl + queryEngine, but the disambiguation step uses name — so what is the actual unique identifier of a connection internally?

2. Story 11 implies matching survives a rename. Does this mean Graph Explorer tracks a stable internal ID (separate from the display name) that the URL matching resolves against? If so, what is that ID — is it auto-generated, or derived from the connection parameters?

3. Story 12 uses name as a tiebreaker when multiple connections share the same graphDbUrl + queryEngine. Does this mean name must be unique across connections to the same database? If a user renames connection A to match connection B's name, does that create an ambiguity the matcher can't resolve?

[kmcginnes]

Connections are matched by value:

DB URL + query language + IAM parameters

There's an internal UUID per connection, but it's per-user and not exposed in URLs. We could include it, but then a missing connection ID would trigger connection creation even when a matching connection already exists (e.g. added as a default, imported from JSON).

Since matching is value-based, renames don't break anything — name is only used as a disambiguation hint when multiple connections share the same value tuple. If multiple still match, we pick the first (or we could prompt the user to choose).

[andy-k-improving]

Connections are matched by value:

DB URL + query language + IAM parameters

There's an internal UUID per connection, but it's per-user and not exposed in URLs. We could include it, but then a missing connection ID would trigger connection creation even when a matching connection already exists (e.g. added as a default, imported from JSON).

Since matching is value-based, renames don't break anything — name is only used as a disambiguation hint when multiple connections share the same value tuple. If multiple still match, we pick the first (or we could prompt the user to choose).

So connection name will never be considered when matching connection logic, right?

[kmcginnes]

The pseudocode for this would be:

const matchingConnections = connections
  .filter(matchesByValue(targetConnection));
if (matchingConnections.length === 1)
  return matchingConnections[0];
else if (matchingConnections.length > 1)
  return matchingConnections
    .filter(matchesByName(targetConnectionName)[0] ?? matchingConnections[0];
else
  return null;

[kmcginnes]

@andy-k-improving I marked this blocked by #1772 because if we don't do that change first, then the connection parameters need to include the proxy server URL as well. This is a bit counterintuitive because the proxy URL is likely the same as the request base URL with a minor tweak.